HTTP Client

The HTTP Client resource template represents an outgoing HTTP connection.

General

The General section has the following fields.

Field Description
Package The name of the package in which you want to create a shared resource.
Name The name of the shared resource.
Description A short description of the shared resource.

HTTP Client

This section has the following fields.

Field Literal Value/Module Property Description
Default Host Yes The name of the host that accepts the incoming requests.

For machines that have only one network card, the default value localhost specifies the current machine. For machines with more than one network card, this field specifies the host name of the card used to accept the incoming HTTP requests.

The default value is localhost.

Default Port Yes The port number on which to invoke outgoing HTTP requests.

The default value is 80.

HTTP Version No

The HTTP version to be used for communication. By default, it is HTTP 1.1. If required, you can select HTTP 2.0 as the version for the HTTP 2 communication. It is mandatory for the server to support HTTP 2 as well if HTTP 2 is selected as the client protocol. When HTTP 2 is selected as the version, the option of the client in the Implementation Library field, changes to Jetty HTTP Client, and other options do not appear, as only the Jetty client supports HTTP 2. When HTTP 1.1 is selected as the version, the previous options reappear along with the new option Jetty HTTP Client, which also supports HTTP 1 communication.

When HTTP 2.0 is selected as the HTTP version in the HTTP client shared resource, enabling SSL through the Confidentiality or Default Confidentiality option is compulsory.

  • If Confidentiality is enabled at the HTTP client and HTTP 2 is the version used, it is necessary to select Enable Mutual Authentication at the corresponding SSL client resource and configure the identity store provider, key alias name, and key password.

Note: HTTP 2 is currently supported only for the HTTP palette along with HTTP 1.1. The SOAP and REST bindings continue to use only HTTP 1.1 for communication.
Implementation Library No

Specifies the implementation library to be used:

  • Apache HttpComponents(Supported by HTTP 1, SOAP and REST): must be used for the SOAP and REST Reference Binding, and Invoke REST API activity.

    When HTTP 2 is selected as the protocol version in HTTP Connector resource, with Follow HTTP1 Compliance selected, and HTTP Components client is used as the implementation library in the HTTP Client resource, the application fails due to lack of common cipher suites. Hence this scenario is presently not supported for HTTP 2 in TIBCO BusinessWorks™ Container Edition .

  • Jetty HTTP Client: can be used for HTTP activities (both HTTP 1.1 and HTTP 2). This client library is currently not supported for REST and SOAP.
  • Apache Commons(Deprecated): Apache Commons library is now no longer used, because it is deprecated. Older imported projects using Apache Commons, continue to display Apache Commons as the client option, but Apache Components is used as the client for executing the HTTP requests, because this library is obsolete.

The default is Apache HttpComponents(Supported by HTTP 1, SOAP and REST), when HTTP 1.1 is selected as the protocol version. When HTTP 2 is selected as the protocol version, the Jetty HTTP Client is the only Implementation option available, because currently only the Jetty Client supports HTTP 2.

Note:  
  • The Jetty HTTP Client implementation can only be chosen for HTTP applications, and is not compatible with SOAP/REST applications.
  • After Axis2 upgrade, Apache Commons client library is no longer used in HTTP. The projects migrated from ActiveMatrix BusinessWorks 5.x shall now show Apache Components as the client library instead of Apache Commons.
Disable Connection Pooling Yes Indicates whether to use the single or multi-threaded connection manager.

If you select this check box, Maximum Total Connections, Idle Connection Timeout(ms), Maximum Total Connections Per Host/Route, and Stale Check fields are disabled.

The default value is False.

This option is not enabled when the Jetty HTTP Client is selected as the implementation library, because connection pooling happens internally in the Jetty Client library.

Maximum Total Connections Yes Specifies the maximum number of concurrent, active HTTP connections allowed by the resource instance to be opened with the target service. This property is enabled only if connection pooling is enabled (the Disable Connection Pooling parameter is deselected).

The default value is 200.

For applications that create many long-lived connections, increase the value of this parameter.

Idle Connection Timeout(ms) Yes Keep-alive time (in milliseconds) for idle HTTP connection in the Persistent Connection Pool.
Maximum Total Connections Per Host/Route Yes Specifies the maximum number of concurrent, active HTTP connections allowed by the resource instance to the same host or route. This property is enabled only if connection pooling is enabled (the Disable Connection Pooling parameter is unchecked).
Note: This number cannot be greater than Maximum Total Connections. Every connection created here also counts into Maximum Total Connections.

