org.osid.profile

Interface ProfileEntryLookupSession

All Superinterfaces:

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

public interface ProfileEntryLookupSession
extends OsidSession

This session defines methods to search and retrieve ProfileEntry mappings.

This lookup session defines two sets of views:

• isolated profile view: All profile methods in this session operate, retrieve and pertain to ProfileEntries defined explicitly in the current Profile. Using an isolated view is useful for managing ProfileEntries with the ProfileEntryAdminSession.
• federated profile view; All profile methods in this session operate, retrieve and pertain to all profile entries defined in this profile and any other entries implicitly available in this profile through profile inheritence.
• effective profile entry view: All profil eentry lookup methods return edges where the current dates falls in between the effective dates inclusive.
• any effective profile entry edge view: Profil eentries of any effective date are returned.
• explicit profile entry view: All profile methods in this session operate, retrieve and pertain to only those profile entries that have been explicitly defined and not derived from Resource groups.
• implicit profile entry view; All profile entry methods in this session operate, retrieve and pertain to all profile entries including those derived from Resource groups.
• explicit resource view: Only show profile entries explicitly mapped to the given resource when looking up profile entries by resource.
• implicit resource view: Include all profile entries related to the resource including profile entries using any agent of the resource.

The view methods such as useExplicitProfileEntryView() and useImplicitProfileEntryView() behave as a radio group and one should be selected before invoking any lookup methods.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupProfileEntries() Tests if this user can perform profile lookups.
ProfileEntry	getExplicitProfileEntry(Id profileEntryId) Gets the explicit ProfileEntry that generated the given implicit profile entry.
Profile	getProfile() Gets the Profile associated with this session.
ProfileEntryList	getProfileEntries() Geta all ProfileEntries.
ProfileEntryList	getProfileEntriesByGenusType(Type profileEntryGenusType) Gets a ProfileEntryList corresponding to the given profile entry genus Type which does not include profile entries of genus types derived from the specified Type.
ProfileEntryList	getProfileEntriesByIds(IdList profileEntryIds) Gets an ProfileEntryList corresponding to the given IdList.
ProfileEntryList	getProfileEntriesByParentGenusType(Type profileEntryGenusType) Gets a ProfileEntryList corresponding to the given profile entry genus Type and include profile entries of genus types derived from the specified Type.
ProfileEntryList	getProfileEntriesByRecordType(Type profileEntryRecordType) Gets a ProfileEntryList containing the given profile entry record Type.
ProfileEntryList	getProfileEntriesForAgent(Id agentId) Gets a list of ProfileEntries associated with a given agent.
ProfileEntryList	getProfileEntriesForAgentAndProfileItem(Id agentId, Id profileItemId) Gets a list of ProfileEntries associated for entries explicitly mapped to a given agent and profile item.
ProfileEntryList	getProfileEntriesForAgentAndProfileItemOnDate(Id agentId, Id profileItemId, DateTime from, DateTime to) Gets a ProfileEntryList for entries explicitly mapped to a given agent and profile item and effective during the entire given date range inclusive but not confined to the date range.
ProfileEntryList	getProfileEntriesForAgentOnDate(Id agentId, DateTime from, DateTime to) Gets a ProfileEntryList for the given agent and effective during the entire given date range inclusive but not confined to the date range.
ProfileEntryList	getProfileEntriesForProfileItem(Id profileItemId) Gets a ProfileEntryList for a given profile item.
ProfileEntryList	getProfileEntriesForProfileItemOnDate(Id profileItemId, DateTime from, DateTime to) Gets a ProfileEntryList for the given profile item and effective during the entire given date range inclusive but not confined to the date range.
ProfileEntryList	getProfileEntriesForResource(Id resourceId) Gets a list of ProfileEntries associated for entries related to a given resource.
ProfileEntryList	getProfileEntriesForResourceAndProfileItem(Id resourceId, Id profileItemId) Gets a list of ProfileEntries associated for entries explicitly mapped to a given resource and profile item.
ProfileEntryList	getProfileEntriesForResourceAndProfileItemOnDate(Id resourceId, Id profileItemId, DateTime from, DateTime to) Gets a ProfileEntryList for entries explicitly mapped to a given resource and profile item and effective during the entire given date range inclusive but not confined to the date range.
ProfileEntryList	getProfileEntriesForResourceOnDate(Id resourceId, DateTime from, DateTime to) Gets a ProfileEntryList for entries explicitly mapped to a given resource and effective during the entire given date range inclusive but not confined to the date range.
ProfileEntryList	getProfileEntriesOnDate(DateTime from, DateTime to) Gets a ProfileEntryList effective date during the entire given date range inclusive but not confined to the date range.
ProfileEntry	getProfileEntry(Id profileEntryId) Gets the ProfileEntry specified by its Id.
Id	getProfileId() Gets the Profile Id associated with this session.
void	useAnyEffectiveProfileEntryView() All profile entries of any effective dates are returned by all methods in this session.
void	useComparativeProfileEntryView() 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	useEffectiveProfileEntryView() Only profile entries whose effective dates are current are returned by methods in this session.
void	useExplicitProfileEntryView() Sets the view for methods in this session to explicit profile entries.
void	useExplicitResourceView() Only include profile entries explicitly mapped to the given resource when looking up profile entries by resource.
void	useFederatedProfileView() Federates the view for methods in this session.
void	useImplicitProfileEntryView() Sets the view for methods in this session to implicit profile entries.
void	useImplicitResourceView() Include profile entries of any agent of a resource when looking up profile entries by resource.
void	useIsolatedProfileView() Isolates the view for methods in this session.
void	usePlenaryProfileEntryView() A complete view of the ProfileEntry returns is desired.

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

