URI syntax and parameters for Web service deployment

The syntax and parameters to deploy a IBM® WebSphere® MQ Web service are defined in a URI. The deployment utility generates a default URI based on the name of the Web service. You can override the defaults by defining your own URI as a parameter to the deployment utility. The deployment utility incorporates the URI in the generated Web service client stubs.

Purpose

A web service is specified using a Universal Resource Identifier (URI). The syntax diagram specifies the URI that is supported in the IBM WebSphere MQ transport for SOAP. The URI controls over IBM WebSphere MQ-specific SOAP parameters and options used to access target services. The URI is compatible with Web services hosted by .NET, Apache Axis 1, WebSphere Application Server, CICS®.

Description

The URI is incorporated into the Web service client classes generated by the deployment utility. The client passes the URI to IBM WebSphere MQ SOAP Sender in an IBM WebSphere MQ message. The URI controls the processing performed by both the IBM WebSphere MQ SOAP Sender and IBM WebSphere MQ SOAP listener.

Syntax

The URI syntax is as follows: 
jms:/queue?name=value&name=value...
where name is a parameter name and value is an appropriate value, and the name=value element can be repeated any number of times with the second and subsequent occurrences being preceded by an ampersand (&).

Parameter names are case-sensitive, as are names of IBM WebSphere MQ objects. If any parameter is specified more than once, the final occurrence of the parameter takes effect. Client applications can override a generated parameter by appending another copy of the parameter to the URI. If any additional unrecognized parameters are included, they are ignored.

If you store a URI in an XML string, you must represent the ampersand character as &. Similarly, if a URI is coded in a script, take care to escape characters such as & that would otherwise be interpreted by the shell.

Syntax diagram

URI (.NET service)
Read syntax diagramSkip visual syntax diagram -u jms:/queue?destination= SOAPN.className1queue &targetService =serviceNameURI (Common)
URI (Java service)
Read syntax diagramSkip visual syntax diagram -u jms:/queue= SOAPJ.className1destination Default Axis mechanism&targetService=serviceNameURI (Common)
URI (Common)
Read syntax diagramSkip visual syntax diagram&initialContextFactory =com.ibm.mq.jms.Nojndi&connectionFactory = ()Name(value) &persistence=012&priority=0priorityValue&replyDestination=SYSTEM.SOAP.RESPONSE.QUEUEreplyQueue&timeout=inheritedwaitTime&timeToLive=0expiryTime
Name(value)
Read syntax diagramSkip visual syntax diagramconnectQueueManager(?qMgrName)binding(auto2clientserverxaclient3)clientChannel(nullclientChannelName)clientConnection(IPV4AddressIPV6AddressHostname)SSL (.NET)SSL (Java)
Notes:
  • 1 The queue manager transforms className to a queue name following the steps described in Destination to queue name transformation
  • 2 client is the default if other options appropriate for a client are specified; for example clientConnection.
  • 3 xaclient applies to .NET only

Destination to queue name transformation

  1. className is prefixed with SOAPJ. for Java services or with SOAPN. for .NET services.
  2. The file extension is removed from the full path name given in the className parameter.
  3. The resulting string is truncated to no more than 48 characters
  4. Directory separator characters are replaced with period characters.
  5. Embedded spaces are replaced with underscore characters.
  6. The colon following a drive prefix letter is replaced with a period for a .NET service.
Note: In some environments, a queue name generated by the deployment utility might not be unique. The deployment utility makes checks whether to create the queue. You might choose to override the deployment utility by restructuring the deployment directory hierarchy, or by customizing the supplied deployment process.

Required URI parameters

destination=queue
queue is the name of the request destination. It can be a queue or a queue alias. If it is queue alias, the alias can resolve to a topic.
  • If the -u parameter is omitted queue is generated from classname using the steps described in Destination to queue name transformation.
  • If the-u parameter is specified queue is required and must be the first parameter of the URI after the initial jms:/queue? string. Specify either a IBM WebSphere MQ queue name, or a queue name and queue manager name connected by an @ symbol, for example SOAPN.trandemos@WMQSOAP.DEMO.QM.
  • The deployment utility checks whether the queue name, generated or provided, matches the name of an existing queue. The action taken is described in Table 1.
    Table 1. queue validation
    Listener script exists? Listener script exists in the ./generated/server directory Listener script does not exist in the ./generated/server directory
    Queue in listener script matches queue? queue does not match request queue being used in listener script queue matches request queue being used in listener script
    queue exists
    • Deployment exits with an error.
    • The service has already been deployed in ./generated/server, but using a different queue.
    • Deployment continues normally.
    • The service has already been deployed in ./generated/server
    • Deployment exits with an error.
    • The listener startup script is not found in ./generated/server, but queue is in use by a different service or application.
    queue does not exist
    • Deployment continues with a warning.
    • The previous deployment might have failed, because the startup is valid, but queue is missing.
    • Deployment continues normally.
    • No service has been deployed from this directory.
&connectionFactory=Name(value)
Name is one of the following parameters: See Connection factory parameters for a description of the values of these parameters.
&targetService=serviceName
1On .NET, serviceName is the name of a .NET service located in the deployment directory, for example: targetService=myService.asmx. In the .NET environment, the targetService parameter makes it possible for a single WebSphere MQ SOAP listener to be able to process requests for multiple services. These services must be deployed from the same directory.

Optional URI parameters

