Proxy Service Fragment

This section discusses how to configure a proxy service in the UltraESB using the IDE of your interest. This section doesn’t cover the internal behaviour of the proxy services, the proxy service internal action and the architecture of the proxy services are discussed in the Proxy Services[Proxy Services] under the Architecture and Design of the UltraESB. To understand how proxy services fits into the UltraESB please follow the Overall architecture of the UltraESB.

Proxy Service

Proxy Service is the one and only entry point for the external messages coming into the UltraESB. The concept of proxy service has been designed to make it easy to configure entry points to any integration solution. The unified model of entry points with proxy services enables the configuration to be easily readable and manageable.

Proxy services are configured as XML fragments in the ultra-unit.xml file of a deployment unit which resides in the ULTRA_HOME/conf/deployments directory. A proxy service configuration has been defined by the UltraESB schema and is having the local element name "proxy" qualified with the UltraESB namespace, which is "http://www.adroitlogic.org/ultraesb".

Proxy services define the transports on which the entry point described by it is exposed, in other words transports on which the proxy service can receive messages. In general proxy services are transport configuration agnostic, except for the name of the transports on which it is deployed. However it can provide information about the entry point to the transport via properties for the transport to expose those entry points properly.

Development of Proxy Services

In order to develop proxy services open the UltraRuntime project shipped with the UltraESB in the installation home directory. Follow the instructions on Setting up the IDE to make sure that the IDE is aware of the schema and to configure the project correctly.

Once the project is loaded, expand the project structure, conf directory and the deployments directory. Create a directory name "hello-world" there to represent a deployment unit and add a file named  ultra-unit.xml to that folder.

ultra unit

Now place the following code fragment which is the wrapping element for a deployment unit configuration which also is a spring configuration.

Bare deployment unit configuration

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:u="http://www.adroitlogic.org/ultraesb"
       xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.2.xsd
http://www.adroitlogic.org/ultraesb http://schemas.adroitlogic.org/ultraesb/v2_6/ultraesb-artifacts.xsd">

<!-- Add your proxy service configurations here -->

</beans>

Adding a proxy service to the UltraESB is just a matter of adding a proxy element to this configuration file, which creates an entry point for the external messages.

Creating a bare Proxy Service

Since we have already configured the IDE to be UltraESB namespace aware, which qualifies the proxy element, the IDE will give the context sensitive element pallet for us to create the XML configuration for a proxy service. Type the XML starting element tag to see the context menu with the possible options, where you can find the proxy element as follows;

context sensitive editing

Move the down cursor to select the proxy element and hit enter to add it to the configuration file. This will result in a bare proxy configuration to be created with a blank "id" attribute and a "target" element, both of which are mandatory for a proxy service as follows.

Starting proxy service confiuration

<u:proxy id="">
  <u:target></u:target>
</u:proxy>

Specify the proxy service identifier, which can be any string without spaces or other special characters in XML. Lets use the identifier "MyFirstProxy" for the proxy service that we have just created. Giving it an identifier completes the bare proxy service creation. Even though the entry point is there (and UltraESB instance can start with this bare proxy configuration), it doesn’t define any action for the messages coming in via this entry point, or any transports for the entry point to be exposed and hence this proxy service is still not practically usable.

Completing this proxy service to define an integration solution requires the endpoint and sequence wiring to this proxy service, which is done by associating them to the target element. While configuration of endpoints and sequences are discussed in detail under the next two sections on Endpoint/Destination Configuration and Sequence and Mediation Development, the following sub section on Target Configuration walks through the association of the endpoints and sequences to the proxy service and how it is configured.

The other factor for exposing this proxy service is the configuration of the transports on which it is exposed, which will be discussed in the below sub section under Transport Configuration.

Target Configuration

Target configuration is a mandatory element for a proxy service, and hence the IDE will automatically add the element with the tag name "target" with the UltraESB namespace under the proxy element as seen in the above section. One and only one target configuration per proxy service is allowed since it defines all the targets of the proxy service, if you add another target element, the IDE will highlight it giving an error that the child element configurations are wrong.

