Package org.jcsp.net

# Class NetChannelLocation

java.lang.Object
org.jcsp.net.NetChannelLocation

All Implemented Interfaces:
  `Serializable`, `Cloneable`

Direct Known Subclasses:
  `CNSNetChannelLocation`

public class NetChannelLocation extends Object implements Cloneable, Serializable

Instances of this class hold location information for a networked `ChannelInput` object. Instances of the class hold sufficient information for a networked `ChannelOutput` object to establish a connection to the networked `ChannelInput` object.

Instances of this class may either be constructed by the `jcsp.net` user or by the networking infrastructure.

Author:
  Quickstone Technologies Limited
See Also:
  - Serialized Form

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`NetChannelLocation(NetChannelLocation other)`
This is a protected constructor which takes another `NetChannelLocation` object and "clones" it into this one.
``
`NetChannelLocation(NodeAddressID channelAddress, String channelLabel)`
Constructor which takes a `NodeAddressID` on which the channel's Node is listening and the label assigned to the channel's Virtual Channel Number (VCN).
``
`NetChannelLocation(NodeID channelNode, String channelLabel)`
Constructor which takes the `NodeID` of the Node hosting the networked `ChannelInput` object and the label assigned to the channel's Virtual Channel Number (VCN).

## Method Summary

Modifier and Type
Method
Description
`protected boolean`
`checkEqual(NetChannelLocation other)`
This method is used by the `equals(Object)` method to determine whether another object is equal to the one on which it is invoked.
`Object`
`clone()`
Returns a clone of the instance of this class.
`final boolean`
`equals(Object o)`
Returns whether this object is equal to another object.
`final NodeAddressID`
`getChannelAddress()`
Public accessor for the channel's address, if held.
`final String`
`getChannelLabel()`
Public accessor for the channel label property.
`final NodeID`
`getChannelNodeID()`
Public accessor for the channel label property.
`final String`
`getStringID()`
Returns a String ID for this `NetChannelLocation` object.
`final int`
`hashCode()`
Return a hashcode for this object.
`boolean`
`refresh()`
This method requests that the instance of this class refresh its information.
`protected final void`
`refreshFrom(NetChannelLocation other)`
This method refreshes the fields in the instance of this object to equal the fields in the supplied object.

### Methods inherited from class java.lang.Object

`finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### NetChannelLocation

public NetChannelLocation(NodeID channelNode, String channelLabel) throws IllegalArgumentException

Constructor which takes the `NodeID` of the Node hosting the networked `ChannelInput` object and the label assigned to the channel's Virtual Channel Number (VCN).

Parameters:
  `channelNode` - the `NodeID` of the Node hosting the read end of the channel.
  `channelLabel` - the label assigned to the channel's Virtual Channel Number (VCN).
Throws:
  `IllegalArgumentException`

### NetChannelLocation

public NetChannelLocation(NodeAddressID channelAddress, String channelLabel) throws IllegalArgumentException

Constructor which takes a `NodeAddressID` on which the channel's Node is listening and the label assigned to the channel's Virtual Channel Number (VCN).

This constructor is intended to be used by code that wishes to connect to a `ChannelInput` running on a Node to which a `Link` has not yet been established. An address of the Node must be known by some means. For example, with a JCSP network running over TCP/IP, a program may prompt the user for an IP address to which to connect.

Parameters:
  `channelAddress` - a `NodeAddressID` on which the channel's Node is listening.
  `channelLabel` - the label assigned to the channel's VCN.
Throws:
  `IllegalArgumentException`

### NetChannelLocation

protected NetChannelLocation(NetChannelLocation other) throws IllegalArgumentException

This is a protected constructor which takes another `NetChannelLocation` object and "clones" it into this one. This allows sub-classes to adopt the field values of an instance of this class by passing a reference of it to this constructor.

Parameters:
  `other` - Another `NetChannelLocation` to "clone" into this one.
Throws:
  `IllegalArgumentException` - iff the parameter is `null`.

## Method Details

### getChannelLabel

public final String getChannelLabel()

Public accessor for the channel label property.

Returns:
  the channel label held by the instance of this object, if exists or else `null`.

### getChannelAddress

public final NodeAddressID getChannelAddress()

Public accessor for the channel's address, if held.

Returns:
  a `NodeAddressID` on which the channel's Node is listening. If the channel's Node's `NodeID` is known, then this will return `null`.

### getChannelNodeID

public final NodeID getChannelNodeID()

Public accessor for the channel label property.

Returns:
  the `NodeID` of the channel's Node, if known, else `null`.

### refresh

public boolean refresh()

This method requests that the instance of this class refresh its information. This class does not actually do anything when this method is called, however, instances of subclasses may take the opportunity to refresh their data.

An example, of when this might be useful is if this class were extended as part of a name service that resolves names to `NetChannelLocation` objects. If a user of an instance of this extended version wanted to check that the data were still up to date, it would call this method which would then check the information with a name service.

Returns:
  `true` if any information has changed, otherwise `false`.

### getStringID

public final String getStringID()

Returns a String ID for this `NetChannelLocation` object.

This method does not need to be used by normal JCSP users.

Returns:
  the id.

### clone

public Object clone() throws CloneNotSupportedException

Returns a clone of the instance of this class. All mutable fields are also cloned.

Overrides:
  `clone` in class `Object`
Returns:
  a clone of the instance of this class.
Throws:
  `CloneNotSupportedException`

### equals

public final boolean equals(Object o)

Returns whether this object is equal to another object.

Overrides:
  `equals` in class `Object`
Returns:
  `true` iff the supplied object is equal.

### hashCode

public final int hashCode()
Return a hashcode for this object.

Overrides:
  `hashCode` in class `Object`
Returns:
  the `int` hash code.

### refreshFrom

protected final void refreshFrom(NetChannelLocation other) throws IllegalArgumentException

This method refreshes the fields in the instance of this object to equal the fields in the supplied object. Only members of the `NetChannelLocation` class are copied and not members added by sub-classes.

Parameters:
  `other` - Another `NetChannelLocation` to "clone" into this one.
Throws:
  `IllegalArgumentException` - iff the parameter is `null`.

### checkEqual

protected boolean checkEqual(NetChannelLocation other)

This method is used by the `equals(Object)` method to determine whether another object is equal to the one on which it is invoked.

This should be used by sub-classes as they cannot override the equals method.

Parameters:
  `other` - the `NetChannelLocation` object to compare with this object.
Returns:
  `true` if the other object is equal to this one.