org.osid.room.squatting

Interface DeedAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

DeedBatchAdminSession

public interface DeedAdminSession
extends OsidSession

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

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

The delete operations delete Deeds. To unmap a Deed from the current Campus, the DeedCampusAssignmentSession should be used. These delete operations attempt to remove the Deed itself thus removing it from all known Campus 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	aliasDeed(Id deedId, Id aliasId) Adds an Id to a Deed for the purpose of creating compatibility.
boolean	canCreateDeeds() Tests if this user can create Deeds.
boolean	canCreateDeedWithRecordTypes(Type[] deedRecordTypes) Tests if this user can create a single Deed using the desired record interface types.
boolean	canDeleteDeeds() Tests if this user can delete Deeds A return of true does not guarantee successful authorization.
boolean	canManageDeedAliases() Tests if this user can manage Id aliases for Deeds.
boolean	canUpdateDeeds() Tests if this user can update Deeds.
Deed	createDeed(DeedForm deedForm) Creates a new Deed.
void	deleteDeed(Id deedId) Deletes a Deed.
Campus	getCampus() Gets the Campus associated with this session.
Id	getCampusId() Gets the Campus Id associated with this session.
DeedForm	getDeedFormForCreate(Id buildingId, Id resourceId, Type[] deedRecordTypes) Gets the deed form for creating new deeds.
DeedForm	getDeedFormForUpdate(Id deedId) Gets the deed form for updating an existing deed.
void	updateDeed(DeedForm deedForm) Updates an existing deed.

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

getCampusId

Id getCampusId()

Gets the Campus Id associated with this session.

Returns:

the Campus Id associated with this session

Compliance:

mandatory - This method must be implemented.

getCampus

Campus getCampus()
                 throws OperationFailedException,
                        PermissionDeniedException

Gets the Campus associated with this session.

Returns:

the campus

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateDeeds

boolean canCreateDeeds()

Tests if this user can create Deeds. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Deed 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 Deed creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateDeedWithRecordTypes

boolean canCreateDeedWithRecordTypes(Type[] deedRecordTypes)

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

Parameters:

deedRecordTypes - array of deed record types

Returns:

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

Throws:

NullArgumentException - deedRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getDeedFormForCreate

DeedForm getDeedFormForCreate(Id buildingId,
                            Id resourceId,
                            Type[] deedRecordTypes)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

Gets the deed form for creating new deeds. A new form should be requested for each create transaction.

Parameters:

buildingId - the Id of the building

resourceId - the Id of the owner resource

deedRecordTypes - array of deed record types

Returns:

the deed form

Throws:

NotFoundException - buildngId or resourceId is not found

NullArgumentException - buildngId, resourceId , or deedRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get from for requested record types

Compliance:

mandatory - This method must be implemented.

createDeed

Deed createDeed(DeedForm deedForm)
                throws OperationFailedException,
                       PermissionDeniedException

Creates a new Deed.

Parameters:

deedForm - the form for this Deed

Returns:

the new Deed

Throws:

IllegalStateException - deedForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - deedForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - deedForm did not originate from getDeedFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateDeeds

boolean canUpdateDeeds()

Tests if this user can update Deeds. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Deed 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 Deed modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getDeedFormForUpdate

DeedForm getDeedFormForUpdate(Id deedId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

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

Parameters:

deedId - the Id of the Deed

Returns:

the deed form

Throws:

NotFoundException - deedId is not found

NullArgumentException - deedId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateDeed

void updateDeed(DeedForm deedForm)
                throws OperationFailedException,
                       PermissionDeniedException

Updates an existing deed.

Parameters:

deedForm - the form containing the elements to be updated

Throws:

IllegalStateException - deedForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - deedForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - deedForm did not originate from getDeedFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteDeeds

boolean canDeleteDeeds()

Tests if this user can delete Deeds A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a Deed 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 Deed deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteDeed

void deleteDeed(Id deedId)
                throws NotFoundException,
                       OperationFailedException,
                       PermissionDeniedException

Deletes a Deed.

Parameters:

deedId - the Id of the Deed to remove

Throws:

NotFoundException - deedId not found

NullArgumentException - deedId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageDeedAliases

boolean canManageDeedAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasDeed

void aliasDeed(Id deedId,
             Id aliasId)
               throws AlreadyExistsException,
                      NotFoundException,
                      OperationFailedException,
                      PermissionDeniedException

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

Parameters:

deedId - the Id of a Deed

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - deedId not found

NullArgumentException - deedId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.