Target defines the following sub configurations for the proxy service.

  1. In Sequence - defines the mediation for the incoming message to the proxy service

  2. In Destination - defines the destination to deliver the incoming message after the mediation defined by in sequence

  3. Out Sequence - defines the mediation for the out going (response) message

  4. Out Destination - defines the destination for the response message going out from the proxy service

  5. Error Sequence - defines the mediation for any error conditions while processing the message

All of these can either be in-lined or referred from the target configuration of the proxy service.

If you insert a space inside the starting tag of of the target element trying to define an attribute for the target element the IDE will pops-up the following options which are the attribute names that you can use in referring to a sequence or an endpoint already defined in the UltraESB configuration.

target referred

On the other hand if you try to insert a new element into the target element with typing the "<" angular bracket to start an element within the start and closing tags of the target element, the IDE again pops-up the possible elements that can come inside the target element as follows, which are going to either have an in-lined sequence of endpoint as there immediate child elements.

target inline

While these IDE pop-ups helps you to add these elements or attributes without spelling mistakes etc, it is vice to have a clear understanding of the configurations behind all thee.

Mix and match the in-lined and referred content
You can mix referred and in-lined content in defining the target configuration, for example, you can refer to an in sequence defined in the UltraESB while specifying the in destination in-line in the proxy service, you should be careful to not to add the same configuration both as an in-lined element as well as an referred attribute.
In Sequence

In sequence defines the mediation sequence for the incoming messages to the associated proxy service. It can either be referred or specified in-line in the target element. If it is referred the sequence has to be defined in the UltraESB configuration, or if it is in-lined it has to be defined within the in sequence element, as one of the sequence types described in the Sequence and Mediation Development.

To configure a referred in sequence the configuration should be as follows.

Referred in sequence for proxy

<u:proxy id="MyFirstProxy">
  <u:target inSequence="MyInSequence"/>
</u:proxy>

Here the referred sequence has to be defined in the ultra-dynamic.xml or in the ultra-custom.xml as a sequence with the identifier "MyInSequence".

To configure an in-lined in sequence for the proxy target element, the configuration should be as follows.

In-line in sequence for proxy

<u:proxy id="MyFirstProxy">
  <u:target>
    <u:inSequence>
      <!-- Sequence definition -->
    </u:inSequence>
  </u:target>
</u:proxy>

Here the inSequence element should define the mediation sequence with one of the sequence type configurations described on Sequence and Mediation Development. Note that in the in-lined in sequence configuration the element tag name "sequence" has been replaced with the tag name "inSequence".

In Destination

In destination defines the destination for the incoming messages going out via the associated proxy service, after mediated with the in sequence. It can either be referred or specified in-line in the target element. If it is referred the endpoint has to be defined in the UltraESB configuration, or if it is in-lined it has to be defined within the in destination element, as one of the endpoint types described in the Endpoint or Destination Configuration.

To configure a referred in destination the configuration should be as follows.

Referred in destination for proxy

<u:proxy id="MyFirstProxy">
  <u:target inDestination="MyInDestination"/>
</u:proxy>

Here the referred endpoint has to be defined in the ultra-dynamic.xml or in the ultra-custom.xml as an endpoint with the identifier "MyInDestination".

To configure an in-lined in destination for the proxy target element, the configuration should be as follows.

In-line in destination for proxy

<u:proxy id="MyFirstProxy">
  <u:target>
    <u:inDestination>
      <!-- Endpoint definition -->
    </u:inDestination>
  </u:target>
</u:proxy>

Here the inDestination element should define the endpoint with one of the endpoint type configurations described on Endpoint or Destination Configuration. Note that in the in-lined in destination configuration the element tag name "endpoint" has been replaced with the tag name "inDestination".

Out Sequence

Out sequence defines the mediation sequence for the outgoing response messages from the associated proxy service. It can either be referred or specified in-line in the target element. If it is referred the sequence has to be defined in the UltraESB configuration, or if it is in-lined it has to be defined within the out sequence element, as one of the sequence types described in the Sequence and Mediation Development.

To configure a referred out sequence the configuration should be as follows.

Referred out sequence for proxy

<u:proxy id="MyFirstProxy">
  <u:target outSequence="MyOutSequence"/>
</u:proxy>

Here the referred sequence has to be defined in the ultra-dynamic.xml or in the ultra-custom.xml as a sequence with the identifier "MyOutSequence".

