Websphere MQ Everyplace

com.ibm.mqe.administration
Class MQeConnectionAdminMsg

java.lang.Object
  |
  +--com.ibm.mqe.MQe
        |
        +--com.ibm.mqe.MQeFields
              |
              +--com.ibm.mqe.MQeMsgObject
                    |
                    +--com.ibm.mqe.MQeAdminMsg
                          |
                          +--com.ibm.mqe.administration.MQeConnectionAdminMsg
All Implemented Interfaces:
MQeExceptionCodes

public class MQeConnectionAdminMsg
extends MQeAdminMsg

This class is used to manage Websphere MQ Everyplace connection definitions.

The class extends MQeAdminMsg and provides the implementation for managing connections.For information on basic administration concepts see MQeAdminMsg

The following actions are applicable on connections:

A connection defines how one queue manager establishes a connection to another queue manager. Once a connection has been defined, it is possible for a queue manager to manipulate messages on the remote queue manager either synchronously or asynchronsly.

Multiple connections can be defined on a queue manager but each must have a unique name. i.e. only one connection can be defined to a given destination.

A connection definition holds parameters that are used when establishing a logical connection called a channel between two queue managers. The channel is established dynamically as and when communication is required. A channel does not worry about the type of network or protocol, it hands this job to a communications adapter. The connection definition contains details on the type of channel and the type of adapter to use for a connection. Information on the supplied set of adapters can be found in package com.ibm.mqe.adapters

As well as specifying the adapter, data required by the adapater is required. The adapter field defines not just the adapter but the basic parameters required by the adatper. This is called a file descriptor and takes the form:

For instance com.ibm.mqe.adpaters.MQeTcpipHttpAdapter:192.168.0.1:8082 defines an http adapter that communicates with another queue manager on host 192.168.0.1 and port 8082.

Network:192.168.0.1:8081 defines an adapter called "Network" which is an alias for the MQeTcpipHttpAdapter that communicates with another queue manager on host 192.168.0.1 and port 8082.

A connection contains an array of one or more adapters. This version of WebSphere MQ Everyplace only supports the definition of one adapter in the adapter array.

It is important that the adapter and its parameters match that of the communication listener on the queue manager being connected to. If there is a mismatch then communications between the two queue managers will fail. For information on administering communications listeners see MQeCommunicationsListenerAdminMsg.

Connection types

Several types of connection can be defined:

Direct
Specify how one queue manager communicates directly to another using an adapter to handle the communications
Routing or via
Specify how one queue manager communicates to another queue manager via or routed through another queue manager. Using via connections it is possible for messages to be routed through multiple queue managers in order to get to the target queue manager. In order to define a via connection a connection to the next hop must already exist.
Local or no-op
A special type of connection which is a definition of another queue manager but not how to communicate with it. This is typically used for:

The table below shows how the different types of connection are defined:
Connection type Name Adapter Array Adapter file descriptor Adapter parameters Adapter options Channel
Direct mandatory One adapter mandatory optional optional mandatory
Via mandatory One adapter name of next hop no no no
no op mandatory no null no no null

Additional information can be passed to the adapter via the adapter parameters and options fields. For instance if the connection is to a queue manager running as a servlet then the adapter parameter can contain the name of the servlet.

Aliases

Multiple names or aliases can be assigned to a connection. When an application calls methods on a queue manager that require a queue manager name be specified, an alias can also be used. Both a local and remote queue managers can be aliased.

When creating a connection definition it is important a reply is obtained on the success of the request before attempting to use that connection definition. For this reason it is recommended that when creating a connection definition the reply to queue manager is always set to either the local queue manager or a queue manager with an existing connection definition. *

For an example of how to use this class, Example2

Properties of the Connection resource (in addition to those inherited - see MQeAdminMsg)
Field name Actions using these fields
Con_Description MQeAdminMsg.Action_Inquire, MQeAdminMsg.Action_Create, MQeAdminMsg.Action_Update.
Con_Adapters MQeAdminMsg.Action_Inquire, MQeAdminMsg.Action_Create, MQeAdminMsg.Action_Update.
Con_Adapter MQeAdminMsg.Action_Inquire, MQeAdminMsg.Action_Create, MQeAdminMsg.Action_Update.
Con_AdapterAsciiParm MQeAdminMsg.Action_Inquire, MQeAdminMsg.Action_Create, MQeAdminMsg.Action_Update.
Con_AdapterOptions MQeAdminMsg.Action_Inquire, MQeAdminMsg.Action_Create, MQeAdminMsg.Action_Update.
Con_Aliases MQeAdminMsg.Action_Inquire, MQeAdminMsg.Action_Create, MQeAdminMsg.Action_Update.


