Interface EntryLookupSession

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

EntryLookupSession is used to look up dictionary entries. This session includes the methods defined in the EntryRetrievalSession .

This session defines two views which offer differing behaviors when retrieving multiple objects.

  • comparative view: elements may be silently omitted or re-ordered
  • plenary view: provides a complete and ordered result set or is an error condition
  • federated view: entries are accessible from the dictionary associated with this session and any descedant dictionaries in the dictionary hierarchy
  • isolated view: entries are accessible from this dictionary only

Generally, the comparative view should be used for most applications as it permits operation even if there is data out of sync or there is an authorization block in a particular element.

  • Method Details

    • getDictionaryId

      Id getDictionaryId()
      Gets the Dictionary Id associated with this session.
      Returns:
      the Dictionary Id associated with this session
      Compliance:
      mandatory - This method must be implemented.

    • getDictionary

      Dictionary getDictionary() throws OperationFailedException, PermissionDeniedException
      Gets the Dictionary associated with this session.
      Returns:
      the Dictionary associated with this session
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • canLookupEntries

      boolean canLookupEntries()
      Tests if this user can perform Entry 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.

    • useComparativeEntryView

      void useComparativeEntryView()
      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.

    • usePlenaryEntryView

      void usePlenaryEntryView()
      A complete view of the Entry 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.

    • useFederatedDictionaryView

      void useFederatedDictionaryView()
      Federates the view for methods in this session. A federated view will include entries from descendant dictionaries in the dictionary hierarchy.
      Compliance:
      mandatory - This method is must be implemented.

    • useIsolatedDictionaryView

      void useIsolatedDictionaryView()
      Isolates the view for methods in this session. An isolated view restricts lookups to this dictionary only.
      Compliance:
      mandatory - This method is must be implemented.

    • getEntry

      Entry getEntry(Id entryId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the Entry specified by its Id . The identifier represents the union of the key, keyType and valueType.In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Entry may have a different Id than requested, such as the case where a duplicate Id was assigned to an Agency and retained for compatibility.
      Parameters:
      entryId - Id of the Entry
      Returns:
      the entry
      Throws:
      NotFoundException - entryId not found
      NullArgumentException - entryId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method is must be implemented.

    • getEntriesByIds

      EntryList getEntriesByIds(IdList entryIds) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets an EntryList 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 Entry elements may be omitted from the list and may present the elements in any order including returning a unique set.
      Parameters:
      entryIds - a list of Entry Ids
      Returns:
      the entry list
      Throws:
      NotFoundException - entryId not found
      NullArgumentException - entryIds is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method is must be implemented.

    • getEntriesByGenusType

      EntryList getEntriesByGenusType(Type entryGenusType) throws OperationFailedException, PermissionDeniedException
      Gets an EntryList corresponding to the given entry genus Type which does not include entries of genus types derived from the specified Type . In plenary mode, the returned list contains all known entries or an error results. Otherwise, the returned list may contain only those entries that are accessible through this session.
      Parameters:
      entryGenusType - an entry genus type
      Returns:
      the returned Entry list
      Throws:
      NullArgumentException - entryGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getEntriesByParentGenusType

      EntryList getEntriesByParentGenusType(Type entryGenusType) throws OperationFailedException, PermissionDeniedException
      Gets an EntryList corresponding to the given entry genus Type and include any additional entries with genus types derived from the specified Type . In plenary mode, the returned list contains all known entries or an error results. Otherwise, the returned list may contain only those entries that are accessible through this session.
      Parameters:
      entryGenusType - an entry genus type
      Returns:
      the returned Entry list
      Throws:
      NullArgumentException - entryGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getEntriesByRecordType

      EntryList getEntriesByRecordType(Type entryyRecordType) throws OperationFailedException, PermissionDeniedException
      Gets an EntryList containing the given entry record Type . In plenary mode, the returned list contains all known entries or an error results. Otherwise, the returned list may contain only those entries that are accessible through this session.
      Parameters:
      entryyRecordType - an entry record type
      Returns:
      the returned Entry list
      Throws:
      NullArgumentException - entryRecordType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getEntriesByKeyType

      EntryList getEntriesByKeyType(Type keyType) throws OperationFailedException, PermissionDeniedException
      Gets all the Dictionary entries matching the given key Type . 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 Entry elements may be omitted from the list and may present the elements in any order including returning a unique set.
      Parameters:
      keyType - the type of the key to match
      Returns:
      the list of entries matching keyType
      Throws:
      NullArgumentException - keyType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getEntriesByKeyTypeAndValueType

      EntryList getEntriesByKeyTypeAndValueType(Type keyType, Type valueType) throws OperationFailedException, PermissionDeniedException
      Gets all the Dictionary entries matching the given key and value Type . 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 Entry elements may be omitted from the list and may present the elements in any order including returning a unique set.
      Parameters:
      keyType - the type of the key to match
      valueType - the type of the value to match
      Returns:
      the list of entries matching keyType
      Throws:
      NullArgumentException - keyType or valueType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getEntriesByKeyAndKeyType

      EntryList getEntriesByKeyAndKeyType(Object key, Type keyType) throws OperationFailedException, PermissionDeniedException
      Gets all the Dictionary entries matching the given key and key Type . 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 Entry elements may be omitted from the list and may present the elements in any order including returning a unique set.
      Parameters:
      key - the key to match
      keyType - the type of the value to match
      Returns:
      the list of entries matching keyType
      Throws:
      NullArgumentException - key or keyType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getEntries

      EntryList getEntries() throws OperationFailedException, PermissionDeniedException
      Gets all Entry elements. In plenary mode, the returned list contains all known entries or an error results. Otherwise, the returned list may contain only those dictionaries that are accessible through this session.
      Returns:
      the list of entries
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.