public final class ImaJmsFactory
extends Object
There are four steps used to create an IBM MessageSight JMS client administered object:
The following sample shows some simplified logic to create a ConnectionFactory and bind it into a JNDI context.
// Create a connection factory
ConnectionFactory cf = ImaJmsFactory.createConnectionFactory();
// Set the desired properties
ImaProperties props = (ImaProperties)cf;
props.put("Port", "1883");
props.put("Server", "server1.company.com");
// Validate the properties. A null return means that the properties are valid.
ImaJmsException [] errstr = props.validate(ImaProperties.WARNINGS);
if (errstr == null) {
// Open the initial context
InitialContext ctx;
Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://server2.company.com/o=jndiTest");
try {
ctx = new InitialContext(env);
// Bind the connection factory to a name
ctx.rebind("ConnName", cf);
} catch (Exception e) {
System.out.println("Unable to open an initial context: " + e);
}
} else {
// Display the validation errors
for (int i=0; i<errstr.length; i++)
System.out.println(""+errstr[i]);
}
Similar logic can be used to create IBM MessageSight JMS client objects without storing the object in JNDI.
In the IBM MessageSight JMS client there are three administered objects:
When a Connection is created, these properties are copied to the Connection object and are available as read only properties in the Connection. When a Session is created from the Connection, the properties of the Connection are copied into the Session and are available as read only properties. The properties within the Connection and Session represent the current state of those objects.
For consumer specific property values, the UserData property is defined on the ConnectionFactory interface. Because it is intended for use by API consumers, this property value can be set at any time on the ConnectionFactory and on Connection and Session objects derived from it. Additional user properties can be defined for the ConnectionFactory using the ImaProperties.addValidProperty() method. In order for a custom property to be writable on Connection and Session objects, the property name must contain the string "user". Otherwise, the property will be read only for the these objects.
The properties which almost always need to be set are the Server and Port which define the location of the server. To use secure communications you will need to set the Protocol to "tcps".
Name | Type | Description |
---|---|---|
AsyncTransactionSend | Boolean | All persistent messages are sent synchronously to the server and non-persistent messages are normally sent asynchronously. This means that for non-persistent messages you will not get the exception for any send problem on the send but it will be raised later. If AsyncTransactionSend has the default value of false, non-persistent messages within a transaction are sent synchronously so that you can see if there is a problem before doing a commit. If AsyncTransactionSend is set to true, non-persistent messages within a transaction are sent asynchronously, and if such a send fails, a commit will fail. |
ClientID | Name | The clientID for this connection. Although in JMS the client ID is optional,
IBM MessageSight requires that every connection have a unique clientID.
This can be set in the ConnectionFactory properties (in JNDI).
It can also be set using the ClientID environment variable, or by the application
after the Connection is created and before the first Session is created.
If the clientID is not set (either by setting the ClientID property on the ConnectionFactory object or by calling setClientID()
on the connection object) before the first session is created or before the start() method is called on the connection object,
the IBM MessageSight JMS client will check to see whether the ClientID environment variable is set and will use that value if
it is found.
If the clientID is not otherwise set, the IBM MessageSight JMS client will automatically create a clientID. An automatically generated clientID cannot be used to create non-shared durable subscriptions, and shared subscriptions are global. The IBM MessageSight JMS client allows any valid Unicode string to be used as a clientID, but we recommend that only displayable characters be used. System generated client IDs start with an underscore (_) and users should avoid using this as an initial character to avoid conflicts. ClientIDs starting with two underscores are reserved for system use. |
ClientMessageCache | UInt | The default maximum number of messages which should be cached at the client for each consumer created within connections created by this connection factory. When not set, the default value is 1000 for unshared topics. This value is always 0 for queues and for shared subscriptions. Setting a larger value increases performance. This value is used by the messaging server as a hint but might not be honored exactly. When set, this value only applies to non-shared topics. The default value of 0 is enforced for queues and for shared subscriptions. In order to set a larger value for queues and for shared subscriptions, you can set the ClientMessageCache property on the destination. |
ConvertMessageType | Enum automatic, bytes, text | The action to take when converting
a message to JMS from a source which does not indicate the message type. If the message comes from JMS this
is not used.
The values can be: automatic, bytes, or text. If this property is not set, the default value is automatic.
If
If
If |
DefaultTimeToLive | UInt | The default JMS time to live in seconds for producers created from this connection. The default value of zero indicates that messages do not expire. |
DisableACK | Boolean | If true all ACK processing is disabled for this connection unless it is overridden by the DisableACK setting of the destination. Disable of ACK is the fastest method of transmitting messages and provides a quality of service below NON_PERSISTENT. If this property is not set, the default value is false. |
DisableMessageID | Boolean | Set the default for whether JMS computes a message ID and puts it in the message. The default is false but can be overridden when the JMS MessageProducer is created. Creating the message ID takes time and increases the size of a message. |
DisableMessageTimestamp | Boolean | Set the default for whether JMS puts a timestamp in the message. The default is false but can be overridden when the JMS MessageProducer is created. Putting the timestamp in the message takes time and increases the size of the message. If the timestamp is not stored in the message, messages will not ever expire. |
DisableTimeout | Boolean | Disable the detection of a silent disconnect. Normally when one side of a connection disconnects, the other side is notified and closes its resources. In some cases this notification does not happen. In order to detect this condition, the JMS client periodically contacts the server to make sure it is still active and closes if it is not. The default setting of false allows this timeout. If set to true, the timeout is disabled in both directions. This should be used with care as it can lead to resources not being freed for long periods of time. You may need to use this option if you are debugging a client application using breakpoints, or sending or receiving very large messages over slow networks. |
Port | Int 1:65535 | The port number of the server to communicate with. If there are multiple servers in the list, they all use the same port. |
Protocol | Enum tcp, tcps | The transmit protocol. This specifies the transmit protocol to use.
This can be tcp for a non-secure connection, or tcps for a secure
connection. If secure connection is used, you must set up the key store for the JVM on which the
IBM MessageSight JMS client is running. |
RecvSockBuffer | Unit | The TCP receive socket buffer size. Setting this larger allows for faster message receive by using more memory. The default is based on the platform TCP buffer size. The platform also has a maximum TCP buffer size, and setting it above this size does not work. The value can have a K or M suffix to indicate the units (kilobytes, or megabytes). |
Server | String | A space or comma delimited list with names or IP addresses of servers to communicate with. The client will attempt to connect to each server until a connection is successfully established. The name or IP address for the successful connection is stored as the Server property in the Connection object. |
TemporaryQueue | String | Specify the prototype name for a temporary queue name. A unique identifier is appended to this name to form the actual temporary queue name. Using this facility allows policies to be assigned to the temporary queue by placing it into a known place in the queue name space. If the prototype contains the character sequence $CLIENTID it will be replaced by the clientID of the connection. The default value is "_TQ/$CLIENTID/". |
TemporaryTopic | String | Specify the prototype name for a temporary topic name. A unique identifier is appended to this name to form the actual temporary topic name. Using this facility allows policies to be assigned to the temporary topic by placing it into a known place in the topic tree. If the prototype contains the character sequence $CLIENTID it will be replaced by the client ID of the connection. The default value is "_TT/$CLIENTID/". |
UserData | Object | User data associated with the Connection. This property is not used by the IBM MessageSight JMS client and can be set on the Connection. This allows data to be kept with the object. |
The only property which is normally set for a Destination is the Name. Because there are so few properties associated with a destination in the IBM MessageSight JMS client, it is common to just use the Session.createTopic() method or the Session.createQueue() method to create the destination by name. Some properties such as DisableACK and ClientMessageCache can be set on a Destination to override the value set on the ConnectionFactory.
When a MessageProducer or MessageConsumer is created, its effective properties are created from the Destination properties and are available as read only properties.
For consumer specific property values, the UserData property is defined on the Destination interface. Because it is intended for use by API consumers, this property value can be set at any time on the Destination and on MessageConsumer and MessageProducer objects derived from it. Additional user properties can be defined for the Destination using the ImaProperties.addValidProperty() method. In order for a custom property to be writable on MessageConsumer and MessageProducer objects, the property name must contain the string "user". Otherwise, the property will be read only for these objects.
Name | Type | Description |
---|---|---|
Name | String | The JMS name of the Queue or Topic. This is the queueName or topicName known to JMS. This property is required but is normally set when creating the Topic or Queue. |
ClientMessageCache | UInt | The maximum number of messages which should be cached at the client
for consumers created for this destination.
The value is used by the messaging server as a hint of the performance tradeoff but might not be honored
exactly. Using a larger value increases performance but decreases fairness when there are
multiple consumers of a queue or a shared subscription.
This value overrides the ClientMessageCache property set on the ConnectionFactory when using non-shared topics. When using a queue or shared topic, the default value is zero. |
DisableACK | Boolean | If true ACK processing is disabled for this destination. This setting overrides the DisableACK setting of the connection. Disable of ACK is the fastest method of transmitting messages and provides a quality of service below NON_PERSISTENT. If this property is not set, the default value is false. |
UserData | Object | User data associated with the Destination, MessageConsumer, or MessageProducer. This property is not used by the IBM MessageSight JMS client and can be set on the MessageConsumer or MessageProducer. |
Name | Type | Description |
---|---|---|
isClosed | Boolean | Whether the connection to the server is closed. |
isStopped | Boolean | Whether the connection to the server is stopped. |
ObjectType | Enum common, queue, topic | Indicates the type of messaging supported by the Connection object; topic, queue or common (where common indicates the object can be used for either topic or queue messaging). |
userid | String | The user name specified when the connection was created. |
Name | Type | Description |
---|---|---|
Connection | Object | The Connection object used to create the Session. |
isClosed | Boolean | Whether the Session is closed. |
ObjectType | Enum common, queue, topic | Indicates the type of messaging supported by the Session object; topic, queue or common (where common indicates the object can be used for either topic or queue messaging). |
Name | Type | Description |
---|---|---|
Connection | Object | The Connection object used to create the Session that created the consumer. |
subscriptionName | String | The subscription name if the consumer is over a durable or shared subscription. |
isClosed | Boolean | Whether the MessageConsumer is closed. |
isDurable | Boolean | Whether the MessageConsumer is a durable subscriber. |
noLocal | Boolean | Whether a topic subscriber is prohibited from receiving messages published on the same connection. |
ObjectType | Enum queue, topic | Indicates the type of messaging supported by the MessageConsumer object; topic or queue. |
Session | Object | The Session object used to create the consumer. |
SubscriptionShared | Enum NonShared, Shared, NonDurable | Specifies the type of shared subscription. |
Name | Type | Description |
---|---|---|
Connection | Object | The Connection object used to create the Session that created the producer. |
isClosed | Boolean | Whether the MessageProducer is closed. |
ObjectType | Enum queue, topic | Indicates the type of messaging supported by the MessageProducer object; topic or queue. |
Session | Object | The Session object used to create the producer. |
Modifier and Type | Field and Description |
---|---|
static String |
COPYRIGHT |
Modifier and Type | Method and Description |
---|---|
static javax.jms.ConnectionFactory |
createConnectionFactory()
Creates an IBM MessageSight JMS client connection factory.
|
static javax.jms.ConnectionFactory |
createConnectionFactory(String protocol,
String server,
int port,
String clientID)
Creates an IBM MessageSight JMS client connection factory.
|
static javax.jms.Queue |
createQueue(String name)
Creates a queue given a name.
|
static javax.jms.QueueConnectionFactory |
createQueueConnectionFactory()
Creates an IBM MessageSight JMS client queue connection factory.
|
static javax.jms.Topic |
createTopic(String name)
Creates a topic given a name.
|
static javax.jms.TopicConnectionFactory |
createTopicConnectionFactory()
Creates an IBM MessageSight JMS client topic connection factory.
|
public static final String COPYRIGHT
public static javax.jms.ConnectionFactory createConnectionFactory() throws javax.jms.JMSException
The ConnectionFactory object within the IBM MessageSight JMS client allows you to create a Connection. In order to do so you must first set properties in the Connection factory object. This can be done by casting the ConnectionFactory to the ImaProperties interface and setting the properties.
javax.jms.JMSException
- If the connection factory cannot be createdpublic static javax.jms.ConnectionFactory createConnectionFactory(String protocol, String server, int port, String clientID) throws javax.jms.JMSException
The ConnectionFactory object within the IBM MessageSight JMS client allows you to create a Connection. This method allows you to set the most common connection factory properties.
If one of the values is null (or zero for port) the default is used.
protocol
- - The protocol - tcp for non-secure or tcps for secure.server
- - A space and/or semicolon separated list of server addresses or resolvable names.port
- - The port to connect toclientID
- - The client identifier for this connectionjavax.jms.JMSException
- if the connection factory cannot be createdpublic static javax.jms.TopicConnectionFactory createTopicConnectionFactory() throws javax.jms.JMSException
javax.jms.JMSException
- If the topic connection factory cannot be createdpublic static javax.jms.QueueConnectionFactory createQueueConnectionFactory() throws javax.jms.JMSException
javax.jms.JMSException
- If the queue connection factory cannot be createdpublic static javax.jms.Topic createTopic(String name) throws javax.jms.JMSException
It is possible to call this method with a null value for the name, but the topic must have a name before it can be used. The name can be set later using the Name property.
name
- The name of the topicjavax.jms.JMSException
- If the topic cannot be createdpublic static javax.jms.Queue createQueue(String name) throws javax.jms.JMSException
It is possible to call this method with a null value for the name, but the queue must have a name before it can be used. The name can be set later using the Name property.
name
- The name of the queuejavax.jms.JMSException
- If the destination cannot be createdCopyright © Contributors to the Eclipse Foundation 2012-2021.