Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Grails plugin for integrating the Atmosphere Framework
JavaScript Groovy
branch: master
Failed to load latest commit information.
grails-app update to 1.0.4
scripts cleanup Jetty plus
src update to 1.0.2
web-app update to 1.0.4
.gitignore update to 1.0.4
AtmosphereMeteorGrailsPlugin.groovy fix issue #49
License.txt Added License.txt
README.md update README
application.properties update to 1.0.4

README.md

Grails plugin for integrating the Atmosphere Framework

Atmosphere Wiki

Atmosphere Google Group

The plugin has been tested in the following environment, using the grails-atmosphere-meteor-sample application and grails-plugin-test-script:

  • atmosphere-runtime 2.2.3 although the current plugin uses 2.2.1 by default

  • OSX 10.10

  • JDK 1.7.0_71

  • Grails versions 2.1.5, 2.2.4, 2.3.9, and 2.4.4

  • Tomcat 7.0.27 through 7.0.54 (version depends on Grails version)

  • Tomcat 8.0.15

  • 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.

Release Notes

The plugin uses the following components of the Atmosphere Framework:

How It Works

Java Servlet

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/*

Configuration

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.

MeteorServlet Class

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.

MeteorHandler Class

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/*.

Plugin Installation, Configuration, and Use

Installation

Edit your BuildConfig.groovy:

plugins {
    // other plugins
    compile ":atmosphere-meteor:1.0.4"
    // other plugins
}

Jetty

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.

Tomcat 7

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

Tomcat 8

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

MeteorServlet

Create a MeteorServlet. Changes to these classes are reloaded automatically.

grails create-meteor-servlet com.example.Default

Handler

Create a handler. Changes to these classes are reloaded automatically.

grails create-meteor-handler com.example.Default

Servlet Configuration

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
            """
        ]
    ]
]

AtmosphereMeteor Bean

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

AtmosphereConfigurationHolder.framework Deprecated

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

AtmosphereMeteorService

The plugin has a service that you can inject into your application artifacts using the line below.

def atmosphereMeteorService

broadcast()

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)

Javascript

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-pipeline plugin

<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

resources plugin

<r:require module="atmosphere-meteor"/>

or

<r:require module="atmosphere-meteor-jquery"/>

Update atmosphere-runtime and JavaScript Library

You can update the atmosphere-runtime version and the Atmosphere JavaScript library your application uses without having to wait on a plugin update.

atmosphere-runtime

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.2.3", {
            excludes "slf4j-api"
        }
        // other dependencies

JavaScript

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

Logging

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"

Message Brokers

Hazelcast

See Hazelcast Broadcaster.

Something went wrong with that request. Please try again.