32 Modifying the Default REST Implementation

You can change the default behavior of the Coherence REST implementation.

This chapter includes the following sections:

• Using the Pass-Through Resource
  Coherence REST includes a resource implementation that enables pass-through access to caches.
• Using Custom Providers and Resources
  Custom providers and resources can be created as required.
• Changing the Embedded HTTP Server
  Coherence REST uses Oracle's lightweight HTTP server by default to handle requests. However, the implementation is not recommended for production environments and is typically used during development and testing.

Using the Pass-Through Resource

Coherence REST includes a resource implementation that enables pass-through access to caches. The resource allows static binaries such as graphics to be cached. The resource is implemented in the PassThroughRootResource class and is registered using the PassThroughResourceConfig class.

To use the pass-through resource in an application, modify the proxy service definition in the cache configuration file and add the fully qualified name of the PassThroughResourceConfig class within the <resource-config> element. The resource is mapped to a specific context path or the default path (/) if no context is defined. The following example registers the resource and uses /cache as the context path. Any cache resources that are defined in the coherence-rest-config.xml configuration file are prefixed with /cache/ in the URL.

<proxy-scheme>
   <service-name>HttpProxyService</service-name>
   <acceptor-config>
      <http-acceptor>
         ...
         <resource-config>
            <context-path>/cache</context-path>
            <instance>
               <class-name>com.tangosol.coherence.rest.server.PassThroughResourceConfig</class-name>
            </instance>
         </resource-config>
      </http-acceptor>
   </acceptor-config>
   <autostart>true</autostart>
</proxy-scheme>

Likewise, the ContainerPassThroughResourceConfig class, which is an extension of the PassThroughResourceConfig class, is used for container deployments of Coherence REST when pass-through is required. The resource is configured in the Web application deployment descriptor included in the Coherence REST application.

<web-app>
   ...
   <listener>
      <listener-class>
         com.tangosol.coherence.rest.servlet.DefaultServletContextListener
      </listener-class>
   </listener>
   <servlet>
      <servlet-name>Coherence REST</servlet-name>
      <servlet-class>org.glassfish.jersey.servlet.ServletContainer
      </servlet-class>
      <init-param>
         <param-name>javax.ws.rs.Application</param-name>
         <param-value>
            com.tangosol.coherence.rest.server.ContainerPassThroughResourceConfig
         </param-value>
      </init-param>
      <load-on-startup>1</load-on-startup>
   </servlet>
   <servlet-mapping>
      <servlet-name>Coherence REST</servlet-name>
      <url-pattern>/rest/*</url-pattern>
    </servlet-mapping>
      ...
</web-app>

Using Custom Providers and Resources

Custom providers and resources can be created as required. This section demonstrates how to register custom providers, and how to override Coherence's default root resource.

The com.tangosol.coherence.rest.server.DefaultResourceConfig class supports package scanning, which can be used to register custom providers or resources. The following example demonstrates registering a custom provider and resource using package scanning:

public class MyResourceConfig  extends DefaultResourceConfig
   {
   public MyResourceConfig()
      {
      super("com.my.providers;com.my.resources");
      }
   }

As an alternative, the following example demonstrates how to override one or more of the register methods defined in the DefaultResourceConfig class in order to use custom providers, a custom root resource, or to add filters and filter factories.

Note:

Never override (unregister) Coherence default Providers without overriding the root resource class as well (the DefaultRootResource class depends on the default providers to provide the necessary dependencies and configuration).

public class MyResourceConfig  extends DefaultResourceConfig
    {
    protected void registerRootResource()
        {
        // remove if you don't want Coherence defaults to be registered
        super.registerRootResource(); 
        getClasses().add(MyRootResource.class);
        }
 
    protected void registerProviders()
        {
        // remove if you don't want Coherence defaults to be registered
        super.registerProviders();
        getSingletons().add(new MyProvider());
        }
 
    protected void registerContainerRequestFilters()
        {
        // remove if you don't want Coherencedefaults to be registered
        super.registerContainerRequestFilters();
        getContainerRequestFilters().add(new MyRequestFilter());
        }
 
    protected void registerContainerResponseFilters()
        {
        // remove if you don't want Coherence defaults to be registered
        super.registerContainerResponseFilters();
        getContainerResponseFilters().add(new MyResponseFilter());
        }
 
    protected void registerResourceFilterFactories()
        {
        // remove if you don't want Coherence defaults to be registered
        super.registerResourceFilterFactories();
        getResourceFilterFactories().add(new MyResourceFilterFactory());
        }
    }

Custom resource configuration classes are enabled in the cache configuration file by adding the fully qualified name of the class using the <resource-config> element within an HTTP acceptor configuration. The class is mapped to a specific context path or the default context path (/) if no context path is defined. Multiple resource configuration class definitions can be added and mapped to different context paths. The following example registers a custom resource called MyResourceConfig and maps it to the /MyApplication context path.

<proxy-scheme>
   <service-name>ExtendHttpProxyService</service-name>
   <acceptor-config>
      <http-acceptor>
         ...
            <resource-config>
               <context-path>/MyApplication</context-path>
               <instance>
                    <class-name>package.MyResourceConfig</class-name>
               </instance>
            </resource-config>
      </http-acceptor>
   </acceptor-config>
   <autostart>true</autostart>
</proxy-scheme>

Changing the Embedded HTTP Server

Coherence REST uses Oracle's lightweight HTTP server by default to handle requests. However, the implementation is not recommended for production environments and is typically used during development and testing.

For production environments, Coherence includes an implementation for the Netty HTTP server.

The Netty HTTP server is supported in Jersey. Refer to the Jersey documentation for instructions on integrating additional HTTP servers, which are beyond the scope of this documentation.

http://jersey.java.net/

This section includes the following topics:

• Using Netty HTTP Server
  

Using Netty HTTP Server

Coherence REST provides a Netty HTTP server implementation (com.tangosol.coherence.http.netty.NettyHttpServer) that can be used instead of the default HTTP server. For more information on the Netty HTTP server, see:

https://netty.io/

The Netty server is enabled in the cache configuration file by adding the fully qualified name of the implementation as a value of the <class-name> element within an HTTP acceptor configuration. For example:

<proxy-scheme>
   <service-name>ExtendHttpProxyService</service-name>
   <acceptor-config>
      <http-acceptor>
         <class-name>com.tangosol.coherence.http.netty.NettyHttpServer</class-name>
         ...
      </http-acceptor>
   </acceptor-config>
   <autostart>true</autostart>
</proxy-scheme>