Package org.jcsp.net

Class Link

java.lang.Object
org.jcsp.net.Link
All Implemented Interfaces:
CSProcess
public abstract class Link extends Object implements CSProcess

This class is an abstract class that all JCSP.NET protocol implementations must implement. Concrete implementations of the Link class must provide the mechanism for sending data to remote Nodes and receiving data back. When a concrete implementation of link is initiated by calling the run() method, it must inititate a handshaking procedure and call certain protected methods in this abstract class.

During handshaking, the runTests(ChannelInput, ChannelOutput, boolean) should be called. See the documentation for this method for a full explanation.

When a Link receives an object from over the network it should deliver the object to its destination by calling the deliverReceivedObject(Object) method.

Link implementations obtain objects to send to the remote Node by reading from the protected txChannel object.

Author:
Quickstone Technologies Limited

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected NodeID
    remoteNodeID
    The remote NodeID.
    protected boolean
    sendNodeID
    True if the subclass must pass the ID of this node to the peer node.
    protected FilteredAny2OneChannel
    txChannel
    The channel used for TX over the link.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Link(ProtocolID protocolID, boolean client, boolean connected)
    A constructor that must be called by sub-classes.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected boolean
    connect()
    Establishes a connection to the peer node.
    protected boolean
    createResources()
    Allocates the resources necessary for the actual connection.
    protected void
    deliverReceivedObject(Object obj)
    A protected method for concrete implementations of this class to call when they received a an object from the remote Node.
    protected void
    destroyResources()
    Deallocates any resources allocated by createResources.
    final boolean
    equals(Object o)
    Compares another object with this object.
    protected boolean
    exchangeNodeIDs()
    Sends the ID of this node to the peer process and receives its ID.
    long
    getPingTime()
    A public accessor for obtaining the ping time between the local Node and this Link's remote Node.
    protected ProtocolID
    getProtocolID()
    A protected accessor for obtaining the identifier of the protocol implementing this Link object.
    protected boolean[]
    getReadSequence(boolean client)
    This is used by concrete Link implementations before calling the runTests method.
    protected NodeID
    getRemoteNodeID()
    Returns the other computer's ID.
    protected ChannelOutput
    getTxChannel()
    Returns channel to use for transmitting.
    final int
    hashCode()
    Returns an int hash code for this Link.
    final NodeID
    obtainNodeID()
    This returns the NodeID of the remote Node to which this link is connected.
    boolean
    performedPingTest()
    A public accessor for enquiring as to whether this Link object has performed a ping test.
    long
    ping()
    Performs a ping on the link.
    protected boolean
    readLinkDecision()
    Reads a boolean link decision as to whether this node can keep or discard the link.
    protected Object
    readTestObject()
    Reads a test object from the underlying connection.
    final void
    run()
    Main process for the link, containing generic code that makes calls on the abstract methods that should be implemented by a concrete subclass.
    protected void
    runTxRxLoop()
    Performs send and receive actions for the link exchanging data with the peer node.
    protected void
    waitForReplies(int numAcknowledgements)
    Waits for numRepliesOutstanding instances of LinkLost to arrive from the txChannel.
    protected void
    writeLinkDecision(boolean use)
    Writes a boolean link decision as to whether the other node has the option to keep or discard the link.
    protected void
    writeTestObject(Object obj)
    Writes a test object to the underlying connection.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • txChannel

      protected FilteredAny2OneChannel txChannel
      The channel used for TX over the link. In the future, this might be made private. It is recommended that implementations use the getTxChannel() to obtain the channel. Protocol implementations should NOT alter any of the filters on this channel.

    • remoteNodeID

      protected NodeID remoteNodeID
      The remote NodeID. The subclass must set this during exchangeNodeIDs.

    • sendNodeID

      protected boolean sendNodeID
      True if the subclass must pass the ID of this node to the peer node.

  • Constructor Details

    • Link

      public Link(ProtocolID protocolID, boolean client, boolean connected)

      A constructor that must be called by sub-classes.

      Parameters:
      protocolID - A ProtocolID object for identifying the protocol that is implementing the Link.
      client - Indicates whether this is the client (true) or server (false) end of the connection.
      connected - true if a connection is already established; otherwise connect() will later be called

  • Method Details

    • connect

      protected boolean connect() throws Exception

      Establishes a connection to the peer node. Called when the process is started unless connected was true in the constructor. This is called internally from this class' run method - do not call it.

      Returns:
      true on success, false on failure
      Throws:
      Exception

    • createResources

      protected boolean createResources() throws Exception

      Allocates the resources necessary for the actual connection. Called as the first part of the handshaking process. This is called internally from the class' handshake method - do not call it.

      Returns:
      true on success, false on failure
      Throws:
      Exception

    • destroyResources

      protected void destroyResources() throws Exception

      Deallocates any resources allocated by createResources. Called in the event of an error during handshaking or when the link is dropped. An implementation of this method must cope with being called multiple times without an intervening call to createResources.

      Throws:
      Exception

    • exchangeNodeIDs

      protected boolean exchangeNodeIDs() throws Exception

      Sends the ID of this node to the peer process and receives its ID. It is only necessary to send this node's ID if sendNodeID is true. The remoteNodeID attribute should be set to the ID of the remote node if received. This is called internally during handshaking - do not call it.

      Returns:
      true on success, false on failure.
      Throws:
      Exception

    • runTxRxLoop

      protected void runTxRxLoop() throws Exception
      Performs send and receive actions for the link exchanging data with the peer node. This is called from this class' run method - do not call it directly.
      Throws:
      Exception

    • waitForReplies

      protected void waitForReplies(int numAcknowledgements) throws Exception
      Waits for numRepliesOutstanding instances of LinkLost to arrive from the txChannel. This is called internally from this class' run method - do not call it directly.
      Parameters:
      numRepliesOutstanding - LinkLost instances to wait for.
      Throws:
      Exception

    • writeTestObject

      protected void writeTestObject(Object obj) throws Exception
      Writes a test object to the underlying connection. Called internally during handshaking - do not call it directly. The value written must be delivered by readTestObject at the remote node.
      Parameters:
      obj - object to be written
      Throws:
      Exception

    • readTestObject

      protected Object readTestObject() throws Exception
      Reads a test object from the underlying connection. Called internally during handshaking - do not call it directly. It must deliver the value passed to writeTestObject at the peer node.
      Returns:
      the object received.
      Throws:
      Exception

    • writeLinkDecision

      protected void writeLinkDecision(boolean use) throws Exception
      Writes a boolean link decision as to whether the other node has the option to keep or discard the link. Called internally during handshaking - do not call it directly. The value written must be delivered by readLinkDecision at the peer node.
      Parameters:
      use - decision result
      Throws:
      Exception

    • readLinkDecision

      protected boolean readLinkDecision() throws Exception
      Reads a boolean link decision as to whether this node can keep or discard the link. Called internally during handshaking - do not call it directly. It must return the value passed to writeLinkDecision at the peer node.
      Returns:
      decision result
      Throws:
      Exception

    • getRemoteNodeID

      protected NodeID getRemoteNodeID()
      Returns the other computer's ID. This method is safe to call while the process is running, however it will return null if the other computer has not yet identified itself.
      Returns:
      ID of connected computer.

    • getProtocolID

      protected ProtocolID getProtocolID()
      A protected accessor for obtaining the identifier of the protocol implementing this Link object.
      Returns:
      the ProtocolID of the protocol implementing this Link.

    • getTxChannel

      protected ChannelOutput getTxChannel()
      Returns channel to use for transmitting. This method is safe to call while the process is running. May block for if handshaking is still in progress. When written to, if the object supplied is not Serializable then an IllegalArgumentException Runtime exception.
      Returns:
      Channel you should send data to if you want to transmit on this Connection.

    • deliverReceivedObject

      protected void deliverReceivedObject(Object obj)
      A protected method for concrete implementations of this class to call when they received a an object from the remote Node. This method delivers the message to its destination (a Channel, Connection etc.).
      Parameters:
      obj - the object to deliver.

    • getPingTime

      public long getPingTime()
      A public accessor for obtaining the ping time between the local Node and this Link's remote Node.
      Returns:
      the ping time as a long.

    • ping

      public long ping()
      Performs a ping on the link.
      Returns:
      the ping time in ms.

    • performedPingTest

      public boolean performedPingTest()

      A public accessor for enquiring as to whether this Link object has performed a ping test.

      Returns:
      true iff a ping test has been performed.

    • getReadSequence

      protected boolean[] getReadSequence(boolean client)

      This is used by concrete Link implementations before calling the runTests method. When tests are run, a series of messages are exchanged between both sides of the link. This allows the link to perform its tests using a single thread.

      Parameters:
      client - a boolean indicating whether this Link object is the client side of the link. If this object is the client then the parameter should be true.
      Returns:
      an array of boolean values indicating the sequence of when to read and when to transmit.

    • equals

      public final boolean equals(Object o)

      Compares another object with this object. This implementation returns true iff the supplied object is the same instance object as this object.

      Overrides:
      equals in class Object
      Parameters:
      o - an object to compare with this object.
      Returns:
      true iff the parameter equals this object.

    • hashCode

      public final int hashCode()

      Returns an int hash code for this Link. The current implementation just uses the instance from Object.

      Overrides:
      hashCode in class Object
      Returns:
      an int hash code.

    • run

      public final void run()

      Main process for the link, containing generic code that makes calls on the abstract methods that should be implemented by a concrete subclass. The subclass will be required to connect() if it hasn't done so, perform handshaking, runTxRxLoop() and then waitForReplies() to acknowledge link termination.

      Specified by:
      run in interface CSProcess

    • obtainNodeID

      public final NodeID obtainNodeID()

      This returns the NodeID of the remote Node to which this link is connected. If a connection has not already been established, this method may connect to the remote Node and request its NodeID and then drop the connection.

      Returns:
      the remote Node's NodeID object.