org.osid.journaling

Interface BranchAdminSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

All Known Subinterfaces:

BranchBatchAdminSession

public interface BranchAdminSession
extends OsidSession

This session creates, updates, and deletes Branches. 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 Branch, a BranchForm is requested using getBranchFormForCreate() specifying the desired record Types or none if no record Types are needed. The returned BranchForm 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 BranchForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each BranchForm corresponds to an attempted transaction.

For updates, BranchForms are requested to the Branch Id that is to be updated using getBranchFormForUpdate(). Similarly, the BranchForm has metadata about the data that can be updated and it can perform validation before submitting the update. The BranchForm can only be used once for a successful update and cannot be reused.

The delete operations delete Branches.

This session includes an Id aliasing mechanism to assign an external Id to an internally assigned Id.

Method Summary

Methods

Modifier and Type	Method and Description
void	aliasBranch(Id branchId, Id aliasId) Adds an Id to a Branch for the purpose of creating compatibility.
boolean	canCreateBranch(Id journalEntryId) Tests if this user can branch a specified JournalEntry.
boolean	canCreateBranches() Tests if this user can branch a version chain.
boolean	canCreateBranchWithRecordTypes(Type[] branchRecordTypes) Tests if this user can create a single Branch using the desired record types.
boolean	canDeleteBranches() Tests if this user can delete branches.
boolean	canManageBranchAliases() Tests if this user can manage Id aliases for branches.
boolean	canMergeBranches() Tests if this user can merge branches.
boolean	canSupersedeBranches() Tests if this user can supersede branches.
boolean	canUpdateBranches() Tests if this user can update branches.
Branch	createBranch(BranchForm branchForm) Creates a branch.
void	deleteBranch(Id branchId) Deletes a branch and all associated versions.
BranchForm	getBranchFormForCreate(Id journalEntryId, Type[] branchRecordTypes) Gets the branch form for creating new entries.
BranchForm	getBranchFormForUpdate(Id branchId) Gets the branch form for updating an existing branch.
Journal	getJournal() Gets the Journal associated with this session.
Id	getJournalId() Gets the Journal Id associated with this session.
JournalEntry	mergeBranches(Id srcBranchId, Id dstBranchId) Merges the source branch into the destination branch.
JournalEntry	supersedeBranch(Id srcBranchId, Id dstBranchId) Joins the source branch to the destination branch by creating a new journal entry.
void	updateBranch(BranchForm branchForm) Updates an existing branch.

Methods inherited from interface org.osid.OsidSession

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

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

getJournalId

Id getJournalId()

Gets the Journal Id associated with this session.

Returns:

the Journal Id associated with this session

Compliance:

mandatory - This method must be implemented.

getJournal

Journal getJournal()
                   throws OperationFailedException,
                          PermissionDeniedException

Gets the Journal associated with this session.

Returns:

the journal

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateBranches

boolean canCreateBranches()

Tests if this user can branch a version chain. A return of true does not guarantee successful authorization. A return of false indicates that it is known branching will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.

Returns:

false if journal branching is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateBranch

boolean canCreateBranch(Id journalEntryId)

Tests if this user can branch a specified JournalEntry. A return of true does not guarantee successful authorization. A return of false indicates that it is known branching the JournalEntry will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.

Parameters:

journalEntryId - the Id of the JournalEntry

Returns:

false if branching is not authorized, true otherwise

Throws:

NullArgumentException - journalEntryId is null

Compliance:

mandatory - This method must be implemented.

Notes:

If - the journalEntryId is not found, then it is acceptable to return false to indicate the lack of branching available.

canCreateBranchWithRecordTypes

boolean canCreateBranchWithRecordTypes(Type[] branchRecordTypes)

Tests if this user can create a single Branch using the desired record types. While JournalingManager.getBranchRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific Branch. Providing an empty array tests if a Branch can be created with no records.

Parameters:

branchRecordTypes - array of branch record types

Returns:

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

Throws:

NullArgumentException - branchyRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getBranchFormForCreate

BranchForm getBranchFormForCreate(Id journalEntryId,
                                Type[] branchRecordTypes)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

Gets the branch form for creating new entries. A new form should be requested for each create transaction.

Parameters:

journalEntryId - the Id of the JournalEntry

branchRecordTypes - array of branch record types

Returns:

the branch form

Throws:

NotFoundException - journalEntryId is not found

NullArgumentException - journalEntryId or branchRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createBranch

Branch createBranch(BranchForm branchForm)
                    throws OperationFailedException,
                           PermissionDeniedException

Creates a branch.

Parameters:

branchForm - the branch form

Returns:

a the new branch

Throws:

IllegalStateException - branchForm already used in a create transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - branchForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - branchForm did not originate from getBranchFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateBranches

boolean canUpdateBranches()

Tests if this user can update branches. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Branch will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.

Returns:

false if Branch modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getBranchFormForUpdate

BranchForm getBranchFormForUpdate(Id branchId)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

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

Parameters:

branchId - the Id of the Branch

Returns:

the branch form

Throws:

NotFoundException - branchId is not found

NullArgumentException - branchId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateBranch

void updateBranch(BranchForm branchForm)
                  throws OperationFailedException,
                         PermissionDeniedException

Updates an existing branch.

Parameters:

branchForm - the form containing the elements to be updated

Throws:

IllegalStateException - branchForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - branchForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - branchForm did not originate from getBranchFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canMergeBranches

boolean canMergeBranches()

Tests if this user can merge branches. A return of true does not guarantee successful authorization. A return of false indicates that it is known merging Branches will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer merging operations to unauthorized users.

Returns:

false if Branch merging is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

mergeBranches

JournalEntry mergeBranches(Id srcBranchId,
                         Id dstBranchId)
                           throws NotFoundException,
                                  OperationFailedException,
                                  PermissionDeniedException

Merges the source branch into the destination branch. A new journal entry is created to join the two branches.

Parameters:

srcBranchId - the Id of the Branch to merge from

dstBranchId - the Id of the Branch to merge into

Returns:

a the new journal entry

Throws:

NotFoundException - branchId not found

NullArgumentException - branchId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canSupersedeBranches

boolean canSupersedeBranches()

Tests if this user can supersede branches. A return of true does not guarantee successful authorization. A return of false indicates that it is known merging Branches will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer superseding operations to unauthorized users.

Returns:

false if Branch superseding is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

supersedeBranch

JournalEntry supersedeBranch(Id srcBranchId,
                           Id dstBranchId)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Joins the source branch to the destination branch by creating a new journal entry. The most recent version of the source branch supsrsedes the most recent versiuon of the desitination branch.

Parameters:

srcBranchId - the Id of the superseding Branch

dstBranchId - the Id of the Branch to override

Returns:

a the new journal entry

Throws:

NotFoundException - branchId not found

NullArgumentException - branchId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canDeleteBranches

boolean canDeleteBranches()

Tests if this user can delete branches. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a Branch will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer delete operations to unauthorized users.

Returns:

false if Branch deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteBranch

void deleteBranch(Id branchId)
                  throws NotFoundException,
                         OperationFailedException,
                         PermissionDeniedException

Deletes a branch and all associated versions.

Parameters:

branchId - the Id of the Branch to remove

Throws:

NotFoundException - branchId not found

NullArgumentException - branchId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageBranchAliases

boolean canManageBranchAliases()

Tests if this user can manage Id aliases for branches. 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 Branch aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasBranch

void aliasBranch(Id branchId,
               Id aliasId)
                 throws AlreadyExistsException,
                        NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

Adds an Id to a Branch for the purpose of creating compatibility. The primary Id of the Branch is determined by the provider. The new Id performs as an alias to the primary Id. If the alias is a pointer to another branch it is reassigned to the given branch Id.

Parameters:

branchId - the Id of a Branch

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - branchId not found

NullArgumentException - branchId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.