Configuring the Agent

HydraExpress User Guide
Rogue Wave web site: Home Page | Main Documentation Page

3.2 Configuring the Agent

Configuration file rwagent.xml defines all configuration data needed to initialize the -HydraExpress Agent, the runtime that hosts HydraExpress services and servlets. It also includes references to other configuration files in the conf directories. You can modify this file to specify:

Agent startup and shutdown configuration
connectors
handler chains
default Agent logging configuration file

Please note that rwagent.xml uses the environment variable RWSF_CONF. This variable points to the default location of the conf directory, which is RWSF_HOME\conf. If you move the conf directory or any of its files to another location, you will need to revise all references to RWSF_CONF in rwagent.xml to point to the new location.

3.2.1 Agent Startup and Shutdown

At the top of rwagent.xml, there are settings for three properties:

the path to the default logging configuration file, typically RWSF_CONF\loggers.xml
a shutdown key representing the message to send to the Agent to cause it to shut down
a shutdown port, the location to send the shutdown message

These properties are followed by a set of elements for defining code to run at Agent startup and shutdown. These elements are hooks to modify the startup and shutdown behavior of the agent. This is what that configuration may look like:

<rwsf:methods>
  <rwsf:preStartup>
    <!--
    <rwsf:method name="load-named-objects"
        class="rwsf_agent_methods46.createNamedObjectLoader">
      <rwsf:property name="rwsf:objects-file"
        value="${RWSF_CONF}/objects.xml"/>
    </rwsf:method>
    -->
  </rwsf:preStartup>

  <rwsf:postStartup>
  </rwsf:postStartup>

  <rwsf:preShutdown>
  </rwsf:preShutdown>

  <rwsf:postShutdown>
    <rwsf:method name="destroy-named-objects"
       class="rwsf_agent_methods46.createNamedObjectCleanup"/>
  </rwsf:postShutdown>
</rwsf:methods>

For any given element, the methods are initialized in the order they appear in the configuration file and are executed in the order they appear within each element. The time of execution for the methods within an element is as follows:

preStartup: executed immediately after the methods end tag is parsed during startup
postStartup: executed after all components have been initialized, and after the connectors have been started
preShutdown - executed at shutdown before any of the normal Agent runtime components shut down
postShutdown - executed at shutdown after all of the normal Agent runtime components have shut down

If you wish to use named objects, you will need to uncomment the rwsf:methods element named load-namedobjects, and update the rwsf:objects-file property to point to your named objects definition file. In the code above, the file is objects.xml in the main conf directory.

3.2.2 Agent Connectors

A connector configuration specifies the end point for a particular transport, and specifies a number of connection parameters. The connector thus configured processes request messages arriving on the transport, preparing the request data for handoff to an associated handler chain, the entry point into the rest of the system.

This is the default definition for the Agent's HTTP connector:

<rwsf:connector name="HTTP/1.1" 
    class="rwsf_transport_http46.createHttpConnectorImp"
    handlerChain="http">
  <rwsf:property name="accepter-threads" value="1"/>
  <rwsf:property name="thread-pool-min" value="5"/>
  <rwsf:property name="thread-pool-max" value="10"/>
  <!-- <rwsf:property name="host" value="localhost"/> -->
  <rwsf:property name="port" value="8090"/>
  <rwsf:property name="request-backlog" value="10"/>
  <rwsf:property name="request-buffersize" value="4096"/>
  <rwsf:property name="request-timeout" value="30000"/>
</rwsf:connector>

HydraExpress provides three default connectors:

HTTP

This connector listens for and accepts requests, stores the transport-specific information and the request payload, and passes the request data to a handler chain.

HTTPS

This connector provides security at the transport level through the HTTPS transport. The default port for receiving HTTPS requests is 8443. For a discussion on configuring the HTTPS connector, see Section 3.2.3.

AJP13

