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.