Package org.jcsp.net

Class NetChannelLocation

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable
    Direct Known Subclasses:
    CNSNetChannelLocation, NetConnectionLocation, NotNameableNetChannelLocation

    public class NetChannelLocation
    extends java.lang.Object
    implements java.lang.Cloneable, java.io.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.

    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private NodeAddressID channelAddress
      The NodeAddressID on which the channel's Node is listening.
      private java.lang.String channelLabel
      The label, if any, assigned to a channel's VCN.
      private NodeID channelNode
      The NodeID of the channel's Node.
      private long vcn
      The VCN of a channel, if known.
    • 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, java.lang.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).
      (package private) NetChannelLocation​(NodeID channelNode, long vcn)
      Package private constructor which takes the NodeID of the Node hosting the networked ChannelInput object and a long holding the VCN of the channel.
        NetChannelLocation​(NodeID channelNode, java.lang.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

      All Methods Instance Methods Concrete Methods 
      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.
      java.lang.Object clone()
      Returns a clone of the instance of this class.
      boolean equals​(java.lang.Object o)
      Returns whether this object is equal to another object.
      NodeAddressID getChannelAddress()
      Public accessor for the channel's address, if held.
      java.lang.String getChannelLabel()
      Public accessor for the channel label property.
      NodeID getChannelNodeID()
      Public accessor for the channel label property.
      java.lang.String getStringID()
      Returns a String ID for this NetChannelLocation object.
      (package private) long getVCN()
      Package level accessor for the channel's VCN if held.
      int hashCode()
      Return a hashcode for this object.
      boolean refresh()
      This method requests that the instance of this class refresh its information.
      protected void refreshFrom​(NetChannelLocation other)
      This method refreshes the fields in the instance of this object to equal the fields in the supplied object.
      (package private) void setLocationDetails​(NodeID nodeID, long vcn)
      Package level mutator for the channel's actual location details.
      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • channelLabel

        private java.lang.String channelLabel
        The label, if any, assigned to a channel's VCN.
      • vcn

        private long vcn
        The VCN of a channel, if known.
      • channelNode

        private NodeID channelNode
        The NodeID of the channel's Node. This should be null if channelAddress is not null.
      • channelAddress

        private NodeAddressID channelAddress
        The NodeAddressID on which the channel's Node is listening. This should be null if channelNode is not null.
    • Constructor Detail

      • NetChannelLocation

        public NetChannelLocation​(NodeID channelNode,
                                  java.lang.String channelLabel)
                           throws java.lang.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:
        java.lang.IllegalArgumentException
      • NetChannelLocation

        public NetChannelLocation​(NodeAddressID channelAddress,
                                  java.lang.String channelLabel)
                           throws java.lang.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:
        java.lang.IllegalArgumentException
      • NetChannelLocation

        NetChannelLocation​(NodeID channelNode,
                           long vcn)
                    throws java.lang.IllegalArgumentException

        Package private constructor which takes the NodeID of the Node hosting the networked ChannelInput object and a long holding the VCN of the channel.

        Users of the jcsp.net package cannot use this constructor. It is intended to be used by the infrastructure for creating an instance of the class in order to return it to the user.

        When used like this, the class may seem to be the same as the ChannelID class, however, this class is publicly visible outside the jcsp.net.

        Parameters:
        channelNode - the NodeID of the Node hosting the read end of the channel.
        vcn - the VCN of the channel
        Throws:
        java.lang.IllegalArgumentException
      • NetChannelLocation

        protected NetChannelLocation​(NetChannelLocation other)
                              throws java.lang.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:
        java.lang.IllegalArgumentException - iff the parameter is null.
    • Method Detail

      • getChannelLabel

        public final java.lang.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 java.lang.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 java.lang.Object clone()
                               throws java.lang.CloneNotSupportedException

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

        Overrides:
        clone in class java.lang.Object
        Returns:
        a clone of the instance of this class.
        Throws:
        java.lang.CloneNotSupportedException
      • equals

        public final boolean equals​(java.lang.Object o)

        Returns whether this object is equal to another object.

        Overrides:
        equals in class java.lang.Object
        Returns:
        true iff the supplied object is equal.
      • hashCode

        public final int hashCode()
        Return a hashcode for this object.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the int hash code.
      • refreshFrom

        protected final void refreshFrom​(NetChannelLocation other)
                                  throws java.lang.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:
        java.lang.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.
      • getVCN

        long getVCN()

        Package level accessor for the channel's VCN if held. Users of jcsp.net should not have any control over VCN allocation so this accessor is not publicly accessible.

        Returns:
        the VCN value held for the channel.
      • setLocationDetails

        void setLocationDetails​(NodeID nodeID,
                                long vcn)

        Package level mutator for the channel's actual location details. The details can only be set if the current NodeID held is null.

        Parameters:
        nodeID - the NodeID of the channel.
        vcn - the VCN of the channel.