public interface RelationshipAdminSession extends OsidSession
This session creates, updates, and deletes Relationships.
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
Relationship,
a RelationshipForm
is requested using
getRelationshipFormForCreate()
specifying the desired peers
and record Types
or none if no record Types
are needed. The returned RelationshipForm
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
RelationshipForm
is submiited to a create operation, it cannot be
reused with another create operation unless the first operation was
unsuccessful. Each RelationshipForm
corresponds to an
attempted transaction.
For updates, RelationshipForms
are requested to the
Relationship
Id
that is to be updated using
getRelationshipFormForUpdate().
Similarly, the
RelationshipForm
has metadata about the data that can be updated
and it can perform validation before submitting the update. The
RelationshipForm
can only be used once for a successful update and
cannot be reused.
The delete operations delete Relationships.
To unmap a
Relationship
from the current Family,
the
RelationshipFamilyAssignmentSession
should be used. These
delete operations attempt to remove the Relationship
itself
thus removing it from all known Family
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 |
aliasRelationship(Id relationshipId,
Id aliasId)
Adds an
Id to a Relationship for the
purpose of creating compatibility. |
boolean |
canCreateRelationships()
Tests if this user can create
Relationships A return of
true does not guarantee successful authorization. |
boolean |
canCreateRelationshipWithRecordTypes(Type[] relationshipRecordTypes)
Tests if this user can create a single
Relationship
using the desired record types. |
boolean |
canDeleteRelationships()
Tests if this user can delete
Relationships. |
boolean |
canManageRelationshipAliases()
Tests if this user can manage
Id aliases for
Relationships. |
boolean |
canUpdateRelationships()
Tests if this user can update
Relationships. |
Relationship |
createRelationship(RelationshipForm relationshipForm)
Creates a new
Relationship. |
void |
deleteRelationship(Id relationshipId)
Deletes a
Relationship. |
Family |
getFamily()
Gets the
Family associated with this session. |
Id |
getFamilyId()
Gets the
Familt Id associated with this
session. |
RelationshipForm |
getRelationshipFormForCreate(Id sourceId,
Id destinationId,
Type[] relationshipRecordTypes)
Gets the relationship form for creating new relationships.
|
RelationshipForm |
getRelationshipFormForUpdate(Id relationshipId)
Gets the relationship form for updating an existing relationship.
|
void |
updateRelationship(RelationshipForm relationshipForm)
Updates an existing relationship.
|
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getFamilyId()
Familt
Id
associated with this
session. Family Id
associated with this sessionmandatory
- This method must be implemented. Family getFamily() throws OperationFailedException, PermissionDeniedException
Family
associated with this session.OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canCreateRelationships()
Relationships
A return of
true does not guarantee successful authorization. A return of false
indicates that it is known creating a Relationship
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 Relationship
creation
is not authorized, true
otherwisemandatory
- This method must be implemented. boolean canCreateRelationshipWithRecordTypes(Type[] relationshipRecordTypes)
Relationship
using the desired record types. While
RelationshipManager.getRelationshipRecordTypes()
can be used
to examine which records are supported, this method tests which
record(s) are required for creating a specific Relationship.
Providing an empty array tests if a Relationship
can be created with no records.relationshipRecordTypes
- array of relationship record types true
if Relationship
creation
using the specified record Types
is supported,
false
otherwiseNullArgumentException
- relationshipRecordTypes
is null
mandatory
- This method must be implemented. RelationshipForm getRelationshipFormForCreate(Id sourceId, Id destinationId, Type[] relationshipRecordTypes) throws NotFoundException, OperationFailedException, PermissionDeniedException
sourceId
- Id
of a peerdestinationId
- Id
of the related peerrelationshipRecordTypes
- array of relationship record typesNotFoundException
- sourceId
or
destinationId
is not foundNullArgumentException
- sourceId
or
destinationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failureUnsupportedException
- unable to get form for requested
recod typesmandatory
- This method must be implemented. Relationship createRelationship(RelationshipForm relationshipForm) throws OperationFailedException, PermissionDeniedException
Relationship.
relationshipForm
- the form for this Relationship
Relationship
IllegalStateException
- relationshipForm
already used in a create transactionInvalidArgumentException
- one or more of the form
elements is invalidNullArgumentException
- relationshipForm
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failureUnsupportedException
- relationshipForm
did not originate from getRelationshipFormForCreate()
mandatory
- This method must be implemented. boolean canUpdateRelationships()
Relationships.
A return
of true does not guarantee successful authorization. A return of false
indicates that it is known updating a Relationship
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 Relationship
modification is not authorized, true
otherwisemandatory
- This method must be implemented. RelationshipForm getRelationshipFormForUpdate(Id relationshipId) throws NotFoundException, OperationFailedException, PermissionDeniedException
relationshipId
- the Id
of the
Relationship
NotFoundException
- relationshipId
is
not foundNullArgumentException
- relationshipId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. void updateRelationship(RelationshipForm relationshipForm) throws OperationFailedException, PermissionDeniedException
relationshipForm
- the form containing the elements to be
updatedIllegalStateException
- relationshipForm
already used in an update transactionInvalidArgumentException
- the form contains an invalid
valueNullArgumentException
- relationshipForm
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failureUnsupportedException
- relationshipForm
did not originate from getRelationshipFormForUpdate()
mandatory
- This method must be implemented. boolean canDeleteRelationships()
Relationships.
A return
of true does not guarantee successful authorization. A return of false
indicates that it is known deleting a Relationship
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 Relationship
deletion
is not authorized, true
otherwisemandatory
- This method must be implemented. void deleteRelationship(Id relationshipId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Relationship.
relationshipId
- the Id
of the
Relationship
to removeNotFoundException
- relationshipId
not
foundNullArgumentException
- relationshipId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canManageRelationshipAliases()
Id
aliases for
Relationships.
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 Relationship
aliasing
is not authorized, true
otherwisemandatory
- This method must be implemented. void aliasRelationship(Id relationshipId, Id aliasId) throws AlreadyExistsException, NotFoundException, OperationFailedException, PermissionDeniedException
Id
to a Relationship
for the
purpose of creating compatibility. The primary Id
of
the Relationship
is determined by the provider. The new
Id
performs as an alias to the primary Id.
If the alias is a pointer to another relationship, it is
reassigned to the given relationship Id.
relationshipId
- the Id
of a Relationship
aliasId
- the alias Id
AlreadyExistsException
- aliasId
is
already assignedNotFoundException
- relationship
not
foundNullArgumentException
- relationshipId
or aliasId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.