Package com.atlassian.confluence.impl.journal

Interface JournalManager

All Known Implementing Classes:

DefaultJournalManager

public interface JournalManager

This manager is an entry point to the journal subsystem.

Typical way to use journal subsystem is to call enqueue(JournalEntry) to queue new entries that should be actioned on each cluster node. Later on queued entries can be processed by calling processEntries(com.atlassian.confluence.api.model.journal.JournalIdentifier, int, com.google.common.base.Function) on each cluster node. Subsequent calls to processEntries will be passed only entries that were added since the last call on that cluster node.

Since:

5.6

Method Summary

Modifier and Type	Method	Description
int	countEntries(@NonNull JournalIdentifier journalId)	Counts the number of entries in a journal.
long	enqueue(@NonNull JournalEntry entry)	Adds the given entry to a journal.
void	enqueue(@NonNull Collection<JournalEntry> entries)	Adds a collection of entries to a journal.
long	getIgnoreWithinMillis()
Iterable<JournalEntry>	peek(@NonNull JournalIdentifier journalId, int maxEntries)	Return a copy of journal entries that are waiting to be processed.
<V> V	processEntries(@NonNull JournalIdentifier journalId, int maxEntries, @NonNull com.google.common.base.Function<Iterable<JournalEntry>,@NonNull EntryProcessorResult<V>> entryProcessor)	Deprecated. since 7.0.1.
default <V> V	processNewEntries(@NonNull JournalIdentifier journalId, int maxEntries, @NonNull Function<Iterable<JournalEntry>,@NonNull EntryProcessorResult<V>> entryProcessor)	Processes journal entries that were added since the last time this method was called for this journal on this cluster node.
void	reset(@NonNull JournalIdentifier journalId)	Resets the state of the journal so that all entries currently in the journal will be skipped.
void	waitForRecentEntriesToBecomeVisible()	Waits long enough to ensure that entries added before calling this method will be available to subsequent call to processNewEntries(JournalIdentifier, int, Function).

Method Detail

enqueue

long enqueue(@NonNull JournalEntry entry)
      throws org.springframework.dao.DataAccessException

Adds the given entry to a journal.

New journal is automatically created if a journal with the given name does not exists.

Parameters:

entry - entry to persist

Returns:

id generated for the entry

Throws:

org.springframework.dao.DataAccessException - if the entry could not be persisted

enqueue

void enqueue(@NonNull Collection<JournalEntry> entries)
      throws ServiceException

Adds a collection of entries to a journal.

Parameters:

entries - entries to persist

Throws:

ServiceException - if one of entries could not be persisted. In this case, the transaction is rolled back and no entries are persisted

Since:

8.2.0

processEntries

@Deprecated
<V> V processEntries(@NonNull JournalIdentifier journalId,
                     int maxEntries,
                     @NonNull com.google.common.base.Function<Iterable<JournalEntry>,@NonNull EntryProcessorResult<V>> entryProcessor)
              throws org.springframework.dao.DataAccessException

Deprecated.

since 7.0.1. Use processNewEntries(JournalIdentifier, int, Function)

Processes journal entries that were added since the last time this method was called for this journal on this cluster node.

This method does not return entries that were added immediately before calling this method. Use waitForRecentEntriesToBecomeVisible() for ensuring these entries will be included.

This method can miss some entries due to identifier assignment and entry insertion not being an atomic operation. The risk of missed entries can be reduced by creating new entries as close to transaction commit as possible.

If entryProcessor throws an exception, the same entries will be returned again when this method is next called for this journal on this cluster node.

New journal is automatically created if a journal with the given name does not exists.

Parameters:

journalId - only entries with this journal id will be returned

maxEntries - maximum number of entries to process

entryProcessor - function that will process entries that were added since the last time

Returns:

result of entryProcessor

Throws:

org.springframework.dao.DataAccessException - if entries could not be fetched or the journal state could not be saved

processNewEntries

default <V> V processNewEntries(@NonNull JournalIdentifier journalId,
                                int maxEntries,
                                @NonNull Function<Iterable<JournalEntry>,@NonNull EntryProcessorResult<V>> entryProcessor)
                         throws org.springframework.dao.DataAccessException

Processes journal entries that were added since the last time this method was called for this journal on this cluster node.

This method does not return entries that were added immediately before calling this method. Use waitForRecentEntriesToBecomeVisible() for ensuring these entries will be included.

This method can miss some entries due to identifier assignment and entry insertion not being an atomic operation. The risk of missed entries can be reduced by creating new entries as close to transaction commit as possible.

If entryProcessor throws an exception, the same entries will be returned again when this method is next called for this journal on this cluster node.

New journal is automatically created if a journal with the given name does not exists.

Parameters:

journalId - only entries with this journal id will be returned

maxEntries - maximum number of entries to process

entryProcessor - function that will process entries that were added since the last time

Returns:

result of entryProcessor

Throws:

org.springframework.dao.DataAccessException - if entries could not be fetched or the journal state could not be saved

Since:

7.0.1

waitForRecentEntriesToBecomeVisible

void waitForRecentEntriesToBecomeVisible()
                                  throws InterruptedException

Waits long enough to ensure that entries added before calling this method will be available to subsequent call to processNewEntries(JournalIdentifier, int, Function).

Throws:

InterruptedException - if the thread got interrupted

peek

Iterable<JournalEntry> peek(@NonNull JournalIdentifier journalId,
                            int maxEntries)

Return a copy of journal entries that are waiting to be processed.

Parameters:

journalId - only entries with this journal id will be returned

maxEntries - maximum number of entries to return

Returns:

a copy of journal entries that are waiting to be processed

reset

void reset(@NonNull JournalIdentifier journalId)

Resets the state of the journal so that all entries currently in the journal will be skipped.

Parameters:

journalId - identifier of the journal to reset

countEntries

int countEntries(@NonNull JournalIdentifier journalId)

Counts the number of entries in a journal.

Parameters:

journalId - identifier of the journal

getIgnoreWithinMillis

long getIgnoreWithinMillis()

Returns:

the time that new entries are ignored