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.
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.
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).
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:
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.
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>.
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.
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.
Copyright © Rogue Wave Software, Inc. All Rights Reserved.
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.
Provide feedback to Rogue Wave about its documentation.