This connector listens for and accepts requests from an Apache Web server. The default port is 8009. For information on the AJP 1.3 Apache connector, see Section 3.4.

By default, all connectors point to the handler chain named http. Handler chains take care of message handling and dispatch to the servlet container, as explained in more detail in Section 3.2.4.

The file may contain configuration information for any number of connectors, including multiple connectors of the same type, provided that each connector has a unique name and listens on a different port.

You can add support for additional transports by deriving from a connector base class and implementing the required functionality (see Chapter 5).

3.2.2.1 Agent Ports

Agent runtime ports are set in rwagent.xml as a property of the connectors. For example, the line in bold below

<rwsf:connector name="HTTP/1.1" 
...
   <rwsf:property name="port" value="8090"/>
...
</rwsf:connector>

sets the port for the HTTP connector to 8090.

The HydraExpress Agent runtime uses the following default ports:

Table 3: Agent default ports

`8090`	Used for HTTP requests sent directly to the Agent.
`8009`	Used for AJP 1.3 requests sent to the Agent; usually sent from an external Web server such as Apache.
`8443`	Used for HTTPS requests sent directly to the Agent
`8089`	Used for sending shutdown requests to the HydraExpress runtime. Shutdown requests must be issued from the host on which the Agent is running.

Common Issues with Ports

If you are running other servers on the same machine as the Agent, such as Tomcat or Apache, be sure that each is assigned a different port. For example, the default Tomcat AJP 1.3 port is 8009, the same port as the default AJP-1.3 connector in HydraExpress. In this case, you would need to change either the port for Tomcat or the AJP-1.3 connector port.

Requests or listeners assigned to the same ports on the same server will result in a fatal startup error Unexpected exception: SocketException: in Socket::bind: ADDRINUSE.

3.2.2.2 Setting the URL of the Agent

The Agent URL is defined by the connector properties host and port. By default, the host property is commented out for all connectors. In the absence of this property, the Agent listens on all interfaces defined for the host machine. To have the Agent listen on a particular interface, uncomment this property and set the value you want.

The connector does not explicitly set the scheme for the transport it handles. This is assumed knowledge. That is, if a client wants to send an HTTP message, it must know to send the message to the host and port defined for the http connector. If you are using a HydraExpress client, the generated code for the client knows about the defined transports and the connector hosts and ports associated with each transport.

The URL below represents the endpoint for an HTTP message sent to an Agent in its default configuration. The servicecontextname and servicename variables depend on the WSDL file for a particular service. If you use the HydraExpress code generator rwsfgen to generate code for the service, these values are created for you.

http://localhost:8090/<servicecontextname>/<servicename>.

3.2.3 Configuring Secure Messaging with HTTPS

The HydraExpress Agent automatically handles messages sent on secure transports (HTTPS) through its HTTPS connector. The default port for receiving HTTPS requests is 8443. Use this connector for encrypted connections between the client and the server.

The HTTPS connector is configured in the main Agent configuration file, rwagent.xml, located in your <installdir>\conf directory. The example below shows the default configuration.

  <rwsf:connector name="HTTPS (HTTP/1.1)" 
    class="rwsf_transport_https42.createHttpsConnectorImp"
    handlerChain="http">
    <rwsf:property name="accepter-threads" value="1"/>
    <rwsf:property name="thread-pool-min" value="5"/>
    <rwsf:property name="thread-pool-max" value="10"/>
    <!-- <rwsf:property name="host" value="localhost"/> -->
    <rwsf:property name="port" value="8443"/>
    <rwsf:property name="request-backlog" value="5"/>
    <rwsf:property name="request-buffersize" value="4096"/>
    <rwsf:property name="request-timeout" value="30000"/>
    <rwsf:property name="ssl-quiet-shutdown" value="false"/>
    <rwsf:property name="ssl-certificate" 
           value="${RWSF_CONF}/certs/localhost.crt"/>
    <rwsf:property name="ssl-private-key" 
           value="${RWSF_CONF}/certs/localhost.key"/>
    <rwsf:property name="security-init-seed" value="123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890"/>
    <rwsf:property name="security-init-seed-type" value="string"/>
  </rwsf:connector>

