java.lang.isolate
Class LinkMessage

java.lang.Object
  |
  +--java.lang.isolate.LinkMessage

public class LinkMessage

extends Object

A LinkMessage wraps the various types that can be sent through a Link.

LinkMessages are immutable and may be sent on multiple links simultaneously or serially. Many of the various objects that can be referenced from a LinkMessage are not immutable, and changes to those objects which are visible before the message is sent will be reflected in the message which is transferred across the link.

A LinkMessageVisitor can be used to dynamically determine the contents of a LinkMessage.

The null reference cannot be sent via LinkMessage.

Since:

1.5

Method Summary

void	acceptVisitor(java.lang.isolate.LinkMessageVisitor visitor) Gets the content of this message via a message visitor.
byte[]	getByteArray() gets a reference to the byte array wrapped in this message.
ByteBuffer	getByteBuffer() Gets a reference to the ByteBuffer object wrapped in this message.
java.lang.isolate.IsolateEvent	getEvent() gets a reference to the IsolateEvent wrapped in this message.
java.lang.isolate.Isolate	getIsolate() Gets the Isolate object wrapped in this message.
java.lang.isolate.Link	getLink() Gets the Link object wrapped in this message.
Pipe.SinkChannel	getPipeSink() gets a reference to the Pipe.SinkChannel wrapped in this message.
Pipe.SourceChannel	getPipeSource() gets a reference to the Pipe.SourceChannel wrapped in this message.
Object	getSerializable() gets a reference to the object wrapped in this message.
ServerSocket	getServerSocket() gets a reference to the ServerSocket wrapped in this message.
Socket	getSocket() gets a reference to the Socket wrapped in this message.
String	getString() gets a reference to the String wrapped in this message.
static java.lang.isolate.LinkMessage	newByteArrayMessage(byte[] b) Creates a LinkMessage for copying the given byte array across a Link.
static java.lang.isolate.LinkMessage	newByteBufferMessage(ByteBuffer b) Creates a LinkMessage for copying the given ByteBuffer across a Link.
static java.lang.isolate.LinkMessage	newEventMessage(java.lang.isolate.IsolateEvent ie) Creates a LinkMessage for sending the given IsolateEvent across a Link.
static java.lang.isolate.LinkMessage	newIsolateMessage(java.lang.isolate.Isolate i) Creates a LinkMessage for sending the given IsolateLink.
static java.lang.isolate.LinkMessage	newLinkMessage(java.lang.isolate.Link l) Creates a LinkMessage for sending the given link handle on a Link.
static java.lang.isolate.LinkMessage	newPipeSinkMessage(Pipe.SinkChannel ps) Creates a LinkMessage for sending the given Pipe.SinkChannel across a Link.
static java.lang.isolate.LinkMessage	newPipeSinkMessage(Pipe.SourceChannel ps) Creates a LinkMessage for sending the given Pipe.SourceChannel across a Link.
static java.lang.isolate.LinkMessage	newSerializableMessage(Object o) Creates a LinkMessage for sending the given object across a Link.
static java.lang.isolate.LinkMessage	newServerSocketMessage(ServerSocket s) Creates a LinkMessage for sending the given ServerSocket across a Link.
static java.lang.isolate.LinkMessage	newSocketMessage(Socket s) Creates a LinkMessage for sending the given Socket across a Link.
static java.lang.isolate.LinkMessage	newStringMessage(String s) Creates a LinkMessage for sending the given String across a Link.

Methods inherited from class java.lang.Object

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

Method Detail

newIsolateMessage

public static java.lang.isolate.LinkMessage newIsolateMessage(java.lang.isolate.Isolate i)

Creates a LinkMessage for sending the given IsolateLink. If the given isolate has not been started a NullPointerException will be thrown.

Parameters:

i - the Isolate to wrap in a LinkMessage

Returns:

a new LinkMessage which wraps the given Isolate object

Throws:

NullPointerException - if i is null

IllegalStateException - if the given isolate has not been started

See Also:

Link.send(LinkMessage)

newLinkMessage

public static java.lang.isolate.LinkMessage newLinkMessage(java.lang.isolate.Link l)

Creates a LinkMessage for sending the given link handle on a Link. Note that if the current blocking mode of the given Link is ignored, the received Link will always be in blocking mode.

Parameters:

l - the Link to wrap in a LinkMessage

Returns:

a new LinkMessage which wraps the given link

Throws:

NullPointerException - if l is null

See Also:

Link.send(LinkMessage)

newByteBufferMessage

public static java.lang.isolate.LinkMessage newByteBufferMessage(ByteBuffer b)

Creates a LinkMessage for copying the given ByteBuffer across a Link.

