org.osid.filing.allocation

Interface AllocationAdminSession

All Superinterfaces:

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

public interface AllocationAdminSession
extends OsidSession

This session defines methods for managing quotas. Allocations can be assigned across all users in a directory structure or on a user by user basis.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canCreateAllocations() Tests if this user can create allocations in this session for or under the session directory.
boolean	canCreateAllocationsForUsers() Tests if this user can create allocations in this session for or under the session directory for specific users.
boolean	canCreateAllocationWithRecordTypes(Type[] allocationRecordTypes) Tests if this user can create a single Allocation using the desired record types.
boolean	canCreateAllocationWithRecordTypesForUsers(Type[] allocationRecordTypes) Tests if this user can create a single Allocation using the desired record types targeted for specific users.
boolean	canDeleteAllocations() Tests if this user can delete allocations for directories in this session.
boolean	canDeleteAllocationsForUser() Tests if this user can delete allocations for users in directories in this session.
boolean	canUpdateAllocations() Tests if this user can update allocations for directories in this session.
boolean	canUpdateAllocationsForUsers() Tests if this user can update allocations for users in directories in this session.
Allocation	createAllocation(AllocationForm allocationForm) Creates a new allocation across all users for a directory.
Allocation	createAllocationForUser(AllocationForm allocationForm) Creates a new allocation for a specific user for a directory.
void	deleteAllocation(java.lang.String name) Deletes the allocation for a directory.
void	deleteAllocationForUser(java.lang.String name, Id agentId) Deletes the allocation for a directory.
AllocationForm	getAllocationFormForCreate(java.lang.String name, Type[] allocationRecordTypes) Gets the file form for creating new allocations across all users for a directory.
AllocationForm	getAllocationFormForCreateForUser(java.lang.String name, Id agentId, Type[] allocationRecordTypes) Gets the file form for creating new allocations across all users for a directory.
AllocationForm	getAllocationFormForUpdate(java.lang.String name) Gets the allocation form for updating an existing allocation.
AllocationForm	getAllocationFormForUpdateForUser(java.lang.String name, Id agentId) Gets the allocation form for updating an existing allocation for a user.
Directory	getDirectory() Gets the directory associated with this session.
java.lang.String	getDirectoryPath() Gets the absolute path of this directory.
void	updateAllocation(AllocationForm allocationForm) Updates an existing allocation.
void	updateAllocationForUser(AllocationForm allocationForm) Updates an existing allocation.

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

getDirectoryPath

java.lang.String getDirectoryPath()

Gets the absolute path of this directory.

Returns:

the absolute path of this directory

Compliance:

mandatory - This method must be implemented.

getDirectory

Directory getDirectory()
                       throws OperationFailedException,
                              PermissionDeniedException

Gets the directory associated with this session.

Returns:

the directory associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateAllocations

boolean canCreateAllocations()

Tests if this user can create allocations in this session for or under the session directory. 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 filing allocation create methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateAllocationWithRecordTypes

boolean canCreateAllocationWithRecordTypes(Type[] allocationRecordTypes)

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

Parameters:

allocationRecordTypes - array of allocation record types

Returns:

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

Throws:

NullArgumentException - allocationRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getAllocationFormForCreate

AllocationForm getAllocationFormForCreate(java.lang.String name,
                                        Type[] allocationRecordTypes)
                                          throws AlreadyExistsException,
                                                 NotFoundException,
                                                 OperationFailedException,
                                                 PermissionDeniedException

Gets the file form for creating new allocations across all users for a directory. A new form should be requested for each create transaction.

Parameters:

name - name of a directory

allocationRecordTypes - array of allocation record types

Returns:

the allocation form

Throws:

AlreadyExistsException - allocation already exists

NotFoundException - name not found

NullArgumentException - name or allocationRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createAllocation

Allocation createAllocation(AllocationForm allocationForm)
                            throws OperationFailedException,
                                   PermissionDeniedException

Creates a new allocation across all users for a directory.

Parameters:

allocationForm - the allocation form

Returns:

the new allocation

Throws:

IllegalStateException - allocationForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - allocationForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - fileForm did not originate from getAllocationFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateAllocations

boolean canUpdateAllocations()

Tests if this user can update allocations for directories in this session. 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 update operations to unauthorized users.

Returns:

false if filing allocation update methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getAllocationFormForUpdate

