moses.member
Class ExMember

java.lang.Object
  |
  +--moses.member.ExMember

All Implemented Interfaces:

java.lang.Runnable

public class ExMember

extends java.lang.Object

implements java.lang.Runnable

This class represent the communication interface between an LGI agent and an external (non-LGI) agent. The communication between an LGI agent and a non-LGI agent is achieved by two mechanism:

• from an LGI agent to a non-LGI agent: the law can use a release primitive operation;
• from an non-LGI agent towards an LGI agent by the use of one of the submitted events;

This class provides a set of methods for communication that resembles the Member class API. Using this class, a non-LGI agent (throughout this document it is called External Member or ExMember) can receive a message previously sent using the release primitive by using a generic_receive_lg() method Alternately, by using one of the send() method, the ExMember produces a message that will trigger a submitted event at the LGI destination.

Beside the generic_receive_lg(), and send() methods, there are few other methods designed to provide means of authentication between the ExMember and the controller.

Generally an interaction session follows the pattern:

 
         ExMember xmember = new ExMember(sport,cport);
 
         xmember.send(msg, dest);
 
         Answer ans = xmember.generic_receive_lg();
 
         xmember.close();
    

Note that send and receive can appear in any order, and either of them can be missing;

The handling of the communication channel between the ExMember and the controller is significantly more complicated than the case of the Member communication. Both the ExMember and the controller can initiate a connection to each other (release/submitted scenario) or both can passively wait for incoming connection. As a consequence, the ExMember implements a TCP/Ip server that waits for incoming connections from the controller. All the connections an ExMember holds are kept together, in a pool of connections. This connection pool maintains both connections initiated by the controller, and self-initiated connections. In order to maintain the optimal number of connections, this class provides a method called close_connection() that will explicitly close a certain connection. A connection can expire either when it's closed by the controller (the controller has its own mechanism of tearing down connections in a "Last Recently Used" manner) or when this ExMember explicitly calls close_connection().

An ExMember initiate a connection towards a controller implicitly, whenever a send() method is invoked and there is no such connection in place towards the destination.

Since an ExMember can receive messages coming from multiple connections, it employs a common buffer for storing the messages from all the connections. The messages are deposited at the end of the buffer and read from the beginning of the buffer in a FIFO manner. Every connection implements a daemon reading from that connection and storing the messages in the buffer. The method generic_receive_lg() simply returns the messages from this buffer.

See Also:

Member

Field Summary

int	auth_method This is the authentication method used by this ExMember when submitting messages for the controller.
moses.security.LGICert	cert This variable holds the certificate to be submitted when the chosen authentication method is Const.A_CERT.
java.util.Hashtable	connections
int	cport This variable maintains the default port used by the infrastructure of controllers for communication In general, the default controller expects communication on port 9000.
java.util.LinkedList	messages
java.lang.String	pwd This variable holds the password to be submitted if the authentication method is Const.A_PWD.
java.lang.String	shost This variable maintain the host name of the machine where the ExMember is running at a particular instance.
byte[]	sign This variable holds the signature to be submitted along with a certificate when the chosen authentication method is Const.A_CERT.
int	sport This variable holds the master port number, the port used by this ExMember to wait for incoming connections from a controller.
java.net.ServerSocket	ss

Constructor Summary

ExMember(int sport, int cport)
The constructor of this class is mainly responsible for instantiating an ExMember variable.

Method Summary

void	append_message(moses.member.Answer ar) Internal method used by the generic_receive_lg for handling the implicit message queue.
void	close_connection(java.lang.String host, int port) This method is exposed in order to give the user a minimal control over what connections should be terminated explicitly.
void	close() This method gracefully terminates the interaction session for this ExMember object.
moses.member.Answer	generic_receive_lg() This method is the method used in receiving incoming messages.
static java.lang.String	hnp(java.lang.String host, int port)
static void	main(java.lang.String[] args)
moses.member.ExConnection	make(java.lang.String host, int port, java.lang.String dest) Internal method designed to create or retrieve a connection from the connection pool, based on the host and port of the controller.
void	remove_connection(moses.member.ExConnection exc) Internal method used for handling of the implicit connections.
void	run() This method represent the background server daemon responsible for accepting connections from the controller.
boolean	send(byte[] bmsg, java.lang.String dest) A byte array method used for sending messages to a controller (and subsequently to an LGI agent).
boolean	send(moses.message.Message m, java.lang.String host, int port) Method used internally for sending messages to the controller.
boolean	send(java.lang.Object omsg, java.lang.String dest) An object method used for sending messages to a controller (and subsequently to an LGI agent).
boolean	send(java.lang.String msg, java.lang.String dest) The main method (in a set of 3 methods) used for sending messages to a controller (and subsequently to an LGI agent).
void	setAuthenticationCert(moses.security.LGICert cert, byte[] sign) This method sets the authentication mechanism to be certificate oriented.
void	setAuthenticationNone() This method resets any authentication mechanism to the Const.A_NONE.
void	setAuthenticationPwd(java.lang.String pwd) This method sets the authentication mechanism to be password oriented.
void	setControllerDefaultPort(int cport) This method sets the controller port of contact to the value specified in the argument.

