14.4.4. Configuring Netty Servlet

Netty Servlet transport allows HornetQ traffic to be tunneled over HTTP to a servlet running in a servlet engine, which redirects it to an in-virtual machine HornetQ server.
This differs from the Netty HTTP transport in that traffic is routed through a servlet engine which may already be serving web applications. This allows HornetQ to be used where corporate policies allow only a single web server to listen on an HTTP port.

Configuring a servlet engine for the Netty Servlet transport

  1. Deploy the servlet. A web application using the servlet might have a web.xml file similar to the following: 
    <?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
  version="2.4">
  <servlet>
    <servlet-name>HornetQServlet</servlet-name>
    <servlet-class>org.jboss.netty.channel.socket.http.HttpTunnelingServlet</servlet-class>
    <init-param>
      <param-name>endpoint</param-name>
      <param-value>local:org.hornetq</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>

  <servlet-mapping>
    <servlet-name>HornetQServlet</servlet-name>
    <url-pattern>/HornetQServlet</url-pattern>
  </servlet-mapping>
</web-app>
  2. Add the netty-invm acceptor to the server-side configuration in <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hornetq/hornetq-configuration.xml: 
    <acceptors>
  <acceptor name="netty-invm">
    <factory-class>
      org.hornetq.core.remoting.impl.netty.NettyAcceptorFactory
    </factory-class>
    <param key="use-invm" value="true"/>
    <param key="host" value="org.hornetq"/>
  </acceptor>
</acceptors>
  3. Define a connector for the client in <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hornetq/hornetq-configuration.xml: 
    <connectors>
  <connector name="netty-servlet">
    <factory-class>
      org.hornetq.core.remoting.impl.netty.NettyConnectorFactory
    </factory-class>
    <param key="host" value="localhost"/>
    <param key="port" value="8080"/>
    <param key="use-servlet" value="true"/>
    <param key="servlet-path" value="/messaging/HornetQServlet"/>
  </connector>
</connectors>

Init Parameters

endpoint
Defines the netty acceptor to which the servlet forwards its packets. Matches the name of the host parameter.
The servlet pattern configured in the web.xml is the path of the URL that is used. The connector parameter servlet-path on the connector configuration must match this using the application context of the web application if there is one.
The servlet transport can also be used over SSL by adding the following configuration to the connector: 
<connector name="netty-servlet">
  <factory-class>
    org.hornetq.core.remoting.impl.netty.NettyConnectorFactory
  </factory-class>
  <param key="host" value="localhost"/>
  <param key="port" value="8443"/>
  <param key="use-servlet" value="true"/>
  <param key="servlet-path" value="/messaging/HornetQServlet"/>
  <param key="ssl-enabled" value="true"/>
  <param key="key-store-path" value="path to a keystore"/>
  <param key="key-store-password" value="keystore password"/>
</connector>
You will also have to configure the application server to use a Key Store. Edit the SSL/TLS connector configuration in server/default/deploy/jbossweb.sar/server.xml like so: 
<Connector protocol="HTTP/1.1" SSLEnabled="true"
  port="8443" address="${jboss.bind.address}"
  scheme="https" secure="true" clientAuth="false"
  keystoreFile="path to a keystore"
  keystorePass="keystore password" sslProtocol = "TLS" />
In both cases you will need to provide a key store and password. See the Servlet SSL example shipped with HornetQ for more detail.