issrg.utils.repository
Class MultiRepository

java.lang.Object
  issrg.utils.repository.DefaultRepository
      issrg.utils.repository.MultiRepository

All Implemented Interfaces:

AttributeRepository

public class MultiRepository
extends DefaultRepository

This class is the implementation of the Attribute Repository for multithreaded access to a cluster of repositories. It can be built out of an array of Repositories. Each of these repositories constitutes a root for searches.

The object can be used for retrieving similar information from multiple directories simultaneously. For example, it is useful when retrieving X.509 Attribute Certificates for PMI entities that possess ACs issued by different issuers (therefore, stored in different repositories available to them).

The object creates multiple threads (one per repository) when attributes are requested and performs the searches simultaneously. This improves efficiency, since most of the time the repositories are waiting for a reply. The object waits till all of the contexts return anything or report an error, so the result is always complete.

Version:

0.2

Author:

A Otenko

Field Summary

Fields inherited from interface issrg.utils.repository.AttributeRepository

FAILURE_STATUS, INHERENT_FAILURE_STATUS, PARTIAL_SUCCESS_STATUS, SUCCESS_STATUS

Constructor Summary

protected	MultiRepository()
	MultiRepository(AttributeRepository repository) This creates a MultiRepository with a single root repository
	MultiRepository(AttributeRepository[] repositories) This constructor builds the MultiRepository with a number of roots.

Method Summary

javax.naming.directory.Attribute	getAttribute(TokenLocator locator, java.lang.String AttributeName) This is method searches for a single attribute.
protected javax.naming.directory.Attributes	getAttributes(java.security.Principal[] DN, AttributeRepository[] repositories, java.lang.String[] AttributeNames) This is the root method called by any other getAttributes that gets the set of named attributes from the entries with the DNs.
javax.naming.directory.Attributes	getAttributes(java.security.Principal DN, java.lang.String[] AttributeNames) This method searches for the given attributes in the repositories provided at construction time.
javax.naming.directory.Attributes	getAttributes(TokenLocator locator, java.lang.String[] AttributeNames) This method will collect attributes from all the entries identified by the TokenLocator.
java.lang.Throwable	getDiagnosis() This method returns the Throwable, representing the error, or null, if no error has been encountered (only if the repository is in SUCCESS_STATUS).
AttributeRepository[]	getRepositories() This method returns the array of repositories used by the MultiRepository by default (when TokenLocators do not refer to a specific repository).
int	getStatus() This method returns the status of the repository.

Methods inherited from class issrg.utils.repository.DefaultRepository

getAllAttributes, getAttribute

Methods inherited from class java.lang.Object

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

Constructor Detail

MultiRepository

protected MultiRepository()

MultiRepository

public MultiRepository(AttributeRepository[] repositories)

This constructor builds the MultiRepository with a number of roots.

Parameters:

repositories - An array of AttributeRepositories to be used as the search roots

MultiRepository

public MultiRepository(AttributeRepository repository)

This creates a MultiRepository with a single root repository

Parameters:

repository - A AttributeRepository

Method Detail

getAttributes

public javax.naming.directory.Attributes getAttributes(java.security.Principal DN,
                                                       java.lang.String[] AttributeNames)
                                                throws RepositoryException

This method searches for the given attributes in the repositories provided at construction time.

Parameters:

DN - - the Principal naming the entry in the repositories

AttributeNames - - the names of the attributes to be retrieved; if null, all available attributes will be returned

Returns:

the requested Attributes

Throws:

RepositoryException

getAttributes

public javax.naming.directory.Attributes getAttributes(TokenLocator locator,
                                                       java.lang.String[] AttributeNames)
                                                throws RepositoryException

This method will collect attributes from all the entries identified by the TokenLocator. Each TokenLocator in the chain points to a location in a repository; if the repository in it is null, all the repositories provided at construction time MultiRepository will be searched; otherwise only the repository stated in the TokenLocator will be searched.

Parameters:

locator - - the locator of the entries with the attributes

AttributeNames - - the names of the attributes

Returns:

Attributes that are located in all the locations pointed to by the TokenLocator

Throws:

RepositoryException

getAttribute

