Interface ProfileEntryLookupSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, OsidSession
public interface ProfileEntryLookupSession extends OsidSession

This session defines methods to search and retrieve ProfileEntries .

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 Details

    • 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.