moses.member
Class Member

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

All Implemented Interfaces:

java.lang.Runnable

public class Member

extends java.lang.Object

implements java.lang.Runnable

This class represents the communication interface between an agent and its controller. A java program becoming part of a community (a proper agent) has to instantiate this class. In general, an interaction session consists from a call to the adopt() or reconnect() method, followed by sending and receiving messages through one of the corresponding methods, and ending in a call to the close method.

    Member m = new Member(...);
 
    m.adopt(...);
 
    m.send_lg(...);
    m.receive_lg();
 
    m.close();
 
    

Beside the methods that handle the above steps, there are several methods dedicated to submitting certificates either as individual messages or as part of the adoption process.
The constructors are responsible for initializing this object's field variables regarding the moses addressing scheme and other aspects of the interaction with the controller.

As this object offers the means of communication between agents within a community, a large part of the functionality is dedicated to sending and receiving methods. The sending method is overloaded such that it accomodates various data types: String, byte[],and Object , as well as XML-formated strings.

In order to allow a convenient method of treating export operations (sending messages to agents operating under different laws - see Moses manual for details) all the sending methods allow an extra String argument representing the law name of the destination agent. The name of the law is interpreted according to the portal field (see Distinguished Control State DCS) of the source agent.

This object implements three receiving methods, distinguished by the data type of the result: String, XML-formatted String, and moses.member.Answer . The last method, the most general of all, returns a wrapper class that allows extraction of messages of various data types. The String method is implemented for convenience and for maintaining compatibility with previous moses.member implementations. The XML method allows retrieval of messages in XML format.

Field Summary

java.lang.String	controllerHost Variable maintaining the name of the controller host.
java.lang.String	controllerLongName Variable maintaining the long name of the controller host.
int	controllerPort Variable maintaining the port of the controller.
java.lang.String	law Variable maintaining the law this agent operates under.
java.lang.String	longName Variable maintaining the full name of an agent.
static int	MAX_NACK Constant specifying the maximum number of unacknowledged message at any moment of time.
static int	MAX_SLEEP Constant specifying the maximum amount of time (in milli-seconds ) elapsed without acknowledging a message.
java.lang.String	shortName Variable maintaining the short name of an agent.

Constructor Summary

Member(java.lang.String law, int lawType, java.lang.String controllerHost, int controllerPort, java.lang.String shortName)
Shorter version of the previous constructor, where no certifying authority public key is supplied.

Member(java.lang.String law, int lawType, java.lang.String controllerHost, int controllerPort, java.lang.String shortName, java.security.PublicKey controllerAuPk)
Creates a new member instance.

Member(java.lang.String lawurl, java.lang.String controllerHost, int controllerPort, java.lang.String shortName)
The shortest form of the constructor.

Method Summary

void	addCertificate(moses.security.LGICert cert, byte[] sign) Appends a pair to the certificate list This method, together with the clearCertificateList method allows manipulation of the certificate list stored by this Member's instance.
int	adopt(java.lang.String passwd, java.lang.String args) This method request a TCPIP connection between this member object and the controller.
int	changePassword(java.lang.String newPass, java.lang.String oldPass) This method is one of the two methods used by an agent to change its reconnecting password.
void	clearCertificateList() Clears the list of certificates to be submitted during adoption An agent can submit a list of certificates to its controller as part of the adoption/connection procedure.
void	close()
moses.member.Answer	generic_receive_lg() This method is the main method used by an agent for receiving messages.
static void	main(java.lang.String[] args)
java.lang.String	receive_lg() This method is designed mainly to maintain backwards compatibility with previous versions of Moses system.
moses.member.Answer	receiveXML_lg() This method is mostly similar to the previous receive_lg method.
int	reconnect(java.lang.String passwd) This method attempts to reestablish a connection with a controller, given that the controller maintains the state for this agent.
void	run() Thread that runs in background and acknowledge messages each MAX_SLEEP ms.
boolean	send_lg(byte[] bmessage, java.lang.String destination) This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages.
boolean	send_lg(byte[] bmessage, java.lang.String destination, java.lang.String lname) This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages.
boolean	send_lg(java.lang.Object omessage, java.lang.String destination) This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages.
boolean	send_lg(java.lang.Object omessage, java.lang.String destination, java.lang.String lname) This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages.
boolean	send_lg(java.lang.String message, java.lang.String destination) This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages.
boolean	send_lg(java.lang.String message, java.lang.String destination, java.lang.String lname) This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages.
int	sendCertificate(moses.security.LGICert cert) This method is used by an agent to submit an LGI certificate to its controller.
int	sendSelfCertificate(moses.security.LGICert cert, byte[] mySign) This method is used by an agent to submit an LGI self certificate to its controller.
boolean	sendXML_lg(java.lang.String message, java.lang.String destination) This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages.
boolean	sendXML_lg(java.lang.String message, java.lang.String destination, java.lang.String lname) This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages.
boolean	test(java.lang.String firstArg, java.lang.String secondArg) This method sends a special TEST - type message to the controller.

