Websphere MQ Everyplace

com.ibm.mqe.jms
Class MQeConnectionFactory

java.lang.Object
  |
  +--com.ibm.mqe.jms.MQeConnectionFactory
All Implemented Interfaces:
javax.jms.ConnectionFactory
Direct Known Subclasses:
MQeJNDIConnectionFactory, MQeQueueConnectionFactory

public class MQeConnectionFactory
extends java.lang.Object
implements javax.jms.ConnectionFactory

A ConnectionFactory encapsulates a set of connection configuration parameters that has been defined by an administrator. A client uses it to create a Connection with a JMS provider.

A ConnectionFactory is a JMS administered object. More information on configuring an MQeConnectionFactory can be found in Chapter 10 of the WebSphere MQ Everyplace Application Programming Guide.

See Also:
MQeJNDIConnectionFactory, MQeQueueConnectionFactory, MQeConnection

Constructor Summary
MQeConnectionFactory()
          Default constructor.
MQeConnectionFactory(java.lang.String iniName)
          Constructor taking a String containing the name of a initialization file.
 
Method Summary
 javax.jms.Connection createConnection()
          Creates a connection with the default user identity (the username and password are both set to 'default').
 javax.jms.Connection createConnection(java.lang.String username, java.lang.String password)
          Creates a connection with the specified user identity.
 java.lang.String getAuthenticatorClass()
          returns the name of the class being used for user authentication
 java.lang.String getClientID()
          Get the client identifier used by all connections created using this Factory.
 java.lang.String getDescription()
          Get the connection factory description.
 int getDUPSOKCount()
          Get the number of messages that a Session in DUPS_OK_ACKNOWLEDGE mode will receive before acknowledging the messages.
 java.lang.String getIniFileName()
          This method returns the name of the configuration (ini) file.
static boolean getJMSXEnabled()
          returns true if JMSX properties are included in a message when it is sent
 int getShutdownDelay()
          Returns the time for which we wait before shutting down the queue manager when the last connection is closed.
static boolean isSQLAllowed()
          Returns true if the SQL parser classes were found when the ConnectionFactory was instantiated.
 void setAuthenticatorClass(java.lang.String authenticator)
          Set the class to be used for username/password authentication.
 void setClientID(java.lang.String id)
          Set the client identifier to be used for all connections created using this Factory.
 void setDescription(java.lang.String desc)
          Set the connection factory description.
 void setDUPSOKCount(int count)
          Set the number of messages that a Session in DUPS_OK_ACKNOWLEDGE mode will accept before acknowledging the received messages.
 void setIniFileName(java.lang.String iniFile)
          This method sets the name of the configuration (ini) file which startQueueManager() uses to start a client queue manager.
 void setJMSXEnabled(boolean enabled)
          Enable or disable JMSX properties set on send (JMSXAppID, JMSXUserID).
 void setShutdownDelay(int delay)
          Set the time in milliseconds to pause before shutting down the queue manager when the last connection is closed.
 void setVerboseStartup(boolean verbose)
          Display diagnostic information during WebSphere MQ Everyplace Queue Manager startup.
 MQeQueueManager startQueueManager()
          This method is called when it is necessary to start an instance of the MQe queue manager.
 void stopQueueManager()
          This method is called by when the last active connection is closed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MQeConnectionFactory

public MQeConnectionFactory()
Default constructor. Creates a MQeConnectionFactory with default configuration values.


MQeConnectionFactory

public MQeConnectionFactory(java.lang.String iniName)
Constructor taking a String containing the name of a initialization file. This is equivalent to;

MQeConnectionFactory cf = new MQeConnectionFactory();
cf.setIniFileName("filename.ini");

Method Detail

createConnection

public javax.jms.Connection createConnection()
                                      throws javax.jms.JMSException
Creates a connection with the default user identity (the username and password are both set to 'default'). The connection is created in stopped mode. No messages will be delivered until the Connection.start method is explicitly called.

Returns:
a newly created connection
Throws:
javax.jms.JMSException - if the JMS provider fails to create the connection due to some internal error.
Since:
1.1

createConnection

public javax.jms.Connection createConnection(java.lang.String username,
                                             java.lang.String password)
                                      throws javax.jms.JMSException
Creates a connection with the specified user identity. The connection is created in stopped mode. No messages will be delivered until the Connection.start method is explicitly called.

Parameters:
password - the caller's password
Returns:
a newly created Connection
Throws:
javax.jms.JMSException - if the JMS provider fails to create the connection due to some internal error.
javax.jms.JMSSecurityException - if client authentication fails due to an invalid user name or password.
Since:
1.1

startQueueManager

public MQeQueueManager startQueueManager()
                                  throws javax.jms.JMSException
