ch.epfl.lsr.apex
Class APEXManager

java.lang.Object
  extended bych.epfl.lsr.apex.APEXManager
Direct Known Subclasses:
APEXEndpointManager, APEXRelayManager

public abstract class APEXManager
extends Object

The APEXManager is the general class for the two APEX managers and offers various functionalities to their subclasses.

Author:
Marc Stoecklin

Field Summary
protected  APEXProcess application
          The application associated to this process
protected  Hashtable lockedIdentifiers
          Set of identifiers (b)locked for in the semaphore when getting an element of the messageTable.
protected  Hashtable messageTable
          Hash table for multiple use (e.g. storage for static classes)
protected  int port
          Default port number to connect to (edge and mesh respectively)
static int PROCESSTYPE_ENDPOINT
          Endpoint process type
static int PROCESSTYPE_RELAY
          Relay process type
static int SERVICEPRIORITIES
          Service properties identifier in service array
protected  Hashtable[] services
          Service array containing on SERVICETABLE a table of all services mapped by their option identifer and on SERVICEPRIORITIES a vector of the priority of their processing.
static int SERVICETABLE
          Service table identifier in service array
protected  Hashtable transactionTable
          Table containing all sets of transactions, mapped by the channelID
 
Constructor Summary
APEXManager()
           
 
Method Summary
 boolean addTransaction(Object channelID, int transID, Object operation)
          Adds a transaction identified by a transID number associated to an APEX endpoint / relay (entity) to the internal transactionTable.
 void debug(String debugMessage)
          Accepts and passes messages to the application's debug method.
 APEXProcess getApplication()
          Returns the application (APEXProcess) associated to this manager.
 Object getFromTable(Object key)
           Returns an object associated to the key or null if the key is not mapped in the message hash table.
 Object getFromTableAndLock(Object key, Object lockIdentifier)
           Offers the possibility to any class (mainly static classes to read arbitrary content identified by a unique key and lock while reading and updating an element for a special group.
 Object getTransaction(Object channelID, int transID)
          Returns the operation identifier for a specified transaction identifier of an associated channel.
abstract  void handleIncomingMessage(APEXMessage am, Object receivingChannelID)
          When a message has been received on a connection it calls its manager's ' handleIncomingMessage' method.
abstract  void messageDiscarded(APEXDataMessage am, int code, String reason)
          This mesthod is called when a connection wasn't able to send an 'APEXMessage', say a (where x !
abstract  void messageSent(APEXDataMessage am, APEXReply reply)
          This mesthod is called when an 'APEXMessage' is successfully sent on a connection, say an element has been received.
 void notification(int code, Object specification)
          Accepts and passes messages to the application's notification method.
protected  int parsePort(String p)
           Parses a String port number, e.g. from an XML attribute and returns the port number as an int if it is valid (between 1 and 65535).
 void putToTable(Object key, Object value)
           Offers the possibility to any class (mainly static classes to store arbitrary content identified by a unique key.
 void putToTableAndUnlock(Object key, Object value, Object unlockIdentifier)
          Puts a value to the message tabe and afterwards unlocks the table.
 void removeAllTransactions(Object channelID)
          Removes completely the transaction table for the associated channel.
 Object removeFromTable(Object key)
          Removes a key and its associated content from the message hash table.
 Object removeTransaction(Object channelID, int transID)
          Removes and returns the operation identifier for a specified transaction identifier of an associated channel.
abstract  int sendAPEXDataMessage(APEXDataMessage adm)
           Sends an APEXDataMessage to the recipients specified within the object.
protected  APEXOption[] sortOptions(APEXOption[] ao)
          Returns an array of sorted 'APEXOptions' as they are specified in the configuration file for the services by the attribute priority.
abstract  int terminate(APEXTerminateMessage atm, Object receivingChannelID)
          Is called when an terminate element is received a status code (for the reply is returned).
 void unlockTable(Object key, Object unlockIdentifier)
          Unlocks the message table for the specified key and the identifier.
protected  boolean validatePort(int port)
          Validates a given port number (between 1 and 65535).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PROCESSTYPE_RELAY

public static final int PROCESSTYPE_RELAY
Relay process type

See Also:
Constant Field Values

PROCESSTYPE_ENDPOINT

public static final int PROCESSTYPE_ENDPOINT
Endpoint process type

See Also:
Constant Field Values

SERVICETABLE

public static final int SERVICETABLE
Service table identifier in service array

See Also:
Constant Field Values

SERVICEPRIORITIES

public static final int SERVICEPRIORITIES
Service properties identifier in service array

See Also:
Constant Field Values

port

protected int port
Default port number to connect to (edge and mesh respectively)


messageTable

protected Hashtable messageTable
Hash table for multiple use (e.g. storage for static classes)


transactionTable

protected Hashtable transactionTable
Table containing all sets of transactions, mapped by the channelID


lockedIdentifiers

protected Hashtable lockedIdentifiers
Set of identifiers (b)locked for in the semaphore when getting an element of the messageTable.


services

protected Hashtable[] services
Service array containing on SERVICETABLE a table of all services mapped by their option identifer and on SERVICEPRIORITIES a vector of the priority of their processing.


application

protected APEXProcess application
The application associated to this process

Constructor Detail

APEXManager

public APEXManager()
Method Detail

sendAPEXDataMessage

public abstract int sendAPEXDataMessage(APEXDataMessage adm)

Sends an APEXDataMessage to the recipients specified within the object.

Parameters:
adm - Data message to be sent. If no recipients are specified, no action is taken.
Returns:
A three-digit status reply code for the message.

handleIncomingMessage

public abstract void handleIncomingMessage(APEXMessage am,
                                           Object receivingChannelID)
                                    throws APEXException
When a message has been received on a connection it calls its manager's ' handleIncomingMessage' method.
This method decides according the message type how to proceed.

Parameters:
am - The incoming message
receivingChannelID - The channel identifier of the channel which received the message
Throws:
APEXException - Is thrown on an error in processing

messageDiscarded

public abstract void messageDiscarded(APEXDataMessage am,
                                      int code,
                                      String reason)
This mesthod is called when a connection wasn't able to send an 'APEXMessage', say a (where x != 250) is received or the next hop is not responding. All applicable services are called by there method 'handleDiscarded'.

Parameters:
am - The message which wasn't sent
code - The error code of this message
reason - A textual reason

messageSent

public abstract void messageSent(APEXDataMessage am,
                                 APEXReply reply)
This mesthod is called when an 'APEXMessage' is successfully sent on a connection, say an element has been received. All applicable services are called by there method 'handleSent'

Parameters:
am - The message which has successfully been sent
reply - The reply object received of the next hop

terminate

public abstract int terminate(APEXTerminateMessage atm,
                              Object receivingChannelID)
Is called when an terminate element is received a status code (for the reply is returned). This method terminates the transaction if it exists

Parameters:
atm - Associated APEXTerminateMessage for operation to terminate.
receivingChannelID - A channel identifier for the channel which received the operation
Returns:
a three-digit code for the operation

getApplication

public APEXProcess getApplication()
Returns the application (APEXProcess) associated to this manager.

Returns:
the application

debug

public void debug(String debugMessage)
Accepts and passes messages to the application's debug method.

Parameters:
debugMessage - the debug message

notification

public void notification(int code,
                         Object specification)
Accepts and passes messages to the application's notification method.

Parameters:
code - A three digit code
specification - An Object specifying the notification
See Also:
APEX, APEXProcess.notification(int, Object)

putToTable

public void putToTable(Object key,
                       Object value)

Offers the possibility to any class (mainly static classes to store arbitrary content identified by a unique key.

Please note that when using this table, the key must be completely unique, you are strongly asked to identify the key with the application or service you are setting up.

This method is synchronized but is not a semaphore - please refer putToTableAndUnlock.

Parameters:
key - unique key for message table
value - the content

getFromTable

public Object getFromTable(Object key)

Returns an object associated to the key or null if the key is not mapped in the message hash table.

This method is synchronized but is not a semaphore - please refer getFromTableAndLock.

Parameters:
key - a unique key in the message table
Returns:
the value which is mapped in the message table or null if the key is null or not mapped

getFromTableAndLock

public Object getFromTableAndLock(Object key,
                                  Object lockIdentifier)

Offers the possibility to any class (mainly static classes to read arbitrary content identified by a unique key and lock while reading and updating an element for a special group.

Please note that when using this table, the key must be completely unique, you are strongly asked to identify the key with the application or service you are setting up.

This method is synchronized and blocks if another process tries to read the same key which is locked.

Parameters:
key - A key to read and lock
lockIdentifier - a special identifier for the reading process
Returns:
the read content or null if the key does not exist - the key is not locked then.

unlockTable

public void unlockTable(Object key,
                        Object unlockIdentifier)
Unlocks the message table for the specified key and the identifier.

Parameters:
key - A key to be unlocked
unlockIdentifier - An associated identifier

putToTableAndUnlock

public void putToTableAndUnlock(Object key,
                                Object value,
                                Object unlockIdentifier)
Puts a value to the message tabe and afterwards unlocks the table. All waiting elements are notified and now can read the new content associated to the key.

Parameters:
key - a key for the content
value - the content to be added
unlockIdentifier - the asscoiated identifier to the block

removeFromTable

public Object removeFromTable(Object key)
Removes a key and its associated content from the message hash table.

Parameters:
key - the key of the element to be removed
Returns:
the removed value

addTransaction

public boolean addTransaction(Object channelID,
                              int transID,
                              Object operation)
Adds a transaction identified by a transID number associated to an APEX endpoint / relay (entity) to the internal transactionTable.

Parameters:
channelID - A channel identifier associated to the transID
transID - The transaction identifier
operation - An operation identifier (@see APEX)
Returns:
true if successful

getTransaction

public Object getTransaction(Object channelID,
                             int transID)
Returns the operation identifier for a specified transaction identifier of an associated channel.

Parameters:
channelID - A channel identifier associated to the transID
transID - The transaction identifier
Returns:
the operation or null if the entity/transID combination does not exist

removeTransaction

public Object removeTransaction(Object channelID,
                                int transID)
Removes and returns the operation identifier for a specified transaction identifier of an associated channel.

Parameters:
channelID - A channel identifier associated to the transID
transID - The transaction identifier
Returns:
the operation identifier or null if the channel/transID combination does not exist

removeAllTransactions

public void removeAllTransactions(Object channelID)
Removes completely the transaction table for the associated channel.

Parameters:
channelID - A channel identifier associated to be removed

sortOptions

protected APEXOption[] sortOptions(APEXOption[] ao)
Returns an array of sorted 'APEXOptions' as they are specified in the configuration file for the services by the attribute priority.

Parameters:
ao - An unsorted array
Returns:
An ascending sorted array

parsePort

protected int parsePort(String p)
                 throws APEXException

Parses a String port number, e.g. from an XML attribute and returns the port number as an int if it is valid (between 1 and 65535).

Otherwise, an 'APEXException' is thrown.

Parameters:
p - A String port number
Returns:
valid integer port number
Throws:
APEXException - thrown if the port is not valid

validatePort

protected boolean validatePort(int port)
Validates a given port number (between 1 and 65535).

Parameters:
port - The sample port number
Returns:
a boolean result of the test