Field Summary
static java.lang.String Con_Adapter
          String used to identify the field in the message representing an adapter file descriptor.
static java.lang.String Con_AdapterAsciiParm
          String used to identify the field in the message representing parameters for an adapter.
static java.lang.String Con_AdapterOptions
          String used to identify the field in the message representing options for an adapter.
static java.lang.String Con_Adapters
          String used to identify the field in the message representing a set of communications adapters and parameters.
static java.lang.String Con_Aliases
          String used to identify the field in the message representing a set of aliases for the connection.
static java.lang.String Con_Channel
          String used to identify the field in the message representing the type of channel.
static java.lang.String Con_Description
          String used to identify the field in the admin message representing the description of the listener.
 
Fields inherited from class com.ibm.mqe.MQeAdminMsg
Action_AddAlias, Action_Create, Action_Delete, Action_Inquire, Action_InquireAll, Action_RemoveAlias, Action_Start, Action_Stop, Action_Unknown, Action_Update, Admin_Action, Admin_Class, Admin_Errors, Admin_MaxAttempts, Admin_Name, Admin_Parms, Admin_RC, Admin_Reason, Admin_TargetQMgr, RC_Fail, RC_Mixed, RC_Success
 
Fields inherited from class com.ibm.mqe.MQeFields
ArraySeparator, TypeArrayElements, TypeAscii, TypeBoolean, TypeByte, TypeDouble, TypeFields, TypeFloat, TypeInt, TypeLong, TypeShort, TypeUnicode, TypeUnTyped
 
Fields inherited from class com.ibm.mqe.MQe
Admin_Queue_Name, Admin_Reply_Queue_Name, copyright, DeadLetter_Queue_Name, Event_Activate, Event_Attribute, Event_Authenticate, Event_Close, Event_Logoff, Event_Logon, Event_MiniCert_Validate, Event_Queue, Event_QueueManager, Event_UserBase, JMS_Version, MQ_Headers, MQe_Log_Audit_Failure, MQe_Log_Audit_Success, MQe_Log_Error, MQe_Log_Information, MQe_Log_Success, MQe_Log_Warning, Msg_BackoutCount, Msg_CorrelID, Msg_ExpireTime, Msg_LockID, Msg_MsgID, Msg_OriginQMgr, Msg_Priority, Msg_ReplyToQ, Msg_ReplyToQMgr, Msg_Resend, Msg_Style, Msg_Style_Datagram, Msg_Style_Reply, Msg_Style_Request, Msg_Time, Msg_WrapMsg, sccsid, System_Default_Queue_Name, version
 
