org.osid.personnel

Interface PersonAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

PersonBatchAdminSession

public interface PersonAdminSession
extends OsidSession

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

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

The delete operations delete Persons. To unmap a Person from the current Realm, the PersonRealmAssignmentSession should be used. These delete operations attempt to remove the Person 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	aliasPerson(Id personId, Id aliasId) Adds an Id to a Person for the purpose of creating compatibility.
boolean	canCreatePersons() Tests if this user can create persons.
boolean	canCreatePersonWithRecordTypes(Type[] personRecordTypes) Tests if this user can create a single Person using the desired record types.
boolean	canDeletePersons() Tests if this user can delete persons.
boolean	canManagePersonAliases() Tests if this user can manage Id aliases for Persons.
boolean	canUpdatePersons() Tests if this user can update persons.
Person	createPerson(PersonForm personForm) Creates a new Person.
void	deletePerson(Id personId) Deletes a Person.
PersonForm	getPersonFormForCreate(Type[] personRecordTypes) Gets the person form for creating new persons.
PersonForm	getPersonFormForUpdate(Id personId) Gets the person form for updating an existing person.
Realm	getRealm() Gets the Realm associated with this session.
Id	getRealmId() Gets the Realm Id associated with this session.
void	updatePerson(PersonForm personForm) Updates an existing person.

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.

canCreatePersons

boolean canCreatePersons()

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

Compliance:

mandatory - This method must be implemented.

canCreatePersonWithRecordTypes

boolean canCreatePersonWithRecordTypes(Type[] personRecordTypes)

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

Parameters:

personRecordTypes - array of person record types

Returns:

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

Throws:

NullArgumentException - personRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getPersonFormForCreate

PersonForm getPersonFormForCreate(Type[] personRecordTypes)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Gets the person form for creating new persons. A new form should be requested for each create transaction.

Parameters:

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

Returns:

the person form

Throws:

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

createPerson

Person createPerson(PersonForm personForm)
                    throws OperationFailedException,
                           PermissionDeniedException

Creates a new Person.

Parameters:

personForm - the form for this Person

Returns:

the new Person

Throws:

IllegalStateException - personForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - personForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - personForm did not originate from getPersonFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdatePersons

boolean canUpdatePersons()

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

Compliance:

mandatory - This method must be implemented.

getPersonFormForUpdate

PersonForm getPersonFormForUpdate(Id personId)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

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

Parameters:

personId - the Id of the Person

Returns:

the person form

Throws:

NotFoundException - personId is not found

NullArgumentException - personId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updatePerson

void updatePerson(PersonForm personForm)
                  throws OperationFailedException,
                         PermissionDeniedException

Updates an existing person.

Parameters:

personForm - the form containing the elements to be updated

Throws:

IllegalStateException - personForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - personForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - personForm did not originate from getPersonFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeletePersons

boolean canDeletePersons()

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

Compliance:

mandatory - This method must be implemented.

deletePerson

void deletePerson(Id personId)
                  throws NotFoundException,
                         OperationFailedException,
                         PermissionDeniedException

Deletes a Person.

Parameters:

personId - the Id of the Person to remove

Throws:

NotFoundException - personId not found

NullArgumentException - personId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManagePersonAliases

boolean canManagePersonAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasPerson

void aliasPerson(Id personId,
               Id aliasId)
                 throws AlreadyExistsException,
                        NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

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

Parameters:

personId - the Id of a Person

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is in use as a primary Id

NotFoundException - personId not found

NullArgumentException - personId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.