getProfileId

Id getProfileId()

Gets the Profile Id associated with this session.

Returns:

the Profile Id associated with this session

Compliance:

mandatory - This method must be implemented.

getProfile

Profile getProfile()
                   throws OperationFailedException,
                          PermissionDeniedException

Gets the Profile associated with this session.

Returns:

the Profile associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canLookupProfileEntries

boolean canLookupProfileEntries()

Tests if this user can perform profile 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 to unauthorized users.

Returns:

false if lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeProfileEntryView

void useComparativeProfileEntryView()

The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error. This view is used when greater interoperability is desired at the expense of precision.

Compliance:

mandatory - This method is must be implemented.

usePlenaryProfileEntryView

void usePlenaryProfileEntryView()

A complete view of the ProfileEntry 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.

Compliance:

mandatory - This method is must be implemented.

useFederatedProfileView

void useFederatedProfileView()

Federates the view for methods in this session. A federated view will include profile entries in profiles which are children of this profile in the profile hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedProfileView

void useIsolatedProfileView()

Isolates the view for methods in this session. An isolated view restricts lookups to this profile only.

Compliance:

mandatory - This method is must be implemented.

useEffectiveProfileEntryView

void useEffectiveProfileEntryView()

Only profile entries whose effective dates are current are returned by methods in this session.

Compliance:

mandatory - This method is must be implemented.

useAnyEffectiveProfileEntryView

void useAnyEffectiveProfileEntryView()

All profile entries of any effective dates are returned by all methods in this session.

Compliance:

mandatory - This method is must be implemented.

useImplicitProfileEntryView

void useImplicitProfileEntryView()

Sets the view for methods in this session to implicit profile entries. An implicit view will include profile entries derived from other entries as a result of the ProfileItem or Resource hierarchies. This method is the opposite of explicitProfileEntryView().

Compliance:

mandatory - This method is must be implemented.

useExplicitProfileEntryView

void useExplicitProfileEntryView()

Sets the view for methods in this session to explicit profile entries. An explicit view includes only those profile entries that were explicitly defined and not implied. This method is the opposite of implicitProfileEntryView().