Fields inherited from interface com.ibm.mqe.MQeExceptionCodes
Except_Active, Except_AdapterException, Except_AdapterMissingRemoteAddress, Except_Admin_ActionNotSupported, Except_Admin_InvalidField, Except_Admin_NotAdminMsg, Except_AdminAction, Except_Authenticate, Except_BadRequest, Except_BridgeListener, Except_Chnl_Attributes, Except_Chnl_ID, Except_Chnl_Limit, Except_Chnl_Overrun, Except_Closed, Except_Con_AdapterRequired, Except_Con_AliasAlreadyExists, Except_Con_AlreadyExists, Except_Con_InvalidName, Except_Connect_Failure, Except_ConnectonType, Except_Cryptor, Except_Data, Except_Duplicate, Except_JmxProperties, Except_Listener, Except_MessageStore, Except_MiniCertReg_ActivateFailed, Except_MiniCertReg_BadPIN, Except_MiniCertReg_NotOpen, Except_NotActive, Except_NotAllowed, Except_NotFound, Except_NotSupported, Except_PrivateReg_ActivateFailed, Except_PrivateReg_BadPIN, Except_PrivateReg_NotOpen, Except_PublicReg_ActivateFailed, Except_PublicReg_InvalidAddress, Except_PublicReg_InvalidRequest, Except_Q_Full, Except_Q_InvalidName, Except_Q_InvalidPriority, Except_Q_MsgTooLarge, Except_Q_NoMatchingMsg, Except_Q_TargetRegistryRequired, Except_QMgr_Activated, Except_QMgr_AlreadyExists, Except_QMgr_InvalidQMgrName, Except_QMgr_InvalidQName, Except_QMgr_NotActive, Except_QMgr_NotBridgeEnabled, Except_QMgr_NotConfigured, Except_QMgr_QDoesNotExist, Except_QMgr_QExists, Except_QMgr_QNotEmpty, Except_QMgr_RegistryDataVersion, Except_QMgr_UnknownQMgr, Except_QMgr_WrongQType, Except_Reg_AddFailed, Except_Reg_AlreadyExists, Except_Reg_AlreadyOpen, Except_Reg_CRTKeyDecFailed, Except_Reg_CRTKeySignFailed, Except_Reg_DeleteFailed, Except_Reg_DeleteRegistryFailed, Except_Reg_DoesNotExist, Except_Reg_InvalidSession, Except_Reg_ListFailed, Except_Reg_NotDefined, Except_Reg_NotSecure, Except_Reg_NullName, Except_Reg_OpenFailed, Except_Reg_ReadFailed, Except_Reg_RenameFailed, Except_Reg_ResetPINFailed, Except_Reg_SearchFailed, Except_Reg_UpdateFailed, Except_RemoteException, Except_Rule, Except_S_BadIntegrity, Except_S_BadSubject, Except_S_CertificateExpired, Except_S_Cipher, Except_S_InvalidAttribute, Except_S_InvalidSignature, Except_S_MiniCertNotAvailable, Except_S_MissingSection, Except_S_NoPresetKeyAvailable, Except_S_RegistryNotAvailable, Except_Stopped, Except_Syntax, Except_TimeOut, Except_Transporter, Except_TriggerTransmission, Except_Trnsport_QMgr, Except_Trnsport_Request, Except_Type, Except_UdpipAdapterStateException, Except_UdpipAdapterTimeOut, Except_UdpipAdapterUnableToConfirmSuccess, Except_UnCoded, Except_Uncontactable_DontTransmit
 
Constructor Summary
MQeConnectionAdminMsg()
          Default constructor.
MQeConnectionAdminMsg(java.lang.String qMgrName)
          This constructor takes the name of the connection and puts it into the admin msg.
 
Method Summary
 void addAlias(java.lang.String alias)
          Setup the admin message to add an alias to the connection.
 void changeAlias(java.lang.String alias)
          Adds an alias name to the aliases array.
 void create(java.lang.String adapter, java.lang.String parameters, java.lang.String options, java.lang.String channel, java.lang.String desc)
          Setup the administration message to create a connection.
 void removeAlias(java.lang.String alias)
          Setup the admin message to remove an alias from the connection.
 void update(java.lang.String adapter, java.lang.String parameters, java.lang.String options, java.lang.String channel, java.lang.String desc)
          Setup the administration message to update a connection.
 
Methods inherited from class com.ibm.mqe.MQeAdminMsg
characteristics, create, delete, duplicate, getAction, getErrorFields, getFieldInError, getInputFields, getMaxAttempts, getName, getOutputFields, getRC, getReason, getTargetQMgr, inquire, inquireAll, setAction, setMaxAttempts, setName, setTargetQMgr, update
 
Methods inherited from class com.ibm.mqe.MQeMsgObject
getMsgUIDFields, getOriginQMgr, getTimeStamp, putOriginQMgr, resetMsgUIDFields, unwrapMsgObject
 
Methods inherited from class com.ibm.mqe.MQeFields
contains, copy, copy, dataType, deepCopy, delete, dump, dumpedType, dumpToString, equals, fields, getArrayLength, getArrayOfByte, getArrayOfDoubleAsLong, getArrayOfFloatAsInt, getArrayOfInt, getArrayOfLong, getArrayOfShort, getAscii, getAsciiArray, getAttribute, getBoolean, getByte, getDoubleAsLong, getFields, getFieldsArray, getFloatAsInt, getInt, getIntArray, getLong, getLongArray, getObject, getShort, getShortArray, getUnicode, getUnicodeArray, includes, isEqualTo, putArrayLength, putArrayOfByte, putArrayOfDoubleAsLong, putArrayOfFloatAsInt, putArrayOfInt, putArrayOfLong, putArrayOfShort, putAscii, putAsciiArray, putBoolean, putByte, putByteArray, putDoubleAsLong, putFields, putFieldsArray, putFloatAsInt, putInt, putIntArray, putLong, putLongArray, putObject, putShort, putShortArray, putUnicode, putUnicodeArray, rename, restore, restoreFromString, restoreFromString, restoreFromString, setAttribute, updateValue
 
