Interface TrsStore

Method Details

• createSynchronizer

  Executor createSynchronizer()

  Creates an executor that guarantees runnable instances handling data related to this store are never executed concurrently but one at a time across the whole web application. If the web application is deployed in a cluster, the executor must ensure only one cluster node can execute at a time the runnable instances.

  Subclasses may choose to use LockExecutors to obtain an executor.

  Returns:

  an executor that guarantees runnable instances are executed one at a time.

  See Also:

  • TrsStoreSynchronizer
  • LockExecutors

• restore

  void restore() throws TrsStoreException

  Restores the store's state to the starting stage.

  Throws:

  CompletionException - if the underlying task cannot complete due to synchronization problems (e.g. a lock cannot be acquired).

  TrsStoreException - if the storage cannot be reestablished to its original state by any other reason.

• saveControl

  void saveControl(TrsServiceControl control) throws TrsStoreException

  Saves the current state of a TRS service control.

  Parameters:

  control - the control to be saved.

  Throws:

  TrsStoreException - if the control cannot be saved.

• getControl

  TrsServiceControl getControl()

  Retrieves the current state of a TRS service control. This method should always return an instance even if an internal implementation-specific exception occurs, in such case, a default instance should be returned to restart over the TRS feed.

  Returns:

  the TRS service control.

• addBaseMembers

  void addBaseMembers(Function<Consumer<ResourceSeed>,?> membersProvider) throws TrsStoreException

  Adds members to the base.

  To support a consistent pagination, this method is expected to keep an order between members to add and existing members. First appended members must have lesser members ids than those appended last. When assigning ids to members to add, implementation shall rely on TrsServiceControl.getLastBaseMemberId() as starting point. Once members are added, implementation must call TrsServiceControl.setLastBaseMemberId(long) to keep track of the last identifier used.

  The function argument provides access to ResourceSeeds to be added in this store as base members. Implementation must call the apply() method of this function and use as argument a Consumer to get notified of members.

  Implementation is advised to use a BufferedConsumer for optimal performance. Implementation is also advised to use a transaction per collection of members to add.

  Parameters:

  membersProvider - a function that provides access to ResourceSeeds to add as base members.

  Throws:

  TrsStoreException - if any other TRS store error occurs.

  Since:

  3.11.0

  See Also:

  • BufferedConsumer

• rebase

  void rebase(Function<Consumer<ChangeEventSeed>,?> eventsProvider) throws TrsStoreException

  Refreshes members in base, to add or remove members given some events in the change log.

  Implementation must call the apply() method of this function and use as argument a Consumer to get notified of change events. Implementation must apply the following changes in base members:

  • Add as base member each resource whose ResourceEvent.getType() is CREATED
  • Remove from base members each resource whose ResourceEvent.getType() is DELETED

  Resource events are already ordered so that implementation can execute actions without additional consideration. Once events are processed, implementation must call TrsServiceControl.setBaseCutoffEvent(ChangeEventSeed), with the last event processed within the transaction as argument, and TrsServiceControl.setBaseUpdate(Date), with current time as argument. If base members were added, implementation must also call TrsServiceControl.setLastBaseMemberId(long).

  Implementation is advised to use a BufferedConsumer for optimal performance. Implementation is also advised to use a transaction per collection of events.

  Parameters:

  eventsProvider - a function that provides access to change events that should impact base members.

  Throws:

  TrsStoreException - if any other TRS store error occurs.

  Since:

  3.11.0

• collectBaseMembers

  Optional<Long> collectBaseMembers(Optional<Long> startingMemberId, Optional<Integer> size, Optional<Integer> resourceType, Optional<String> resourceProject, Consumer<ResourceSeed> baseMembersConsumer) throws TrsStoreException

  Collects base members, either all of them or just a page. Consumers may raise CancellationException to indicate the collecting process must stop, but implementations must no propagate this exception, this is a convenient way to stop a searching process.

  Parameters:

  startingMemberId - optional, the initial member (id) on the page. If not present, starts from first page (member).

  size - optional, number of members to populate including startingMemberId if present (used for pagination).

  resourceType - optional, only members of this type will be collected.

  resourceProject - optional, only members of this project area will be collected.

  baseMembersConsumer - base members consumer.

  Returns:

  if present, the id of the next member in the next page, otherwise it means no more pages exist (or pagination was not used).

  Throws:

  CompletionException - if consumer raise it to stop the collecting process due an error occurred.

  TrsStoreException - if any other TRS store error occurs.

  Since:

  3.3.0

• pushResourceEvents

  void pushResourceEvents(Function<Consumer<ResourceEvent>,?> eventsProvider) throws TrsStoreException

  Stores the latest events in the trs:ChangeLog.

  The function argument provides access to resource events to be added in this store. Implementation must call the apply() method of this function and use as argument a Consumer to get notified of events.

  For each provided resource event, implementation must assign an event order when creating and storing the corresponding change event. Implementation shall rely on TrsServiceControl.getLastEventOrder() as starting point. Once events are added, implementation must call TrsServiceControl.setLastEventOrder(long) to keep track of the last event order used.

  Implementation is advised to use a BufferedConsumer for optimal performance. Implementation is also advised to use a transaction per collection of events to add.

  Parameters:

  eventsProvider - a function that provides access to resource events to become part of the trs:ChangeLog.

  Throws:

  TrsStoreException - if any other TRS store error occurs.

  Since:

  3.11.0

  See Also:

  • BufferedConsumer

