public interface AgentAdminSession extends OsidSession
This session creates, updates, and deletes Agents.
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
Agent,
an AgentForm
is requested using
getAgentFormForCreate()
specifying the desired record
Types
or none if no record Types
are needed.
The returned AgentForm
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 AgentForm
is submiited to
a create operation, it cannot be reused with another create operation
unless the first operation was unsuccessful. Each AgentForm
corresponds to an attempted transaction.
For updates, AgentForms
are requested to the
Agent
Id
that is to be updated using
getAgentFormForUpdate().
Similarly, the AgentForm
has metadata about the data that can be updated and it can perform
validation before submitting the update. The AgentForm
can
only be used once for a successful update and cannot be reused.
The delete operations delete Agents.
To unmap an
Agent
from the current Agency,
the
AgentAgencyAssignmentSession
should be used. These delete
operations attempt to remove the Agent
itself thus removing
it from all known Agency
catalogs.
This session includes an Id
aliasing mechanism to
assign an external Id
to an internally assigned Id.
Modifier and Type | Method and Description |
---|---|
void |
aliasAgent(Id agentId,
Id aliasId)
Adds an
Id to an Agent for the purpose
of creating compatibility. |
boolean |
canCreateAgents()
Tests if this user can create
Agents. |
boolean |
canCreateAgentWithRecordTypes(Type[] agentRecordTypes)
Tests if this user can create a single
Agent using the
desired record types. |
boolean |
canDeleteAgent(Id agentId)
Tests if this user can delete a specified
Agent. |
boolean |
canDeleteAgents()
Tests if this user can delete
Agents. |
boolean |
canManageAgentAliases()
Tests if this user can manage
Id aliases for
Agents. |
boolean |
canUpdateAgent(Id agentId)
Tests if this user can update a specified agent.
|
boolean |
canUpdateAgents()
Tests if this user can update
Agents. |
Agent |
createAgent(AgentForm agentForm)
Creates a new
Agent. |
void |
deleteAgent(Id agentId)
Deletes the
Agent identified by the given Id
removing it from all other Agencies to which
this Agent is associated. |
Agency |
getAgency()
Gets the
Agency associated with this session. |
Id |
getAgencyId()
Gets the
Agency Id associated with this
session. |
AgentForm |
getAgentFormForCreate(Type[] agentRecordTypes)
Gets the agent form for creating new agents.
|
AgentForm |
getAgentFormForUpdate(Id agentId)
Gets the agent form for updating an existing agent.
|
void |
updateAgent(AgentForm agentForm)
Updates an existing agent.
|
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getAgencyId()
Agency
Id
associated with this
session. Agency Id
associated with this sessionmandatory
- This method must be implemented. Agency getAgency() throws OperationFailedException, PermissionDeniedException
Agency
associated with this session. Agency
associated with this sessionOperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canCreateAgents()
Agents.
A return of true
does not guarantee successful authorization. A return of false
indicates that it is known creating an Agent
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. false
if Agent
creation is not
authorized, true
otherwisemandatory
- This method must be implemented. boolean canCreateAgentWithRecordTypes(Type[] agentRecordTypes)
Agent
using the
desired record types. While
AuthenticationManager.getAgentRecordTypes()
can be used to
examine which records are supported, this method tests which record(s)
are required for creating a specific Agent.
Providing
an empty array tests if an Agent
can be created with no
records.agentRecordTypes
- array of agent record types true
if Agent
creation using the
specified record Types
is supported,
false
otherwiseNullArgumentException
- agentRecordTypes
is null
mandatory
- This method must be implemented. AgentForm getAgentFormForCreate(Type[] agentRecordTypes) throws OperationFailedException, PermissionDeniedException
agentRecordTypes
- array of agent record typesNullArgumentException
- agentRecordTypes
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failureUnsupportedException
- unable to get form for requested
record typesmandatory
- This method must be implemented. Agent createAgent(AgentForm agentForm) throws OperationFailedException, PermissionDeniedException
Agent.
agentForm
- the form for this Agent
Agent
IllegalStateException
- agentForm
already used in a create transactionInvalidArgumentException
- one or more of the form
elements is invalidNullArgumentException
- agentForm
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failureUnsupportedException
- agentForm
did not
originate from getAgentFormForCreate()
mandatory
- This method must be implemented. boolean canUpdateAgents()
Agents.
A return of true
does not guarantee successful authorization. A return of false
indicates that it is known updating an Agent
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. false
if agent modification is not authorized,
true
otherwisemandatory
- This method must be implemented. boolean canUpdateAgent(Id agentId)
PERMISSION_DENIED.
This is intended as a hint to an
application that may opt not to offer an update operation to an
unauthorized user for this agent.agentId
- the Id
of the Agent
false
if agent modification is not authorized,
true
otherwiseNullArgumentException
- agentId
is
null
mandatory
- This method must be implemented. If
- the agentId
is not found, then it is
acceptable to return false to indicate the lack of an update
available. AgentForm getAgentFormForUpdate(Id agentId) throws NotFoundException, OperationFailedException, PermissionDeniedException
agentId
- the Id
of the Agent
NotFoundException
- agentId
is not foundNullArgumentException
- agentId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. void updateAgent(AgentForm agentForm) throws OperationFailedException, PermissionDeniedException
agentForm
- the form containing the elements to be updatedIllegalStateException
- agentForm
already used in an update transactionInvalidArgumentException
- the form contains an invalid
valueNullArgumentException
- agentId
or
agentForm
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failureUnsupportedException
- agentForm
did not
originate from getAgentFormForUpdate()
mandatory
- This method must be implemented. boolean canDeleteAgents()
Agents.
A return of true
does not guarantee successful authorization. A return of false
indicates that it is known deleting an Agent
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. false
if Agent
deletion is not
authorized, true
otherwisemandatory
- This method must be implemented. boolean canDeleteAgent(Id agentId)
Agent.
A
return of true does not guarantee successful authorization. A return
of false indicates that it is known deleting the Agent
will result in a PERMISSION_DENIED.
This is intended as
a hint to an application that may opt not to offer a delete operation
to an unauthorized user for this agent.agentId
- the Id
of the Agent
false
if Agent
deletion is not
authorized, true
otherwiseNullArgumentException
- agentId
is
null
mandatory
- This method must be implemented. If
- the agentId
is not found, then it is
acceptable to return false to indicate the lack of a delete
available. void deleteAgent(Id agentId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Agent
identified by the given Id
removing it from all other Agencies
to which
this Agent
is associated.agentId
- the Id
of the Agent
to
deleteNotFoundException
- an Agent
was not
found identified by the given Id
NullArgumentException
- agentId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canManageAgentAliases()
Id
aliases for
Agents.
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 Agent
aliasing is not
authorized, true
otherwisemandatory
- This method must be implemented. void aliasAgent(Id agentId, Id aliasId) throws AlreadyExistsException, NotFoundException, OperationFailedException, PermissionDeniedException
Id
to an Agent
for the purpose
of creating compatibility. The primary Id
of the
Agent
is determined by the provider. The new Id
performs as an alias to the primary Id.
If the alias is
a pointer to another engine, it is reassigned to the given engine
Id.
agentId
- the Id
of an Agent
aliasId
- the alias Id
AlreadyExistsException
- aliasId
is
already assignedNotFoundException
- agentId
not foundNullArgumentException
- agentId
or
aliasId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.