Interface PositionAdminSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, 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 Details

    • 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.