com.nmt.mgp
Interface MgpSessionI

All Known Implementing Classes:
MgpSession

public interface MgpSessionI

A session to the MGP Server.

When connected to the server it can be used to send and receive operations using MGP (Messaging Gateway Protocol). It provides a way to get information about the server as well as to send and receive messages.


Method Summary
 void close()
          Clears the session by logging off from the server and closing the current connection.
 void connect(java.lang.String host, int port, boolean useSsl)
          Connect to the server.
 java.sql.ResultSet dbexec(java.lang.String profile, java.lang.String sql)
          Send an SQL string to be executed on the EMG server.
 void deleteMessage(int id)
          Delete a message.
 OptionHolder execute(int operation, OptionHolder options)
          Send an operation with arguments to the EMG server, and wait for the response.
 int getAdminFlags()
          Gets the full administration flags for the currently logged in user.
 java.lang.String getClientConfig()
          Gets the client configuration string.
 OptionHolder getLoginOptions()
          Gets the current login options.
 int getPermissions()
          Gets the permissions for the currently logged in user.
 java.lang.String getRemoteIp()
          The IP number of this client, as seen by the server.
 boolean havePermission(int functions)
          Checks if the current user has all of the given permissions.
 boolean havePermission(int mask, boolean all)
          Checks if the current user has any or all of the given permissions.
 boolean isAdmin()
          Deprecated. As of MGP Java 1.4, use getPermissions() instead and check for the specific functionality.
 void login(java.lang.String username, java.lang.String password)
          Login to the server using username and password for authentication.
 void login(java.lang.String username, java.lang.String password, java.lang.String servicetype)
          Login to the server using username and password for authentication.
 void logoff()
          Logoff from the server.
 int queryMessage(int id)
          Query the server for status of a message, identified by the specified id.
 int readOperation(OptionHolder options)
          Deprecated. Use execute(int, com.nmt.mgp.OptionHolder) instead.
 int readResponse()
          Read the response to the last command sent to the EMG server.
 void reload()
          Reload the configuration on the server, while keeping the connection open.
 int sendMessage(Message msg)
          Send a message.
 void sendOperation(int operation, OptionHolder options)
          Deprecated. Use execute(int, com.nmt.mgp.OptionHolder) instead.
 void sendOperation(int operation, OptionHolder options, boolean doFlush)
          Deprecated. Use execute(int, com.nmt.mgp.OptionHolder) instead.
 void setDebug(boolean on)
          Enables/disables runtime debug output.
 

Method Detail

connect

void connect(java.lang.String host,
             int port,
             boolean useSsl)
             throws MgpException
Connect to the server.

Parameters:
host - the host name to connect to
port - the port number to connect to
useSsl - true if and only if the communication should use SSL
Throws:
MgpException - if a communication error occurs

close

void close()
           throws MgpException
Clears the session by logging off from the server and closing the current connection.

Throws:
MgpException

sendOperation

void sendOperation(int operation,
                   OptionHolder options,
                   boolean doFlush)
                   throws MgpException
Deprecated. Use execute(int, com.nmt.mgp.OptionHolder) instead.

Send an operation to the EMG server.

Parameters:
operation - the operation number, one of Mgp.MGP_OP_*
options - the list of operation parameters
doFlush - true if and only if the socket stream should be flushed after the operation
Throws:
MgpException
See Also:
Mgp

sendOperation

void sendOperation(int operation,
                   OptionHolder options)
                   throws MgpException
Deprecated. Use execute(int, com.nmt.mgp.OptionHolder) instead.

Send an operation to the EMG server.

This is a simple overload to sendOperation(int,OptionHolder,boolean), with true used as the third argument.

Parameters:
operation - the operation number, one of Mgp.MGP_OP_*
options - the list of operation parameters
Throws:
MgpException

readOperation

int readOperation(OptionHolder options)
                  throws MgpException
Deprecated. Use execute(int, com.nmt.mgp.OptionHolder) instead.

Read an operation request from the server and store the options in the provided option holder.

Parameters:
options - an empty OptionHolder, which will get filled with the parameters to the operation
Throws:
MgpException - if a communication error occurs

readResponse

int readResponse()
                 throws MgpException
Read the response to the last command sent to the EMG server.

