Event Driven APIs with API Gateway and SOAP over JMS

Knowledge base
, , ,
1

By James, Clench Paign

Supported Versions: 10.1 & above

webMethods API Gateway tutorial

Introduction

This tutorial is prepared to help understanding the below details.

  1. JMS Inbound scenario and the policies associated with it.
  2. JMS Outbound scenario and the policies associated with it.
  3. The configurations required in Integration Server for the JMS policies.

Use case 1 - JMS policy in Inbound

This section explains the usage of JMS Inbound scenario in API Gateway.

838×366 30.3 KB

  • The API Provider creates an API for a SOAP native service in API Gateway and configures the Require JMS policy for that API. This policy would help the API to be exposed over JMS protocol. 
  • A JMS trigger is created in the Integration server and it would be listening for the incoming messages from the Inbound JMS Queue. 
  • The API Consumer creates a JMS message with the request SOAP message and sends the message to the Inbound queue over JMS protocol and starts listening for the reply message from the Reply queue. 
  • When the message reaches the Inbound queue the JMS Trigger reads it and retrieves the SOAP envelop from the message and injects it into the API Gateway API. 
  • The API then invokes the native service with the request SOAP message. 
  • The native service sends the response back to the API and the API creates a JMS message with the response SOAP message and sends the JMS message over to the Reply queue. 
  • When the message reaches the Reply queue the JMS client reads it and retrieves the SOAP response.

1280×768 74.6 KB

Prerequisite configuration in Integration Server

The JMS inbound policy requires certain configurations to be done in the Integration server's administration page prior to its usage.

JNDI Provider Alias

A JNDI Provider Alias has to be created in the Integration server's administration page with the Universal Messaging Server as the JMS provider.

  • Click on Settings → Messaging → JNDISettings and edit the default JNDI alias. DEFAULT_IS_JNDI_PROVIDER and give the below details.
  • JNDI Alias Name  as DEFAULT_IS_JNDI_PROVIDER
  • Description as some text
  • Initial Context Factory as com.pcbsys.nirvana.nSpace.NirvanaContextFactory
  • Provider URL as nsp://localhost:9000
  • Save it and test the JNDI Provider Alias(DEFAULT_IS_JNDI_PROVIDER) by clicking on the Test Lookup icon.

JMS Connection Alias

A JMS Connection Alias has to be created with the respective JNDI Provider Alias. This alias is used to esablish a connection to the JMS server.

  • Click on Settings → Messaging → JMS Settings and edit the default JMS connection alias DEFAULT_IS_JMS_CONNECTION and give the below details.
  • Connection Alias Name as DEFAULT_IS_JMS_CONNECTION
  • Description as some text
  • Under Connection Protocol Settings, Choose Create Connection Using as JNDI LOOKUP
  • Choose the created JNDI Provider Alias Name as DEFAULT_IS_JNDI_PROVIDER
  • Enter the Connection Factory Lookup Name as  UMConnectionFactory
  • Save it and enable the connection by click on the Enabled Column value No to Yes.

879×430 11.1 KB

Web Service Endpoint Alias for JMS Provider

A Web Service Endpoint Alias has to be created for JMS Provider. This is used to create a JMS Trigger in Trigger Management.

  • Click on Settings → Web Services → Create Endpoint Alias and provide the below details.
  • Alias as JMSProviderEndpointAlias
  • Description as some text
  • Choose Type as Provider
  • Choose TransportType as JMS
    • Note: Default enabled Include JNDI Parameters, which will include the JNDI information in the soap address value when WSDL is generated for the deployed virtual service. The full JMS Trigger Name is populated by IS to match the Alias name.
  • Save Changes. A JMS trigger entry is created in the JMS Trigger Management with name as WS Endpoint Trigger: JMSProviderEndpointAlias

JMS Trigger configuration

The JMS trigger would be created with default values. The trigger has to be edited and given proper values for Connection Alias Name and Destination.

  • Click on Settings → Messaging → JMS Trigger Management → 
  • Connection Alias Name as DEFAULT_IS_JMS_CONNECTION and Destination as APIGatewayInboundQ

1142×427 18.2 KB

Enable JMS/AMQP policy

The Enable JMS/AMQP policy should be added to the SOAP API so that the API would be exposed over JMS protocol. This policy takes the below inputs.

SNo Parameter name Description
1 JMS Provider Endpoint Alias This is the Web Service endpoint alias created in the Integration Server for the JMS Provider.
2 SOAP Version SOAP version of the request SOAP message.

Configuration in API Gateway UI

The Enable JMS/AMQP policy is placed under Transport category in Policies tab of the API details page. The user should input values for JMS Provider Endpoint Alias and SOAP Version and save.

1914×993 133 KB

When the API is activated, the API will have an endpoint as a JMS connection URL with the JMS queue name and parameters. Using the values given in the connection URL the API consumer can invoke the API.

1543×176 16.2 KB

API Invocation

