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

This session provides methods for retrieving Edge objects. The Edge represents a connection between two Nodes.

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 edge methods in this session operate, retrieve and pertain to edges defined explicitly in the current graph. Using an isolated view is useful for managing Edges with the EdgeAdminSession.
  • federated graph view: All edge methods in this session operate, retrieve and pertain to all edges defined in this graph and any other edges implicitly available in this graph through graph inheritence.
  • effective edge view: All edge lookup methods return edges where the current dates falls in between the effective dates inclusive.
  • any effective edge view: Edges 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.
MethodcanLookupEdges
Description

Tests if this user can perform Edge 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.
MethoduseComparativeEdgeView
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.
MethodusePlenaryEdgeView
Description

A complete view of the Edge 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 edges 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.
MethoduseEffectiveEdgeView
Description

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

CompliancemandatoryThis method is must be implemented.
MethoduseAnyEffectiveEdgeView
Description

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

CompliancemandatoryThis method is must be implemented.
MethodgetEdge
Description

Gets the Edge specified by its Id.

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

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

Parametersosid.id.IdedgeId Id of the Edge
Returnosid.topology.Edgethe edge
ErrorsNOT_FOUND edgeId not found
NULL_ARGUMENT edgeId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method is must be implemented.
MethodgetEdgesByIds
Description

Gets an EdgeList corresponding to the given IdList.

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

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

Parametersosid.id.IdListedgeIdsthe list of Ids to retrieve
Returnosid.topology.EdgeListthe returned Edge list
ErrorsNOT_FOUNDan Id was not found
NULL_ARGUMENT edgeIds is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesByGenusType
Description

Gets an EdgeList corresponding to the given edge genus Type which does not include edges of genus types derived from the specified Type.

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

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

Parametersosid.type.TypeedgeGenusTypean edge genus type
Returnosid.topology.EdgeListthe returned Edge list
ErrorsNULL_ARGUMENT edgeGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesByParentGenusType
Description

Gets an EdgeList corresponding to the given edge genus Type and include any additional edges with genus types derived from the specified Type.

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

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

Parametersosid.type.TypeedgeGenusTypean edge genus type
Returnosid.topology.EdgeListthe returned Edge list
ErrorsNULL_ARGUMENT edgeGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesByRecordType
Description

Gets an EdgeList containing the given edge record Type.

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

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

Parametersosid.type.TypeedgeRecordTypean edge record type
Returnosid.topology.EdgeListthe returned Edge list
ErrorsNULL_ARGUMENT edgeRecordType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesOnDate
Description

Gets an EdgeList effective during the entire given date range inclusive but not confined to the date range.

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

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

Parametersosid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.EdgeListthe returned Edge 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.
MethodgetEdgesByGenusTypeOnDate
Description

Gets an EdgeList of a genus type effective during the entire given date range inclusive but not confined to the date range.

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

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

Parametersosid.type.TypeedgeGenusTypean edge genus type
osid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.EdgeListthe returned Edge list
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT edgeGenusType, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesForSourceNode
Description

Gets an EdgeList corresponding to the given source node Id.

In plenary mode, the returned list contains all of the edges corresponding to the given peer, including duplicates, or an error results if an edge is inaccessible. Otherwise, inaccessible Edges may be omitted from the list and may present the elements in any order including returning a unique set.

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

Parametersosid.id.IdsourceNodeIda node Id
Returnosid.topology.EdgeLista list of edges
ErrorsNULL_ARGUMENT sourceNodeId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesForSourceNodeOnDate
Description

Gets an EdgeList with effective during the entire given date range inclusive but not confined to the date range.

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

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

Parametersosid.id.IdsourceNodeIda node Id
osid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.EdgeLista list of edges
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT sourceNodeId, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesByGenusTypeForSourceNode
Description

Gets an EdgeList corresponding to the given source node Id and edge genus Type and includes any genus types derived from the given genus type.

In plenary mode, the returned list contains all of the edges corresponding to the given peer, including duplicates, or an error results if an edge is inaccessible. Otherwise, inaccessible Edges may be omitted from the list and may present the elements in any order including returning a unique set.

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

Parametersosid.id.IdsourceNodeIda node Id
osid.type.TypeedgeGenusTypean edge genus type
Returnosid.topology.EdgeLista list of edges
ErrorsNULL_ARGUMENT sourceNodeId or edgeGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesByGenusTypeForSourceNodeOnDate
Description

