org.osid.topology.batch

Interface EdgeBatchAdminSession

All Superinterfaces:

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

public interface EdgeBatchAdminSession
extends EdgeAdminSession

This session creates, updates, and deletes Edges in bulk. The data for create and update is provided by the consumer via the form object. OsidForms are requested for each create or update and may not be reused.

Create and update operations differ in their usage. To create an Edge, an EdgeForm is requested using getEdgeFormsForCreate() specifying the desired record Types or none if no record Types are needed. Each of the returned EdgeForms will indicate that it is to be used with a create operation and can be used to examine metdata or validate data prior to creation. Once an EdgeForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each EdgeForm corresponds to an attempted transaction.

The EdgeForms returned from getEdgeFormsForCreate() may be linked to the originating request through the peer Ids of the EdgeForm. In the case where there may be duplicates, any EdgeForm of the same peer Ids may be used for a create operation.

Once a batch of EdgeForms are submitted for create, a CreateResponse is returned for each EdgeForm, although the ordering is not defined. Only errors that pertain to the entire create operation are returned from createEdges(), errors specific to an individual EdgeForm are indicated in the corresponding CreateResponse. CreateResponses may be linked to the originating EdgeForm through the EdgeForm Id .

For updates, EdgeForms are requested to the Edge Id that is to be updated using getEdgeFormsForUpdate() where the reference Id in the EdgeForm may be used to link the request. Similarly, the EdgeForm has metadata about the data that can be updated and it can perform validation before submitting the update. The EdgeForm can only be used once for a successful update and cannot be reused.

Once a batch of EdgeForms are submitted for update, an UpdateResponse is returned for each EdgeForm, although the ordering is not defined. Only errors that pertain to the entire update operation are returned from updateEdges(), errors specific to an individual EdgeForm are indicated in the corresponding UpdateResponse. UpdateResponses may be linked to the originating EdgeForm through the EdgeForm Id.

The delete operations delete Edges in bulk. To unmap an Edge from the current Graph, the EdgeGraphAssignmentSession should be used. These delete operations attempt to remove the Edge itself thus removing it from all known Graph catalogs. Bulk delete operations return the results in DeleteResponses.

Method Summary

Methods

Modifier and Type	Method and Description
AliasResponseList	aliasEdges(AliasRequestList aliasRequests) Adds an Id to an Edge for the purpose of creating compatibility.
CreateResponseList	createEdges(EdgeBatchFormList edgeForms) Creates a new set of Edges.
DeleteResponseList	deleteAllEdges() Deletes all Edges in this Graph .
DeleteResponseList	deleteEdges(IdList edgeIds) Deletes edges for the given Ids.
DeleteResponseList	deleteEdgesForDestinationNode(Id destinationNodeId) Deletes edges for the given destination node.
DeleteResponseList	deleteEdgesForSourceNode(Id sourceNodeId) Deletes edges for the given source node.
DeleteResponseList	deleteIneffectiveEdgesByDate(DateTime date) Deletes edges ineffective before the given date.
EdgeBatchFormList	getEdgeFormsForCreate(EdgePeerList peers, Type[] edgeRecordTypes) Gets the edge forms for creating a bunch of new edges.
EdgeBatchFormList	getEdgeFormsForUpdate(IdList edgeIds) Gets the edge forms for updating an existing set of edges.
UpdateResponseList	updateEdges(EdgeBatchFormList edgeForms) Updates existing edges.

Methods inherited from interface org.osid.topology.EdgeAdminSession

aliasEdge, canCreateEdges, canCreateEdgeWithRecordTypes, canDeleteEdges, canManageEdgeAliases, canUpdateEdges, createEdge, deleteEdge, getEdgeFormForCreate, getEdgeFormForUpdate, getGraph, getGraphId, updateEdge

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

getEdgeFormsForCreate