Calls readOperation(OptionHolder), extracts the return code (Mgp.MGP_OPTION_RETCODE) and returns the value as an int.

Throws:
MgpException - if an error occurs when reading from the stream
See Also:
Mgp

execute

OptionHolder execute(int operation,
                     OptionHolder options)
                     throws MgpException
Send an operation with arguments to the EMG server, and wait for the response. The implementation of this method should be synchronized to provide a simple multithread safe access point.

Parameters:
operation - the operation number, as one of MGP_OP_* from Mgp
options - the input parameters, to be sent to the server
Returns:
the returned parameters from the server
Throws:
MgpException - if a communication error occurs

login

void login(java.lang.String username,
           java.lang.String password,
           java.lang.String servicetype)
           throws MgpException
Login to the server using username and password for authentication.

Parameters:
username - the EMG username, sent as Mgp.MGP_OPTION_USERNAME
password - the EMG password, sent as Mgp.MGP_OPTION_PASSWORD
servicetype - the systemtype, sent as Mgp.MGP_OPTION_SYSTEMTYPE
Throws:
MgpException - if a communication error occurs

login

void login(java.lang.String username,
           java.lang.String password)
           throws MgpException
Login to the server using username and password for authentication.

Throws:
MgpException

logoff

void logoff()
            throws MgpException
Logoff from the server.

Throws:
MgpException

reload

void reload()
            throws MgpException
Reload the configuration on the server, while keeping the connection open.

Throws:
MgpException

sendMessage

int sendMessage(Message msg)
                throws MgpException
Send a message.

Destination address and message data is mandatory. This is checked before the message is sent. If the message is not valid an exception is thrown.

Returns the message id on success, otherwise an MgpException is thrown.

Parameters:
msg - A message with message text, destination address etc set
Throws:
MgpException - if a communication error occurs

queryMessage

int queryMessage(int id)
                 throws MgpException
Query the server for status of a message, identified by the specified id.

Returns message status on success, otherwise an MgpException is thrown.

Parameters:
id - the unique identifier of the message, returned by sendMessage(Message)
Throws:
MgpException - if the message isn't found on the server, or a communication error occurs

deleteMessage

void deleteMessage(int id)
                   throws MgpException
Delete a message.

Shortcut for deleting the message identified by the specified id.

Returns message status on success, otherwise an MgpException is thrown.

Parameters:
id - the unique identifier of the message, returned by sendMessage(Message)
Throws:
MgpException - if the message isn't found on the server, or a communication error occurs

dbexec

java.sql.ResultSet dbexec(java.lang.String profile,
                          java.lang.String sql)
                          throws MgpException,
                                 java.sql.SQLException
Send an SQL string to be executed on the EMG server.

Parameters:
profile - the database profile name
sql - the SQL string
Returns:
the selected data, or an empty ResultSet if the SQL didn't produce any data (such as an INSERT or UPDATE).
Throws:
MgpException
java.sql.SQLException

isAdmin

boolean isAdmin()
Deprecated. As of MGP Java 1.4, use getPermissions() instead and check for the specific functionality.

Returns whether user in session is an administrator.


getAdminFlags

int getAdminFlags()
Gets the full administration flags for the currently logged in user.

Since:
MGP Java 1.5c

getPermissions

int getPermissions()
Gets the permissions for the currently logged in user.

The value is a combined bitmask of MGP_ACCESS_* from Mgp.

Since:
MGP Java 1.4

havePermission

boolean havePermission(int functions)
Checks if the current user has all of the given permissions.

See Also:
havePermission(int, boolean)

havePermission

boolean havePermission(int mask,
                       boolean all)
Checks if the current user has any or all of the given permissions. The permissions should be from the MGP_ACCESS_* constants in Mgp.

Parameters:
mask - the bitmask of permissions
all - true if all permissions must be present

getClientConfig

java.lang.String getClientConfig()
Gets the client configuration string.


setDebug

void setDebug(boolean on)
Enables/disables runtime debug output.

Parameters:
on - true for debug out, false if not

getLoginOptions

OptionHolder getLoginOptions()
Gets the current login options.


getRemoteIp

java.lang.String getRemoteIp()
The IP number of this client, as seen by the server.