API InvocationThe SOAP API with the inbound JMS policy should be invoked by sending a JMS message along with the request SOAP envelope to the JMS queue given in the connection URL by establishing a connection to the JMS server using the connection parameters like jndiConnectionFactoryName, jndiInitialContextFactory and jndiURL. The API can also be invoked using Software AG Designer by invoking the ESB service pub.jmsLsendAndWait under WmPublic package.

Use case 2 - JMS policies in Outbound

This section explains the usage of JMS Outbound scenario in API Gateway.

758×372 20.5 KB

  • The API Provider creates an API in API Gateway for a SOAP over JMS native service and configures it with JMS Routing and an optional JMS Properties policies.
  • The JMS Routing policy would help the API to route the outbound requests over JMS protocol. The JMS Properties policy would help to send some custom JMS properties in the outgoing JMS message. It also helps to override some of the existing JMS headers in the message.
  • After the API is saved and activated, the API Consumer creates a SOAP request and sends it over HTTP protocol to the API using an HTTP client. 
  • When the request reaches the API the API Gateway executes all the mediation policies on the request before routing it to the native service. 
  • While routing the API Gateway creates a JMS message with the outbound request's SOAP envelop and sends it over JMS protocol to the JMS queue. After that it starts listening from the Reply queue for the response message.
  • When the response message is placed in the reply queue the API reads it and extracts the response SOAP message from it and sends it back to the HTTP client.

Prerequisite configuration in Integration Server

The JMS outbound policies require certain configurations to be done in the Integration server's administration page prior to their usage.

Web Service Endpoint Alias for JMS Provider

Along with the JNDI Provider Alias and JMS Connection Alias, a Web Service Endpoint Alias has to be created for JMS Consumer for outbound scenario. This endpoint alias is used by the Integration server to establish a connection to the destination JMS queue for sending JMS message.

  • Click on Settings → Web Services → Create Endpoint Alias and provide the below details.
  • Alias as JMSConsumerEndpointAlias
  • Description as some text
  • Choose Type as Consumer
  • Choose TransportType as JMS
  • Under JMS Transport Properties,
    • Choose Connection Using as JMS Connection Alias
    • Choose JMS Connection Alias as DEFAULT_IS_JMS_CONNECTION
  • Save Changes.

822×347 8.05 KB

JMS/AMQP Routing for SOAP policy

The JMS/AMQP Routing for SOAP policy should be added to the SOAP API so that the API would route the outbound request over JMS protocol to a JMS queue. This policy takes the below inputs.

SNo Parameter name Expected values
1 Connection URL A connection URL for connecting to the JMS provider
2 Reply To Destination A JMS Queue name where a reply to a message should be sent
3 Priority An integer that represents the priority of this JMS message with respect to other messages that are in the same queue. The priority value determines the order in which the messages are routed. Value 0 is the lowest priority and 9 is the highest priority. The messages with this priority value are executed first.
  • Priority values 0 through 9
  • The default priority for a JMS message is 0
4 Time to Live (ms) A numeric value (in milliseconds) that specifies the expiration time of the JMS message. If the time-to-live is specified as zero, expiration is set to zero which indicates the message does not expire. The default value is 0.
5 Delivery Mode The type of message delivery to the endpoint.
Value Description
Non Persistent Default. The message is not stored before delivery.
Persistent The message is stored by the JMS server before delivering it to the client

Connection URL Structure

The connection URL contains various elements that construct the destination and other connection specific parameters. The format is given as below, 
<protocol>:<lookupVariant>:<destination>?<parameters>
Component Description
protocol The transport protocol.
In this feature it is always "jms"
lookupVariant Specifies the destination type, either a "queue" or "topic".
In this feature it is always "queue"
destination The destination name of the JMS Provider.
For dynamic queue it is dynamicQueues/< Queue name >

Parameters

The parameters in the connection URL are used to establish a connection to JMS server for sending the JMS message and pass the API's details like name, action, etc. in the JMS message properties if the native SOAP service is an API in an API Gateway.

The below table contains the predefined parameters.

Parameter Description
wm-wsendpointalias Integration Server's JMS Consumer Endpoint Alias. It is required for Integration Server/API Gateway to look up the JMS consumer alias to send the request to the specified queue.
jndiInitialContextFactory Initial Context Factory for the JNDI look up.
For e.g. org.apache.activemq.jndi.ActiveMQInitialContextFactory for ActiveMQ
jndiConnectionFactoryName Connection Factory Lookup Name.
For e.g. ConnectionFactory for ActiveMQ
jndiURL The JMS Provider's URL to connect to.
For e.g tcp://vmmeddemo03:61616 for ActiveMQ
targetService A Gateway API name.
This parameter is required if the JMS message is destined to another Gateway API that uses JMS as the entry protocol.

Connection URL Examples

With consumer endpoint alias,

jms:queue:dynamicQueues/MyTestQueue?wm-wsendpointalias=JMSConsumerEndpointAlias&targetService=EchoS_VS_JMS_IN
With JNDI lookup parameters,
jms:queue:dynamicQueues/MyTestQueue?jndiConnectionFactoryName=ConnectionFactory&jndiInitialContextFactory=org.apache.activemq.jndi.ActiveMQInitialContextFactory&targetService=EchoS_VS_JMS_IN

