URI syntax and parameters for web service deployment

• ¹ The queue manager transforms className to a queue name following the steps described in Destination to queue name transformation
• ² client is the default if other options appropriate for a client are specified; for example clientConnection.
• ³ 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.

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 an IBM 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:

• connectQueueManager(qMgrName)
• binding(bindingType)
• clientChannel(channel)
• clientConnection(connection)
• Required SSL parameters ( Java )

See Connection factory parameters for a description of the values of these parameters.

&targetService = serviceName

¹ On .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 IBM 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

² On 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 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 IBM 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 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 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 an IBM 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 we 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 IBM MQ SOAP transport for SOAP sender.

clientConnection ( connection )

The SOAP client uses connection to make an IBM MQ client connection. The default host name 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

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.

jms:/queue?destination=myQ&connectionFactory=()&initialContextFactory=com.ibm.mq.jms.Nojndi

jms:/queue?destination=myQ&connectionFactory=()&targetService=MyService.asmx
&initialContextFactory=com.ibm.mq.jms.Nojndi

jms:/queue?destination=myQ@myRQM&connectionFactory=connectQueueManager(myconnQM)
binding(client)clientChannel(myChannel)clientConnection(myConnection)
&initialContextFactory=com.ibm.mq.jms.Nojndi

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