|
Websphere MQ Everyplace | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.ibm.mqe.MQe | +--com.ibm.mqe.MQeFields | +--com.ibm.mqe.MQeMsgObject | +--com.ibm.mqe.MQeAdminMsg
This class is used to create a basic MQeAdminMsg. The class extends
MQeMsgObject
and provides a base for all administration
messages. Descendants of this class are created to administer different types
of resource.
A typical administration application instantiates a subclass of MQeAdminMsg, configures it with the required administration request, and passes it to the administration queue on the target queue manager. If the application wishes to know the outcome of the action, a reply can be requested. When the request has been processed the result of is returned in a message to the reply-to queue and queue manager specified in the request message. Performing administration using messages provides location transparent administration. A resource can be administered either locally on the owning queue manager or from a remote queue manager using the same administration message.
There are two default queues that can be used for administration requests
MQe.Admin_Queue_Name
MQe.Admin_Reply_Queue_Name
Every administration messages takes the same basic form.
Breaking each section into more down:
Base admin field items | |
---|---|
Admin_Action
| What administration action to perform |
Admin_TargetQMgr
| The name of the queue manager where the action is to be performed. |
Fields specific to the resource being managed | |
Admin_Parms
| Input parameters to the action. For example Admin_Name |
Optional fields (commonly used) | |
MQe.Msg_Style
| Is is a datagram or request message. i.e is a reply required. |
MQe.Msg_ReplyToQ
| Name of the reply to queue |
MQe.Msg_ReplyToQMgr
| Name of the reply to queue manager |
MQe.Msg_MsgID
| A message identifier |
MQe.Msg_CorrelID
| A message correlation identifier. Typically used to match a request message to a treply message. |
A reply message is a copy of the request message with a number of new fields together with updates to existing fields. The table below shows the main changes in a reply message:
Base admin field items | |
---|---|
Admin_RC
| Return code detailing whether the action worked or not. |
Admin_Reason
| If the action failed the main reason is contained in this field |
Fields specific to the resource being managed | |
Admin_Parms
| Output parameters from the action. For instance if the request was an inquiry then the result is contained in the field. |
Admin_Errors
| Detailed description of any errors. |
Optional fields | |
None. |
There are several ways that administration messages can be setup and manipulated:
setName(java.lang.String)
| Sets the name of the resource to be managed. |
setAction(int)
| Sets the action to be performed. |
getInputFields()
| Get the Admin_Parms field from the message. If it does not exist create and return an empty one. |
create(com.ibm.mqe.MQeFields)
| Request that a new resource be created. |
getRC()
| Retrive the return code from a reply message |
Each type of resource that can be managed has its own administration message that is derived from MQeAdminMsg. Administration message for the core manageable objects are found in package com.ibm.mqe.administration. Administration messages for bridge related manageable objects are found in package com.ibm.mqe.mqbridge
A number of examples that demonstrates various ways to use administration messages can be found in packages:
Field Summary | |
static int |
Action_AddAlias
Action to use when adding an alias to a resource. |
static int |
Action_Create
Action to use when creating a resource. |
static int |
Action_Delete
Action to use when deleting a resource. |
static int |
Action_Inquire
Action to use when inquiring on one or more characteristics of a resource. |
static int |
Action_InquireAll
Action to use when inquiring on all characteristics of a resource. |
static int |
Action_RemoveAlias
Action to use when removing an alias from a resouce. |
static int |
Action_Start
Action to use when starting a resouce. |
static int |
Action_Stop
Action to use when stopping a resource. |
static int |
Action_Unknown
Action is unknown or has not been set. |
static int |
Action_Update
Action to use when updating a resource. |
static java.lang.String |
Admin_Action
Name of the field that contains the administration action that is to be performed. |
static java.lang.String |
Admin_Class
Name of the field that contains the type of the resource being managed. |
static java.lang.String |
Admin_Errors
The name of a field that contains detailed error information. |
static java.lang.String |
Admin_MaxAttempts
The name of the field that contains the maximum number of times a request is tried. |
static java.lang.String |
Admin_Name
Name of the field that contains the name of the resource to be managed. |
static java.lang.String |
Admin_Parms
Name of the field that contains the resource characteristics that are required for or returned by an action. |
static java.lang.String |
Admin_RC
Name of the field that contains the overall result of the action. |
static java.lang.String |
Admin_Reason
Name of the field that contains the overall reason for any failure. |
static java.lang.String |
Admin_TargetQMgr
Name of the field that contains the name of the queue manager on which the requested action is to take place (the target queue manager). |
static int |
RC_Fail
Return code used when the request fails. |
static int |
RC_Mixed
Return code used when the request is partially successul. |
static int |
RC_Success
Return code used when the request completes successfully. |
Fields inherited from class com.ibm.mqe.MQeFields |
ArraySeparator, TypeArrayElements, TypeAscii, TypeBoolean, TypeByte, TypeDouble, TypeFields, TypeFloat, TypeInt, TypeLong, TypeShort, TypeUnicode, TypeUnTyped |
Constructor Summary | |
MQeAdminMsg()
The constructor creates and initializes a default MQeAdminMsg. |
Method Summary | |
MQeFields |
characteristics()
Return an MQeFields object containing the
characteristics of the resource. |
void |
create(MQeFields parms)
Sets up an administration message to run the Action_Create action. |
void |
delete(MQeFields parms)
Sets up an administration message to run the Action_Delete
action. |
MQeAdminMsg |
duplicate()
Creates a duplicate administration message. |
int |
getAction()
Returns the administration action that is to be, or has been performed. |
MQeFields |
getErrorFields()
Returns a reference to the error fields object. |
java.lang.String[] |
getFieldInError(java.lang.String fieldName)
Given the field name of a resource characteristic, return any error that occurred when processing the characteristic. |
MQeFields |
getInputFields()
Returns a reference to the input fields object. |
int |
getMaxAttempts()
Get the maximum number of times the request should be tried. |
java.lang.String |
getName()
Get the name of the managed resource. |
MQeFields |
getOutputFields()
Returns a reference to the output fields object. |
int |
getRC()
Returns the return code resulting from the action. |
java.lang.String |
getReason()
Returns the reason for failure if an error occurred. |
java.lang.String |
getTargetQMgr()
Returns the name of the queue manager where the request is to be processed. |
void |
inquire(MQeFields parms)
Sets up the administration message to perform the Action_Inquire
action. |
void |
inquireAll(MQeFields parms)
Sets up the administration message to perform the Action_InquireAll
action. |
void |
setAction(int action)
Set the administration action to perform. |
void |
setMaxAttempts(int maxAttempts)
Set the maximum number of times the request should be attempted. |
void |
setName(java.lang.String resourceName)
Set the name of the resource that the action is to be performed on. |
void |
setTargetQMgr(java.lang.String targetQMgr)
Set the name of queue manager where the request is to be processed. |
void |
update(MQeFields parms)
Sets up an administration message to run the Action_Update action. |
Methods inherited from class com.ibm.mqe.MQeMsgObject |
getMsgUIDFields, getOriginQMgr, getTimeStamp, putOriginQMgr, resetMsgUIDFields, unwrapMsgObject |
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 |
public static final java.lang.String Admin_TargetQMgr
The target queue manager can be either a local or a remote queue manager. As only one queue manager can be active at a time in a Java Virtual Machine, the target queue manager, and the one to which the message is put, must be the same.
Field type | ascii |
Set in request message | mandatory |
public static final java.lang.String Admin_Action
Each managed resource provides a set of administrative actions that it can perform. A single administration message can only request that one action be performed. The following common actions are defined:
These actions may be added to in order to provide additional actions that are specific to a resource. Also some of the common actions are not applicable to all resources.Field type | int |
Set in request message | mandatory |
public static final int Action_Create
Admin_Action
,
Constant Field Valuespublic static final int Action_Delete
Admin_Action
,
Constant Field Valuespublic static final int Action_Inquire
Admin_Action
,
Constant Field Valuespublic static final int Action_InquireAll
Admin_Action
,
Constant Field Valuespublic static final int Action_Update
Admin_Action
,
Constant Field Valuespublic static final int Action_Stop
Admin_Action
,
Constant Field Valuespublic static final int Action_Start
Admin_Action
,
Constant Field Valuespublic static final int Action_AddAlias
Admin_Action
,
Constant Field Valuespublic static final int Action_RemoveAlias
Admin_Action
,
Constant Field Valuespublic static final int Action_Unknown
Admin_Action
,
Constant Field Valuespublic static final java.lang.String Admin_Parms
Every resource has a set of unique characteristics. Each characteristic
has a name, type and value, and the name of each is defined by a constant
in the administration message. The name of the resource is a characteristic
that is common to all managed resources. The name of the resource is
held in the Admin_Name
field. The full set of characteristics
of a resource can be determined by using the characteristics()
method against an instance of an administration message.
The action requested determines the set of characteristics that
can be set in this field. In all cases, the name of the resource,
must be set. For certain actions like Action_InquireAll
this is the only parameter that is required.
For a reply message this field contains the results of the request. For instance if the request was an inquiry then the results will be contained in this field.
Field type | MQeFields |
Set in request message | mandatory |
public static final java.lang.String Admin_Name
The name of the resouce must be placed into the Admin_Parms field for every request.
Field type | ascii |
Set in request message | mandatory |
Admin_Parms
,
Constant Field Valuespublic static final java.lang.String Admin_RC
A reply message will contain this field which can take the following values:
More detailed information on any failure can be found in fields:
Field type | byte |
Set in request message | no |
Admin_Reason
,
Admin_Errors
,
Constant Field Valuespublic static final int RC_Success
Admin_RC
,
Constant Field Valuespublic static final int RC_Fail
Admin_RC
,
Admin_Errors
,
Constant Field Valuespublic static final int RC_Mixed
Admin_RC
,
Admin_Errors
,
Constant Field Valuespublic static final java.lang.String Admin_Reason
If an action failed with either RC_Mixed or RC_Fail then a
reply message will provide a reason for the failure. If several
failures occured, for instance a 2 attributes of a resource were
in error then more detailed information can be found in field
Admin_Errors
.
The field typically contains a toString() of the exception that caused
the failure. If the exception is of type MQeException
the string includes the MQeException code at the start of the string as
"Code=nnn;"
Field type | unicode |
Set in request message | no |
Admin_RC
,
Admin_Errors
,
Constant Field Valuespublic static final java.lang.String Admin_Errors
The MQeFields object contains any errors related to subproblems that occur when a request fails with a return code of RC_Fail or RC_Mixed. For each attribuute in error there will be a corresponding field in this MQeFields object.If the field that was processed was an array then the corresponding error field will be of type ascii array. If the field that was processed was not an array then the corresponding error field will be of type ascii. For example if an update request was made to change 4 attributes of a resource and 2 of the updates were successful and 2 failed, this field would contain information detailing the reason for the 2 failures.
Each error is typically a toString() representation of the exception
that caused the failure. If the exception is of type MQeException
the string includes the MQeException code at the start of the string as
"Code=nnn;"
Field type | MQeFields |
Set in request message | no |
Admin_RC
,
Admin_Reason
,
Constant Field Valuespublic static final java.lang.String Admin_MaxAttempts
If a request fails then it can be retried. As an example if a request to delete a queue fails because there are messages on the queue then a retry may succeed.
Field type | int |
Set in request message | optional |
public static final java.lang.String Admin_Class
Field type | ascii |
Set in request message | no |
Constructor Detail |
public MQeAdminMsg() throws java.lang.Exception
MQeAdminMsg exMQeAdminMsg = (MQeAdminMsg) new MQeQueueManagerAdminMsg();
Method Detail |
public MQeFields characteristics() throws java.lang.Exception
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)
java.lang.Exception
public void UseCharacteristics(MQeAdminMsg msg) throws Exception { MQeFields chars = msg.characteristics(); Enumeration fields = chars.fields(); while (fields.hasMoreElements()) { System.out.println("Contains field:" + (String) fields.nextElement()); } }
public void create(MQeFields parms) throws java.lang.Exception
Sets up an administration message to run the Action_Create
action.
Attempts to create a new resource with characteristics as specified in the parms parameter.
The Admin_Action
and Admin_Parms
fields are set by this method
parms
- an MQeFields
object containing name value
pairs for any characteristics that require a setting different to that of the
resources default setting. The name of the resource can be included
in parms but can also be set with the setName(java.lang.String)
method.
java.lang.Exception
Action_Create
//Create ExampleQ MQeAdminMsg msg = (MQeAdminMsg) new MQeQueueAdminMsg(); msg.setName("ExampleQM"); parms.putUnicode(MQeQueueAdminMsg.Queue_Description, "a new description ..."); //Set the action required and its parameters into the message msg.create(parms);
public void delete(MQeFields parms) throws java.lang.Exception
Sets up an administration message to run the Action_Delete
action.
Attempts to delete a resource.
The Admin_Action
and Admin_Parms
fields are set by this method
parms
- an MQeFields
that must contain the
name of the managed resource to delete if it has not been set with the
setName(java.lang.String)
method.
java.lang.Exception
Action_Create
//Delete ExampleQ MQeAdminMsg msg = (MQeAdminMsg) new MQeQueueAdminMsg(); msg.setName("ExampleQM"); msg.delete(parms);
public MQeAdminMsg duplicate() throws java.lang.Exception
Creates a duplicate administration message.
All fields are duplicated with the exception of fields that constitute the messages unique identifier.
Note:The MQeFields.copy(com.ibm.mqe.MQeFields, boolean)
method is employed so only
a shallow copy of the message is made.
java.lang.ClassNotFoundException
java.lang.Exception
//Create a message as the same type as this one MQeAdminMsg requestMsg = (MQeAdminMsg) new MQeQueueAdminMsg(); MQeQueueAdminMsg reply = (MQeQueueAdminMsg) requestMsg.duplicate();
public int getAction()
Returns the administration action that is to be, or has been performed.
Admin_Action
from the administration message or Action_Unknown
if not set.Admin_Action
int action = 0; try { MQeAdminMsg requestMsg = (MQeAdminMsg) new MQeQueueAdminMsg(); action = requestMsg.getAction(); switch (action) { case 1: // Create // performCreate(); break; case 2: // Delete // performDelete(); break; default:; break; } } catch (Exception e) { System.err.println("Failure ! " + e.toString()); }
public MQeFields getErrorFields()
Returns a reference to the error fields object.
Admin_Errors
MQeFields object from the administration
message or an empty MQeFields
object if the field
does not exist.Admin_Errors
MQeFields errs = null; try { MQeAdminMsg replyMsg = (MQeAdminMsg) new MQeQueueAdminMsg(); if (replyMsg.getRC() != 0) { errs = replyMsg.getErrorFields(); Enumeration fields = errs.fields(); while (fields.hasMoreElements()) { String errF = (String) fields.nextElement(); System.out.println("Field:" + errF + "failed with error "); } } } catch (Exception e) { System.err.println("Failure ! " + e.toString()); }
public java.lang.String[] getFieldInError(java.lang.String fieldName)
Given the field name of a resource characteristic, return any error that occurred when processing the characteristic.
Checks the Admin_Errors
field for any error information
related to a named characteristic.
fieldName
- the field name of the characteristic to check
Admin_Errors
String[] errs = null; try { MQeAdminMsg replyMsg = (MQeAdminMsg) new MQeQueueAdminMsg(); if (replyMsg.getRC() != 0) { fieldName = MQeQueueAdminMsg.Queue_Priority; errs = replyMsg.getFieldInError(fieldName); if (errs != null) System.out.println("Error setting priority" + errs[0]); } } catch (Exception e) { System.err.println("Failure ! " + e.toString()); }
public MQeFields getInputFields()
Returns a reference to the input fields object.
The input fields object contains the input parameters required by
an action. The input parameters for an action are stored in the
Admin_Parms
field of the administration message.
Admin_Parms
MQeFields object from the administration
message or an empty MQeFields object if the field does not exist.Admin_Parms
,
getOutputFields()
MQeFields parms = null; try { MQeAdminMsg requestMsg = (MQeAdminMsg) new MQeQueueAdminMsg(); parms = requestMsg.getInputFields(); } catch (Exception e) { System.err.println("Failure ! " + e.toString()); }
public int getMaxAttempts()
Get the maximum number of times the request should be tried.
Admin_MaxAttempts
from the administration message or a default of 1 if not set.Admin_MaxAttempts
int tries = 0; try { MQeAdminMsg requestMsg = (MQeAdminMsg) new MQeQueueAdminMsg(); tries = requestMsg.getMaxAttempts(); } catch (Exception e) { System.err.println("Failure ! " + e.toString()); }
public java.lang.String getName()
Get the name of the managed resource.
Admin_Name
from the administration message or null if not set.Admin_Name
String name = " "; try { MQeAdminMsg requestMsg = (MQeAdminMsg) new MQeQueueAdminMsg(); name = requestMsg.getName(); } catch (Exception e) { System.err.println("Failure ! " + e.toString()); }
public MQeFields getOutputFields()
Returns a reference to the output fields object.
The output fields object contains both the input parameters of a
request together with the results of the request (not error details).
The output parameters for an action are stored in the
Admin_Parms
field of the administration message.
Admin_Parms
MQeFields object from the administration
message or an empty MQeFields object if it does not exist.Admin_Parms
MQeFields parms = null; try { MQeQueueAdminMsg replyMsg = new MQeQueueAdminMsg(); parms = replyMsg.getOutputFields(); if (parms.contains(MQeQueueAdminMsg.Queue_Description)) { System.out.println("Queue description:" + parms.getUnicode(MQeQueueAdminMsg.Queue_Description)); } } catch (Exception e) { System.err.println("Failure ! " + e.toString()); }
public int getRC() throws java.lang.Exception
Returns the return code resulting from the action.
Admin_RC
from the administration message.
java.lang.Exception
Admin_RC
String error = " "; int rc = 0; try { MQeAdminMsg ReplyMsg = (MQeAdminMsg) new MQeQueueAdminMsg(); rc = ReplyMsg.getRC(); if (rc != ReplyMsg.RC_Success) error = ReplyMsg.getReason(); } catch (Exception e) { System.err.println("Failure ! " + e.toString()); }
public java.lang.String getReason()
Returns the reason for failure if an error occurred.
Admin_Reason
from the administration message.Admin_Reason
String error = " "; int rc = 0; try { MQeAdminMsg replyMsg = (MQeAdminMsg) new MQeQueueAdminMsg(); rc = replyMsg.getRC(); if (rc != replyMsg.RC_Success) error = replyMsg.getReason(); } catch (Exception e) { System.err.println("Failure ! " + e.toString()); }
public java.lang.String getTargetQMgr() throws java.lang.Exception
Returns the name of the queue manager where the request is to be processed.
MQeException
- java.lang.Exception
String targetQMgr = " "; try { MQeAdminMsg requestMsg = (MQeAdminMsg) new MQeQueueAdminMsg(); targetQMgr = requestMsg.getTargetQMgr(); } catch (Exception e) { System.out.println("Target queue manager not set"); }
public void inquire(MQeFields parms) throws java.lang.Exception
Sets up the administration message to perform the Action_Inquire
action.
When performed, the action will return the specified characteristics of an existing resource.
The Admin_Action
and Admin_Parms
fields are set by this method
parms
- an MQeFields object containing one or more names of the characteristic(s) of
the resource that is to be inquired on. The name of the resource can be included
in parms but can also be set with the setName(java.lang.String)
method.
java.lang.Exception
Action_Inquire
//Request the value of description and max queue depth try { MQeAdminMsg msg = (MQeAdminMsg) new MQeQueueAdminMsg(); parms = new MQeFields(); parms.putUnicode(MQeQueueAdminMsg.Queue_Description, null); parms.putInt(MQeQueueAdminMsg.Queue_MaxQSize, 0); //set the name of the queue to inquire on msg.setName("ExampleQM"); //Set the action required and its parameters into the message msg.inquire(parms); } catch (Exception e) { System.err.println("Failure ! " + e.toString()); }
public void inquireAll(MQeFields parms) throws java.lang.Exception
Sets up the administration message to perform the Action_InquireAll
action.
When performed the action will return all the characteristics of an existing resource.
The Admin_Action
and Admin_Parms
fields are set by this method
parms
- an MQeFields object containing the name of the resource to
be inquired on. The name of the resource can be included
in parms but can also be set with the setName(java.lang.String)
method in which
case parms can be set to null.
java.lang.Exception
Action_InquireAll
try { MQeAdminMsg msg = (MQeAdminMsg) new MQeQueueAdminMsg(); //set the name of the queue to inquire on msg.setName("ExampleQM"); //Set the action required and its parameters into the message msg.inquireAll(new MQeFields()); } catch (Exception e) { System.err.println("Failure ! " + e.toString()); }
public void setAction(int action)
Set the administration action to perform.
Sets the Admin_Action
field in the administration
message.
action
- the action to performAdmin_Action
try { MQeAdminMsg requestMsg = (MQeAdminMsg) new MQeQueueAdminMsg(); requestMsg.setAction(MQeAdminMsg.Action_Inquire); } catch (Exception e) { System.err.println("Failure ! " + e.toString()); }
public void setMaxAttempts(int maxAttempts)
Sets the Admin_MaxAttempts
field in the administration
message
maxAttempts
- the maximum number of times the request can be attempted.Admin_MaxAttempts
public void setName(java.lang.String resourceName) throws java.lang.Exception
Set the name of the resource that the action is to be performed on.
Sets the Admin_Name
field in the administration
message
resourceName
- Name of the resource
java.lang.Exception
Admin_Name
MQeFields parms = new MQeFields(); //Set the action required and its parameters into the message try { MQeAdminMsg msg = (MQeAdminMsg) new MQeConnectionAdminMsg(); msg.inquireAll(parms); msg.setName("ExampleQM"); } catch (Exception e) { System.err.println("Failure ! " + e.toString()); }
public void setTargetQMgr(java.lang.String targetQMgr) throws java.lang.Exception
Set the name of queue manager where the request is to be processed.
Sets the Admin_TargetQMgr
field in the administration
message
targetQMgr
- the name of the queue manager that will process
the request.
java.lang.Exception
Admin_TargetQMgr
try { MQeQueueAdminMsg requestMsg = new MQeQueueAdminMsg(); requestMsg.setTargetQMgr("ExampleQM"); requestMsg.setName("ExampleQM"); requestMsg.create(new MQeFields()); } catch (Exception e) { System.err.println("Failure ! " + e.toString()); }
public void update(MQeFields parms) throws java.lang.Exception
Sets up an administration message to run the Action_Update
action.
When the action is performed, an attempt is made to update the specified characteristics of a resource
The Admin_Action
and Admin_Parms
fields are set by this method
parms
- an MQeFields
object containing the set
of fields that are to be updated. The name of the resource can be included
in parms but can also be set with the setName(java.lang.String)
method.
java.lang.Exception
Action_Update
//Set name of resource to be managed try { MQeAdminMsg msg = (MQeAdminMsg) new MQeQueueAdminMsg(); msg.setName("ExampleQM"); //Change the value of description parms = new MQeFields(); parms.putUnicode(MQeQueueAdminMsg.Queue_Description, "Change description ..."); //Set the action required and its parameters into the message msg.update(parms); } catch (Exception e) { System.err.println("Failure ! " + e.toString()); }
|
Websphere MQ Everyplace | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |