org.osid.offering

Interface ParticipantAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

ParticipantBatchAdminSession

public interface ParticipantAdminSession
extends OsidSession

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

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

The delete operations delete Participants. To unmap a Participant from the current Catalogue, the ParticipantCatalogueAssignmentSession should be used. These delete operations attempt to remove the Participant itself thus removing it from all known Catalogue 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	aliasParticipant(Id participantId, Id aliasId) Adds an Id to a Participant for the purpose of creating compatibility.
boolean	canCreateParticipants() Tests if this user can create participants.
boolean	canCreateParticipantWithRecordTypes(Type[] participantRecordTypes) Tests if this user can create a single Participant using the desired record types.
boolean	canDeleteParticipants() Tests if this user can delete participants.
boolean	canManageParticipantAliases() Tests if this user can manage Id aliases for Participants.
boolean	canUpdateParticipants() Tests if this user can update participants.
Participant	createParticipant(ParticipantForm participantForm) Creates a new Participant.
void	deleteParticipant(Id participantId) Deletes a Participant.
Catalogue	getCatalogue() Gets the Catalogue associated with this session.
Id	getCatalogueId() Gets the Catalogue Id associated with this session.
ParticipantForm	getParticipantFormForCreate(Id offeringId, Id resourceId, Type[] participantRecordTypes) Gets the participant form for creating new participants.
ParticipantForm	getParticipantFormForUpdate(Id participantId) Gets the participant form for updating an existing participant.
void	updateParticipant(ParticipantForm participantForm) Updates an existing participant.

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

getCatalogueId

Id getCatalogueId()

Gets the Catalogue Id associated with this session.

Returns:

the Catalogue Id associated with this session

Compliance:

mandatory - This method must be implemented.

getCatalogue

Catalogue getCatalogue()
                       throws OperationFailedException,
                              PermissionDeniedException

Gets the Catalogue associated with this session.

Returns:

the catalogue

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateParticipants

boolean canCreateParticipants()

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

Compliance:

mandatory - This method must be implemented.

canCreateParticipantWithRecordTypes

boolean canCreateParticipantWithRecordTypes(Type[] participantRecordTypes)

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

Parameters:

participantRecordTypes - array of participant record types

Returns:

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

Throws:

NullArgumentException - participantRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getParticipantFormForCreate

ParticipantForm getParticipantFormForCreate(Id offeringId,
                                          Id resourceId,
                                          Type[] participantRecordTypes)
                                            throws NotFoundException,
                                                   OperationFailedException,
                                                   PermissionDeniedException

Gets the participant form for creating new participants. A new form should be requested for each create transaction.

Parameters:

offeringId - the offering Id to which this participant belongs

resourceId - the resource Id for this participant

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

Returns:

the participant form

Throws:

NotFoundException - offeringId or resourceId is not found

NullArgumentException - offeringId, resourceId, or participantRecordTypes 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.

createParticipant

Participant createParticipant(ParticipantForm participantForm)
                              throws OperationFailedException,
                                     PermissionDeniedException

Creates a new Participant.

Parameters:

participantForm - the form for this Participant

Returns:

the new Participant

Throws:

IllegalStateException - participantForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - participantForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - participantForm did not originate from getParticipantFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateParticipants

boolean canUpdateParticipants()

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

Compliance:

mandatory - This method must be implemented.

getParticipantFormForUpdate

ParticipantForm getParticipantFormForUpdate(Id participantId)
                                            throws NotFoundException,
                                                   OperationFailedException,
                                                   PermissionDeniedException

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

Parameters:

participantId - the Id of the Participant

Returns:

the participant form

Throws:

NotFoundException - participantId is not found

NullArgumentException - participantId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateParticipant

void updateParticipant(ParticipantForm participantForm)
                       throws OperationFailedException,
                              PermissionDeniedException

Updates an existing participant.

Parameters:

participantForm - the form containing the elements to be updated

Throws:

IllegalStateException - participantForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - participantForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - participantForm did not originate from getParticipantFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteParticipants

boolean canDeleteParticipants()

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

Compliance:

mandatory - This method must be implemented.

deleteParticipant

void deleteParticipant(Id participantId)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Deletes a Participant.

Parameters:

participantId - the Id of the Participant to remove

Throws:

NotFoundException - participantId not found

NullArgumentException - participantId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageParticipantAliases

boolean canManageParticipantAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasParticipant

void aliasParticipant(Id participantId,
                    Id aliasId)
                      throws AlreadyExistsException,
                             NotFoundException,
                             OperationFailedException,
                             PermissionDeniedException

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

Parameters:

participantId - the Id of a Participant

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is in use as a primary Id

NotFoundException - participantId not found

NullArgumentException - participantId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.