The entire capacity of the ByteBuffer will be copied into the receiver isolate. The receiver's ByteBuffer will have the same Buffer.capacity(), Buffer.mark(), Buffer.limit(), and Buffer.position() as the given ByteBuffer.

If the contents of the given ByteBuffer (or its underlying array) are changed after the LinkMessage is created, such changes will be reflected in the ByteBuffer sent to a receiver. However, once a ByteBuffer has been sent to a receiver, changes in the source buffer will not be reflected in the receiver's buffer. (Basically, the ByteBuffer is copied during the send/receive rendezvous on a Link, no sooner, no later.)

Parameters:

b - the ByteBuffer to wrap in a LinkMessage

Returns:

a new LinkMessage which contains a reference to the given ByteBuffer

Throws:

NullPointerException - if b is null

See Also:

Link.send(LinkMessage)

newByteArrayMessage

public static java.lang.isolate.LinkMessage newByteArrayMessage(byte[] b)

Creates a LinkMessage for copying the given byte array across a Link.

If the contents of the given byte array are changed after the LinkMessage is created, such changes will be reflected in the byte array given to a receiver. However, once a byte array has been sent to a receiver, changes in the source array will not be reflected in the receiver's array. (Basically, the byte array is copied during the send/receive rendezvous on a Link, no sooner, no later.)

Parameters:

b - the byte array to wrap in a LinkMessage

Returns:

a new LinkMessage which contains a reference to the given byte array.

Throws:

NullPointerException - if b is null

See Also:

Link.send(LinkMessage)

newStringMessage

public static java.lang.isolate.LinkMessage newStringMessage(String s)

Creates a LinkMessage for sending the given String across a Link.

Parameters:

s - the byte array to wrap in a LinkMessage

Returns:

a new LinkMessage which contains a reference to the given String

Throws:

NullPointerException - if s is null

See Also:

Link.send(LinkMessage)

newSocketMessage

public static java.lang.isolate.LinkMessage newSocketMessage(Socket s)

Creates a LinkMessage for sending the given Socket across a Link.

Only socket objects created by the platform default socket implementation are supported by LinkMessage. Passing a non-supported socket type to this method will result in a NullPointerException.

Note that DatagramSocket is not supported. A workaround is to pass the necessary information for creating such a socket and have the remote isolate create a new DatagramSocket with that information.

Parameters:

s - the Socket to wrap in a LinkMessage

Returns:

a new LinkMessage which contains a reference to the given Socket

Throws:

NullPointerException - if s is null

IllegalArgumentException - if s is not of a specific type supported by the implementation

See Also:

Link.send(LinkMessage)

newServerSocketMessage

public static java.lang.isolate.LinkMessage newServerSocketMessage(ServerSocket s)

Creates a LinkMessage for sending the given ServerSocket across a Link.

Only server socket objects created by the platform default socket implementation are supported by LinkMessage. Passing a non-supported socket type to this method will result in a NullPointerException.

Parameters:

s - the ServerSocket to wrap in a LinkMessage

Returns:

a new LinkMessage which contains a reference to the given ServerSocket

Throws:

NullPointerException - if s is null

IllegalArgumentException - if s is not of a specific type supported by the implementation

See Also:

Link.send(LinkMessage)

newSerializableMessage

public static java.lang.isolate.LinkMessage newSerializableMessage(Object o)

Creates a LinkMessage for sending the given object across a Link.

The object will be sent as if serialized as a result of (but possibly following) use of send but as if deserialized during the call to getSerializable() in the receiver (not during the receive). The point at which visible side effects of serialization happen is unspecified but guaranteed to occur prior to return from getSerializable() as long as the message was received on a link. If the message was not received on a link, no serialization, deserialization, or side effects will happen.

If the serialization or deserialization do not work correctly (for example, mis-matched class information), the link will not be corrupted.

Parameters:

o - the Serializable object to wrap in a LinkMessage

Returns:

a new LinkMessage which contains a reference to the given Serializable

Throws:

NullPointerException - if o is null

See Also:

Link.send(LinkMessage), getSerializable()

newPipeSinkMessage

public static java.lang.isolate.LinkMessage newPipeSinkMessage(Pipe.SinkChannel ps)

Creates a LinkMessage for sending the given Pipe.SinkChannel across a Link.

Parameters:

ps - the Pipe.SinkChannel to wrap in a LinkMessage

Returns:

a new LinkMessage which contains a reference to the given Pipe.SinkChannel

Throws:

NullPointerException - if ps is null

See Also:

Link.send(LinkMessage)

newPipeSinkMessage

public static java.lang.isolate.LinkMessage newPipeSinkMessage(Pipe.SourceChannel ps)

Creates a LinkMessage for sending the given Pipe.SourceChannel across a Link.

