org.licas

## Class PasswordHandler

- java.lang.Object
- - org.licas.PasswordHandler

-     public class PasswordHandler
      extends java.lang.Object

  This class stores and processes passwords related to the parent service. This includes all levels of security access if security levels are included. By default, a service has one password to allow access to any of its methods and also a service password to allow the administrator of the service to perform other method operations that might alter the service itself. These are stored in the `password` and `adminKey` fields respectively. If no security levels are specified in an admin document, then these are the only passwords that are required.

  If an admin document is included with the service's initialisation, then security levels can be specified, where each level can have a different password. These different levels are also managed by this object, which essentially needs to check that a password entered is the same as the one at the specified level. This also relates to the method that the calling service is trying to invoke. The service is also allowed to specify certain methods to be globally available, without any password. These are stored in the `globalMethods` list.

  While traversing through nested services, it is necessary to create temporary passwords to allow access to the next nested service by the invoking service only. These temporary passwords are stored in a `tempPasswords` list. These are created and destroyed automatically during the traversal process.

  The parent service also needs to be able to store passwords to other services that it knows about, to allow it to access the other services' methods. These are stored in the `servicePasswords` and `adminKeys` lists.

  This class now also accepts Element URI descriptions as well as String-based IDs. The element is automatically converted into its String-based equivalent and that is then used. This means that it is easy to pass the full URI Handle description for any service, if you want to store the password under a full description. This might be useful to GUIs, for example, that connect to more than one server. note however that when asking for a password, you need to match the same key that you added it with. So if it was added with a URI, the same URI needs to be entered to retrieve it.

  Author:
    Kieran Greer

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `PasswordHandler()` Create a new instance of PasswordHandler.
    `PasswordHandler(java.lang.String thePassword, java.lang.String theAdminKey)` Create a new instance of PasswordHandler.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `addAdminKey(org.licas_xml.abs.Element serviceUri, java.lang.String adminKey)` Add a new service key for a new service.
    `boolean` | `addAdminKey(java.lang.String serviceID, java.lang.String adminKey)` Add a new service key for a new service.
    `void` | `addPasswords(java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>> allPasswords)` Add the passwords in the hashtable structure to the handler.
    `boolean` | `addServicePassword(org.licas_xml.abs.Element serviceUri, java.lang.String servicePassword)` Add a new password for a new service.
    `boolean` | `addServicePassword(java.lang.String serviceID, java.lang.String servicePassword)` Add a new password for a new service.
    `org.licas_xml.abs.Element` | `asXml()` Serialize the password details into XML.
    `boolean` | `canAccess(java.lang.String thePassword)` Return true if the password allows the calling component to access this component.
    `protected boolean` | `canAccess(java.lang.String thePassword, java.lang.String methodName)` Return true if the password allows the calling component to access the specified method on this component.
    `protected boolean` | `canAccess(java.lang.String thePassword, java.lang.String methodName, org.licas_xml.abs.Element methodXml)` Return true if the password allows the calling component to access the specified method on this component.
    `boolean` | `canAccessTemp(java.lang.String thePassword)` Return true if the password allows the calling component to access this component by a temp password.
    `void` | `clearLinkedServicePasswords(java.util.ArrayList<?> serviceIDs, java.lang.String thisAdminKey)` Remove all passwords relating to linked or nested services.
    `void` | `clearLinkedServicePasswords(java.lang.String thisAdminKey)` Remove all passwords relating to linked or nested services.
    `void` | `fromXml(org.licas_xml.abs.Element passwordsXml)` Parse the XML-based description of passwords and add to this password handler.
    `java.lang.String` | `getAdminKey()` Get the service key.
    `java.lang.String` | `getAdminKey(org.licas_xml.abs.Element serviceUri)` Get the admin key associated with the specified service.
    `java.lang.String` | `getAdminKey(java.lang.String serviceID)` Get the admin key associated with the specified service.
    `protected java.lang.String` | `getLevelPassword(java.lang.String levelID)` Get the password associated with the specified service level.
    `static java.lang.String` | `getNewPassword()` Get a new password.
    `java.lang.String` | `getPassword()` Get the password.
    `protected java.lang.String` | `getPassword(org.licas_xml.abs.Element serviceUri, java.lang.String theAdminKey)` Get the password for the specified service.
    `protected java.lang.String` | `getPassword(java.lang.String theAdminKey)` Get the password for this service based on this service's key.
    `protected java.lang.String` | `getPassword(java.lang.String serviceID, java.lang.String theAdminKey)` Get the password for the specified service.
    `java.lang.String` | `getServicePassword(org.licas_xml.abs.Element serviceUri)` Get the password associated with the specified service.
    `java.lang.String` | `getServicePassword(java.lang.String serviceID)` Get the password associated with the specified service.
    `java.lang.String` | `getServicePassword(java.lang.String serviceID, java.lang.String serverUrl)` Get the service password, making a remote call if necessary.
    `java.util.List<java.lang.String>` | `getTempPasswords()` Get the temporary passwords.
    `boolean` | `hasAdminKey(org.licas_xml.abs.Element serviceUri)` Return true if a service key is stored for the specified service uuid.
    `boolean` | `hasAdminKey(java.lang.String serviceID)` Return true if a service key is stored for the specified service uuid.
    `boolean` | `hasServicePassword(org.licas_xml.abs.Element serviceUri)` Return true if a password is stored for the specified service uuid.
    `boolean` | `hasServicePassword(java.lang.String serviceID)` Return true if a password is stored for the specified service uuid.
    `boolean` | `isAdminKey(java.lang.String theAdminKey)` Return true if the key passed in is the same as this service's admin key.
    `boolean` | `isPassword(java.lang.String thePassword)` Return true if the key passed in is the same as this service's password.
    `boolean` | `isPublicMethod(java.lang.String methodName)` Return true if the method can be freely called.
    `void` | `remove(java.util.ArrayList<?> serviceIDs)` Remove passwords and admin keys for the specified services.
    `void` | `removeAdminKey(org.licas_xml.abs.Element serviceUri)` Remove the admin key for the specified service if it exists.
    `void` | `removeAdminKey(java.lang.String serviceID)` Remove the admin key for the specified service if it exists.
    `void` | `removeExcept(java.util.ArrayList<?> serviceURIs)` Remove passwords and admin keys for all services except for the specified URIs.
    `void` | `removeServicePassword(org.licas_xml.abs.Element serviceUri)` Remove the specified service from the password list if it exists.
    `void` | `removeServicePassword(java.lang.String serviceID)` Remove the specified service from the password list if it exists.
    `void` | `reset(java.lang.String thePassword, java.lang.String theAdminKey)` Reset the password values.
    `void` | `setAllExclude(java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>> theAllExclude)` Set the excluded levels values.
    `void` | `setAllGroups(java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>> theAllGroups)` Set the level groups.
    `void` | `setLevelGroups(java.util.HashMap<java.lang.String,java.lang.String> theLevelGroups)` Set the groups for each level.
    `void` | `setLevelMethods(java.util.HashMap<java.lang.String,org.licas_xml.abs.Element> theLevelMethods)` Set the methods for each level.
    `void` | `setLevelOrder(java.util.ArrayList<java.lang.String> theLevelOrder)` Set the order of the access levels.
    `void` | `setLevelPasswords(java.util.HashMap<java.lang.String,java.lang.String> theLevelPasswords)` Set the passwords for each level.
    `protected void` | `setService(Service thisService)` Set a link to the parent service.
    `org.licas_xml.abs.Element` | `toXml()` Serialize the password details into XML.

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

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

