OSID Logo
OSID Specifications
topology path package
Version 3.0.0
Release Candidate Preview
Interfaceosid.topology.path.PathLookupSession
Implementsosid.OsidSession
Description

This session provides methods for retrieving Path objects.

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

  • comparative view: elements may be silently omitted or re-ordered
  • plenary view: provides a complete set or is an error condition
  • isolated graph view: All path methods in this session operate, retrieve and pertain to paths defined explicitly in the current graph. Using an isolated view is useful for managing Paths with the PathAdminSession.
  • federated graph view: All path methods in this session operate, retrieve and pertain to all paths defined in this graph and any other paths implicitly available in this graph through graph inheritence.
  • effective path view: All path lookup methods return paths where the current dates falls in between the effective dates inclusive.
  • any effective path view: Paths of any effective date are returned.

Generally, the comparative view should be used for most applications as it permits operation even if there is data that cannot be accessed. The methods useFederatedGraphView() and useIsolatedGraphView() behave as a radio group and one should be selected before invoking any lookup methods.

MethodgetGraphId
Description

Gets the Graph Id associated with this session.

Returnosid.id.Idthe Graph Id associated with this session
CompliancemandatoryThis method must be implemented.
MethodgetGraph
Description

Gets the Graph associated with this session.

Returnosid.topology.Graphthe graph
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodcanLookupPaths
Description

Tests if this user can perform Path 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.

Returnboolean false if lookup methods are not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethoduseComparativePathView
Description

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.

CompliancemandatoryThis method is must be implemented.
MethodusePlenaryPathView
Description

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

CompliancemandatoryThis method is must be implemented.
MethoduseFederatedGraphView
Description

Federates the view for methods in this session. A federated view will include paths in graphs which are children of this graph in the graph hierarchy.

CompliancemandatoryThis method is must be implemented.
MethoduseIsolatedGraphView
Description

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

CompliancemandatoryThis method is must be implemented.
MethoduseEffectivePathView
Description

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

CompliancemandatoryThis method is must be implemented.
MethoduseAnyEffectivePathView
Description

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

CompliancemandatoryThis method is must be implemented.
MethodgetPath
Description

Gets the Path specified by its Id.

In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Path may have a different Id than requested, such as the case where a duplicate Id was assigned to a Path and retained for compatibility.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdpathId Id of the Path
Returnosid.topology.path.Paththe path
ErrorsNOT_FOUND pathId not found
NULL_ARGUMENT pathId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method is must be implemented.
MethodgetPathsByIds
Description

Gets a PathList corresponding to the given IdList.

In plenary mode, the returned list contains all of the paths 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 Paths may be omitted from the list and may present the elements in any order including returning a unique set.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdListpathIdsthe list of Ids to retrieve
Returnosid.topology.path.PathListthe returned Path list
ErrorsNOT_FOUNDan Id was not found
NULL_ARGUMENT pathIds is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsByGenusType
Description

Gets a PathList corresponding to the given path genus Type which does not include paths of genus types derived from the specified Type.

In plenary mode, the returned list contains all known paths or an error results. Otherwise, the returned list may contain only those paths that are accessible through this session.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.type.TypepathGenusTypea path genus type
Returnosid.topology.path.PathListthe returned Path list
ErrorsNULL_ARGUMENT pathGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsByParentGenusType
Description

Gets a PathList corresponding to the given path genus Type and include any additional paths with genus types derived from the specified Type.

In plenary mode, the returned list contains all known paths or an error results. Otherwise, the returned list may contain only those paths that are accessible through this session.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.type.TypepathGenusTypea path genus type
Returnosid.topology.path.PathListthe returned Path list
ErrorsNULL_ARGUMENT pathGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsByRecordType
Description

Gets a PathList containing the given path record Type.

In plenary mode, the returned list contains all known paths or an error results. Otherwise, the returned list may contain only those paths that are accessible through this session.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.type.TypepathRecordTypea path record type
Returnosid.topology.path.PathListthe returned Path list
ErrorsNULL_ARGUMENT pathRecordType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsOnDate
Description

Gets a PathList effective during the entire given date range inclusive but not confined to the date range.

In plenary mode, the returned list contains all known paths or an error results. Otherwise, the returned list may contain only those paths that are accessible through this session.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.path.PathListthe returned Path list
ErrorsINVALID_ARGUMENT from Is greater than to
NULL_ARGUMENT from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsByGenusTypeOnDate
Description

Gets a PathList of a genus type 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 paths or an error results. Otherwise, the returned list may contain only those paths that are accessible through this session.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.type.TypepathGenusTypea path genus type
osid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.path.PathListthe returned Path list
ErrorsINVALID_ARGUMENT edgeGenusType, from Is greater than to
NULL_ARGUMENT from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsForStartingNode
Description

Gets a PathList starting from the given Node.

In plenary mode, the returned list contains all of the paths, or an error results if a path connected to the node is not found or inaccessible. Otherwise, inaccessible Paths may be omitted from the list.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdnodeIda node Id
Returnosid.topology.path.PathListthe returned Path list
ErrorsNULL_ARGUMENT nodeId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsForStartingNodeOnDate
Description

Gets a PathList effective during the entire given date range inclusive but not confined to the date range.

In plenary mode, the returned list contains all known paths or an error results. Otherwise, the returned list may contain only those paths that are accessible through this session.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdnodeIda node Id
osid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.path.PathListthe returned Path list
ErrorsINVALID_ARGUMENT from Is greater than to
NULL_ARGUMENT nodeId, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsByGenusTypeForStartingNode
Description

Gets a PathList starting from the given Node and path genus Type including any genus Types derived from the given genus Type.

