org.osid.room

Interface BuildingAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

BuildingBatchAdminSession

public interface BuildingAdminSession
extends OsidSession

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

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

The delete operations delete Buildings. To unmap a Building from the current Campus, the BuildingCampusAssignmentSession should be used. These delete operations attempt to remove the Building 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	aliasBuilding(Id buildingId, Id aliasId) Adds an Id to a Building for the purpose of creating compatibility.
boolean	canCreateBuildings() Tests if this user can create Buildings.
boolean	canCreateBuildingWithRecordTypes(Type[] buildingRecordTypes) Tests if this user can create a single Building using the desired record interface types.
boolean	canDeleteBuildings() Tests if this user can delete Buildings A return of true does not guarantee successful authorization.
boolean	canManageBuildingAliases() Tests if this user can manage Id aliases for Buildings.
boolean	canUpdateBuildings() Tests if this user can update Buildings.
Building	createBuilding(BuildingForm buildingForm) Creates a new Building.
void	deleteBuilding(Id buildingId) Deletes a Building.
BuildingForm	getBuildingFormForCreate(Type[] buildingRecordTypes) Gets the building form for creating new buildings.
BuildingForm	getBuildingFormForUpdate(Id buildingId) Gets the building form for updating an existing building.
Campus	getCampus() Gets the Campus associated with this session.
Id	getCampusId() Gets the Campus Id associated with this session.
void	updateBuilding(BuildingForm buildingForm) Updates an existing building.

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.

canCreateBuildings

boolean canCreateBuildings()

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

Compliance:

mandatory - This method must be implemented.

canCreateBuildingWithRecordTypes

boolean canCreateBuildingWithRecordTypes(Type[] buildingRecordTypes)

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

Parameters:

buildingRecordTypes - array of building record types

Returns:

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

Throws:

NullArgumentException - buildingRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getBuildingFormForCreate

BuildingForm getBuildingFormForCreate(Type[] buildingRecordTypes)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Gets the building form for creating new buildings. A new form should be requested for each create transaction.

Parameters:

buildingRecordTypes - array of building record types

Returns:

the building form

Throws:

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

createBuilding

Building createBuilding(BuildingForm buildingForm)
                        throws OperationFailedException,
                               PermissionDeniedException

Creates a new Building.

Parameters:

buildingForm - the form for this Building

Returns:

the new Building

Throws:

IllegalStateException - buildingForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - buildingForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - buildingForm did not originate from getBuildingFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateBuildings

boolean canUpdateBuildings()

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

Compliance:

mandatory - This method must be implemented.

getBuildingFormForUpdate

BuildingForm getBuildingFormForUpdate(Id buildingId)
                                      throws NotFoundException,
                                             OperationFailedException,
                                             PermissionDeniedException

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

Parameters:

buildingId - the Id of the Building

Returns:

the building form

Throws:

NotFoundException - buildingId is not found

NullArgumentException - buildingId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateBuilding

void updateBuilding(BuildingForm buildingForm)
                    throws OperationFailedException,
                           PermissionDeniedException

Updates an existing building.

Parameters:

buildingForm - the form containing the elements to be updated

Throws:

IllegalStateException - buildingForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - buildingForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - buildingForm did not originate from getBuildingFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteBuildings

boolean canDeleteBuildings()

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

Compliance:

mandatory - This method must be implemented.

deleteBuilding

void deleteBuilding(Id buildingId)
                    throws NotFoundException,
                           OperationFailedException,
                           PermissionDeniedException

Deletes a Building.

Parameters:

buildingId - the Id of the Building to remove

Throws:

NotFoundException - buildingId not found

NullArgumentException - buildingId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageBuildingAliases

boolean canManageBuildingAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasBuilding

void aliasBuilding(Id buildingId,
                 Id aliasId)
                   throws AlreadyExistsException,
                          NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

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

Parameters:

buildingId - the Id of a Building

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - buildingId not found

NullArgumentException - buildingId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.