org.osid.topology

Interface EdgeLookupSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

public interface EdgeLookupSession
extends OsidSession

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.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupEdges() Tests if this user can perform Edge lookups.
Edge	getEdge(Id edgeId) Gets the Edge specified by its Id.
EdgeList	getEdges() Gets all Edges.
EdgeList	getEdgesByGenusType(Type edgeGenusType) Gets an EdgeList corresponding to the given edge genus Type which does not include edges of genus types derived from the specified Type.
EdgeList	getEdgesByGenusTypeForDestinationNode(Id destinationNodeId, Type edgeGenusType) 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.
EdgeList	getEdgesByGenusTypeForDestinationNodeOnDate(Id destinationNodeId, Type edgeGenusType, DateTime from, DateTime to) Gets an EdgeList with the given genus type and effective during the entire given date range inclusive but not confined to the date range.
EdgeList	getEdgesByGenusTypeForNodes(Id sourceNodeId, Id destinationNodeId, Type edgeGenusType) Gets an EdgeList corresponding to the given peer Ids and edge genus type and includes and genus types derived from the given genus type.
EdgeList	getEdgesByGenusTypeForNodesOnDate(Id sourceNodeId, Id destinationNodeId, Type edgeGenusType, DateTime from, DateTime to) Gets an EdgeList of the given genus type effective during the entire given date range inclusive but not confined to the date range.
EdgeList	getEdgesByGenusTypeForSourceNode(Id sourceNodeId, Type edgeGenusType) 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.
EdgeList	getEdgesByGenusTypeForSourceNodeOnDate(Id nodeId, Type edgeGenusType, DateTime from, DateTime to) Gets an EdgeList with the given genus type and effective during the entire given date range inclusive but not confined to the date range.
EdgeList	getEdgesByGenusTypeOnDate(Type edgeGenusType, DateTime from, DateTime to) Gets an EdgeList of a genus type effective during the entire given date range inclusive but not confined to the date range.
EdgeList	getEdgesByIds(IdList edgeIds) Gets an EdgeList corresponding to the given IdList.
EdgeList	getEdgesByParentGenusType(Type edgeGenusType) Gets an EdgeList corresponding to the given edge genus Type and include any additional edges with genus types derived from the specified Type.
EdgeList	getEdgesByRecordType(Type edgeRecordType) Gets an EdgeList containing the given edge record Type.
EdgeList	getEdgesForDestinationNode(Id destinationNodeId) Gets an EdgeList corresponding to the given destination node Id.
EdgeList	getEdgesForDestinationNodeOnDate(Id destinationNodeId, DateTime from, DateTime to) Gets an EdgeList effective during the entire given date range inclusive but not confined to the date range.
EdgeList	getEdgesForNodes(Id sourceNodeId, Id destinationNodeId) Gets an EdgeList corresponding to the given node Ids.
EdgeList	getEdgesForNodesOnDate(Id sourceNodeId, Id destinationNodeId, DateTime from, DateTime to) Gets an EdgeList effective during the entire given date range inclusive but not confined to the date range.
EdgeList	getEdgesForSourceNode(Id sourceNodeId) Gets an EdgeList corresponding to the given source node Id.
EdgeList	getEdgesForSourceNodeOnDate(Id sourceNodeId, DateTime from, DateTime to) Gets an EdgeList with effective during the entire given date range inclusive but not confined to the date range.
EdgeList	getEdgesOnDate(DateTime from, DateTime to) Gets an EdgeList effective during the entire given date range inclusive but not confined to the date range.
Graph	getGraph() Gets the Graph associated with this session.
Id	getGraphId() Gets the Graph Id associated with this session.
void	useAnyEffectiveEdgeView() All edges of any effective dates are returned by all methods in this session.
void	useComparativeEdgeView() The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	useEffectiveEdgeView() Only edges whose effective dates are current are returned by methods in this session.
void	useFederatedGraphView() Federates the view for methods in this session.
void	useIsolatedGraphView() Isolates the view for methods in this session.
void	usePlenaryEdgeView() A complete view of the Edge returns is desired.

Methods inherited from interface org.osid.OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

