com.atlassian.extension.api

Interface ExtensionAccessor

@PublicApi
public interface ExtensionAccessor

Provides the ability to query for current extensions.

An ExtensionAccessor is expected to inspect some implicit context to determine availability of extensions.

Since:

1.0.0

Method Summary

Modifier and Type	Method and Description
<E> Iterable<E>	getExtensionsByClass(Class<E> extensionClass) Obtains a snapshot of extensions for the given extension class that are available in the current implicit context.
<E,D> Supplier<D>	getExtensionsByClassSupplier(Class<E> extensionClass, Function<Iterable<E>,D> extensionTransform, Function<Iterable<D>,D> extensionReduce) Obtains a supplier for getting extensions for the given extension class available in the current implicit context, possibly transformed by a map reduce operation.

Method Detail

getExtensionsByClass

@Nonnull
<E> Iterable<E> getExtensionsByClass(Class<E> extensionClass)

Obtains a snapshot of extensions for the given extension class that are available in the current implicit context.

Extensions which subclass extensionClass are returned, provided they currently are available.

Type Parameters:

E - the class of the extension.

Parameters:

extensionClass - the class of the extensions to return.

Returns:

an immutable iterable with a snapshot of all extensions of extensionClass or subclasses that are currently available. All elements returned by the iterator of the returned iterable are non-null.

getExtensionsByClassSupplier

@Nonnull
<E,D> Supplier<D> getExtensionsByClassSupplier(Class<E> extensionClass,
                                                        Function<Iterable<E>,D> extensionTransform,
                                                        Function<Iterable<D>,D> extensionReduce)

Obtains a supplier for getting extensions for the given extension class available in the current implicit context, possibly transformed by a map reduce operation.

This is intended to provide a interface which can be aggressively cached by the implementation allowing for different providers with different abilities to cache.

This method is for clients that need to process (via map reduce) the extensions of a given class multiple times, possibly with different implicit context at different times, possibly concurrently. It returns a supplier whose get method returns a value of the reduced type D which was obtained by

1. determining the multiset of extensions of the given class, or a subclass, currently available when the get method is called,
2. partitioning that multiset into some number of parts, where the order within the parts is not defined,
3. calling extensionTransform on each part, and
4. calling extensionReduce on the results in some undefined order.

Importantly, the calls to extensionTransform and extensionReduce may be made at any time, possibly by other threads, possibly after this method is called, and possibly before the returned suppliers get is called. If the implementation can determine that an existing part of of currently available extensions of the given class have already been transformed, reduced, or both, then it may reuse old intermediate values.

Callers must allow for the above semantics when providing transform and reduce operations.

Type Parameters:

E - the class of the extension.

D - the reduced type returned by the provided extensionTransform and extensionReduce.

Parameters:

extensionClass - the class of the extensions to obtain.

extensionTransform - a transformation to be applied to arbitrary groups of the extensions. This may be called multiple times, possibly concurrently, for varying subsets and orders of the extensions, as and when the returned supplier needs. The Iterable<E> argument is immutable, and all elements returned by its iterator are non-null. The extensionTransform must return a non-null instance of D.

extensionReduce - a reduction to be applied to arbitrary results from the extensionTransform. This may be called multiple times, possibly concurrently, for varying subsets and orders of the transform results, as and when the returned supplier needs. The Iterable<D> argument is immutable, and all elements returned by its iterator are non-null. The extensionReduce must return a non-null instance of D.

Returns:

A supplier whose get returns a value equivalent to calling getExtensionsByClass(Class) for the given class in the implicit context at the time of the get call, selecting a partition of the results, applying extensionTransform to each block of the partition, and applying extensionReduce to the results of extensionTransform in some order. The get of the returned Supplier may be called concurrently from multiple threads, and does not return null.