Sun Java System Message Queue 3.7 UR1 Administration Guide

Enabling HTTP Support

The following sections describe the steps you need to take to enable HTTP support.

ProcedureTo Enable HTTP Support

  1. Deploy the HTTP tunnel servlet. You can deploy the HTTP tunnel servlet on the following:

    • Sun Java SystemTM Web Server

      • Sun Java System Application Server

  2. Configure the broker’s httpjms connection service and start the broker.

  3. Configure an HTTP connection.

Step 1. Deploy the HTTP Tunnel Servlet

You can deploy the HTTP tunnel servlet as a Web archive (.war) file on a Sun Java System Web Server or Sun Java System Application Server.

Deploying the HTTP tunnel servlet as a .war file consists of using the deployment mechanism provided by the Web server/application server. The HTTP tunnel servlet .war file (imqhttp.war) is located in the directory containing .jar, .war, and .rar files, and depends on your operating system (see Appendix A, Platform-Specific Locations of Message QueueTM Data).

The .war file includes a deployment descriptor that contains the basic configuration information needed by the Web server/application server to load and run the servlet. Depending on the Web server/application server, you might also need to specify the context root portion of the servlet’s URL.

Deploying as a Web Archive File

For deployment on a Sun Java System Web Server, see Deploying the HTTP Tunnel Servlet on Sun Java System Web Server.

For deployment on a Sun Java System Application Server, see Deploying the HTTP Tunnel Servlet on Sun Java System Application Server.

Deploying the HTTP Tunnel Servlet on Sun Java System Web Server

The instructions below refer to deployment on Sun Java System Web Server. You can verify successful HTTP tunnel servlet deployment by accessing the servlet URL using a Web browser. It should display status information.

ProcedureTo Deploy the HTTP Tunnel Servlet as a .war File

  1. In the browser-based administration GUI, select the Virtual Server Class tab and select Manage Classes.

  2. Select the appropriate virtual server class name (for example, defaultClass) and click the Manage button.

  3. Select Manage Virtual Servers.

  4. Select an appropriate virtual server name and click the Manage button.

  5. Select the Web Applications tab.

  6. Click on Deploy Web Application.

  7. Select the appropriate values for the WAR File On and WAR File Path fields so as to point to the imqhttp.war file, which can be found in a directory that depends on your operating system (see Appendix A, Platform-Specific Locations of Message QueueTM Data).

  8. Enter a path in the Application URI field.

    The Application URI field value is the /contextRoot portion of the tunnel servlet URL:

    http://hostName :portNumber / contextRoot/tunnel

    For example, if you set the contextRoot to imq, the Application URI field would be:

    /imq

  9. Enter the installation directory path (typically somewhere under the Sun Java System Web Server installation root) where the servlet should be deployed.

  10. Click OK.

  11. Restart the Web server instance.

    The servlet is now available at the following address:


    http://hostName:portNumber/
    contextRoot/tunnel

    Clients can now use this URL to connect to the message service using an HTTP connection.

Disabling a Server Access Log

You do not have to disable the server access log, but you will obtain better performance if you do.

ProcedureTo Disable the Server Access Log

  1. Select the Status tab.

  2. Choose the Log Preferences Page.

    Use the Log client accesses control to disable logging.

Deploying the HTTP Tunnel Servlet on Sun Java System Application Server

This section describes how you deploy the HTTP tunnel servlet as a .war file on the Sun Java System Application Server, and then configure the tunnel servlet to accept connections from a Message Queue broker.

Two steps are required:

Using the Deployment Tool

ProcedureTo Deploy the HTTP Tunnel Servlet in an Application Server Environment

  1. In the Web-based administration GUI, choose

    App Server > Instances > server1 > Applications > Web Applications.

  2. Click the Deploy button.

  3. In the File Path: text field, enter the location of the HTTP tunnel servlet .war file (imqhttp.war), and click OK.

    The location of the imqhttp.war file depends on your operating system (see Appendix A, Platform-Specific Locations of Message QueueTM Data).

  4. Set the value for the Context Root text field, and click OK.

    The Context Root field value is the /contextRoot portion of the tunnel servlet URL:

    http://hostName :portNumber / contextRoot/tunnel

    For example, you could set the Context Root field to /imq.

    The confirmation screen that appears confirms that the tunnel servlet has been successfully deployed, is enabled by default, and in this case is located at:


    /var/opt/SUNWappserver8/domains/domain1/server1/applications/
    j2ee-modules/imqhttp_1

    The servlet is now available at the following URL:


    http://hostName:portNumber/
    contextRoot/tunnel

    Clients can now use this URL to connect to the message service using an HTTP connection.

Modifying the server.policy File

The Application Server enforces a set of default security policies that, unless modified, would prevent the HTTP tunnel servlet from accepting connections from the Message Queue broker.

Each application server instance has a file that contains its security policies, or rules. For example, the location of this file for the server1 instance on Solaris is:

/var/opt/SUNWappserver8/domains/domain1/server1/config/
server.policy

