Using AtmosphereInterceptor to customize Atmosphere Framework Dispatch Mechanism

The AtmosphereInterceptor interface allows application or framework integrator to intercept the AtmosphereResource before it gets dispatched to an AtmosphereHandler. As an example, The ReflectorServletProcessor handler' role is to dispatch AtmosphereResource to Servlet based application or framework. An application/framework can defines one or multiple AtmosphereInterceptor in order to intercept AtmosphereResource and manipulate its associated AtmosphereRequest and AtmosphereResponse. You define them in web.xml or application.xml In web.xml

        <init-param>
            <param-name>org.atmosphere.cpr.AtmosphereInterceptor</param-name>
            <param-value>org.foo.BarAtmosphereInterceptor, org.bar.FooAtmosphereInterceptor</param-value>
        </init-param>

or in atmosphere.xml

        <applicationConfig>
            <param-name>org.atmosphere.cpr.AtmosphereInterceptor</param-name>
            <param-value>org.foo.BarAtmosphereInterceptor, org.bar.FooAtmosphereInterceptor</param-value>
        </applicationConfig>

The AtmosphereInterceptor API looks like

public interface AtmosphereInterceptor {
    Action inspect(AtmosphereResource r);
}

An AtmosphereInterceptor can suspend, resume, timeout, cancel or just continue the AtmosphereResource processing by returning the appropriate Action . As an example, the following AtmosphereInterceptor will cancel the processing based on some security token

            @Override
            public Action inspect(AtmosphereResource r) {
                
                AtmosphereRequest req = r.getRequest();
                if (req.getHeader("SomeSecurityToken") == null) {
                    return Action.CANCELLED;                   
                } else {
                    return Action.CONTINUE;                   
                }
            }

You can also suspend the AtmosphereResource without delivering the request to an application/framework. This is useful when you just want to suspend and not dispatch anything.

            @Override
            public Action inspect(AtmosphereResource r) {
                r.suspend();
                return Action.SUSPEND;
            }

You can also manipulate the AtmosphereResponse. As an example, below is an SSEAtmosphereInterceptor, which add Server Side Events support to Atmosphere

 @Override
    public Action inspect(final AtmosphereResource r) {
        final AtmosphereResponse response = r.getResponse();

        if (r.transport().equals(AtmosphereResource.TRANSPORT.SSE)) {
            response.asyncIOWriter(new AsyncIOWriter() {
                @Override
                public void redirect(String location) throws IOException {
                    response.sendRedirect(location);
                }

                @Override
                public void writeError(int errorCode, String message) throws IOException {
                    response.sendError(errorCode);
                }

                @Override
                public void write(String data) throws IOException {
                    AtmosphereResourceImpl.class.cast(r).writeSSE(false);
                    response.write("data:" + data + "\n\n");
                }

                // TODO: Performance: execute a single write
                @Override
                public void write(byte[] data) throws IOException {
                    AtmosphereResourceImpl.class.cast(r).writeSSE(false);
                    response.write("data:").write(data).write("\n\n");
                }

                @Override
                public void write(byte[] data, int offset, int length) throws IOException {
                    AtmosphereResourceImpl.class.cast(r).writeSSE(false);
                    response.write("data:").write(data, offset, length).write("\n\n");
                }

                @Override
                public void close() throws IOException {
                    response.closeStreamOrWriter();
                }

                @Override
                public void flush() throws IOException {
                    response.flushBuffer();
                }
            });
        }
        return Action.CONTINUE;
    }