Class ImaJmsFactory
- Object
-
- com.ibm.ima.jms.ImaJmsFactory
-
public final class ImaJmsFactory extends Object
Constructs IBM MessageSight JMS client administered objects.Table of contents
- Method summary
- ConnectionFactory properties
- Queue and Topic properties
- Read only properties for other objects
Introduction
Normally when using JMS, the ConnectionFactory and Destination objects are looked up in a JNDI repository. This class allows these objects to be constructed so that they can be stored in a JNDI repository.There are four steps used to create an IBM MessageSight JMS client administered object:
- Create the administered object using create methods in the ImaJmsFactory class.
- Set the properties in the administered object by casting it to ImaProperties and using put methods in the ImaProperties interface.
- Validate the properties by using validate methods in the ImaProperties interface.
- Store the object in the JNDI repository using the bind or rebind methods.
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:
- ConnectionFactory
- The ConnectionFactory implementation in the IBM MessageSight JMS client implements the three connection factory interfaces: ConnectionFactory, TopicConnectionFactory, and QueueConnectionFactory.
- Queue
- The Queue implementation in the IBM MessageSight JMS client implements two destination interfaces: Destination and Queue.
- Topic
- The Topic implementation in the IBM MessageSight JMS client implements two destination interfaces: Destination and Topic.
ConnectionFactory properties
The properties for ConnectionFactory are listed in the following table. These properties are used to create the IBM MessageSight JMS client Connection object.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".
Properties for a connection factory
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
automatic
is specified, the JMS client will create the message type by looking at the content of the message. When using automatic conversion, you should useinstanceof
to check the class of the message. Messages coming from MQTT will be converted to either BytesMessage or TextMessage. Any messages containing control characters or invalid character sequences are converted to BytesMessages.If
bytes
is specified, the message body is converted into a BytesMessage. If the message contains only a text string, you must get the entire content as a byte array and convert it to a String using the String constructor with the UTF-8 character set.If
text
is specified, the message body is converted into a TextMessage. If any invalid character sequences are found the text cannot be received.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, ortcps
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. Queue and Topic properties
The properties for Queue and Topic are listed in the following table. These destination properties are used when creating an IBM MessageSight JMS client MessageConsumer or MessageProducer.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. Read only properties for other objects
The Connection, Session, MesssgeConsumer, and MessageProducer objects within the IBM MessageSight JMS client contain read only properties that are derived from the objects used to create them.Connection properties
In addition to read only properties derived from the ConnectionFactory properties, the following read only properties may exist for Connection objects.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. Session properties
In addition to read only properties derived from the Connection properties, the following read only properties may exist for Session objects.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). Message consumer properties
In addition to read only properties derived from the Destination properties, the following read only properties may exist for MessageConsumer objects. These properties represent the actual values and might differ from the properties of the source objects.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. Message producer properties
In addition to read only properties derived from the Destination properties, the following read only properties may exist for MessageProducer objects.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.
-
-
Field Summary
Fields Modifier and Type Field Description static String
COPYRIGHT
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method 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.
-
-
-
Field Detail
-
COPYRIGHT
public static final String COPYRIGHT
- See Also:
- Constant Field Values
-
-
Method Detail
-
createConnectionFactory
public static javax.jms.ConnectionFactory createConnectionFactory() throws javax.jms.JMSException
Creates an IBM MessageSight JMS client connection factory.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.
- Returns:
- A ConnectionFactory which can also be cast to ImaProperties.
- Throws:
javax.jms.JMSException
- If the connection factory cannot be created
-
createConnectionFactory
public static javax.jms.ConnectionFactory createConnectionFactory(String protocol, String server, int port, String clientID) throws javax.jms.JMSException
Creates an IBM MessageSight JMS client connection factory.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.
- Parameters:
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 connection- Returns:
- A ConnectionFactory which can also be cast to ImaProperties or used to create a Connection.
- Throws:
javax.jms.JMSException
- if the connection factory cannot be created
-
createTopicConnectionFactory
public static javax.jms.TopicConnectionFactory createTopicConnectionFactory() throws javax.jms.JMSException
Creates an IBM MessageSight JMS client topic connection factory.- Returns:
- A TopicConnectionFactory which can also be cast to ImaProperties.
- Throws:
javax.jms.JMSException
- If the topic connection factory cannot be created
-
createQueueConnectionFactory
public static javax.jms.QueueConnectionFactory createQueueConnectionFactory() throws javax.jms.JMSException
Creates an IBM MessageSight JMS client queue connection factory.- Returns:
- A QueueConnectionFactory which can also be cast to ImaProperties.
- Throws:
javax.jms.JMSException
- If the queue connection factory cannot be created
-
createTopic
public static javax.jms.Topic createTopic(String name) throws javax.jms.JMSException
Creates a topic given a name. The name of a topic is a String which describes the topic. This is often different from the name under which it is stored in JNDI.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.
- Parameters:
name
- The name of the topic- Returns:
- A Topic which can also be cast to ImaProperties.
- Throws:
javax.jms.JMSException
- If the topic cannot be created
-
createQueue
public static javax.jms.Queue createQueue(String name) throws javax.jms.JMSException
Creates a queue given a name. The name of a queue is a String which describes the queue. This is often different from the name under which it is stored in JNDI.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.
- Parameters:
name
- The name of the queue- Returns:
- A Queue which can also be cast to ImaProperties.
- Throws:
javax.jms.JMSException
- If the destination cannot be created
-
-