org.osid.topology

Interface GraphAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

GraphBatchAdminSession

public interface GraphAdminSession
extends OsidSession

This session creates, updates, and deletes Graphs. 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 a Graph, a GraphForm is requested using getGraphFormForCreate() specifying the desired record Types or none if no record Types are needed. The returned GraphForm 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 the GraphForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each GraphForm corresponds to an attempted transaction.

For updates, GraphForms are requested to the Graph Id that is to be updated using getGraphFormForUpdate(). Similarly, the GraphForm has metadata about the data that can be updated and it can perform validation before submitting the update. The GraphForm can only be used once for a successful update and cannot be reused.

The delete operations delete Graphs.

This session includes an Id aliasing mechanism to assign an external Id to an internally assigned Id.

Method Summary

Methods

Modifier and Type	Method and Description
void	aliasGraph(Id graphId, Id aliasId) Adds an Id to a Graph for the purpose of creating compatibility.
boolean	canCreateGraphs() Tests if this user can create Graphs.
boolean	canCreateGraphWithRecordTypes(Type[] graphRecordTypes) Tests if this user can create a single Graph using the desired record types.
boolean	canDeleteGraphs() Tests if this user can delete Graphs.
boolean	canManageGraphAliases() Tests if this user can manage Id aliases for graphs.
boolean	canUpdateGraphs() Tests if this user can update Graphs.
Graph	createGraph(GraphForm graphForm) Creates a new Graph.
void	deleteGraph(Id graphId) Deletes a Graph.
GraphForm	getGraphFormForCreate(Type[] graphRecordTypes) Gets the graph form for creating new graphs.
GraphForm	getGraphFormForUpdate(Id graphId) Gets the graph form for updating an existing graph.
void	updateGraph(GraphForm graphForm) Updates an existing graph

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

canCreateGraphs

boolean canCreateGraphs()

Tests if this user can create Graphs. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Graph. will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.

Returns:

false if Graph creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateGraphWithRecordTypes

boolean canCreateGraphWithRecordTypes(Type[] graphRecordTypes)

Tests if this user can create a single Graph using the desired record types. While TopologyManager.getGraphRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific Graph. Providing an empty array tests if a Graph can be created with no records.

Parameters:

graphRecordTypes - array of graph record types

Returns:

true if Graph creation using the specified record Types is supported, false otherwise

Throws:

NullArgumentException - graphRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getGraphFormForCreate

GraphForm getGraphFormForCreate(Type[] graphRecordTypes)
                                throws OperationFailedException,
                                       PermissionDeniedException

Gets the graph form for creating new graphs. A new form should be requested for each create transaction.

Parameters:

graphRecordTypes - array of graph record types

Returns:

the graph form

Throws:

NullArgumentException - graphRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createGraph

Graph createGraph(GraphForm graphForm)
                  throws OperationFailedException,
                         PermissionDeniedException

Creates a new Graph.

Parameters:

graphForm - the form for this Graph

Returns:

the new Graph

Throws:

IllegalStateException - graphForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - graphForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - graphForm did not originate from getGraphFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateGraphs

boolean canUpdateGraphs()

Tests if this user can update Graphs. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Graph will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.

Returns:

false if Graph modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getGraphFormForUpdate

GraphForm getGraphFormForUpdate(Id graphId)
                                throws NotFoundException,
                                       OperationFailedException,
                                       PermissionDeniedException

Gets the graph form for updating an existing graph. A new graph form should be requested for each update transaction.

Parameters:

graphId - the Id of the Graph

Returns:

the graph form

Throws:

NotFoundException - graphId is not found

NullArgumentException - graphId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateGraph

void updateGraph(GraphForm graphForm)
                 throws OperationFailedException,
                        PermissionDeniedException

Updates an existing graph

Parameters:

graphForm - the form containing the elements to be updated

Throws:

IllegalStateException - graphForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - graphForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - graphForm did not originate from getGraphFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteGraphs

boolean canDeleteGraphs()

Tests if this user can delete Graphs. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a Graph will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer delete operations to unauthorized users.

Returns:

false if Graph deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteGraph

void deleteGraph(Id graphId)
                 throws NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

Deletes a Graph.

Parameters:

graphId - the Id of the Graph to remove

Throws:

NotFoundException - graphId not found

NullArgumentException - graphId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageGraphAliases

boolean canManageGraphAliases()

Tests if this user can manage Id aliases for graphs. A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.

Returns:

false if Graph aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasGraph

void aliasGraph(Id graphId,
              Id aliasId)
                throws AlreadyExistsException,
                       NotFoundException,
                       OperationFailedException,
                       PermissionDeniedException

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

Parameters:

graphId - the Id of a Graph

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - graphId not found

NullArgumentException - graphId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.