com.hazelcast.journal

Interface EventJournal<E>

Type Parameters:

E - journal event type

All Known Subinterfaces:

CacheEventJournal, MapEventJournal

All Known Implementing Classes:

RingbufferCacheEventJournalImpl, RingbufferMapEventJournalImpl

public interface EventJournal<E>

The event journal is a container for events related to a data structure. This interface provides methods for distributed object event journals. Each distributed object and partition has its own event journal.

If an object is destroyed or migrated, the related event journal will be destroyed or migrated as well. In this regard, the event journal is co-located with the object partition and its replicas.

Since:

3.9

Method Summary

Modifier and Type	Method and Description
void	cleanup(ObjectNamespace namespace, int partitionId) Cleans up the event journal by removing any expired items.
void	destroy(ObjectNamespace namespace, int partitionId) Destroys the event journal for the given object and partition ID.
EventJournalConfig	getEventJournalConfig(ObjectNamespace namespace) Returns the event journal configuration or null if there is none or the journal is disabled for the given namespace.
WaitNotifyKey	getWaitNotifyKey(ObjectNamespace namespace, int partitionId) Return the WaitNotifyKey for objects waiting and notifying on the event journal.
boolean	hasEventJournal(ObjectNamespace namespace) Returns true if the object has a configured and enabled event journal.
void	isAvailableOrNextSequence(ObjectNamespace namespace, int partitionId, long sequence) Checks if the sequence is of an item that can be read immediately or is the sequence of the next item to be added into the event journal.
boolean	isNextAvailableSequence(ObjectNamespace namespace, int partitionId, long sequence) Checks if the sequence is the sequence of the next event to be added to the event journal.
long	newestSequence(ObjectNamespace namespace, int partitionId) Returns the sequence of the newest event stored in the event journal.
long	oldestSequence(ObjectNamespace namespace, int partitionId) Returns the sequence of the oldest event stored in the event journal.
<T> long	readMany(ObjectNamespace namespace, int partitionId, long beginSequence, ReadResultSetImpl<E,T> resultSet) Reads events from the journal in batches.
RingbufferConfig	toRingbufferConfig(EventJournalConfig config) Creates a new RingbufferConfig for a ringbuffer that will keep event journal events for a single partition.

Method Detail

newestSequence

long newestSequence(ObjectNamespace namespace,
                    int partitionId)

Returns the sequence of the newest event stored in the event journal.

Parameters:

namespace - the object namespace

partitionId - the partition ID of the event journal

Returns:

the sequence of the last stored event

Throws:

IllegalStateException - if there is no event journal configured for this object

oldestSequence

long oldestSequence(ObjectNamespace namespace,
                    int partitionId)

Returns the sequence of the oldest event stored in the event journal.

Parameters:

namespace - the object namespace

partitionId - the partition ID of the event journal

Returns:

the sequence of the oldest stored event

Throws:

IllegalStateException - if there is no event journal configured for this object

destroy

void destroy(ObjectNamespace namespace,
             int partitionId)

Destroys the event journal for the given object and partition ID.

Parameters:

namespace - the object namespace

partitionId - the partition ID of the entries in the journal

isAvailableOrNextSequence

void isAvailableOrNextSequence(ObjectNamespace namespace,
                               int partitionId,
                               long sequence)

Checks if the sequence is of an item that can be read immediately or is the sequence of the next item to be added into the event journal. Since this method allows the sequence to be one larger than the newestSequence(ObjectNamespace, int), the caller can use this method to check the sequence before performing a possibly blocking read.

Parameters:

namespace - the object namespace

partitionId - the partition ID of the entries in the journal

sequence - the sequence wanting to be read

Throws:

StaleSequenceException - if the requested sequence is smaller than the sequence of the oldest event (the sequence has been overwritten)

IllegalArgumentException - if the requested sequence is greater than the next available sequence + 1

IllegalStateException - if there is no event journal configured for this object

isNextAvailableSequence

boolean isNextAvailableSequence(ObjectNamespace namespace,
                                int partitionId,
                                long sequence)

Checks if the sequence is the sequence of the next event to be added to the event journal.

Parameters:

namespace - the object namespace

partitionId - the partition ID of the entries in the journal

sequence - the sequence to be checked

Returns:

true if the sequence is one greater than the sequence of the last event, false otherwise

Throws:

IllegalStateException - if there is no event journal configured for this object

getWaitNotifyKey

WaitNotifyKey getWaitNotifyKey(ObjectNamespace namespace,
                               int partitionId)

Return the WaitNotifyKey for objects waiting and notifying on the event journal.

Parameters:

namespace - the object namespace

partitionId - the partition ID of the entries in the journal

Returns:

the key for a wait notify object

Throws:

IllegalStateException - if there is no event journal configured for this object

readMany

<T> long readMany(ObjectNamespace namespace,
                  int partitionId,
                  long beginSequence,
                  ReadResultSetImpl<E,T> resultSet)

Reads events from the journal in batches. It will read up to the maximum number that the set can hold - see ReadResultSetImpl.isMaxSizeReached() or until the journal is exhausted. The resultSet allows filtering and projections on journal items so that the caller can control which data is returned.

If the set has reached its max size, the returned sequence is one greater than the sequence of the last item in the set. In other cases it means that the set hasn't reached its full size because we have reached the end of the event journal. In this case the returned sequence is one greater than the sequence of the last stored event.

Type Parameters:

T - the return type of the projected events

Parameters:

namespace - the object namespace

partitionId - the partition ID of the entries in the journal

beginSequence - the sequence of the first item to read.

resultSet - the container for read, filtered and projected events

Returns:

returns the sequenceId of the next item to read

Throws:

IllegalStateException - if there is no event journal configured for this object

StaleSequenceException - if the requested sequence is smaller than the sequence of the oldest event

IllegalArgumentException - if the requested sequence is greater than the sequence of the newest event + 1

See Also:

isAvailableOrNextSequence(ObjectNamespace, int, long)

cleanup

void cleanup(ObjectNamespace namespace,
             int partitionId)

Cleans up the event journal by removing any expired items. Items are considered expired as according to the configured expiration policy.

Parameters:

namespace - the object namespace

partitionId - the partition ID of the entries in the journal

Throws:

IllegalStateException - if there is no event journal configured for this object

hasEventJournal

boolean hasEventJournal(ObjectNamespace namespace)

Returns true if the object has a configured and enabled event journal.

Parameters:

namespace - the object namespace

Returns:

true if the object has a configured and enabled event journal, false otherwise

getEventJournalConfig

EventJournalConfig getEventJournalConfig(ObjectNamespace namespace)

Returns the event journal configuration or null if there is none or the journal is disabled for the given namespace.

NOTE
If the Cluster.getClusterVersion() is less than Versions.V3_9, this method will return null, regardless of whether the journal is actually enabled by the configuration. This is because some members might not know how to save journal events and respond to subscribe/read operations.

Parameters:

namespace - the object namespace of the specific distributed object

Returns:

the journal configuration or null if the journal is not enabled or available

toRingbufferConfig

RingbufferConfig toRingbufferConfig(EventJournalConfig config)

Creates a new RingbufferConfig for a ringbuffer that will keep event journal events for a single partition.

Parameters:

config - the event journal config

Returns:

the ringbuffer config for a single partition of the event journal