The default value is 20.

Stale Check Yes Selecting this check box determines whether the stale connection check is to be used. Disabling the stale connection check can result in slight performance improvement at the risk of getting an I/O error, when executing a request over a connection that has been closed at the server side.
Cookie Policy No Specifies the Cookie Policy to use:
Note: Ensure you have selected Apache HttpComponents (Supported by HTTP and REST) as the Implementation Library when selecting a Cookie Policy.
  • BROWSER_COMPATIBILITY: Choose this option to select a cookie policy that is compatible with the common cookie management practices, including those that are not fully standards compliant.
  • NETSCAPE: Select this option to use the Netscape cookie draft compliant policy. When you select this option, Cookie2 headers are not sent in the request message.
  • RFC_2109: Select this option to use the RFC2109 compliant policy. This policy is supported for HTTP palette activities.
    Note: If this policy is selected for the Invoke API activity or the REST Reference Binding, the BEST_MATCH policy is selected instead.
  • IGNORE_COOKIES: Select this option if cookies sent by the server need be disabled.
  • BEST_MATCH: This is the default selection. Select this option to choose the BEST_MATCH Cookie Policy.
Disable connection state tracking Yes This check box is enabled only when Apache HttpComponents (Supported by HTTP and REST) option is selected in the Implementation Library field.

When this check box is selected, the HTTPS connections are not reset by the Apache components client, and a single HTTPS connection can be reused.

By default, the check box is clear.

Caution: If you select this check box, there might be a security risk of leasing a persistent SSL connection to the wrong user.

This option is not enabled when the Jetty HTTP Client is selected as the implementation library.

Thread Pool No Specifies a queue of threads available to run a queue of tasks.

Thread pools are used to improve performance when executing large numbers of asynchronous tasks by reducing per task invocation overhead, provide a means of bounding, and managing the resources consumed when executing a collection of tasks.

You can optionally create this client thread pool to route messages to the target service. The thread pool resource can be created by either selecting a thread pool resource template or creating a new one.

For more information, see the Thread Pool topic.

Service Discovery Configuration
Enable Service Discovery No Select this check box to enable service discovery.
Service Name Yes The service name to be discovered on Eureka or Consul. You can also browse the services from Consul or Eureka by using icon.
  • Consul: To browse the services from Consul, select Consul and the service to be set for the HTTP Client Service Registry Configuration.
  • Eureka: To browse the services from Consul, select Eureka and select the service to be set for the HTTP Client Service Registry Configuration.
Note: Set the Consul and the Eureka URLs in the Service Registry preference.

Enable Caching Yes When enabled, services are discovered only from the local cache instead of accessing the Eureka or Consul servers.
Thread Pool No Specifies a queue of threads available to run a queue of tasks.

Thread pools are used to improve performance when executing large numbers of asynchronous tasks by reducing per task invocation overhead, provide a means of bounding, and managing the resources consumed when executing a collection of tasks.

You can optionally create this client thread pool to route messages to the target service. The thread pool resource can be created by either selecting a thread pool resource template or creating a new one.

For more information, see the Thread Pool topic.

Enable Loadbalancing Yes If enabled, service instances are invoked in a round-robin fashion. If not enabled, the first cached service instance is always invoked irrespective of the number of service instances.

Advanced

This section has the following fields.

Field Literal Value/Module Property Description
Socket Timeout (ms) Yes Specifies the number of milliseconds to wait for data before the connection is severed.

The value zero (0) is interpreted as an infinite timeout and is used when no socket timeout is set in the HTTP method parameters.

Connection Timeout (ms) Yes Specifies the number of milliseconds to wait while a connection is being established.

The value zero (0) is interpreted as no timeout.

Accept Redirect Yes Indicates whether the HTTP method should automatically follow HTTP redirects.

This option is used when client connection receives the redirect responses from server like Moved Permanently, Moved Temporarily, Temporary Redirect and so on.

The default value is False.

Retry Count Yes Specifies the maximum number of retry attempts for connecting to the server if an exception occurs.

