+

Search Tips | Advanced Search

W3C SOAP over JMS URI for the IBM MQ Axis 2 client

Define a W3C SOAP over JMS URI to call a web service from an Axis 2 client using IBM MQ JMS as the SOAP transport. The web service must be provided by a server that supports IBM MQ JMS and the W3C SOAP over JMS candidate recommendation for the SOAP/JMS binding.


Description

The W3C candidate recommendation defines the SOAP over JMS binding; SOAP over Java Message Service 1.0. Also useful for its examples is URI Scheme for Java(tm) Message Service 1.01.

Use the syntax diagram to create W3C SOAP over JMS URIs that are syntactically correct, and are accepted by the IBM MQ Axis 2 client. It is limited to defining the URI that is accepted by the IBM MQ Axis 2 client. It is a subset of the W3C recommendation in two respects:
  1. The jms-variant topic is not supported, and must not be specified in a URI passed to the IBM MQ Axis 2 client.
  2. The following properties are omitted from the syntax diagram because they are JMS properties, and not part of the URI.
    1. bindingVersion
    2. contentType
    3. soapAction
    4. requestURI
    5. isFault
The JMS properties are set by the Axis 2 client or the server.

The diagram extends the W3C recommendation by defining a custom parameter, connectionFactory. connectionFactory is used as an alternative to JNDI to specify how the Axis 2 client connects to a queue manager using a queue.

The IBM MQ Axis 2 client only accepts properties as part of the URI passed to the client by the client application or as environment variables. The IBM MQ Axis 2 client has no capability to process a WSDL document. The client application or a development tool might process the WSDL and create the URI to pass to the Axis 2 client. An IBM MQ Axis 2 client application cannot set the JMS message properties directly.


Syntax

In accordance with the W3C recommendation, all the parameters can be obtained from environment variables. The environment variable names are formed by prefacing the parameter name with soapjms_. The syntax is: soapjms_parameterName ; for example, 
set soapjms_targetServer=com.example.org.stockquote
If a parameter is set using an environment variable it overrides the value set in the URI.

In accordance with the W3C recommendation, all the parameters can be repeated. The last instance of a parameter is used, unless overridden by an environment variable.

jms-uri

