public interface FamilyHierarchySession extends OsidSession
This session defines methods for traversing a hierarchy of
Family
objects. Each node in the hierarchy is a unique
Family.
The hierarchy may be traversed recursively to establish
the tree structure through getParentFamilies()
and
getChildFamilies().
To relate these Ids
to another
OSID, getFamilyNodes()
can be used for retrievals that can
be used for bulk lookups in other OSIDs. Any Family
available in the Relationship OSID is known to this hierarchy but does not
appear in the hierarchy traversal until added as a root node or a child of
another node.
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 getParentFamilies()
or getChildFamilies()
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.
Modifier and Type | Method and Description |
---|---|
boolean |
canAccessFamilyHierarchy()
Tests if this user can perform hierarchy queries.
|
FamilyList |
getChildFamilies(Id familyId)
Gets the child families of the given
id. |
IdList |
getChildFamilyIds(Id familyId)
Gets the child
Ids of the given family. |
Hierarchy |
getFamilyHierarchy()
Gets the hierarchy associated with this session.
|
Id |
getFamilyHierarchyId()
Gets the hierarchy
Id associated with this session. |
Node |
getFamilyNodeIds(Id familyId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given family.
|
FamilyNode |
getFamilyNodes(Id familyId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given family.
|
FamilyList |
getParentFamilies(Id familyId)
Gets the parent families of the given
id. |
IdList |
getParentFamilyIds(Id familyId)
Gets the parent
Ids of the given family. |
FamilyList |
getRootFamilies()
Gets the root families in the family hierarchy.
|
IdList |
getRootFamilyIds()
Gets the root family
Ids in this hierarchy. |
boolean |
hasChildFamilies(Id familyId)
Tests if a family has any children.
|
boolean |
hasParentFamilies(Id familyId)
Tests if the
Family has any parents. |
boolean |
isAncestorOfFamily(Id id,
Id familyId)
Tests if an
Id is an ancestor of a family. |
boolean |
isChildOfFamily(Id id,
Id familyId)
Tests if a family is a direct child of another.
|
boolean |
isDescendantOfFamily(Id id,
Id familyId)
Tests if an
Id is a descendant of a family. |
boolean |
isParentOfFamily(Id id,
Id familyId)
Tests if an
Id is a direct parent of a family. |
void |
useComparativeFamilyView()
The returns from the family methods may omit or translate elements
based on this session, such as authorization, and not result in an
error.
|
void |
usePlenaryFamilyView()
A complete view of the
Family returns is desired. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getFamilyHierarchyId()
Id
associated with this session. Id
associated with this sessionmandatory
- This method must be implemented. Hierarchy getFamilyHierarchy() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canAccessFamilyHierarchy()
PERMISSION_DENIED.
This is intended as a hint to an
an application that may not offer hierrachy traversal operations to
unauthorized users. false
if hierarchy traversal methods are not
authorized, true
otherwisemandatory
- This method must be implemented. void useComparativeFamilyView()
mandatory
- This method is must be implemented. void usePlenaryFamilyView()
Family
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. IdList getRootFamilyIds() throws OperationFailedException, PermissionDeniedException
Ids
in this hierarchy. Ids
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. FamilyList getRootFamilies() throws OperationFailedException, PermissionDeniedException
Ids
are known to the
hierarchy, an orphan does not appear in the hierarchy unless
explicitly added as a root node or child of another node.OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method is must be implemented. boolean hasParentFamilies(Id familyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Family
has any parents.familyId
- the Id
of a family true
if the family has parents, false
otherwiseNotFoundException
- familyId
is not
foundNullArgumentException
- familyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isParentOfFamily(Id id, Id familyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a direct parent of a family.id
- an Id
familyId
- the Id
of a family true
if this id
is a parent of
familyId,
false
otherwiseNotFoundException
- familyId
is not
foundNullArgumentException
- id
or
familyId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getParentFamilyIds(Id familyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given family.familyId
- the Id
of a family Ids
of the familyNotFoundException
- familyId
is not
foundNullArgumentException
- familyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. FamilyList getParentFamilies(Id familyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id.
familyId
- the Id
of the Family
to
query id
NotFoundException
- a Family
identified
by Id is
not foundNullArgumentException
- familyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isAncestorOfFamily(Id id, Id familyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is an ancestor of a family.id
- an Id
familyId
- the Id
of a family true
if this id
is an ancestor
of familyId,
false
otherwiseNotFoundException
- familyId
is not
foundNullArgumentException
- id
or
familyId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
boolean hasChildFamilies(Id familyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
familyId
- the Id
of a family true
if the familyId
has
children, false
otherwiseNotFoundException
- familyId
is not
foundNullArgumentException
- familyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isChildOfFamily(Id id, Id familyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id
- an Id
familyId
- the Id
of a family true
if the id
is a child of
familyId,
false
otherwiseNotFoundException
- familyId
is not
foundNullArgumentException
- id
or
familyId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getChildFamilyIds(Id familyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given family.familyId
- the Id
to queryNotFoundException
- familyId
is not
foundNullArgumentException
- familyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. FamilyList getChildFamilies(Id familyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id.
familyId
- the Id
of the Family
to
query id
NotFoundException
- a Family
identified
by Id is
not foundNullArgumentException
- familyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isDescendantOfFamily(Id id, Id familyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a descendant of a family.id
- an Id
familyId
- the Id
of a family true
if the id
is a descendant
of the familyId,
false
otherwiseNotFoundException
- familyId
is not
foundNullArgumentException
- id
or
familyId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
is not found return false.
Node getFamilyNodeIds(Id familyId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
familyId
- the Id
to queryancestorLevels
- 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 siblingsNotFoundException
- familyId
is not
foundNullArgumentException
- familyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. FamilyNode getFamilyNodes(Id familyId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
familyId
- the Id
to queryancestorLevels
- 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 siblingsNotFoundException
- familyId
is not
foundNullArgumentException
- familyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.