When the client library implementation is set to Apache Components, the retry count at HTTP client shared resource is accessed internally by the Apache Components Client to create a DefaultHttpRequestRetryHandler (https://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/impl/client/DefaultHttpRequestRetryHandler.html), which retries to send the failed requests number of times specified in the Retry Count field.

Interrupted IO Exception, Unknown Host Exception, Connect Exception, and SSL Exception are the types of exceptions for which the requests cannot be retried. The requests are retried for all other exceptions, only if the request has not been successfully sent. The default value of retry count is 3.

Use Single Cookie Header Yes Select this check box if multiple name/value pairs must be sent in a single non-repeating Cookie header element for outgoing HTTP requests.

The default value is False.

Use Non-Preemptive Authentication Yes Select this check box if you want to use non-preemptive authentication.
Log Request/Response Time Yes Select this check box to log the time required for sending and receiving the HTTP response in the Send HTTP Request activity.
HTTP Proxy No Specifies the HTTP proxy server to be used to gain access outside of a firewall. The Proxy Configuration shared configuration resource specifies the configuration of the proxy server.

For more information, see the Proxy Configuration.

Circuit Breaker Configuration

Field Literal Value/Module Property Description
Enable Circuit Breaker Yes Select Enable Circuit Breaker to configure properties for Resilience 4j configuration.

The default value is False.

Circuit Breaker Name Yes The specific Resilience4j command.

The circuit breaker name should be unique for each HTTP Connector shared resource.

Circuit Breaker Configuration
Sliding Window Type No

This property configures the type of sliding window which is used to record the outcome of calls when the CircuitBreaker is closed.

Sliding window can either be count-based or time-based.

If the sliding window is COUNT_BASED, the last slidingWindowSize calls are recorded and aggregated.

If the sliding window is TIME_BASED, the calls of the last slidingWindowSize seconds recorded and aggregated.

The default value is COUNT_BASED.
Failure Rate Threshold Yes

This property configures the rate of failure threshold in percentage.

When the rate of failure is equal or greater than the threshold, the CircuitBreaker transitions to open and starts short-circuiting calls.

The default value is 50.

Minimum Number of Calls Yes

This property configures the minimum number of calls which are required (per sliding window period) before the CircuitBreaker can calculate the error rate or slow call rate.

For example, if minimumNumberOfCalls is 10, then at least 10 calls must be recorded, before the failure rate can be calculated.

If only 9 calls have been recorded the CircuitBreaker will not transition to open even if all 9 calls have failed.

The default value is 100.

Permitted Number of Calls in HalfOpen State. Yes

This property configures the number of calls permitted when the CircuitBreaker is half open.

The default value is 10.
Wait Duration in Open State (ms) Yes

The time required for the CircuitBreaker to wait before transitioning from open to half-open.

The default value is 60000 (ms).

Slow Call Rate Threshold Yes This property configures threshold in percentage. The CircuitBreaker considers a call as slow, when the call duration is greater than slowCallDurationThreshold

When the percentage of slow calls is equal or greater than the threshold, the CircuitBreaker transitions to open and starts short-circuiting calls.

The default value is 100.

Slow Call Duration Threshold Yes This property configures the duration of threshold above which calls are considered as slow and increases the rate of slow calls.

The default value is 60000 (ms)

Automatic Transition From Open to HalfOpen Enabled Yes

If this is check box is enabled, the CircuitBreaker will automatically transition from open to half-open state and no call is needed to trigger the transition. A thread is created to monitor all the instances of CircuitBreakers to transition them to HALF_OPEN once waitDurationInOpenState passes.

If the check box is disabled, the transition to HALF_OPEN only happens if a call is made, even after waitDurationInOpenState is passed. The advantage here is no thread monitors the state of all CircuitBreakers.

The default value is false.
Sliding Window Size Yes

This property configures the size of the sliding window which is used to record the outcome of calls when the CircuitBreaker is closed.

The default value is 100.
Max Wait Duration in HalfOpen State (ms) Yes

This property configures a maximum wait duration which controls the longest amount of time a CircuitBreaker could stay in Half Open state, before it switches to open. Value 0 means Circuit Breaker would wait infinitely in HalfOpen State until all permitted calls have been completed.

The default value is 6000 (ms)
Exceptions to record No

This table lists exceptions that record as a failure and thus increase the failure rate. Any exception matching or inheriting from the list is not counted as a failure or if a list of the exceptions is specified, all other exceptions count as a success unless explicitly ignored by ignoreExceptions.

Note: The complete qualified names of the exceptions should be added in the Exceptions to record table. For example, adding ConnectException will not work. You need to add the complete qualified name, java.net.ConnectException
Exceptions to ignore No

This table lists exceptions that are ignored and neither count as a failure or success. Any exception matching or inheriting from the lists is not counted as a failure or success, even if the exceptions are a part of the recordExceptions.

Note: The complete qualified names of the exceptions should be added in the Exceptions to ignore table.For example, adding ConnectException will not work. You need to add the complete qualified name, java.net.ConnectException
Record Failure Predicate No

Using this field you can browse and select a java class that implements the predicate interface.

Note: The application module must be converted to JAVA projects and the predicate class should be created under the src folder.

For example, 

public class CustomPredicate implements Predicate<Throwable> {
 @Override
 public boolean test(Throwable throwable) {
 return !(throwable instanceof java.net.NoRouteToHostException);
 }
}

The above predicate ignores the NoRouteToHostException exception and records other exceptions.

Specific error codes can be recorded or ignored by using the below exception classes:

BWCircuitBreakerClientExceptions and BWCircuitBreakerServerExceptions

Examples of conditions that can be used in predicate class to handle error codes:

BWCircuitBreakerClientExceptions)throwable).getCode() == 4xx