Methods inherited from class java.lang.Object

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

Field Detail

shortName

public java.lang.String shortName

Variable maintaining the short name of an agent.
This variable is initialized by one of the constructors of this object, and represent the name chosen by the agent itself.

longName

public java.lang.String longName

Variable maintaining the full name of an agent.
The full name of the agent is composed from the agent short name and the controller long name separted by the @ symbol, in an email-like format. This variable is initialized by one of the constructors of this object.

law

public java.lang.String law

Variable maintaining the law this agent operates under.
Depending on the lawType variable, this field may have on of the following meanings:
-if lawType == Const.URL_LAW (or 0 as defined in moses.util.Const), then law holds the URL where the law can be accessed;
-if lawType == Const.IMM_LAW (or 1 as defined in moses.util.Const), then law holds the text in String format representing the content of this law;
This variable is initialized by one of the constructors of this object.

controllerHost

public java.lang.String controllerHost

Variable maintaining the name of the controller host.
The Internet name of the controller host is supplied by the agent prior to connecting to the controller.
This variable is initialized by one of the constructors of this object.

controllerLongName

public java.lang.String controllerLongName

Variable maintaining the long name of the controller host.
This field is designed to hold the Internet cannonical name of the host of the controller. As the present implementation, this variable is always equals with the controllerHost variable. In the future implementations, however, this variable will hold the result of the getCannonicalHostName() call supplied with a controllerHost argument. As this method only appears in Java 1.4.0 implementation, and the curent moses package is Java 1.3.0 compliant, this field is superfluous.
This variable is initialized by one of the constructors of this object.

controllerPort

public int controllerPort

Variable maintaining the port of the controller.
This variable is initialized by one of the constructors of this object, and represents the IP port where the controller waits for connections from the agents.

MAX_NACK

public static final int MAX_NACK

Constant specifying the maximum number of unacknowledged message at any moment of time. See also receive_lg() and close() method descriptions.

See Also:

Constant Field Values

MAX_SLEEP

public static final int MAX_SLEEP

Constant specifying the maximum amount of time (in milli-seconds ) elapsed without acknowledging a message. See also receive_lg() and close() method descriptions.

See Also:

Constant Field Values

Constructor Detail

Member

public Member(java.lang.String law,
              int lawType,
              java.lang.String controllerHost,
              int controllerPort,
              java.lang.String shortName,
              java.security.PublicKey controllerAuPk)

Creates a new member instance. It is responsible for instantiation and initialization of member fields with argument variables..The following list of parameters should be provided:

Parameters:

law - specifies the law an agent wants to operate under after adoption. Depending on the value of the lawType argument, this argument stores either the text of the law or the absolute URL where the text of the law can be retrieved from. The law can be published by any server following HTTP 1.1 protocol.

lawType - is a modifier argument, specifying the way the law argument is interpreted. Acceptable values are moses.util.Const.URL_LAW ( int value 0 ) or moses.util.Const.IMM_LAW ( i.e. immediate law, int value 1 ).

controllerHost - represents the fully qualified host name of the controller.

controllerPort - represents the port number the controller waits for agents to connect. The default value for the controller port number is 9000.

shortName - the name an agent wants to bear as a member of the community. Since agent names are globally unique, the adoption of the agent can fail because of a poor name choice.

