ImaJmsFactory ("Eclipse Amlen" Javadoc Reference)

Package com.ibm.ima.jms

## 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
  See The JMS API documentation for information about the JMS classes and methods.

  ## 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 use `instanceof` 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, 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.

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

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### 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 to
        `clientID` - - 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