Table 4 lists the configurable properties.

Table 4: HTTPS connector properties

Property name	Types	Description
`accepter-threads`	`int`	Specifies the number of threads that should be spawned listening for new connections. Defaults to `1`.
`thread-pool-min`	`int`	The minimum number of threads to be created in the thread pool. Defaults to `5`.
`thread-pool-max`	`int`	The maximum number of threads to be created in the thread pool. Defaults to `10`.
`port`	`string`	Port name used to create a listener socket. Defaults to 8443.
`request-backlog`	`int`	The number of pending connection requests allowed before the system starts refusing connections. The value specified in the default configuration files is `5`.
`request-buffersize`	`long`	Size of the buffer used to receive incoming messages. Smaller values may result in slower performance. Larger values may result in wasted space. The value specified in the default configuration files is `4096`. If no value is specified, the default is no buffering.
`request-timeout`	`long`	Timeout used when returning a request to the client. The value is specified in milliseconds. The value specified in the default configuration files is `30000`. If not specified, the listener blocks indefinitely.
`ssl-quiet-shutdown`	`bool`	During normal shutdown of an SSL connection, both sides will attempt to perform a final handshake indicating that each has agreed to close the connection. If one side closes the connection before the other can send its part of the handshake, this operation can fail with an exception or signal. This property disables this final handshake. The default value is `false`.
`ssl-certificate`	`string`	This property indicates the file that contains the X.509 Certificate for the client. This property is mandatory if performing server authentication. This property cannot be changed until the transport disconnects.¹
`ssl-private-key`	`string`	This property indicates the file that contains the Private Key for the client. This property is mandatory if performing server authentication. This property cannot be changed until the transport disconnects.¹
`security-init-seed`	`string`	This is used as the seed for the random number generator. This value cannot be changed until the transport disconnects.
`security-init-seed-type`	`string`	If this property is set to `string`, it indicates that the `security-init-seed` property contains a seed string. If set to `filename`, it indicates that the `security-init-seed` property contains the name of a file holding the seed.

Provided certificate and key should be used for testing purposes only.

3.2.4 Handler Chains

The rwagent.xml file also configures the handler chains. Connectors pass incoming requests to a handler chain as specified in the connector configuration (see above). This is the default http handler chain definition:

<rwsf:handler-chain name="http">
  <rwsf:handler name="httpServer"
    class="rwsf_transport_http46.createHttpServerHandlerImp" type="request"/>
  <rwsf:handler name="servlet" 
    class="rwsf_servlet46.createServletMessageInfoHandlerImp" type="request">
    <rwsf:property name="rwsf:configDir" value="${RWSF_CONF}/servlet"/>
    <rwsf:property name="rwsf:webappsDir" value="${RWSF_HOME}/apps/servlets"/> 
    <rwsf:property name="rwsf:librarySuffix" value="4612d"/>
    <rwsf:property name="rwsf:debugLibrarySuffix" value="4615d"/>
  </rwsf:handler>
</rwsf:handler-chain>

The http handler chain is the default chain for the HTTP, HTTPS and AJP 13 connectors. It contains just two handlers, httpServer, which prepares the request for handoff to the execution engine, and servlet, which represents the entry point to the servlet container. HydraExpress web services are implemented as servlets.

The servlet container has its own handler system. While you can create handlers at both the Agent and servlet container levels, we recommend that you use the servlet container handler system for any additional handlers you want to create. For the details on how to create and configure custom handlers in the servlet execution engine, see Chapter 14, "SOAP Message Handlers," in the HydraExpress Web Service Development Guide.

The Rogue Wave name and logo are registered trademarks of Rogue Wave Software, and HydraExpress is a trademark of Rogue Wave Software. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.