Methods inherited from class com.ibm.mqe.MQe
abbreviate, alias, asciiToByte, byteToAscii, byteToHex, byteToHex, byteToInt, byteToLong, byteToShort, byteToUnicode, fileSeparator, getEventLogHandler, hexToAscii, hexToByte, intToByte, isCLDC, loadClass, loadObject, log, setEventLogHandler, setLoader, sliceByteArray, type, unicodeToByte, uniqueValue
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

Con_Description

public static final java.lang.String Con_Description
String used to identify the field in the admin message representing the description of the listener.

The field is of type unicode

See Also:
Constant Field Values

Con_Channel

public static final java.lang.String Con_Channel
String used to identify the field in the message representing the type of channel.

Use either the class name or class alias for the channel that this connection will use. For instance com.ibm.mqe.MQeChannel or DefaultChannel.

The field is manadatory for a direct connection and can be null for other types of connection.

The field is of type ascii

See Also:
Constant Field Values

Con_Adapters

public static final java.lang.String Con_Adapters
String used to identify the field in the message representing a set of communications adapters and parameters.

The field is an array of MQeFields objects where each entry represents an adapter and its parameters. The current version of the product only supports a maximum of one entry in the array.

Each MQeFields entry in the array can consist of the following fields:

The field is mandatory for direct and via connections.

The field is of type MQeFields Array

See Also:
Constant Field Values

Con_Adapter

public static final java.lang.String Con_Adapter
String used to identify the field in the message representing an adapter file descriptor.

This field is contained in an MQeFields object that is stored in field Con_Adapters.

The file descriptor takes the form:

For example,

Network:192.168.0.3:8085
make a connection to a queue manager on host 192.168.0.3 port 8085
QueueMgr5
To get to the target queue manager go via QueueMgr5

The field is mandatory for direct and via connections.

The field is of type ascii

See Also:
Con_Adapters, com.ibm.mqe.adapters, Constant Field Values

Con_AdapterAsciiParm

public static final java.lang.String Con_AdapterAsciiParm
String used to identify the field in the message representing parameters for an adapter.

This field is contained in an MQeFields object that is stored in field Con_Adapters.

For example when using an http adapter to communicate with a queue manager running in a servlet, this field can contain the name of the servlet like /servet/MQe.

The field is of type ascii

See Also:
Con_Adapter, Con_Adapters, com.ibm.mqe.adapters, Constant Field Values

Con_AdapterOptions

public static final java.lang.String Con_AdapterOptions
String used to identify the field in the message representing options for an adapter.

This field is contained in an MQeFields object that is stored in field Con_Adapters.

For example when using a tcpip length adapter the following options can be used: or .

The field is of type ascii

See Also:
Con_Adapter, Con_Adapters, com.ibm.mqe.adapters, Constant Field Values

Con_Aliases

public static final java.lang.String Con_Aliases
String used to identify the field in the message representing a set of aliases for the connection.

Multiple names or aliases can be assigned to a connection. This field holds the set of aliases.

The field is of type ascii array

See Also:
Constant Field Values
Constructor Detail

MQeConnectionAdminMsg

public MQeConnectionAdminMsg()
                      throws java.lang.Exception
Default constructor.

Throws:
java.lang.Exception

MQeConnectionAdminMsg

public MQeConnectionAdminMsg(java.lang.String qMgrName)
                      throws java.lang.Exception
This constructor takes the name of the connection and puts it into the admin msg.

This constructor uses the MQeAdminMsg.setName(String) method to put the name into the administratoin message parameters field

Throws:
java.lang.Exception
See Also:
MQeAdminMsg.setName(String)
Method Detail

addAlias

public void addAlias(java.lang.String alias)
              throws java.lang.Exception
