org.licas.call

## Class Handle

- java.lang.Object
- - org.licas.call.Handle

-     public class Handle
      extends java.lang.Object

  This is a helper class for creating the URI descriptions that define each service address running on a licas server. It provides a full description, including the server http address, the service UUID names and an additional method to invoke if required. The description is stored as XML elements, encapsulated inside of a `Handle` element.

  An address of a service uniquely defines it and includes a number of parts. The first part is the URL of the server that is hosting the service. This is stored in a `U` element. Each base service running on a server is then required to have a unique UUID. This is stored in an `S` element. Each service nested inside of any other service then has another UUID (not necessarily unique) that is also stored in an `S` element. If the path is for a method invocation, the final element that stores the method name is an `M` element. A full path description could look something like `<Handle><U>http://123.4.5.6:8888</U><S>service_1</S><S>service_2</S><M>method</M></Handle>`.

  This would call the method 'method' on the service 'service_2' nested, or child of service 'service_1', running on a server at the address http://123.4.5.6:8888. Note also that the `M` element is not typically added by the user, but is automatically added by the system as part of the invocation process. It is declared when the related `MethodInfo` object is created. Because of this, a number of the Handle methods are only used by the automatic calling mechanism and would not need to be used otherwise. A user would typically only use this class to construct a service path, but all methods are available.

  Because there is a pre-defined format, this Handle can be used to construct the address correctly. You need to start by creating the handle, so that the outer `Handle` element is added. You can then add to that structure. For example: 1. You can call `createBaseServiceHandle` with the UUID of a base service and a full path description will be returned, including the server address element. Note this this is just for a base service - any child services then need to be added afterwards. Also, a local server needs to be running. 2. The `handleToString` method will return the path description as a String, which is useful for key indexes, for example.

  You can also construct the full handle path description manually. 1. Firstly call `createNewUrlHandle` with the correct http address. 2. Then call `addToHandle(current_handle, asHandleElement(serviceName))` to add the service names. 3. Finally, calling `addToHandle(current_handle, asMethodElement(methodName))` will add the method name at the end.

  There are a number of other methods listed that the system itself might use and so it is not expected that you would need to use all of these methods yourself.

  Author:
    Kieran Greer

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Handle()` Creates a new instance of Handle

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected static org.licas_xml.abs.Element` | `addExecute(org.licas_xml.abs.Element handle)` Add the specific execute method name to the handle.
    `static org.licas_xml.abs.Element` | `addToHandle(org.licas_xml.abs.Element handle, org.licas_xml.abs.Element newElement)` Return a handle with the new element added at the end.
    `static org.licas_xml.abs.Element` | `addToHandleFirstElement(org.licas_xml.abs.Element handle, org.licas_xml.abs.Element newElement)` Return a handle with the new element added to the handle as the first element of the handle.
    `static org.licas_xml.abs.Element` | `asHandleElement(java.lang.String serviceUuid)` Create an XML element to hold the Service handle part.
    `static org.licas_xml.abs.Element` | `asMethodElement(java.lang.String method)` Create an XML element to hold the Method handle part.
    `static org.licas_xml.abs.Element` | `asUrlElement(java.lang.String url)` Create an XML element to hold the URL handle part.
    `static org.licas_xml.abs.Element` | `changeFirstHandleServiceServer(org.licas_xml.abs.Element origHandle, java.lang.String newID)` Change the first handle service part value that is not the server, or the only service part if there is only 1 service element.
    `static org.licas_xml.abs.Element` | `createNewHandleHandle(java.lang.String serviceUuid)` Create a new handle spec with a service part only.
    `protected static org.licas_xml.abs.Element` | `createNewMethodHandle(java.lang.String methodName)` Create a new handle spec with a method name part only.
    `static org.licas_xml.abs.Element` | `createNewServerHandle(java.lang.String url)` Create a new handle spec for a different server uri.
    `static org.licas_xml.abs.Element` | `createNewUrlHandle(java.lang.String url)` Create a new handle spec with a URL part only.
    `static org.licas_xml.abs.Element` | `createServiceHandle(org.licas_xml.abs.Element uriWithURL, java.lang.String uuid)` Create a full service handle, including the server ip address, for the locally running server.
    `static org.licas_xml.abs.Element` | `createServiceHandle(java.lang.String uuid)` Create a full service handle, including the server ip address, for the locally running server.
    `static org.licas_xml.abs.Element` | `formatURI(org.licas_xml.abs.Element origHandle)` Format the full handle so that the URL part can be compared with other URLs.
    `static java.lang.String` | `getFirstHandleServiceServer(org.licas_xml.abs.Element origHandle)` Return the first handle service part value that is not the server, or the only service part if there is only 1 service element.
    `static java.lang.String` | `getFirstServiceHandle(org.licas_xml.abs.Element origHandle)` Return the first handle service part value.
    `static java.lang.String` | `getLastServiceHandle(org.licas_xml.abs.Element origHandle)` Return the last handle service part value.
    `static org.licas_xml.abs.Element` | `getLocalServerURI()` If a local server is running then try to create its default handle.
    `static java.lang.String` | `getLocalServerUriStr()` Return the whole URI address of the static HTTP server as a String.
    `static java.lang.String` | `getMethod(org.licas_xml.abs.Element methodCall)` Return the method part of a method call.
    `static org.licas_xml.abs.Element` | `getRestOfCall(org.licas_xml.abs.Element methodCall)` Return the rest of a method call with the first part of any type removed.
    `static java.lang.String` | `getURL(org.licas_xml.abs.Element address)` Return the URL part of an address or null if it does not exist.
    `static java.lang.String` | `handleToString(org.licas_xml.abs.Element handle)` Get a string-based description of the handle.
    `static boolean` | `hasHandleSeparator(org.licas_xml.abs.Element methodCall)` Return true if the method call has a handle separator between two elements of the form service `S` or method `M`.
    `static boolean` | `hasURL(org.licas_xml.abs.Element origHandle)` Return true if the uri has a URL part as specified by the `U` name.
    `protected static boolean` | `isDirectMethodCall(org.licas_xml.abs.Element methodCall)` Return true if the method call is a direct call on the current object.
    `static boolean` | `isExecuteMethod(java.lang.String methodName)` Return true if the method name is the execute method.
    `static boolean` | `isLocalURI(org.licas_xml.abs.Element origHandle)` Return true if the uri is for a service with a local ip address - the local server.
    `static boolean` | `isServerURI(org.licas_xml.abs.Element origHandle)` Return true if the uri is a server uri.
    `static org.licas_xml.abs.Element` | `removeFirstServiceHandle(org.licas_xml.abs.Element servicePath)` Return the whole handle with the first service part removed.
    `static org.licas_xml.abs.Element` | `removeLastServiceHandle(org.licas_xml.abs.Element servicePath)` Return the whole handle with the last service part removed.
    `static org.licas_xml.abs.Element` | `removeURL(org.licas_xml.abs.Element origHandle)` Remove the URL part of the handle.
    `static int` | `separatorCount(org.licas_xml.abs.Element methodCall)` Return a count of the number of handle separators in the method call, ignoring the URL part.
    `static org.licas_xml.abs.Element` | `toFull(java.lang.String handleURI)` Try to re-create a properly formatted XML-based URI description from the String-based description.
    `static java.lang.String` | `toShort(org.licas_xml.abs.Element handleURI)` Remove the XML tag names to return a URI description for displaying.
    `static java.lang.String` | `toShort(java.lang.String handleURI)` Remove the XML tag names to return a URI description for displaying.

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Handle

          public Handle()

      Creates a new instance of Handle

  - ### Method Detail

    - #### toShort

          public static java.lang.String toShort(java.lang.String handleURI)

      Remove the XML tag names to return a URI description for displaying.
      Parameters:
        `handleURI` - a properly formatted URI description, created by this class.
      Returns:
        the path contents without the formatting.

    - #### toShort

          public static java.lang.String toShort(org.licas_xml.abs.Element handleURI)

      Remove the XML tag names to return a URI description for displaying.
      Parameters:
        `handleURI` - a properly formatted URI description, created by this class.
      Returns:
        the path contents without the formatting.

    - #### toFull

          public static org.licas_xml.abs.Element toFull(java.lang.String handleURI)

      Try to re-create a properly formatted XML-based URI description from the String-based description.
      Parameters:
        `handleURI` - the path contents without any XML formatting.
      Returns:
        the path contents contained inside of XML elements, as defined by this class.

    - #### isServerURI

          public static boolean isServerURI(org.licas_xml.abs.Element origHandle)

      Return true if the uri is a server uri.
      Parameters:
        `origHandle` - the original handle of any type.
      Returns:
        true if a server uri of the form `<Handle><U>http://123.4.5.6:8888</U><S>httpServer</S></Handle>`.

    - #### isLocalURI

          public static boolean isLocalURI(org.licas_xml.abs.Element origHandle)

      Return true if the uri is for a service with a local ip address - the local server.
      Parameters:
        `origHandle` - the original handle of any type.
      Returns:
        true if a server ip address and the handle ip address are the same.

    - #### isExecuteMethod

          public static boolean isExecuteMethod(java.lang.String methodName)

      Return true if the method name is the execute method. This is typically only called by the system.
      Parameters:
        `methodName` - the method that should be equal to the `EXECUTE` (execute) constant.
      Returns:
        true if the method is the execute method.

    - #### hasHandleSeparator

          public static boolean hasHandleSeparator(org.licas_xml.abs.Element methodCall)

      Return true if the method call has a handle separator between two elements of the form service `S` or method `M`.
      Parameters:
        `methodCall` - the method call of any form.
      Returns:
        true if any handle separators exists.

    - #### hasURL

          public static boolean hasURL(org.licas_xml.abs.Element origHandle)

      Return true if the uri has a URL part as specified by the `U` name.
      Parameters:
        `origHandle` - the original handle of any type. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>uuid</S><M>method</M></Handle>`.
      Returns:
        true if the `<U>`part exists.

    - #### isDirectMethodCall

          protected static boolean isDirectMethodCall(org.licas_xml.abs.Element methodCall)

      Return true if the method call is a direct call on the current object. This is typically only called by the system.
      Parameters:
        `methodCall` - the full method call. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>uuid</S><M>method</M></Handle>`.
      Returns:
        true if call only has one handle separator or less, ignoring the URL part and is not an 'execute' method. True in this case (1 separator).

    - #### handleToString

          public static java.lang.String handleToString(org.licas_xml.abs.Element handle)
                                                 throws java.lang.Exception

      Get a string-based description of the handle. This can be useful of key indexes, etc.
      Parameters:
        `handle` - the XML handle element.
      Returns:
        the string-based description.
      Throws:
        `java.lang.Exception` - any error.

    - #### createServiceHandle

          public static org.licas_xml.abs.Element createServiceHandle(java.lang.String uuid)

      Create a full service handle, including the server ip address, for the locally running server. This is the most common form of address that is used.
      Parameters:
        `uuid` - the uuid of the service to add to the server address, to make a full path description to a base service. If the uuid is already a full URI description, then an XML form of it is returned without any other changes.
      Returns:
        the full handle path description. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>uuid</S></Handle>`.

    - #### createServiceHandle

          public static org.licas_xml.abs.Element createServiceHandle(org.licas_xml.abs.Element uriWithURL,
                                                                      java.lang.String uuid)

      Create a full service handle, including the server ip address, for the locally running server. This is the most common form of address that is used.
      Parameters:
        `uriWithURL` - a server or service URI handle with the target URL address.
        `uuid` - the uuid of the service to add to the URL address, to make a full path description to a base service.
      Returns:
        the full handle path description. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>uuid</S></Handle>`.

    - #### createNewServerHandle

          public static org.licas_xml.abs.Element createNewServerHandle(java.lang.String url)

      Create a new handle spec for a different server uri.
      Parameters:
        `url` - the URL address of the server, e.g. http://987.6.5.4:3333.
      Returns:
        the handle spec in XML format, including the default server id. This could look like `<Handle><U>http://987.6.5.4:3333</U><S>HttpServer</S></Handle>`.

    - #### createNewUrlHandle

          public static org.licas_xml.abs.Element createNewUrlHandle(java.lang.String url)

      Create a new handle spec with a URL part only.
      Parameters:
        `url` - the url address, e.g. http://123.4.5.6:8888.
      Returns:
        the handle spec in XML format. This could look like `<Handle><U>http://123.4.5.6:8888</U></Handle>`.

    - #### createNewHandleHandle

          public static org.licas_xml.abs.Element createNewHandleHandle(java.lang.String serviceUuid)

      Create a new handle spec with a service part only.
      Parameters:
        `serviceUuid` - the service UUID.
      Returns:
        the handle spec in XML format. This could look like `<Handle><S>serviceUuid</S></Handle>`.

    - #### createNewMethodHandle

          protected static org.licas_xml.abs.Element createNewMethodHandle(java.lang.String methodName)

      Create a new handle spec with a method name part only. This is typically only called by the system.
      Parameters:
        `methodName` - the method name.
      Returns:
        the handle spec in XML format. This could look like `<Handle><M>methodName</M></Handle>`.

    - #### addToHandle

          public static org.licas_xml.abs.Element addToHandle(org.licas_xml.abs.Element handle,
                                                              org.licas_xml.abs.Element newElement)

      Return a handle with the new element added at the end.
      Parameters:
        `handle` - the handle to add to. This is not changed.
        `newElement` - the new handle element. Note that the new element must be converted into the correct format first using either `asUrlElement`, `asHandleElement`, or `asMethodElement`, depending on the element type.
      Returns:
        the new Handle element. This could look like `<Handle><orig handle>orig handle value</orig handle><?>new element value here</?></Handle>`.

    - #### addToHandleFirstElement

          public static org.licas_xml.abs.Element addToHandleFirstElement(org.licas_xml.abs.Element handle,
                                                                          org.licas_xml.abs.Element newElement)

      Return a handle with the new element added to the handle as the first element of the handle.
      Parameters:
        `handle` - the handle to add to. This is not changed.
        `newElement` - the new handle element. Note that the new element must be converted into the correct format first using either `asUrlElement`, `asHandleElement`, or `asMethodElement`, depending on the element type.
      Returns:
        the new Handle element. This could look like `<Handle><?>new element value here</?><orig handle>orig handle value</orig handle></Handle>`.

    - #### addExecute

          protected static org.licas_xml.abs.Element addExecute(org.licas_xml.abs.Element handle)

      Add the specific execute method name to the handle. This is typically only called by the system.
      Parameters:
        `handle` - the handle to add to. This is not changed.
      Returns:
        the handle with the execute method appended. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>uuid</S><M>execute</M></Handle>`.

    - #### getURL

          public static java.lang.String getURL(org.licas_xml.abs.Element address)

      Return the URL part of an address or null if it does not exist.
      Parameters:
        `address` - the address of the form `<Handle><U>http://123.4.5.6:8888</U><S>uuid</S> ... </Handle>`.
      Returns:
        the url part. This could look like `http://123.4.5.6:8888`.

    - #### getRestOfCall

          public static org.licas_xml.abs.Element getRestOfCall(org.licas_xml.abs.Element methodCall)

      Return the rest of a method call with the first part of any type removed. This is typically only called by the system.
      Parameters:
        `methodCall` - a full or partial method call description. This could look like `<Handle><?>any handle part</?><S>uuid</S><M>method</M></Handle>`.
      Returns:
        the handle with the first part removed. This could look like `<Handle><S>uuid</S><M>method</M></Handle>`

    - #### getLocalServerURI

          public static org.licas_xml.abs.Element getLocalServerURI()

      If a local server is running then try to create its default handle.
      Returns:
        the default handle with the local ip address, or null if no server is running. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>HttpServer</S></Handle>`.

    - #### getLocalServerUriStr

          public static java.lang.String getLocalServerUriStr()
                                                       throws java.lang.Exception

      Return the whole URI address of the static HTTP server as a String.
      Returns:
        whole URI address.
      Throws:
        `java.lang.Exception` - any error.

    - #### getMethod

          public static java.lang.String getMethod(org.licas_xml.abs.Element methodCall)

      Return the method part of a method call. This is typically only called by the system.
      Parameters:
        `methodCall` - the original handle. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>uuid</S><M>method</M></Handle>`.
      Returns:
        the method part. This could look like `method`.

    - #### getFirstServiceHandle

          public static java.lang.String getFirstServiceHandle(org.licas_xml.abs.Element origHandle)

      Return the first handle service part value.
      Parameters:
        `origHandle` - the original handle. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>uuid1</S><S>uuid2</S></Handle>`.
      Returns:
        the first service part value or null if none exist. This could look like `uuid1`.

    - #### getLastServiceHandle

          public static java.lang.String getLastServiceHandle(org.licas_xml.abs.Element origHandle)

      Return the last handle service part value.
      Parameters:
        `origHandle` - the original handle. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>uuid1</S><S>uuid2</S></Handle>`.
      Returns:
        the last service part value or null if none exist. This could look like `uuid2`.

    - #### getFirstHandleServiceServer

          public static java.lang.String getFirstHandleServiceServer(org.licas_xml.abs.Element origHandle)

      Return the first handle service part value that is not the server, or the only service part if there is only 1 service element.
      Parameters:
        `origHandle` - the original handle. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>HttpServer</S><S>uuid1</S><S>uuid2</S></Handle>`.
      Returns:
        the first service part value or null if none exist. This could look like `uuid1`.

    - #### changeFirstHandleServiceServer

          public static org.licas_xml.abs.Element changeFirstHandleServiceServer(org.licas_xml.abs.Element origHandle,
                                                                                 java.lang.String newID)

      Change the first handle service part value that is not the server, or the only service part if there is only 1 service element.
      Parameters:
        `origHandle` - the original handle. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>HttpServer</S><S>uuid1</S></Handle>`.
        `newID` - the new service ID to change to, for example `newUuid`.
      Returns:
        the sane path with last service part changed. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>HttpServer</S><S>newUuid</S></Handle>`. or the same Handle if there is no service element.

    - #### removeURL

          public static org.licas_xml.abs.Element removeURL(org.licas_xml.abs.Element origHandle)

      Remove the URL part of the handle.
      Parameters:
        `origHandle` - the original handle. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>uuid</S></Handle>`.
      Returns:
        the handle with the URL part removed. This could look like `<Handle><S>uuid</S></Handle>`.

    - #### removeFirstServiceHandle

          public static org.licas_xml.abs.Element removeFirstServiceHandle(org.licas_xml.abs.Element servicePath)

      Return the whole handle with the first service part removed.
      Parameters:
        `servicePath` - the original handle. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>uuid1</S><S>uuid2</S></Handle>`.
      Returns:
        the same handle with the first service part removed. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>uuid2</S></Handle>`.

    - #### removeLastServiceHandle

          public static org.licas_xml.abs.Element removeLastServiceHandle(org.licas_xml.abs.Element servicePath)

      Return the whole handle with the last service part removed. This probably makes most sense if there is no method part to the handle.
      Parameters:
        `servicePath` - the original handle. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>uuid1</S><S>uuid2</S></Handle>`.
      Returns:
        the same handle with the last service part removed. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>uuid1</S></Handle>`.

    - #### separatorCount

          public static int separatorCount(org.licas_xml.abs.Element methodCall)

      Return a count of the number of handle separators in the method call, ignoring the URL part.
      Parameters:
        `methodCall` - a method call of any form. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>uuid1</S><S>uuid2</S><M>method</M></Handle>`.
      Returns:
        a count of the number of handle separators, 2 in this case.

    - #### formatURI

          public static org.licas_xml.abs.Element formatURI(org.licas_xml.abs.Element origHandle)

      Format the full handle so that the URL part can be compared with other URLs.
      Parameters:
        `origHandle` - the original handle. This could look like `<Handle><U>http://123.4.5.6:8888</U><S>service_1</S><S>service_2</S></Handle>`.
      Returns:
        the handle with a re-formatted URL. this could look like `<Handle><U>http://123.4.5.6:8888/</U><S>service_1</S><S>service_2</S></Handle>`.

    - #### asUrlElement

          public static org.licas_xml.abs.Element asUrlElement(java.lang.String url)

      Create an XML element to hold the URL handle part.
      Parameters:
        `url` - the url address. This could look like `http://123.4.5.6:8888`.
      Returns:
        URL handle part only. This could look like `<U>http://123.4.5.6:8888</U>`.

    - #### asHandleElement

          public static org.licas_xml.abs.Element asHandleElement(java.lang.String serviceUuid)

      Create an XML element to hold the Service handle part.
      Parameters:
        `serviceUuid` - the service name for the next handle path.
      Returns:
        service handle part only. This could look like `<S>serviceUuid</S>`.

    - #### asMethodElement

          public static org.licas_xml.abs.Element asMethodElement(java.lang.String method)

      Create an XML element to hold the Method handle part.
      Parameters:
        `method` - the method name.
      Returns:
        method handle part only. This could look like `<M>method</M>`.