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>http://123.4.5.6:8888<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

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>http://123.4.5.6:8888<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>http://123.4.5.6:8888<S>uuid</S><M>method</M></Handle>.
 
 Returns:
 
 true if the 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>http://123.4.5.6:8888<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>http://123.4.5.6:8888<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>http://123.4.5.6:8888<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>http://987.6.5.4:3333<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>http://123.4.5.6:8888</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>http://123.4.5.6:8888<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>http://123.4.5.6:8888<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>http://123.4.5.6:8888<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>http://123.4.5.6:8888<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>http://123.4.5.6:8888<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>http://123.4.5.6:8888<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>http://123.4.5.6:8888<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>http://123.4.5.6:8888<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>http://123.4.5.6:8888<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>http://123.4.5.6:8888<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>http://123.4.5.6:8888<S>uuid1</S><S>uuid2</S></Handle>.
 
 Returns:
 
 the same handle with the first service part removed. This could look like <Handle>http://123.4.5.6:8888<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>http://123.4.5.6:8888<S>uuid1</S><S>uuid2</S></Handle>.
 
 Returns:
 
 the same handle with the last service part removed. This could look like <Handle>http://123.4.5.6:8888<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>http://123.4.5.6:8888<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>http://123.4.5.6:8888<S>service_1</S><S>service_2</S></Handle>.
 
 Returns:
 
 the handle with a re-formatted URL. this could look like <Handle>http://123.4.5.6:8888/<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 http://123.4.5.6:8888.
 - 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>.

Class Handle

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Handle

Method Detail

toShort

toShort

toFull

isServerURI

isLocalURI

isExecuteMethod

hasHandleSeparator

hasURL

isDirectMethodCall

handleToString

createServiceHandle

createServiceHandle

createNewServerHandle

createNewUrlHandle

createNewHandleHandle

createNewMethodHandle

addToHandle

addToHandleFirstElement

addExecute

getURL

getRestOfCall

getLocalServerURI

getLocalServerUriStr

getMethod

getFirstServiceHandle

getLastServiceHandle

getFirstHandleServiceServer

changeFirstHandleServiceServer

removeURL

removeFirstServiceHandle

removeLastServiceHandle

separatorCount

formatURI

asUrlElement

asHandleElement

asMethodElement