Setup the admin message to add an alias to the connection.

A method that assists in setting up an administratoin message to add one or more aliases to a connection definition. Multiple aliases can be added in one message by calling the method multiple times. The message is set to perform action MQeAdminMsg.Action_AddAlias.

The following basic fields are set:

The following fields are set in the Admin_Parms field.

The name of the connection to add an alias to is specified using method MQeAdminMsg.setName(java.lang.String) or using the constructor that takes the resource name or by setting the MQeAdminMsg.Admin_Name field.

Parameters:
alias - the alias to add to the connection.
Throws:
java.lang.Exception
See Also:
MQeAdminMsg.Action_AddAlias, Con_Aliases

changeAlias

public void changeAlias(java.lang.String alias)
                 throws java.lang.Exception
Adds an alias name to the aliases array. Used internally by addAlias and removeAlias.

Parameters:
alias - java.lang.String
Throws:
java.lang.Exception

create

public void create(java.lang.String adapter,
                   java.lang.String parameters,
                   java.lang.String options,
                   java.lang.String channel,
                   java.lang.String desc)
            throws java.lang.Exception
Setup the administration message to create a connection.

A method that assists the construction of a connection administration message in order to create a connection. The message is set to perform action MQeAdminMsg.Action_Create.

The following basic fields are set:

The following fields are set in the Admin_Parms field.

The name of the connection to be created is specified using method MQeAdminMsg.setName(java.lang.String) or using the constructor that takes the resource name or by setting the MQeAdminMsg.Admin_Name field.

Parameters:
adapter - File descriptor for the adapter.
options - Adapter options
channel - Type of channel to use
Throws:
java.lang.Exception
See Also:
com.ibm.mqe.adapters, MQeAdminMsg.Action_Create
Example:
 MQeConnectionAdminMsg con = new MQeConnectionAdminMsg();
 
 con.setName("ServerQM123");
 con.create("Network:127.0.0.1:8081",
     null,
     null,
     "DefaultChannel",
     "Con to MQeServer");
 
 MQeConnectionAdminMsg con2 = new MQeConnectionAdminMsg();
 
 con2.setName("ServletQM123");
 con2.create("Network:127.0.0.1:8081",
     "/servlet/MQe",
     null,
     "DefaultChannel",
     "Con to MQeServlet");
 
 

removeAlias

public void removeAlias(java.lang.String alias)
                 throws java.lang.Exception
Setup the admin message to remove an alias from the connection.

A method that assists in setting up an administratoin message to remove one or more aliases from a connection. Multiple aliases can be removed in one message by calling the method multiple times. The message is set to perform action MQeAdminMsg.Action_RemoveAlias.

The following basic fields are set:

The following fields are set in the Admin_Parms field.

The name of the connection to remove an alias from is specified using method MQeAdminMsg.setName(java.lang.String) or using the constructor that takes the resource name or by setting the MQeAdminMsg.Admin_Name field.

Parameters:
alias - the alias to remove from a connection.
Throws:
java.lang.Exception
See Also:
MQeAdminMsg.Action_RemoveAlias, Con_Aliases

update

public void update(java.lang.String adapter,
                   java.lang.String parameters,
                   java.lang.String options,
                   java.lang.String channel,
                   java.lang.String desc)
            throws java.lang.Exception
Setup the administration message to update a connection.

A method that assists the construction of a connection administration message in order to update a connection. The message is set to perform action MQeAdminMsg.Action_Update.

The following basic fields are set:

The following fields are set in the Admin_Parms field.

The name of the connection to be updated is specified using method MQeAdminMsg.setName(java.lang.String) or using the constructor that takes the resource name or by setting the MQeAdminMsg.Admin_Name field.

Parameters:
adapter - File descriptor for the adapter.
options - Adapter options
channel - Type of channel to use
desc - Description of connection
Throws:
java.lang.Exception
See Also:
com.ibm.mqe.adapters, MQeAdminMsg.Action_Update
Example:
 MQeConnectionAdminMsg con = new MQeConnectionAdminMsg();
 
 con.setName("ServerQM123");
 con.update("Network:127.0.0.1:8082",
     null,
     null,
     "DefaultChannel",
     "Con to MQeServer");
 
 

Websphere MQ Everyplace