+

Search Tips   |   Advanced Search

createSIBJMSConnectionFactory command

Use the createSIBJMSConnectionFactory command to create a new JMS connection factory for the default messaging provider at a specific scope.

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

(iSeries) (iSeries) The wsadmin scripting client is run from Qshell. (iSeries) See Configure Qshell to run WebSphere scripts .

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

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

AdminConfig.save()

This command creates a new JMS connection factory at a specific scope.


Target object

Scope of the default messaging provider at which the JMS connection factory is to be created.


Required parameters

-name

The administrative name assigned to this connection factory.

-jndiName

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

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


Optional parameters

-type

queue | topic

The type parameter specifies the type of connection factory to create. To create a queue connection factory, set this parameter to queue. To create a topic connection factory, set this parameter to topic. Leave this parameter unset to create a generic connection factory.

-category

An optional category string to use when classifying or grouping the resource.

-description

text

-logMissingTransactionContext

True | False

-manageCachedHandles

True | False

-clientID

id

-userName

name

-password

password

-target

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

Before the connection proximity search is performed to select a suitable messaging engine, the set of messaging engines that are members of the specified target group are selected. The connection proximity search is then restricted to these messaging engines. If a target group is not specified (the default), then all messaging engines in the bus are considered during the connection proximity search. For example, if the Target type property is set to Bus member name, the Target property specifies the name of the bus member from which suitable messaging engines can be chosen.

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

To specify a non-clustered bus member the -target property must be set to node.server, for example Node01.server1. For a cluster bus member the -target property must be set to the cluster name.

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 used to reach the named messaging engine.

-targetSignificance

This property specifies the significance of the target group.

This property defines whether the connection proximity search is restricted to only the messaging engines in 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.

A connection to a non-preferred target might be returned even if a preferred one is available. This can happen when connection pooling is enabled for a ConnectionFactory, which it is by default when we use a JMS ConnectionFactory in a server environment:

  • When a preferred messaging engine is not available, a connection to a non-preferred one can be created and stored in the connection pool.

  • The next time the application requests a connection it receives this pooled connection even if the preferred messaging engine has subsequently become available.

We can modify the connection pool settings to regularly discard all unused connections in the pool. After the connection pool is emptied, connections are made to the preferred messaging engine if one is available. For example, set the ReapTime, AgedTimeout and UnusedTimeout to 300 seconds, and the PurgePolicy to EntirePool. This refreshes the connection pool every 5 minutes, after which time the application selects a preferred messaging engine if one is available.

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.

These transport chains specify the communication protocols used to communicate with the application server to which the client application is connected.

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 we 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 -> [Server messaging] Messaging engine inbound transports panel. The following transport chains are provided, but we can define our 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 hostName:portNumber:chainName, used to connect to a bootstrap server. For example Merlin:7276:BootstrapBasicMessaging,Gandalf:5557:BootstrapSecureMessaging. If hostName is not specified, the default is localhost. If portNumber is not specified, the default is 7276. If chainName is not specified, the default is BootstrapBasicMessaging. Refer to the information center for more information.

-connectionProximity

Bus | Host | Cluster | Server

-durableSubscriptionHome

me_name

-nonPersistentMapping

BestEffortNonPersistent | ExpressNonPersistent | ReliableNonPersistent | ReliablePersistent | AssuredPersistent | AsSIBDestination | None

-persistentMapping

BestEffortNonPersistent | ExpressNonPersistent | ReliableNonPersistent | ReliablePersistent | AssuredPersistent | AsSIBDestination | None

-readAhead

Default | AlwaysOn | AlwaysOff

-tempQueueNamePrefix

prefix

-tempTopicNamePrefix

prefix

-shareDurableSubscriptions

AsCluster | AlwaysShared | NeverShared

The pass message payload by reference properties:

-producerDoesNotModifyPayloadAfterSet

true | false (default false)

Applications that use this connection factory to send messages must obey the following rules:

  • The application does not modify the data object contained in a JMS object message.

  • The application populates a JMS bytes message using a single call to writeBytes(byte[]) and does not modify the byte array after it is set in the message.

-consumerDoesNotModifyPayloadAfterGet

true | false (default false)

Applications that use this connection factory 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 we 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 our 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.

-authDataAlias

alias_name

-shareDataSourceWithCMP

True | False

-xaRecoveryAuthAlias

alias_name


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.