+

Search Tips   |   Advanced Search

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.

Use the custom properties page to define the following properties:

  • Secure web services applications at the transport level
  • Configure additional HTTP transport properties using the wsadmin command-line tool
  • Configure additional HTTP transport properties for JAX-RPC web services with an assembly tool
  • Configure additional HTTP transport properties using the JVM custom property panel in the administrative console
  • Configure the HTTP transport policy
  • Configure endpoint URL information for HTTP bindings
  • HTTPTransport policy and binding properties
  • Java virtual machine custom properties


    com.ibm.websphere.webservices.http.connectionIdleTimeout

    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

    This property only can be configured as a JVM custom property for Web services applications.

    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 we 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.

    Even if we receive a 202 Accepted response to a request, the request might not be processed. The 202 response code only indicates that the request has been accepted for processing. An accepted request is not acted upon if the request is disallowed when the server tries to process the request. There is no capability for re-sending a status code from an asynchronous operation such as an HTTP request. Therefore, the 202 response code is intentionally non-committal. The purpose of this code is to allow a server to accept a request for some other process, such as a batch-oriented process that is only run once per day, without requiring your agent's connection to the server to persist until the process is completed. The entity returned with this response should include an indication of the current status of the request, and either a pointer to a status monitor, or some estimate of when we can expect the request to be fulfilled..

    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

    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

    This property only can be configured as a JVM custom property for web services applications.

    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

    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

    We can only configure this property as a JVM custom property for web services applications.

    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

    Maximum number of connections 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.

    For performance reasons, ensure that the com.ibm.websphere.webservices.http.maxConnection custom property is equal to or greater than the size of the maximum number of threads in the web container thread pool. The default size for the web container thread pool is 50. As a result, the default size of the com.ibm.websphere.webservices.http.maxConnection property is set to 25 and 50 for JAX-RPC and JAX-WS, respectively. We can adjust the setting for com.ibm.websphere.webservice.http.maxConnection upwards from this initial value, as required, to better use the threads. bprac

    Information Value
    Data type Integer
    Default

    25 for JAX-RPC applications

    50 for JAX-WS applications

    Range 5 to the maximum integer, which is less than or equal to half of the size of web container thread pool

    This property only can be configured as a JVM custom property for web services applications.

    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

    Type of encoding to be used in the message of each HTTP response. It is an HTTP transport property we can configure for web services applications.

    This property is for JAX-RPC only, and it will not be used if it is enabled for services based on JAX-WS.

    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" 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 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

    Type of encoding to use in the message of each HTTP outbound request. It is an HTTP transport property we 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.

    We 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 we 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

    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

    If an invalid value is specified, the default value overrides the invalid value.

    Range 0 (zero) to 2147482 (the maximum integer)

    This property only can be configured as a JVM custom property for web services applications.

    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 we 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

    This property can be configured as a JVM custom property for JAX-RPC web services applications only. For information about how to configure this property, see the Configuring additional HTTP transport properties using the administrative console information.

    We must restart the application server after this custom property has been defined so that this property is used by the system.


    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 JAX-RPC web services.

    The following code demonstrates how to configure the enableMultiThreadedSession property programmatically: 

    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

    We must restart the application server after this custom property has been defined so that this property is used by the system.


    HttpInboundPersistReadTimeout

    Amount of time, in seconds, before the persistent read timeout occurs for asynchronous JAX-WS applications.

    This property is only applicable for asynchronous JAX-WS applications running in a stand-alone application server environment and applies to all defined asynchronous response listeners. We can configure the property only as a JVM custom property. This property affects all web services HTTP connections made within one JVM.

    For asynchronous web services, the client asynchronous response listener opens a socket with the default value of seven seconds to persist and listen for asynchronous responses. If the server operation takes longer than the default value, the server or client might receive the following exception: 

    java.io.IOException: Async IO operation failed (1), reason: RC: 32  Broken pipe
    This exception occurs because the persistent read timeout limit is exceeded on the client and subsequently, the connection is closed.

    Use this property when we 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 we 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 we can configure for web services applications.

    Any requests invoked by the client application 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 ("|"). We can optionally use an asterisk (*) as a wildcard character.

    The http.nonProxyHosts property applies for both HTTP and HTTPS connections.

    For example, on the JVM custom properties panel, enter a name-value pair for the proxy host and the non-proxy host:

    • 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.

    All requests will be routed through the proxy server, myproxy.mycompany.com, except for the HTTP requests destined for the following hosts:

    • 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

    Processing the settings for 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"

    When using a web services client through a web proxy, it is a best practice to set the 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 we 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.bprac

    Information Value
    Data type String

    This property only can be configured as a JVM custom property for web services applications.

    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 we 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 we 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 we 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 we 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

    Amount of time, in seconds, before the read time out occurs.

    When reading a large web services message, we 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 we 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

    We can configure this property as a JVM custom property for JAX-WS applications. For information about how to configure this property as a JVM custom property, see the configuring the HTTP transport policy information. For JAX-RPC applications, we can configure the read time out property as com.ibm.ws.webservices.readTimeout as a JVM custom property.

    For JAX-WS applications, we can also configure this property by customizing the HTTP transport policy or 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

    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, we 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 we 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

    We can configure this property as a JVM custom property for JAX-WS applications. For information about how to configure this property as a JVM custom property, see the configuring the HTTP transport policy information. For JAX-RPC applications, we can configure the write time out property as com.ibm.ws.webservices.writeTimeout as a JVM custom property.

    For JAX-WS applications, we can also configure this property by customizing the HTTP transport policy or 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.