To configure an in-lined out sequence for the proxy target element, the configuration should be as follows.

In-line out sequence for proxy

<u:proxy id="MyFirstProxy">
  <u:target>
    <u:outSequence>
      <!-- Sequence definition -->
    </u:outSequence>
  </u:target>
</u:proxy>

Here the outSequence element should define the mediation sequence with one of the sequence type configurations described on Sequence and Mediation Development. Note that in the in-lined out sequence configuration the element tag name "sequence" is replaced with the tag name "outSequence".

Out Destination

Out destination defines the destination for the outgoing response messages going out via the associated proxy service, after mediated with the out sequence. It can either be referred or specified in-line in the target element. If it is referred the endpoint has to be defined in the UltraESB configuration, or if it is in-lined it has to be defined within the out destination element, as one of the endpoint types described in the Endpoint or Destination Configuration.

To configure a referred out destination the configuration should be as follows.

Referred out destination for proxy

<u:proxy id="MyFirstProxy">
  <u:target outDestination="MyOutDestination"/>
</u:proxy>

Here the referred endpoint has to be defined in the ultra-dynamic.xml or in the ultra-custom.xml as an endpoint with the identifier "MyOutDestination".

To configure an in-lined out destination for the proxy target element, the configuration should be as follows.

In-line out destination for proxy

<u:proxy id="MyFirstProxy">
  <u:target>
    <u:outDestination>
      <!-- Endpoint definition -->
    </u:outDestination>
  </u:target>
</u:proxy>

Here the outDestination element should define the endpoint with one of the endpoint type configurations described on Endpoint or Destination Configuration. Note that in the in-lined out destination configuration the element tag name "endpoint" is replaced with the tag name "outDestination".

Error Sequence

Error sequence defines the mediation sequence for the messages that faces an error condition while processing in the associated proxy service. It can either be referred or specified in-line in the target element. If it is referred the sequence has to be defined in the UltraESB configuration, or if it is in-lined it has to be defined within the error sequence element, as one of the sequence types described in the Sequence and Mediation Development.

To configure a referred error sequence the configuration should be as follows.

Referred error sequence for proxy

<u:proxy id="MyFirstProxy">
  <u:target errorSequence="MyErrorSequence"/>
</u:proxy>

Here the referred sequence has to be defined in the ultra-dynamic.xml or in the ultra-custom.xml as a sequence with the identifier "MyErrorSequence".

To configure an in-lined error sequence for the proxy target element, the configuration should be as follows.

In-line error sequence for proxy

<u:proxy id="MyFirstProxy">
  <u:target>
    <u:errorSequence>
      <!-- Sequence definition -->
    </u:errorSequence>
  </u:target>
</u:proxy>

Here the errorSequence element should define the mediation sequence with one of the sequence type configurations described on Sequence and Mediation Development. Note that in the in-lined error sequence configuration the element tag name "sequence" is replaced with the tag name "errorSequence".

Referred sequences/endpoitns enables reusability
Note that, while the sequences and endpoints defined in-line in a proxy service target are not reusable in another proxy service, the referred sequences and endpoints allows the same reference to be used for another proxy service as either in, out, error sequence or in, out destination.
Transport Configuration

For any proxy service to be reachable over a given transport, the proxy configuration should define the transport on which it is exposed. Optionally any configuration properties associated with that transport for registering the service should be passed in as transport configuration properties in the proxy service.

The transport configuration of a proxy service is specified with element tag named "transport" again qualified with the UltraESB namespace. Unlike in the case of the target element, this transport element can/should repeat for each and every transport on which this service is exposed. In other words, the configuration should have exactly the same number of transport elements defining the transports on which this proxy service is exposed. The configuration should specify the transport identifier, in the "id" attribute of the transport element.

Transport identifier
UltraESB transports are defined in the ultra-root.xml file again found on the same folder as the ultra-dynamic.xml file, which is the conf directory. Open the ultra-root.xml and find the spring bean identifier of the transport listener that you want to configure the proxy service, for example the default spring bean id for the HTTP transport is, "http-8280". See more information on transport configuration under the Configuration and Administration.

Define the transports over which the proxy service is exposed, as shown in the following example;

