com.cloudera.gertrude

Interface ExperimentState

All Known Subinterfaces:

HttpServletExperimentState

All Known Implementing Classes:

AbstractExperimentState

public interface ExperimentState

Container for all of the information about how to divert a request into experiments and what the values of experiment flags are for the current request.

Most of the logic for managing experiment ids and flag value calculations is defined in the AbstractExperimentState class, which clients should extend in order to provide a definition of the getDiversionIdentifier(int) method that is appropriate for their application.

ExperimentState is an interface so that clients may create re-usable families of Condition functions that expect a specific sub-interface of ExperimentState and are aware of how to process them. For example, there could be a HttpServletRequestExperimentState sub-interface that provided a getServletRequest() method, and an associated set of Condition functions that could process the HttpServletRequest and make decisions based on its values. Then any client could access and use those Condition functions simply by extending the AbstractExperimentState and implementing the HttpServletRequestExperimentState interface, without having to re-write their own Condition implementations for every application.

Method Summary

Methods

Modifier and Type	Method and Description
Set<Integer>	forceExperimentIds() Indicate a set of experiment IDs that this ExperimentState should be forced into by the ExperimentHandler.handle(AbstractExperimentState) method.
<T> T	get(ExperimentFlag<T> flag) Returns the value of the given ExperimentFlag for this ExperimentState.
com.google.common.base.Optional<String>	getDiversionIdentifier(int diversionId) Return the identifier to use for this instance with the diversion criterion that has the given identifer.
Set<Integer>	getExperimentIds() Returns the integer identifiers for the experiments that this state was diverted into.
float	getFloat(ExperimentFlag<Double> doubleFlag) A convenience method for acccessing the value of a ExperimentFlag<Double> as a float.
int	getInt(ExperimentFlag<Long> longFlag) A convenience method for acccessing the value of a ExperimentFlag<Long> as an int.
long	getRequestTimeMsec() Returns the time that this ExperimentState instance was created in milliseconds.
boolean	isDiverted() Indicates whether or not this ExperimentState has been passed to ExperimentHandler.handle(com.cloudera.gertrude.AbstractExperimentState).

Method Detail

getDiversionIdentifier

com.google.common.base.Optional<String> getDiversionIdentifier(int diversionId)

Return the identifier to use for this instance with the diversion criterion that has the given identifer.

Clients must override this method in order to specify the identifiers that they support for a given request, and what the values of those identifiers are for each request.

Remember that these identifiers are used for randomly diverting requests into experiments, so they should be unique for each entity that we are experimenting on. For example, using the country that a request comes from is a relatively poor choice of a diversion identifier compared to a random account ID or browser cookie.

Parameters:

diversionId - The unique id of the requested diversion criterion

Returns:

an identifier to use for diverting this request into an experiment or domain

forceExperimentIds

Set<Integer> forceExperimentIds()

Indicate a set of experiment IDs that this ExperimentState should be forced into by the ExperimentHandler.handle(AbstractExperimentState) method.

By default, this method returns an empty set. Subclasses may override this method to provide clients with a way to force a request to be in a certain experiment in order to test or debug a scenario.

Returns:

the ids of the experiments that this request should be in

get

<T> T get(ExperimentFlag<T> flag)

Returns the value of the given ExperimentFlag for this ExperimentState.

If the FlagValue that was calculated for this flag can be cached on a per-request basis, then this instance will keep the calculated value in a cache so that it is not re-computed unnecessarily during the same request.

If this state has not yet been diverted by the ExperimentHandler, then the default value of the flag is returned, but not stored in the cache.

Parameters:

flag - the flag whose value is returned

Returns:

the value of the flag for this instance

getInt

int getInt(ExperimentFlag<Long> longFlag)

A convenience method for acccessing the value of a ExperimentFlag<Long> as an int.

Parameters:

longFlag - the flag

Returns:

the integer point value of the flag

getFloat

float getFloat(ExperimentFlag<Double> doubleFlag)

A convenience method for acccessing the value of a ExperimentFlag<Double> as a float.

Parameters:

doubleFlag - the flag

Returns:

the floating point value of the flag

getExperimentIds

Set<Integer> getExperimentIds()

Returns the integer identifiers for the experiments that this state was diverted into.

Returns:

the integer identifiers for the experiments that this state was diverted into

isDiverted

boolean isDiverted()

Indicates whether or not this ExperimentState has been passed to ExperimentHandler.handle(com.cloudera.gertrude.AbstractExperimentState).

Returns:

true if this instance has already been diverted, false otherwise

getRequestTimeMsec

long getRequestTimeMsec()

Returns the time that this ExperimentState instance was created in milliseconds. Used for determining whether a particular experiment should be active or inactive for this request.

Returns:

the time that this object was created in milliseconds