org.osid.profile

Interface ProfileItemAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

ProfileItemBatchAdminSession

public interface ProfileItemAdminSession
extends OsidSession

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

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

The delete operations delete ProfileItems. To unmap a ProfileItem from the current Profile the ProfileItemProfileAssignmentSession should be used. These delete operations attempt to remove the ProfileItem itself thus removing it from all known Profile 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	aliasProfileItem(Id profileItemId, Id aliasId) Adds an Id to a ProfileItem for the purpose of creating compatibility.
boolean	canCreateProfileItems() Tests if this user can create ProfileItems.
boolean	canCreateProfileItemWithRecordTypes(Type[] profileItemRecordTypes) Tests if this user can create a single ProfileItem using the desired record types.
boolean	canDeleteProfileItems() Tests if this user can delete ProfileItems.
boolean	canManageProfileItemAliases() Tests if this user can manage Id aliases for ProfileItems.
boolean	canUpdateProfileItems() Tests if this user can update ProfileItems.
ProfileItem	createProfileItem(ProfileItemForm profileItemForm) Creates a new ProfileItem.
void	deleteProfileItem(Id profileItemId) Deletes the ProfileItem identified by the given Id.
Profile	getProfile() Gets the Profile associated with this session.
Id	getProfileId() Gets the Profile Id associated with this session.
ProfileItemForm	getProfileItemFormForCreate(Type[] profileItemRecordTypes) Gets the profile item form for creating new profile items.
ProfileItemForm	getProfileItemFormForUpdate(Id profileItemId) Gets the profile item form for updating an existing profile item.
void	updateProfileItem(ProfileItemForm profileItemForm) Updates an existing profile item.

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

getProfileId

Id getProfileId()

Gets the Profile Id associated with this session.

Returns:

the Profile Id associated with this session

Compliance:

mandatory - This method must be implemented.

getProfile

Profile getProfile()
                   throws OperationFailedException,
                          PermissionDeniedException

Gets the Profile associated with this session.

Returns:

the Profile associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateProfileItems

boolean canCreateProfileItems()

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

Compliance:

mandatory - This method must be implemented.

canCreateProfileItemWithRecordTypes

boolean canCreateProfileItemWithRecordTypes(Type[] profileItemRecordTypes)

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

Parameters:

profileItemRecordTypes - array of profile item record types

Returns:

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

Throws:

NullArgumentException - profileItemRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getProfileItemFormForCreate

ProfileItemForm getProfileItemFormForCreate(Type[] profileItemRecordTypes)
                                            throws OperationFailedException,
                                                   PermissionDeniedException

Gets the profile item form for creating new profile items. A new form should be requested for each create transaction.

Parameters:

profileItemRecordTypes - array of profile item record types

Returns:

the profile item form

Throws:

NullArgumentException - profileItemRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form with requested record types

Compliance:

mandatory - This method must be implemented.

createProfileItem

ProfileItem createProfileItem(ProfileItemForm profileItemForm)
                              throws OperationFailedException,
                                     PermissionDeniedException

Creates a new ProfileItem.

Parameters:

profileItemForm - the form for this ProfileItem

Returns:

the new ProfileItem

Throws:

IllegalStateException - profileItemForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - profileItemForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - profileItemForm did not originate from getProfileItemFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateProfileItems

boolean canUpdateProfileItems()

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

Compliance:

mandatory - This method must be implemented.

getProfileItemFormForUpdate

ProfileItemForm getProfileItemFormForUpdate(Id profileItemId)
                                            throws NotFoundException,
                                                   OperationFailedException

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

Parameters:

profileItemId - the Id of the ProfileItem

Returns:

the profile item form

Throws:

NotFoundException - profileItemId is not found

NullArgumentException - profileItemId is null

OperationFailedException - unable to complete request

Compliance:

mandatory - This method must be implemented.

updateProfileItem

void updateProfileItem(ProfileItemForm profileItemForm)
                       throws OperationFailedException,
                              PermissionDeniedException

Updates an existing profile item.

Parameters:

profileItemForm - the form containing the elements to be updated

Throws:

IllegalStateException - profileItemForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - profileItemForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - profileItemForm did not originate from getProfileItemFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteProfileItems

boolean canDeleteProfileItems()

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

Compliance:

mandatory - This method must be implemented.

deleteProfileItem

void deleteProfileItem(Id profileItemId)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Deletes the ProfileItem identified by the given Id.

Parameters:

profileItemId - the Id of the ProfileItem to delete

Throws:

NotFoundException - a ProfileItem was not found identified by the given Id

NullArgumentException - profileItemId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageProfileItemAliases

boolean canManageProfileItemAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasProfileItem

void aliasProfileItem(Id profileItemId,
                    Id aliasId)
                      throws AlreadyExistsException,
                             NotFoundException,
                             OperationFailedException,
                             PermissionDeniedException

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

Parameters:

profileItemId - the Id of a ProfileItem

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - profileItemId not found

NullArgumentException - profileItemId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.