org.apache.gobblin.broker.iface

Interface SharedResourcesBroker<S extends ScopeType<S>>

Type Parameters:

S - the ScopeType tree used by this SharedResourcesBroker.

All Superinterfaces:

AutoCloseable, Closeable

public interface SharedResourcesBroker<S extends ScopeType<S>>
extends Closeable

A class that provides access to objects shared by multiple components within a process, as well as objects virtually shared among different processes (i.e. objects that synchronize with equivalent objects in other processes). Different parts of an application may require objects that are ideally shared. For example, if multiple objects are writing to the same file, it is convenient to have a single file handle. Instead of passing around all shared objects, using static objects, or doing dependency injection, a SharedResourcesBroker provides a way to acquire such shared objects as needed, letting the broker manage the lifecycle of the objects. Objects are created using SharedResourceFactorys, and are specific to a particular ScopeInstance and SharedResourceKey. ScopeInstances represent a DAG of relevant scopes in the application, for example GLOBAL -> JOB -> TASK. SharedResourceKey identify different objects created by the same factory, for example handles to different files could be keyed by the file path. SharedResourcesBroker guarantees that multiple requests for objects with the same factory, ScopeInstance and SharedResourceKey return the same object, even if called for different SharedResourcesBroker instances. This guarantee requires that new brokers are created using newSubscopedBuilder(ScopeInstance) only.

Method Summary

Modifier and Type	Method and Description
<T,K extends SharedResourceKey> void	bindSharedResourceAtScope(SharedResourceFactory<T,K,S> factory, K key, S scopeType, T instance) Bind an instance to the input factory, key, and scope.
void	close() Close all resources at this and descendant scopes, meaning Closeables will be closed and Services will be shut down.
ScopeInstance<S>	getScope(S scopeType) Get the ScopeInstance in this brokers topology at the provided ScopeType.
<T,K extends SharedResourceKey> T	getSharedResource(SharedResourceFactory<T,K,S> factory, K key) Get a shared resource created by the input SharedResourceFactory.
<T,K extends SharedResourceKey> T	getSharedResourceAtScope(SharedResourceFactory<T,K,S> factory, K key, S scopeType) Get a shared resource created by the input SharedResourceFactory at the ScopeInstance returned by #getScope) on the input ScopeType.
SubscopedBrokerBuilder<S,?>	newSubscopedBuilder(ScopeInstance<S> subscope) Get a builder to create a descendant SharedResourcesBroker.
ScopeInstance<S>	selfScope()

Method Detail

selfScope

ScopeInstance<S> selfScope()

Returns:

The lowest defined ScopeInstance in this SharedResourcesBroker. This is provides the lowest ScopeType at which the SharedResourcesBroker can return shared objects.

getScope

ScopeInstance<S> getScope(S scopeType)
                   throws NoSuchScopeException

Get the ScopeInstance in this brokers topology at the provided ScopeType.

Throws:

NoSuchScopeException - if the input ScopeType is lower than that of selfScope().

getSharedResource

<T,K extends SharedResourceKey> T getSharedResource(SharedResourceFactory<T,K,S> factory,
                                                    K key)
                                             throws NotConfiguredException

Get a shared resource created by the input SharedResourceFactory. The resource will be shared at least by all brokers with the same selfScope(), but the factory may chose to create the resource at a higher scope.

Type Parameters:

T - type of object created by the factory.

K - type of factory accepted by the factory.

Parameters:

factory - The SharedResourceFactory used to create the shared object.

key - Identifies different objects from the same factory in the same ScopeInstance.

Returns:

an object of type T.

Throws:

NotConfiguredException

getSharedResourceAtScope

<T,K extends SharedResourceKey> T getSharedResourceAtScope(SharedResourceFactory<T,K,S> factory,
                                                           K key,
                                                           S scopeType)
                                                    throws NotConfiguredException,
                                                           NoSuchScopeException

Get a shared resource created by the input SharedResourceFactory at the ScopeInstance returned by #getScope) on the input ScopeType.

Type Parameters:

T - type of object created by the factory.

K - type of factory accepted by the factory.

Parameters:

factory - The SharedResourceFactory used to create the shared object.

key - Identifies different objects from the same factory in the same ScopeInstance.

scopeType - ScopeType at which the object will be obtained.

Returns:

an object of type T.

Throws:

NotConfiguredException

NoSuchScopeException

bindSharedResourceAtScope

<T,K extends SharedResourceKey> void bindSharedResourceAtScope(SharedResourceFactory<T,K,S> factory,
                                                               K key,
                                                               S scopeType,
                                                               T instance)
                                                        throws NoSuchScopeException

Bind an instance to the input factory, key, and scope.

Type Parameters:

T - type of object created by the factory.

K - type of factory accepted by the factory.

Parameters:

factory - The SharedResourceFactory used to create the shared object.

key - Identifies different objects from the same factory in the same ScopeInstance.

scopeType - ScopeType at which the object will be obtained.

instance - the instance to bind.

Throws:

NoSuchScopeException

close

void close()
    throws IOException

Close all resources at this and descendant scopes, meaning Closeables will be closed and Services will be shut down. Future calls to get the same resource will instantiate a new resource instead. Best practice guideline: this method should only be called by the object who created the SharedResourcesBroker. Objects or methods which received an already built SharedResourcesBroker should not call this method.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException

newSubscopedBuilder

SubscopedBrokerBuilder<S,?> newSubscopedBuilder(ScopeInstance<S> subscope)

Get a builder to create a descendant SharedResourcesBroker.

Parameters:

subscope - the ScopeInstance of the new SharedResourcesBroker.

Returns:

a SubscopedBrokerBuilder.