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

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.