&initialContextFactory=contextFactory
contextFactory is required and must be set to com.ibm.mq.jms.Nojndi. Make sure Nojndi.jar is in the class path for a WebSphere Application Server Web services client. Nojndi.jar returns Java objects based on the contents of the connectionFactory and destination parameters, rather than by reference to a directory.
&targetService=serviceName
2On Axis, serviceName is the fully qualified name of a Java service, for example: targetService=javaDemos.service.StockQuoteAxis. If targetService is not specified, a service is loaded using the default Axis mechanism.
&persistence=messagePersistence
messagePersistence takes one of the following values:
0
Persistence is inherited from the queue definition.
1
The message is non-persistent.
2
The message is persistent
&priority=priorityValue
priorityValue is in the range 0 - 9. 0 is low priority. The default value is environment-specific, which in the case of IBM WebSphere MQ is 0.
&replyDestination=replyToQueue
The queue at the client side to be used for the response message. The default reply queue is SYSTEM.SOAP.RESPONSE.QUEUE.
  • Run the setupWMQSOAP script to create the default WebSphere MQ SOAP objects.
  • Specify a model queue for replyToQueue to create either a temporary or permanent dynamic response queue. For both temporary and permanent dynamic response queues, a separate instance of dynamic queue is created for each request. If any of the following events happen the queue is deleted:
    • The response arrives and is processed.
    • The request times out.
    • The requesting program terminates.

    For the best performance, use temporary dynamic queues rather than permanent dynamic queues. Do not send a persistent request message to a URI with a temporary dynamic queue. The IBM WebSphere MQ listener SOAP fails to process the message and outputs an error. The client times out waiting for the reply.

  • The setupWMQSOAP script creates a default permanent dynamic model queue called SYSTEM.SOAP.MODEL.RESPONSE.QUEUE.
&timeout=waitTime
The time, in milliseconds, that the client waits for a response message. waitTime overrides values set by the infrastructure or client application. If not specified the application value, if specified, or infrastructure default is inherited.
Note: No relationship is enforced between timeout and timeToLive.
&timeToLive=expiryTime
expiryTime is the time, specified in milliseconds, before the message expires. The default is zero, which indicates an unlimited lifetime.
Note: No relationship is enforced between timeout and timeToLive.

Connection factory parameters

connectQueueManager(qMgrName)
qMgrName specifies the queue manager to which the client connects. The default is blank.
binding(bindingType)
bindingType specifies how the client is connected to qMgrName. The default is auto. bindingType takes the following values:
auto
The sender tries the following connection types, in order:
  1. If other options appropriate to a client connection are specified, the sender uses a client binding. The other options are clientConnection or clientChannel.
  2. Use a server connection.
  3. Use a client connection.
Use binding(auto) in the URI if there is no local queue manager at the SOAP client. A client connection is built for the SOAP client.
client
Use binding(client) in the URI to build a client configuration for the SOAP sender.
server
Use binding(server) in the URI to build a server configuration for the SOAP sender. If the connection has client type parameters the connection fails and an error is displayed by the IBM WebSphere MQ SOAP sender. Client type parameters are clientConnection, clientChannel, or SSL parameters.
xaclient
xaclient is applicable only on .NET and not for Java clients. Use an XA-client connection.
clientChannel(channel)
  • The SOAP client uses channel to make a IBM WebSphere MQ client connection. channel must match the name of a server connection channel, unless channel auto definition is enabled at the server. clientChannel is a required parameter, unless you have provided a Client Connection Definition table (CCDT).
  • Provide a CCDT in Java by setting com.ibm.mq.soap.transport.jms.mqchlurl. In .NET set the MQCHLLIB and MQCHLTAB environment variables; see Use a channel definition table with the WebSphere MQ SOAP transport for SOAP sender.
clientConnection(connection)
The SOAP client uses connection to make a IBM WebSphere MQ client connection. The default hostname is localhost, and default port is 1414. If connection is a TCP/IP address, it takes one of three formats, and can be suffixed with a port number.

JMS clients can either use the format: hostname:port or 'escape' the brackets using the format %X where X is the hexadecimal value that represents the bracket character in the code page of the URI. For example, in ASCII, %28 and %29 for ( and ) respectively.

.Net clients can use the brackets explicitly: hostname(port) or use the 'escaped' format.

IPV4 address
For example, 192.0.2.0.
IPV6 address
For example, 2001:DB8:0:0:0:0:0:0.
Host name
For example, www.example.com%281687%29, www.example.com:1687, or www.example.com(1687).
SSL platform
See Required SSL parameters (Java)

Sample URIs

Note:
  1. & in the URI is encoded as &
  2. All the parameter listed previously are applicable to the clients.
  3. Only destination, connectionFactory and initialContextFactory are applicable to the WCF service.
Figure 1. URI for an Axis service, supplying only required parameters
jms:/queue?destination=myQ&connectionFactory=()&initialContextFactory=com.ibm.mq.jms.Nojndi
Figure 2. URI for a .NET service, supplying only required parameters
jms:/queue?destination=myQ&connectionFactory=()&targetService=MyService.asmx
&initialContextFactory=com.ibm.mq.jms.Nojndi
Figure 3. URI for an Axis service, supplying some optional connectionFactory parameters
jms:/queue?destination=myQ@myRQM&connectionFactory=connectQueueManager(myconnQM)
binding(client)clientChannel(myChannel)clientConnection(myConnection)
&initialContextFactory=com.ibm.mq.jms.Nojndi
Figure 4. URI for an Axis service, supplying the sslPeerName option of the connectionFactory parameter
jms:/queue?destination=myQ@myRQM&connectionFactory=connectQueueManager(myconnQM)
binding(client)clientChannel(myChannel)clientConnection(myConnection)
sslPeerName(CN=MQ Test 1,O=IBM,S=Hampshire,C=GB)
&initialContextFactory=com.ibm.mq.jms.Nojndi
1 .NET service only
2 Java service only