org.osid.personnel

Interface PositionAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

PositionBatchAdminSession

public interface PositionAdminSession
extends OsidSession

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

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

The delete operations delete Positions. To unmap a Position from the current Realm, the PositionRealmAssignmentSession should be used. These delete operations attempt to remove the Position itself thus removing it from all known Realm 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	aliasPosition(Id positionId, Id aliasId) Adds an Id to a Position for the purpose of creating compatibility.
boolean	canCreatePositions() Tests if this user can create positions.
boolean	canCreatePositionWithRecordTypes(Type[] positionRecordTypes) Tests if this user can create a single Position using the desired record types.
boolean	canDeletePositions() Tests if this user can delete positions.
boolean	canManagePositionAliases() Tests if this user can manage Id aliases for Positions.
boolean	canUpdatePositions() Tests if this user can update positions.
Position	createPosition(PositionForm positionForm) Creates a new Position.
void	deletePosition(Id positionId) Deletes a Position.
PositionForm	getPositionFormForCreate(Id organizationId, Type[] positionRecordTypes) Gets the position form for creating new positions.
PositionForm	getPositionFormForUpdate(Id positionId) Gets the position form for updating an existing position.
Realm	getRealm() Gets the Realm associated with this session.
Id	getRealmId() Gets the Realm Id associated with this session.
void	updatePosition(PositionForm positionForm) Updates an existing position.

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

getRealmId

Id getRealmId()

Gets the Realm Id associated with this session.

Returns:

the Realm Id associated with this session

Compliance:

mandatory - This method must be implemented.

getRealm

Realm getRealm()
               throws OperationFailedException,
                      PermissionDeniedException

Gets the Realm associated with this session.

Returns:

the realm

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreatePositions

boolean canCreatePositions()

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

Compliance:

mandatory - This method must be implemented.

canCreatePositionWithRecordTypes

boolean canCreatePositionWithRecordTypes(Type[] positionRecordTypes)

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

Parameters:

positionRecordTypes - array of position record types

Returns:

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

Throws:

NullArgumentException - positionRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getPositionFormForCreate

PositionForm getPositionFormForCreate(Id organizationId,
                                    Type[] positionRecordTypes)
                                      throws NotFoundException,
                                             OperationFailedException,
                                             PermissionDeniedException

Gets the position form for creating new positions. A new form should be requested for each create transaction.

Parameters:

organizationId - the organization Id to which this position belongs

positionRecordTypes - array of position record types to be included in the create operation or an empty list if none

Returns:

the position form

Throws:

NotFoundException - organizationId is not found

NullArgumentException - organizationId or positionRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - cannot get form for requested record types

Compliance:

mandatory - This method must be implemented.

createPosition

Position createPosition(PositionForm positionForm)
                        throws OperationFailedException,
                               PermissionDeniedException

Creates a new Position.

Parameters:

positionForm - the form for this Position

Returns:

the new Position

Throws:

IllegalStateException - positionForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - positionForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - positionForm did not originate from getPositionFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdatePositions

boolean canUpdatePositions()

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

Compliance:

mandatory - This method must be implemented.

getPositionFormForUpdate

PositionForm getPositionFormForUpdate(Id positionId)
                                      throws NotFoundException,
                                             OperationFailedException,
                                             PermissionDeniedException

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

Parameters:

positionId - the Id of the Position

Returns:

the position form

Throws:

NotFoundException - positionId is not found

NullArgumentException - positionId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updatePosition

void updatePosition(PositionForm positionForm)
                    throws OperationFailedException,
                           PermissionDeniedException

Updates an existing position.

Parameters:

positionForm - the form containing the elements to be updated

Throws:

IllegalStateException - positionForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - positionForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - positionForm did not originate from getPositionFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeletePositions

boolean canDeletePositions()

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

Compliance:

mandatory - This method must be implemented.

deletePosition

void deletePosition(Id positionId)
                    throws NotFoundException,
                           OperationFailedException,
                           PermissionDeniedException

Deletes a Position.

Parameters:

positionId - the Id of the Position to remove

Throws:

NotFoundException - positionId not found

NullArgumentException - positionId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManagePositionAliases

boolean canManagePositionAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasPosition

void aliasPosition(Id positionId,
                 Id aliasId)
                   throws AlreadyExistsException,
                          NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

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

Parameters:

positionId - the Id of a Position

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is in use as a primary Id

NotFoundException - positionId not found

NullArgumentException - positionId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.