EdgeBatchFormList getEdgeFormsForCreate(EdgePeerList peers,
                                      Type[] edgeRecordTypes)
                                        throws NotFoundException,
                                               OperationFailedException,
                                               PermissionDeniedException

Gets the edge forms for creating a bunch of new edges. A form is returned for each set of edge peers.

Parameters:

peers - a list of edge peers

edgeRecordTypes - array of edge record types to be included in each create operation or an empty list if none

Returns:

the edge forms

Throws:

NotFoundException - a node is not found

NullArgumentException - peers or edgeRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to request forms with given record types

Compliance:

mandatory - This method must be implemented.

createEdges

CreateResponseList createEdges(EdgeBatchFormList edgeForms)
                               throws OperationFailedException,
                                      PermissionDeniedException

Creates a new set of Edges. This method returns an error if the entire operation fails. Otherwise, the status of an individual create operation is indicated in the BatchCreateResponse .

Parameters:

edgeForms - the edge forms

Returns:

the create responses

Throws:

NullArgumentException - edgeForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getEdgeFormsForUpdate

EdgeBatchFormList getEdgeFormsForUpdate(IdList edgeIds)
                                        throws NotFoundException,
                                               OperationFailedException,
                                               PermissionDeniedException

Gets the edge forms for updating an existing set of edges. A new edge form should be requested for each update transaction.

Parameters:

edgeIds - the Ids of the Edge

Returns:

the edge form

Throws:

NotFoundException - an edgeId is not found

NullArgumentException - edgeIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateEdges

UpdateResponseList updateEdges(EdgeBatchFormList edgeForms)
                               throws OperationFailedException,
                                      PermissionDeniedException

Updates existing edges. This method returns an error if the entire operation fails. Otherwise, the status of an individual update operation is indicated in the BatchCreateResponse .

Parameters:

edgeForms - the form containing the elements to be updated

Returns:

the update responses

Throws:

NullArgumentException - edgeForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteAllEdges

DeleteResponseList deleteAllEdges()
                                  throws OperationFailedException,
                                         PermissionDeniedException

Deletes all Edges in this Graph .

Returns:

the delete responses

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteEdges

DeleteResponseList deleteEdges(IdList edgeIds)
                               throws OperationFailedException,
                                      PermissionDeniedException

Deletes edges for the given Ids.

Parameters:

edgeIds - the Ids of the edges to delete

Returns:

the delete responses

Throws:

NullArgumentException - edgeIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteEdgesForSourceNode

DeleteResponseList deleteEdgesForSourceNode(Id sourceNodeId)
                                            throws OperationFailedException,
                                                   PermissionDeniedException

Deletes edges for the given source node.

Parameters:

sourceNodeId - the Id of a node

Returns:

the delete responses

Throws:

NullArgumentException - sourceNodeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteEdgesForDestinationNode

DeleteResponseList deleteEdgesForDestinationNode(Id destinationNodeId)
                                                 throws OperationFailedException,
                                                        PermissionDeniedException

Deletes edges for the given destination node.

Parameters:

destinationNodeId - the Id of a node

Returns:

the delete responses

Throws:

NullArgumentException - destinationNodeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteIneffectiveEdgesByDate

DeleteResponseList deleteIneffectiveEdgesByDate(DateTime date)
                                                throws OperationFailedException,
                                                       PermissionDeniedException

Deletes edges ineffective before the given date.

Parameters:

date - a date

Returns:

the delete responses

Throws:

NullArgumentException - date is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

aliasEdges

AliasResponseList aliasEdges(AliasRequestList aliasRequests)
                             throws OperationFailedException,
                                    PermissionDeniedException

Adds an Id to an Edge for the purpose of creating compatibility. The primary Id of the Edge is determined by the provider. The new Id is an alias to the primary Id. If the alias is a pointer to another edge, it is reassigned to the given edge Id.

Parameters:

aliasRequests - the alias requests

Returns:

the alias responses

Throws:

NullArgumentException - aliasRequests is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.