org.eclipse.ecf.provider.datashare.nio
Class NIOChannel

java.lang.Object
  extended by org.eclipse.ecf.provider.datashare.nio.NIOChannel
All Implemented Interfaces:
org.eclipse.core.runtime.IAdaptable, IIdentifiable, IAbstractChannel, IChannel

public abstract class NIOChannel
extends java.lang.Object
implements IChannel

An abstract implementation of IChannel that uses Java 1.4 NIO APIs for sending and retrieving data.

This channel will inherently spawn multiple socket connections as messages are sent to different remote clients via sendMessage(ID, byte[]). Please note that the current implementation does not handle repeated invocations to that method well. Please refer to its javadoc for further information.

Subclasses must implement the following:

Note: This class/interface is part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.


Constructor Summary
NIOChannel(NIODatashareContainer datashareContainer, ID containerId, ID id, IChannelListener listener)
          Instantiates a new channel for sending and receiving messages in a non-blocking manner via sockets.
 
Method Summary
 void dispose()
          Disposes of this channel.
 java.lang.Object getAdapter(java.lang.Class adapter)
           
protected  int getBackLog()
          Retrieves the listen backlog length of this channel's server socket.
protected  java.net.SocketAddress getBindAddress()
          Returns the address that this channel's server socket should bind to.
 ID getID()
          Return the ID for this 'identifiable' object.
 IChannelListener getListener()
          Get IChannelListener instance for this IAbstractChannel
protected  int getLocalPort()
          Returns the port that is currently open for incoming socket connections.
protected abstract  void log(org.eclipse.core.runtime.IStatus status)
           
 void sendMessage(byte[] message)
          Send message to remote instances of this channel
 void sendMessage(ID receiver, byte[] message)
          Sends a message to a remote instance of this channel of the target peer.
protected abstract  void sendRequest(ID receiver)
          Sends a request to the receiver to notify them that a socket is open and waiting for incoming connections to establish a channel connection.
 IChannelListener setListener(IChannelListener listener)
          Set listener to new IChannelListener instance
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

NIOChannel

public NIOChannel(NIODatashareContainer datashareContainer,
                  ID containerId,
                  ID id,
                  IChannelListener listener)
           throws ECFException
Instantiates a new channel for sending and receiving messages in a non-blocking manner via sockets.

Parameters:
datashareContainer - the source NIODatashareContainer that created this channel, cannot be null
containerId - the id of the originating owner container, this should not be the id of the datashare container that created this channel but the parent container of the datashare container, may not be null
id - the id of this channel, may not be null
listener - the channel listener for this channel, may be null if no notification is required
Throws:
ECFException - if an error occurred while creating this channel
Method Detail

log

protected abstract void log(org.eclipse.core.runtime.IStatus status)

getBindAddress

protected java.net.SocketAddress getBindAddress()
Returns the address that this channel's server socket should bind to. If null, a default port and valid local address will be used.

Returns:
this channel's server socket's bind address, may be null if a default should be used

getBackLog

protected int getBackLog()
Retrieves the listen backlog length of this channel's server socket. If the value is less than or equal to zero, the default length is used.

Returns:
this channel's server socket's listen backlog length

getLocalPort

protected final int getLocalPort()
Returns the port that is currently open for incoming socket connections.

Returns:
the open port for socket connections
See Also:
sendRequest(ID), NIODatashareContainer.enqueue(SocketAddress)

sendRequest

protected abstract void sendRequest(ID receiver)
                             throws ECFException
Sends a request to the receiver to notify them that a socket is open and waiting for incoming connections to establish a channel connection. It is up to the client to decide how this request should be sent as the communication channel between one client and another is entirely dependent on the underlying provider's networking protocol.

This method will be invoked when a socket corresponding to the receiver's ID cannot be found.

Parameters:
receiver - the receiver to contact, will not be null
Throws:
ECFException - if an error occurred while attempting to send the request
See Also:
getLocalPort(), NIODatashareContainer.enqueue(SocketAddress)

sendMessage

public void sendMessage(byte[] message)
                 throws ECFException
Description copied from interface: IChannel
Send message to remote instances of this channel

Specified by:
sendMessage in interface IChannel
Parameters:
message - the byte [] message to send. Must not be null.
Throws:
ECFException - if some problem sending message

sendMessage

public void sendMessage(ID receiver,
                        byte[] message)
                 throws ECFException
Sends a message to a remote instance of this channel of the target peer.

Note: The current implementation does not handle repeated invocations of this method in succession prior to a socket connection established. For optimal performance and some assurance of success, there needs to be a time lag between the first message that is sent and the ones that follow it. This lag should hopefully allow the provider sufficient time for establishing a socket connection with the remote peer. Otherwise, there may be multiple invocations of sendRequest(ID) and clients are responsible for handling this individually.

Specified by:
sendMessage in interface IChannel
Parameters:
receiver - the receiver to send the message to, must not be null
message - the message to send, must not be null
Throws:
ECFException - if some problem sending message

dispose

public void dispose()
Disposes of this channel. Clients may extend to perform additional clean-up but must call super.dispose() before the method returns.

Specified by:
dispose in interface IAbstractChannel

getListener

public IChannelListener getListener()
Description copied from interface: IAbstractChannel
Get IChannelListener instance for this IAbstractChannel

Specified by:
getListener in interface IAbstractChannel
Returns:
IChannelListener for this IAbstractChannel instance. If null, the channel has no listener.

setListener

public IChannelListener setListener(IChannelListener listener)
Description copied from interface: IAbstractChannel
Set listener to new IChannelListener instance

Specified by:
setListener in interface IAbstractChannel
Parameters:
listener - the new listener to set for this channel. If null, then there will be no new listener for this channel.
Returns:
IChannelListener that was previously the listener. If null, then then channel had no previous listener

getAdapter

public java.lang.Object getAdapter(java.lang.Class adapter)
Specified by:
getAdapter in interface org.eclipse.core.runtime.IAdaptable

getID

public ID getID()
Description copied from interface: IIdentifiable
Return the ID for this 'identifiable' object. The returned ID should be unique within its namespace. May return null.

Specified by:
getID in interface IIdentifiable
Returns:
the ID for this identifiable object. May return null.