org.osid.resourcing

Interface AvailabilityAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

AvailabilityBatchAdminSession

public interface AvailabilityAdminSession
extends OsidSession

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

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

The delete operations delete Availabilities. To unmap an Availability from the current Foundry, the AvailabilityFoundryAssignmentSession should be used. These delete operations attempt to remove the Availability itself thus removing it from all known Foundry 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	aliasAvailability(Id availabilityId, Id aliasId) Adds an Id to an Availability for the purpose of creating compatibility.
boolean	canCreateAvailabilities() Tests if this user can create Availabilities.
boolean	canCreateAvailabilityWithRecordTypes(Type[] availabilityRecordTypes) Tests if this user can create a single Availability using the desired record types.
boolean	canDeleteAvailabilities() Tests if this user can delete Availabilities.
boolean	canManageAvailabilityAliases() Tests if this user can manage Id aliases for Availabilities.
boolean	canUpdateAvailabilities() Tests if this user can update Availabilities.
Availability	createAvailability(AvailabilityForm availabilityForm) Creates a new Availability.
void	deleteAvailability(Id availabilityId) Deletes an Availability.
AvailabilityForm	getAvailabilityFormForCreate(Id resourceId, Id jobId, Type[] availabilityRecordTypes) Gets the availability form for creating new availabilities.
AvailabilityForm	getAvailabilityFormForUpdate(Id availabilityId) Gets the availability form for updating an existing availability.
Foundry	getFoundry() Gets the Foundry associated with this session.
Id	getFoundryId() Gets the Foundry Id associated with this session.
void	updateAvailability(AvailabilityForm availabilityForm) Updates an existing availability.

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

getFoundryId

Id getFoundryId()

Gets the Foundry Id associated with this session.

Returns:

the Foundry Id associated with this session

Compliance:

mandatory - This method must be implemented.

getFoundry

Foundry getFoundry()
                   throws OperationFailedException,
                          PermissionDeniedException

Gets the Foundry associated with this session.

Returns:

the foundry

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateAvailabilities

boolean canCreateAvailabilities()

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

Compliance:

mandatory - This method must be implemented.

canCreateAvailabilityWithRecordTypes

boolean canCreateAvailabilityWithRecordTypes(Type[] availabilityRecordTypes)

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

Parameters:

availabilityRecordTypes - array of availability record types

Returns:

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

Throws:

NullArgumentException - availabilityRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getAvailabilityFormForCreate

AvailabilityForm getAvailabilityFormForCreate(Id resourceId,
                                            Id jobId,
                                            Type[] availabilityRecordTypes)
                                              throws NotFoundException,
                                                     OperationFailedException,
                                                     PermissionDeniedException

Gets the availability form for creating new availabilities. A new form should be requested for each create transaction.

Parameters:

resourceId - the Id for the resource

jobId - the Id for the job

availabilityRecordTypes - array of availability record types

Returns:

the availability form

Throws:

NotFoundException - resourceId or jobId is not found

NullArgumentException - resourceId, jobId, or availabilityRecordTypes 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.

createAvailability

Availability createAvailability(AvailabilityForm availabilityForm)
                                throws OperationFailedException,
                                       PermissionDeniedException

Creates a new Availability.

Parameters:

availabilityForm - the form for this Availability

Returns:

the new Availability

Throws:

IllegalStateException - availabilityForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - availabilityForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - availabilityForm did not originate from getAvailabilityFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateAvailabilities

boolean canUpdateAvailabilities()

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

Compliance:

mandatory - This method must be implemented.

getAvailabilityFormForUpdate

AvailabilityForm getAvailabilityFormForUpdate(Id availabilityId)
                                              throws NotFoundException,
                                                     OperationFailedException,
                                                     PermissionDeniedException

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

Parameters:

availabilityId - the Id of the Availability

Returns:

the availability form

Throws:

NotFoundException - availabilityId is not found

NullArgumentException - availabilityId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateAvailability

void updateAvailability(AvailabilityForm availabilityForm)
                        throws OperationFailedException,
                               PermissionDeniedException

Updates an existing availability.

Parameters:

availabilityForm - the form containing the elements to be updated

Throws:

IllegalStateException - availabilityForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - availabilityForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - availabilityForm did not originate from getAvailabilityFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteAvailabilities

boolean canDeleteAvailabilities()

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

Compliance:

mandatory - This method must be implemented.

deleteAvailability

void deleteAvailability(Id availabilityId)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Deletes an Availability.

Parameters:

availabilityId - the Id of the Availability to remove

Throws:

NotFoundException - availabilityId not found

NullArgumentException - availabilityId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageAvailabilityAliases

boolean canManageAvailabilityAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasAvailability

void aliasAvailability(Id availabilityId,
                     Id aliasId)
                       throws AlreadyExistsException,
                              NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

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

Parameters:

availabilityId - the Id of an Availability

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - availabilityId not found

NullArgumentException - availabilityId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.