modifySIBJMSActivationSpec command

Use the modifySIBJMSActivationSpec command to change properties of a JMS activation specification for the default messaging provider at a specific scope.

To run the command, use the AdminTask object of the wsadmin scripting client.

[IBM i] [IBM i] The wsadmin scripting client is run from Qshell.

Command-line help is provided for service integration bus commands:

For a list of the available service integration bus JMS commands in Jython and a brief description of each command, enter the following command at the wsadmin prompt:
print AdminTask.help('SIBJMSAdminCommands')
For overview help on a given command, enter the following command at the wsadmin prompt:
print AdminTask.help('command_name')

After using the command, save your changes to the master configuration by using the following command:

AdminConfig.save()

Purpose

This command changes the properties of a JMS activation specification.

Target object

The scope of the default messaging provider at which the JMS activation specification is to be modified.

Required parameters

None.

Optional parameters

-name

The administrative name assigned to this activation specification.

-jndiName

The JNDI name that is specified in the bindings for message-driven beans associated with this activation specification.

-description

An optional description for the activation specification.

-destinationType

Use this parameter to determine whether the message-driven bean uses a JMS queue or a JMS topic. Select one of the following values:

Queue: The message-driven bean uses a JMS queue. The JNDI name of the JMS queue is specified on the Destination JNDI name property.
Topic: The message-driven bean uses a JMS topic. The JNDI name of the JMS topic is specified on the Destination JNDI name property.

-destinationJndiName

The JNDI name of the destination JMS queue or topic used by the message-driven bean.

-messageSelector

string

-busName

Enter the name of the service integration bus to which connections are made. This must be the name of the bus on which the destination identified by the -destinationJndiName property is defined.

-acknowledgeMode

The acknowledge mode indicates how a message received by a message-driven bean should be acknowledged. Select one of the following values:

Auto-acknowledge: The session automatically acknowledges the delivery of a message.
Duplicates-ok auto-acknowledge: The session lazily acknowledges the delivery of messages, which can improve performance, but can lead to a message-driven bean receiving a message more than once.

-target

The name of a target that identifies a group of messaging engines. Specify the type of target using the Target type property.

-targetType

The type of target named in the -target property. Select one of the following values:

Bus member name: The name of a bus member. This option retrieves the active messaging engines that are hosted by the named bus member (an application server or server cluster).
Custom messaging engine group name: The name of a custom group of messaging engines (that form a self-declaring cluster). This option retrieves the active messaging engines that have registered with the named custom group.
Messaging engine name: The name of a messaging engine. This option retrieves the available endpoints that can be used to reach the named messaging engine.

-targetSignificance

This property specifies the significance of the target group. Select one of the following values:

Preferred: It is preferred that a messaging engine is selected from the target group. A messaging engine in the target group is selected if one is available. If a messaging engine is not available in the target group, a messaging engine outside the target group is selected if available in the same service integration bus.
Required: It is required that a messaging engine is selected from the target group. A messaging engine in the target group is selected if one is available. If a messaging engine is not available in the target group, the connection process fails.

-targetTransportChain

The name of the inbound transport chain that the application should target when connecting to a messaging engine in a separate process to the application. If a messaging engine in another process is chosen, a connection can be made only if the messaging engine is in a server that runs the specified inbound transport chain. Refer to the documentation for more information.

If the selected messaging engine is in the same server as the application, a direct in-process connection is made and this transport chain property is ignored.

The transport chains represent network protocol stacks operating within a server. The name you specify must be one of the transport chains available in the server that hosts the messaging engine, as listed on the Servers -> Server Types -> WebSphere application servers -> server_name -> [Server messaging] Messaging engine inbound transports panel. The following transport chains are provided, but you can define your own transport chains on that panel.

InboundBasicMessaging: This is a connection-oriented protocol that uses a standard TCP/IP connection (JFAP-TCP/IP). It includes support for two-phase transactional (remote XA) flows, so that a message producer or consumer, running on a client or server system, can participate in a global transaction managed on that client or server system. The specific use for the XA flows is to support access from an application running in one server to a messaging engine on second server, perhaps because the first server does not have a suitable messaging engine. If the remote XA flows are used, a transaction coordinator must be available local to the application.
InboundSecureMessaging: This is the InboundBasicMessaging protocol wrapped in SSL.

For more information about using this property with other connection factory properties for workload management of connections, see the topic Administrative properties for JMS connections to a bus.

-providerEndPoints

A comma-separated list of endpoint triplets, with the syntax host_name:port_number:chain_name, used to connect to a bootstrap server. For example Merlin:7276:BootstrapBasicMessaging,Gandalf:5557:BootstrapSecureMessaging.