In plenary mode, the returned list contains all of the paths, or an error results if a path connected to the node is not found or inaccessible. Otherwise, inaccessible Paths may be omitted from the list.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdnodeIda node Id
osid.type.TypepathGenusTypea path genus type
Returnosid.topology.path.PathListthe returned Path list
ErrorsNULL_ARGUMENT nodeId is or pathGenusType null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsByGenusTypeForStartingNodeOnDate
Description

Gets a PathList of the given genus type 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 paths or an error results. Otherwise, the returned list may contain only those paths that are accessible through this session.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdnodeIda node Id
osid.type.TypepathGenusTypea path genus type
osid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.path.PathListthe returned Path list
ErrorsINVALID_ARGUMENT from Is greater than to
NULL_ARGUMENT nodeId, pathGenusType, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsForEndingNode
Description

Gets a PathList ending at the given Node.

In plenary mode, the returned list contains all of the paths, or an error results if a path connected to the node is not found or inaccessible. Otherwise, inaccessible Paths may be omitted from the list.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdnodeIda node Id
Returnosid.topology.path.PathListthe returned Path list
ErrorsNULL_ARGUMENT nodeId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsForEndingNodeOnDate
Description

Gets a PathList effective during the entire given date range inclusive but not confined to the date range.

In plenary mode, the returned list contains all known paths or an error results. Otherwise, the returned list may contain only those paths that are accessible through this session.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdnodeIda node Id
osid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.path.PathListthe returned Path list
ErrorsINVALID_ARGUMENT from Is greater than to
NULL_ARGUMENT nodeId, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsByGenusTypeForEndingNode
Description

Gets a PathList ending at the given Node and path genus Type including any genus Types derived from the given genus Type.

In plenary mode, the returned list contains all of the paths, or an error results if a path connected to the node is not found or inaccessible. Otherwise, inaccessible Paths may be omitted from the list.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdnodeIda node Id
osid.type.TypepathGenusTypea path genus type
Returnosid.topology.path.PathListthe returned Path list
ErrorsNULL_ARGUMENT nodeId or pathGenusType null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsByGenusTypeForEndingNodeOnDate
Description

Gets a PathList of the given genus type 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 paths or an error results. Otherwise, the returned list may contain only those paths that are accessible through this session.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdnodeIda node Id
osid.type.TypepathGenusTypea path genus type
osid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.path.PathListthe returned Path list
ErrorsINVALID_ARGUMENT from Is greater than to
NULL_ARGUMENT nodeId, pathGenusType, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsForNodes
Description

Gets a PathList between to the two given Nodes.

In plenary mode, the returned list contains all of the paths, or an error results if a path connected to the node is not found or inaccessible. Otherwise, inaccessible Paths may be omitted from the list.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdstartingNodeIdstarting node Id
osid.id.IdendingNodeIdending node Id
Returnosid.topology.path.PathListthe returned Path list
ErrorsNULL_ARGUMENT startingNodeId or endingNodeId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsForNodesOnDate
Description

Gets a PathList effective during the entire given date range inclusive but not confined to the date range.

In plenary mode, the returned list contains all known paths or an error results. Otherwise, the returned list may contain only those paths that are accessible through this session.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdstartingNodeIdstarting node Id
osid.id.IdendingNodeIdending node Id
osid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.path.PathListthe returned Path list
ErrorsINVALID_ARGUMENT from Is greater than to
NULL_ARGUMENT startingNodeId, endingNodeId, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsByGenusTypeForNodes
Description

Gets a PathList of the given genus type between the given Nodes.

In plenary mode, the returned list contains all of the paths, or an error results if a path connected to the node is not found or inaccessible. Otherwise, inaccessible Paths may be omitted from the list.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdstartingNodeIdstarting node Id
osid.id.IdendingNodeIdending node Id
osid.type.TypepathGenusTypea path genus type
Returnosid.topology.path.PathListthe returned Path list
ErrorsNULL_ARGUMENT startingNodeId, endingNodeId or pathGenusType null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsByGenusTypeForNodesOnDate
Description

Gets a PathList of the given genus type 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 paths or an error results. Otherwise, the returned list may contain only those paths that are accessible through this session.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdstartingNodeIdstarting node Id
osid.id.IdendingNodeIdending node Id
osid.type.TypepathGenusTypea path genus type
osid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.path.PathListthe returned Path list
ErrorsINVALID_ARGUMENT from Is greater than to
NULL_ARGUMENT startingNodeId, endingNodeId, pathGenusType, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsAlongNodes
Description

Gets a PathList connected to all the given Nodes.

In plenary mode, the returned list contains all of the paths through the nodes, or an error results if a path connected to the node is not found or inaccessible. Otherwise, inaccessible Paths may be omitted from the list.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdListnodeIdsthe list of Ids to retrieve
Returnosid.topology.path.PathListthe returned Path list
ErrorsNULL_ARGUMENT nodeIds is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPathsAlongNodesOnDate
Description

Gets a PathList connected to all the given Nodes and and effective during the entire given date range inclusive but not confined to the date range.

In plenary mode, the returned list contains all of the paths through the nodes, or an error results if a path connected to the node is not found or inaccessible. Otherwise, inaccessible Paths may be omitted from the list.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Parametersosid.id.IdListnodeIdsthe list of Ids to retrieve
osid.calendaring.DateTimefromstart of date range
osid.calendaring.DateTimetoend of date range
Returnosid.topology.path.PathListthe returned Path list
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT nodeIds, from , or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetPaths
Description

Gets all Paths.

In plenary mode, the returned list contains all known paths or an error results. Otherwise, the returned list may contain only those paths that are accessible through this session.

In effective mode, paths are returned that are currently effective. In any effective mode, effective paths and those currently expired are returned.

Returnosid.topology.path.PathLista list of Paths
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.