HTTP transport custom properties for web services applications
Use HTTP transport properties for Java™ API for XML-Based Web Services (JAX-WS) and Java API for XML-based RPC (JAX-RPC) web services to manage the connection pool for HTTP outbound connections, configure the content encoding of the HTTP message, enable HTTP persistent connection, and resend the HTTP request when a timeout occurs.
Establishing a connection is an expensive operation. Connection pooling improves performance by avoiding the overhead of creating and disconnecting connections. When an application invokes a web service over an HTTP transport, the HTTP outbound connector for the web service locates and uses an existing connection from a pool of connections. When the response is received, the connector returns the connection to the connection pool for reuse. The overhead to create and disconnect the connection is avoided.
- com.ibm.websphere.webservices.http.connectionIdleTimeout
- com.ibm.websphere.webservices.http.connectionKeepAlive
- com.ibm.websphere.webservices.http.connectionPoolCleanUpTime
- com.ibm.websphere.webservices.http.connectionTimeout
- com.ibm.websphere.webservices.http.maxConnection
- com.ibm.websphere.webservices.http.responseContentEncoding
- com.ibm.websphere.webservices.http.requestContentEncoding
- com.ibm.websphere.webservices.http.requestResendEnabled
- com.ibm.websphere.webservices.http.SocketTimeout
- com.ibm.ws.webservices.enableHTTPPrefix
- com.ibm.ws.websvcs.transport.outbound.connection.forceCleanUpPoolTimeSec
- enableMultiThreadedSession
- HttpInboundPersistReadTimeout
- http.nonProxyHosts
- http.proxyHost
- http.proxyPort
- https.proxyHost
- https.proxyPort
- timeout
- write_timeout
com.ibm.websphere.webservices.http.connectionIdleTimeout
This property specifies the interval, in seconds, after which a connection is not reused.
When an application requests a new connection, the HTTP outbound connector searches through existing unused connections. If it finds a connection that is idle for more time than this property specifies, the connection might be released. If it finds a connection that is idle for less time than this property specifies, the connection is reused and the search stops. Because the search looks for only one endpoint and stops before it reviews all connections, idle connections can remain.
The cleanup task regularly checks all unused connections for their
idle time. If the cleanup task finds a connection that is idle for
more time than this property specifies, it is released. Thus, idle
connections can persist for the length of the cleanup task timer delay
plus the value of this property. For example, if the cleanup task
timer delay is 180
seconds and com.ibm.websphere.webservices.http.connectionIdleTimeout
is set to the default value of 5
seconds, connections
can idle for up to 185 seconds before they are released. The JVM property
that controls the cleanup task timer delay is com.ibm.websphere.webservices.http.connectionPoolCleanUpTime.
This property affects all Web services HTTP connections made within one JVM.
Information | Value |
---|---|
Data type | Integer |
Units | Seconds |
Default | 5 |
Range | 0 (zero) to the maximum integer |
For information about how to configure this property, see the configuring additional HTTP transport properties using the administrative console information.
com.ibm.websphere.webservices.http.connectionKeepAlive
This property specifies whether the connector should maintain a live or persistent HTTP connection. It is an HTTP transport property you can configure for web services applications.
If the property is set to true
, the connector
keeps the connection in the connection pool and reuses the connection
for subsequent HTTP requests. However, the connection is closed if
syncTimeout(Read timeout) is reached or the server has dropped the
connection. Also, an idle connection is closed by the pool maintenance
thread if the idle time has passed the connection idle time out value.
If the property is set to false
, the connection
is closed after the HTTP request is sent. If a new request is ready
to send and the connection does not exist, the HTTP connector creates
one.
An HTTP 200 response to a request indicates that the request was received, and that the connection used for that request is alive and available for re-use for the next call. An HTTP 202 response to a request indicates that the request was received but the connection used for that request is not available for re-use.
Information | Value |
---|---|
Data type | String |
Default | True |
Valid values | True, false |
For information about how to configure this property, see the information on configuring additional HTTP transport properties using wsadmin, and configuring additional HTTP transport properties using an assembly tool.
com.ibm.websphere.webservices.http.connectionPoolCleanUpTime
This property specifies the interval, in seconds, between runs of the connection pool maintenance thread.
This property affects all HTTP connections for web services made within one JVM. For example, if the property is set to 180, the pool maintenance thread runs every 180 seconds. When the pool maintenance thread runs, the connector discards any connections in the clean up queue.
Information | Value |
---|---|
Data type | Integer |
Units | Seconds |
Default | 180 |
Range | 0 (zero) to the maximum integer |
For information about how to configure this property, see the configuring additional HTTP transport properties using the administrative console information.
com.ibm.websphere.webservices.http.connectionTimeout
This property specifies the interval, in seconds, that
a connection request times-out and the WebServicesFault(
"Connection timed out" )
error occurs.
The value affects all of the HTTP connection requests made by the
HTTP outbound connector. The wait time is needed when the maximum
number of connections in the connection pool is reached. For example,
if the property is set to 300 and the maximum number of connections
is reached, the connector waits for 300 seconds until a connection
is available. After 300 seconds, the WebServicesFault(
"Connection timed out" )
error occurs if a connection
is not available. If the property is set to 0 (zero), the connector
waits until a connection is available.
If the WebServicesFault( "Connection timed out")
error
occurs in the application, set the com.ibm.websphere.webservices.http.connectionTimeout
property value higher. Also, review the application usage. If the
com.ibm.websphere.webservices.http.maxConnection property value is
set to 0 (zero), and is enabled for an unlimited number of connections,
the com.ibm.websphere.webservices.http.connectionTimeout property
value is ignored.
Information | Value |
---|---|
Data type | Integer |
Units | Seconds |
Default | 300 |
Range | 0 (zero) to the maximum integer |
For information about how to configure this property, see the configuring additional HTTP transport properties using the administrative console information.
com.ibm.websphere.webservices.http.maxConnection
This property specifies the maximum number of connections that are created in the HTTP outbound connector connection pool.
This property affects all of the web services HTTP connections
that are made within one JVM. When the maximum number of connections
is reached, no new connection are created and the HTTP connector waits
for a current connection to return to the connection pool. If the
HTTP connector does not wait for a current connection because of a
connection request timeout, the WebServicesFault( "Connection
timed out" )
error occurs. For example, if the property
is set to 5, and there are 5 connections in use, the HTTP connector
waits for the specified time set in the com.ibm.websphere.webservices.http.connectionTimeout
property for a connection to become available.
Information | Value |
---|---|
Data type | Integer |
Default | 25 for JAX-RPC applications 50 for JAX-WS applications |
Range | 5 to the maximum integer |
For information about how to configure this property, see the configuring additional HTTP transport properties using the administrative console information.
com.ibm.websphere.webservices.http.responseContentEncoding
This property specifies the type of encoding to be used in the message of each HTTP response. It is an HTTP transport property you can configure for web services applications.
Supported encoding formats follow the HTTP 1.1 protocol specification including gzip, x-gzip, and
deflate. If this property is configured, the Content-Encoding
header in the HTTP
response is set to the same value. If the property is not set, the HTTP response message content is
not encoded. The default value is no encoding
.
If the property is set, the request client must also support the
same encoding. Otherwise, a failure can occur and a WebServicesFault()
error
displays.
The compress encoding format is not supported and x-gzip encoding is equivalent to gzip encoding.
Information | Value |
---|---|
Data type | String |
Valid values | gzip, x-gzip, or deflate |
For information about how to configure this property, see the information on configuring additional HTTP transport properties using wsadmin, and configuring additional HTTP transport properties using an assembly tool.
com.ibm.websphere.webservices.http.requestContentEncoding
This property specifies the type of encoding to use in the message of each HTTP outbound request. It is an HTTP transport property you can configure for web services applications.
Supported encoding formats follow the HTTP 1.1 protocol specification including gzip, x-gzip, and
deflate. If this property is configured, the headers Content-Encoding
and
Accept-Encoding
in the HTTP request are also set to the same value. For example, if
the property is set to gzip, the headers become Content-Encoding: gzip and Accept-Encoding: gzip.
However, if the property is not set, the HTTP request message is not encoded. The default is no
encoding.
You should check if the target web server is capable of decoding
the configured coding format. For example, if the property is set
to gzip, the target web server must also support the gzip encoding.
Otherwise, a failure can occur and a status code of 415
Unsupported Media Type
might display.
The compress encoding format is not supported and x-gzip encoding is equivalent to gzip encoding.
Information | Value |
---|---|
Data type | String |
Valid values | gzip, x-gzip, and deflate |
For information about how to configure this property, see the information on configuring additional HTTP transport properties using wsadmin, and configuring additional HTTP transport properties using an assembly tool.
com.ibm.websphere.webservices.http.requestResendEnabled
This property tells the HTTP connector to resend the SOAP
message over HTTP request after a java.net.ConnectException:
read timed out
error is logged. It is an HTTP transport
property you can configure for web services applications.
This property tells the HTTP connector to resend the SOAP message
over HTTP request after a java.net.ConnectException: read
timed out
error is logged. The java.net.ConnectException
is
caused by a socket time out, or when a server shuts down while the
request is being sent. If the property is enabled, the connector tries
to reconnect one time only and resends the same SOAP message over
HTTP. Otherwise, the connector stops sending the SOAP message and
a WebServicesFault
error is logged.
Problems can occur with the application this property is enabled. The HTTP request that is resent can be received twice by the server and can cause an unexpected result.
Information | Value |
---|---|
Data type | String |
Default | False |
Valid values | True, false |
For information about how to configure this property, see the information on configuring additional HTTP transport properties using wsadmin, and configuring additional HTTP transport properties using an assembly tool.
com.ibm.websphere.webservices.http.SocketTimeout
This property specifies the amount of time, in seconds, to wait for the outbound socket to be established with the remote server.
This property affects all web services HTTP connections made within one JVM. If an invalid value is provided, the default value overrides the invalid value.
Information | Value |
---|---|
Data type | Integer |
Units | Seconds |
Default | 180 Attention: If an invalid value
is specified, the default value overrides the invalid value.
|
Range | 0 (zero) to 2147482 (the maximum integer) |
For information about how to configure this property, see the configuring additional HTTP transport properties using the administrative console information.
com.ibm.ws.webservices.enableHTTPPrefix
This property specifies whether the hostname:port
value
that is defined as a custom HTTP URL prefix in the Provide HTTP endpoint
URL panel in the administrative console is populated to the URL field
in the copy of the WSDL file that is returned from the service to
the client. It is an HTTP transport property you can configure for
web services applications.
Configure this property with the value of true
so
the specified custom HTTP URL prefix is correctly specified in the
WSDL file that is returned to the client. If this property is not
configured with the value of true
, then the
specified custom hostname:port
of the server node
that responds to the request is not populated in the URL field in
the copy of the WSDL file that is returned to the client.
Information | Value |
---|---|
Data type | String |
Default | False |
Valid values | True, false |
For information about how to configure this property, see the Configuring additional HTTP transport properties using the administrative console information.
You must restart the application server after this custom property has been defined so that this property is used by the system.
com.ibm.ws.websvcs.transport.outbound.connection.forceCleanUpPoolTimeSec
This property specifies an amount of time after which connections are removed from the connection pool, regardless of whether they are active or abandoned.
In rare cases, connections might remain in the connection pool, which can fill up the connection pool. If the connection pool is full, all new requests must wait for an available connection and eventually time out. To prevent this connection leak issue, you can specify a time after which connections that have not received a response are cleaned up.
To enable forced connection cleanup, configure this property with a value in seconds. Connections that exist for longer than the configured value are cleaned up.
Information | Value |
---|---|
Data type | Integer |
Units | Seconds |
Default | N/A |
Range | 0 (zero) to 2147482 (the maximum integer) |
For information about how to configure this property, see the documentation for configuring additional HTTP transport properties using the administrative console.
enableMultiThreadedSession
This property specifies whether to allow a client to share
HTTP session information across threads for the same client instance.
To enable this behavior, configure this property with the value of true
by
calling the _setProperty method on the client stub. If this property
is not enabled, the default behavior is to make sessions local to
the thread on which the client was invoked.
This property is only applicable for Java API for XML-based RPC (JAX-RPC) web services.
Properties prop = new Properties();
InitialContext ctx = new InitialContext(prop);
Service service = (Service)ctx.lookup("java:comp/env/service/StockQuoteService");
QName portQname = new QName("http://httpchannel.test.wsfvt.ws.ibm.com", "StockQuoteHttp");
StockQuote sq = (StockQuote)service.getPort(portQname, StockQuote.class);
((javax.xml.rpc.Stub) sq)._setProperty(com.ibm.wsspi.webservices.Constants.ENABLE_MULTITHREADED_SESSION, Boolean.TRUE);
Information | Value |
---|---|
Data type | Boolean |
Default | False |
Valid values | True, false |
You must restart the application server after this custom property has been defined so that this property is used by the system.
HttpInboundPersistReadTimeout
This property specifies the amount of time, in seconds, before the persistent read timeout occurs for asynchronous JAX-WS applications.
java.io.IOException: Async IO operation failed (1), reason: RC: 32 Broken pipeThis exception occurs because the persistent read timeout limit is exceeded on the client and subsequently, the connection is closed.
Use this property when you are reading large data, or at times when the network is slow such that it takes more than the default value of seven seconds on the server side to read the data. If you receive the broken pipe exception on the server side, increase the value of this time out property.
Information | Value |
---|---|
Data type | Integer |
Units | Seconds |
Default | 7 |
Valid values | 0 (zero) to the maximum integer |
For information about how to configure this property, see the configuring additional HTTP transport properties using the administrative console information.
http.nonProxyHosts
This JVM system property acts as an override to the http.proxyHost
and https.proxyHost
properties
and specifies the host names of machines to which requests will not
be sent through the proxy server. It is an HTTP transport property
you can configure for web services applications.
Any requests invoked by the client application that are sent to a host whose name is contained in
this property will not pass through the proxy server. Separate each host name in the list with a
vertical bar (|
). You can optionally use an asterisk (*
) as a
wildcard character.
The http.nonProxyHosts
property applies for both
HTTP and HTTPS connections.
- For the proxy host, enter a name of http.proxyHost and a value of myproxy.mycompany.com.
- For the non-proxy host, enter a name of http.nonProxyHosts and a value of host1.company1.com|host*.company2.com|*.company3.com.
- a single host named host1.company1.com
- any host in the company2.com domain whose name starts with host
- any host in the company3.com domain
http.nonProxyHosts
is performed as pure pattern
matching. Host names are not expanded to their fully-qualified form before being matched to the
pattern. For example, with http.nonProxyHosts
specified in the preceding example,
the string host1 will not match any of the settings specified, and as such, the
web services engine will send the request through the proxy server. In order for the
host1 request to not be sent through the proxy server, the
http.nonProxyHosts
specification would have to include host1
somewhere in the specification. An illustration of this specification
follows.http.nonProxyHosts="host1.company1.com|host*.company2.com|*.company3.com|host1"
http.nonProxyHosts
property to include the local
host if any web services are hosted on the same system. For example, if the local host is named
myHost.myCorp.com, then set the http.nonProxyHosts
property to
localhost|myHost.myCorp.com
or localhost|*.myCorp.com
. If you do
not set the http.nonProxyHosts
property to include the local host, then web
services requests made to the local host will go out to the web proxy and then return back to the
local host.Information | Value |
---|---|
Data type | String |
For information about how to configure this property, see the configuring additional HTTP transport properties using the administrative console information.
http.proxyHost
This property specifies the host name of an HTTP proxy. It is an HTTP transport property you can configure for web services applications.
Information | Value |
---|---|
Data type | String |
For information about how to configure this property, see the information on configuring additional HTTP transport properties using wsadmin, and configuring additional HTTP transport properties using an assembly tool.
http.proxyPort
This property specifies the port of an HTTP proxy. It is an HTTP transport property you can configure for web services applications.
Information | Value |
---|---|
Data type | String |
For information about how to configure this property, see the information on configuring additional HTTP transport properties using wsadmin, and configuring additional HTTP transport properties using an assembly tool.
https.proxyHost
This property specifies the host name of an HTTPS proxy. It is an HTTP transport property you can configure for web services applications.
Information | Value |
---|---|
Data type | String |
For information about how to configure this property, see the information on configuring additional HTTP transport properties using wsadmin, and configuring additional HTTP transport properties using an assembly tool.
https.proxyPort
This property specifies the port of an HTTPS proxy. It is an HTTP transport property you can configure for web services applications.
Information | Value |
---|---|
Data type | String |
For information about how to configure this property, see the information on configuring additional HTTP transport properties using wsadmin, and configuring additional HTTP transport properties using an assembly tool.
timeout
This property specifies the amount of time, in seconds, before the read time out occurs.
When reading a large web services message, you might receive WSWS3228E messages along with SocketTimeoutExceptions errors when web services calls are made.
The value affects all of the HTTP connection requests made by the HTTP inbound connector. Use this read time out property when you are reading large data or at times when the network is slow and it takes more than the default time of 300 seconds to read the data. If SocketTimeoutExceptions errors occur when the message is read, increase the value of the timeout property.
Information | Value |
---|---|
Data type | Integer |
Units | Seconds |
Default | 300 |
Range | 0 (zero) to the maximum integer |
com.ibm.ws.webservices.readTimeout
as a JVM custom property.For JAX-WS applications, you can also configure this property by customizing the HTTP transport policy or by using JAX-WS bindings. For information about how to configure this property using these methods, see the information on configuring additional HTTP transport properties using the administrative console or configuring HTTPTransport policy and binding properties.
write_timeout
This property specifies the length of time, in seconds, for the write to time out action to occur when a message is sent.
When writing a large web services message, you might receive WSWS3228E messages along with SocketTimeoutExceptions errors when web services calls are made.
The value affects all of the HTTP connection requests made by the HTTP outbound connector. Use this write time out property when you are sending large amounts of data or at times when the network is slow and it takes more than the default time of 300 seconds to write the data. If the SocketTimeoutExceptions errors occur when the message is written, increase the value of the write_timeout property.
Information | Value |
---|---|
Data type | Integer |
Units | Seconds |
Default | 300 |
Range | 0 (zero) to the maximum integer |
com.ibm.ws.webservices.writeTimeout
as a JVM custom property.For JAX-WS applications, you can also configure this property by customizing the HTTP transport policy or by using JAX-WS bindings. For information about how to configure this property using these methods, see the information on configuring additional HTTP transport properties using the administrative console or configuring HTTPTransport policy and binding properties.