getGraphId

Id getGraphId()

Gets the Graph Id associated with this session.

Returns:

the Graph Id associated with this session

Compliance:

mandatory - This method must be implemented.

getGraph

Graph getGraph()
               throws OperationFailedException,
                      PermissionDeniedException

Gets the Graph associated with this session.

Returns:

the graph

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canLookupEdges

boolean canLookupEdges()

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.

Returns:

false if lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeEdgeView

void useComparativeEdgeView()

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.

usePlenaryEdgeView

void usePlenaryEdgeView()

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.

Compliance:

mandatory - This method is must be implemented.

useFederatedGraphView

void useFederatedGraphView()

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.

Compliance:

mandatory - This method is must be implemented.

useIsolatedGraphView

void useIsolatedGraphView()

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

Compliance:

mandatory - This method is must be implemented.

useEffectiveEdgeView

void useEffectiveEdgeView()

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

Compliance:

mandatory - This method is must be implemented.

useAnyEffectiveEdgeView

void useAnyEffectiveEdgeView()

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

Compliance:

mandatory - This method is must be implemented.

getEdge

Edge getEdge(Id edgeId)
             throws NotFoundException,
                    OperationFailedException,
                    PermissionDeniedException

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.

Parameters:

edgeId - Id of the Edge

Returns:

the edge

Throws:

NotFoundException - edgeId not found

NullArgumentException - edgeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

getEdgesByIds

EdgeList getEdgesByIds(IdList edgeIds)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

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.

Parameters:

edgeIds - the list of Ids to retrieve

Returns:

the returned Edge list

Throws:

NotFoundException - an Id was not found

NullArgumentException - edgeIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesByGenusType

EdgeList getEdgesByGenusType(Type edgeGenusType)
                             throws OperationFailedException,
                                    PermissionDeniedException

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.

Parameters:

edgeGenusType - an edge genus type

Returns:

the returned Edge list

Throws:

NullArgumentException - edgeGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesByParentGenusType

EdgeList getEdgesByParentGenusType(Type edgeGenusType)
                                   throws OperationFailedException,
                                          PermissionDeniedException

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.

Parameters:

edgeGenusType - an edge genus type

Returns:

the returned Edge list

Throws:

NullArgumentException - edgeGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesByRecordType

EdgeList getEdgesByRecordType(Type edgeRecordType)
                              throws OperationFailedException,
                                     PermissionDeniedException

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.

Parameters:

edgeRecordType - an edge record type

Returns:

the returned Edge list

Throws:

NullArgumentException - edgeRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesOnDate

EdgeList getEdgesOnDate(DateTime from,
                      DateTime to)
                        throws OperationFailedException,
                               PermissionDeniedException

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.

Parameters:

from - starting date

to - ending date

Returns:

the returned Edge list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesByGenusTypeOnDate

EdgeList getEdgesByGenusTypeOnDate(Type edgeGenusType,
                                 DateTime from,
                                 DateTime to)
                                   throws OperationFailedException,
                                          PermissionDeniedException

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.

Parameters:

edgeGenusType - an edge genus type

from - starting date

to - ending date

Returns:

the returned Edge list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - edgeGenusType, from, or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesForSourceNode

EdgeList getEdgesForSourceNode(Id sourceNodeId)
                               throws OperationFailedException,
                                      PermissionDeniedException

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.

Parameters:

sourceNodeId - a node Id

Returns:

a list of edges

Throws:

NullArgumentException - sourceNodeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesForSourceNodeOnDate

EdgeList getEdgesForSourceNodeOnDate(Id sourceNodeId,
                                   DateTime from,
                                   DateTime to)
                                     throws OperationFailedException,
                                            PermissionDeniedException

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.

Parameters:

sourceNodeId - a node Id

from - starting date

to - ending date

Returns:

a list of edges

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - sourceNodeId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesByGenusTypeForSourceNode

EdgeList getEdgesByGenusTypeForSourceNode(Id sourceNodeId,
                                        Type edgeGenusType)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

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.

Parameters:

sourceNodeId - a node Id

edgeGenusType - an edge genus type

Returns:

a list of edges

Throws:

NullArgumentException - sourceNodeId or edgeGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesByGenusTypeForSourceNodeOnDate

EdgeList getEdgesByGenusTypeForSourceNodeOnDate(Id nodeId,
                                              Type edgeGenusType,
                                              DateTime from,
                                              DateTime to)
                                                throws OperationFailedException,
                                                       PermissionDeniedException

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.

Parameters:

nodeId - a node Id

edgeGenusType - an edge genus type

from - starting date

to - ending date

Returns:

a list of edges

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - sourceNodeId, edgeGenusType, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesForDestinationNode

EdgeList getEdgesForDestinationNode(Id destinationNodeId)
                                    throws OperationFailedException,
                                           PermissionDeniedException

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.

Parameters:

destinationNodeId - a node Id

Returns:

a list of edges

Throws:

NullArgumentException - destinationNodeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesForDestinationNodeOnDate

EdgeList getEdgesForDestinationNodeOnDate(Id destinationNodeId,
                                        DateTime from,
                                        DateTime to)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

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.

Parameters:

destinationNodeId - a node Id

from - starting date

to - ending date

Returns:

a list of edges

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - destinationNodeId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesByGenusTypeForDestinationNode

EdgeList getEdgesByGenusTypeForDestinationNode(Id destinationNodeId,
                                             Type edgeGenusType)
                                               throws OperationFailedException,
                                                      PermissionDeniedException

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.

Parameters:

destinationNodeId - a node Id

edgeGenusType - an edge genus type

Returns:

a list of edges

Throws:

NullArgumentException - destinationNodeId or edgeGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesByGenusTypeForDestinationNodeOnDate

EdgeList getEdgesByGenusTypeForDestinationNodeOnDate(Id destinationNodeId,
                                                   Type edgeGenusType,
                                                   DateTime from,
                                                   DateTime to)
                                                     throws OperationFailedException,
                                                            PermissionDeniedException

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.

Parameters:

destinationNodeId - a node Id

edgeGenusType - an edge genus type

from - starting date

to - ending date

Returns:

a list of edges

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - destinationNodeId, edgeGenusType, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesForNodes

EdgeList getEdgesForNodes(Id sourceNodeId,
                        Id destinationNodeId)
                          throws OperationFailedException,
                                 PermissionDeniedException

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.

Parameters:

sourceNodeId - a node Id

destinationNodeId - a node Id

Returns:

a list of edges

Throws:

NullArgumentException - sourceNodeId or destinationNodeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesForNodesOnDate

EdgeList getEdgesForNodesOnDate(Id sourceNodeId,
                              Id destinationNodeId,
                              DateTime from,
                              DateTime to)
                                throws OperationFailedException,
                                       PermissionDeniedException

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.

Parameters:

sourceNodeId - a node Id

destinationNodeId - a node Id

from - starting date

to - ending date

Returns:

a list of edges

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - sourceNodeId, destinationNodeId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesByGenusTypeForNodes

EdgeList getEdgesByGenusTypeForNodes(Id sourceNodeId,
                                   Id destinationNodeId,
                                   Type edgeGenusType)
                                     throws OperationFailedException,
                                            PermissionDeniedException

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.

Parameters:

sourceNodeId - a node Id

destinationNodeId - a node Id

edgeGenusType - an edge genus type

Returns:

the edges

Throws:

NullArgumentException - sourceNodeId, destinationNodeId, or edgeGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgesByGenusTypeForNodesOnDate

EdgeList getEdgesByGenusTypeForNodesOnDate(Id sourceNodeId,
                                         Id destinationNodeId,
                                         Type edgeGenusType,
                                         DateTime from,
                                         DateTime to)
                                           throws OperationFailedException,
                                                  PermissionDeniedException

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.

Parameters:

sourceNodeId - a node Id

destinationNodeId - a node Id

edgeGenusType - an edge genus type

from - starting date

to - ending date

Returns:

a list of edges

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - sourceNodeId, destinationNodeId, edgeGenusType, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdges

EdgeList getEdges()
                  throws OperationFailedException,
                         PermissionDeniedException

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.

Returns:

a list of Edges

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.