Creating an Endpoint Alias for a Provider Web Service Descriptor for Use with JMS

Software AG Products 10.5 | Administering Integration Server | Configuring Endpoint Aliases for Web Services | Creating an Endpoint Alias for a Provider Web Service Descriptor for Use with JMS

If a provider web service descriptor binder specifies the JMS transport, you must assign a web service endpoint alias to the binder. For a web service descriptor that uses SOAP over JMS, the provider web service endpoint alias provides the following information:

JMS message header information for the request message, such as delivery mode, time to live, and the destination for replies. Integration Server uses this information to populate the binding elements in the WSDL generated for the web service descriptor.

The SOAP-JMS trigger that listens for SOAP over JMS messages for the web service descriptor. The SOAP-JMS trigger also provides the JMS connection information needed to create a connection on the JMS provider. Integration Server uses the information provided by the SOAP-JMS trigger to construct most of the JMS URI (the web service descriptor determines the targetService). The JMS URI appears in the WSDL document as the value of the "location=" attribute for the address element within the port element.

WS Security Properties that specify the information needed by the SOAP processor to decrypt and verify the inbound SOAP request and/or encrypt and sign the outbound SOAP response and the details for adding the timestamp information.

Note:
WS-Security credentials such as private keys and public keys do not always need to be provided in a web service endpoint alias. If this information is not provided in the alias, Integration Server can obtain the information from other locations. For more information about usage and resolution order of certificates and keys for WS-Security, see the Web Services Developer’s Guide.

Message addressing properties that provides addressing information relating to the delivery of a message to a web service. This includes the destination address of a message or fault and the authentication credentials required to send a response to a different address than the one from which the request was received.

Keep the following information in mind when creating a web service endpoint alias for a JMS binder in a provider web service descriptor:

You can associate the web service endpoint alias with:

A SOAP-JMS trigger that already exists.

A WS endpoint trigger that you create at the same time you create the endpoint alias.

If you use a SOAP-JMS trigger in the web service endpoint alias and subsequently assign the alias to a JMS binder in a provider web service descriptor, the web service descriptor has a dependency on the SOAP-JMS trigger. Consequently, at start up or when reloading the package containing the web service descriptor, Integration Server must load the SOAP-JMS trigger before loading the web service descriptor. If the SOAP-JMS trigger and web service descriptor are not in the same package, you need to create a package dependency for the package that contains the web service descriptor on the package that contains the SOAP-JMS trigger.

If you rename the SOAP-JMS trigger assigned to an alias, you need to update the alias to use the renamed trigger.

The following properties are optional.

Delivery Mode

Time to Live

Priority

Reply To Name

Reply To Type

If you do not specify values for one of the listed properties (or specify an invalid value), Integration Server will not include information for the property in the WSDL document generated for a provider web service descriptor that uses the web service endpoint alias. The absence of the property from the WSDL document instructs the web service consumer to use the default value for the property as indicated in the Java Message Service standard.

To create a provider web service endpoint alias for use with JMS

1. Open Integration Server Administrator if it is not already open.

2. In the Navigation panel, select Settings > Web Services.

3. Click Create Web Service Endpoint Alias.

4. Under Web Service Endpoint Alias Properties, provide the following information:

In this field	Specify
Alias	A name for the JMS provider web service endpoint alias. The alias name cannot include the following illegal characters: # ©\ & @ ^ ! % * : $ . / \ \ ` ; , ~ + = ) ( \| } { ] [ > < "
Description	A description for the endpoint alias.
Type	Provider
Transport Type	JMS

5. Under JMS Transport Properties, provide the following information:

In this field	Specify
JMS Trigger Name	The name of the SOAP-JMS trigger used to Receive JMS messages. Supply JMS connection properties to any web service descriptors using this web service endpoint alias. If you want to use a WS endpoint trigger, select WS Endpoint Trigger. For more information about WS endpoint triggers, see About WS Endpoint Triggers.
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.
	Select	To
	PERSISTENT	Indicate the request message should be persistent. The message will not be lost if the JMS provider fails.
	NON_PERSISTENT	Indicate the request message is not persistent. The message might be lost if the JMS provider fails.
Time to Live	The number of milliseconds that can elapse before the request message expires on the JMS provider. A value of 0 indicates that the message does not expire.
Priority	Specifies the message priority. The JMS standard defines priority levels from 0 to 9, with 0 as the lowest priority and 9 as the highest.
Reply To Name	Name or lookup name of the destination to which the web service sends a response (reply) message. Specify a name if the JMS connection alias used by the SOAP-JMS trigger connects to the webMethods Broker natively. Specify a lookup name if the JMS connection alias uses JNDI to retrieve a connection factory that is then used to connect to the JMS provider.
Reply To Type	Type of destination to which the web service sends the response (reply) message. Specify the destination type if the following are true: The web service descriptor to which the endpoint alias is assigned use the In-Out message exchange pattern. The JMS connection alias specified by the SOAP-JMS trigger connects to the webMethods Broker natively. On the webMethods Broker, a queue and topic can have the same name. You must specify Reply To Type to indicate to which destination the reply will be sent.
	Select	To
	QUEUE	Indicate that the web service sends the response message to a particular queue.
	TOPIC	Indicate that the web service sends the request message to a particular topic.

