Websphere MQ Everyplace

com.ibm.mqe.administration
Class MQeCommunicationsListenerAdminMsg

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

public final class MQeCommunicationsListenerAdminMsg
extends MQeAdminMsg

This class is used to manage WebSphere MQ Everyplace communications listeners.

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

The following actions are applicable:

A listener handles new incoming communications requests, assisting the setup of the slave half of a channel. The main attributes of the listener that can be configured by the admin message are:

A channel forms a logical pipe between two queue managers. The pipe may run across many different network types and many different network protocols. The client or master end of a channel is configured using an MQeConnectionAdminMsg. The server end or slave end is configured using this admin message. It is important that both the client and server end specifiy the same protocol. The protocol and associated parameters are encapsulated in communications adapters. For information on the supplied set of adapters see package com.ibm.mqe.adapters

If a queue manager runs as a true client then no listeners need be configured. If it is to run as a server then one or more listeners may be configured. Each listener can listen using different protocols or the same protocol but different parameters

For examples of how to use this class, see classes starting Listener* in package examples.administration.commandline

Properties of the Communications Listener resource (in addition to those inherited - see MQeAdminMsg)
Field name Actions using these fields
LISTENER_PROTOCOL MQeAdminMsg.Action_Inquire, MQeAdminMsg.Action_Create.
LISTENER_CHANNEL_TIMEOUT MQeAdminMsg.Action_Inquire, MQeAdminMsg.Action_Create, MQeAdminMsg.Action_Update.
LISTENER_MAXIMUM_CHANNELS MQeAdminMsg.Action_Inquire, MQeAdminMsg.Action_Create, MQeAdminMsg.Action_Update.
LISTENER_CURRENT_CHANNELS MQeAdminMsg.Action_Inquire.
LISTENER_DESCRIPTION MQeAdminMsg.Action_Inquire, MQeAdminMsg.Action_Create, MQeAdminMsg.Action_Update.
LISTENER_RUNNING MQeAdminMsg.Action_Inquire.


Field Summary
static java.lang.String LISTENER_CHANNEL_TIMEOUT
          String used to identify the field in the message representing the timeout value for any channels owned by the listener.
static java.lang.String LISTENER_CURRENT_CHANNELS
          String used to identify the field in the message representing the current number of open channels the listener has.
static long LISTENER_DEFAULT_CHANNEL_TIMEOUT
          Default value of LISTENER_CHANNEL_TIMEOUT is 5 minutes.
static int LISTENER_DEFAULT_MAX_CHANNELS
          Default value of LISTENER_MAX_CHANNELS is 0 meaning no maximum.
static java.lang.String LISTENER_DESCRIPTION
          String used to identify the field in the message representing the description of the listener.
static java.lang.String LISTENER_MAXIMUM_CHANNELS
          String used to identify the field in the message representing the maximum number of channels the listener can have open at any one time.
static java.lang.String LISTENER_PROTOCOL
          String identifying the field in the message representing the protocol upon which the listener listens.
static java.lang.String LISTENER_RUNNING
          String used to identify the field in the message representing the current state 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
MQeCommunicationsListenerAdminMsg()
          Construct an empty MQeCommunicationsListenerAdminMsg.
MQeCommunicationsListenerAdminMsg(java.lang.String listenerName)
          This constructor takes the name of the listener and puts it into the admin msg.
 
Method Summary
 MQeFields characteristics()
          Return an MQeFields object containing the characteristics of the resource.
 void create(MQeFields listenProtocol, long channelTimeout, int maxChannels)
          Setup the admin message to create a communications listener.
 void create(java.lang.String commsAdapter, int port)
          Setup the admin message to create a communications listener.
 void create(java.lang.String commsAdapter, int port, long channelTimeout, int maxChannels)
          Setup the admin message to create a communications listener.
 void start()
          Setup the admin message to start a listener.
 void stop()
          Setup the admin message to stop a listener The name of the listener 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.
 
Methods inherited from class com.ibm.mqe.MQeAdminMsg
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

LISTENER_PROTOCOL

public static final java.lang.String LISTENER_PROTOCOL
String identifying the field in the message representing the protocol upon which the listener listens.