Provider endpoints are not used unless the specified bus cannot be found in the local cell. MDB applications first attempt to connect the specified bus in the local cell. If this attempt fails, provider endpoints are used to allow the applications to consume messages from a remote cell.

If the host name is not specified, localhost is used as a default value.

If the port number is not specified, 7276 is used as the default value.

If the protocol is not specified, a predefined chain such as BootstrapBasicMessaging is used as the default value.

-authenticationAlias

The name of a J2C authentication alias used for component-managed authentication of connections to the service integration bus.

A Java™ Platform, Enterprise Edition (Java EE) Connector Architecture (JCA) authentication alias specifies the user ID and password that is used to authenticate the creation of a new connection to the JMS provider.

-maxBatchSize

The maximum number of messages in a single batch delivered serially to a single message-driven bean instance. Batching of messages can improve performance particularly when used with Acknowledge mode set to Duplicates-ok auto-acknowledge. If message-ordering must be retained across failed deliveries, set the batch size to 1

-maxConcurrency

The maximum number of endpoints to which messages are delivered concurrently.

Increasing this number can improve performance but can increase the number of threads that are in use at any one time. If message ordering must be retained across failed deliveries, set the maximum concurrent endpoints to 1. Message ordering applies only if the destination that the message-driven bean is consuming from is not a partitioned destination. Partitioned destinations are used in a workload sharing scenario in a cluster.

-subscriptionDurability

Whether a JMS topic subscription is durable or nondurable

Usually, only one application at a time can have a consumer for a particular durable subscription. This property enables you to override this behavior, to enable a durable subscription to have multiple simultaneous consumers. Select one of the following values:

Durable: The messaging provider stores messages while the message-driven bean is not available, and delivers the messages when the message-driven bean becomes available again.
Nondurable: The messaging provider does not store and redeliver messages if a message-driven bean is not available.

-subscriptionName

The subscription name needed for durable topic subscriptions. Required field when using a durable topic subscription.

Each JMS durable subscription is identified by a subscription name (specified on this property). A JMS connection also has an associated client identifier (specified on the Client identifier property), which is used to associate a connection and its objects with the list of messages (on the durable subscription) that is maintained by the JMS provider for the client.

This subscription name must be unique within a given client identifier.

-clientId

The JMS client identifier needed for durable topic subscriptions on all connections created using this activation specification.

The value specified is a unique identifier for a client (message-driven bean). The client identifier is used to associate a client connection with the list of messages (on a durable subscription) that the messaging provider keeps for the client. When a client becomes available again, after a being unavailable, the messaging provider uses the client identifier to redeliver stored messages to the correct client.

-durableSubscriptionHome

The name of the messaging engine used to store messages delivered to durable subscriptions for objects created from this JMS activation specification. This is a required field when using a durable topic subscription.

Administrators can manage the runtime state of durable subscriptions through publication points for this messaging engine.

-shareDurableSubscriptions

Controls whether or not durable subscriptions are shared across connections with members of a server cluster.

Usually, only one session at a time can have a TopicSubscriber for a particular durable subscription. This property enables you to override this behavior, to enable a durable subscription to have multiple simultaneous consumers, one on each application server in the server cluster.

Select one of the following values:

In cluster: Allows sharing of durable subscriptions when connections are made from within a server cluster.
Always shared: Durable subscriptions can be shared across connections.
Never shared: Durable subscriptions are never shared across connections.

-shareDataSourceWithCmp

Allow sharing of connections between JMS and container-managed persistence (CMP) entity beans.

True | False

This option is used as part of the task to enable container-managed persistence (CMP) entity beans to share the database connections used by the data store of a messaging engine. This has been estimated as a potential performance improvement of 15% for overall message throughput, but can only be used for entity beans connected to the application server that contains the messaging engine. This option must not be enabled for a messaging engine that uses file store as its data store.

For more information about using this option, see Enabling CMP entity beans and messaging engine data stores to share database connections..

-readAhead

Read ahead is an optimization that preemptively assigns messages to consumers. This improves the time taken to satisfy consumer requests.

Messages that are assigned to a consumer are locked on the server and cannot be consumed by any other consumers for that destination. Messages that are assigned to a consumer, but not consumed before that consumer is closed, are subsequently unlocked on the server and then available for receipt by other consumers.

You can override this property for individual JMS destinations by setting the Read ahead property on the JMS destination.

Select one of the following values:

Enabled: The messaging provider preemptively assigns messages to consumers. This improves the time taken to satisfy consumer requests.
Disabled: The messaging provider does not preemptively assign messages to consumers.
Default: The message provider preemptively assigns messages to consumers on nondurable subscriptions and unshared durable subscriptions. That is, read ahead optimization is turned on only when there can only be a single consumer.