Compliance:

mandatory - This method is must be implemented.

useImplicitResourceView

void useImplicitResourceView()

Include profile entries of any agent of a resource when looking up profile entries by resource.

Compliance:

mandatory - This method is must be implemented.

useExplicitResourceView

void useExplicitResourceView()

Only include profile entries explicitly mapped to the given resource when looking up profile entries by resource.

Compliance:

mandatory - This method is must be implemented.

getProfileEntry

ProfileEntry getProfileEntry(Id profileEntryId)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Gets the ProfileEntry specified by its Id. In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned ProfileEntry may have a different Id than requested, such as the case where a duplicate Id was assigned to an ProfileEntry and retained for compatibility. In effective mode, profile entries are returned that are currently effective. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

profileEntryId - the Id of the ProfileEntry to retrieve

Returns:

the returned ProfileEntry

Throws:

NotFoundException - no ProfileEntry found with the given Id

NullArgumentException - profileEntryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getProfileEntriesByIds

ProfileEntryList getProfileEntriesByIds(IdList profileEntryIds)
                                        throws NotFoundException,
                                               OperationFailedException,
                                               PermissionDeniedException

Gets an ProfileEntryList corresponding to the given IdList. In plenary mode, the returned list contains all of the entries 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 ProfileEntries may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, profile entries are returned that are currently effective. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

profileEntryIds - the list of Ids to retrieve

Returns:

the returned ProfileEntry list

Throws:

NotFoundException - an Id was not found

NullArgumentException - profileEntryIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getProfileEntriesByGenusType

ProfileEntryList getProfileEntriesByGenusType(Type profileEntryGenusType)
                                              throws OperationFailedException,
                                                     PermissionDeniedException

Gets a ProfileEntryList corresponding to the given profile entry genus Type which does not include profile entries of genus types derived from the specified Type. In plenary mode, the returned list contains all known profile entries or an error results. Otherwise, the returned list may contain only those profile ebtries that are accessible through this session. In effective mode, profile entries are returned that are currently effective. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

profileEntryGenusType - a profile entry genus type

Returns:

the returned ProfileEntry list

Throws:

NullArgumentException - profileEntryGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

getProfileEntriesByParentGenusType

ProfileEntryList getProfileEntriesByParentGenusType(Type profileEntryGenusType)
                                                    throws OperationFailedException,
                                                           PermissionDeniedException

Gets a ProfileEntryList corresponding to the given profile entry genus Type and include profile entries of genus types derived from the specified Type. In plenary mode, the returned list contains all known profile entries or an error results. Otherwise, the returned list may contain only those profile ebtries that are accessible through this session. In effective mode, profile entries are returned that are currently effective. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

profileEntryGenusType - a profile entry genus type

Returns:

the returned ProfileEntry list

Throws:

NullArgumentException - profileEntryGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

getProfileEntriesByRecordType

ProfileEntryList getProfileEntriesByRecordType(Type profileEntryRecordType)
                                               throws OperationFailedException,
                                                      PermissionDeniedException

Gets a ProfileEntryList containing the given profile entry record Type. In plenary mode, the returned list contains all known profile entries or an error results. Otherwise, the returned list may contain only those profile entries that are accessible through this session. In effective mode, profile entries are returned that are currently effective. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

profileEntryRecordType - a profile entry record type

Returns:

the returned ProfileEntry list

Throws:

NullArgumentException - profileEntryRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

getProfileEntriesOnDate

ProfileEntryList getProfileEntriesOnDate(DateTime from,
                                       DateTime to)
                                         throws OperationFailedException,
                                                PermissionDeniedException

Gets a ProfileEntryList effective date during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known authorizations or an error results. Otherwise, the returned list may contain only those authorizations that are accessible through this session. In effective mode, profile entries are returned that are currently effective in addition to being effective durting the date range. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

from - starting date

to - ending date

Returns:

the returned ProfileEntry list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