The field is of type MQeFields and is used to contains a set of unicode fields relating to the protocol the listener will listen on. It is mandatory that field MQeCommunicationsAdapter.COMMS_ADAPTER_CLASS be included when creating a listener. This field specifies the name of the communications adapter Other adapter parameters are optional but are likely to include MQeCommunicationsAdapter.COMMS_ADAPTER_PORT which specifies the port to listen on.

The field is of type MQeFields, and is mandatory in the following actions:

This field can only be set when the listener is created

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

LISTENER_CHANNEL_TIMEOUT

public static final java.lang.String LISTENER_CHANNEL_TIMEOUT
String used to identify the field in the message representing the timeout value for any channels owned by the listener.

The field is of type long and contains the time in milliseconds that idle incoming channels live before being timed out. The value may be zero in which case no channel timeout will be set, otherwise it must represent a positive value.

See Also:
Constant Field Values

LISTENER_MAXIMUM_CHANNELS

public static final java.lang.String LISTENER_MAXIMUM_CHANNELS
String used to identify the field in the message representing the maximum number of channels the listener can have open at any one time.

The field is of type int. The value may be zero in which case no limit will be set to the number of channels allowed, otherwise it must represent a positive value.

See Also:
Constant Field Values

LISTENER_DEFAULT_MAX_CHANNELS

public static final int LISTENER_DEFAULT_MAX_CHANNELS
Default value of LISTENER_MAX_CHANNELS is 0 meaning no maximum.

See Also:
Constant Field Values

LISTENER_DEFAULT_CHANNEL_TIMEOUT

public static final long LISTENER_DEFAULT_CHANNEL_TIMEOUT
Default value of LISTENER_CHANNEL_TIMEOUT is 5 minutes.

See Also:
Constant Field Values

LISTENER_CURRENT_CHANNELS

public static final java.lang.String LISTENER_CURRENT_CHANNELS
String used to identify the field in the message representing the current number of open channels the listener has.

The field is of type int, and is read only - it is only valid as part of an inquire request

See Also:
Constant Field Values

LISTENER_DESCRIPTION

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

The field is of type Unicode

See Also:
Constant Field Values

LISTENER_RUNNING

public static final java.lang.String LISTENER_RUNNING
String used to identify the field in the message representing the current state of the listener.

The field is of type boolean, and is read only, it is only valid as part of an inquire

See Also:
Constant Field Values
Constructor Detail

MQeCommunicationsListenerAdminMsg

public MQeCommunicationsListenerAdminMsg()
                                  throws java.lang.Exception
Construct an empty MQeCommunicationsListenerAdminMsg.

Throws:
java.lang.Exception - The exception description.

MQeCommunicationsListenerAdminMsg

public MQeCommunicationsListenerAdminMsg(java.lang.String listenerName)
                                  throws java.lang.Exception
This constructor takes the name of the listener and puts it into the admin msg.

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

Parameters:
listenerName - The name of the communications listener to manage.
Throws:
java.lang.Exception
Method Detail

characteristics

public MQeFields characteristics()
                          throws java.lang.Exception
Description copied from class: MQeAdminMsg
Return an MQeFields object containing the characteristics of the resource.

The complete set of field names and types for the resource can be determined from the resulting MQeFields object. (It does not contain the value of each characteristic)

Overrides:
characteristics in class MQeAdminMsg
Returns:
An MQeFields object containing the valid characteristics of the resource
Throws:
java.lang.Exception
See Also:
MQeAdminMsg.characteristics()

create

public final void create(java.lang.String commsAdapter,
                         int port)
Setup the admin message to create a communications listener.

A method that assists the construction of a communications listener administration message for a listener that will listen on a TCPIP based protocol.The message is setup to perform action MQeAdminMsg.Action_Create

Attempts to create a new resource with the specified characteristic. The MQeAdminMsg.Admin_Action and MQeAdminMsg.Admin_Parms fields are set by this method

The name of the listener 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.

This method supplies the default values for listenerTimeout and maxChannels.

Parameters:
commsAdapter - a string containing the name of the communications adapter that the listener will use to listen with.
port - an int specifiying the port that the listener will listen on.
Returns:
void
See Also:
com.ibm.mqe.adapters, MQeAdminMsg.Action_Create
Example:
 System.out.println("Build admin message to create a listener");
 MQeCommunicationsListenerAdminMsg msg = new MQeCommunicationsListenerAdminMsg();
 
 msg.setName(listenerName);
 msg.create(listenAdapter, listenPort, channelTimeout, maxChannels);
 
 MQeFields results = sendWaitMessage(myQMgr, targetQMgr, msg);
 
 System.out.println("Listener created successfully.");
 
 

