Class Link
- All Implemented Interfaces:
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
FieldsModifier and TypeFieldDescriptionprotected NodeID
The remote NodeID.protected boolean
True if the subclass must pass the ID of this node to the peer node.protected FilteredAny2OneChannel
The channel used for TX over the link. -
Constructor Summary
ConstructorsConstructorDescriptionLink
(ProtocolID protocolID, boolean client, boolean connected) A constructor that must be called by sub-classes. -
Method Summary
Modifier and TypeMethodDescriptionprotected boolean
connect()
Establishes a connection to the peer node.protected boolean
Allocates the resources necessary for the actual connection.protected void
A protected method for concrete implementations of this class to call when they received a an object from the remote Node.protected void
Deallocates any resources allocated bycreateResources
.final boolean
Compares another object with this object.protected boolean
Sends the ID of this node to the peer process and receives its ID.long
A public accessor for obtaining the ping time between the local Node and this Link's remote Node.protected ProtocolID
A protected accessor for obtaining the identifier of the protocol implementing this Link object.protected boolean[]
getReadSequence
(boolean client) This is used by concreteLink
implementations before calling therunTests
method.protected NodeID
Returns the other computer's ID.protected ChannelOutput
Returns channel to use for transmitting.final int
hashCode()
Returns anint
hash code for thisLink
.final NodeID
This returns theNodeID
of the remote Node to which this link is connected.boolean
A public accessor for enquiring as to whether thisLink
object has performed a ping test.long
ping()
Performs a ping on the link.protected boolean
Reads a boolean link decision as to whether this node can keep or discard the link.protected Object
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
Performs send and receive actions for the link exchanging data with the peer node.protected void
waitForReplies
(int numAcknowledgements) Waits fornumRepliesOutstanding
instances ofLinkLost
to arrive from thetxChannel
.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.
-
Field Details
-
txChannel
The channel used for TX over the link. In the future, this might be made private. It is recommended that implementations use thegetTxChannel()
to obtain the channel. Protocol implementations should NOT alter any of the filters on this channel. -
remoteNodeID
The remote NodeID. The subclass must set this duringexchangeNodeIDs
. -
sendNodeID
protected boolean sendNodeIDTrue if the subclass must pass the ID of this node to the peer node.
-
-
Constructor Details
-
Link
A constructor that must be called by sub-classes.
- Parameters:
protocolID
- AProtocolID
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; otherwiseconnect()
will later be called
-
-
Method Details
-
connect
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
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
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 tocreateResources
.- Throws:
Exception
-
exchangeNodeIDs
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. TheremoteNodeID
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
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
Waits fornumRepliesOutstanding
instances ofLinkLost
to arrive from thetxChannel
. This is called internally from this class'run
method - do not call it directly.- Parameters:
numRepliesOutstanding
-LinkLost
instances to wait for.- Throws:
Exception
-
writeTestObject
Writes a test object to the underlying connection. Called internally during handshaking - do not call it directly. The value written must be delivered byreadTestObject
at the remote node.- Parameters:
obj
- object to be written- Throws:
Exception
-
readTestObject
Reads a test object from the underlying connection. Called internally during handshaking - do not call it directly. It must deliver the value passed towriteTestObject
at the peer node.- Returns:
- the object received.
- Throws:
Exception
-
writeLinkDecision
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 byreadLinkDecision
at the peer node.- Parameters:
use
- decision result- Throws:
Exception
-
readLinkDecision
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 towriteLinkDecision
at the peer node.- Returns:
- decision result
- Throws:
Exception
-
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
A protected accessor for obtaining the identifier of the protocol implementing this Link object.- Returns:
- the
ProtocolID
of the protocol implementing this Link.
-
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
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 therunTests
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
- aboolean
indicating whether thisLink
object is the client side of the link. If this object is the client then the parameter should betrue
.- Returns:
- an array of
boolean
values indicating the sequence of when to read and when to transmit.
-
equals
Compares another object with this object. This implementation returns
true
iff the supplied object is the same instance object as this object. -
hashCode
public final int hashCode()Returns an
int
hash code for thisLink
. The current implementation just uses the instance fromObject
. -
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 thenwaitForReplies()
to acknowledge link termination. -
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 itsNodeID
and then drop the connection.- Returns:
- the remote Node's
NodeID
object.
-