6. Under JMS WSDL Options, provide the following information:

Select	To
Include Connection Factory Name	Include the connection factory name in the JMS URI.
Include JNDI Parameters	Include the JNDI parameters in the JMS URI.

Note:
The JMS URI appears in the WSDL document as the location attribute value for the address element contained within the port element.

7. Under WS Security Properties, if the inbound SOAP request must be decrypted and/or the outbound SOAP response must be signed, do the following:

In this field	Specify
Keystore Alias	Alias of the keystore containing the private key used to decrypt the inbound SOAP request or sign the outbound SOAP response. Important: The provider must have already given the consumer the corresponding public key.
Key Alias	Alias of the private key used to decrypt the request or sign the response. The key must be in the keystore specified in Keystore Alias.

8. Under WS Security Properties, if the signing certificate chain of an inbound signed SOAP message has to be verified, specify the following:

In this field	Specify
Truststore Alias	The alias for the truststore that contains the list of CA certificates that Integration Server uses to validate the trust relationship.

9. Under WS Security Properties, configure how Integration Server handles timestamps in the security header.

In this field	Specify
Timestamp Precision	Whether the timestamp is precise to the second or millisecond. If you set the precision to milliseconds, Integration Server uses the timestamp format yyyy-MM-dd'T'HH:mm:ss:SSS'Z'. If you set the precision to seconds, Integration Server uses the timestamp format yyyy-MM-dd'T'HH:mm:ss'Z'. If you do not select a precision value, Integration Server will use the value specified for the watt.server.ws.security.timestampPrecisionInMilliseconds parameter.
Timestamp Time to Live	The time-to-live value for the outbound message in seconds. Integration Server uses the time-to-live value to set the expiry time in the Timestamp element of outbound messages. The Timestamp Time to Live value must be an integer greater than 0. If you do not specify a Timestamp Time to Live value, Integration Server will use the value specified for the watt.server.ws.security.timestampTimeToLive parameter. Note: The Timestamp Time to Live value should be greater than the Time to Live value specified under JMS Transport Properties.
Timestamp Maximum Skew	The maximum number of seconds that the web services client and host clocks can differ and still allow timestamp expiry validation to succeed. Specify a positive integer or zero. Integration Server uses the timestamp maximum skew value only when you implement WS-Security via a WS-Policy. Integration Server validates the inbound SOAP message only when the creation timestamp of the message is less than the sum of the timestamp maximum skew value and the current system clock time. If you do not specify a timestamp maximum skew value, Integration Server will use the value specified for the watt.server.ws.security.timestampMaximumSkew parameter.

10. Under Message Addressing Properties, provide the following addressing information relating to the delivery of the message. The message addressing properties define the addressing information that can be attached to the SOAP message.

In this field	Specify
To	RI of the destination of the SOAP message. In the Reference Parameters field, specify additional parameters, if any, that correspond to <wsa:ReferenceParameters> properties of the endpoint reference to which the message is addressed. Optionally, you can specify metadata (such as WSDL or WS-Policy) about the service in the Metadata Elements field. You can also specify Extensible Elements, which are elements other than those specified as part of the Metadata and Reference Parameters. You can specify more than one reference parameter, metadata element, or extensible element. Click the ‘+’ icon to add more rows and the ‘x’ icon to delete the rows.
Response Map	Address to which the provider will send the reply or fault message and the corresponding message addressing alias. Integration Server retrieves the authentication details needed to send the response from the message addressing alias mapped to the address. In the Address field, specify the URI to which the provider will send the reply or the fault message. From the Message Addressing Alias list, select the Message Addressing endpoint alias from which Integration Server will retrieve the authentication details. Integration Server uses the authentication details to send the response to the ReplyTo or FaultTo endpoints. Click the ‘+’ icon to add more rows and the ‘x’ icon to delete the rows.

11. Click Save Changes.

If you selected WS endpoint trigger for JMS Trigger Name, saving the alias creates the WS endpoint trigger. Before the WS endpoint trigger is usable, you will need to specify a destination and enable it. You can also change the values of some message processing properties. For more information about editing a WS endpoint trigger, see Editing WS Endpoint Triggers.

Note:
If a provider web service endpoint alias for use with JMS specifies a WS endpoint trigger, deleting the alias also deletes the WS endpoint trigger.