The plugin has been tested in the following environment, using the grails-atmosphere-meteor-sample application and grails-plugin-test-script:
-
atmosphere-runtime 2.3.2
-
OSX 10.10
-
JDK 1.7.0_75
-
Grails versions 2.1.5, 2.2.4, 2.3.9, 2.4.5, and 2.5.0
-
Tomcat 7.0.27 through 7.0.54 (version depends on Grails version)
-
Tomcat 8.0.22
-
Jetty plugin version 3.0.0, available in Grails 2.3.7 or greater
If you have a question, problem, suggestion, or want to report a bug, please submit an issue. I will reply as soon as I can.
The plugin uses the following components of the Atmosphere Framework:
The plugin is designed to create and use a servlet for each main or significant URL pattern. For example, if you download the sample application, you will see that a servlet is created for each URL pattern below:
/atmosphere/chat/*
/atmosphere/notification/*
/atmosphere/public/*
All servlets are defined in grails-app/conf/AtmosphereMeteorConfig.groovy. A default file that you must edit will be copied to your app when the plugin is first installed.
The create-meteor-servlet script creates a class in grails-app/atmosphere that extends Atmosphere's MeteorServlet. You can probably use a single class throughout your application.
The create-meteor-handler script creates a class in grails-app/atmosphere that extends HttpServlet. This is where you customize how the HTTP requests and responses are handled by overriding the doGet() and doPost() methods.
Each URL pattern can be differentiated using a combination of request headers, path, etc. For example, a chat room could be established under /atmosphere/chat/private-room-12345 that is serviced by the same MeteorServlet and MeteorHandler classes as /atmosphere/chat/*.
Edit your BuildConfig.groovy:
plugins {
// other plugins
compile ":atmosphere-meteor:1.0.5"
// other plugins
}
The plugin works with the Jetty plugin version 3.0.0 (Jetty 9) or greater, which can be used with Grails versions 2.3.7 and greater. See the Jetty Page for workarounds with Jetty 8.
Your BuildConfig.groovy must be configured to use the Servlet 3.0 API and the Tomcat NIO connector.
grails.servlet.version = "3.0"
grails.tomcat.nio = true
You do not need to modify your BuildConfig.groovy if using Tomcat 8. It will default to the NIO connector and Servlet API 3.1. Use the tomcat plugin and not the tomcat8 one. For example, in your BuildConfig.groovy:
plugins {
build ":tomcat:8.0.15"
// other plugins
Create a MeteorServlet. Changes to these classes are reloaded automatically.
grails create-meteor-servlet com.example.Default
Create a handler. Changes to these classes are reloaded automatically.
grails create-meteor-handler com.example.Default
Edit grails-app/conf/AtmosphereMeteorConfig.groovy. Changes to this file will be implemented when the application is restarted.
import com.example.DefaultMeteorHandler
defaultMapping = "/atmosphere/*"
servlets = [
MeteorServletDefault: [
className: "com.example.DefaultMeteorServlet",
mapping: "/atmosphere/*",
handler: DefaultMeteorHandler,
initParams: [
// Uncomment the line below use native WebSocket support with native Comet support.
//"org.atmosphere.useWebSocketAndServlet3": "false",
"org.atmosphere.cpr.broadcasterCacheClass": "org.atmosphere.cache.UUIDBroadcasterCache",
"org.atmosphere.cpr.AtmosphereInterceptor": """
org.atmosphere.client.TrackMessageSizeInterceptor,
org.atmosphere.interceptor.AtmosphereResourceLifecycleInterceptor,
org.atmosphere.interceptor.HeartbeatInterceptor
"""
]
]
]
You can access the AtmosphereFramework and default BroadcasterFactory instances by injecting the atmosphereMeteor bean anywhere in your application using either the standard DI procedure
def atmosphereMeteor
or for example in a class in grails-app/atmosphere
def atmosphereMeteor = grails.util.Holders.applicationContext.getBean("atmosphereMeteor")
and then accessing its properties
def atmosphereFramework = atmosphereMeteor.framework
def broadcasterFactory = atmosphereMeteor.broadcasterFactory
I have already deprecated the AtmosphereConfigurationHolder.framework property that I made available in version 0.9.2. It is no longer necessary due to the atmosphereMeteor bean.
If you have added the last line below in your MeteorServlet class, you can safely delete it.
class DefaultMeteorServlet extends MeteorServlet {
@Override
public void init(ServletConfig sc) throws ServletException {
super.init(sc)
AtmosphereConfigurationHolder.framework = framework
The plugin has a service that you can inject into your application artifacts using the line below.
def atmosphereMeteorService
The broadcast() method uses the Atmosphere DefaultBroadcaster and offers two signatures. The one below will create the broadcaster if it does not exist, and the second one allows you to turn off this behavior by using false as the create argument. These are convenience methods that save you from having to grab the BroadcasterFactory instance.
atmosphereMeteorService.broadcast(String mapping, data)
atmosphereMeteorService.broadcast(String mapping, data, Boolean create)
The plugin supports both the asset-pipeline and resources plugins. You can use the following tags depending on whether or not you are using jQuery.
<asset:javascript src="atmosphere-meteor.js"/>
or
<asset:javascript src="atmosphere-meteor-jquery.js"/>
You can also add the dependency in one of your JavaScript manifests:
//= require atmosphere-meteor
or
//= require atmosphere-meteor-jquery
<r:require module="atmosphere-meteor"/>
or
<r:require module="atmosphere-meteor-jquery"/>
You can update the atmosphere-runtime version and the Atmosphere JavaScript library your application uses without having to wait on a plugin update.
Edit your BuildConfig.groovy and add atmosphere-runtime to the grails.project.dependency.resolution.dependencies closure. For example, to use version 2.2.3 your file should look like this.
dependencies {
compile "org.atmosphere:atmosphere-runtime:2.3.3", {
excludes "slf4j-api"
}
// other dependencies
You can update the Atmosphere Javascript files by running the script below. This will allow you to update the client files without having to wait on a plugin release.
grails update-atmosphere-meteor-javascript
You can change the Atmosphere log level by adding a line to your application's grails-app/conf/Config.groovy in the appropriate place. For example, to set the level to warn:
warn "org.atmosphere"
You can change the plugin log level by adding a a line to your application's grails-app/conf/Config.groovy in the appropriate place. For example, to set the level to debug:
debug "org.grails.plugins.atmosphere_meteor"