ch.epfl.lsr.apex
Class APEXEndpointManager

java.lang.Object
  ch.epfl.lsr.apex.APEXManager
      ch.epfl.lsr.apex.APEXEndpointManager

public class APEXEndpointManager

extends APEXManager

The APEXEndpointManager handles the interface between an endpoint and a relay. It must be initialized by every application implementing APEXEndpointProcess to be able to attach to the APEX mesh and to send messages.

Author:

Marc Stoecklin

Field Summary

Fields inherited from class ch.epfl.lsr.apex.APEXManager

application, lockedIdentifiers, messageTable, port, PROCESSTYPE_ENDPOINT, PROCESSTYPE_RELAY, SERVICEPRIORITIES, services, SERVICETABLE, transactionTable

Constructor Summary

APEXEndpointManager(APEXEndpointProcess application, String serviceConfigurationFile)
Instantiates a new APEX endpoint manager using the standard port 912 for apex-edge-connections (say to its relay).

APEXEndpointManager(APEXEndpointProcess application, String serviceConfigurationFile, int edgePort)
Instantiates a new APEX endpoint manager using a specified port number for apex-edge-connections (say to its relay).

Method Summary

void	attachAs(APEXEndpointAddress aea, APEXStatus status) Allows an application to attach as the specified endpoint and to set a listener on the APEXStatus.
HashSet	getAttachedEndpoints() Returns a set of the attached endpoints.
int	getUniqueTransID(APEXStatus handler, APEXEndpointAddress aea) Returns a unique transaction identifier for the specified endpoint address.
void	handleIncomingMessage(APEXMessage message, Object receivingChannelID) When a message has been received on a connection it calls its manager's ' handleIncomingMessage' method.
void	messageDiscarded(APEXDataMessage m, int code, String reason) This mesthod is called when a connection wasn't able to send an 'APEXDataMessage', say a (where x !
void	messageSent(APEXDataMessage m, APEXReply reply) This mesthod is called when an 'APEXDataMessage' is successfully sent on a connection, say an element has been received.
void	removeAttachment(APEXEndpointAddress aea) Removes an attachment of the register and sends a notification to the application Internal use only!
void	removeAttachments(HashSet aeas) Removes a set of attachments of the register and sends a notification to the application Internal use only!
int	sendAPEXDataMessage(APEXDataMessage message) Sends an APEXDataMessage to the recipients specified within the object.
int	sendMessage(APEXDataMessage message, APEXStatus status) Sends an APEXDataMessage to the recipients specified within the object.
int	sendMessage(APEXEndpointAddress originator, APEXEndpointAddress recipient, byte[] content, String contentType, String transferEncoding, APEXStatus status) Sends a data message (MIME Multipart) to the specified recipient endpoint address containing the specified byte content.
int	sendMessage(APEXEndpointAddress originator, APEXEndpointAddress recipient, String content, APEXStatus status) Sends a data message to the specified recipient endpoint address containing the specified textual / XML content.
int	sendMessage(APEXEndpointAddress originator, HashSet recipients, byte[] content, String contentType, String transferEncoding, APEXStatus status) Sends a data message (MIME Multipart) to the specified recipient endpoint addresses containing the specified byte content.
int	sendMessage(APEXEndpointAddress originator, HashSet recipients, String content, APEXStatus status) Sends a data message to the specified recipient endpoint addresses containing the specified textual / XML content.
void	setAttachedAs(APEXEndpointAddress aea) Registeres an attached endpoint in the endpoint manager and sends a notification to the application.
void	terminate(APEXEndpointAddress aea, APEXStatus status) Terminates an attachment as the specified endpoint address or throws an APEXException if the manager is not attached as the specified endpoint
void	terminate(APEXEndpointAddress aea, int code, APEXStatus status) Terminates an attachment as the specified endpoint address or throws an APEXException if the manager is not attached as the specified endpoint
void	terminate(APEXEndpointAddress aea, int transID, int code, String content, String xmlLang, APEXStatus status) Terminates an attachment as the specified endpoint address or throws an APEXException if the manager is not attached as the specified endpoint
void	terminate(APEXEndpointAddress aea, int code, String content, APEXStatus status) Terminates an attachment as the specified endpoint address or throws an APEXException if the manager is not attached as the specified endpoint
void	terminate(APEXEndpointAddress aea, int code, String content, String xmlLang, APEXStatus status) Terminates an attachment as the specified endpoint address or throws an APEXException if the manager is not attached as the specified endpoint
int	terminate(APEXTerminateMessage atm, Object receivingChannelID) Is called when an terminate element is received a status code (for the reply is returned).

Methods inherited from class ch.epfl.lsr.apex.APEXManager