• pollChangeEventSeeds

  Optional<Long> pollChangeEventSeeds(long startingOrder, int count, Consumer<ChangeEventSeed> changeEventsConsumer) throws TrsStoreException

  Collects (backwards) a given number of events from the trs:ChangeLog. This method is not forced to resolve all requested events, it must just provide as many as it has from requested and from startingOrder. Implementations must also consider that a count of zero may be requested. In this case, no events must be added to target, but the existence of a further event must be resolved in order to determine whether or not a next page exists. This latter must be reflected in the return value. Consumers may raise CancellationException to indicate the collecting process must stop, but implementations must no propagate this exception, this is a convenient way to stop a searching process.

  Parameters:

  startingOrder - starting event order inclusive.

  count - number of events to poll.

  changeEventsConsumer - changes events consumer.

  Returns:

  event order of previous event (not included in the extraction) if present; empty Optional if no more events exists.

  Throws:

  CompletionException - if consumer raise it to stop the collecting process due an error occurred.

  TrsStoreException - if any other TRS store error occurs.

  Since:

  4.0.0

• collectChangeEventSeeds

  void collectChangeEventSeeds(Optional<ChangeEventSeed> since, Optional<ResourceEvent.Type> eventType, Consumer<ChangeEventSeed> changeEventsConsumer) throws TrsStoreException

  Collects (forwards) all existing events in trs:ChangeLog since (optionally) a particular event. Consumers may raise CancellationException to indicate the collecting process must stop, but implementations must no propagate this exception, this is a convenient way to stop a searching process.

  Parameters:

  since - starting event (exclusive) to be consumed. If present, typically the last trs:Base cutoff event.

  eventType - the type of event to collect; all types of events if Optional.empty().

  changeEventsConsumer - changes events consumer.

  Throws:

  CompletionException - if consumer raise it to stop the collecting process due an error occurred.

  TrsStoreException - if any other TRS store error occurs.

• countChangeEventSeeds

  long countChangeEventSeeds(Optional<ChangeEventSeed> since) throws TrsStoreException

  Counts how many resource events exist in trs:ChangeLog since (optionally) a particular event.

  Parameters:

  since - starting point to count (exclusive). If present, it is typically the last trs:Base cutoff event.

  Returns:

  number of events in trs:ChangeLog since changeEvent.

  Throws:

  TrsStoreException - if any other TRS store error occurs.

• getFirstChangeEventSince

  Optional<ChangeEventSeed> getFirstChangeEventSince(Date date) throws TrsStoreException

  Determines the oldest change event on or after a given a date. Implementations should compare only the date part, not the time.

  Parameters:

  date - point of reference to find the event

  Returns:

  an empty Optional if no event exists; the contained reference otherwise.

  Throws:

  TrsStoreException - if any other TRS store error occurs.

  Since:

  3.8.0

• removeChangeEventSeedsBefore

  int removeChangeEventSeedsBefore(long order) throws TrsStoreException

  Removes events in trs:ChangeLog prior or equal to a given order.

  Parameters:

  order - event order of reference (inclusive) to remove events.

  Returns:

  number of deleted events.

  Throws:

  TrsStoreException - if any other TRS store error occurs.

  Since:

  4.0.0

• isResourceExposed

  boolean isResourceExposed(ResourceSeed seed) throws TrsStoreException

  Determines whether a resource is exposed or not. An exposed resource is one that is part of the TRS feed, this means there has not been a DELETION event for it and it is either part of the trs:base or there is a CREATION event in the trs:changeLog.

  Implementation must not check whether base was updated, as testing resource exposure is used to recover from a base partially initialized.

  Parameters:

  seed - the resource seed.

  Returns:

  true if resource is exposed, false otherwise.

  Throws:

  TrsStoreException - if a TRS store error occurs.

• synchronizeResourceEvents

  void synchronizeResourceEvents() throws TrsStoreException

  Synchronizes all the stored events (since the last synchronization) so all of them get their right order and become visible to the TRS feed.

  When assigning orders to events, implementation shall rely on TrsServiceControl.getLastEventOrder() as starting point. Once event are synchronized, implementation must call TrsServiceControl.setLastEventOrder(long) to keep track of the last event order used.

  Throws:

  TrsStoreException - if the synchronization fails.

  Since:

  3.11.0

• getStagingResourceEventStore

  StagingResourceEventStore getStagingResourceEventStore(String id) throws TrsStoreException

  Gets a staging resource event store for a given identifier.

  Parameters:

  id - the given identifier.

  Returns:

  the corresponding staging resource event store.

  Throws:

  TrsStoreException - if the store cannot be retrieved.

  Since:

  3.11.0