Gets an EdgeList with 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 edges or an error results. Otherwise, the returned list may contain only those edges that are accessible through this session.

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

Parametersosid.id.IdnodeIda node Id
osid.type.TypeedgeGenusTypean edge genus type
osid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.EdgeLista list of edges
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT sourceNodeId, edgeGenusType, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesForDestinationNode
Description

Gets an EdgeList corresponding to the given destination node Id.

In plenary mode, the returned list contains all of the edges corresponding to the given peer, including duplicates, or an error results if an edge is inaccessible. Otherwise, inaccessible Edges may be omitted from the list and may present the elements in any order including returning a unique set.

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

Parametersosid.id.IddestinationNodeIda node Id
Returnosid.topology.EdgeLista list of edges
ErrorsNULL_ARGUMENT destinationNodeId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesForDestinationNodeOnDate
Description

Gets an EdgeList effective during the entire given date range inclusive but not confined to the date range.

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

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

Parametersosid.id.IddestinationNodeIda node Id
osid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.EdgeLista list of edges
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT destinationNodeId, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesByGenusTypeForDestinationNode
Description

Gets an EdgeList corresponding to the given destination node Id and edge genus Type and includes any genus types derived from the given genus type.

In plenary mode, the returned list contains all of the edges corresponding to the given peer, including duplicates, or an error results if an edge is inaccessible. Otherwise, inaccessible Edges may be omitted from the list and may present the elements in any order including returning a unique set.

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

Parametersosid.id.IddestinationNodeIda node Id
osid.type.TypeedgeGenusTypean edge genus type
Returnosid.topology.EdgeLista list of edges
ErrorsNULL_ARGUMENT destinationNodeId or edgeGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesByGenusTypeForDestinationNodeOnDate
Description

Gets an EdgeList with 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 edges or an error results. Otherwise, the returned list may contain only those edges that are accessible through this session.

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

Parametersosid.id.IddestinationNodeIda node Id
osid.type.TypeedgeGenusTypean edge genus type
osid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.EdgeLista list of edges
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT destinationNodeId, edgeGenusType, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesForNodes
Description

Gets an EdgeList corresponding to the given node Ids.

In plenary mode, the returned list contains all of the edges corresponding to the given peer, including duplicates, or an error results if an edge is inaccessible. Otherwise, inaccessible Edges may be omitted from the list and may present the elements in any order including returning a unique set.

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

Parametersosid.id.IdsourceNodeIda node Id
osid.id.IddestinationNodeIda node Id
Returnosid.topology.EdgeLista list of edges
ErrorsNULL_ARGUMENT sourceNodeId or destinationNodeId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesForNodesOnDate
Description

Gets an EdgeList effective during the entire given date range inclusive but not confined to the date range.

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

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

Parametersosid.id.IdsourceNodeIda node Id
osid.id.IddestinationNodeIda node Id
osid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.EdgeLista list of edges
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT sourceNodeId, destinationNodeId, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesByGenusTypeForNodes
Description

Gets an EdgeList corresponding to the given peer Ids and edge genus type and includes and genus types derived from the given genus type.

In plenary mode, the returned list contains all of the edges corresponding to the given peer, including duplicates, or an error results if an edge is inaccessible. Otherwise, inaccessible Edges may be omitted from the list and may present the elements in any order including returning a unique set.

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

Parametersosid.id.IdsourceNodeIda node Id
osid.id.IddestinationNodeIda node Id
osid.type.TypeedgeGenusTypean edge genus type
Returnosid.topology.EdgeListthe edges
ErrorsNULL_ARGUMENT sourceNodeId, destinationNodeId, or edgeGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdgesByGenusTypeForNodesOnDate
Description

Gets an EdgeList of the given genus type effective during the entire given date range inclusive but not confined to the date range.

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

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

Parametersosid.id.IdsourceNodeIda node Id
osid.id.IddestinationNodeIda node Id
osid.type.TypeedgeGenusTypean edge genus type
osid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.topology.EdgeLista list of edges
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT sourceNodeId, destinationNodeId, edgeGenusType, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetEdges
Description

Gets all Edges.

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

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

Returnosid.topology.EdgeLista list of Edges
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.