issrg.utils.repository
Interface AttributeRepository

All Known Implementing Classes:

DefaultRepository, FileRepository, LDAPRepository, MultiRepository, PMIXMLRepository, SAMLRepository, VirtualLDAP, VirtualRepository, VOMSSAMLRepository, WebDAVRepository

public interface AttributeRepository

This interface defines the basic methods that can be performed on a read-only repository. It provides methods for retrieving attributes from a given entry (attributes and entries are terms like for the Directory). Besides this the caller can enquire on the status of the repository between calls to react more intelligently should an outage occur.

Note that some terms (like DN) are Directory-like, but in fact they are treated in a quite general fashion, and the interface does not require them to be DNs, if the implementation uses a different naming convention.

For better multi-threaded support it is advised that the methods were NOT synchronized, so that multiple threads could request attributes simultaneously. Note also that if you do need them to be synchronized, make sure that there will be no recursive invocation of it from multiple threads. For example, MultiRepository spawns multiple threads that often invoke the same MultiRepository; if somehow your repository invokes getAttributes on the same MultiRepository that called it, the synchronized method in your repository may block execution. So the remedy is: don't wrap repositories that may call you, or don't use synchronized methods.

Version:

1.0

Author:

A Otenko

See Also:

MultiRepository

Field Summary

static int	FAILURE_STATUS This is a status code for when an unrecoverable error occurred.
static int	INHERENT_FAILURE_STATUS This is when the repository failed to process a request because any of the previous calls returned an unfavourable result.
static int	PARTIAL_SUCCESS_STATUS This is a status code for when the repository succeeded to execute the call only partially.
static int	SUCCESS_STATUS This is a status code for when everything is alright with the repository.

Method Summary

javax.naming.directory.Attributes	getAllAttributes(java.security.Principal DN) This method returns the collection of all attributes and all of their values.
javax.naming.directory.Attribute	getAttribute(java.security.Principal DN, java.lang.String AttributeName) This method returns the given attribute or null, if the attribute is not present in the given entry of the repository.
javax.naming.directory.Attributes	getAttributes(java.security.Principal DN, java.lang.String[] AttributeNames) This method does the same as getAttribute for each of the specified attributes in the attribute list.
java.lang.Throwable	getDiagnosis() This method returns the last Exception thrown or an exception the Repository wanted to throw very much, but did not, only because the error was not fatal.
int	getStatus() This method returns the status of the Repository.

Field Detail

SUCCESS_STATUS

static final int SUCCESS_STATUS

This is a status code for when everything is alright with the repository. Particularly, the last function call succeeded.

See Also:

Constant Field Values

FAILURE_STATUS

static final int FAILURE_STATUS

This is a status code for when an unrecoverable error occurred.

See Also:

Constant Field Values

PARTIAL_SUCCESS_STATUS

static final int PARTIAL_SUCCESS_STATUS

This is a status code for when the repository succeeded to execute the call only partially. For example, only part of attributes were returned.

See Also:

Constant Field Values

INHERENT_FAILURE_STATUS

static final int INHERENT_FAILURE_STATUS

This is when the repository failed to process a request because any of the previous calls returned an unfavourable result. Generally, this means that you should have checked the status before calling and calculate your decision to call this method more carefully. Repository implementations may not use this error code at all.

See Also:

Constant Field Values

Method Detail

getAttribute

javax.naming.directory.Attribute getAttribute(java.security.Principal DN,
                                              java.lang.String AttributeName)
                                              throws RepositoryException

This method returns the given attribute or null, if the attribute is not present in the given entry of the repository. Does effectively the same as

getAttributes(DN, new String[]{AttributeName});

though, returns one attribute only.

Parameters:

DN - is the Principal, for which to retrieve the attribute

AttributeName - is a repository attribute name of the attribute to return

Returns:

an Attribute with multiple values, retrieved from the Repository; can be null, if no such attribute exists in the given entry

Throws:

RepositoryException, - if no such entry exists, or other error occurs during the call

RepositoryException

getAttributes

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

This method does the same as getAttribute for each of the specified attributes in the attribute list. It looks in the named entry for the set of attributes. It returns any of the attributes found. Some of the attributes may be missing in the entry.

Parameters:

DN - is the Principal, for which to retrieve the attributes

AttributeNames - is an array of repository attribute names of the attributes to return; returns all attributes available, if the array is null

Returns:

an Attributes object with multiple values for each attribute, retrieved from the Repository; can be either an empty set of attributes or null, if no such attributes exist

Throws:

RepositoryException, - if no such entry exists, or other error occurs during the call

RepositoryException

getAllAttributes

javax.naming.directory.Attributes getAllAttributes(java.security.Principal DN)
                                                   throws RepositoryException

This method returns the collection of all attributes and all of their values. Does exactly the same as

getAttributes(DN, null);

Parameters:

DN - is the Principal, for which to retrieve the attributes

Returns:

an Attributes object, containing all values of all attributes of the given Principal; can be an empty set of attributes or null, if no attributes exist

Throws:

RepositoryException, - if no such entry exists, or other error occurs during the call

RepositoryException

getStatus

int getStatus()

This method returns the status of the Repository.

Returns:

one of the *_STATUS values

See Also:

SUCCESS_STATUS, FAILURE_STATUS, PARTIAL_SUCCESS_STATUS, INHERENT_FAILURE_STATUS

getDiagnosis

java.lang.Throwable getDiagnosis()

This method returns the last Exception thrown or an exception the Repository wanted to throw very much, but did not, only because the error was not fatal.

TODO: I am very keen to remove getStatus() method, and return DiagnosisException only; which will contain the status code in it and a reference to an embedded exception. Thus it will be possible to throw such an exception in cases of need, and still it will be possible to keep it for further information. I envisage that the PbaException is one of this sort: a DiagnosisException.

Returns:

the last Throwable the Repository was eager to throw or has thrown

See Also:

getStatus()