- - ### Constructor Detail

    - #### PasswordHandler

          public PasswordHandler()

      Create a new instance of PasswordHandler. Initialise with `Const`.`ANON` passwords. They might not be used.

    - #### PasswordHandler

          public PasswordHandler(java.lang.String thePassword,
                                 java.lang.String theAdminKey)

      Create a new instance of PasswordHandler.
      Parameters:
        `thePassword` - the parent service password.
        `theAdminKey` - the parent service admin key.

  - ### Method Detail

    - #### reset

          public void reset(java.lang.String thePassword,
                            java.lang.String theAdminKey)

      Reset the password values.
      Parameters:
        `thePassword` - the service password.
        `theAdminKey` - the service key.

    - #### remove

          public void remove(java.util.ArrayList<?> serviceIDs)
                      throws java.lang.Exception

      Remove passwords and admin keys for the specified services.
      Parameters:
        `serviceIDs` - list of IDs for services to remove. Should be String key or Element path.
      Throws:
        `java.lang.Exception` - any error.

    - #### removeExcept

          public void removeExcept(java.util.ArrayList<?> serviceURIs)
                            throws java.lang.Exception

      Remove passwords and admin keys for all services except for the specified URIs.
      Parameters:
        `serviceURIs` - list of service URIs to keep. This must be exact and might probably be the server URIs themselves. Should be String key or Element path.
      Throws:
        `java.lang.Exception` - any error.

    - #### hasServicePassword

          public boolean hasServicePassword(org.licas_xml.abs.Element serviceUri)
                                     throws java.lang.Exception

      Return true if a password is stored for the specified service uuid.
      Parameters:
        `serviceUri` - the unique service URI.
      Returns:
        true if a password is stored for this service.
      Throws:
        `java.lang.Exception` - any error.

    - #### hasServicePassword

          public boolean hasServicePassword(java.lang.String serviceID)

      Return true if a password is stored for the specified service uuid.
      Parameters:
        `serviceID` - the unique service name.
      Returns:
        true if a password is stored for this service.

    - #### hasAdminKey

          public boolean hasAdminKey(org.licas_xml.abs.Element serviceUri)
                              throws java.lang.Exception

      Return true if a service key is stored for the specified service uuid.
      Parameters:
        `serviceUri` - the unique service URI.
      Returns:
        true if a service key is stored for this service.
      Throws:
        `java.lang.Exception` - any error.

    - #### hasAdminKey

          public boolean hasAdminKey(java.lang.String serviceID)

      Return true if a service key is stored for the specified service uuid.
      Parameters:
        `serviceID` - the unique service name.
      Returns:
        true if a service key is stored for this service.

    - #### isPassword

          public boolean isPassword(java.lang.String thePassword)

      Return true if the key passed in is the same as this service's password.
      Parameters:
        `thePassword` - the password to check.
      Returns:
        true if the same as this service password.

    - #### isAdminKey

          public boolean isAdminKey(java.lang.String theAdminKey)

      Return true if the key passed in is the same as this service's admin key.
      Parameters:
        `theAdminKey` - the key to check.
      Returns:
        true if the specified key is the service key.

    - #### canAccess

          protected boolean canAccess(java.lang.String thePassword,
                                      java.lang.String methodName)
                               throws java.lang.Exception

      Return true if the password allows the calling component to access the specified method on this component.
      Parameters:
        `thePassword` - the password to use.
        `methodName` - the name of the method.
      Returns:
        true if the specified password allows access to the method.
      Throws:
        `java.lang.Exception` - any error.

    - #### canAccess

          protected boolean canAccess(java.lang.String thePassword,
                                      java.lang.String methodName,
                                      org.licas_xml.abs.Element methodXml)
                               throws java.lang.Exception

      Return true if the password allows the calling component to access the specified method on this component.
      Parameters:
        `thePassword` - the password to use.
        `methodName` - the name of the method.
        `methodXml` - the xml description of the method.
      Returns:
        true if the specified password allows access to the method.
      Throws:
        `java.lang.Exception` - any error.

    - #### canAccess

          public boolean canAccess(java.lang.String thePassword)

      Return true if the password allows the calling component to access this component.
      Parameters:
        `thePassword` - the password to use.
      Returns:
        true if the specified password is the correct password or there is no password.

    - #### canAccessTemp

          public boolean canAccessTemp(java.lang.String thePassword)

      Return true if the password allows the calling component to access this component by a temp password.
      Parameters:
        `thePassword` - the password to use.
      Returns:
        true if the entered password is the valid.

    - #### getPassword

          protected java.lang.String getPassword(java.lang.String theAdminKey)

      Get the password for this service based on this service's key.
      Parameters:
        `theAdminKey` - the service key.
      Returns:
        the access password for this service.

    - #### getPassword

          protected java.lang.String getPassword(org.licas_xml.abs.Element serviceUri,
                                                 java.lang.String theAdminKey)
                                          throws java.lang.Exception

      Get the password for the specified service.
      Parameters:
        `serviceUri` - the unique service URI.
        `theAdminKey` - the service key.
      Returns:
        the password for the specified service or null if it cannot be retrieved.
      Throws:
        `java.lang.Exception` - any error.

    - #### getPassword

          protected java.lang.String getPassword(java.lang.String serviceID,
                                                 java.lang.String theAdminKey)
                                          throws java.lang.Exception

      Get the password for the specified service.
      Parameters:
        `serviceID` - the id of the service to ask the password for.
        `theAdminKey` - the service key.
      Returns:
        the password for the specified service or null if it cannot be retrieved.
      Throws:
        `java.lang.Exception` - any error.

    - #### getServicePassword

          public java.lang.String getServicePassword(java.lang.String serviceID,
                                                     java.lang.String serverUrl)
                                              throws ServiceException,
                                                     java.lang.Exception

      Get the service password, making a remote call if necessary. This method only makes a single call to the other service to try and retrieve the password with default values. It assumes that the other service will automatically return its password when asked (the default implementation) and does not negotiate in any way. If the service's password is already stored then no call in made.
      Parameters:
        `serviceID` - the uuid of the service. This should only be the uuid and not the whole serviceUri path.
        `serverUrl` - URL address of a remote server if it needs to be called. Can be null for local server.
      Returns:
        the password for the service to call.
      Throws:
        `ServiceException` - probably for password or service not found.
        `java.lang.Exception` - any error.

    - #### addPasswords

          public void addPasswords(java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>> allPasswords)
                            throws java.lang.Exception

      Add the passwords in the hashtable structure to the handler. If the service key already exists do not overwrite.
      Parameters:
        `allPasswords` - the list of passwords. Keys are the service ids of type String and values are lists containing service thread state, service password and service key.
      Throws:
        `java.lang.Exception` - any error.

    - #### getLevelPassword

          protected java.lang.String getLevelPassword(java.lang.String levelID)

      Get the password associated with the specified service level.
      Parameters:
        `levelID` - the level the password is for.
      Returns:
        the password if it exists or null otherwise.

    - #### getTempPasswords

          public java.util.List<java.lang.String> getTempPasswords()

      Get the temporary passwords.
      Returns:
        the value of tempPasswords. Values are passwords of type String.

    - #### clearLinkedServicePasswords

          public void clearLinkedServicePasswords(java.lang.String thisAdminKey)

      Remove all passwords relating to linked or nested services.
      Parameters:
        `thisAdminKey` - the service key for the parent service.

    - #### clearLinkedServicePasswords

          public void clearLinkedServicePasswords(java.util.ArrayList<?> serviceIDs,
                                                  java.lang.String thisAdminKey)
                                           throws java.lang.Exception

      Remove all passwords relating to linked or nested services.
      Parameters:
        `serviceIDs` - id list for service passwords to remove. Should be String key or Element path.
        `thisAdminKey` - the service key for the parent service.
      Throws:
        `java.lang.Exception` - any error.

    - #### addServicePassword

          public boolean addServicePassword(org.licas_xml.abs.Element serviceUri,
                                            java.lang.String servicePassword)
                                     throws java.lang.Exception

      Add a new password for a new service.
      Parameters:
        `serviceUri` - the unique service URI.
        `servicePassword` - the password to access the service.
      Returns:
        true if added or false if the service name already exists.
      Throws:
        `java.lang.Exception` - any error.

    - #### addServicePassword

          public boolean addServicePassword(java.lang.String serviceID,
                                            java.lang.String servicePassword)

      Add a new password for a new service.
      Parameters:
        `serviceID` - the unique id of the service.
        `servicePassword` - the password to access the service.
      Returns:
        true if added or false if the service name already exists.

    - #### removeServicePassword

          public void removeServicePassword(org.licas_xml.abs.Element serviceUri)
                                     throws java.lang.Exception

      Remove the specified service from the password list if it exists.
      Parameters:
        `serviceUri` - the unique service URI.
      Throws:
        `java.lang.Exception` - any error.

    - #### removeServicePassword

          public void removeServicePassword(java.lang.String serviceID)

      Remove the specified service from the password list if it exists.
      Parameters:
        `serviceID` - the unique service id.

    - #### getServicePassword

          public java.lang.String getServicePassword(org.licas_xml.abs.Element serviceUri)
                                              throws java.lang.Exception,
                                                     PasswordException

      Get the password associated with the specified service.
      Parameters:
        `serviceUri` - the unique service URI.
      Returns:
        the password if it exists or null otherwise.
      Throws:
        `PasswordException` - if no password exists.
        `java.lang.Exception` - any other error.

    - #### getServicePassword

          public java.lang.String getServicePassword(java.lang.String serviceID)
                                              throws PasswordException

      Get the password associated with the specified service. Password keys are all strings, but can be full handle paths or just uuids.
      Parameters:
        `serviceID` - the unique service id.
      Returns:
        the password if it exists or null otherwise.
      Throws:
        `PasswordException` - if no password exists.

    - #### addAdminKey

          public boolean addAdminKey(org.licas_xml.abs.Element serviceUri,
                                     java.lang.String adminKey)
                              throws java.lang.Exception

      Add a new service key for a new service.
      Parameters:
        `serviceUri` - the unique service URI.
        `adminKey` - the key to access the service.
      Returns:
        true if added or false if the service name already exists.
      Throws:
        `java.lang.Exception` - any error.

    - #### addAdminKey

          public boolean addAdminKey(java.lang.String serviceID,
                                     java.lang.String adminKey)

      Add a new service key for a new service.
      Parameters:
        `serviceID` - the unique id of the service.
        `adminKey` - the key to access the service.
      Returns:
        true if added or false if the service name already exists.

    - #### removeAdminKey

          public void removeAdminKey(org.licas_xml.abs.Element serviceUri)
                              throws java.lang.Exception

      Remove the admin key for the specified service if it exists.
      Parameters:
        `serviceUri` - the unique service URI.
      Throws:
        `java.lang.Exception` - any error.

    - #### removeAdminKey

          public void removeAdminKey(java.lang.String serviceID)

      Remove the admin key for the specified service if it exists.
      Parameters:
        `serviceID` - the unique service id.

    - #### getAdminKey

          public java.lang.String getAdminKey(org.licas_xml.abs.Element serviceUri)
                                       throws java.lang.Exception,
                                              PasswordException

      Get the admin key associated with the specified service.
      Parameters:
        `serviceUri` - the unique service URI.
      Returns:
        the admin key if it exists or null otherwise.
      Throws:
        `PasswordException` - if no admin key exists.
        `java.lang.Exception` - any other error.

    - #### getAdminKey

          public java.lang.String getAdminKey(java.lang.String serviceID)
                                       throws PasswordException

      Get the admin key associated with the specified service.
      Parameters:
        `serviceID` - the unique service id.
      Returns:
        the admin key if it exists or null otherwise.
      Throws:
        `PasswordException` - if no admin key exists.

    - #### setService

          protected void setService(Service thisService)

      Set a link to the parent service.
      Parameters:
        `thisService` - the parent service.

    - #### getPassword

          public java.lang.String getPassword()

      Get the password.
      Returns:
        the value of password.

    - #### getAdminKey

          public java.lang.String getAdminKey()

      Get the service key.
      Returns:
        the value of adminKey.

    - #### setLevelOrder

          public void setLevelOrder(java.util.ArrayList<java.lang.String> theLevelOrder)

      Set the order of the access levels.
      Parameters:
        `theLevelOrder` - the access levels in order from lowest to highest. Values are access level names of type String.

    - #### setLevelPasswords

          public void setLevelPasswords(java.util.HashMap<java.lang.String,java.lang.String> theLevelPasswords)

      Set the passwords for each level.
      Parameters:
        `theLevelPasswords` - the passwords for each level. Keys are access levels of type String and values are passwords of type String.

    - #### setLevelMethods

          public void setLevelMethods(java.util.HashMap<java.lang.String,org.licas_xml.abs.Element> theLevelMethods)

      Set the methods for each level.
      Parameters:
        `theLevelMethods` - the methods for each level. Keys are the level names of type String and values are method descriptions in XML format.

    - #### setLevelGroups

          public void setLevelGroups(java.util.HashMap<java.lang.String,java.lang.String> theLevelGroups)

      Set the groups for each level.
      Parameters:
        `theLevelGroups` - the access levels with related groups. Keys are the access levels of type String and values are the associated group names of type String.

    - #### setAllGroups

          public void setAllGroups(java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>> theAllGroups)

      Set the level groups.
      Parameters:
        `theAllGroups` - the groups the levels are put into. Keys are the group names of type String and values are the access levels in that group of type ArrayList of Strings.

    - #### setAllExclude

          public void setAllExclude(java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>> theAllExclude)

      Set the excluded levels values.
      Parameters:
        `theAllExclude` - the excluded levels values. Keys are the access levels of type String and values are the excluded access levels of type ArrayList of Strings.

    - #### isPublicMethod

          public boolean isPublicMethod(java.lang.String methodName)

      Return true if the method can be freely called.
      Parameters:
        `methodName` - the name of the method.
      Returns:
        true if the method can be freely called.

    - #### asXml

          public org.licas_xml.abs.Element asXml()

      Serialize the password details into XML. Any Handle-style keys are returned in a `shortened` form that is not XML-based.
      Returns:
        the passwords list as an XML-based description.

    - #### toXml

          public org.licas_xml.abs.Element toXml()
                                          throws java.lang.Exception

      Serialize the password details into XML. Any Handle-style keys are returned in a `full` form includes XML-based elements.
      Returns:
        the passwords list as an XML-based description.
      Throws:
        `java.lang.Exception` - any error.

    - #### fromXml

          public void fromXml(org.licas_xml.abs.Element passwordsXml)

      Parse the XML-based description of passwords and add to this password handler.
      Parameters:
        `passwordsXml` - an xml-based description, probably created using `toXml`.

    - #### getNewPassword

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

      Get a new password.
      Returns:
        a new unique password.
      Throws:
        `java.lang.Exception` - any error.