Transport and Listener Properties

HydraExpress Web Service Development Guide
Rogue Wave web site: Home Page | Main Documentation Page

11.3 Transport and Listener Properties

The elements that define transports and listeners in the configuration files contain a number of rwsf::property elements. These elements specify default values for certain named properties. These values are used when initializing the transport or listener.

The property values can be modified at runtime. The proxy classes have a setTransportProperty() method that takes two strings, corresponding to a rwsf::property element name and value. The transport and listener base classes have a method called setProperty() for setting properties directly through the transport or listener object.

Table 6 lists the properties of the HTTP and HTTPS transports supplied with HydraExpress, including HTTPS support for client-side authentication.

Note that, in this discussion, the files being edited are the project's transport files, server-transports.xml, and client-transports.xml, rather than the template files located in the <installdir>\conf\webservice directory. This means that the settings are relevant to just a single project. If you want the settings to apply to all projects, instead edit the template files in the <installdir>\conf\webservices directory.

Table 6: Transport properties for HTTP and HTTPS

Property name	Type	Description
`cancel-session`	bool	If `true`, the transport does not maintain the session across calls. This value can be changed between requests.
`connect-timeout`	long	Timeout used when the transport attempts to connect to the server. The value is in milliseconds. The value specified in the default configuration files is `60000`. This value cannot be changed until the transport disconnects.
`password`	string	The password for the `user` property. This value can be changed between requests. This value is ignored if `user` is not set.
`proxy-location`	string	Specifies the location of the proxy server to use. This property must be specified in the `server-transports.xml` file, and must specify a URL to the proxy to be used. For example, in order to specify a HTTP proxy running on `www.somewhere.net port 8080`, you would add the following property to HTTP Transport block: <rwsf:property name="proxy-location" value="http://www.somewhere.net:8080/"/>
`reply-timeout`	long	Timeout used when waiting for the reply. The value is specified in milliseconds. The value specified in the default configuration files is `60000`. This value can be changed between requests.
`submit-timeout`	long	Timeout used when submitting the request to the server. The value is specified in milliseconds. The value specified in the default configuration files is `60000`. This value can be changed between requests.
`user`	string	If this value is set and the `password` property is set, the transport sends the user and password combination as an HTTP header via the Basic Authorization header. This value can be changed between requests.
HTTPS-specific Transport Properties (extensions to the set of properties listed above)
`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.
`ssl-certificate`	string	This property indicates the file that contains the X.509 Certificate for the client. This property is mandatory if performing client 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 client authentication. This property cannot be changed until the transport disconnects.
`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-trusted-certificates`	string	This property indicates the file that contains the trusted certificate chain used in authentication. This property is mandatory if performing server authentication. This property cannot be changed until the transport disconnects.

Table 7 lists the properties of the HTTP and HTTPS listeners supplied with HydraExpress.

Table 7: Listener properties for HTTP and HTTPS

Property name	Type	Description
`auto-start`	string	If `true`, the listener thread is started automatically when the listener object is initialized.
`bound-host`	string	The host used by the listener. If `host` is unspecified, this property is populated with the name returned by `gethostname()`.
`bound-ip`	string	The IP address used by the listener. If the `host` property is unspecified, this property is populated with the IP address of the host name returned by `gethostname()`.If the host property is specified, the `bound-ip` property will be set to the IP address of the specified host.
`bound-port`	string	The port used by the listener. If the `port` property is unspecified, this property is populated with the first unbound port. If the `port` property is specified, the `bound-port` property will be set to the same value.
`host`	string	Host name used to create a listener socket. Note: This value is also assigned to `bound-host`, which is always used by the system to locate the listener host If not specified, the host name returned by the global function `gethostname()` is used. In this case, `host` is left unpopulated.
`keep-alive`	bool	If `true`, the connection is not automatically closed once the response had been sent to the client. This property allows support of HTTP/1.1 persistent connections.
`port`	string	Port name used to create a listener socket. If not specified, the value `0` is assumed, and the property `bound-port` is populated with the first unbound port. In this case, the `port` property will be left unassigned, and `bound-port` will be used.
`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`. If this property is not specified, the default is `10`.
`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 not 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 `60000`. If not specified, the listener blocks indefinitely.
HTTPS-specific Listener Properties (extensions to the set of properties listed above)
`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.
`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.
`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-trusted-certificates`	string	This property indicates the file that contains the trusted certificate chain used in authentication. This property is mandatory if performing client authentication. This property cannot be changed until the transport disconnects.

© Copyright Rogue Wave Software, Inc. All Rights Reserved. All Rights Reserved. Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. HydraExpress is a trademark of Rogue Wave Software, Inc. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.