org.iperg.part.core
Class IpNetworkEvent

java.lang.Object
  org.iperg.part.core.IpEvent
      org.iperg.part.core.IpNetworkEvent

All Implemented Interfaces:

IpSerializable

public final class IpNetworkEvent
extends IpEvent
implements IpSerializable

The IpNetworkEvent class is used to represent events that can be sent to remote platform objects, via the network.

Network events have replicated object identifiers as their destinations. When sending the event using the send method, the identifier is used to determine the network route to use to deliver the event to its destination object. If the destination is a process identifier, the event will be delivered to the event handler registered with the IpLocalProcess singleton instance on the remote process.

A network event can hold data via its payload attribute. The payload is an io stream where the sender can encode arbitrary data. The receiver of a network event can retrieve the payload stream and decode the data encoded by the sender.

If the sender of an event wants to receive a reply, the IpNetworkEvent class provides a number of methods that can be used to synchronise the sender and receiver. Basically there are two mechanisms that the sender can use to wait for a reply, blocking or polling. Both mechanisms require the sender to set a reply timeout. A reply timeout is the maximum time the platform will wait for a reply to an event sent to its destination. If a timeout occurs, the reply is lost.

The blocking reply mechanism requires the sender to set a reply timeout, and then call a wait method which will return the reply or throw a timeout exception if no reply has been received within the timeout interval:

 IpNetworkEvent e = new IpNetworkEvent(type, destId, payload);
 e.setReplyTimeout(10000); // 10 second timeout
 e.send();
 try {
   // block waiting for reply or timeout
   IpNetworkEvent reply = e.waitForReply();
   // We got a reply!
   ...
 } catch (IpTimeoutException ex) {
    // no reply was received within 10 seconds
 } 

The polling method involves continuously checking whether a reply has been received:

 IpNetworkEvent e = new IpNetworkEvent(type, destId, payload);
 e.setReplyTimeout(10000); // 10 second timeout
 e.send();
 IpNetworkEvent reply;
 while (e.timeUntilReplyTimeout() > 0) {
   reply = e.getReplyEvent();
   if (reply != null) {
     // We got a reply!
     break;
   } else {
     // do something else for a while
     ...
   }
 }
 if (reply == null) {
   // no reply was received within 10 seconds
   ...
 } 

In order for the reply mechanims to work, the object sending the reply must use the createReply method to create an event to be sent back to the original sender:

 IpNetworkEvent reply = receivedEvent.createReply(TYPE, payload);
 reply.send();

Apart from sending events to a single destination, events can also be broadcasted to many destinations. The broadcast will sent an event to every process that can be reach from the local process. A process that receives a broadcast event will deliver the event to its application event handler.

Version:

1.0.0 Initial version

Author:

Olov Stahl - olovs@sics.se

Constructor Summary

IpNetworkEvent()
Create a new (empty) network event.

IpNetworkEvent(java.lang.String type, IpIdentifier destId, IpIoStream payload)
Create a new network event of the given type.

Method Summary

void	broadcast() Send the event to every process that can be reached from the local process.
IpNetworkEvent	createReply(java.lang.String type, IpIoStream payload) Create an event which can be used as a reply to the current event.
IpIoStream	getPayload() Get the event's io stream.
IpNetworkEvent	getReplyEvent() Get the reply event.
int	getReplyTimeout() Get the current reply timeout.
IpIdentifier	getSender() Get the identifier of the object sending this event.
void	read(IpInputStream stream) Read the event state from an input stream.
void	send() Send an event to its destination object.
void	setDestination(IpIdentifier destId) Set the event destination.
void	setReplyTimeout(int timeout) Set the reply timeout.
long	timeUntilReplyTimeout() Check how long it will take until the reply timeout will occur.
IpNetworkEvent	waitForReply() Block the current thread until a reply event has been received, or a timeout exception is thrown.
void	write(IpOutputStream stream) Write the event state into an output stream.

Methods inherited from class org.iperg.part.core.IpEvent

getDestination, getType

Methods inherited from class java.lang.Object

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

Constructor Detail

IpNetworkEvent

