webMethods and Intelligent Business Operations 10.2 | API Gateway User's Guide | Policies | System-defined Stages and Policies | Routing | JMS
 
JMS
The Java Message Service (JMS) is a Java API that allows applications to communicate with each other using a common set of interfaces. The JMS API provides messaging interfaces, but not the implementations. A JMS provider, such as Software AG Universal Messaging or webMethods Broker, is a messaging system that supports the JMS message interfaces and provides administrative and control features. It supports the routing and delivery of JMS messages. JMS clients are the programs or components, written in Java, that produce and consume messages.
To configure API Gateway for JMS messaging, you need to:
*Create one or more JNDI provider aliases to specify where API Gateway can look up administered objects when it needs create a connection to JMS provider or specify a destination for sending or receiving messages.
*Create one or more connection aliases that encapsulate the properties that API Gateway needs to create a connection with the JMS provider.
For more information on JMS and how to create JNDI provider aliases, see webMethods Integration Agent Administrator's Guide and Using webMethods Integration Server to Build a Client for JMS.
JMS policy can be used in any of the following scenarios:
*JMS inbound: Use this scenario when a native service accepts requests through HTTP protocol and if you want to accept requests from a JMS provider queue and send the response to another JMS provider queue. You can create an API in API Gateway for the native service (exposed over HTTP) and ensure that API Gateway API listens from a JMS provider queue for incoming requests. The HTTP native service is exposed over JMS through API Gateway using protocol bridging. This scenario helps the API consumer to get asynchronous-messaging and guaranteed-delivery benefits that are available by using JMS as the message transport.
*JMS outbound: Use this scenario when a native service accepts requests using JMS protocol and if you want to accept requests from a HTTP client and send the response over HTTP protocol in API Gateway. You can create an API in API Gateway for the native service (which was exposed over JMS) and ensure that the API Gateway API listens from the HTTP clients for incoming requests. The JMS native service is exposed over HTTP through API Gateway using protocol bridging. This scenario helps the API consumer get the benefits that are available by using HTTP as the request transport.
*JMS inbound and JMS outbound: Use this scenario when a JMS provider queue for which a list of API consumers are subscribed to consume the message and perform their respective business logic based on the available message content. You can also use this scenario wjhen you want to restrict the producers from directly sending the message to the queue or you want to enforce some rules and policies before the message is sent to the queue. Create an API in API Gateway and ensure that the API Gateway API listens from a virtual JMS queue for incoming JMS message. After enforcing this policy, the mediation policies sends that JMS message to the native JMS queue. Once the response is received from the reply queue, API Gateway enforces the mediation policies and sends the response JMS message back to the virtual JMS queue. This scenario helps the API consumer use the API Gateway mediation capabilities such as logging, monitoring, throttling and security on the JMS message that is being sent to the native queue.
The available JMS policies are:
*Require JMS
*JMS Routing
*JMS Properties
To use the JMS Routing and JMS Properties policies, the following prerequisites must be met:
*Create an alias to a JNDI Provider (in the Integration Server Administrator, go to Settings > Web Services).
*To establish an active connection between Integration Server and the JMS provider, you must configure Integration Server to use a JMS connection alias (in the Integration Server Administrator, go to Settings > Messaging > JNDI Settings).
*Create a WS (Web Service) JMS Consumer endpoint alias. In the Integration Server Administrator, navigate to Settings > Web Services > Create Web Service Endpoint Alias and configure the Alias, Description, Type (Consumer), Transport Type (JMS) fields and JMS Transport Properties.
*Additionally, ensure that you delete the predefined Straight Through Routing action from the Routing stage. This is because, these actions are mutually exclusive.
JMS Routing
Note: This policy is applicable only for SOAP APIs.
This action allows you to specify a JMS queue to which the API Gateway submits the request, and the destination to which the API Gateway waits for the native API to return the response.
This policy is used when you have a native API that is exposed over JMS and that requires clients to communicate with the server using the HTTP or JMS protocols. This action allows you to bridge protocols between the client and the native API. When this action is configured for a proxy API, you can route the SOAP message over JMS protocol to the JMS provider. For example, if you have a native API that is exposed over JMS, you can expose the proxy API either over HTTP (JMS outbound) or over JMS (JMS inbound and outbound) protocols.
You can use this policy for any of the following scenarios:
*JMS outbound
*JMS inbound and JMS outbound
The table lists the properties that you can specify for this policy:
Parameter
Description
Connection URL
Provide a connection alias for connecting to the JMS provider (for example, an Integration Server alias or a JNDI URL). The connection URL contains various elements that construct the destination and other connection specific parameters. The structure of the connection URL is: <protocol>:<lookupVariant>:<destination>?<parameters>
Where...
Description
protocol
Specify the name of the transport protocol. The default value is JMS.
lookupVariant
Specify the destination type such as queue or topic. The default value is queue.
destination
Specify the destination name of the JMS Provider. For dynamic queue the destination name is:
dynamicQueues/<Queue name>
Parameters
wm-wsendpointalias
Specify the Integration Server JMS consumer endpoint alias. This parameter is required for Integration Server or API Gateway to look up the JMS consumer alias and send the request to the specified queue.
jndiInitialContextFactory
Specify the initial context factory for the JNDI look up. For example:
org.apache.activemq.jndi.ActiveMQInitialContextFactory for ActiveMQ.
jndiConnectionFactoryName
Specify the connection factory look up name. For example:
ConnectionFactory for ActiveMQ
jndiURL
Specify the JMS Provider's URL to connect to API Gateway. For example:
tcp://vmmeddemo03:61616 for ActiveMQ.
targetService
Specify the API Gateway API name. This parameter is required if you are sending the request to another API in API Gateway that uses JMS as the entry protocol.
Sample: With consumer endpoint alias
jms:queue:dynamicQueues/MyTestQueue?
wm-wsendpointalias=JMSConsumerEndpointAlias&target
Service=EchoS_VS_JMS_IN
Sample: With JNDI lookup parameters
jms:queue:dynamicQueues/MyTestQueue?
jndiConnectionFactoryName=ConnectionFactory
&jndiInitialContextFactory=org.apache.
activemq.jndi.ActiveMQInitialContextFactory
&targetService=EchoS_VS_JMS_IN
Reply To Destination
Specify a queue name where a reply to the message must be sent.
Priority
Type 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. The lowest priority value is 0 and the highest priority value is 9. The messages with this priority value are executed first.
*Priority values 0 through 9.
*The default priority for a JMS message is 0.
Time to Live (ms)
Specify 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.
Delivery Mode
The message delivery mode for the request message. This is the delivery mode that web service clients must specify in the JMS message that serves as the request message for the web service. The available options are:
*Non-persistent. Indicates that the request message is not persistent. The message might be lost if the JMS provider fails.
*Persistent. Indicates that the request message should be persistent. The message is not lost if the JMS provider fails.
JMS Properties
Note: This policy is applicable only for SOAP APIs.
The JMS Properties policy can be configured to set JMS Properties, a few standard JMS Headers, and HTTP Transport Headers in the outgoing JMS message that is being sent from the proxy API to the native API.
JMS headers are part of the JMS message that are used by both clients and providers. They are used to identify a message and to route the message to the applicable JMS Providers or consumers.
You can add HTTP Headers such as API Key, Authorization header, and so on. This is useful when the native API is configured with the Require JMS policy and the proxy API wants to pass the security headers over to that native API.
Every JMS message includes JMS properties that are always passed from provider to client. The purpose of the properties is to convey extra information to the client outside the normal content of the message body. Additionally, JMS property values are set exclusively by the consumer application. When a client receives a message, the properties are in read-only mode. If a client tries to modify any of the properties, a MessageNotWriteableException occurs.
The properties are standard Java name or value pairs. The property names must conform to the message selector syntax specifications defined in the Message interface. Property fields are most often used for message selection and filtering. By using a property field, a message consumer can interrogate the property field and perform message filtering and selection. When this action is configured for a proxy API, API Gateway uses the JMS properties to authenticate client requests before submitting to the native APIs. JMS headers can also be set using properties, however, JMS properties take precedence over headers. For more information on JMS properties and JMS headers, see webMethods Integration Agent Administrator's Guide.
The table lists the properties that you can specify for this policy:
Parameter
Description
JMS Property Key
Specify the JMS property key.
JMS Property Value
Specify the JMS property value.
Predefined JMS Properties
Property Categories
Properties
Comment
Run-time settings
*jms.deliveryMode
*jms.priority
*jms.timeToLive
*jms.messageType
If the jms.messageType is set to TextMessage, the SOAP envelope in the request is sent as a text message to the JMS queue instead of byte stream.
Standard JMS headers
*JMSType
*JMSCorrelationID
*JMSXGroupID
*JMSXGroupSeq
The following headers are not applicable. If they are added an error response would be sent at runtime:
*JMSMessageID
*JMSExpiration
*JMSRedelivered
*JMSTimestamp
*JMSDeliveryMode
*JMSPriority
*JMSReplyTo
*JMSDestination
Application specific properties
*SOAPJMS_requestURI
*SOAPJMS_bindingVersion
*SOAPJMS_soapAction
*SOAPJMS_targetService
*SOAPJMS_contentType
Copyright © 2015- 2018 | Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.
Innovation Release