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.