OSID - osid.ontology.SubjectAdminSession Service Interface Definition

Interface	osid.ontology.SubjectAdminSession
Implements	`osid.OsidSession`
Implemented By	`osid.ontology.batch.SubjectBatchAdminSession`
Used By	`osid.ontology.OntologyManager`
Used By	`osid.ontology.OntologyProxyManager`
Description	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.
Method	getOntologyId
Description	Gets the `Ontology` `Id` associated with this session.
Return	`osid.id.Id`		the `Ontology Id` associated with this session
Compliance	`mandatory`		This method must be implemented.
Method	getOntology
Description	Gets the `Ontology` associated with this session.
Return	`osid.ontology.Ontology`		the `Ontology` associated with this session
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canCreateSubjects
Description	Tests if this user can create `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.
Return	`boolean`		`false` if `Subject` creation is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canCreateSubjectWithRecordTypes
Description	Tests if this user can create a single `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.
Parameters	`osid.type.Type[]`	`subjectRecordTypes`	array of subject record types
Return	`boolean`		`true` if `Subject` creation using the specified record `Types` is supported, `false` otherwise
Errors	NULL_ARGUMENT		`subjectRecordTypes` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	getSubjectFormForCreate
Description	Gets the subject form for creating new subjects. A new form should be requested for each create transaction.
Parameters	`osid.type.Type[]`	`subjectRecordTypes`	array of subject record types
Return	`osid.ontology.SubjectForm`		the subject form
Errors	NULL_ARGUMENT		`subjectRecordTypes` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		unable to get form for requested record types
Compliance	`mandatory`		This method must be implemented.
Method	createSubject
Description	Creates a new `Subject`.
Parameters	`osid.ontology.SubjectForm`	`subjectForm`	the form for this `Subject`
Return	`osid.ontology.Subject`		the new `Subject`
Errors	ILLEGAL_STATE		`subjectForm` already used in a create transaction
	INVALID_ARGUMENT		one or more of the form elements is invalid
	NULL_ARGUMENT		`subjectForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`subjectForm` did not originate from `getSubjectFormForCreate()`
Compliance	`mandatory`		This method must be implemented.
Method	canUpdateSubjects
Description	Tests if this user can update `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.
Return	`boolean`		`false` if subject modification is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getSubjectFormForUpdate
Description	Gets the subject form for updating an existing subject. A new subject form should be requested for each update transaction.
Parameters	`osid.id.Id`	`subjectId`	the `Id` of the `Subject`
Return	`osid.ontology.SubjectForm`		the subject form
Errors	NOT_FOUND		`subjectId` is not found
	NULL_ARGUMENT		`subjectId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	updateSubject
Description	Updates an existing subject.
Parameters	`osid.ontology.SubjectForm`	`subjectForm`	the form containing the elements to be updated
Errors	ILLEGAL_STATE		`subjectForm` already used in an update transaction
	INVALID_ARGUMENT		the form contains an invalid value
	NULL_ARGUMENT		`subjectForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`subjectForm` did not originate from `getSubjectFormForUpdate()`
Compliance	`mandatory`		This method must be implemented.
Method	canDeleteSubjects
Description	Tests if this user can delete `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.
Return	`boolean`		`false` if `Subject` deletion is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	deleteSubject
Description	Deletes the `Subject` identified by the given `Id`.
Parameters	`osid.id.Id`	`subjectId`	the `Id` of the `Subject` to delete
Errors	NOT_FOUND		a `Subject` was not found identified by the given `Id`
	NULL_ARGUMENT		`subjectId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canManageSubjectAliases
Description	Tests if this user can manage `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.
Return	`boolean`		`false` if `Subject` aliasing is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	aliasSubject
Description	Adds an `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`.
Parameters	`osid.id.Id`	`subjectId`	the `Id` of a `Subject`
Parameters	`osid.id.Id`	`aliasId`	the alias `Id`
Errors	ALREADY_EXISTS		`aliasId` is already assigned
	NOT_FOUND		`subjectId` not found
	NULL_ARGUMENT		`subjectId` or `aliasId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.