org.osid.authorization

Interface AuthorizationAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

AuthorizationBatchAdminSession

public interface AuthorizationAdminSession
extends OsidSession

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

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

The delete operations delete Authorizations. To unmap an Authorization from the current Vault, the AuthorizationVaultAssignmentSession should be used. These delete operations attempt to remove the Authorization itself thus removing it from all known Vault 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	aliasAuthorization(Id authorizationId, Id aliasId) Adds an Id to an Authorization for the purpose of creating compatibility.
boolean	canCreateAuthorizations() Tests if this user can create Authorizations.
boolean	canCreateAuthorizationWithRecordTypes(Type[] authorizationRecordTypes) Tests if this user can create a single Authorization using the desired record types.
boolean	canDeleteAuthorizations() Tests if this user can delete Authorizations.
boolean	canManageAuthorizationAliases() Tests if this user can manage Id aliases for Authorizations.
boolean	canUpdateAuthorizations() Tests if this user can update Authorizations.
Authorization	createAuthorization(AuthorizationForm authorizationForm) Creates a new explicit Authorization.
void	deleteAuthorization(Id authorizationId) Deletes the Authorization identified by the given Id.
AuthorizationForm	getAuthorizationFormForCreateForAgent(Id agentId, Id functionId, Id qualifierId, Type[] authorizationRecordTypes) Gets the authorization form for creating new authorizations.
AuthorizationForm	getAuthorizationFormForCreateForResource(Id resourceId, Id functionId, Id qualifierId, Type[] authorizationRecordTypes) Gets the authorization form for creating new authorizations.
AuthorizationForm	getAuthorizationFormForCreateForResourceAndTrust(Id resourceId, Id trustId, Id functionId, Id qualifierId, Type[] authorizationRecordTypes) Gets the authorization form for creating new authorizations.
AuthorizationForm	getAuthorizationFormForUpdate(Id authorizationId) Gets the authorization form for updating an existing authorization.
Vault	getVault() Gets the Vault associated with this session.
Id	getVaultId() Gets the Vault Id associated with this session.
void	updateAuthorization(AuthorizationForm authorizationForm) Updates an existing authorization

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

getVaultId

Id getVaultId()

Gets the Vault Id associated with this session.

Returns:

the Vault Id associated with this session

Compliance:

mandatory - This method must be implemented.

getVault

Vault getVault()
               throws OperationFailedException,
                      PermissionDeniedException

Gets the Vault associated with this session.

Returns:

the Vault associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateAuthorizations

boolean canCreateAuthorizations()

Tests if this user can create Authorizations. 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 Authorization creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateAuthorizationWithRecordTypes

boolean canCreateAuthorizationWithRecordTypes(Type[] authorizationRecordTypes)

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

Parameters:

authorizationRecordTypes - array of authorization record types

Returns:

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

Throws:

NullArgumentException - authorizationRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getAuthorizationFormForCreateForAgent

AuthorizationForm getAuthorizationFormForCreateForAgent(Id agentId,
                                                      Id functionId,
                                                      Id qualifierId,
                                                      Type[] authorizationRecordTypes)
                                                        throws NotFoundException,
                                                               OperationFailedException,
                                                               PermissionDeniedException

Gets the authorization form for creating new authorizations. A new form should be requested for each create transaction.

Parameters:

agentId - the agent Id

functionId - the function Id

qualifierId - the qualifier Id

authorizationRecordTypes - array of authorization record types

Returns:

the authorization form

Throws:

NotFoundException - agentId, functionId or qualifierId is not found

NullArgumentException - agentId, functionId, qualifierId or authorizationRecordTypes 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.

getAuthorizationFormForCreateForResource

AuthorizationForm getAuthorizationFormForCreateForResource(Id resourceId,
                                                         Id functionId,
                                                         Id qualifierId,
                                                         Type[] authorizationRecordTypes)
                                                           throws NotFoundException,
                                                                  OperationFailedException,
                                                                  PermissionDeniedException

Gets the authorization form for creating new authorizations. A new form should be requested for each create transaction.

Parameters:

resourceId - the resource Id

functionId - the function Id

qualifierId - the qualifier Id

authorizationRecordTypes - array of authorization record types

Returns:

the authorization form

Throws:

NotFoundException - resourceId, functionId or qualifierId is not found

NullArgumentException - resourceId, functionId, qualifierId, or authorizationRecordTypes 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.

getAuthorizationFormForCreateForResourceAndTrust

AuthorizationForm getAuthorizationFormForCreateForResourceAndTrust(Id resourceId,
                                                                 Id trustId,
                                                                 Id functionId,
                                                                 Id qualifierId,
                                                                 Type[] authorizationRecordTypes)
                                                                   throws NotFoundException,
                                                                          OperationFailedException,
                                                                          PermissionDeniedException

Gets the authorization form for creating new authorizations. A new form should be requested for each create transaction.

Parameters:

resourceId - a resource Id

trustId - an Id for a circle of trust

functionId - a function Id

qualifierId - the qualifier Id

authorizationRecordTypes - array of authorization record types

Returns:

the authorization form

Throws:

NotFoundException - resourceId, trustId, functionId , or qualifierid is not found

NullArgumentException - resourceId, trustId , resourceId, qualifierId or authorizationRecordTypes 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.

createAuthorization

Authorization createAuthorization(AuthorizationForm authorizationForm)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Creates a new explicit Authorization.

Parameters:

authorizationForm - the authorization form

Returns:

t he new Authorization

Throws:

IllegalStateException - authorizationForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - authorizationForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - authorizationForm did not originate from this service

Compliance:

mandatory - This method must be implemented.

canUpdateAuthorizations

boolean canUpdateAuthorizations()

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

Compliance:

mandatory - This method must be implemented.

getAuthorizationFormForUpdate

AuthorizationForm getAuthorizationFormForUpdate(Id authorizationId)
                                                throws NotFoundException,
                                                       OperationFailedException,
                                                       PermissionDeniedException

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

Parameters:

authorizationId - the Id of the Authorization

Returns:

the authorization form

Throws:

NotFoundException - authorizationId is not found

NullArgumentException - authorizationId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateAuthorization

void updateAuthorization(AuthorizationForm authorizationForm)
                         throws OperationFailedException,
                                PermissionDeniedException

Updates an existing authorization

Parameters:

authorizationForm - the authorization Id

Throws:

IllegalStateException - authorizationForm already used in an update transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - authorizationForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - authorizationForm did not originate from getAuthorizationFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteAuthorizations

boolean canDeleteAuthorizations()

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

Compliance:

mandatory - This method must be implemented.

deleteAuthorization

void deleteAuthorization(Id authorizationId)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Deletes the Authorization identified by the given Id.

Parameters:

authorizationId - the Id of the Authorization to delete

Throws:

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

NullArgumentException - authorizationId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageAuthorizationAliases

boolean canManageAuthorizationAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasAuthorization

void aliasAuthorization(Id authorizationId,
                      Id aliasId)
                        throws AlreadyExistsException,
                               NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

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

Parameters:

authorizationId - the Id of an Authorization

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - authorizationId not found

NullArgumentException - authorizationId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.