org.osid.topology

Interface NodeAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

NodeBatchAdminSession

public interface NodeAdminSession
extends OsidSession

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

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

The delete operations delete Nodes. To unmap a Node from the current Graph, the NodeGraphAssignmentSession should be used. These delete operations attempt to remove the Node itself thus removing it from all known Graph catalogs.

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	aliasNode(Id nodeId, Id aliasId) Adds an Id to a Node for the purpose of creating compatibility.
boolean	canCreateNodes() Tests if this user can create Nodes.
boolean	canCreateNodeWithRecordTypes(Type[] nodeRecordTypes) Tests if this user can create a single Node using the desired record types.
boolean	canDeleteNodes() Tests if this user can delete Nodes.
boolean	canManageNodeAliases() Tests if this user can manage Id aliases for node entries.
boolean	canUpdateNodes() Tests if this user can update Nodes.
Node	createNode(NodeForm nodeForm) Creates a new Node.
void	deleteNode(Id nodeId) Deletes a Node.
Graph	getGraph() Gets the Graph associated with this session.
Id	getGraphId() Gets the Graph Id associated with this session.
NodeForm	getNodeFormForCreate(Type[] nodeRecordTypes) Gets the node form for creating new nodes.
NodeForm	getNodeFormForUpdate(Id nodeId) Gets the node form for updating an existing node.
void	updateNode(NodeForm nodeForm) Updates an existing node.

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.

canCreateNodes

boolean canCreateNodes()

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

Returns:

false if Node creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateNodeWithRecordTypes

boolean canCreateNodeWithRecordTypes(Type[] nodeRecordTypes)

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

Parameters:

nodeRecordTypes - array of node record types

Returns:

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

Throws:

NullArgumentException - nodeRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getNodeFormForCreate

NodeForm getNodeFormForCreate(Type[] nodeRecordTypes)
                              throws OperationFailedException,
                                     PermissionDeniedException

Gets the node form for creating new nodes. A new form should be requested for each create transaction.

Parameters:

nodeRecordTypes - array of node record types

Returns:

the node form

Throws:

NullArgumentException - nodeRecordTypes 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.

createNode

Node createNode(NodeForm nodeForm)
                throws OperationFailedException,
                       PermissionDeniedException

Creates a new Node.

Parameters:

nodeForm - the form for this Node

Returns:

the new Node

Throws:

IllegalStateException - nodeForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - nodeForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - nodeForm did not originate from getNodeFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateNodes

boolean canUpdateNodes()

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

Returns:

false if Node modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getNodeFormForUpdate

NodeForm getNodeFormForUpdate(Id nodeId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

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

Parameters:

nodeId - the Id of the Node

Returns:

the node form

Throws:

NotFoundException - nodeId is not found

NullArgumentException - nodeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateNode

void updateNode(NodeForm nodeForm)
                throws OperationFailedException,
                       PermissionDeniedException

Updates an existing node.

Parameters:

nodeForm - the form containing the elements to be updated

Throws:

IllegalStateException - nodeForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - nodeForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - nodeForm did not originate from getNodeFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteNodes

boolean canDeleteNodes()

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

Returns:

false if Node deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteNode

void deleteNode(Id nodeId)
                throws NotFoundException,
                       OperationFailedException,
                       PermissionDeniedException

Deletes a Node.

Parameters:

nodeId - the Id of the Node to remove

Throws:

NotFoundException - nodeId not found

NullArgumentException - nodeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageNodeAliases

boolean canManageNodeAliases()

Tests if this user can manage Id aliases for node entries. 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 Node aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasNode

void aliasNode(Id nodeId,
             Id aliasId)
               throws AlreadyExistsException,
                      NotFoundException,
                      OperationFailedException,
                      PermissionDeniedException

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

Parameters:

nodeId - the Id of a Node

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - nodeId not found

NullArgumentException - nodeId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.