getProfileEntriesForResource

ProfileEntryList getProfileEntriesForResource(Id resourceId)
                                              throws OperationFailedException,
                                                     PermissionDeniedException

Gets a list of ProfileEntries associated for entries related to a given resource. In explicit resource view, only include entries with the given resource. In implicit resource view, also include entries using any agent of the given resource. In plenary mode, the returned list contains all known profile entries or an error results. Otherwise, the returned list may contain only those profile ebtries that are accessible through this session. In effective mode, profile entries are returned that are currently effective. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

resourceId - a resource Id

Returns:

the returned ProfileEntry list

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getProfileEntriesForResourceOnDate

ProfileEntryList getProfileEntriesForResourceOnDate(Id resourceId,
                                                  DateTime from,
                                                  DateTime to)
                                                    throws OperationFailedException,
                                                           PermissionDeniedException

Gets a ProfileEntryList for entries explicitly mapped to a given resource and effective during the entire given date range inclusive but not confined to the date range. In explicit resource view, only include entries with the given resource. In implicit resource view, also include entries using any agent of the given resource. In plenary mode, the returned list contains all known authorizations or an error results. Otherwise, the returned list may contain only those authorizations that are accessible through this session. In effective mode, profile entries are returned that are currently effective. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

resourceId - a resource Id

from - starting date

to - ending date

Returns:

the returned ProfileEntry list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - resourceId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

getProfileEntriesForAgent

ProfileEntryList getProfileEntriesForAgent(Id agentId)
                                           throws OperationFailedException,
                                                  PermissionDeniedException

Gets a list of ProfileEntries associated with a given agent. In plenary mode, the returned list contains all known profile entries or an error results. Otherwise, the returned list may contain only those profile ebtries that are accessible through this session. In effective mode, profile entries are returned that are currently effective. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

agentId - an agent Id

Returns:

the returned ProfileEntry list

Throws:

NullArgumentException - agentId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getProfileEntriesForAgentOnDate

ProfileEntryList getProfileEntriesForAgentOnDate(Id agentId,
                                               DateTime from,
                                               DateTime to)
                                                 throws OperationFailedException,
                                                        PermissionDeniedException

Gets a ProfileEntryList for the given agent and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known authorizations or an error results. Otherwise, the returned list may contain only those authorizations that are accessible through this session. In effective mode, profile entries are returned that are currently effective in addition to being effective during the date range. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

agentId - an agent Id

from - starting date

to - ending date

Returns:

the returned ProfileEntry list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - agentId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

getProfileEntriesForProfileItem

ProfileEntryList getProfileEntriesForProfileItem(Id profileItemId)
                                                 throws OperationFailedException,
                                                        PermissionDeniedException

Gets a ProfileEntryList for a given profile item. In plenary mode, the returned list contains all known profile entries or an error results. Otherwise, the returned list may contain only those profile entries that are accessible through this session. In effective mode, profile entries are returned that are currently effective. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

profileItemId - a profile item Id

Returns:

the returned ProfileEntry list

Throws:

NullArgumentException - profileItemId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getProfileEntriesForProfileItemOnDate

ProfileEntryList getProfileEntriesForProfileItemOnDate(Id profileItemId,
                                                     DateTime from,
                                                     DateTime to)
                                                       throws OperationFailedException,
                                                              PermissionDeniedException

Gets a ProfileEntryList for the given profile item and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known authorizations or an error results. Otherwise, the returned list may contain only those authorizations that are accessible through this session. In effective mode, profile entries are returned that are currently effectiv in addition to being effective during the date range. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

profileItemId - a profile item Id

from - starting date

to - ending date

Returns:

the returned ProfileEntry list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - profileItemId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

getProfileEntriesForResourceAndProfileItem

ProfileEntryList getProfileEntriesForResourceAndProfileItem(Id resourceId,
                                                          Id profileItemId)
                                                            throws OperationFailedException,
                                                                   PermissionDeniedException

