Interface IdLookupSession

All Superinterfaces:

AutoCloseable, Closeable, OsidSession, 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

Modifier and Type	Method	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, String authority)	Gets a list of Id aliases in a authority for an Id .
IdList	getIdAliasesByAuthorityAndNamespace(Id id, String authority, String namespace)	Gets a list of Id aliases in a namespace for an Id .
IdList	getIds()	Gets all Ids .
IdList	getIdsByAuthority(String authority)	Gets Ids by the given authority.
IdList	getIdsByAuthorityAndNamespace(String authority, 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 Closeable

close

Methods inherited from interface OsidSession

close

Modifier and Type	Method	Description
void	close()	Close this session.

Methods inherited from interface OsidSession

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

Modifier and Type	Method	Description
Agent	getAuthenticatedAgent()	Gets the agent authenticated to this session.
Id	getAuthenticatedAgentId()	Gets the Id of the agent authenticated to this session.
BigDecimal	getClockRate()	Gets the rate of the service clock.
Date	getDate()	Gets the service date which may be the current date or the effective date in which this session exists.
Agent	getEffectiveAgent()	Gets the effective agent in use by this session.
Id	getEffectiveAgentId()	Gets the Id of the effective agent in use by this session.
Type	getFormatType()	Gets the DisplayText format Type preference in effect for this session.
Locale	getLocale()	Gets the locale indicating the localization preferences in effect for this session.
boolean	isAuthenticated()	Tests if an agent is authenticated to this session.
Transaction	startTransaction()	Starts a new transaction for this sesson.
boolean	supportsTransactions()	Tests for the availability of transactions.

Method Details

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 primary Id if the given Id Is an alias. Otherwise, the same Id is returned.

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 primary Ids if different from the given Ids . Otherwise, the same Ids are returned.

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(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(String authority,
 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 such as one is an alias of the other.

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,
 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,
 String authority,
 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.