com.atlassian.webresource.api.prebake

Interface Dimensions

@ExperimentalApi
public interface Dimensions

Represents all the possible "dimensions" or set of possible combinations of query parameters that a transformer or condition can support. For example, an i18n transformer may support a "locale" query param that can have values "en", "fr", etc. A condition may support a query param "isadmin" that may be "true" or absent. Both those Dimensions can be combined via product(Dimensions) to produce all possible valid combinations of "locale" and "isadmin".

For example:

 Dimensions locale = Dimensions.empty().andExactly("locale", "en", "fr);
 Dimensions isadmin = Dimensions.empty().andExactly("isadmin", "true").andAbsent("isadmin");
 Dimensions dims = locale.product(isadmin);
 

This Dimensions concept does not support a query param having multiple values simultaneously. For example, you could not construct a Dimensions that represented ?locale=en&locale=fr

Instances of this class are immutable, and all methods return results and do not modify the current instance.

Implementors of this interface will define equals/hashCode.

Method Summary

Modifier and Type	Method and Description
Dimensions	andAbsent(String key) Adds a dimension that represents the absence of key in the query string.
Dimensions	andExactly(String key, Collection<String> values) Adds dimensions for query param key over all the given values.
Dimensions	andExactly(String key, String... values) Adds dimensions for query param key over all the given values.
Dimensions	blacklistValues(Dimensions blacklist) Filters the dimension values using the blacklist passed as parameter.
Stream<Coordinate>	cartesianProduct() Computes the cartesian product as an unordered stream of Coordinates.
long	cartesianProductSize() Computes the size of the cartesian product.
static Dimensions	empty() Factory for an empty dimension object.
static Dimensions	fromMap(Map<String,List<String>> dimensionMap) Initialises a new Dimensions instance from a Map.
Dimensions	product(Dimensions rhs) Combines two dimensions, representing all possible combinations of both dimensions.
Dimensions	whitelistValues(Dimensions whitelist) Filters the dimension values using the whitelist passed as parameter.

Method Detail

empty

static Dimensions empty()

Factory for an empty dimension object.

fromMap

@Nonnull
static Dimensions fromMap(@Nonnull
                                   Map<String,List<String>> dimensionMap)

Initialises a new Dimensions instance from a Map. Keys correspond to the names of the dimension, and values to the list of values that the dimension can assume. A null value will be interpreted as an absent dimension value (see andAbsent(String)).

Parameters:

dimensionMap - A Map containing the dimension values

Returns:

Dimensions object populated with the data in the map passed as parameter

andExactly

Dimensions andExactly(String key,
                      String... values)

Adds dimensions for query param key over all the given values. Does not include the absence of key.

andExactly

Dimensions andExactly(String key,
                      Collection<String> values)

Adds dimensions for query param key over all the given values. Does not include the absence of key.

andAbsent

Dimensions andAbsent(String key)

Adds a dimension that represents the absence of key in the query string.

product

Dimensions product(Dimensions rhs)

Combines two dimensions, representing all possible combinations of both dimensions.

whitelistValues

@Nonnull
Dimensions whitelistValues(@Nonnull
                                    Dimensions whitelist)

Filters the dimension values using the whitelist passed as parameter.

This method produces a new Dimensions object that includes, for the dimension keys contained in the whitelist, only the values explicitly included in the whitelist. All dimensions that don't have a corresponding entry in the whitelist object will be kept as-is.

blacklistValues

@Nonnull
Dimensions blacklistValues(@Nonnull
                                    Dimensions blacklist)

Filters the dimension values using the blacklist passed as parameter.

This method produces a new Dimensions object that includes, for the dimension keys contained in the blacklist, only the values that are not contained in the blacklist. All dimensions that don't have a corresponding entry in the blacklist object will be kept as-is.

cartesianProduct

Stream<Coordinate> cartesianProduct()

Computes the cartesian product as an unordered stream of Coordinates. A Coordinate represents a single possible query-string combination.

cartesianProductSize

long cartesianProductSize()

Computes the size of the cartesian product.

Use this method instead of iterating over the list of coordinates, or collecting the coordinates in a list, as both these solutions might take a considerable amount of time and memory (their time and memory footprint is more than 2^n, where n is the number of dimensions).