public interface SubjectAdminSession extends OsidSession
This session creates, updates, and deletes Subjects.
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 a
Subject,
a SubjectForm
is requested using
getSubjectFormForCreate()
specifying the desired record
Types
or none if no record Types
are needed. The
returned SubjectForm
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 SubjectForm
is submiited
to a create operation, it cannot be reused with another create operation
unless the first operation was unsuccessful. Each SubjectForm
corresponds to an attempted transaction.
For updates, SubjectForms
are requested to the
Subject
Id
that is to be updated using
getSubjectFormForUpdate().
Similarly, the SubjectForm
has metadata about the data that can be updated and it can perform
validation before submitting the update. The SubjectForm
can only be used once for a successful update and cannot be reused.
The delete operations delete Subjects.
To unmap a
Subject
from the current Ontology,
the
SubjectOntologyAssignmentSession
should be used. These
delete operations attempt to remove the Subject
itself thus
removing it from all known Ontology
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 |
aliasSubject(Id subjectId,
Id aliasId)
Adds an
Id to a Subject for the purpose
of creating compatibility. |
boolean |
canCreateSubjects()
Tests if this user can create
Subjects. |
boolean |
canCreateSubjectWithRecordTypes(Type[] subjectRecordTypes)
Tests if this user can create a single
Subject using
the desired record interface types. |
boolean |
canDeleteSubjects()
Tests if this user can delete
Subjects. |
boolean |
canManageSubjectAliases()
Tests if this user can manage
Id aliases for
Subjects. |
boolean |
canUpdateSubjects()
Tests if this user can update
Subjects. |
Subject |
createSubject(SubjectForm subjectForm)
Creates a new
Subject. |
void |
deleteSubject(Id subjectId)
Deletes the
Subject identified by the given Id. |
Ontology |
getOntology()
Gets the
Ontology associated with this session. |
Id |
getOntologyId()
Gets the
Ontology Id associated with
this session. |
SubjectForm |
getSubjectFormForCreate(Type[] subjectRecordTypes)
Gets the subject form for creating new subjects.
|
SubjectForm |
getSubjectFormForUpdate(Id subjectId)
Gets the subject form for updating an existing subject.
|
void |
updateSubject(SubjectForm subjectForm)
Updates an existing subject.
|
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getOntologyId()
Ontology
Id
associated with
this session. Ontology Id
associated with this sessionmandatory
- This method must be implemented. Ontology getOntology() throws OperationFailedException, PermissionDeniedException
Ontology
associated with this session. Ontology
associated with this sessionOperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canCreateSubjects()
Subjects.
A return of
true does not guarantee successful authorization. A return of false
indicates that it is known creating a subject 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 Subject
creation is not
authorized, true
otherwisemandatory
- This method must be implemented. boolean canCreateSubjectWithRecordTypes(Type[] subjectRecordTypes)
Subject
using
the desired record interface types. While
OntologyManager.getSubjectRecordTypes()
can be used to examine
which record interfaces are supported, this method tests which
record(s) are required for creating a specific Subject.
Providing an empty array tests if a Subject
can be
created with no records.subjectRecordTypes
- array of subject record types true
if Subject
creation using
the specified record Types
is supported,
false
otherwiseNullArgumentException
- subjectRecordTypes
is null
mandatory
- This method must be implemented. SubjectForm getSubjectFormForCreate(Type[] subjectRecordTypes) throws OperationFailedException, PermissionDeniedException
subjectRecordTypes
- array of subject record typesNullArgumentException
- subjectRecordTypes
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failureUnsupportedException
- unable to get form for requested
record typesmandatory
- This method must be implemented. Subject createSubject(SubjectForm subjectForm) throws OperationFailedException, PermissionDeniedException
Subject.
subjectForm
- the form for this Subject
Subject
IllegalStateException
- subjectForm
already used in a create transactionInvalidArgumentException
- one or more of the form
elements is invalidNullArgumentException
- subjectForm
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failureUnsupportedException
- subjectForm
did
not originate from getSubjectFormForCreate()
mandatory
- This method must be implemented. boolean canUpdateSubjects()
Subjects.
A return of
true does not guarantee successful authorization. A return of false
indicates that it is known updating a Subject
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 subject modification is not
authorized, true
otherwisemandatory
- This method must be implemented. SubjectForm getSubjectFormForUpdate(Id subjectId) throws NotFoundException, OperationFailedException, PermissionDeniedException
subjectId
- the Id
of the Subject
NotFoundException
- subjectId
is not
foundNullArgumentException
- subjectId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. void updateSubject(SubjectForm subjectForm) throws OperationFailedException, PermissionDeniedException
subjectForm
- the form containing the elements to be updatedIllegalStateException
- subjectForm
already used in an update transactionInvalidArgumentException
- the form contains an invalid
valueNullArgumentException
- subjectForm
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failureUnsupportedException
- subjectForm
did
not originate from getSubjectFormForUpdate()
mandatory
- This method must be implemented. boolean canDeleteSubjects()
Subjects.
A return of
true does not guarantee successful authorization. A return of false
indicates that it is known deleting a Subject
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 Subject
deletion is not
authorized, true
otherwisemandatory
- This method must be implemented. void deleteSubject(Id subjectId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Subject
identified by the given Id.
subjectId
- the Id
of the Subject
to deleteNotFoundException
- a Subject
was not
found identified by the given Id
NullArgumentException
- subjectId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canManageSubjectAliases()
Id
aliases for
Subjects.
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 Subject
aliasing is not
authorized, true
otherwisemandatory
- This method must be implemented. void aliasSubject(Id subjectId, Id aliasId) throws AlreadyExistsException, NotFoundException, OperationFailedException, PermissionDeniedException
Id
to a Subject
for the purpose
of creating compatibility. The primary Id
of the
Subject
is determined by the provider. The new Id
performs as an alias to the primary Id.
If the
alias is a pointer to another subject, it is reassigned to the given
subject Id.
subjectId
- the Id
of a Subject
aliasId
- the alias Id
AlreadyExistsException
- aliasId
is
already assignedNotFoundException
- subjectId
not foundNullArgumentException
- subjectId
or
aliasId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.