Parameters:

ps - the Pipe.SourceChannel to wrap in a LinkMessage

Returns:

a new LinkMessage which contains a reference to the given Pipe.SourceChannel

Throws:

NullPointerException - if ps is null

See Also:

Link.send(LinkMessage)

newEventMessage

public static java.lang.isolate.LinkMessage newEventMessage(java.lang.isolate.IsolateEvent ie)

Creates a LinkMessage for sending the given IsolateEvent across a Link.

Parameters:

ie - the IsolateEvent to wrap in a LinkMessage

Returns:

a new LinkMessage which contains a reference to the given IsolateEvent

Throws:

NullPointerException - if ie is null

See Also:

Link.send(LinkMessage)

getIsolate

public java.lang.isolate.Isolate getIsolate()

Gets the Isolate object wrapped in this message.

Returns:

the Isolate object wrapped in this message.

Throws:

IllegalStateException - if this message does not contain an Isolate.

getLink

public java.lang.isolate.Link getLink()

Gets the Link object wrapped in this message.

Returns:

the Link object wrapped in this message.

Throws:

IllegalStateException - if this message does not contain a Link.

getByteBuffer

public ByteBuffer getByteBuffer()

Gets a reference to the ByteBuffer object wrapped in this message.

Returns:

a reference to the ByteBuffer object wrapped in this message.

Throws:

IllegalStateException - if this message does not contain a ByteBuffer.

getByteArray

public byte[] getByteArray()

gets a reference to the byte array wrapped in this message.

Returns:

a reference to the byte array wrapped in this message.

Throws:

IllegalStateException - if this message does not contain a byte array.

getString

public String getString()

gets a reference to the String wrapped in this message.

Returns:

a reference to the String wrapped in this message.

Throws:

IllegalStateException - if this message does not contain a String.

getSocket

public Socket getSocket()

gets a reference to the Socket wrapped in this message.

Returns:

a reference to the Socket wrapped in this message.

Throws:

IllegalStateException - if this message does not contain a Socket.

getServerSocket

public ServerSocket getServerSocket()

gets a reference to the ServerSocket wrapped in this message.

Returns:

a reference to the ServerSocket wrapped in this message.

Throws:

IllegalStateException - if this message does not contain a ServerSocket.

getSerializable

public Object getSerializable()
                       throws LinkSerializationException

gets a reference to the object wrapped in this message.

If this message was received from a link, and this is the first invocation, the returned object will be created as if by an invocation of ObjectInputStream.readObject on the serialized representation contained in this message when it was received. Subsequent invocations of this method will return the same object returned by the first invocation. Consequently, deserialization (including any possible side effects) happens no more than once. Note that if getSerializable is never invoked during the lifetime of this message, neither deserialization nor its possible side effects will occur.

If this message was not received from a link, ie. if it was created by the current isolate, the object returned will be the same as the object supplied as the argument to the newSerializableMessage factory method that created it. In this case, an invocation of this method will not result in any serialization or deserialization or their side effects.

If there are errors deserializing an object, subsequent attempts to invoke this method will result in an IllegalStateException.

Returns:

the object wrapped in this message

Throws:

IllegalStateException - if this message does not contain a serialized object

LinkSerializationException - if a Serialization error occurred

See Also:

newSerializableMessage(java.lang.Object)

getPipeSink

public Pipe.SinkChannel getPipeSink()

gets a reference to the Pipe.SinkChannel wrapped in this message.

Returns:

a reference to the Pipe.SinkChannel wrapped in this message.

Throws:

IllegalStateException - if this message does not contain a Pipe.SinkChannel.

getPipeSource

public Pipe.SourceChannel getPipeSource()

gets a reference to the Pipe.SourceChannel wrapped in this message.

Returns:

a reference to the Pipe.SourceChannel wrapped in this message.

Throws:

IllegalStateException - if this message does not contain a Pipe.SourceChannel.

getEvent

public java.lang.isolate.IsolateEvent getEvent()

gets a reference to the IsolateEvent wrapped in this message.

Returns:

a reference to the IsolateEvent wrapped in this message.

Throws:

IllegalStateException - if this message does not contain an IsolateEvent.

acceptVisitor

public void acceptVisitor(java.lang.isolate.LinkMessageVisitor visitor)
                   throws LinkSerializationException

Gets the content of this message via a message visitor. Depending on the content type, the appropriate receiver method will be called in the given receiver. This is a convenience method for processing or dispatching link messages with unknown content.

Parameters:

visitor - The message visitor on which to invoke the appropriate method

Throws:

NullPointerException - if r is null

IllegalStateException - if the message receiver is unable to process the content of this message

LinkSerializationException - if a Serialization error occurred while deserializing a serializable.