HydraExpress User Guide : PART II The HydraExpress Agent : Chapter 3 Overview of Agent Configuration : Configuring the Agent
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
NOTE >> 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.
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.
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 “Configuring Secure Messaging with HTTPS.”.
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 “Configuring Apache as an External Web Server.”.
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 “Handler Chains.”.
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 ).
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.
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>.
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.1
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.1
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.

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

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 container, and servlet, which represents the entry point to the servlet container. HydraExpress web services are implemented as servlets.
The servlet container within the Agent 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 container, see Chapter 14, “SOAP Message Handlers,” in the HydraExpress Web Service Development Guide.