To configure the tunnel servlet to accept connections from the Message Queue broker, an additional entry is required in this file.

ProcedureTo Modify the Application Server’s server.policy File

  1. Open the server.policy file.

  2. Add the following entry:


    grant codeBase
    "file:/var/opt/SUNWappserver8/domains/domain1/server1/
                    applications/j2ee-modules/imqhttp_1/-”
    {
            permission java.net.SocketPermission "*",
                    “connect,accept,resolve";
    };

Step 2. Configure the httpjms Connection Service

HTTP support is not activated for a broker by default, so you need to reconfigure the broker to activate the httpjms connection service. Once reconfigured, the broker can be started as outlined in Starting Brokers.

ProcedureTo Activate the httpjms Connection Service

  1. Open the broker’s instance configuration file.

    The instance configuration file is stored in a directory identified by the name of the broker instance (instanceName) with which the configuration file is associated (see Appendix A, Platform-Specific Locations of Message QueueTM Data):

    /instances/ instanceName/props/config.properties

  2. Add the httpjms value to the imq.service.activelist property:


    imq.service.activelist=jms,admin,httpjms

    At startup, the broker looks for a Web server/application server and HTTP tunnel servlet running on its host machine. To access a remote tunnel servlet, however, you can reconfigure the servletHost and servletPort connection service properties.

    You can also reconfigure the pullPeriod property to improve performance. The httpjms connection service configuration properties are detailed in Step 2. Configure the httpjms Connection Service.

    Property 

    Description 

    imq.httpjms.http.servletHost

    Change this value, if necessary, to specify the name of the host (hostname or IP address) on which the HTTP tunnel servlet is running. (This can be a remote host or a specific hostname on a local host.) Default: localhost.

    imq.httpjms.http. servletPort

    Change this value to specify the port number that the broker uses to access the HTTP tunnel servlet. (If the default port is changed on the Web server, you must change this property accordingly.) Default: 7675.

    imq.httpjms.http. pullPeriod

    Specifies the interval, in seconds, between HTTP requests made by a client runtime to pull messages from the broker. (Note that this property is set on the broker and propagates to the client runtime.) If the value is zero or negative, the client keeps one HTTP request pending at all times, ready to pull messages as fast as possible. With a large number of clients, this can be a heavy drain on Web/application server resources and the server may become unresponsive. In such cases, you should set the pullPeriod property to a positive number of seconds. This sets the time the client’s HTTP transport driver waits before making subsequent pull requests. Setting the value to a positive number conserves Web/application server resources at the expense of the response times observed by clients. Default: -1.

    imq.httpjms.http. connectionTimeout

    Specifies the time, in seconds, that the client runtime waits for a response from the HTTP tunnel servlet before throwing an exception. (Note that this property is set on the broker and propagates to the client runtime.) This property also specifies the time the broker waits after communicating with the HTTP tunnel servlet before freeing up a connection. A timeout is necessary in this case because the broker and the tunnel servlet have no way of knowing if a client that is accessing the HTTP servlet has terminated abnormally. Default: 60.

Step 3. Configure an HTTP Connection

A client application must use an appropriately configured connection factory administered object to make an HTTP connection to a broker. This section discusses HTTP connection configuration issues.

Configuring the Connection Factory

To enable HTTP support, you need to set the connection factory’s imqAddressList attribute to the HTTP tunnel servlet URL. The general syntax of the HTTP tunnel servlet URL is the following:

http://hostName:portNumber

/contextRoot/tunnel

where hostName:portNumber is the name and port of the Web server/application server hosting the HTTP tunnel servlet and contextRoot is a path set when deploying the tunnel servlet on the Web server/application server.

For more information on connection factory attributes in general, and the imqAddressList attribute in particular, see the Message Queue Developer's Guide for Java Clients.

You can set connection factory attributes in one of the following ways:

Using a Single Servlet to Access Multiple Brokers

You do not need to configure multiple Web servers/application servers and servlet instances if you are running multiple brokers. You can share a single Web server/application server and HTTP tunnel servlet instance among concurrently running brokers. If multiple broker instances are sharing a single tunnel servlet, you must configure the imqAddressList connection factory attribute as shown below:

http://hostName:portNumber

/contextRoot/tunnel?ServerName=
bkrHostName:instanceName

Where bkrHostName is the broker instance host name and instanceName is the name of the specific broker instance you want your client to access.

To check that you have entered the correct strings for bkrHostName and instanceName, generate a status report for the HTTP tunnel servlet by accessing the servlet URL from a browser. The report lists all brokers being accessed by the servlet:


HTTP tunnel servlet ready.
Servlet Start Time : Thu May 30 01:08:18 PDT 2005
Accepting TCP connections from brokers on port : 7675
Total available brokers = 2
Broker List :
   jpgserv:broker2
   cochin:broker1

Using an HTTP Proxy

If you are using an HTTP proxy to access the HTTP tunnel servlet:

You can set these properties using the -D option to the command that launches the client application.