controllerAuPk - public key of the certifying authority that certifies this controller as a "certifiedController" (as defined by moses.util.Const.ATTRIBUTES). This public key is used in order to verify the certificate a controller submits during the connection phase, as a proof of trust for the agent.

Member

public Member(java.lang.String law,
              int lawType,
              java.lang.String controllerHost,
              int controllerPort,
              java.lang.String shortName)

Shorter version of the previous constructor, where no certifying authority public key is supplied. If no public key is suplied, any submitted certificate is ignored during connection phase.

Parameters:

law - specifies the law an agent wants to operate under after adoption. Depending on the value of the lawType argument, this argument stores either the text of the law or the absolute URL where the text of the law can be retrieved from. The law can be published by any server following HTTP 1.1 protocol.

lawType - is a modifier argument, specifying the way the law argument is interpreted. Acceptable values are moses.util.Const.URL_LAW ( int value 0 ) or moses.util.Const.IMM_LAW ( i.e. immediate law, int value 1 ).

controllerHost - represents the fully qualified host name of the controller.

controllerPort - represents the port number the controller waits for agents to connect. The default value for the controller port number is 9000.

shortName - the name an agent wants to bear as a member of the community. Since agent names are globally unique, the adoption of the agent can fail because of a poor name choice.

Member

public Member(java.lang.String lawurl,
              java.lang.String controllerHost,
              int controllerPort,
              java.lang.String shortName)

The shortest form of the constructor. It creates an Member instance assuming the law is suplied in an URL form. ( lawType is moses.util.Const.URL_LAW ).

Parameters:

controllerHost - represents the fully qualified host name of the controller.

controllerPort - represents the port number the controller waits for agents to connect. The default value for the controller port number is 9000.

shortName - the name an agent wants to bear as a member of the community. Since agent names are globally unique, the adoption of the agent can fail because of a poor name choice.

Method Detail

clearCertificateList

public void clearCertificateList()

Clears the list of certificates to be submitted during adoption An agent can submit a list of certificates to its controller as part of the adoption/connection procedure. The controller then verifies these certificates and present them to the law evaluation in the adoption event. The Member class maintains a private variable for storing the list of certificates. Prior to calling the adoption method, one might want to modify this list of certificates through one of the addCertificate and clearCertificateList methods.
This method clears all the certificates previously stored in this Members list of certificates. As a result, later on during adoption no certificate will be sent to the controller.

See Also:

addCertificate(moses.security.LGICert, byte[])

addCertificate

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

Appends a pair to the certificate list This method, together with the clearCertificateList method allows manipulation of the certificate list stored by this Member's instance. The certificates added using this method will be sent to the controller during adoption/connection phase. The certificates can be of two types: self certificates and proper certificates (the later are also called certificates). A self certificate is a proper certificate whose subject is the bearer of the certificate. In order to prove this relationship, a self certificate is accomanied by a signature of the certificate by the owner of this certificate. This method allows for submitting self certificates by maintaining the signature along with the certificate.

Parameters:

cert - represent the certificate to submit to the controller during adoption. The certificate (of LGICert type) can be either a proper or a self certificate. It can be created and handled by using certCreation class.

sign - represent the signature corresponding to a self certificate. If the argument is null, then cert argument is intrepreted as a proper certificate.

See Also:

clearCertificateList(), LGICert, certCreation

adopt

public int adopt(java.lang.String passwd,
                 java.lang.String args)

This method request a TCPIP connection between this member object and the controller. A connection is attempted to the host and the port specified by the object variables and (previously initialized). After succesfully establishing the connection, a special message is sent to the controller in a format defined by moses.message.Message class. This message contains mainly the following information: the desired name of the agent, the law this agent wants to operate under (either as immediate value or as URL), the password used for reconnection, and the argument provided by the user ( the later two fields taken as arguments to this method). If this object stores any certificate, they are also send along within this message.

