Use the createSIBJMSConnectionFactory command
to create a new JMS connection factory for the default messaging provider
at a specific scope.
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 information center 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
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 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 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)