AllocationForm getAllocationFormForUpdate(java.lang.String name)
                                          throws NotFoundException,
                                                 OperationFailedException,
                                                 PermissionDeniedException

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

Parameters:

name - name of the directory

Returns:

the allocation form

Throws:

NotFoundException - name is not found or no allocation exists

NullArgumentException - name is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateAllocation

void updateAllocation(AllocationForm allocationForm)
                      throws OperationFailedException,
                             PermissionDeniedException

Updates an existing allocation.

Parameters:

allocationForm - the form containing the elements to be updated

Throws:

IllegalStateException - allocationForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - allocationForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - allocationForm did not originate from getAllocationFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteAllocations

boolean canDeleteAllocations()

Tests if this user can delete allocations for directories in this session. 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 delete operations to unauthorized users.

Returns:

false if filing allocation delete methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteAllocation

void deleteAllocation(java.lang.String name)
                      throws NotFoundException,
                             OperationFailedException,
                             PermissionDeniedException

Deletes the allocation for a directory.

Parameters:

name - the name of the directory

Throws:

NotFoundException - name is not found or no allocation exists

NullArgumentException - name is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateAllocationsForUsers

boolean canCreateAllocationsForUsers()

Tests if this user can create allocations in this session for or under the session directory for specific users. 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 user allocation create methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateAllocationWithRecordTypesForUsers

boolean canCreateAllocationWithRecordTypesForUsers(Type[] allocationRecordTypes)

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

Parameters:

allocationRecordTypes - array of allocation record types

Returns:

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

Throws:

NullArgumentException - allocationRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getAllocationFormForCreateForUser

AllocationForm getAllocationFormForCreateForUser(java.lang.String name,
                                               Id agentId,
                                               Type[] allocationRecordTypes)
                                                 throws AlreadyExistsException,
                                                        NotFoundException,
                                                        OperationFailedException,
                                                        PermissionDeniedException

Gets the file form for creating new allocations across all users for a directory. A new form should be requested for each create transaction.

Parameters:

name - name of a directory

agentId - the Id of a user

allocationRecordTypes - array of allocation record types

Returns:

the allocation form

Throws:

AlreadyExistsException - allocation already exists

NotFoundException - name or agentId is not found

NullArgumentException - name, agentId, or allocationRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createAllocationForUser

Allocation createAllocationForUser(AllocationForm allocationForm)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Creates a new allocation for a specific user for a directory.

Parameters:

allocationForm - the allocation form

Returns:

the new allocation

Throws:

IllegalStateException - allocationForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - allocationForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - fileForm did not originate from getAllocationFormForCreateForUser()

Compliance:

mandatory - This method must be implemented.

canUpdateAllocationsForUsers

boolean canUpdateAllocationsForUsers()

Tests if this user can update allocations for users in directories in this session. 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 update operations to unauthorized users.

Returns:

false if filing allocation user update methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getAllocationFormForUpdateForUser

AllocationForm getAllocationFormForUpdateForUser(java.lang.String name,
                                               Id agentId)
                                                 throws NotFoundException,
                                                        OperationFailedException,
                                                        PermissionDeniedException

Gets the allocation form for updating an existing allocation for a user. A new file form should be requested for each update transaction.

Parameters:

name - name of the directory

agentId - the Id of the user

Returns:

the allocation form

Throws:

NotFoundException - name or agentId is not found or no allocation exists

NullArgumentException - name or agentId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateAllocationForUser

void updateAllocationForUser(AllocationForm allocationForm)
                             throws OperationFailedException,
                                    PermissionDeniedException

Updates an existing allocation.

Parameters:

allocationForm - the form containing the elements to be updated

Throws:

IllegalStateException - allocationForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - allocationForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - allocationForm did not originate from getAllocationFormForUpdateForUser()

Compliance:

mandatory - This method must be implemented.

canDeleteAllocationsForUser

boolean canDeleteAllocationsForUser()

Tests if this user can delete allocations for users in directories in this session. 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 delete operations to unauthorized users.

Returns:

false if filing allocation delete methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteAllocationForUser

void deleteAllocationForUser(java.lang.String name,
                           Id agentId)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Deletes the allocation for a directory.

Parameters:

name - name of the directory

agentId - the Id of the user

Throws:

NotFoundException - name or agentId is not found or no allocation exists

NullArgumentException - name or agentId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.