public javax.naming.directory.Attribute getAttribute(TokenLocator locator,
                                                     java.lang.String AttributeName)
                                              throws RepositoryException

This is method searches for a single attribute. This is a shortcut for getAttributes(locator, new String[]{AttributeName}).get(AttributeName);

Parameters:

locator - - the TokenLocator identifying multiple locations of the attribute

AttributeName - - the name of the attribute to retrieve

Returns:

the requested Attribute

Throws:

RepositoryException

getAttributes

protected javax.naming.directory.Attributes getAttributes(java.security.Principal[] DN,
                                                          AttributeRepository[] repositories,
                                                          java.lang.String[] AttributeNames)
                                                   throws RepositoryException

This is the root method called by any other getAttributes that gets the set of named attributes from the entries with the DNs. It searches all provided repositories simultaneously. If the DN and named attribute exist in more than one of the named contexts, then multiple attribute values will be returned.

The list of entry names DN is synchronised with the list of repositories so that each entry name is used only for the corresponding repository, but the whole list of attributes is requested from each repository. When other getAttributes methods use this method, they simply construct such synchronous lists of entry names and repositories. These methods do not update the status or diagnosis set by this method, and they propagate the exceptions thrown by this method.

Effectively, this method constructs a new MultiThreadSearch and invokes a getAttributes method on it. Because this may cause recursive invocation of this method from different threads, this method is NOT synchronized. For example, a search for attributes in two chained TokenLocators with no repository specified constructs one MultiThreadSearch, which spawns two threads, each attempting to invoke getAttributes method on this very MultiRepository object; this should be allowed (no mutex on the method), and in its turn creates two other MultiThreadSearches, each spawning one thread for each initial repository passed to the MultiRepository at construction time. The side effect of this is that during the call to getAttributes the status and diagnosis values are undetermined, since the calls to multiple MultiThreadSearch will temporarily set the status and diagnosis of this MultiRepository, until the recursion unwinds back, and the MultiThreadSearch at the root of this recursion will set the ultimate diagnosis and status of invocation of getAttributes method. Note also that if the getAttributes method on the corresponding repositories is synchronized, this will only slow down the multithreaded search, but will not block the process (unless by some bad design they use the same MultiRepository that invoked them).

After calling the method the repository will be set into one of the states: FAILURE_STATUS, SUCCESS_STATUS or PARTIAL_SUCCESS_STATUS. Failure means there were no roots that succeeded. Success means that all of the roots succeeded (the entries were found and some or no attributes were retrieved). Partial success means that some of the roots failed, but some have succeeded, which may be in case some of the roots do not contain the required entry. The caller must find out himself what the cause is, and decide if the results are sufficiently successful.

Parameters:

DN - The distinguished names of the entry from which the attributes are requested

repositories - The repositories to be searched; must have the same number of elements, as DN; each DN must have a non-null repository corresponding

AttributeNames - The array of LDAP names for the attributes; can be null, if all available attributes and their values are to be retrieved

Returns:

the requested attributes; the Repository status reflects the status of retrieval, the diagnosis contains exceptions the underlying objects threw, if they failed

Throws:

RepositoryException, - if all of the repositories failed, in which case the embedded exception will be the Throwable returned by getDiagnosis method; FAILURE_STATUS will also be set

RepositoryException

See Also:

MultiThreadSearch.getAttributes(java.security.Principal[], issrg.utils.repository.AttributeRepository[], java.lang.String[])

getStatus

public int getStatus()

This method returns the status of the repository. It is set when returning attributes.

Returns:

the integer value corresponding to the status

See Also:

getAttributes(java.security.Principal,String[])

getDiagnosis

public java.lang.Throwable getDiagnosis()

This method returns the Throwable, representing the error, or null, if no error has been encountered (only if the repository is in SUCCESS_STATUS). The Throwable contains an error message and the stack trace of the error.

Returns:

Throwable object, representing the error, or null, if no error occured

See Also:

AttributeRepository.getStatus()

getRepositories

public AttributeRepository[] getRepositories()

This method returns the array of repositories used by the MultiRepository by default (when TokenLocators do not refer to a specific repository).

Returns:

the array of AttributeRespositories used by MultiRepository by default; is never null, does not contain null entries, but may be empty (zero length)