Methods inherited from class java.lang.Object

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

Field Detail

connections

public java.util.Hashtable connections

messages

public java.util.LinkedList messages

ss

public java.net.ServerSocket ss

sport

public int sport

This variable holds the master port number, the port used by this ExMember to wait for incoming connections from a controller.

shost

public java.lang.String shost

This variable maintain the host name of the machine where the ExMember is running at a particular instance.

cport

public int cport

This variable maintains the default port used by the infrastructure of controllers for communication In general, the default controller expects communication on port 9000.

auth_method

public int auth_method

This is the authentication method used by this ExMember when submitting messages for the controller. Allowable values are :

• 0 (as defined in moses.util.Const.A_NONE ),
• 1 (as defined in moses.util.Const.A_PWD ),
• 2 (as defined in moses.util.Const.A_CERT ),

cert

public moses.security.LGICert cert

This variable holds the certificate to be submitted when the chosen authentication method is Const.A_CERT.

sign

public byte[] sign

This variable holds the signature to be submitted along with a certificate when the chosen authentication method is Const.A_CERT.

pwd

public java.lang.String pwd

This variable holds the password to be submitted if the authentication method is Const.A_PWD.

Constructor Detail

ExMember

public ExMember(int sport,
                int cport)

The constructor of this class is mainly responsible for instantiating an ExMember variable. Beside saving the arguments, this method also spawns a thread that is waiting for incoming connection from controllers. When such connections are accepted they are added under the hood to an implicit connection pool.

Parameters:

sport - specifies the port used by this ExMember to wait for incoming connections.

cport - specifies the port to contact the controller on, when sending a message. Generally, a message's destination contains the name of the agent and the host name of the controller. This parameter is required to fully specify the address of the destination.

See Also:

Member

Method Detail

setAuthenticationPwd

public void setAuthenticationPwd(java.lang.String pwd)

This method sets the authentication mechanism to be password oriented. It takes the password arguments and saves it the local variable with the same name, and sets the authentication method variable to Const.A_PWD.

Parameters:

pwd - represents the password used by this ExMember to authenticate itself against the law of the destination;

See Also:

setAuthenticationNone(), setAuthenticationCert(LGICert, byte[])

setAuthenticationCert

public void setAuthenticationCert(moses.security.LGICert cert,
                                  byte[] sign)

This method sets the authentication mechanism to be certificate oriented. It takes the certificate and signature arguments and saves it the local variables with the same name, and sets the authentication method variable to Const.A_CERT.

Parameters:

cert - represents the certificate used by this ExMember to authenticate itself against the law of the destination;

sign - represents the signature performed over the certificate used by this ExMember to authenticate itself against the law of the destination. The details of the certificate-signature method of authentication are described at large in the moses.member.Member class.

See Also:

setAuthenticationNone(), setAuthenticationPwd(String)

setAuthenticationNone

public void setAuthenticationNone()

This method resets any authentication mechanism to the Const.A_NONE. No authentication is provided while interacting in this mode.

See Also:

setAuthenticationPwd(String), setAuthenticationCert(LGICert, byte[])

setControllerDefaultPort

public void setControllerDefaultPort(int cport)

This method sets the controller port of contact to the value specified in the argument. If calling this method previous to any send method, it allows the ExMember to handle simultaneous communication to controllers on different ports.

Parameters:

cport - represents the port on which to contact the controller

send

public boolean send(java.lang.String msg,
                    java.lang.String dest)

The main method (in a set of 3 methods) used for sending messages to a controller (and subsequently to an LGI agent). This method proceeds as follow. It first packages the message into a moses.message.Message object, used by the underlying mechanism for communication. In doing this, based on the value of the auth_method variable it either stores the tuple, the password, or neither of them. Following this, based on the host name part of the destination and the cport object variable, it looks up for a connection to the destination controller. If no such connection exists, it creates a new one and then sends the message into that connection.

