Endpoint Configuration

Endpoint configuration property files

SOAP and HTTP external endpoints can be tweaked using some property files. A common set of properties are available to configure external services. At run time, ODE will translate these properties and apply them to Axis2 or HttpClient depending if the targeted service uses SOAP binding or HTTP binding.

Conventions and locations

The extension of these property files must be *.endpoint. These files can be dropped in 2 different locations: the global configuration directory of ODE which is by default ode/WEB-INF/conf. This location might be customized with the system property org.apache.ode.configDir the process deployment directory, ode/WEB-INF/processes/$your_process

Two rules of precedence apply: 1. Endpoint files in a same directory are loaded in alphabetical order. Meaning that if a property is set in two different files, the value from the "greatest" file name will have precedence. 1. Endpoint files located in the global conf directory have precedence over files in process deployment directories.

Version Information

This feature is available in ODE > 1.1. For version 1.1, a file named endpoint-configuration.properties may be dropped in process deployment unit directories. For backward compatibility, ODE > 1.1 supports this file too.

Dynamic refresh

Properties are dynamically loaded and refreshed at run time. The timing is the following: On every request, if the file has not been polled during the last 30 seconds then check the file for updates. If any, reload it.

Consequently, if you have updated properties, you have to wait ~30 seconds and then trigger a request.

Hierarchical properties

The property file is a regular property file except that service name and port name may be used to apply different default values to different services. All properties follow this pattern:

[nsalias.servicename[.portname].ode.]property

If service name is mentioned but port name omitted, the value will apply to all ports of the service. If service name and port name are omitted, the value will apply to all services.

Namespace management

A service has to be qualified. To so do you may define namespace aliases. Aliases will then prefixed the service local name.

alias.ode_ns=http://ode.apache.org

ode_ns.dummyservice.ode.http.request.chunk=true

If your namespace does not collide with the property syntax , you dont have to define an alias. This property file is accepted:

# Next line is commented
# alias.ode_ns=http://ode.apache.org

ode_ns.dummyservice.ode.http.request.chunk=true

Examples

For instance, considering 2 services: the foo-service and the brel-service which has 2 ports: port-of-amsterdam and port-of-hiva-oa

and this property file:

alias.test_ns=http://test.org
http.protocol.max-redirects=5

test_ns.brel-service.ode.http.protocol.max-redirects=40
test_ns.brel-service.port-of-amsterdam.ode.http.protocol.max-redirects=100

The http.protocol.max-redirect property will have the following values:

  • 5 for all ports of foo-service
  • 40 for brel-service.port-of-hiva-oa
  • 100 for brel-service.port-of-amsterdam

Supported properties

Here the list of supported properties, and their descriptions. If the file contains some properties not listed here, they will be available in the property map nevertheless. Values will be strings. Such unmanaged properties will also be passed to Axis2 options and HttpClient params, see below.

Context Property name Accepted values Description/Notes
BPEL-runtime mex.timeout a long the ODE Message Exchange timeout
mex.failure.verbose true(default)/false mute the details of a failure that might occur during a process invocation (to avoid information disclosure for instance)
Outbound Services address a URL overrides the soap:address or http:address.
The order of precedence is: process, property files, wsdl.
http.request.chunk true/false This will enable/disable chunking support. Will not apply to http-bound services TBD
http.protocol.version HTTP/1.1 or HTTP/1.0 the HTTP protocol version used
http.request.gzip true/false Will not apply to http-bound services TBD
http.accept.gzip true/false Append gzip to the Accept-Encoding header
http.protocol.content-charset a string
http.default-headers.{your-header} You must define one property per header, prefixed with 'http.default-headers'.
These values will be appended to any previous value already set for a given header.
http.connection.timeout an int timeout in milliseconds until a connection is etablished
http.socket.timeout an int timeout in milliseconds for waiting for data
http.protocol.max-redirects an int the maximum number of redirects to be followed
http.proxy.host=myproxy.org To disable proxy set the host to null
http.proxy.port
http.proxy.domain
http.proxy.user
http.proxy.password
jms.reply.destination a string the reply-to destination in an outbound message
jms.reply.timeout an int timeout in milliseconds for waiting for two-way reply
ws-adddressing.headers true(default)/false Enable/disable the WS-Addressing headers for outgoing soap requests

Sample file

sample.endpoint.txt

Download, remove the '.txt' prefix, customize then enjoy...

Implementation Details for Outbound services

