org.osid.id

Interface IdLookupSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

public interface IdLookupSession
extends OsidSession

This session is for retrieving Id objects. getIds() retrieves all known Ids. The existence of a single identifier can be confirmed through the getId() method, or it can be used as a means of Id translation.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupIds() Tests if this user can perform Id lookups.
Id	getId(Id id) Gets an Id.
IdList	getIdAliases(Id id) Gets a list of Id aliases of an Id.
IdList	getIdAliasesByAuthority(Id id, java.lang.String authority) Gets a list of Id aliases in a authority for an Id.
IdList	getIdAliasesByAuthorityAndNamespace(Id id, java.lang.String authority, java.lang.String namespace) Gets a list of Id aliases in a namespace for an Id.
IdList	getIds() Gets all Ids.
IdList	getIdsByAuthority(java.lang.String authority) Gets Ids by the given authority.
IdList	getIdsByAuthorityAndNamespace(java.lang.String authority, java.lang.String namespace) Gets Ids by the given authority and namespace.
IdList	getIdsByIds(IdList ids) Gets a list of Ids.
boolean	isEquivalent(Id id, Id equivalentId) Tests if the two Ids are equivalent.

Methods inherited from interface org.osid.OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

canLookupIds

boolean canLookupIds()

Tests if this user can perform Id lookups. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer lookup operations.

Returns:

false if lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getId

Id getId(Id id)
         throws NotFoundException,
                OperationFailedException,
                PermissionDeniedException

Gets an Id. This method serves to get the principal Id if the given Id Is an alias.

Parameters:

id - an Id

Returns:

the Id

Throws:

NotFoundException - id is not found

NullArgumentException - id is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getIdsByIds

IdList getIdsByIds(IdList ids)
                   throws NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

Gets a list of Ids. This method serves to get the principal Ids if different from the given Ids.

Parameters:

ids - a list of Ids

Returns:

a list of Ids

Throws:

NotFoundException - an id is not found

NullArgumentException - ids is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getIdsByAuthority

IdList getIdsByAuthority(java.lang.String authority)
                         throws OperationFailedException,
                                PermissionDeniedException

Gets Ids by the given authority.

Parameters:

authority - an authority

Returns:

a list of Ids

Throws:

NullArgumentException - authority is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getIdsByAuthorityAndNamespace

IdList getIdsByAuthorityAndNamespace(java.lang.String authority,
                                   java.lang.String namespace)
                                     throws OperationFailedException,
                                            PermissionDeniedException

Gets Ids by the given authority and namespace.

Parameters:

authority - an authority

namespace - a namespace

Returns:

a list of Ids

Throws:

NullArgumentException - authority or namespace is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getIds

IdList getIds()
              throws OperationFailedException,
                     PermissionDeniedException

Gets all Ids.

Returns:

the list of all Ids

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isEquivalent

boolean isEquivalent(Id id,
                   Id equivalentId)
                     throws OperationFailedException,
                            PermissionDeniedException

Tests if the two Ids are equivalent. Two Ids are equivalent if they identify the same object. If one of the Ids is not known, they are not equivalent.

Parameters:

id - an Id

equivalentId - an Id

Returns:

true if the Ids are equivalent, false otherwise

Throws:

NullArgumentException - null argument provided

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getIdAliases

IdList getIdAliases(Id id)
                    throws OperationFailedException,
                           PermissionDeniedException

Gets a list of Id aliases of an Id.

Parameters:

id - an Id

Returns:

a list of alias Ids

Throws:

NullArgumentException - id is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getIdAliasesByAuthority

IdList getIdAliasesByAuthority(Id id,
                             java.lang.String authority)
                               throws OperationFailedException,
                                      PermissionDeniedException

Gets a list of Id aliases in a authority for an Id.

Parameters:

id - an Id

authority - an authority

Returns:

a list of alias Ids

Throws:

NullArgumentException - id or authority is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getIdAliasesByAuthorityAndNamespace

IdList getIdAliasesByAuthorityAndNamespace(Id id,
                                         java.lang.String authority,
                                         java.lang.String namespace)
                                           throws OperationFailedException,
                                                  PermissionDeniedException

Gets a list of Id aliases in a namespace for an Id.

Parameters:

id - an Id

authority - an authority

namespace - a namespace

Returns:

a list of alias Ids

Throws:

NullArgumentException - id, authority, or namespace is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.