As a result of this message, the controller starts the procedure of creating an LGI agent. The main steps involved are the downloading and the verification of the law, checking the name of the agent, and setting up the state associated with this agent (Control State CS, Distinguished Control State DCS, with all its components), and other data structures internal to the controller. The controller will also set up a mailbox where all the un-acknowledged messages will be stored. Subsequent to these steps, if the creation of the agent is succesfull, an adopted event will be triggered according to the law this agent operates under. In the same time, an acceptance message will be sent back to this Member object. If the controller is not able to create an LGI agent (for reasons discussed below), a rejected message is sent back.

If there were certificates previously stored in this object (using addCertificate method), these certificates will be send as part of the first message to the controller. After their proper verification these certificates will be presented as part of the adopted event. The failure to verify the validity of a certificate will be treated quietly: the adoption will still be succesfull (thus a succesful message will be sent to this object), but the adoption event will not include the failed certificate. In extremis, if none of the certificates passes the verification stage, the adopted events will be evaluated with an empty list of certificates.

Some other details of the adoption procedure are also discussed in the context of the adoption event in the law object.

Parameters:

passwd - represents the password to be used later for reconnection to this controller should this connection will be torn down or the agent will temporarly disconnect. Once the password is established, it can be changed in two ways: either using this obejct's changePassword method, or within the law, by using the setPassword primitive operation. This second method is also discussed in the documentation adjacent to the description of the law.

args - represents an arbitrary string to be used during the evaluation of the adoption event. In the case of an agent operating under a law written in Java, the string can be any arbitrary string. In the case of a Prolog law, this string should follow the syntax of a properly formed Prolog term.

Returns:

an integer specifying the acceptance or the rejection code for the adopt method. As defined in moses.util.Const class, the following are the return values and their interpretation:

• -1 : successful adoption

• 3 : the controller has replied with an invalid answer
• 4 : the proposed name is malformed, containing special characters ( '@' and '.')
• 8 : the certificate/signature send by the controller failed the verification
• 10 : the name submitted is already used by an active agent
• 12 : the controller cannot be contacted at the

• 21 : failure to download the law
• 22 : failure to parse the law: inproper format
• 23 : hashing failure: unable to compute the hash of the law
• 24 : preamble failure: the preamble of the law is invalid
• 25 : compilation failure: unable to compile the Java law
• 26 : generic, unspecified law failure

• 31 : authority generic failure
• 32 : failure to download a public key specified in an authority clause
• 33 : failure in computing the hash of the authority public key
• 34 : the law attempts to declare multiple authorities with the same public key hash

• 35 : the authority used in the law clause not declared in the authority table
• 41 : portal generic failure
• 42 : failure to download a law declared in the portal
• 43 : failure the compute the hash of a portal law
• 44 : the law attempts to declare multiple portal entries with the same law hash
• 45 : a portal clause attempts to use an undeclared authority

• 51 : alias clause not declared properly
• 52 : alias attempts to use a reserved name
• 53 : the Java law attempts to use object fields
• 54 : the Java law attempts to use restricted operation
• 55 : the Java law attempts to use a restricted inheritance

• 61 : initial control state in unproper format
• 65 : failure starting the Prolog engine

• 70 : message from controller is invalid

reconnect

public int reconnect(java.lang.String passwd)

This method attempts to reestablish a connection with a controller, given that the controller maintains the state for this agent. A connection is attempted to the host and the port specified by the object variables and (previously initialized). After succesfully establishing the connection, a special message is sent to the controller in a format defined by moses.message.Message class. This message contains mainly the following information: the name of the agent, and the password necesary to authenticate this member.

In order for the controller to accept the reconnection, the password should match the password maintained by the controller on behalf of the agent, and the state of the controller agent should be DISCONNECTED. The other two possible states of an agent are either CONNECTED (for a controller agent maintaining an active TCPIP connection with its agent) either UNCONNECTABLE (for a controller agent that has a "null" password as result of setPassword primitive operation). If the above steps are successful, a reconnected event is triggered for this agent. Simultaneously, the controller returns a sucessful message that will be provided as a result value of this method. Otherwise, an error message will be returned. If this method returns sucessfully, and the controller has previously stored any messages on behalf of this agent during the disconnection time, all the unacknowledged messages will be sent to this member.

Parameters:

passwd - represents the password provided as means of authenticating the member

Returns:

an integer specifying the acceptance or the rejection code for the reconnect method. As defined in moses.util.Const class, the following are the return values and their interpretation:

