Apache ODE – 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].axis2 file at the root of the process bundle. Currently, this file can only be added on the server, under ode/WEB-INF/processes/$your_process.

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.