Interface RelationshipAdminSession

All Superinterfaces:

AutoCloseable, Closeable, OsidSession, OsidSession

All Known Subinterfaces:

RelationshipBatchAdminSession

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.

Method Summary

Modifier and Type	Method	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.

Methods inherited from interface Closeable

close

Methods inherited from interface OsidSession

close

Modifier and Type	Method	Description
void	close()	Close this session.

Methods inherited from interface OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Modifier and Type	Method	Description
Agent	getAuthenticatedAgent()	Gets the agent authenticated to this session.
Id	getAuthenticatedAgentId()	Gets the Id of the agent authenticated to this session.
BigDecimal	getClockRate()	Gets the rate of the service clock.
Date	getDate()	Gets the service date which may be the current date or the effective date in which this session exists.
Agent	getEffectiveAgent()	Gets the effective agent in use by this session.
Id	getEffectiveAgentId()	Gets the Id of the effective agent in use by this session.
Type	getFormatType()	Gets the DisplayText format Type preference in effect for this session.
Locale	getLocale()	Gets the locale indicating the localization preferences in effect for this session.
boolean	isAuthenticated()	Tests if an agent is authenticated to this session.
Transaction	startTransaction()	Starts a new transaction for this sesson.
boolean	supportsTransactions()	Tests for the availability of transactions.

Method Details

getFamilyId

Id getFamilyId()

Gets the Familt Id associated with this session.

Returns:

the Family Id associated with this session

Compliance:

mandatory - This method must be implemented.

getFamily

Family getFamily()
          throws OperationFailedException,
PermissionDeniedException

Gets the Family associated with this session.

Returns:

the family

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateRelationships

boolean canCreateRelationships()

Tests if this user can create 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.

Returns:

false if Relationship creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateRelationshipWithRecordTypes

boolean canCreateRelationshipWithRecordTypes(Type[] relationshipRecordTypes)

Tests if this user can create a single 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.

Parameters:

relationshipRecordTypes - array of relationship record types

Returns:

true if Relationship creation using the specified record Types is supported, false otherwise

Throws:

NullArgumentException - relationshipRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getRelationshipFormForCreate

RelationshipForm getRelationshipFormForCreate(Id sourceId,
 Id destinationId,
 Type[] relationshipRecordTypes)
                                       throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets the relationship form for creating new relationships. A new form should be requested for each create transaction.

Parameters:

sourceId - Id of a peer

destinationId - Id of the related peer

relationshipRecordTypes - array of relationship record types

Returns:

the relationship form

Throws:

NotFoundException - sourceId or destinationId is not found

NullArgumentException - sourceId or destinationId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested recod types

Compliance:

mandatory - This method must be implemented.

createRelationship

Relationship createRelationship(RelationshipForm relationshipForm)
                         throws OperationFailedException,
PermissionDeniedException

Creates a new Relationship .

Parameters:

relationshipForm - the form for this Relationship

Returns:

the new Relationship

Throws:

IllegalStateException - relationshipForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - relationshipForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - relationshipForm did not originate from getRelationshipFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateRelationships

boolean canUpdateRelationships()

Tests if this user can update 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.

Returns:

false if Relationship modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getRelationshipFormForUpdate

RelationshipForm getRelationshipFormForUpdate(Id relationshipId)
                                       throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets the relationship form for updating an existing relationship. A new relationship form should be requested for each update transaction.

Parameters:

relationshipId - the Id of the Relationship

Returns:

the relationship form

Throws:

NotFoundException - relationshipId is not found

NullArgumentException - relationshipId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateRelationship

void updateRelationship(RelationshipForm relationshipForm)
                 throws OperationFailedException,
PermissionDeniedException

Updates an existing relationship.

Parameters:

relationshipForm - the form containing the elements to be updated

Throws:

IllegalStateException - relationshipForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - relationshipForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - relationshipForm did not originate from getRelationshipFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteRelationships

boolean canDeleteRelationships()

Tests if this user can delete 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.

Returns:

false if Relationship deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteRelationship

void deleteRelationship(Id relationshipId)
                 throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Deletes a Relationship .

Parameters:

relationshipId - the Id of the Relationship to remove

Throws:

NotFoundException - relationshipId not found

NullArgumentException - relationshipId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageRelationshipAliases

boolean canManageRelationshipAliases()

Tests if this user can manage 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.

Returns:

false if Relationship aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasRelationship

void aliasRelationship(Id relationshipId,
 Id aliasId)
                throws AlreadyExistsException,
NotFoundException,
OperationFailedException,
PermissionDeniedException

Adds an 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 .

Parameters:

relationshipId - the Id of a Relationship

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - relationship not found

NullArgumentException - relationshipId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.