The properties related to Outbound services have to be applied to Axis2 (for SOAP services) or HttpClient (for HTTP services). Tables below sum up this information.

SOAP Services (Axis2)

For Axis2, all properties are converted to meet the Options#setProperty() requirements.

Property name Axis2 Description/Notes
http.request.chunk Options.setProperty(HTTPConstants.CHUNKED, ?)
http.protocol.version Options.setProperty(HTTPConstants.HTTP_PROTOCOL_VERSION, ?)
http.request.gzip Options.setProperty(HTTPConstants.MC_GZIP_REQUEST, ?)
http.accept.gzip Options.setProperty(HTTPConstants.MC_ACCEPT_GZIP, ?)
http.protocol.content-charset Options.setProperty(Constants.Configuration.CHARACTER_SET_ENCODING,?)
http.default-headers.* Options.setProperty(HTTPConstants.HTTP_HEADERS, ?)
http.connection.timeout Options.setProperty(HTTPConstants.CONNECTION_TIMEOUT, ?)
http.socket.timeout Options.setProperty(HTTPConstants.SO_TIMEOUT, ?)
http.protocol.max-redirects not applied to Axis2 service
http.proxy.* Options.setProperty(HTTPConstants.PROXY, ?)
jms.reply.destination Options.setProperty(JMSConstants.REPLY_PARAM, ?)
jms.reply.timeout Options.setProperty(JMSConstants.JMS_WAIT_REPLY, ?)

HTTP Services (HttpClient)

For HttpClient, all properties are defined by: HttpMethodParams , HostParams, HttpClientParams, HttpConnectionParams and HttpConnectionManagerParams. The idea is to convert properties into the expected type and push them in a DefaultHttpParams . This property holder is then set as the parent of all other HttpParams used. If a given property is not listed below, you are still able to set it as long as the expected value is a string. For instance "http.protocol.cookie-policy" can be set seamlessly.

Property name HttpClient Description/Notes
http.request.chunk EntityEnclosingMethod.setContentChunked()
http.protocol.version HttpParams.setParameter(HttpMethodParams.PROTOCOL_VERSION, ?)
http.request.gzip not supported
http.accept.gzip not supported
http.protocol.content-charset HttpParams.setParameter(HttpMethodParams.HTTP_CONTENT_CHARSET,?)
http.default-headers.* HttpParams.setParameter(HTTPConstants.HTTP_HEADERS, ?)
http.connection.timeout HttpParams.setParameter(HttpConnectionParams.CONNECTION_TIMEOUT, ?)
http.socket.timeout HttpParams.setParameter(HttpMethodParams.SO_TIMEOUT, ?)
http.protocol.max-redirects HttpParams.setParameter(HttpClientParams.MAX_REDIRECTS, ?)
http.proxy.* Cannot be set with simple properties. Custom code added.

Additional Configuration for SOAP Endpoints

If you deploy ODE in an application server, the Axis2 Integration Layer allows ODE to communicate via Web Service interactions. SOAP Web Services will be managed by Axis2. These web services may be configured dynamically. For each service, you need to place a \[serviceLocalName\](servicelocalname\.html).axis2 file at the root of the process bundle. Currently, this file can only be added on the server, under var/processes/\{$process_dir\}.

For example, given this wsdl:

<?xml version="1.0" encoding="utf-8"?>
<wsdl:definitions ...>
  <wsdl:documentation xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">A sample Time service</wsdl:documentation>
 ...
  <wsdl:service name="TimeService">
    <wsdl:port name="TimeServiceSoap" binding="tns:TimeServiceSoap">
      <soap:address location="http://ws.intalio.com/TimeService/" />
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

You would place a TimeService.axis2 file with:

<service name="TimeService" scope="application" targetNamespace="http://ws.intalio.com/TimeService/">
    <module ref="sandesha2" />
    <module ref="addressing" />
</service>

This will engage Engage sandesha2 and addressing modules.

On every request, if the config file has not been polled during the last 30 seconds then check the file for changes and (re)load it if any.

For further details about the type of parameters that can be set, see Axis2 Service Config.

This mechanism is available for external SOAP services -- i.e. services that processes invoke -- and for SOAP services exposed by ODE -- i.e. services exposed by BPEL processes.

The service.xml could be quite powerful. However all options are not accessible this way. Many settings are available programmatically only using the Options class.. ODE exposes these settings through an additional property file described in the previous section.