public interface RealmLookupSession extends OsidSession
This session provides methods for retrieving Realm
objects. The Realm
represents a collection of
Persons.
This session defines views that offer differing behaviors when retrieving multiple objects.
Modifier and Type | Method and Description |
---|---|
boolean |
canLookupRealms()
Tests if this user can perform
Realm lookups. |
Realm |
getRealm(Id realmId)
Gets the
Realm specified by its Id. |
RealmList |
getRealms()
Gets all
Realms. |
RealmList |
getRealmsByGenusType(Type realmGenusType)
Gets a
RealmList corresponding to the given realm genus
Type which does not include realms of genus types
derived from the specified Type. |
RealmList |
getRealmsByIds(IdList realmIds)
Gets a
RealmList corresponding to the given
IdList. |
RealmList |
getRealmsByParentGenusType(Type realmGenusType)
Gets a
RealmList corresponding to the given realm genus
Type and include any additional realms with genus types
derived from the specified Type. |
RealmList |
getRealmsByProvider(Id resourceId)
Gets a
RealmList for the given provider. |
RealmList |
getRealmsByRecordType(Type realmRecordType)
Gets a
RealmList containing the given realm record
Type. |
void |
useComparativeRealmView()
The returns from the lookup methods may omit or translate elements
based on this session, such as authorization, and not result in an
error.
|
void |
usePlenaryRealmView()
A complete view of the
Realm returns is desired. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
boolean canLookupRealms()
Realm
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 not offer lookup operations to unauthorized
users. false
if lookup methods are not authorized,
true
otherwisemandatory
- This method must be implemented. void useComparativeRealmView()
mandatory
- This method is must be implemented. void usePlenaryRealmView()
Realm
returns is desired.
Methods will return what is requested or result in an error. This view
is used when greater precision is desired at the expense of
interoperability.mandatory
- This method is must be implemented. Realm getRealm(Id realmId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Realm
specified by its Id.
In
plenary mode, the exact Id
is found or a
NOT_FOUND
results. Otherwise, the returned Realm
may have a different Id
than requested, such as
the case where a duplicate Id
was assigned to a
Realm
and retained for compatibility.realmId
- Id
of the Realm
NotFoundException
- realmId
not foundNullArgumentException
- realmId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method is must be implemented. RealmList getRealmsByIds(IdList realmIds) throws NotFoundException, OperationFailedException, PermissionDeniedException
RealmList
corresponding to the given
IdList.
In plenary mode, the returned list contains all of the
realms specified in the Id
list, in the order of the
list, including duplicates, or an error results if an Id
in the supplied list is not found or inaccessible. Otherwise,
inaccessible Realms
may be omitted from the list and
may present the elements in any order including returning a unique
set.realmIds
- the list of Ids
to retrieve Realm
listNotFoundException
- an Id was
not foundNullArgumentException
- realmIds
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RealmList getRealmsByGenusType(Type realmGenusType) throws OperationFailedException, PermissionDeniedException
RealmList
corresponding to the given realm genus
Type
which does not include realms of genus types
derived from the specified Type.
In plenary mode, the
returned list contains all known realms or an error results.
Otherwise, the returned list may contain only those realms that are
accessible through this session.realmGenusType
- a realm genus type Realm
listNullArgumentException
- realmGenusType
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RealmList getRealmsByParentGenusType(Type realmGenusType) throws OperationFailedException, PermissionDeniedException
RealmList
corresponding to the given realm genus
Type
and include any additional realms with genus types
derived from the specified Type.
In plenary mode, the
returned list contains all known realms or an error results.
Otherwise, the returned list may contain only those realms that are
accessible through this session.realmGenusType
- a realm genus type Realm
listNullArgumentException
- realmGenusType
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RealmList getRealmsByRecordType(Type realmRecordType) throws OperationFailedException, PermissionDeniedException
RealmList
containing the given realm record
Type.
In plenary mode, the returned list contains all
known realms or an error results. Otherwise, the returned list may
contain only those realms that are accessible through this session.realmRecordType
- a realm record type Realm
listNullArgumentException
- realmRecordType
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RealmList getRealmsByProvider(Id resourceId) throws OperationFailedException, PermissionDeniedException
RealmList
for the given provider. In plenary
mode, the returned list contains all known realms or an error results.
Otherwise, the returned list may contain only those realms that are
accessible through this session.resourceId
- a resource Id Realm
listNullArgumentException
- resourceId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RealmList getRealms() throws OperationFailedException, PermissionDeniedException
Realms.
In plenary mode, the returned list
contains all known realms or an error results. Otherwise, the returned
list may contain only those realms that are accessible through this
session. Realms
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.