Interface BranchAdminSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, 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 Details

    • 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 create branches. 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 creating branches 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 {@code 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.