org.osid.journaling

Interface JournalEntryAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

JournalEntryBatchAdminSession

public interface JournalEntryAdminSession
extends OsidSession

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

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

The delete operations delete JournalEntries.

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	aliasJournalEntry(Id journalEntryId, Id aliasId) Adds an Id to a JournalEntry for the purpose of creating compatibility.
boolean	canCreateJournalEntries() Tests if this user can create journal entries.
boolean	canCreateJournalEntryWithRecordTypes(Type[] journalEntryRecordTypes) Tests if this user can create a single JournalEntry using the desired record interface types.
boolean	canDeleteJournalEntries() Tests if this user can delete journal entries.
boolean	canManageJournalEntryAliases() Tests if this user can manage Id aliases for journal entries.
boolean	canUpdateJournalEntries() Tests if this user can update journal entries.
JournalEntry	createJournalEntry(JournalEntryForm journalEntryForm) Creates a new JournalEntry.
void	deleteJournalEntry(Id journalEntryId) Deletes a JournalEntry.
Journal	getJournal() Gets the Journal associated with this session.
JournalEntryForm	getJournalEntryFormForCreate(Id branchId, Id sourceId, Type[] journalEntryRecordTypes) Gets the journal entry form for creating new entries.
JournalEntryForm	getJournalEntryFormForUpdate(Id journalEntryId) Gets the journal entry form for updating an existing entry.
Id	getJournalId() Gets the Journal Id associated with this session.
void	updateJournalEntry(JournalEntryForm journalEntryForm) Updates an existing journal entry.

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.

canCreateJournalEntries

boolean canCreateJournalEntries()

Tests if this user can create journal entries. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a JournalEntry 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 JournalEntry creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateJournalEntryWithRecordTypes

boolean canCreateJournalEntryWithRecordTypes(Type[] journalEntryRecordTypes)

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

Parameters:

journalEntryRecordTypes - array of journal entry record types

Returns:

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

Throws:

NullArgumentException - journalEntryRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getJournalEntryFormForCreate

JournalEntryForm getJournalEntryFormForCreate(Id branchId,
                                            Id sourceId,
                                            Type[] journalEntryRecordTypes)
                                              throws NotFoundException,
                                                     OperationFailedException,
                                                     PermissionDeniedException

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

Parameters:

branchId - the Id for the branch

sourceId - the Id for the journaled object

journalEntryRecordTypes - array of journal entry record types

Returns:

the journal entry form

Throws:

NotFoundException - branchId is not found

NullArgumentException - branchId, sourceId, or journalEntryRecordTypes 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.

createJournalEntry

JournalEntry createJournalEntry(JournalEntryForm journalEntryForm)
                                throws OperationFailedException,
                                       PermissionDeniedException

Creates a new JournalEntry.

Parameters:

journalEntryForm - the form for this JournalEntry

Returns:

the new JournalEntry

Throws:

IllegalStateException - journalEntryForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - journalEntryForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - journalEntryForm did not originate from getJournalEntryFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateJournalEntries

boolean canUpdateJournalEntries()

Tests if this user can update journal entries. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a 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.

Returns:

false if JournalEntry modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getJournalEntryFormForUpdate

JournalEntryForm getJournalEntryFormForUpdate(Id journalEntryId)
                                              throws NotFoundException,
                                                     OperationFailedException,
                                                     PermissionDeniedException

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

Parameters:

journalEntryId - the Id of the JournalEntry

Returns:

the entry form

Throws:

NotFoundException - journalEntryId is not found

NullArgumentException - journalEntryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateJournalEntry

void updateJournalEntry(JournalEntryForm journalEntryForm)
                        throws OperationFailedException,
                               PermissionDeniedException

Updates an existing journal entry.

Parameters:

journalEntryForm - the form containing the elements to be updated

Throws:

IllegalStateException - journalEntryForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - journalEntryForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - journalEntryForm did not originate from getJournalEntryFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteJournalEntries

boolean canDeleteJournalEntries()

Tests if this user can delete journal entries. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a JournalEntry 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 JournalEntry deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteJournalEntry

void deleteJournalEntry(Id journalEntryId)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Deletes a JournalEntry.

Parameters:

journalEntryId - the Id of the JournalEntry to remove

Throws:

NotFoundException - journalEntryId not found

NullArgumentException - journalEntryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageJournalEntryAliases

boolean canManageJournalEntryAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasJournalEntry

void aliasJournalEntry(Id journalEntryId,
                     Id aliasId)
                       throws AlreadyExistsException,
                              NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

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

Parameters:

journalEntryId - the Id of a JournalEntry

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - journalEntryId not found

NullArgumentException - journalEntryId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.