addTransaction, debug, getApplication, getFromTable, getFromTableAndLock, getTransaction, notification, parsePort, putToTable, putToTableAndUnlock, removeAllTransactions, removeFromTable, removeTransaction, sortOptions, unlockTable, validatePort

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

APEXEndpointManager

public APEXEndpointManager(APEXEndpointProcess application,
                           String serviceConfigurationFile)

Instantiates a new APEX endpoint manager using the standard port 912 for apex-edge-connections (say to its relay).

Parameters:

application - An application accepting call-backs (e.g. incoming messages, notifcations)

serviceConfigurationFile - The file name (path) of an optional service configuration file

APEXEndpointManager

public APEXEndpointManager(APEXEndpointProcess application,
                           String serviceConfigurationFile,
                           int edgePort)
                    throws APEXException

Instantiates a new APEX endpoint manager using a specified port number for apex-edge-connections (say to its relay).

Parameters:

application - An application accepting call-backs (e.g. incoming messages, notifcations)

serviceConfigurationFile - The file name (path) of an optional service configuration file

edgePort - The port number to contact the relay(s)

Throws:

APEXException - Thrown if the port number is not valid

Method Detail

getUniqueTransID

public int getUniqueTransID(APEXStatus handler,
                            APEXEndpointAddress aea)
                     throws APEXException

Returns a unique transaction identifier for the specified endpoint address.

Parameters:

handler - An APEXStatus for events on this transaction identifier

aea - The associated endpoint address (concering the channel)

Returns:

The transaction identifier

Throws:

APEXException - Thrown if the manager is not (yet) attached as the specified endpoint address

getAttachedEndpoints

public HashSet getAttachedEndpoints()

Returns a set of the attached endpoints.

Returns:

The attached endpoints

setAttachedAs

public void setAttachedAs(APEXEndpointAddress aea)

Registeres an attached endpoint in the endpoint manager and sends a notification to the application.

Internal use only!

To attach, use attachAs instead!

Parameters:

aea - The endpoint address to attach

removeAttachment

public void removeAttachment(APEXEndpointAddress aea)

Removes an attachment of the register and sends a notification to the application

Internal use only!

To release an attachment, use terminate instead!

Parameters:

aea - An endpoint address to remove

removeAttachments

public void removeAttachments(HashSet aeas)

Removes a set of attachments of the register and sends a notification to the application

Internal use only!

To release an attachment, use terminate instead!

Parameters:

aeas - A set of endpoint addresses (APEXEndpointAddress)

attachAs

public void attachAs(APEXEndpointAddress aea,
                     APEXStatus status)

Allows an application to attach as the specified endpoint and to set a listener on the APEXStatus.

The status' getStatus method can either be used as blocking directly after attaching or in a status listener thread.

Parameters:

aea - An endpoint address to attach as

status - A status or null if no status should be set

terminate

public void terminate(APEXEndpointAddress aea,
                      APEXStatus status)
               throws APEXException

Terminates an attachment as the specified endpoint address or throws an APEXException if the manager is not attached as the specified endpoint

Parameters:

aea - An endpoint address (attachment) to termination

status - A status listener or null

Throws:

APEXException - Thrown if the manager is not attached as the specified endpoint

terminate

public void terminate(APEXEndpointAddress aea,
                      int code,
                      APEXStatus status)
               throws APEXException

Terminates an attachment as the specified endpoint address or throws an APEXException if the manager is not attached as the specified endpoint

Parameters:

aea - An endpoint address (attachment) to termination

code - A code for termination (application use)

status - A status listener or null

Throws:

APEXException - Thrown if the manager is not attached as the specified endpoint

terminate

public void terminate(APEXEndpointAddress aea,
                      int code,
                      String content,
                      APEXStatus status)
               throws APEXException

Terminates an attachment as the specified endpoint address or throws an APEXException if the manager is not attached as the specified endpoint

Parameters:

aea - An endpoint address (attachment) to termination

code - A code for termination (application use)

content - A textual message or XML content

status - A status listener or null

Throws:

APEXException - Thrown if the manager is not attached as the specified endpoint

terminate

public void terminate(APEXEndpointAddress aea,
                      int code,
                      String content,
                      String xmlLang,
                      APEXStatus status)
               throws APEXException

Terminates an attachment as the specified endpoint address or throws an APEXException if the manager is not attached as the specified endpoint

Parameters:

aea - An endpoint address (attachment) to termination

code - A code for termination (application use)

content - A textual message or XML content

xmlLang - xml:lang attribute for this termination

status - A status listener or null

Throws:

APEXException - Thrown if the manager is not attached as the specified endpoint

terminate

public void terminate(APEXEndpointAddress aea,
                      int transID,
                      int code,
                      String content,
                      String xmlLang,
                      APEXStatus status)
               throws APEXException