• -1 : successful reconnection

• 3 : the controller has replied with an invalid answer
• 5 : the password was invalid
• 8 : the certificate/signature send by the controller failed the verification
• 9 : the name of this agent is unknown to this controller, no state maintained for this name
• 11 : the controller agent is in an unconnectable state
• 12 : the controller cannot be contacted at the

• 70 : message from controller is invalid

send_lg

public boolean send_lg(java.lang.String message,
                       java.lang.String destination)

This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages. For every message sent using this method the following actions are taken. The message goes first to the controller, where it triggers the sent event-method. If the law of the sender is written in Prolog, and the message is not a Prolog expression, a notification invalid: original message is sent back to the actor. Next, if the law allows (based on the actual implementation of the sent event), the message is being forwarded to the destination.

Parameters:

message - represent the body of this message (i.e. the payload). Any non-nullvalue is allowed.

destination - represent the destination of this message. Unless the law itself overwrites this argument, this value should be a non-null moses address of the form "agent-name@controller.name".

Returns:

true if the message has been send succesfully to the controller. There are no guarantees with respect to the later handling of the message, less about the actual delivery at the destination. It returns false if the message could not be sent into the connection (if the connection expired or some other network errors have occured).

See Also:

send_lg( byte[] bmessage, String destination), send_lg( Object omessage, String destination), send_lg( byte[] bmessage, String destination), send_lg( String message, String destination, String lname), send_lg( Object omessage, String destination, String lname), sendXML_lg(String message, String destination, String lname), sendXML_lg(String message, String destination, String lname)

send_lg

public boolean send_lg(byte[] bmessage,
                       java.lang.String destination)

This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages. The method is mostly similar to the previous one, except that the payload message is a low-level byte array. Since it avoids serialization of the payload, this is the fastest sending method.

See Also:

send_lg( String message, String destination)

send_lg

public boolean send_lg(java.lang.Object omessage,
                       java.lang.String destination)

This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages. The method is mostly similar to the previous one, except that the payload message is a generic object. This method uses the underlying Java method for object serialization, thus it is the responsability of the user to send a proper serializable object. Moreover, since this object will be travelling into a different address space/ virtual machine, the sender should make sure that the base class of the object can be access at both the destination and the intermediary controllers mediating the communication. As of the current law model/controller implementation, only JDK and Moses objects can be transfered, although a full supporting implementation should come naturaly.

See Also:

send_lg( String message, String destination)

sendXML_lg

public boolean sendXML_lg(java.lang.String message,
                          java.lang.String destination)

This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages. The method is mostly similar to the previous one, except that the string message is assumed to be a proper XML document. Prior to sending the message, the message is converted into a Prolog compliant form. Al the previous observation hold for this method as well.

See Also:

send_lg( String message, String destination)

sendCertificate

public int sendCertificate(moses.security.LGICert cert)

This method is used by an agent to submit an LGI certificate to its controller. Once the controller receives and verifies the certificate, it triggers a certified event. The certificate can be obtain either by instantiating the LGICert constructor or by using the moses.security.certCreation utility in order to create, save, and retrieve an LGIcert object into and from a file. The public and private keys required for the above operations can be generated using moses.security.KeyGenerator and moses.security.keyPairCreation. The controller performs the following steps in order to verify the certificate. It first checks whether this law declares an authority having the public key of the certificate signer. If this is true, then it verifies the signature of the certificate. The next step is to find/generate a temporary name for the subject of this certificate. Finally, the certified event is triggered.

Parameters:

cert - represents a properly initialized LGIcert object.

Returns:

an integer specifying whether the certificate has been received and verified, or an error code otherwise. As defined in moses.util.Const class, the following are the return values and their interpretation:

• Const.VERSUCC (0) when the certificate has been send and verified succesfully by the controller.
• Const.CACPKMM (1) the certificate and the public key mismatch.
• Const.CASIGMM (3) the signature on the certificate does not verify.
• Const.CANOTREC (5) the certification authorithy is not recognizable (not in Authentication Table).
• Const.GENERIC_F (6) a generic filure/communication failure has occured.