create

public final void create(java.lang.String commsAdapter,
                         int port,
                         long channelTimeout,
                         int maxChannels)
Setup the admin message to create a communications listener.

A method that assists the construction of a communications listener administration message for a listener that will listen on a TCPIP based protocol. The message is setup to perform action MQeAdminMsg.Action_Create.

Attempts to create a new resource with the specified characteristic. The MQeAdminMsg.Admin_Action and MQeAdminMsg.Admin_Parms fields are set by this method

The name of the listener 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:
commsAdapter - a string containing the name of the communications adapter that the listener will use to listen with.
port - an int specifiying the port that the listener will listen on.
channelTimeout - a long specifying the time in milliseconds that idle incoming channels are kept alive. If this value is zero the channels are not timed out, otherwise it must represent a postive value or an exception will be thrown and the value not used. This parameter is used to set field LISTENER_CHANNEL_TIMEOUT in the admin message.
maxChannels - an int specifying the maximum number of channels the listener can have open at any one time. If this value is zero there is no maximum limit put on the number of channels allowed, otherwise it must represent a postive value or an exception will be thrown and the value not used. This parameter is used to set field LISTENER_MAXIMUM_CHANNELS in the admin message.
Returns:
void
See Also:
com.ibm.mqe.adapters, MQeAdminMsg.Action_Create
Example:
 System.out.println("Build admin message to create a listener");
 MQeCommunicationsListenerAdminMsg msg = new MQeCommunicationsListenerAdminMsg();
 
 msg.setName(listenerName);
 msg.create(listenAdapter, listenPort, channelTimeout, maxChannels);
 
 MQeFields results = sendWaitMessage(myQMgr, targetQMgr, msg);
 
 System.out.println("Listener created successfully.");
 
 

create

public final void create(MQeFields listenProtocol,
                         long channelTimeout,
                         int maxChannels)
Setup the admin message to create a communications listener.

A method that assists the construction of a communications listener administration message.The message is setup to perform action MQeAdminMsg.Action_Create

Attempts to create a new resource with the specified characteristic. The MQeAdminMsg.Admin_Action and MQeAdminMsg.Admin_Parms fields are set by this method

The name of the listener 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:
listenProtocol - an MQeFields object that contains a set of unicode fields relating to the protocol the listener will listen on. See description of field LISTENER_PROTOCOL for more details.
channelTimeout - a long specifying the time in milliseconds that idle incoming channels are kept alive. This parameter is used to set field LISTENER_CHANNEL_TIMEOUT in the admin message.
maxChannels - an int specifying the maximum number of channels the listener can have open at any one time. This parameter is used to set field LISTENER_MAXIMUM_CHANNELS in the admin message.
Returns:
void
See Also:
com.ibm.mqe.adapters, MQeAdminMsg.Action_Create
Example:
 System.out.println("Build admin message to create a listener");
 MQeCommunicationsListenerAdminMsg msg = new MQeCommunicationsListenerAdminMsg();
 
 msg.setName(listenerName);
 msg.create(listenAdapter, listenPort, channelTimeout, maxChannels);
 
 MQeFields results = sendWaitMessage(myQMgr, targetQMgr, msg);
 
 System.out.println("Listener created successfully.");
 
 

start

public final void start()
Setup the admin message to start a listener. The name of the listener 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.

Returns:
void
Example:
 System.out.println("Build an admin message to start a listner");
 MQeCommunicationsListenerAdminMsg msg = new MQeCommunicationsListenerAdminMsg();
 
 msg.setName(listenerName);
 msg.start();
 
 MQeFields results = sendWaitMessage(myQMgr, targetQMgr, msg);
 
 System.out.println("Listener started successfully.");
 
 

stop

public final void stop()
Setup the admin message to stop a listener The name of the listener 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.

Returns:
void
Example:
 System.out.println("Build an admin message to stop a listener");
 MQeCommunicationsListenerAdminMsg msg = new MQeCommunicationsListenerAdminMsg();
 
 msg.setName(listenerName);
 msg.stop();
 
 MQeFields results = sendWaitMessage(myQMgr, targetQMgr, msg);
 
 System.out.println("Listen stopped successfully.");
 
 

Websphere MQ Everyplace