BWCircuitBreakerServerExceptions)throwable).getCode() == 5xx

Security

Security can include any combination of the following characteristics:

Field Literal Value/Module Property Description
Authentication None To be included when the messages must be authenticated. Authentication can be performed with user names and passwords.

Identity Provider : Provides user name and password credentials encapsulated in an identity provider resource. Selecting this check box activates the Identity Provider field.

Note: You can enforce authentication on requests by selecting the Authentication check box, or by associating the Basic Credential Mapping policy with REST or HTTP activities. If you choose to use the policy, ensure the Authentication check box on the HTTP Client resource is not selected.
Oauth Configuration None Selecting this check box enables the OAuth configuration.

OAuth configuration requires additional configurations. For more information about OAuth configuration, see OAuth Configuration Resource.

Kerberos Authentication None

Selecting this check box enables Kerberos Authentication.

Kerberos Authentication requires a few additional configurations. For more information about configurations, see the section "Kerberos Authentication Configuration".

To enforce Kerberos authentication on REST binding, you must select Apache HttpComponents (Supported by HTTP and REST) library.

Note: Kerberos authentication is not supported on Invoke REST API. Use REST Reference Binding or HTTP to invoke a kerberized service.
Username None Enter the Active Directory user name to be used for the Kerberos authentication.

This field is enabled only when the Kerberos Authentication field is selected.

Password None Enter the password for the specified user name.

This field is enabled only when the Kerberos Authentication field is selected. This field is mandatory.

Default Confidentiality Yes Select the check box to encrypt or decrypt messages.

Select the check box to enable the SSL with default configuration.

For more information about SSL Client configuration, see the SSL Client Configuration.

Note: If you select Default Confidentiality, there is no need to create a shared resource. SSL is enabled with Default Configuration. If custom configurations for SSL are required, select Confidentiality. When using Default Confidentiality ensure that the correct root certificates are present at the <TIBCO_HOME>\tibcojre64\1.8.0\lib\security\cacerts trust store.

Confidentiality Yes Select the check box when encrypting or decrypting messages.

When you select a module property for this field and set it to true, or select the check box, the SSL Client Configuration field is visible.

For more information about SSL Client configuration, see the SSL Client Configuration.

JWT Authentication No Select the check box to use the JSON Web Token (JWT) authentication when exposing a REST Reference.

Select the check box to enable the JWT Token field.

For more information about JWT, see JWT.io

By default, the check box is clear.

JWT Token Yes Provide a JWT value.

Kerberos Authentication Configuration

The krb5.conf and login.conf files are present under the config folder at the location, BW Home/config. We recommend that the configurations in the login.conf file should not be changed. However, values in the krb5.conf file can be changed according to the Kerberos environment you are working in.

You can configure the following values in the krb5.conf file:

  • libdefaults
  • realms
  • domain_realm