Terminates an attachment as the specified endpoint address or throws an APEXException if the manager is not attached as the specified endpoint

Parameters:

aea - The endpoint address which originates the termination (rather domain)

transID - A transaction identifier to terminate

code - A code for termination (application use)

content - A textual message or XML content

xmlLang - xml:lang attribute for this termination

status - A status listener or null

Throws:

APEXException - Thrown if the manager is not attached as the specified endpoint

sendMessage

public int sendMessage(APEXEndpointAddress originator,
                       APEXEndpointAddress recipient,
                       String content,
                       APEXStatus status)

Sends a data message to the specified recipient endpoint address containing the specified textual / XML content. An APEXStatus may report on success or failure.

Parameters:

originator - Originator endpoint address

recipient - Receipient endpoint address

content - Textual or XML content

status - A status listener or null

Returns:

An internal three-digit status indicating if the message is transfered to the appropriated channel

sendMessage

public int sendMessage(APEXEndpointAddress originator,
                       HashSet recipients,
                       String content,
                       APEXStatus status)
                throws APEXParsingException

Sends a data message to the specified recipient endpoint addresses containing the specified textual / XML content. An APEXStatus may report on success or failure.

Parameters:

originator - Originator endpoint address

recipients - A set of receipient endpoint addresses

content - Textual or XML content

status - A status listener or null

Returns:

An internal three-digit status indicating if the message is transfered to the appropriated channel

Throws:

APEXParsingException

sendMessage

public int sendMessage(APEXEndpointAddress originator,
                       APEXEndpointAddress recipient,
                       byte[] content,
                       String contentType,
                       String transferEncoding,
                       APEXStatus status)
                throws APEXParsingException

Sends a data message (MIME Multipart) to the specified recipient endpoint address containing the specified byte content. An APEXStatus may report on success or failure.

Parameters:

originator - Originator endpoint address

recipient - Receipient endpoint address

content - Byte content for this message

contentType - the content type or null for none

transferEncoding - the encoding of the byte content

status - A status listener or null

Returns:

An internal three-digit status indicating if the message is transfered to the appropriated channel

Throws:

APEXParsingException - Thrown if the creation if the MIME Multipart fails

sendMessage

public int sendMessage(APEXEndpointAddress originator,
                       HashSet recipients,
                       byte[] content,
                       String contentType,
                       String transferEncoding,
                       APEXStatus status)
                throws APEXParsingException

Sends a data message (MIME Multipart) to the specified recipient endpoint addresses containing the specified byte content. An APEXStatus may report on success or failure.

Parameters:

originator - Originator endpoint address

recipients - A set of receipient endpoint addresses

content - Byte content for this message

contentType - the content type or null for none

transferEncoding - the encoding of the byte content

status - A status listener or null

Returns:

An internal three-digit status indicating if the message is transfered to the appropriated channel

Throws:

APEXParsingException - Thrown if the creation if the MIME Multipart fails

sendMessage

public int sendMessage(APEXDataMessage message,
                       APEXStatus status)

Sends an APEXDataMessage to the recipients specified within the object.

Parameters:

message - The message to be sent

status - A status listener or null

Returns:

An internal three-digit status indicating if the message is transfered to the appropriated channel

sendAPEXDataMessage

public int sendAPEXDataMessage(APEXDataMessage message)

Sends an APEXDataMessage to the recipients specified within the object.

Specified by:

sendAPEXDataMessage in class APEXManager

Parameters:

message - Data message to be sent. If no recipients are specified, no action is taken.

Returns:

A three-digit status reply code for the message.

terminate

public 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

Specified by:

terminate in class APEXManager

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

handleIncomingMessage

public void handleIncomingMessage(APEXMessage message,
                                  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, say if it is an

• attach element: call 'attachEndpoint' method
• terminate element: call 'terminate' method
• data element: call 'processData' method
• otherwise: send an error reply

Specified by:

handleIncomingMessage in class APEXManager

Parameters:

message - 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 void messageDiscarded(APEXDataMessage m,
                             int code,
                             String reason)

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

Note: In an APEXEndpointAddress, no messages can be discarded, since there is no relaying

Specified by:

messageDiscarded in class APEXManager

Parameters:

m - The message which wasn't sent

code - The error code of this message

reason - A textual reason

messageSent

public void messageSent(APEXDataMessage m,
                        APEXReply reply)

This mesthod is called when an 'APEXDataMessage' is successfully sent on a connection, say an element has been received. All applicable services are called by their method 'handleSent'

Note: In an APEXEndpointAddress, no messages relayed, thus, this method is not used.

Specified by:

messageSent in class APEXManager

Parameters:

m - The message which has successfully sent

reply - The reply object received of the next hop