jms: queue:queueName?&Other propertiesConnection factory property
  • jndi:destinationName?&JNDI properties
  • &Other properties
  • Other propertiestargetService=Server specific defaultserviceName
  • deliveryMode=PERSISTENTNON_PERSISTENT
  • timeToLive=0milliseconds
  • priority=41...9
  • replyToName=SYSTEM.SOAP.RESPONSE.QUEUEreplyToDestination
  • CustomParameter=customParameterValue
  • JNDI properties1jndiConnectionFactoryName=connectionFactoryName
  • jndiInitialContextFactory=contextFactoryName
  • jndiURL=providerURL
  • jndi-ContextParameter=contextParameterValue
  • Connection factory propertyconnectionFactory=()
  • connectionFactory=connectQueueManager(?qMgrName
  • )
  • BindingSSL property
  • Bindingbinding (auto)Client binding property
  • (client)Client binding property
  • (server)
  • Client binding propertyclientChannel(channel)clientConnection(localhosthostnameIPv4 addressIPv6 address
  • (1414port number
  • )
  • )
  • SSL propertysslCipherSuite(cipherSuite)sslPeerName(peerName)
  • sslKeyStore(KeyStoreName)
  • sslKeyStorePassword(KeyStorePassword)
  • sslTrustStore(TrustStoreName)
  • sslTrustPassword(TrustStorePassword)
  • sslKeyResetCount(byteCount)
  • sslFipsRequired(fipsCertified)
  • sslLDAPCRLServers(LDAPServerList)
  • Notes:

    • 1 jndiConnectionFactoryName, jndiConnectionFactoryName and jndiURL are all required parameters. jndi- ContextParameter is optional.


    Parameters

      connectionFactory = connectionFactoryParameterList

      • connectionFactoryParameterList are parameters that qualify how the Axis 2 client connects to a queue manager when the destination variant is queue.
      • connectionFactory must not be specified with the jndi destination variant.
      • The parameters are not passed to the server in the request URI.
      • If connectionFactory is omitted, the queue must belong to a default queue manager running on the same server as the Axis 2 client.
      • The connectionFactoryParameterList:

        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).

        sslCipherSuite (CipherSuite)
        CipherSuite specifies the sslCipherSuite used on the channel. The CipherSuite specified by the client must match the CipherSuite specified on the server connection channel.
        sslFipsRequired (fipsCertified)
        fipsCertified specifies whether CipherSpec or CipherSuite must use FIPS-certified cryptography in IBM MQ on the channel. The effect of setting fipsCertified is the same as setting the FipsRequired field of the MQSCO structure on an MQCONNX call.
        sslKeyStore (KeyStoreName)
        KeyStoreName specifies the sslKeyStoreName used on the channel. The keystore holds the private key of the client used to authenticate the client to the server. The keystore is optional if the TLS connection is configured to accept anonymous client connections.
        sslKeyResetCount (bytecount)
        bytecount specifies the number of bytes passed across a TLS channel before the TLS secret key must be renegotiated. To disable the renegotiation of TLS keys omit the field or set it to zero. Zero is the only value supported in some environments, see Renegotiating the secret key in IBM MQ classes for Java . The effect of setting sslKeyResetCount is the same as setting the KeyResetCount field in the MQSCO structure on an MQCONNX call.
        sslKeyStorePassword (KeyStorePassword)
        KeyStorePassword specifies the sslKeyStorePassword used on the channel.
        sslLDAPCRLServers (LDAPServerList)

        LDAPServerList specifies a list of LDAP servers to be used for Certificate Revocation List checking.

        For TLS enabled client connections, LDAPServerList is a list of LDAP servers to be used for Certificate Revocation List (CRL) checking. The certificate provided by the queue manager is checked against one of the listed LDAP CRL servers; if found, the connection fails. Each LDAP server is tried in turn until connectivity is established to one of them. If it is impossible to connect to any of the servers, the certificate is rejected. Once a connection has been successfully established to one of them, the certificate is accepted or rejected depending on the CRLs present on that LDAP server.

        If LDAPServerList is blank, the certificate belonging to the queue manager is not checked against a Certificate Revocation List. An error message is displayed if the supplied list of LDAP URIs is not valid. The effect of setting this field is the same as that of including MQAIR records and accessing them from an MQSCO structure on an MQCONNX.

        sslPeerName (peerName)
        peerName specifies the sslPeerName used on the channel.
        sslTrustStore (TrustStoreName)
        TrustStoreName specifies the sslTrustStoreName used on the channel. The truststore holds the public certificate of the server, or its key chain, to authenticate the server to the client. The truststore is optional if the root certificate of a certificate authority is used to authenticate the server. In Java, root certificates are held in the JRE certificate store, cacerts.
        sslTrustStorePassword (TrustStorePassword)
        TrustStorePassword specifies the sslTrustStorePassword used on the channel.

      CustomParameter = customParameterValue

      • CustomParameter is the user-defined name of a custom parameter, and customParameterValue is the value of the parameter.
      • Custom parameters that are not used by the Axis 2 client are sent by the Axis 2 client to the SOAP server. Consult the server documentation. connectionFactory is a custom parameter that is used by the Axis 2 client and is not passed to the server.
      • CustomParameter must not match the name of an existing parameter.
      • If CustomParameter starts with the string jndi- it is used in looking up a JNDI destination; see jndi-.
      deliveryMode = deliveryMode
      deliveryMode sets the message persistence. The default is PERSISTENT.
      jndi : destinationName
      destinationName is a JNDI destination name that maps to a JMS queue. If the jndi destination variant is specified, you must provide a destinationName.
      jndiConnectionFactoryName = connectionFactoryName
      connectionFactoryName sets the JNDI name of the connection factory. If the destination variant is jndi, connectionFactoryName must be provided.
      jndiInitialContextFactory = contextFactoryName
      contextFactoryName sets the JNDI name of the initial context factory. If the destination variant is jndi, contextFactoryName must be provided. See Use JNDI to retrieve administered objects in a JMS application.
      jndiURL = providerURL
      jndiURL sets the URL name of the JNDI provider. If the destination variant is jndi, jndiURL must be specified.
      jndi- ContextParameter = contextParameterValue
      jndi- ContextParameter is the user-defined name of a custom parameter that used to pass information to the JNDI provider. contextParameterValue is the information that is passed.
      priority = priorityValue
      priorityValue sets the JMS message priority. 0 is low, 9 is high. The default value is 4.
      queue : queueName
      queueName is the name of a JMS queue on which the SOAP request is placed. If the queue variant is specified, a queue name must be provided. If the queue does not belong to a default queue manager on the same server as the client, set the connectionFactory parameter.
      replyToName = replyToDestination
      replyToDestination sets the destination queue name. If the destination variant is jndi, the name is a JNDI name that must map to a queue. If the variant is queue the name is a JMS queue. The default value is SYSTEM.SOAP.RESPONSE.QUEUE.
      targetService = serviceName
      The name used by the SOAP server to start the target web service.

      • On Axis, serviceName is the fully qualified name of a Java service, for example: targetService=www.example.org.StockQuote. If targetService is not specified, a service is loaded using the default Axis mechanism.
      timeToLive = milliseconds
      Set milliseconds to the time before the message expires. The default, 0, is the message never expires.


    Examples

    Figure 1. Use jms:jndi to send a SOAP/JMS request
    jms:jndi:REQUESTQ
    ?jndiURL=file:/C:/JMSAdmin
    &jndiInitialContextFactory=com.sun.jndi.fscontext.RefFSContextFactory
    &jndiConnectionFactoryName=ConnectionFactory
    &replyToName=RESPONSEQ
    &deliveryMode(NON_PERSISTENT)
    Figure 2. Use jms:queue to send a SOAP/JMS request
    jms:queue:SOAPJ.demos
    ?connectionFactory=connectQueueManager(QM1)
     Bind(Client)
     ClientChannel(SOAPClient)
     ClientConnection(www.example.org(1418))
     &deliveryMode(NON_PERSISTENT)
    1 Look for URI Scheme for JMS, in the