|
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--java.lang.Thread | +--com.ls.lars.communication.CommunicationTemplate
provides the basic communication and logging functionalities needed by lars agents
Field Summary | |
protected String |
agentName
Name of this agent, initialized in the constructor. |
protected String |
homePlatform
lars platform where this agent was born |
protected IPKIHandler |
iPKIHandler
the Interface to integrate PKI-Handling |
protected ILogger |
logger
log file of this agent |
static boolean |
STATUS_CONNECTED
connectionStatus = STATUS_CONNECTED: connection to lars platform is ok |
static boolean |
STATUS_NOT_CONNECTED
connectionStatus = STATUS_NOT_CONNECTED: connection to lars platform is not available |
Fields inherited from class java.lang.Thread |
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY |
Constructor Summary | |
CommunicationTemplate(String agentName,
Map connectionParameters)
Constructor, that is used, if the agent wants to use and set up a it's own remote messenger (for example a SocketMessenger for socket communication). |
|
CommunicationTemplate(String agentName,
String homePlatform)
Constructor, that creates a local messenger and does the basic initialization of a new agent. |
Method Summary | |
void |
addConnectionParameter(String key,
Object connectionParameter)
Sets a connection parameter e.g. compression settings, secure settings, ... |
protected void |
checkSendSystemReply(Message message,
String serviceOfReply,
int failureCode,
String reasonDescription)
Called to check, whether the system needs to generate and send a reply to the given message for the specified failure code. |
void |
connect()
Initiates to connect to the lars system and then calls Messenger#waitForConnection() .
|
protected String |
createReplyId()
returns a unique number / key to be used as reply ID of a message |
void |
disconnect()
Disconnects from the lars system (if already connected). |
protected void |
disconnectForMigration()
used for disconnecting an agent form a platform when he's mirating |
abstract void |
executeLifeCycle()
Implements the "until the thread" loop (which probably in a while loop receives messages from the inbox by calling receiveBlockedMessage() and interprets them).
|
protected void |
finalize()
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. |
void |
forwardMessage(Message message,
List forwardReceivers)
Forwards a message by creating a shallow copy and then exchanging the receiver in the copy. |
void |
forwardMessage(Message message,
String forwardReceiver)
Forwards a message by creating a shallow copy and then exchanging the receiver in the copy. |
String |
getAgentName()
returns the name of the agent |
Map |
getConnectionParameters()
Gets the connection parameters e.g. compression settings, secure settings, ... |
int |
getInboxSize()
returns the size of the inbox |
String |
getLarsHost()
Returns the host name of the lars system. |
long |
getNumberOfProcessedMessages()
returns the number of processed messages since the start of the agent |
long |
getNumberOfProcessedMessagesPerMinute()
returns the number of processed messages per hour |
long |
getStartTime()
returns the start time this agent in milliseconds since 01-jan-1970 |
boolean |
isConnected()
Checkes if the object(messanger) is connected to the lars system or not. |
protected void |
logInbox()
writes the content of the inbox of the agent to its log file |
Message |
receiveBlockedMessage()
waits until a message arrives in the agent's inbox and returns it It may happen that an existing connection becomes invalid physically (e.g. due to a platform crash) - althought this party gets not informed about that. |
Message |
receiveBlockedMessage(long timeout)
Waits until a message arrives in the agent's inbox and returns it If there is currently no message available, the method will wait for timeout
milliseconds to receive one - after that time span it returns null .
|
protected boolean |
reconnectAfterMigration()
Reconnects an agent on a (guest) platform. |
void |
run()
Executes when this thread gets started. |
void |
sendMessage(Message message)
sends a message Note: the sender of the message is set to the current agent's name |
Message |
sendSynchronousRequest(Message message)
sends a message expecting a request for synchronous messaging by calling sendSynchronousRequest(Message, long) |
Message |
sendSynchronousRequest(Message message,
long timeout)
sends a message expecting a request for synchronous messaging Note: the sender of the message is set to the current agent's name Note for developers: You should use this method if - and only if - you're absolutely sure that the call does not make your agent blocking for a longer period. |
void |
setConnectionParameters(Map connectionParameters)
Sets the connection parameters e.g. compression settings, secure settings, ... |
protected void |
setLog()
sets the ILogger of the messenger |
protected void |
setMeantimeBetweenConnectionCheck(long meantime)
sets the meantime between checking the connection |
boolean |
terminateAction()
Executes actions that have to be performed before the agent terminates. |
void |
waitForConnection()
Blocks the calling thread, if the current connection status is STATUS_NOT_CONNECTED . |
void |
waitForConnection(long timeout)
Blocks the calling thread, if - timeout time in milliseconds is not reached and - current connection status is STATUS_NOT_CONNECTED .
if the timeout is zero, then the thread blocks as long as the connection status is
not changed in a connection setup inside of a Messenger (then called by another thread). |
Methods inherited from class java.lang.Thread |
activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, toString, yield |
Methods inherited from class java.lang.Object |
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Methods inherited from interface com.ls.lars.communication.IToLars |
start |
Field Detail |
public static final boolean STATUS_NOT_CONNECTED
public static final boolean STATUS_CONNECTED
protected final String agentName
protected String homePlatform
protected IPKIHandler iPKIHandler
protected transient ILogger logger
Constructor Detail |
public CommunicationTemplate(String agentName, String homePlatform) throws NullPointerException
agentName
- name of the agent (example: xyz )homePlatform
- name of the platform, where the agent was created (example: 195.52.158.233/lars)NullPointerException
- If the given agentName is null or empty or
If the given homePlatform is null or emptyLocalMessenger
public CommunicationTemplate(String agentName, Map connectionParameters) throws ConnectionException, NullPointerException
keys
for this map
are defined in the ICommunication
interface.agentName
- name of the agent (example: "xyz@195.52.158.233/lars")connectionParameters
- being used for establishing the connectionConnectionException
- if a connection cannot be establishedNullPointerException
- If the given agentName is null or empty or
if the given map is null or
if the given map does not contain mappings for
ICommunication.HOST_IP
and ICommunication.HOST_ID
ClientMessengerFactory
,
ICommunication
Method Detail |
protected void setLog()
protected void setMeantimeBetweenConnectionCheck(long meantime)
meantime
- the time between connection checkspublic final int getInboxSize()
public final long getNumberOfProcessedMessages()
public final long getNumberOfProcessedMessagesPerMinute()
public final String getAgentName()
getAgentName
in interface ICommunication
public final String getLarsHost()
getLarsHost
in interface IToLars
public final long getStartTime()
protected final void logInbox()
public final boolean isConnected()
isConnected
in interface IToLars
public final void sendMessage(Message message)
sendMessage
in interface ICommunication
message
- message to be sentpublic final Message sendSynchronousRequest(Message message) throws TimeoutException, ProgrammingException
sendSynchronousRequest(Message, long)
sendSynchronousRequest
in interface ICommunication
message
- to be sentTimeoutException
- If no message with the specified reply ID could be read from the inbox within the
default timeout timeProgrammingException
- If no 'replyWith' field was specified for the synchronous requestpublic final Message sendSynchronousRequest(Message message, long timeout) throws TimeoutException, ProgrammingException
Note for developers: You should use this method if - and only if - you're absolutely sure that the call does not make your agent blocking for a longer period. Especially when your agent holds a very important position on the , platform this blocking could result in an very bad runtime behavior of the whole system.
Example:
Think of an agent, who is to process multiple incoming requests from a number of connected servlets.
When you are sending the messages synchronously using this method, all other requests are blocked until the
agent receives the response for the outgoing message, or receives a TimeoutException
.
The more sophisticated way would be to send all your messages only in an asynchronous way using the standard
sendMessage(Message)
method. In this case your agent is not blocked and thus free to perform any
other operations, instead of wasting time while waiting for an awaited response message.
sendSynchronousRequest
in interface ICommunication
message
- message to be senttimeout
- time in milliseconds how long to wait for an answer, before throwing a TimeoutExceptionTimeoutException
- If no message with the specified reply ID could be read from the inbox within the
specified timeout timeProgrammingException
- If no 'replyWith' field was specified for the synchronous requestpublic final void forwardMessage(Message message, String forwardReceiver)
SingleMessage
, it is converted into a
SingleMessage. Then the original message type cannot be determined at the forwardReceiver any more. forwardMessage
in interface ICommunication
message
- message to be forwardedforwardReceiver
- new receiver of the message (the one, to whom the message will be forwarded)public final void forwardMessage(Message message, List forwardReceivers)
MulticastMessage
, it is converted into a
MulticastMessage. Then the original message type cannot be determined at the forwardReceivers any more. forwardMessage
in interface ICommunication
message
- message to be forwardedforwardReceivers
- list of new receivers of the message (the ones, to whom the message will be forwarded)public final Message receiveBlockedMessage()
Messenger#getBlockedInboxMessage()
public final Message receiveBlockedMessage(long timeout) throws TimeoutException
timeout
milliseconds to receive one - after that time span it returns null
.
It may happen that an existing connection becomes invalid physically
(e.g. due to a platform crash) - althought this party gets not informed
about that. Therefore we check the underlying messenger's connection status
explicitely before calling its Messenger#getBlockedInboxMessage()
timeout
- timeout time in milliseconds after null
will be returned.TimeoutException
- if no message could be received within the specified amount of timeprotected final void checkSendSystemReply(Message message, String serviceOfReply, int failureCode, String reasonDescription)
QualityOfService.createReply(message, serviceOfReply, failureCode, reasonDescription, null)
returns a reply message, this is sent.message
- message which's quality of service needs to be checkedserviceOfReply
- service to use in the reply messagefailureCode
- code of the failure (see QualityOfService
)reasonDescription
- contains the textual description of the reason for the failureprotected final String createReplyId()
public final void run()
messenger.waitForConnection()
executeLifeCycle()
disconnect()
run
in class Thread
public abstract void executeLifeCycle()
receiveBlockedMessage()
and interprets them).
Note: This method is called in run()
, after the messenger
was initialized.
public void connect() throws ConnectionException
Messenger#waitForConnection()
.
This method uses the connection parameters, which have to be provided by setConnectionParameters(Map)
.connect
in interface IToLars
ConnectionException
- If the connection setup failspublic void disconnect()
disconnect
in interface IToLars
public boolean terminateAction()
public void setConnectionParameters(Map connectionParameters)
setConnectionParameters
in interface IToLars
connectionParameters
- contains any Map with any parameterspublic void addConnectionParameter(String key, Object connectionParameter)
key
- key of the parameterconnectionParameter
- value of the parametersetConnectionParameters(java.util.Map)
public Map getConnectionParameters()
getConnectionParameters
in interface IToLars
public void waitForConnection() throws ConnectionException
STATUS_NOT_CONNECTED
. The calling thread is blocked as long as the connection
status is not changed in a connection setup inside of a Messenger (then called by another thread).waitForConnection
in interface IToLars
ConnectionException
- If the connection setup failsMessenger#waitForConnection
public void waitForConnection(long timeout) throws ConnectionException
STATUS_NOT_CONNECTED
.
if the timeout is zero, then the thread blocks as long as the connection status is
not changed in a connection setup inside of a Messenger (then called by another thread).waitForConnection
in interface IToLars
timeout
- time in milliseconds; How long is the calling thread waits until
an exception is thrown.ConnectionException
- If the connection setup failsprotected final void disconnectForMigration()
protected boolean reconnectAfterMigration()
protected void finalize() throws Throwable
finalize
in class Object
Throwable
- If an error occurs
|
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |