Package com.tccc.kos.commons.core.service.handle

Class Handle

java.lang.Object
com.tccc.kos.commons.core.service.handle.Handle
public class Handle extends Object
Building block for allocating a handle to an object. A handle is used to provide an object with a unique and deterministic path, similar to a filesystem path. This path can be used to look up the object using HandleService and allows the bean to be referenced in endpoints using its path. The path can also be used as a storage key to store information about the bean.

Handles are a useful construct for creating hierarchical and durable identifiers for objects but require some work on behalf of the caller to connect the handles into a graph that can then be resolved into paths. This process is normally handled using the HandleAware interface rather than working with handle objects directly. While handles form a graph of objects, all handle references are weak and will not impact garbage collection.

Handles are chained together into a path, with each handle providing a name within the path. When a child Handle is chained to a parent, it can be chained using a prefix which becomes part of the path. For example, consider a Handle for a pump with the name of "water". It is then chained to a parent Handle with a name of "board". This results in a path of: 

    board.water
However, if the board also contains cutoff switch for water, it too may have the name "water", resulting in two objects with the same path. Since the pump and cutoff switch are different types of objects, a prefix is used when chaining the handles. In general, the prefix represents the type of objects whereas the name represents the name of the object. In our example a prefix of "pump" would be used for pumps and "cutoff" would be used for cutoff switches. This would result in two distinct paths: 
    board.pump:water
    board.cutoff:water
Path segments are separated by periods, and each path segment is made up of an optional prefix and name, separated by a colon.

Handle paths are considered opaque. While they are designed to be human readable, they should not be parsed or synthentically generated. The fact that they are human readable aids in debugging and logging.

As handle paths tend to be used as persistence keys and other identifiers, care should be taken when defining paths as changing them later may cause migration issues.

Since:
1.0
Version:
2022-08-30

  • Constructor Summary

    Constructors
    Constructor
    Description
    Handle(Object bean)
    Constructs a new handle with the name derived from the bean class.
    Handle(String name, Object bean)
    Constructs a new handle node with the specified name and bean.
    Handle(String name, Object bean, String prefix, Handle parent)
    Constructs a new handle node with the specified name and bean, and attaches is to the specified parent with the supplied prefix.
    Handle(String name, Object bean, String prefix, HandleAware parent)
    Constructs a new handle node with the specified name and bean, and attaches is to the specified parent with the supplied prefix.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(Handle child)
    Adds the specified handle as a child of this handle without a name prefix.
    void
    add(String prefix, Handle child)
    Adds the specified handle as a child of this handle using the specified name prefix.
    void
    add(String prefix, HandleAware child)
    Adds the specified HandleAware as a child of this handle using the specified name prefix.
    void
    broadcast(String topic, Class<?> view)
    Causes the associated bean to be broadcast from HandleService with a topic of: /kos/handle/<topic>/<path> .
    Object
    getBean()
    Get the associated bean.
    String
    getName()
    Gets the name of the node.
    String
    getPath()
    Returns the path of this handle.
    boolean
    hasParent()
    Return true if the handle already has a parent.
    void
    setName(String name)
    Sets the name.
    String
    toString()
    Returns the string representation of this object.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Handle

      public Handle(Object bean)
      Constructs a new handle with the name derived from the bean class.
      Parameters:
      bean - the bean associated with the handle

    • Handle

      public Handle(String name, Object bean)
      Constructs a new handle node with the specified name and bean.
      Parameters:
      name - the name of the node, used to construct the handle
      bean - the bean associated with the handle

    • Handle

      public Handle(String name, Object bean, String prefix, Handle parent)
      Constructs a new handle node with the specified name and bean, and attaches is to the specified parent with the supplied prefix.
      Parameters:
      name - the name of the node, used to construct the handle
      bean - the bean associated with the handle
      prefix - prefix for the bean relative to parent
      parent - the parent handle

    • Handle

      public Handle(String name, Object bean, String prefix, HandleAware parent)
      Constructs a new handle node with the specified name and bean, and attaches is to the specified parent with the supplied prefix.
      Parameters:
      name - the name of the node, used to construct the handle
      bean - the bean associated with the handle
      prefix - prefix for the bean relative to parent
      parent - the parent handle

  • Method Details

    • getBean

      public Object getBean()
      Get the associated bean.

    • getName

      public String getName()
      Gets the name of the node. This is just a component of the overall handle.
      Returns:
      the name of the node

    • setName

      public void setName(String name)
      Sets the name. This is only used if the name wasn't really known when the constructor was called and should be set before paths are generated.
      Parameters:
      name - the name of the handle

    • getPath

      public String getPath()
      Returns the path of this handle. This is an opaque string that uniquely identifies this handle in a graph of beans.
      Returns:
      the path to the handle

    • hasParent

      public boolean hasParent()
      Return true if the handle already has a parent.

    • add

      public void add(Handle child)
      Adds the specified handle as a child of this handle without a name prefix.
      Parameters:
      child - the child handle

    • add

      public void add(String prefix, Handle child)
      Adds the specified handle as a child of this handle using the specified name prefix.
      Parameters:
      prefix - the name prefix for the resulting path
      child - the child handle

    • add

      public void add(String prefix, HandleAware child)
      Adds the specified HandleAware as a child of this handle using the specified name prefix.
      Parameters:
      prefix - the name prefix for the resulting path
      child - the child handle

    • broadcast

      public void broadcast(String topic, Class<?> view)
      Causes the associated bean to be broadcast from HandleService with a topic of: /kos/handle/<topic>/<path> . This provides a simple way of sending handle related beans without needing access to the message broker or defining new root topics. This is simply a convenience method.
      Parameters:
      topic - the topic fragment to add to the final topic
      view - the view used to serialize the object to json

    • toString

      public String toString()
      Returns the string representation of this object.
      Overrides:
      toString in class Object
      Returns:
      string representation of this object