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.

[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 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 that is 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 is used to specify 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. Specify the 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_name.server_name, 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 that can be 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.
Note: 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 you 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.
You 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 documentation for more information.

These transport chains specify the communication protocols that can be 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 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 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 documentation 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 by 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 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.
-authDataAlias
alias_name
-shareDataSourceWithCMP
True | False

-xaRecoveryAuthAlias
alias_name

Example

Note: 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.
  • Using Jython:
    wsadmin>AdminConfig.getid("/Node:9994GKCNode01" )

    "9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)"

    wsadmin>AdminTask.createSIBJMSConnectionFactory("9994GKCNode01(cells/
9994GKCNode01Cell/nodes/9994GKCNode01|node.xml)", ["-name", "jmscf1", 
 "-jndiName", "jms/jmscf1", "-busName", "abus"])

    "jmscf1(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml#
J2CConnectionFactory_1098733325084)"
    wsadmin>AdminTask.createSIBJMSConnectionFactory("9994GKCNode01(cells/
9994GKCNode01Cell/nodes/9994GKCNode01|node.xml)", ["-name", "jmsqcf2", 
 "-jndiName", "jms/jmsqcf1", "-busName", "abus", "-type", "queue"])

    "jmsqcf2(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml#
J2CConnectionFactory_1098733675578)"
  • Using Jacl:
    wsadmin>$AdminConfig getid /Node:9994GKCNode01

    9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)

    wsadmin>$AdminTask createSIBJMSConnectionFactory 
9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)
 {-name jmscf1 -jndiName jms/jmscf1 -busName abus}

    jmscf1(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml#
J2CConnectionFactory_1098733325084)

    wsadmin>$AdminTask createSIBJMSConnectionFactory 
9994GKCNode01(cells/9994GKCNode01Cell/nodes/9994GKCNode01|node.xml#Node_1)
 {-name jmsqcf2 -jndiName jms/jmsqcf1 -busName abus -type queue}

    jmsqcf2(cells/9994GKCNode01Cell/nodes/9994GKCNode01|resources.xml#
J2CConnectionFactory_1098733675578)