Transport configuration for proxy

<u:proxy id="MyFirstProxy">
  <u:transport id="http-8280"/>
  <u:target></u:target>
</u:proxy>

Certain transports have transport specific configurations to be done at the proxy service level and those are specified as transport properties in the configuration with the element tag name "property" within the transport element. Information on different transport properties could be found in the Transport configuration properties reference guide.

Advance Proxy Service Configurations

While the bare proxy configuration is pretty easy and straight forward, it’s flexibility to define advance properties or qualities of the entry point are very convenient in a practical integration solutions. There are many advance configurations including the service properties, pinned servers and work manager configuration etc..

Pinned Servers Configuration

Pinned servers is a concept where you can limit the operation of a particular proxy service into a given node or a set of nodes in a clustered deployment of the UltraESB, when sharing the same configuration. The concept found to be very convenient when exposing the proxy service on polling transports (file transport and email transport, etc..) in a clustered deployment, to make sure the same message (file or email) is not tried to be pulled by different nodes in the cluster.

Once configured to be pinned (which is an optional configuration) the proxy service will look at the node identifier (passed in as serverName for the startup script) and check whether it matches an entry in the pinned servers list before starting the proxy. If not the proxy service will not be operational on that node of the cluster.

To configure pinned servers for a proxy service add the attribute "pinnedServers" to the proxy element defining the proxy service and specify the node identifiers (server names) in the cluster, on which this service needs to be exposed.

Pinning the proxy for transports

<u:proxy id="MyFirstProxy" pinnedServers="esb1, esb2">
  <u:transport id="http-8280"/>
  <u:target></u:target>
</u:proxy>

The above configuration limits the proxy service to be only operational in nodes identified as esb1 and esb2.

Note
A cluster in this case has the identical configuration, even though some proxy services are pinned to certain nodes and those proxy services are not operational on the other nodes in the cluster, in other wards are pinned to the given nodes only.

In case of a failure of a node with pinned server if any backup node is specified for that node, it will automatically take over the failed node and start acting as that node, after a configurable grace period. Upon seeing the original failed node joining back into the cluster the failover node stops acting as the failed node and stops acting as that node. Follow the Clustering Configuration on the Configuration and Administration for more information on failover node configuration.

Pinned server concept on non-clustered setup
You could use the pinned servers on a non clustered deployment too, in which case the above automatic failover node will not be effective. However, UTerm provides a terminal command to manually start/stop acting as a given node identifier, which is operational on clustered as well as on non-clustered deployments.

Pinned servers is an advance configuration for proxy services which helps you define the maximum number of operational proxy services instance in the cluster regardless of the number of nodes in the cluster. For example, in the previous configuration, it is guaranteed that only 2 operational proxy service instances of MyFirstProxy is there on the complete cluster.

Pinned Server Groups Configuration

Pinned Server Groups concept comes with the concept of newly introduced ServerGroups concept where set of UltraESB servers can be defined as a server group. So we can used pinned server group concept, similar to pinned servers concept.

<u:proxy id="MyFirstProxy" pinnedServerGroups="esbGroup1">
  <u:transport id="http-8280"/>
  <u:target></u:target>
</u:proxy>
Work Manager Configuration

Work manager is a concept derived from the Java thread pool executors, where you can have two thread pools named primary and secondary, with work being overflowed to the secondary when the primary pool gets exhausted. You may go through the Static Configurations of the UltraESB under the overall architecture to understand the concepts of a work manager in detail.

Work Managers are defined in the ultra-root.xml spring configuration located on the same directory as the ultra-dynamic.xml file. The configuration of the work manager for a proxy service is optional and if specified, makes sure that the proxy service is always using the named work manger to submit messages for processing, which defaults (if no work manager is specified in the proxy service) to the work manager identified with the "default" key.

To configure a work manager, use the "workManager" attribute of the proxy element to specify the work manager identifier.

Custom work manger for proxy

<u:proxy id="MyFirstProxy" workManager="myCustomWM">
  <u:transport id="http-8280"/>
  <u:target></u:target>
</u:proxy>

Here the "myCustomWM" is the identifier of the spring bean defining a work manger in the ultra-root.xml root configuration of the UltraESB.

In this topic
In this topic
Contact Us