See Also:

sendSelfCertificate(LGICert cert, byte [] mySign)

sendSelfCertificate

public int sendSelfCertificate(moses.security.LGICert cert,
                               byte[] mySign)

This method is used by an agent to submit an LGI self certificate to its controller. Once the controller receives and verifies the certificate, it triggers a certified event. A self certificate is a certificate whose holder (a.k.a. this sender) is also the subject of the certificate. The ownership is prooven by the submission of the certificate along with its signature. The signature is generated by signing the whole certificate with the private key of the holder. This method of source authentication, even though it is knownly flawed, has been temporary choosen over the standard nonce signature method for simplicity reasons. This method is mostly similar to the sendCertificate method. In addition to it the signature of the certificate is also submitted. The certificate can be obtain either by instantiating the LGICert constructor or by using the moses.security.certCreation utility in order to create, save, and retrieve an LGIcert object into and from a file. The signature can be obtain by using moses.security.Secu.signSelfCertificate method. The private and public keys required for the above operations can be generated using moses.security.KeyGenerator and moses.security.keyPairCreation. The verification of the certificate is mostly similar to the one performed after executing the sendCertificate method. In addition to this, the signature of the certificate is verified against the public key of the subject of this certificate. If the verification is succesful, a certified event is triggered. In the scope of this event, the name of the subject of this certificate will be the moses name of the agent submitting the certificate.

Parameters:

cert - represents a properly initialized LGIcert object.

mySign - represent the signature of the certificate performed with the private key of the submitting agent.

Returns:

an integer specifying whether the certificate and the signature has been received and verified, or an error code otherwise. As defined in moses.util.Const class, the following are the return values and their interpretation:

• Const.VERSUCC (0) when the certificate has been send and verified succesfully by the controller.
• Const.CACPKMM (1) the certificate and the public key mismatch.
• Const.CASIGMM (3) the signature on the certificate does not verify.
• Const.SIGMM (4) the signature of the subject on the certificate does not verify.
• Const.CANOTREC (5) the certification authorithy is not recognizable (not in Authentication Table).
• Const.GENERIC_F (6) a generic filure/communication failure has occured.

See Also:

sendCertificate(LGICert cert)

send_lg

public boolean send_lg(java.lang.String message,
                       java.lang.String destination,
                       java.lang.String lname)

This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages. The method is mostly similar to the previous ones, except that it implements a so called "export" operation (i.e. sending a message to an agent working under a different law than this agent). Although exporting a message can be achieved through the previous send methods, this represent a convenience shortcut to the same operation.

Parameters:

message - represent the body of this message (i.e. the payload). Any non-nullvalue is allowed.

destination - represent the destination of this message. Unless the law itself overwrites this argument, this value should be a non-null moses address of the form "agent-name@controller.name".

lname - represent the name of the law the destination operates under. The name of the destination law should be defined in the portal of the law of the sending agent. A non-null value is required.

See Also:

send_lg( String message, String destination)

send_lg

public boolean send_lg(byte[] bmessage,
                       java.lang.String destination,
                       java.lang.String lname)

This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages. The method is mostly similar to the previous one, except that the payload message is a low-level byte array.

See Also:

send_lg( String message, String destination)

send_lg

public boolean send_lg(java.lang.Object omessage,
                       java.lang.String destination,
                       java.lang.String lname)

This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages. The method is mostly similar to the previous one, except that the payload message is a generic object.

See Also:

send_lg( String message, String destination)

sendXML_lg

public boolean sendXML_lg(java.lang.String message,
                          java.lang.String destination,
                          java.lang.String lname)

This method is used by any agent that is curently connected to a controller in order to send LGI (regulated) messages. The method is mostly similar to the previous one, except that the string message is assumed to be a proper XML document.

See Also:

send_lg( String message, String destination)

generic_receive_lg

public moses.member.Answer generic_receive_lg()

