org.osid.room.squatting

Interface LeaseAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

LeaseBatchAdminSession

public interface LeaseAdminSession
extends OsidSession

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

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

The delete operations delete Leases. To unmap a Lease from the current Campus, the LeaseCampusAssignmentSession should be used. These delete operations attempt to remove the Lease 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	aliasLease(Id leaseId, Id aliasId) Adds an Id to a Lease for the purpose of creating compatibility.
boolean	canCreateLeases() Tests if this user can create Leases.
boolean	canCreateLeaseWithRecordTypes(Type[] leaseRecordTypes) Tests if this user can create a single Lease using the desired record interface types.
boolean	canDeleteLeases() Tests if this user can delete Leases A return of true does not guarantee successful authorization.
boolean	canManageLeaseAliases() Tests if this user can manage Id aliases for Leases.
boolean	canUpdateLeases() Tests if this user can update Leases.
Lease	createLease(LeaseForm leaseForm) Creates a new Lease.
void	deleteLease(Id leaseId) Deletes a Lease.
Campus	getCampus() Gets the Campus associated with this session.
Id	getCampusId() Gets the Campus Id associated with this session.
LeaseForm	getLeaseFormForCreate(Id roomId, Id resourceId, Type[] leaseRecordTypes) Gets the lease form for creating new leases.
LeaseForm	getLeaseFormForUpdate(Id leaseId) Gets the lease form for updating an existing lease.
void	updateLease(LeaseForm leaseForm) Updates an existing lease.

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.

canCreateLeases

boolean canCreateLeases()

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

Compliance:

mandatory - This method must be implemented.

canCreateLeaseWithRecordTypes

boolean canCreateLeaseWithRecordTypes(Type[] leaseRecordTypes)

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

Parameters:

leaseRecordTypes - array of lease record types

Returns:

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

Throws:

NullArgumentException - leaseRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getLeaseFormForCreate

LeaseForm getLeaseFormForCreate(Id roomId,
                              Id resourceId,
                              Type[] leaseRecordTypes)
                                throws NotFoundException,
                                       OperationFailedException,
                                       PermissionDeniedException

Gets the lease form for creating new leases. A new form should be requested for each create transaction.

Parameters:

roomId - a room Id

resourceId - a tenant resource Id

leaseRecordTypes - array of lease record types

Returns:

the lease form

Throws:

NotFoundException - roomId or resourceId is not found

NullArgumentException - roomId, resourceId, or leaseRecordTypes 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.

createLease

Lease createLease(LeaseForm leaseForm)
                  throws OperationFailedException,
                         PermissionDeniedException

Creates a new Lease.

Parameters:

leaseForm - the form for this Lease

Returns:

the new Lease

Throws:

IllegalStateException - leaseForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - leaseForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - leaseForm did not originate from getLeaseFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateLeases

boolean canUpdateLeases()

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

Compliance:

mandatory - This method must be implemented.

getLeaseFormForUpdate

LeaseForm getLeaseFormForUpdate(Id leaseId)
                                throws NotFoundException,
                                       OperationFailedException,
                                       PermissionDeniedException

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

Parameters:

leaseId - the Id of the Lease

Returns:

the lease form

Throws:

NotFoundException - leaseId is not found

NullArgumentException - leaseId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateLease

void updateLease(LeaseForm leaseForm)
                 throws OperationFailedException,
                        PermissionDeniedException

Updates an existing lease.

Parameters:

leaseForm - the form containing the elements to be updated

Throws:

IllegalStateException - leaseForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - leaseForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - leaseForm did not originate from getLeaseFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteLeases

boolean canDeleteLeases()

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

Compliance:

mandatory - This method must be implemented.

deleteLease

void deleteLease(Id leaseId)
                 throws NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

Deletes a Lease.

Parameters:

leaseId - the Id of the Lease to remove

Throws:

NotFoundException - leaseId not found

NullArgumentException - leaseId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageLeaseAliases

boolean canManageLeaseAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasLease

void aliasLease(Id leaseId,
              Id aliasId)
                throws AlreadyExistsException,
                       NotFoundException,
                       OperationFailedException,
                       PermissionDeniedException

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

Parameters:

leaseId - the Id of a Lease

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - leaseId not found

NullArgumentException - leaseId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.