The pass message payload by reference properties:

-forwarderDoesNotModifyPayloadAfterSet

true | false (default false)

Applications resending messages that were originally received using this activation specification must obey the following rules:

The application can replace the data object in a JMS object message, provided that the data object has not yet been set in the message. The application does not modify or replace the data object after it is set in the message.
The application can replace the byte array in a JMS bytes message, but only by using a single call to writeBytes(byte[]), and provided that the byte array has not yet been set in the message. The application does not modify or replace the byte array after it is set in the message.

-consumerDoesNotModifyPayloadAfterGet

true | false (default false)

Applications that use this activation specification to receive messages must obey the following rule: The application does not modify the data object obtained from a JMS object message. The data object is treated as read only.

When large object messages or bytes messages are sent, the cost in memory and processor use of serializing, deserializing, and copying the message payload can be significant. If you enable the pass message payload by reference properties on a connection factory or activation specification, you tell the default messaging provider to override the JMS 1.1 specification and potentially reduce or bypass this data copying.

CAUTION:

The parts of the JMS Specification that are bypassed by these properties are defined to ensure message data integrity. Any of your JMS applications that use these properties must strictly follow the rules that are described in the topic Why and when to pass the JMS message payload by reference, or you risk losing data integrity.

-alwaysActivateAllMDBs

True | False

This property is only used when the MDB application is running on a server that is a member of the bus that the application is targeting. It has no effect when the MDB is running on a server that is not a member of the target bus.

If the MDB application is running on a server that is a member of the target bus, enabling this option allows the MDB application to process messages whether or not the server also hosts a running messaging engine. If this option is not enabled, then MDB applications on servers that do not have a local ME running do not process messages.

For MDB applications connecting to a cluster bus member, you can also use this option to enable either of the following additional configurations:

All servers in the cluster can receive messages from the MDB application, to make full use of the processing power in the cluster.
Just one server at a time can receive messages from the MDB application, to ensure sequential processing of the messages.

To enable all servers in the cluster to receive messages from the MDB application, select this option. To enable just one server at a time to receive messages from the MDB application, check that this option is not selected and select the receive exclusive option on the destination.

For more information, see How a message-driven bean connects in a cluster.

-retryInterval

The delay (in seconds) between attempts to connect to a messaging engine, both for the initial connection, and any subsequent attempts to establish a better connection.

-userName

The user identity for Java 2 connector security to use.

-password

The password for Java 2 connector security to use.

-WAS_EndpointInitialState

This property determines whether the endpoint is activated when the endpoint is registered. If the property is set to active, message consumption begins from the JMS destination as soon as the activation specification is used for a message-driven bean to connect with the destination.

The value of this parameter must be ACTIVE or INACTIVE.

Example

The following example shows an activation specification being modified using Jython:

wsadmin>AdminTask.modifySIBJMSActivationSpec("myjmsas(cells/
9994GKCNode01Cell/nodes/
9994GKCNode01|resources.xml#J2CActivationSpec_1098726667851)", 
 ["-jndiName", "jms/jmsas4q1", 
 "-description", "JMS activation specification for myqueue1",
 "-destinationJndiName", "jms/myqueue1"])
"myjmsas(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml#
J2CActivation Spec_1098726667851)"

The following example shows an activation specification being modified using Jacl:

wsadmin>$AdminTask modifySIBJMSActivationSpec 
myjmsas(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml#
J2CActivationSpec_1098726667851) 
{-jndiName jms/jmsas4q1 -description "JMS activation specification 
for myqueue1" -destinationJndiName jms/myqueue1}
myjmsas(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml#
J2CActivation Spec_1098726667851)

The following example modifies an activation specification by activating the WAS_EndpointInitialState optional parameter, using Jython:

wsadmin>attrs = "[[name "WAS_EndpointInitialState"] [required "false"] [type "java.lang.String"] [value "ACTIVE"]]"
wsadmin>AdminConfig.getid("/Node:myNode01")
"myNode01(cells/myCell01/nodes/myNode01|node.xml#Node_1)"
wsadmin>AdminTask.listSIBJMSActivationSpecs("myNode01(cells/myCell01/nodes/myNode01|node.xml#Node_1)")
"newas(cells/myCell01/nodes/myNode01|resources.xml#J2CActivationSpec_1298546034140)"
wsadmin>AdminConfig.create("J2EEResourceProperty", 
"testas(cells/myCell01/nodes/myNode01|resources.xml#J2CActivationSpec_1298546034140)", attrs)
"WAS_EndpointInitialState(cells/myCell01/nodes/myNode01|resources.xml#J2EEResourceProperty_1298546239332)"