public IpNetworkEvent(java.lang.String type,
                      IpIdentifier destId,
                      IpIoStream payload)

Create a new network event of the given type. The local process will be set as the event sender.

Parameters:

type - The event type

destId - The identifier of the event destination object. Must not be null unless the event is to be broadcasted.

payload - The event payload, may be null

IpNetworkEvent

public IpNetworkEvent()

Create a new (empty) network event.

Method Detail

getPayload

public IpIoStream getPayload()

Get the event's io stream.

Returns:

The event's io stream or null if the event's contains no strea,

setDestination

public void setDestination(IpIdentifier destId)

Set the event destination.

Overrides:

setDestination in class IpEvent

Parameters:

destId - The identifier of the destination object

createReply

public IpNetworkEvent createReply(java.lang.String type,
                                  IpIoStream payload)

Create an event which can be used as a reply to the current event. Replies can only be created for events that have been received from the network.

Parameters:

type - The reply event type

payload - The reply event payload

Returns:

A reply event

waitForReply

public IpNetworkEvent waitForReply()
                            throws IpTimeoutException

Block the current thread until a reply event has been received, or a timeout exception is thrown. A timeout exception is thrown if the reply has not been received within the timeout interval set using setReplyTimeout, counting from the time when the event was sent.

If timeout interval is zero, a timeout exception is thrown immediately. The same thing happens if the event has not yet been sent.

If reply has already been received, call will immediately return the reply event.

Returns:

The reply event received from the destination object to which the event was sent

Throws:

IpTimeoutException

getReplyEvent

public IpNetworkEvent getReplyEvent()

Get the reply event.

Returns:

Reply event or null if no reply has been received.

timeUntilReplyTimeout

public long timeUntilReplyTimeout()

Check how long it will take until the reply timeout will occur. If -1 is returned, the timeout has already occured.

Returns:

Time in millisecons until reply timeout occurs

setReplyTimeout

public void setReplyTimeout(int timeout)

Set the reply timeout. Should only be done if an reply is expected from the event destination object.

Parameters:

timeout - Time in milliseconds

getReplyTimeout

public int getReplyTimeout()

Get the current reply timeout. By default, reply timeouts are 0.

Returns:

Reply timeout in milliseconds.

getSender

public IpIdentifier getSender()

Get the identifier of the object sending this event.

Returns:

The sender object's identifier

send

public void send()
          throws java.io.IOException

Send an event to its destination object. The event will be delivered to the object's handleEvent method.

Throws:

java.io.IOException - if the send operation failed for some reason

broadcast

public void broadcast()
               throws java.io.IOException

Send the event to every process that can be reached from the local process. This doesn't only include processes that are directly connected to the local process, but a also the process directly connected to those processes, and so on. A process that receives a broadcast event will deliver the event to its application event handler.

Broadcasting ignores the event's destination attribute.

Throws:

java.io.IOException - if the broadcast operation failed for some reason

write

public void write(IpOutputStream stream)
           throws java.io.IOException

Write the event state into an output stream. Sub-classes of IpNetworkEvent must call IpNetworkEvent.write if they add a write method. A class specific write method must therefore look like this:

 public void write(IpOutputStream stream)
     throws IOException
 {
     // write class specific state information
     ..

     // then let IpNetworkEvent write its state
     super.write(stream); 
 } 

Specified by:

write in interface IpSerializable

Overrides:

write in class IpEvent

Parameters:

stream - The output stream into which the event should be written

Throws:

java.io.IOException - if an io exception occured while writing the event to the stream

read

public void read(IpInputStream stream)
          throws java.io.IOException

Read the event state from an input stream. Sub-classes of IpNetworkEvent must call IpNetworkEvent.read if they add a read method. A class specific read method must therefore look like this:

 public void read(IpInputStream stream)
     throws IOException
 {
     // read class specific state information
     ...

     // then let IpNetworkEvent read its state
     super.read(stream); 
 } 

Specified by:

read in interface IpSerializable

Overrides:

read in class IpEvent

Parameters:

stream - The input stream from which the event should be read

Throws:

java.io.IOException - if an io exception occured while reading the event from the stream