Web Service 部署的 URI 语法和参数

用于部署 IBM® MQ Web Service 的语法和参数在 URI 中定义。 部署实用程序根据 Web Service 的名称生成缺省 URI。 您可以通过将自己的 URI 定义为部署实用程序的参数来覆盖缺省值。 部署实用程序将 URI 合并到生成的 Web Service 客户机存根中。

用途

使用统一资源标识 (URI) 指定 Web Service。 语法图指定 IBM MQ Transport for SOAP 中支持的 URI。 URI 控制用于访问目标服务的特定于 IBM MQ 的 SOAP 参数和选项。 URI 与 .NET， Apache Axis 1 ， WebSphere® Application Server和 CICS®托管的 Web Service 兼容。

描述

该 URI 将合并到由部署实用程序生成的 Web Service 客户机类中。 客户机将 URI 传递到 IBM MQ 消息中的 IBM MQ SOAP 发送方。 URI 控制由 IBM MQ SOAP 发送方和 IBM MQ SOAP 侦听器执行的处理。

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 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 = serviceName URI (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

目标到队列名称变换

  1. className 以 SOAPJ. for Java 服务或 SOAPN. for .NET 服务为前缀。
  2. 将从 className 参数中给定的完整路径名中除去文件扩展名。
  3. 生成的字符串将截断为不超过 48 个字符
  4. 目录分隔符将替换为句点字符。
  5. 嵌入的空格将替换为下划线字符。
  6. 驱动器前缀字母后面的冒号将替换为 .NET 服务的句点。
注: 在某些环境中，部署实用程序生成的队列名称可能不唯一。 部署实用程序将检查是否创建队列。 您可以选择通过重构部署目录层次结构或定制提供的部署过程来覆盖部署实用程序。

必需的 URI 参数

destination = 队列
queue 是请求目标的名称。 它可以是队列或队列别名。 如果是队列别名，那么该别名可以解析为主题。
  • 如果省略了 -u 参数，那么将使用 目标到队列名称变换中描述的步骤从 classname 生成 queue 。
  • 如果指定了 -u 参数，那么 queue 是必需的，并且必须是初始 jms: / queue 之后 URI 的第一个参数? 字符串。 指定 IBM MQ 队列名称或通过 @ 符号连接的队列名称和队列管理器名称，例如 SOAPN.trandemos@WMQSOAP.DEMO.QM。
  • 部署实用程序将检查生成或提供的队列名称是否与现有队列的名称匹配。 表 1中描述了所执行的操作。
    表 1。 队列 验证
    是否存在侦听器脚本? 侦听器脚本存在于 ./generated/server 目录中 侦听器脚本在 ./generated/server 目录中不存在
    侦听器脚本中的队列是否与 queue 匹配? queue 与侦听器脚本中使用的请求队列不匹配 queue 与侦听器脚本中正在使用的请求队列相匹配
    队列 存在
    • 部署存在错误。
    • 该服务已部署在 ./generated/server中，但正在使用另一个队列。
    • 部署正常继续。
    • 该服务已部署在 ./generated/server 中
    • 部署存在错误。
    • 在 ./generated/server中找不到侦听器启动脚本，但其他服务或应用程序正在使用 队列 。
    队列 不存在
    • 部署继续，但存在警告。
    • 先前部署可能已失败，因为启动有效，但缺少 queue 。
    • 部署正常继续。
    • 未从此目录部署任何服务。
&connectionFactory = 名称 (值)
Name 是下列其中一个参数:请参阅 连接工厂参数 以获取这些参数的值的描述。
&targetService = serviceName
1 在 .NET上， serviceName 是位于部署目录中的 .NET 服务的名称，例如: targetService=myService.asmx。 在 .NET 环境中， targetService 参数使单个 IBM MQ SOAP 侦听器能够处理针对多个服务的请求。 必须从同一目录部署这些服务。

可选 URI 参数

&initialContextFactory = contextFactory
contextFactory 是必需的，必须设置为 com.ibm.mq.jms.Nojndi。 确保 Nojndi.jar 位于 WebSphere Application Server Web Service 客户机的类路径中。 Nojndi.jar 根据 connectionFactory 和 destination 参数的内容 (而不是通过引用目录) 返回 Java 对象。
&targetService = serviceName
2 在 Axis 上， serviceName 是 Java 服务的标准名称，例如: targetService=javaDemos.service.StockQuoteAxis。 如果未指定 targetService ，那么将使用缺省 Axis 机制装入服务。
&persistence = messagePersistence
messagePersistence 采用下列其中一个值:
0
从队列定义继承持久性。
1
该消息是非持久消息。
2
消息是持久的
&priority = priorityValue
priorityValue 在 0-9 范围内。 0 是低优先级。 缺省值为特定于环境的值，在 IBM MQ 的情况下为 0。
&replyDestination = replyToQueue
要用于响应消息的客户机端的队列。 缺省应答队列为 SYSTEM.SOAP.RESPONSE.QUEUE。
  • 运行 setupWMQSOAP 脚本以创建缺省 IBM MQ SOAP 对象。
  • 为replyToQueue指定一个模型队列，以创建临时或永久动态响应队列。 对于临时和永久动态响应队列，将为每个请求创建单独的动态队列实例。 如果发生以下任何事件，那么将删除队列:
    • 响应已到达并已处理。
    • 请求超时。
    • 请求程序终止。

    为了获得最佳性能，请使用临时动态队列而不是永久动态队列。 请勿将持久请求消息发送到具有临时动态队列的 URI。 IBM MQ 侦听器 SOAP 无法处理消息并输出错误。 客户机等待应答时超时。

  • setupWMQSOAP 脚本创建名为 SYSTEM.SOAP.MODEL.RESPONSE.QUEUE的缺省永久动态模型队列。
&timeout = waitTime
客户机等待响应消息的时间 (以毫秒计)。 waitTime 覆盖基础结构或客户机应用程序设置的值。 如果未指定，那么将继承应用程序值 (如果已指定) 或基础结构缺省值。
注：超时和timeToLive 之间没有强制关系。
&timeToLive = expiryTime
expiryTime 是消息到期之前的时间 (以毫秒为单位)。 缺省值为零，这指示生存期不受限制。
注：超时和timeToLive 之间没有强制关系。

连接工厂参数

connectQueueManager ( qMgrName )
qMgrName指定客户端连接的队列管理器。 缺省值为空白。
binding ( bindingType )
bindingType指定客户端与qMgrName 的连接方式。 缺省值为 auto。 bindingType 采用以下值:
自动
发送方按顺序尝试以下连接类型:
  1. 如果指定了适合于客户机连接的其他选项，那么发送方将使用客户机绑定。 其他选项为 clientConnection 或 clientChannel。
  2. 使用服务器连接。
  3. 使用客户机连接。
如果 SOAP 客户机上没有本地队列管理器，请在 URI 中使用 binding ( auto ) 。 为 SOAP 客户机构建客户机连接。
client
使用 URI 中的 binding ( client ) 为 SOAP 发送方构建客户机配置。
server
使用 URI 中的 binding ( 服务器 ) 为 SOAP 发送方构建服务器配置。 如果连接具有客户机类型参数，那么连接将失败，并且 IBM MQ SOAP 发送方将显示错误。 客户端类型参数包括clientConnection、clientChannel 或 SSL 参数。
xaclient
xaclient 仅适用于 .NET ，而不适用于 Java 客户机。 使用 XA 客户机连接。
clientChannel ( 通道 )
  • SOAP 客户机使用 通道 来建立 IBM MQ 客户机连接。 除非在服务器上启用了通道自动定义，否则 channel 必须与服务器连接通道的名称匹配。 clientChannel 是必需参数，除非您提供了 "客户机连接定义" 表 (CCDT)。
  • 通过设置 com.ibm.mq.soap.transport.jms.mqchlurl在 Java 中提供 CCDT。 在 .NET 中，设置 MQCHLLIB 和 MQCHLTAB 环境变量; 请参阅 将通道定义表与 IBM MQ SOAP Transport for SOAP 发送方配合使用。
clientConnection ( 连接 )
SOAP 客户机使用 连接 来建立 IBM MQ 客户机连接。 缺省主机名为 localhost，缺省端口为 1414。 如果 connection 是 TCP/IP 地址，那么它采用三种格式之一，并且可以使用端口号作为后缀。

JMS 客户机可以使用格式 : hostname:port 或使用格式 %X 对方括号进行 "转义" ，其中 X 是表示 URI 的代码页中括号字符的十六进制值。 例如，在 ASCII 中， %28 和 %29 分别用于 ( 和 ) 。

.Net 客户机可以显式使用方括号 : hostname(port) 或使用 "转义" 格式。

IPv4 地址
例如，192.0.2.0。
IPv6 地址
例如，2001:DB8:0:0:0:0:0:0。
主机名
例如，www.example.com%281687%29、www.example.com:1687 或 www.example.com(1687)。
SSL 平台
请参阅 必需的 SSL 参数 (Java)

样本 URI

注：
  1. URI 中的 & 编码为 &
  2. 先前列示的所有参数都适用于客户机。
  3. 只有 destination， connectionFactory 和 initialContextFactory 适用于 WCF 服务。
图 1。 用于 Axis 服务的 URI ，仅提供必需参数
jms:/queue?destination=myQ&connectionFactory=()&initialContextFactory=com.ibm.mq.jms.Nojndi
图 2。 .NET 服务的 URI ，仅提供必需参数
jms:/queue?destination=myQ&connectionFactory=()&targetService=MyService.asmx
&initialContextFactory=com.ibm.mq.jms.Nojndi
图 3。 用于 Axis 服务的 URI ，提供一些可选 connectionFactory 参数
jms:/queue?destination=myQ@myRQM&connectionFactory=connectQueueManager(myconnQM)
binding(client)clientChannel(myChannel)clientConnection(myConnection)
&initialContextFactory=com.ibm.mq.jms.Nojndi
图 4： Axis 服务的 URI，提供connectionFactory参数的sslPeerName选项
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 服务
仅 2 Java 服务