com.atlassian.bamboo.core

Interface ScopedExclusionService

All Known Implementing Classes:

ScopedExclusionServiceImpl

public interface ScopedExclusionService

Classes implementing this interface let you execute code guarded by mutual exclusion locks. You should use methods of this class directly only if there are no adequate methods in com.atlassian.bamboo.core.ScopedExclusionServiceHelper class. All taken locks are exclusive. A lock is always taken in a scope. For example a lock on PROJECT_DATA scope defined by project name 'MINE-ALLMINE' would be different than a lock taken on JOB_KEY scope with name 'MINE-ALLMINE'. You can use any object for locking, but since this service is shared, it's very important to lock the same objects that other users of service lock within the same exclusion scope. That's why use of ExclusionScopeType or, better yet com.atlassian.bamboo.core.ScopedExclusionServiceHelper is strongly recommended.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ScopedExclusionService.ExclusionScopeType Predefined exclusion scopes.
static interface	ScopedExclusionService.ExclusiveFunction<F,V,E extends Throwable> Function to call once the object is locked.
static interface	ScopedExclusionService.GeneratorCallable<V,E extends Throwable> Generator called to generate new names for objects.

Method Summary

Modifier and Type	Method and Description
<S,V,E extends Throwable> io.atlassian.fugue.Either<Boolean,Optional<V>>	tryWithLock(Enum<?> scopeType, S objectToLock, ScopedExclusionService.ExclusiveFunction<S,V,E> function) Executes function with lock taken in a given scope and object name or returns immediately if lock is already taken.
<S,V,E extends Throwable> V	withLock(Enum<?> scopeType, S objectToLock, ScopedExclusionService.ExclusiveFunction<S,V,E> function) Executes function with lock taken in a given scope and object name.
<S,V,E extends Throwable,F extends Throwable> V	withNewLockedObject(Enum<?> generationScope, S objectToLockDuringGeneration, Enum<?> generatedObjectScope, ScopedExclusionService.GeneratorCallable<S,F> objectGenerator, ScopedExclusionService.ExclusiveFunction<S,V,E> function) Executes code with a new, unique name generated within given exclusion scope and locked for exclusive use.

Method Detail

withLock

<S,V,E extends Throwable> V withLock(@NotNull
                                     Enum<?> scopeType,
                                     @NotNull
                                     S objectToLock,
                                     @NotNull
                                     ScopedExclusionService.ExclusiveFunction<S,V,E> function)
                              throws E extends Throwable

Executes function with lock taken in a given scope and object name.

Parameters:

scopeType - type of scope (if we wanted to lock a Job, this would be JOB_KEY - jobs are locked by key)

objectToLock - object to lock within scope (if we wanted to lock a Job, this would be job key)

function - the function to call

Returns:

the result of function

Throws:

E - exception thrown from function

E extends Throwable

tryWithLock

<S,V,E extends Throwable> io.atlassian.fugue.Either<Boolean,Optional<V>> tryWithLock(@NotNull
                                                                                     Enum<?> scopeType,
                                                                                     @NotNull
                                                                                     S objectToLock,
                                                                                     @NotNull
                                                                                     ScopedExclusionService.ExclusiveFunction<S,V,E> function)
                                                                              throws E extends Throwable

Executes function with lock taken in a given scope and object name or returns immediately if lock is already taken.

Parameters:

scopeType - type of scope (if we wanted to lock a Job, this would be JOB_KEY - jobs are locked by key)

objectToLock - object to lock within scope (if we wanted to lock a Job, this would be job key)

function - the function to call

Returns:

either the result of function or false if the lock could not be acquired

Throws:

E - exception thrown from function

E extends Throwable

withNewLockedObject

<S,V,E extends Throwable,F extends Throwable> V withNewLockedObject(@NotNull
                                                                    Enum<?> generationScope,
                                                                    @Nullable
                                                                    S objectToLockDuringGeneration,
                                                                    @Nullable
                                                                    Enum<?> generatedObjectScope,
                                                                    @NotNull
                                                                    ScopedExclusionService.GeneratorCallable<S,F> objectGenerator,
                                                                    @NotNull
                                                                    ScopedExclusionService.ExclusiveFunction<S,V,E> function)
                                                             throws E extends Throwable,
                                                                    F extends Throwable

Executes code with a new, unique name generated within given exclusion scope and locked for exclusive use. Objects to lock are generated by objectGenerator. If the generated object is already locked, the generator will be asked for a new object. The whole generation (including all unsuccesful lock attempts) will be run with an exclusive lock held on objectToLockDuringGeneration within generationScope. As soon as a valid object, locked within generatedObjectScope is generated: - other generations within the same scope may continue and - the function will be called. - the generation lock is dropped

Throws:

E extends Throwable