Use the modifySIBJMSActivationSpec command
to change properties of a JMS activation specification for the default
messaging provider at a specific scope.
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.
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 information center 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
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.
This option should be changed from its
default only in WebSphere® Application Server environments
that support server clusters.
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.
- -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)"