Gets a list of ProfileEntries associated for entries explicitly mapped to a given resource and profile item. In explicit resource view, only include entries with the given resource. In implicit resource view, also include entries using any agent of the given resource. In plenary mode, the returned list contains all known profile entries or an error results. Otherwise, the returned list may contain only those profile ebtries that are accessible through this session. In effective mode, profile entries are returned that are currently effective. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

resourceId - a resource Id

profileItemId - a profile item Id

Returns:

the returned ProfileEntry list

Throws:

NullArgumentException - resourceId or profileItemId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getProfileEntriesForResourceAndProfileItemOnDate

ProfileEntryList getProfileEntriesForResourceAndProfileItemOnDate(Id resourceId,
                                                                Id profileItemId,
                                                                DateTime from,
                                                                DateTime to)
                                                                  throws OperationFailedException,
                                                                         PermissionDeniedException

Gets a ProfileEntryList for entries explicitly mapped to a given resource and profile item and effective during the entire given date range inclusive but not confined to the date range. In explicit resource view, only include entries with the given resource. In implicit resource view, also include entries using any agent of the given resource. In plenary mode, the returned list contains all known authorizations or an error results. Otherwise, the returned list may contain only those authorizations that are accessible through this session. In effective mode, profile entries are returned that are currently effective. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

resourceId - a resource Id

profileItemId - a profile item Id

from - starting date

to - ending date

Returns:

the returned ProfileEntry list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - resourceId, profileItemId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

getProfileEntriesForAgentAndProfileItem

ProfileEntryList getProfileEntriesForAgentAndProfileItem(Id agentId,
                                                       Id profileItemId)
                                                         throws OperationFailedException,
                                                                PermissionDeniedException

Gets a list of ProfileEntries associated for entries explicitly mapped to a given agent and profile item. In plenary mode, the returned list contains all known profile entries or an error results. Otherwise, the returned list may contain only those profile ebtries that are accessible through this session. In effective mode, profile entries are returned that are currently effective. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

agentId - an agent Id

profileItemId - a profile item Id

Returns:

the returned ProfileEntry list

Throws:

NullArgumentException - agentId or profileItemId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getProfileEntriesForAgentAndProfileItemOnDate

ProfileEntryList getProfileEntriesForAgentAndProfileItemOnDate(Id agentId,
                                                             Id profileItemId,
                                                             DateTime from,
                                                             DateTime to)
                                                               throws OperationFailedException,
                                                                      PermissionDeniedException

Gets a ProfileEntryList for entries explicitly mapped to a given agent and profile item and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known authorizations or an error results. Otherwise, the returned list may contain only those authorizations that are accessible through this session. In effective mode, profile entries are returned that are currently effective. In any effective mode, effective profile entries and those currently expired are returned.

Parameters:

agentId - an agent Id

profileItemId - a profile item Id

from - starting date

to - ending date

Returns:

the returned ProfileEntry list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - agentId, profileItemId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

getExplicitProfileEntry

ProfileEntry getExplicitProfileEntry(Id profileEntryId)
                                     throws NotFoundException,
                                            OperationFailedException,
                                            PermissionDeniedException

Gets the explicit ProfileEntry that generated the given implicit profile entry. If the given ProfileEntry is explicit, then the same ProfileEntry is returned.

Parameters:

profileEntryId - a profile entry

Returns:

the explicit ProfileEntry

Throws:

NotFoundException - profileEntryId is not found

NullArgumentException - profileEntryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getProfileEntries

ProfileEntryList getProfileEntries()
                                   throws OperationFailedException,
                                          PermissionDeniedException

Geta all ProfileEntries. In plenary mode, the returned list contains all known profile entries or an error results. Otherwise, the returned list may contain only those profile ebtries that are accessible through this session. In effective mode, profile entries are returned that are currently effective. In any effective mode, effective profile entries and those currently expired are returned.

Returns:

a list of ProfileEntries

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.