Interface GroupHierarchySession

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

This session provides a hierarchical view of resource groups. Each node in the hierarchy is a unique Resource . The hierarchy may be traversed recursively to establish the tree structure through getParentResources() and getChildResources() . To relate these Ids to another OSID, getResourceNodes() can be used for retrievals that can be used for bulk lookups in other OSIDs.

A user may not be authorized to traverse the entire hierarchy. Parts of the hierarchy may be made invisible through omission from the returns of getParentResources() or getChildResources() in lieu of a PERMISSION_DENIED error that may disrupt the traversal through authorized pathways.

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

  • comparative view: resource elements may be silently omitted or re-ordered
  • plenary view: provides a complete set or is an error condition

  • Method Details

    • getBinId

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

    • getBin

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

    • canAccessGroupHierarchy

      boolean canAccessGroupHierarchy()
      Tests if this user can perform hierarchy queries. 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 hierarchy traversal methods are not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • useComparativeResourceView

      void useComparativeResourceView()
      The returns from the group 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.

    • usePlenaryResourceView

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

    • useFederatedBinView

      void useFederatedBinView()
      Federates the view for methods in this session. A federated view will include resources in bins which are children of this bin in the bin hierarchy.
      Compliance:
      mandatory - This method is must be implemented.

    • useIsolatedBinView

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

    • isMemberOfGroup

      boolean isMemberOfGroup(Id groupId, Id resourceId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Tests if a resource Id is a member of a group either directly or indirectly through nested groups.
      Parameters:
      groupId - a resource group Id
      resourceId - the Id of a resource
      Returns:
      true if this resourceId is a member of groupId , f alse otherwise
      Throws:
      NotFoundException - groupId is not found
      NullArgumentException - groupId or resourceId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.
      Notes:
      If - {@code resourceId} not found return {@code false} .

    • getResourceNodeIds

      Node getResourceNodeIds(Id resourceId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets a portion of the hierarchy for the given resource group.
      Parameters:
      resourceId - the Id to query
      ancestorLevels - the maximum number of ancestor levels to include. A value of 0 returns no parents in the node.
      descendantLevels - the maximum number of descendant levels to include. A value of 0 returns no children in the node.
      includeSiblings - true to include the siblings of the given node, false to omit the siblings
      Returns:
      a resource node
      Throws:
      NotFoundException - resourceId is not found
      NullArgumentException - resourceId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getResourceNodes

      ResourceNode getResourceNodes(Id resourceId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets a portion of the hierarchy for the given resource group.
      Parameters:
      resourceId - the Id to query
      ancestorLevels - the maximum number of ancestor levels to include. A value of 0 returns no parents in the node.
      descendantLevels - the maximum number of descendant levels to include. A value of 0 returns no children in the node.
      includeSiblings - true to include the siblings of the given node, false to omit the siblings
      Returns:
      a resource node
      Throws:
      NotFoundException - resourceId is not found
      NullArgumentException - resourceId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.