org.osid.profile

Interface ProfileEntryAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

ProfileEntryBatchAdminSession

public interface ProfileEntryAdminSession
extends OsidSession

This session creates and removes ProfileEntries. An ProfileEntry may be defined using an Agent or a Resource. Create and delete methods exist for each type desired.

An explicit ProfileEntry is identified by the mapping among a Resource/Agent and ProfileItem. There can be only one explicit ProfileEntry for each triplet however multiple implicit ProfileEntries may exist.

When a profile entry is created, it is disabled until enableProfileEntry() is used.

Create and update operations differ in their usage. To create a ProfileEntry, a ProfileEntryForm is requested using geProfileEntryFormFormForCreate() specifying the profile item, resource or agent, and desired record Types or none if no record Types are needed. The returned ProfileEntryForm 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 ProfileEntryForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each ProfileEntryForm corresponds to an attempted transaction.

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

The delete operations delete ProfileEntries. To unmap a ProfileEntry from the current Profile the ProfileEntryProfileAssignmentSession should be used. These delete operations attempt to remove the ProfileEntry 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	aliasProfileEntry(Id profileEntryId, Id aliasId) Adds an Id to an ProfileEntry for the purpose of creating compatibility.
boolean	canCreateProfileEntries() Tests if this user can create ProfileEntries.
boolean	canCreateProfileEntryWithRecordTypes(Type[] profileEntryRecordTypes) Tests if this user can create a single ProfileEntry using the desired record types.
boolean	canDeleteProfileEntries() Tests if this user can delete ProfileEntries.
boolean	canManageProfileEntryAliases() Tests if this user can manage Id aliases for profile entries.
boolean	canUpdateProfileEntries() Tests if this user can update ProfileEntries.
ProfileEntry	createProfileEntry(ProfileEntryForm profileEntryForm) Creates a new ProfileEntry.
void	deleteProfileEntry(Id profileEntryId) Deletes the ProfileEntry identified by the given Id.
Profile	getProfile() Gets the Profile associated with this session.
ProfileEntryForm	getProfileEntryFormForCreateForAgent(Id agentId, Id profileItemId, Type[] profileEntryRecordTypes) Gets the profile entry form for creating new profile entries.
ProfileEntryForm	getProfileEntryFormForCreateForResource(Id resourceId, Id profileItemId) Gets the profile entry form for creating new profile entries.
ProfileEntryForm	getProfileEntryFormForUpdate(Id profileEntryId) Gets the profile entry form for updating an existing profile entry.
Id	getProfileId() Gets the Profile Id associated with this session.
void	updateProfileEntry(ProfileEntryForm profileEntryForm) Updates an existing profile entry.

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.

canCreateProfileEntries

boolean canCreateProfileEntries()

Tests if this user can create ProfileEntries. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer create operations to unauthorized users.

Returns:

false if ProfileEntry creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateProfileEntryWithRecordTypes

boolean canCreateProfileEntryWithRecordTypes(Type[] profileEntryRecordTypes)

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

Parameters:

profileEntryRecordTypes - array of profile entry types

Returns:

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

Throws:

NullArgumentException - profileEntryRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getProfileEntryFormForCreateForAgent

ProfileEntryForm getProfileEntryFormForCreateForAgent(Id agentId,
                                                    Id profileItemId,
                                                    Type[] profileEntryRecordTypes)
                                                      throws NotFoundException,
                                                             OperationFailedException,
                                                             PermissionDeniedException

Gets the profile entry form for creating new profile entries. A new form should be requested for each create transaction.

Parameters:

agentId - the agent Id

profileItemId - the profile item Id

profileEntryRecordTypes - array of profile entry types

Returns:

the profile entry form

Throws:

NotFoundException - agentId or profileItemId is not found

NullArgumentException - agentId or profileItemId 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.

getProfileEntryFormForCreateForResource

ProfileEntryForm getProfileEntryFormForCreateForResource(Id resourceId,
                                                       Id profileItemId)
                                                         throws NotFoundException,
                                                                OperationFailedException,
                                                                PermissionDeniedException

Gets the profile entry form for creating new profile entries. A new form should be requested for each create transaction.

Parameters:

resourceId - the resource Id

profileItemId - the profile item Id

Returns:

the profile entry form

Throws:

NotFoundException - resourceId or profileItemId is not found

NullArgumentException - resourceId or profileItemId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

createProfileEntry

ProfileEntry createProfileEntry(ProfileEntryForm profileEntryForm)
                                throws OperationFailedException,
                                       PermissionDeniedException

Creates a new ProfileEntry.

Parameters:

profileEntryForm - the profile entry form

Returns:

t he new ProfileEntry

Throws:

IllegalStateException - profileEntryForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - profileEntryForm null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - profileEntryForm did not originate from getprofileEntryFormForAgent() or getProfileEntryFormForResource()

Compliance:

mandatory - This method must be implemented.

canUpdateProfileEntries

boolean canUpdateProfileEntries()

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

Compliance:

mandatory - This method must be implemented.

getProfileEntryFormForUpdate

ProfileEntryForm getProfileEntryFormForUpdate(Id profileEntryId)
                                              throws NotFoundException,
                                                     OperationFailedException,
                                                     PermissionDeniedException

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

Parameters:

profileEntryId - the Id of the ProfileEntry

Returns:

the profile entry form

Throws:

NotFoundException - profileEntryId is not found

NullArgumentException - profileEntryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateProfileEntry

void updateProfileEntry(ProfileEntryForm profileEntryForm)
                        throws OperationFailedException,
                               PermissionDeniedException

Updates an existing profile entry.

Parameters:

profileEntryForm - the profile entry form

Throws:

IllegalStateException - profileEntryForm already used in an update transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - profileEntryForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - profileEntryForm did not originate from getProfileEntryFormForCreate()

Compliance:

mandatory - This method must be implemented.

canDeleteProfileEntries

boolean canDeleteProfileEntries()

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

Compliance:

mandatory - This method must be implemented.

deleteProfileEntry

void deleteProfileEntry(Id profileEntryId)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Deletes the ProfileEntry identified by the given Id.

Parameters:

profileEntryId - the Id of the ProfileEntry to delete

Throws:

NotFoundException - an ProfileEntry was not found identified by the given Id

NullArgumentException - profileEntryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageProfileEntryAliases

boolean canManageProfileEntryAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasProfileEntry

void aliasProfileEntry(Id profileEntryId,
                     Id aliasId)
                       throws AlreadyExistsException,
                              NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Adds an Id to an ProfileEntry for the purpose of creating compatibility. The primary Id of the ProfileEntry 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 entry it is reassigned to the given profile entry Id.

Parameters:

profileEntryId - the Id of an ProfileEntry

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - profileEntryId not found

NullArgumentException - profileEntryId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.