Configuration in API Gateway UI

The JMS/AMQP Routing for SOAP policy is placed under Routing category in Policies tab of the API details page.

1919×995 119 KB

JMS/AMQP Properties for SOAP policy

JMS/AMQP Properties for SOAP policy takes properties as inputs to send in the outgoing JMS message. These properties are application specific instead of message and they would be used by the applications or consumers which consume the JMS Message.

Parameters

SNo Parameter name Data Type Expected values Comments
1 jmsProperties List Key value pair

These properties fall into different categories like application specific, runtime jms headers, standard JMS headers and custom properties.


Properties Category Properties Comments
Application specific properties SOAPJMS_requestURI

SOAPJMS_bindingVersion

SOAPJMS_soapAction

SOAPJMS_targetService

SOAPJMS_contentType		 These are specific to the application which consumes the JMS message.
Runtime settings jms.deliveryMode

jms.priority

jms.timeToLive

jms.messageType		 These are actually the JMS headers in different name format. The values in them would override the JMS header values in the outgoing JMS message.
If the jms.messageType has the value "TextMessage", the SOAP envelope in the request would be sent as a text message to the JMS Queue instead of byte stream
Standard JMS headers JMSType

JMSCorrelationID

JMSXGroupID

JMSXGroupSeq		 Other than the mentioned JMS headers the following headers are not allowed. JMSMessageID, JMSExpiration, JMSRedelivered, JMSTimestamp, JMSDeliveryMode, JMSPriority, JMSReplyTo and JMSDestination. If they are added an error response would be sent at runtime.

Configuration in API Gateway UI

The JMS/AMQP Properties for SOAP policy is placed under Routing category in Policies tab of the API details page.

1910×933 108 KB

Sample SOAP over JMS native service setup

This section explains how a native SOAP over JMS service can be set up to test the JMS outbound policies.

The native service is an Axis service running on an Axis engine with JMS transport configured as inbound and outbound protocols.

To run a native service follow the below steps.

  • Download the Axis2 binary distribution from HERE and install it.
  • Open the axis2.xml file in <Axis2_Root>/conf/ directory and add the transportSender and transportReceiver entries for JMS protocol. Under these elements all the JMS server connection related parameters have to be given as below.
<transportReceivername="jms"class="org.apache.axis2.transport.jms.JMSListener"> 
        <parametername="nirvanaQConnectionFactory"locked="false">            
            <parametername="java.naming.factory.initial"locked="false">com.pcbsys.nirvana.nSpace.NirvanaContextFactory</parameter> 
            <parametername="java.naming.provider.url"locked="false">nsp://10.60.34.59:9000/</parameter>     
            <parametername="transport.jms.ConnectionFactoryJNDIName"locked="false">ConnectionFactory</parameter>
            <parametername="transport.jms.ConnectionFactoryType"locked="false">queue</parameter>
        </parameter>
</transportReceiver>
...
<transportSendername="jms"class="org.apache.axis2.transport.jms.JMSSender"> 
        <parametername="nirvanaQConnectionFactory"locked="false">            
            <parametername="java.naming.factory.initial"locked="false">com.pcbsys.nirvana.nSpace.NirvanaContextFactory</parameter> 
            <parametername="java.naming.provider.url"locked="false">nsp://10.60.34.59:9000/</parameter>     
            <parametername="transport.jms.ConnectionFactoryJNDIName"locked="false">ConnectionFactory</parameter> 
            <parametername="transport.jms.ConnectionFactoryType"locked="false">queue</parameter>
        </parameter> 
</transportSender>
  • Save the file.
  • Copy this GreetingService.aar file to <Axis2_Root>/repository/services directory. The services.xml in this service archive would contain JMS specific configuration parameters as below.
<servicename="GreetingService">
    <description>
        This is a sample Web Service with two operations,echo and ping.
    </description>
    <parametername="ServiceClass">userguide.example1.MyService</parameter>   
    <parametername="transport.jms.ConnectionFactory"locked="true">nirvanaQConnectionFactory</parameter>
    <parametername="transport.jms.Destination"locked="true">GreetingServiceInboundQ</parameter>
    <parametername="transport.jms.DestinationType"locked="true">queue</parameter>
    <parametername="transport.jms.ReplyDestination"locked="true">GreetingServiceReplyQ</parameter>
    <operationname="echo">
        <messageReceiverclass="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
        <actionMapping>urn:echo</actionMapping>
    </operation>
    <operationname="ping">
        <messageReceiverclass="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/>
        <actionMapping>urn:ping</actionMapping>
    </operation>
</service>
  • Start the Axis2 server. The GreetingService would be deployed and starts listening for JMS messages from GreetingServiceInboundQ which is present in the Universal Messaging server. The service would send the response message to GreetingServiceReplyQ. 

Limitations

This section lists out the limitations associated with the usages JMS policies.

  • If a SOAP API is configured with JMS inbound policy the external port configuration is not applicable to that API because the API reads the request JMS message from a JMS queue. Hence the Threat protection policies are not supported for that API.
  • The JMS policies cannot be configured at a global level.