org.osid.resource.batch

Interface ResourceRelationshipBatchAdminSession

All Superinterfaces:

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

public interface ResourceRelationshipBatchAdminSession
extends ResourceRelationshipAdminSession

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

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

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

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

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

The delete operations delete ResourceRelationships in bulk. To unmap a ResourceRelationship from the current Bin, the ResourceRelationshipBinAssignmentSession should be used. These delete operations attempt to remove the ResourceRelationship itself thus removing it from all known Bin catalogs. Bulk delete operations return the results in DeleteResponses.

Method Summary

Methods

Modifier and Type	Method and Description
AliasResponseList	aliasResourceRelationships(AliasRequestList aliasRequests) Adds an Id to a ResourceRelationship for the purpose of creating compatibility.
CreateResponseList	createResourceRelationships(ResourceRelationshipBatchFormList resourceRelationshipForms) Creates a new set of ResourceRelationships.
DeleteResponseList	deleteAllResourceRelationships() Deletes all ResourceRelationships in this Bin .
DeleteResponseList	deleteIneffectiveResourceRelationshipsByDate(DateTime date) Deletes resource relationships expired before the given date.
DeleteResponseList	deleteResourceRelationships(IdList resourceRelationshipIds) Deletes resource relationships for the given Ids.
DeleteResponseList	deleteResourceRelationshipsForDestinationRelationship(Id resourceId) Deletes all resource relationships for the given resource.
DeleteResponseList	deleteResourceRelationshipsForSourceRelationship(Id resourceId) Deletes all resource relationships for the given resource.
ResourceRelationshipBatchFormList	getResourceRelationshipFormsForCreate(ResourceRelationshipPeerList peers, Type[] resourceRelationshipRecordTypes) Gets the resource relationship forms for creating a bunch of new resource relationships.
ResourceRelationshipBatchFormList	getResourceRelationshipFormsForUpdate(IdList resourceRelationshipIds) Gets the resource relationship forms for updating an existing set of resource relationships.
UpdateResponseList	updateResourceRelationships(ResourceRelationshipBatchFormList resourceRelationshipForms) Updates existing resource relationships.

Methods inherited from interface org.osid.resource.ResourceRelationshipAdminSession

aliasResourceRelationship, canCreateResourceRelationships, canCreateResourceRelationshipWithRecordTypes, canDeleteResourceRelationships, canManageResourceRelationshipAliases, canUpdateResourceRelationships, createResourceRelationship, deleteResourceRelationship, getBin, getBinId, getResourceRelationshipFormForCreate, getResourceRelationshipFormForUpdate, updateResourceRelationship

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

getResourceRelationshipFormsForCreate

ResourceRelationshipBatchFormList getResourceRelationshipFormsForCreate(ResourceRelationshipPeerList peers,
                                                                      Type[] resourceRelationshipRecordTypes)
                                                                        throws NotFoundException,
                                                                               OperationFailedException,
                                                                               PermissionDeniedException

Gets the resource relationship forms for creating a bunch of new resource relationships. A ResourceRelationshipForm is returned for each resource peer.

Parameters:

peers - a list of peers

resourceRelationshipRecordTypes - array of resource relationship record types to be included in each create operation or an empty list if none

Returns:

the resource relationship forms

Throws:

NotFoundException - a resourceId is not found

NullArgumentException - peers or resourceRelationshipRecordTypes 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.

createResourceRelationships

CreateResponseList createResourceRelationships(ResourceRelationshipBatchFormList resourceRelationshipForms)
                                               throws OperationFailedException,
                                                      PermissionDeniedException

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

Parameters:

resourceRelationshipForms - the resource relationship forms

Returns:

the create responses

Throws:

NullArgumentException - resourceRelationshipForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getResourceRelationshipFormsForUpdate

ResourceRelationshipBatchFormList getResourceRelationshipFormsForUpdate(IdList resourceRelationshipIds)
                                                                        throws NotFoundException,
                                                                               OperationFailedException,
                                                                               PermissionDeniedException

Gets the resource relationship forms for updating an existing set of resource relationships. A new resource relationship form should be requested for each update transaction.

Parameters:

resourceRelationshipIds - the Ids of the ResourceRelationship

Returns:

the resource relationship form

Throws:

NotFoundException - a resourceRelationshipId is not found

NullArgumentException - resourceRelationshipIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateResourceRelationships

UpdateResponseList updateResourceRelationships(ResourceRelationshipBatchFormList resourceRelationshipForms)
                                               throws OperationFailedException,
                                                      PermissionDeniedException

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

Parameters:

resourceRelationshipForms - the form containing the elements to be updated

Returns:

the update responses

Throws:

NullArgumentException - resourceRelationshipForms is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteAllResourceRelationships

DeleteResponseList deleteAllResourceRelationships()
                                                  throws OperationFailedException,
                                                         PermissionDeniedException

Deletes all ResourceRelationships in this Bin .

Returns:

the delete responses

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteResourceRelationships

DeleteResponseList deleteResourceRelationships(IdList resourceRelationshipIds)
                                               throws OperationFailedException,
                                                      PermissionDeniedException

Deletes resource relationships for the given Ids.

Parameters:

resourceRelationshipIds - the Ids of the resource relationships to delete

Returns:

the delete responses

Throws:

NullArgumentException - resourceRelationshipIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteResourceRelationshipsForSourceRelationship

DeleteResponseList deleteResourceRelationshipsForSourceRelationship(Id resourceId)
                                                                    throws OperationFailedException,
                                                                           PermissionDeniedException

Deletes all resource relationships for the given resource.

Parameters:

resourceId - an Id of a resource

Returns:

the delete responses

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteResourceRelationshipsForDestinationRelationship

DeleteResponseList deleteResourceRelationshipsForDestinationRelationship(Id resourceId)
                                                                         throws OperationFailedException,
                                                                                PermissionDeniedException

Deletes all resource relationships for the given resource.

Parameters:

resourceId - an Id of a resource

Returns:

the delete responses

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

deleteIneffectiveResourceRelationshipsByDate

DeleteResponseList deleteIneffectiveResourceRelationshipsByDate(DateTime date)
                                                                throws OperationFailedException,
                                                                       PermissionDeniedException

Deletes resource relationships expired 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.

aliasResourceRelationships

AliasResponseList aliasResourceRelationships(AliasRequestList aliasRequests)
                                             throws OperationFailedException,
                                                    PermissionDeniedException

Adds an Id to a ResourceRelationship for the purpose of creating compatibility. The primary Id of the ResourceRelationship is determined by the provider. The new Id is an alias to the primary Id. If the alias is a pointer to another resource relationship, it is reassigned to the given entry 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.