com.abb.mpi
Class MXRequest

java.lang.Object
  |
  +--com.abb.mpi.MXRequest

public class MXRequest
extends java.lang.Object

The MXRequest class is used to access IMO/ABB MX infrastructure server functionality. It is used by application software.

MXRequest uses the security and cryptography classes provided by Sun Microsystems.

The JSSE 1.0.2 is used for posting HTTPS requests and writing server responses to the client's application.

The JCE 1.2.1 (Java Cryptography Extention 1.2.1) API is used for simple data encryption.

Note that the above classes are only supporting classes. They do not provide MX access on their own. The MXRequest class aggregates them to provide a standard interface which allows consistent and convient access to MX Server functionality. The documentation for JSSE and JCE can be obtained from JSSE and JCE . The MXRequest class provides the following catagories of functionality:

Login. MXRequest users authenticate using HTTP basic authorization. It also creates a SSL Session with the Web Server for encryption of data. Invoke the login method after creating an MXRequest instance to perform the actual login.

Download Messages. This method is used to get new,active,alarm messages from server once there is a successful login. Use the getMessage method.

Receipt. Message Exchange Server requires that once the message is at the clients' end, client should send back the receipt with a message ID, so that message can be marked as received in the Database. The sendReceipt method is called automatically for the user. User doesn't have to worry about sending back the receipts to the server.

Response. Message Exchange Server requires that the client send send back a response for a particular messageID. Use the following method to send Responses for all the message which are to be ACCEPTED: sendAccept.

Response. Message Exchange Server requires that the client send send back a response for a particular messageID. Use the following method to send Responses for all the message which are to be REJECTED: sendReject.

Notes.

User need to include the mxapi.jar in the classpath to be albe to use the API.

A test program is provided in the mx/source directory which exercises the MXRequest object. It is called MXAppTest.java, reference it for usage examples.

All the messages will be in the XML format. One of the tag in the XML Message is TYPE which tells the users the type of the current message.

The types are:

ACTIVE
This message will be sent to user when user first calls the getMessage function in the application. These messages are all the users' active messages which will be sent to user at the startup of the application.

DISPATCH
This message type will be sent to user when the new messages come in to the Message Exchange.

CONFIRMATIONOK
This message will be sent to user after receiving the response from the user within the stipulated time.

CONFIRMATIONNOTOK
This message will be sent to user after receiving the response from the user after the stipulated time.

TIMEOUT
This message will be sent to user, when the messages get timed out on the Message Exchange Server. The message get timedout when Message Exchange doesn't receive the response within the stipulated time.

ALARM_BAD
This message will be sent to the user when there is some problem communicating with the SCADA Server, or if some processes on the SCADA Server are not working well.

ALARM_GOOD
This message will be sent after the ALARM_BAD message when everything starts working well.

LOG
This message will be sent to user if user wasn't online for few hours and there were messages sent to Message Exchange for that user. When users' application starts and the first time it calls the getMessage function, the LOG messages will be sent to user.

Please take a look at Dispatch Information for greater details about all the different kinds of dispatches.


Field Summary
static int APPLET
          If the user wants to use the API for creating APPLETS, users should use this Execution mode type constant.
static int APPLICATION
          If the user wants to use the API for creating an APPLICATION, users should use this Execution mode type constant.
 
Constructor Summary
MXRequest(java.lang.String host, java.lang.String protocol, int port, java.lang.String username, java.lang.String password, int execMode)
          Initializes a newly created MXRequest object with the passed HTTP basic authorization arguments.
 
Method Summary
 java.util.Vector getMessage()
          getMessage - Return new/alarm/active/log messages to the user.
 java.lang.String getUsername()
          Return MX logged-in user name.
 boolean login()
          Login MX Web user.
 void logout()
          Logout MX user.
 void sendAccept(java.util.Vector accepts)
          sendAccept - send responses for a group of messages which are recieved on the client.
 void sendReject(java.util.Vector rejects)
          sendReject - send responses for a group of messages which are recieved on the client.
 void setDebug(boolean flag)
          Set debug status using flag argument.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

APPLET

public static final int APPLET
If the user wants to use the API for creating APPLETS, users should use this Execution mode type constant.

APPLICATION

public static final int APPLICATION
If the user wants to use the API for creating an APPLICATION, users should use this Execution mode type constant.
Constructor Detail

MXRequest

public MXRequest(java.lang.String host,
                 java.lang.String protocol,
                 int port,
                 java.lang.String username,
                 java.lang.String password,
                 int execMode)
          throws java.io.IOException
Initializes a newly created MXRequest object with the passed HTTP basic authorization arguments. If the protocol used is HTTPS, then it creates a SSL session with server and each message passed through the connection is encrypted.
Parameters:
host - Contains the MX Web Server name as String.
protocol - Contains the protocol to use (HTTP, HTTPS) in String format.
port - Contains the HTTP int port to communicate over.
username - Contains the HTTP basic authorization username String.
password - Contains the HTTP basic authorization password String.
execMode - int value specifying what environment the code is running in. Specify one of the field constants labeled Execution mode type.
Throws:
java.io.IOException - Returned for any URL object creation failures.
Method Detail

setDebug

public void setDebug(boolean flag)
Set debug status using flag argument. Debugging information is sent to standard output when enabled.
Parameters:
flag - Set true to turn debugging on and false to turn it off.

login

public boolean login()
              throws java.lang.Exception
Login MX Web user. For HTTPS login, this method contacts the Web Server and passes the username and password for verification. If successful, access to the Web Server on behalf of the logged-in user is now possible.

Returns:
true if login is successful, and false if it is not.

logout

public void logout()
Logout MX user. Invoke this method to release resources consumed by logged-in user.

getUsername

public java.lang.String getUsername()
Return MX logged-in user name.
Returns:
The logged in user's login name String.

getMessage

public java.util.Vector getMessage()
                            throws java.lang.Exception
getMessage - Return new/alarm/active/log messages to the user. This method will return messages as an string. The messages will be in an XML format. It depends upon user to use the message according to the Applications' need.
Returns:
Vector
Throws:
java.lang.Exception -  

sendAccept

public void sendAccept(java.util.Vector accepts)
                throws java.lang.Exception
sendAccept - send responses for a group of messages which are recieved on the client. Vector containing all the messageID's which are to be ACCEPTED, has to be send as a parameter to this function. The messageID's must be Strings.
Parameters:
Vector. -  
Throws:
java.io.StreamCorruptedException -  
java.io.IOException -  
java.lang.ClassNotFoundException -  

sendReject

public void sendReject(java.util.Vector rejects)
                throws java.lang.Exception
sendReject - send responses for a group of messages which are recieved on the client. Vector containing all the messageID's which are to be REJECTED, has to be send as a parameter to this function. The messageID's must be Strings.
Parameters:
Vector. -  
Throws:
java.io.StreamCorruptedException -  
java.io.IOException -  
java.lang.ClassNotFoundException -