This method is the main method used by an agent for receiving messages. It is a blocking method. When the agent calls this method, it blocks on the underlying TCP/IP stream until a moses message comes available from the controller. The communication between the controller and the agent employs a controller maintained message circular buffer, called mailbox. The main purpose of the mailbox is to hold messages on behalf of the user while the user is in a disconnected and connectible state (i.e. when the user is not connected, its state allows for latter reconnection). Every message that the controller delivers is also copied in the mailbox. In turn, the agent receiving messages from the controller are acknowledged. Upon acknowledging a message, the message is removed from the mailbox. The acknowledgement is cumulative: an acknowledgment type of message is sent every MAX_NACK received messages. This acknowledgment releases all messages from the mailbox whose message_id is smaller than this acknowledgement id. An acknowledgement to a message is sent back to the controller in two other situations. One situation is when there are messages received and not acknowledged for a MAX_SLEEP period of time. The second situation is when the agent disconnects from its controller gracefully, by using moses.member.Member.close() method. These both situations are out of the scope of the generic_receive_lg method. The mailbox can hold up to moses.controllerMailbox.MAILBOX_STD_SIZE messages.

Returns:

an Answer object. This object is a multifunctional object capable of holding various types of message payloads: strings, objects and byte arrays. It also holds information related to the source, destination and the law the message originates from.

See Also:

receive_lg()

receive_lg

public java.lang.String receive_lg()

This method is designed mainly to maintain backwards compatibility with previous versions of Moses system. The main difference is that this method returns a string result containing the payload, the source, the destination and the law the message originates from, all in a specific format. All the observations made during the genericc_receive_lg description also hold true here.

Returns:

a string of the following form: "arrived(source,string_payload,dest)" if the mesage originates from a different law than the law of this agent, the result will have the following form: "arrived([source,law],string_payload,dest)" The return string will be meaningful only in the case of messages with a String payload. If a message whose payload is not a string is received, then this method will return the following string: "arrived(source,Payload not a String,dest)" or: "arrived([source,law],Payload not a String,dest)"

See Also:

generic_receive_lg()

receiveXML_lg

public moses.member.Answer receiveXML_lg()

This method is mostly similar to the previous receive_lg method. Additionally, before this method returns the string result, it transforms it from a Prolog syntax into an XML form.

Returns:

a string in an XML format. If the payload of the message is not a string, or if any error has occured during XML parsing, a null value is returned.

See Also:

generic_receive_lg(), receive_lg()

changePassword

public int changePassword(java.lang.String newPass,
                          java.lang.String oldPass)

This method is one of the two methods used by an agent to change its reconnecting password. The other method is the doSetPasswd primitive operation. As a result of calling this method, the controller will change the password for this agent accordingly. The password will be changed only if the submitted old password will match the curent password. The following password values have a special meaning: moses.util.Const.EMPTY_PWD (defined as empty string "") moses.util.Const.NONE_PWD (defined as "none") moses.util.Const.NULL_PWD (defined as "null") The first two values represent a publicly open agent connectible by anybody. The last value represent an agent that is not in a connectible state. If attempted, the above values cannot be changed by this method.

Parameters:

newPass - represent the new password for the reconnection to this agent.

oldPass - represent the old password already in place.

Returns:

Const.CHPWD_OK if the password has been changed succesfully; Const.CHPWD_INVALID if the old password is one of the reserved passwords; Const.OPWD_MISMATCH if the submitted password does not match the old password; Const.CHPWD_GF if a communication error has occured during the execution of this method;

test

public boolean test(java.lang.String firstArg,
                    java.lang.String secondArg)

This method sends a special TEST - type message to the controller. When the agent is in the test mode, the messages sent to the controller are treated in a special mode. The "Moses Manual/User Interface" covers in more detail the testing interaction between the agent and the controller. In short, an agent sends a testing message using this method, while the the testing answer can be received using the (generic_)receive_lg method.

Returns:

true if the message has been sent properly into the network. It returns false if a transmission error has occured.

close

public void close()

run

public void run()

Thread that runs in background and acknowledge messages each MAX_SLEEP ms. The threads repeatedly sleeps and when the time elapsed or it has been woken up, it checks whether there are unacknowledged messages. If this is the case, it sends the proper "ack". Furthermore, if "this.status" is CONTROLLER_UNAVAILABLE (that's connection broken), try to clean up and exit.

Specified by:

run in interface java.lang.Runnable

main

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

java.lang.Exception