public interface AgencyAdminSession extends OsidSession
This session creates, updates, and deletes Agencies.
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
Agency,
an AgencyForm
is requested using
getAgencyFormForCreate()
specifying the desired record
Types
or none if no record Types
are needed.
The returned AgencyForm
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 AgencyForm
is submiited to
a create operation, it cannot be reused with another create operation
unless the first operation was unsuccessful. Each AgencyForm
corresponds to an attempted transaction.
For updates, AgencyForms
are requested to the
Agency
Id
that is to be updated using
getAgencyFormForUpdate().
Similarly, the AgencyForm
has metadata about the data that can be updated and it can perform
validation before submitting the update. The AgencyForm
can
only be used once for a successful update and cannot be reused.
The delete operations delete Agencies.
This session includes an Id
aliasing mechanism to
assign an external Id
to an internally assigned Id.
Modifier and Type | Method and Description |
---|---|
void |
aliasAgency(Id agencyId,
Id aliasId)
Adds an
Id to an Agency for the purpose
of creating compatibility. |
boolean |
canCreateAgencies()
Tests if this user can create
Agencies. |
boolean |
canCreateAgencyWithRecordTypes(Type[] agencyRecordTypes)
Tests if this user can create a single
Agency using the
desired record types. |
boolean |
canDeleteAgencies()
Tests if this user can delete agencies.
|
boolean |
canManageAgencyAliases()
Tests if this user can manage
Id aliases for
Agencies. |
boolean |
canUpdateAgencies()
Tests if this user can update
Agencies. |
Agency |
createAgency(AgencyForm agencyForm)
Creates a new
Agency. |
void |
deleteAgency(Id agencyId)
Deletes an
Agency. |
AgencyForm |
getAgencyFormForCreate(Type[] agencyRecordTypes)
Gets the agency form for creating new agencies.
|
AgencyForm |
getAgencyFormForUpdate(Id agencyId)
Gets the agency form for updating an existing agency.
|
void |
updateAgency(AgencyForm agencyForm)
Updates an existing agency.
|
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
boolean canCreateAgencies()
Agencies.
A return of
true does not guarantee successful authorization. A return of false
indicates that it is known creating an Agency
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. false
if Agency
creation is not
authorized, true
otherwisemandatory
- This method must be implemented. boolean canCreateAgencyWithRecordTypes(Type[] agencyRecordTypes)
Agency
using the
desired record types. While
AuthenticationManager.getAgencyRecordTypes()
can be used to
examine which records are supported, this method tests which record(s)
are required for creating a specific Agency.
Providing
an empty array tests if an Agency
can be created with
no records.agencyRecordTypes
- array of agency record types true
if Agency
creation using
the specified Types
is supported, false
otherwiseNullArgumentException
- agencyRecordTypes
is null
mandatory
- This method must be implemented. AgencyForm getAgencyFormForCreate(Type[] agencyRecordTypes) throws OperationFailedException, PermissionDeniedException
agencyRecordTypes
- array of agency record typesNullArgumentException
- agencyRecordTypes
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failureUnsupportedException
- unable to get form for requested
record typesmandatory
- This method must be implemented. Agency createAgency(AgencyForm agencyForm) throws OperationFailedException, PermissionDeniedException
Agency.
agencyForm
- the form for this Agency
Agency
IllegalStateException
- agencyForm
already used for a create transactionInvalidArgumentException
- one or more of the form
elements is invalidNullArgumentException
- agencyForm
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failureUnsupportedException
- agencyForm
did
not originate from getAgencyFormForCreate()
mandatory
- This method must be implemented. boolean canUpdateAgencies()
Agencies.
A return of
true does not guarantee successful authorization. A return of false
indicates that it is known updating an Agency
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. false
if Agency
modification is
not authorized, true
otherwisemandatory
- This method must be implemented. AgencyForm getAgencyFormForUpdate(Id agencyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
agencyId
- the Id
of the Agency
NotFoundException
- agencyId
is not
foundNullArgumentException
- agencyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. void updateAgency(AgencyForm agencyForm) throws OperationFailedException, PermissionDeniedException
agencyForm
- the form containing the elements to be updatedIllegalStateException
- agencyForm
already used for an update transactionInvalidArgumentException
- the form contains an invalid
valueNullArgumentException
- agencyForm
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failureUnsupportedException
- agencyForm
did
not originate from getAgencyFormForUpdate()
mandatory
- This method must be implemented. boolean canDeleteAgencies()
Agency
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. false
if Agency
deletion is not
authorized, true
otherwisemandatory
- This method must be implemented. void deleteAgency(Id agencyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Agency.
agencyId
- the Id
of the Agency
to
removeNotFoundException
- agencyId
not foundNullArgumentException
- agencyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canManageAgencyAliases()
Id
aliases for
Agencies.
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. false
if Agency
aliasing is not
authorized, true
otherwisemandatory
- This method must be implemented. void aliasAgency(Id agencyId, Id aliasId) throws AlreadyExistsException, NotFoundException, OperationFailedException, PermissionDeniedException
Id
to an Agency
for the purpose
of creating compatibility. The primary Id
of the
Agency
is determined by the provider. The new Id
performs as an alias to the primary Id.
If the
alias is a pointer to another agency, it is reassigned to the given
entry Id.
agencyId
- the Id
of an Agency
aliasId
- the alias Id
AlreadyExistsException
- aliasId
is
already assignedNotFoundException
- agencyId
not foundNullArgumentException
- agencyId
or
aliasId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.