This method is called when it is necessary to start an instance of the MQe queue manager. By default, it tries to find an instance of the queue manager already running in the JVM. If this fails, then it uses the ini file (if one was specified) to start an instance of MQeJMSQueueManager. If no ini file is specified, and no queue manager is running in the JVM an exception is thrown.

This method can be overridden if the administrator wants to start a queue manager differently. Note that this method is public so that it can be overridden easily (from another package if necessary) and is not intended to be called directly. If this method is overridden then it may also be necessary to override stopQueueManager().

Returns:
The MQeQueueManager object that has been started.
Throws:
java.lang.Exception - propagated if there is an error starting the queue manager.
javax.jms.JMSException

stopQueueManager

public void stopQueueManager()
                      throws java.lang.Exception
This method is called by when the last active connection is closed. If startQueueManager() had started a client queue manager, this method stops it. If startQueueManager() found an instance of a running queue manager, this method doesn’t do anything.

Like startQueueManager, this method is public so that it can be overridden if required, rather than to enable it to be called directly.

Throws:
java.lang.Exception - propagated if there is an error stopping the queue manager.

setClientID

public final void setClientID(java.lang.String id)
Set the client identifier to be used for all connections created using this Factory.

Parameters:
id - The value to be set for the client Id

getClientID

public final java.lang.String getClientID()
Get the client identifier used by all connections created using this Factory.

Returns:
The value currently set for the client Id

setIniFileName

public final void setIniFileName(java.lang.String iniFile)
This method sets the name of the configuration (ini) file which startQueueManager() uses to start a client queue manager. If a queue manager is already running in the JVM then this parameter will be ignored.

Parameters:
iniFile - The name of the ini file to be used to start the queue manager.

getIniFileName

public final java.lang.String getIniFileName()
This method returns the name of the configuration (ini) file. This can be null.

Returns:
The name of the configuration (ini) file which will be used to start the queue manager.

setDescription

public final void setDescription(java.lang.String desc)
Set the connection factory description.


getDescription

public final java.lang.String getDescription()
Get the connection factory description.

Returns:
String The description

setDUPSOKCount

public final void setDUPSOKCount(int count)
                          throws javax.jms.JMSException
Set the number of messages that a Session in DUPS_OK_ACKNOWLEDGE mode will accept before acknowledging the received messages. The default value is 10. Setting this to 1 means that each message received is individually acknowledged - i.e. identical behaviour to a session in AUTO_ACKNOWLEDGE mode

Throws:
javax.jms.JMSException - if a zero or negative count in specified

getDUPSOKCount

public final int getDUPSOKCount()
Get the number of messages that a Session in DUPS_OK_ACKNOWLEDGE mode will receive before acknowledging the messages.

Returns:
int the number of messages to receive before acknowledgement

setVerboseStartup

public void setVerboseStartup(boolean verbose)
Display diagnostic information during WebSphere MQ Everyplace Queue Manager startup. This is intended for debugging purposes, and is set to false by default.


setShutdownDelay

public final void setShutdownDelay(int delay)
Set the time in milliseconds to pause before shutting down the queue manager when the last connection is closed. Must be greater than 0. A very short delay may lead to the Queue Manager shutting down before remote message delivery is complete. In this case, delivery will resume when the Queue Manager is next restarted.


getShutdownDelay

public final int getShutdownDelay()
Returns the time for which we wait before shutting down the queue manager when the last connection is closed. This gives messages sent shortly before shutdown a chance to be transmitted.


isSQLAllowed

public static final boolean isSQLAllowed()
Returns true if the SQL parser classes were found when the ConnectionFactory was instantiated.


setAuthenticatorClass

public final void setAuthenticatorClass(java.lang.String authenticator)
Set the class to be used for username/password authentication. This is used when creating a connection with createConnection(). By default this is set to com.ibm.mqe.jms.MQeJMSSimpleAuthenticator

Parameters:
authenticator - class

getAuthenticatorClass

public final java.lang.String getAuthenticatorClass()
returns the name of the class being used for user authentication

Returns:
classname

setJMSXEnabled

public final void setJMSXEnabled(boolean enabled)
Enable or disable JMSX properties set on send (JMSXAppID, JMSXUserID). If this is enabled then these properties are included in a message when it is sent. Disabling JMSX properties will reduce the amount of data sent across the network. Note that this does not affect JMSX properties that are set on receive (JMSXDeliveryCount, JMSXRcvTimestamp).

This is disabled by default.


getJMSXEnabled

public static final boolean getJMSXEnabled()
returns true if JMSX properties are included in a message when it is sent

Returns:
boolean

Websphere MQ Everyplace