Parameters:

msg - represents the String message to be submitted

dest - represent a moses formed agent destination name ("agent-name@controller.fully.qualified.name")

Returns:

true if the message has been pushed into connection successfully; returns false otherwise.

See Also:

send(Object, String), send(byte[], String)

send

public boolean send(byte[] bmsg,
                    java.lang.String dest)

A byte array method used for sending messages to a controller (and subsequently to an LGI agent). This method proceeds as follow. It first packages the message into a moses.message.Message object, used by the underlying mechanism for communication. In doing this, based on the value of the auth_method variable it either stores the tuple, the password, or neither of them. Following this, based on the host name part of the destination and the cport object variable, it looks up for a connection to the destination controller. If no such connection exists, it creates a new one and then sends the message into that connection.

Parameters:

dest - represent a moses formed agent destination name ("agent-name@controller.fully.qualified.name")

Returns:

true if the message has been pushed into connection successfully; returns false otherwise.

See Also:

send(String, String), send(Object, String)

send

public boolean send(java.lang.Object omsg,
                    java.lang.String dest)

An object method used for sending messages to a controller (and subsequently to an LGI agent). This method proceeds as follow. It first packages the message into a moses.message.Message object, used by the underlying mechanism for communication. In doing this, based on the value of the auth_method variable it either stores the tuple, the password, or neither of them. Following this, based on the host name part of the destination and the cport object variable, it looks up for a connection to the destination controller. If no such connection exists, it creates a new one and then sends the message into that connection.

Parameters:

dest - represent a moses formed agent destination name ("agent-name@controller.fully.qualified.name")

Returns:

true if the message has been pushed into connection successfully; returns false otherwise.

See Also:

send(String, String), send(byte[], String)

close

public void close()

This method gracefully terminates the interaction session for this ExMember object. It is responsible for closing all pending connections and their associated receiving threads as well as for shutting down the main server thread.

send

public boolean send(moses.message.Message m,
                    java.lang.String host,
                    int port)

Method used internally for sending messages to the controller. It is mostly similar to the previous sending methods. It exposes the internal moses.message.Message format for any message to be sent.

make

public moses.member.ExConnection make(java.lang.String host,
                                      int port,
                                      java.lang.String dest)

Internal method designed to create or retrieve a connection from the connection pool, based on the host and port of the controller. In the future releases, this method will have package access rights at most.

generic_receive_lg

public moses.member.Answer generic_receive_lg()

This method is the method used in receiving incoming messages. Simply, this method accesses the internal (implicit) message buffer and retrieves messages on a FIFO manner. The answers all come in an Answer type format, providing easy access to the different components of a message. The description of the Answer data type and its functionality is beyond the scope of this method and is discussed in the Answer documentation itself. Note: When establishing a TCP/IP connection with a certified controller, the first message that arrives on that connection represents the tuple held by the controller. Since the management of the connections happens mostly under the hood, any application using this ExMember object should accommodate the intermittent-nondeterministic arrival of such messages;

Returns:

an Answer object packing the fields of an incoming message.

See Also:

Member.generic_receive_lg(), Answer

append_message

public void append_message(moses.member.Answer ar)

Internal method used by the generic_receive_lg for handling the implicit message queue. In the future Moses releases, it will have at most package access right.

remove_connection

public void remove_connection(moses.member.ExConnection exc)

Internal method used for handling of the implicit connections. In the future Moses releases, it will have at most package access right.

close_connection

public void close_connection(java.lang.String host,
                             int port)

This method is exposed in order to give the user a minimal control over what connections should be terminated explicitly. The connection to this is retrieved from the connection pool. After it is found, it is closed explicitly.

Parameters:

host - represents the host of the controller

port - represent the port of the controller for the targeted connection victim

run

public void run()

This method represent the background server daemon responsible for accepting connections from the controller. After a connection request comes, the connection is established and a receiver thread is spawn for that particular connection. This receiver thread is responsible for receiving messages and appending them to a common buffer for later retrieval by the generic_receive_lg method. This method is not to be called. Instead it is launched as a daemon-thread implicitly from the constructor of this class.

Specified by:

run in interface java.lang.Runnable

hnp

public static java.lang.String hnp(java.lang.String host,
                                   int port)

main

public static void main(java.lang.String[] args)