org.dataconservancy.pass.support.messaging.cri

Class CriticalPath

java.lang.Object

org.dataconservancy.pass.support.messaging.cri.CriticalPath

All Implemented Interfaces:

CriticalRepositoryInteraction

@Component
public class CriticalPath
extends Object
implements CriticalRepositoryInteraction

Provides the guarantees set by CriticalRepositoryInteraction, and boilerplate for interacting with, and modifying the state of, repository resources.

Note that the critical methods may modify the state of a resource. If the the critical method modifies resource state (tested according to PassEntity.hashCode()), the resource will be persisted in the repository. Likewise, if the critical method does not modify resource state, it will not attempt to persist the resource (since there are no changes to persist). Even though update requests (e.g. implemented as PATCH HTTP requests) that do not change the state of the resource are idempotent, Fedora issues a JMS message indicating that the resource has been modified. This happens despite the "business" state of the resource having not been changed.

Author:

Elliot Metsger (emetsger@jhu.edu)

Nested Class Summary

Nested classes/interfaces inherited from interface org.dataconservancy.pass.support.messaging.cri.CriticalRepositoryInteraction

CriticalRepositoryInteraction.CriticalResult<R,T>

Constructor Summary

Constructors

Constructor and Description
CriticalPath(org.dataconservancy.pass.client.PassClient passClient, ConflictHandler conflictHandler)

Method Summary

Modifier and Type	Method and Description
<R,T extends org.dataconservancy.pass.model.PassEntity> CriticalRepositoryInteraction.CriticalResult<R,T>	performCritical(URI uri, Class<T> clazz, Predicate<T> precondition, BiPredicate<T,R> postcondition, Function<T,R> critical) Execute a critical interaction with the repository, subject to precondition.
<R,T extends org.dataconservancy.pass.model.PassEntity> CriticalRepositoryInteraction.CriticalResult<R,T>	performCritical(URI uri, Class<T> clazz, Predicate<T> precondition, Predicate<T> postcondition, Function<T,R> critical) Execute a critical interaction with the repository, subject to precondition.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CriticalPath

public CriticalPath(org.dataconservancy.pass.client.PassClient passClient,
                    ConflictHandler conflictHandler)

Method Detail

performCritical

public <R,T extends org.dataconservancy.pass.model.PassEntity> CriticalRepositoryInteraction.CriticalResult<R,T> performCritical(URI uri,
                                                                                                                                 Class<T> clazz,
                                                                                                                                 Predicate<T> precondition,
                                                                                                                                 Predicate<T> postcondition,
                                                                                                                                 Function<T,R> critical)

Execute a critical interaction with the repository, subject to precondition. Success of the interaction depends on the evaluation of postcondition.

See the other form of performCritical if the postcondition needs to evaluate both the PassEntity resource and the return from the critical path.

Implementation notes

Executes in order:

1. Obtain a lock over the interned, string form of the uri, insuring no interference from other threads executing in this JVM
2. Read the PassEntity identified by uri from the repository, short-circuiting the interaction by returning a CriticalResult if an Exception is thrown
3. Apply the pre-condition Predicate, short-circuiting the interaction by returning a CriticalResult if the condition fails
4. Perform the critical interaction, short-circuiting the interaction by returning a CriticalResult if an Exception is thrown
5. If the critical interaction modifies the resource, update the resource in the repository. Read the resource from the repository (even if no update is performed). If a ConflictUpdateException is thrown during the update, it is supplied to the ConflictHandler for resolution. If any other Exception is thrown, the interaction is short-circuited, and a CriticalResult returned.
6. Apply the post-condition Predicate and returns CriticalResult

Exception handling

All code that executes within this method is executed within try/catch blocks. Each lambda passed to this method executes within a try/catch, and all supporting code within this method executes within try/catch blocks. If an Exception is thrown, it will be caught, placed in the CriticalResult, and this method immediately returns. The caller is responsible for evaluating the CriticalResult and determining success or failure of this method.

Specified by:

performCritical in interface CriticalRepositoryInteraction

Type Parameters:

T - the type of PassEntity

R - the type of Object returned by critical

Parameters:

uri - the uri of the PassEntity which is the subject of the critical pathv

clazz - the concrete Class of the PassEntity represented by uri

precondition - precondition that must evaluate to true for the critical path to execute

postcondition - postcondition that must evaluate to true for the CriticalResult to be considered successful

critical - the critical interaction with the repository, which may return a result of type R

Returns:

a CriticalResult encapsulating the PassEntity, the return from the critical path, any exception thrown, and the overall success as determined by the post-condition

performCritical

public <R,T extends org.dataconservancy.pass.model.PassEntity> CriticalRepositoryInteraction.CriticalResult<R,T> performCritical(URI uri,
                                                                                                                                 Class<T> clazz,
                                                                                                                                 Predicate<T> precondition,
                                                                                                                                 BiPredicate<T,R> postcondition,
                                                                                                                                 Function<T,R> critical)

Execute a critical interaction with the repository, subject to precondition. Success of the interaction depends on the evaluation of postcondition.

See the other form of performCritical if the postcondition only needs to evaluate the PassEntity resource.

Implementation notes

Executes in order:

1. Obtain a lock over the interned, string form of the uri, insuring no interference from other threads executing in this JVM
2. Read the PassEntity identified by uri from the repository, short-circuiting the interaction by returning a CriticalResult if an Exception is thrown
3. Apply the pre-condition Predicate, short-circuiting the interaction by returning a CriticalResult if the condition fails
4. Perform the critical interaction, short-circuiting the interaction by returning a CriticalResult if an Exception is thrown
5. If the critical interaction modifies the resource, update the resource in the repository. Read the resource from the repository (even if no update is performed). If a ConflictUpdateException is thrown during the update, it is supplied to the ConflictHandler for resolution. If any other Exception is thrown, the interaction is short-circuited, and a CriticalResult returned.
6. Apply the post-condition BiPredicate and returns CriticalResult

Exception handling

All code that executes within this method is executed within try/catch blocks. Each lambda passed to this method executes within a try/catch, and all supporting code within this method executes within try/catch blocks. If an Exception is thrown, it will be caught, placed in the CriticalResult, and this method immediately returns. The caller is responsible for evaluating the CriticalResult and determining success or failure of this method.

Specified by:

performCritical in interface CriticalRepositoryInteraction

Type Parameters:

T - the type of PassEntity

R - the type of Object returned by critical

Parameters:

uri - the uri of the PassEntity which is the subject of the critical pathv

clazz - the concrete Class of the PassEntity represented by uri

precondition - precondition that must evaluate to true for the critical path to execute

postcondition - postcondition that must evaluate to true for the CriticalResult to be considered successful

critical - the critical interaction with the repository, which may return a result of type R

Returns:

a CriticalResult encapsulating the PassEntity, the return from the critical path, any exception thrown, and the overall success as determined by the post-condition