Network Deployment (Distributed operating systems), v8.0 > Reference > Commands (wsadmin scripting)


createSIBJMSActivationSpec command

Use the createSIBJMSActivationSpec command to create a new 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.

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

After using the command, save changes to the master configuration; for example, by using the following command:


AdminConfig.save()

The createSIBJMSActivationSpec command creates a new JMS activation specification at a specific scope.


Target object

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



Required parameters

-name

The administrative name assigned to this activation specification.

-jndiName

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

-destinationJndiName

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



Optional parameters

-description

An optional description for the activation specification.

-destinationType

An option 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.

-messageSelector

The JMS message selector used to determine which messages the message-driven bean receives. The value is a string used to select a subset of the available messages. The syntax is based on a subset of the SQL 92 conditional expression syntax, as described in the JMS specification. Refer to the information center for more information.

The selector string can refer to fields in the JMS message header and fields in the message properties. Message selectors cannot reference message body values.

A null value (an empty string) indicates that there is no message selector for the message consumer.

-busName

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 by 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 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 used if the specified bus cannot be found in the local cell. Message-driven bean 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 EE Connector Architecture (JCA) authentication alias specifies the user ID and password 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

This option specifies 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, after it has been unavailable, the messaging provider uses the client identifier to re-deliver 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.

For more information about using this option, see Enable 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.

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

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

ACTIVE |INACTIVE

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.


Example

In the following examples, code blocks beginning with wsadmin> show code that is entered by the user. Lines that do not begin with wsadmin> show code that has been returned by the console.


Pass message payload by reference: Example code for producer and consumer applications
Pass message payload by reference: Usage scenarios and example code for forwarding applications
J2C activation specification configuration and use
JCA activation specifications and service integration
Why and when to pass the JMS message payload by reference
Pass message payload by reference: Potential benefits for each processing step
Configure a connection to a non-default bootstrap server
Configure an activation specification for the default messaging provider


Related


deleteSIBJMSActivationSpec command
listSIBJMSActivationSpecs command
modifySIBJMSActivationSpec command
showSIBJMSActivationSpec command

+

Search Tips   |   Advanced Search