com.cloudera.gertrude

Class Experiments

java.lang.Object

com.cloudera.gertrude.Experiments

public final class Experiments
extends Object

A namespace for declaring, configuring, and accessing the core classes in the Gertrude framework.

Most clients will get started with Gertrude by declaring ExperimentFlag instances in their code that reference parameters that can be calculated by the framework:

   ExperimentFlag<Boolean> featureOn = Experiments.declare("feature", false);
 ExperimentFlag<Long> upperLimit = Experiments.declare("limit", 1729L);
 ExperimentFlag<Double> threshold = Experiments.declare("threshold_for_model", 0.05);
 ExperimentFlag<String> background = Experiments.declare("background_color", "white");  

At server startup time, Gertrude needs some additional classes configured so that the framework can load and process new experiments from external sources:

1. A ConditionFactory for mapping from names of Condition functions to implementations,
2. a ExperimentSpaceDeserializer for processing the serialized form of an ExperimentSpace,
3. a ExperimentSpaceLoader that is configured with the location of the serialized ExperimentSpace,
4. and an optional MetricRegistry for tracking experiment requests and diversions.

After these instances are configured, the ExperimentHandler for the server can be accessed via the getHandler() method and used to divert client requests (represented by a subclass of AbstractExperimentState) into experiments that modify parameter values as specified in the configuration of the ExperimentSpace.

Method Summary

Methods

Modifier and Type	Method and Description
static ExperimentFlag<Boolean>	declare(String name, boolean defaultValue) Declares a boolean experiment flag with the given name and default value.
static ExperimentFlag<Double>	declare(String name, double defaultValue) Declares a double experiment flag with the given name and default value.
static ExperimentFlag<Long>	declare(String name, long defaultValue) Declares a long experiment flag with the given name and default value.
static ExperimentFlag<String>	declare(String name, String defaultValue) Declares a string experiment flag with the given name and default value.
static ExperimentHandler	getHandler()
static boolean	registerConditionFactory(ConditionFactory factory) Register the given ConditionFactory for creating new Condition instances from the serialized ExperimentSpace configuration.
static boolean	registerDeserializer(ExperimentSpaceDeserializer deserializer) Register the given ExperimentSpaceDeserializer for creating and validating new ExperimentSpace instances.
static boolean	registerLoader(ExperimentSpaceLoader loader) Register the given ExperimentSpaceLoader for retrieving serialized ExperimentSpace instances.
static boolean	registerMetricRegistry(com.codahale.metrics.MetricRegistry registry) Register the given MetricRegistry for stat tracking with the framework.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

declare

public static ExperimentFlag<Boolean> declare(String name,
                              boolean defaultValue)

Declares a boolean experiment flag with the given name and default value.

Parameters:

name - the name of the flag

defaultValue - the default value of the flag

Returns:

the instance of ExperimentFlag for the name and default value

declare

public static ExperimentFlag<Long> declare(String name,
                           long defaultValue)

Declares a long experiment flag with the given name and default value.

Parameters:

name - the name of the flag

defaultValue - the default value of the flag

Returns:

the instance of ExperimentFlag for the name and default value

declare

public static ExperimentFlag<Double> declare(String name,
                             double defaultValue)

Declares a double experiment flag with the given name and default value.

Parameters:

name - the name of the flag

defaultValue - the default value of the flag

Returns:

the instance of ExperimentFlag for the name and default value

declare

public static ExperimentFlag<String> declare(String name,
                             String defaultValue)

Declares a string experiment flag with the given name and default value.

Parameters:

name - the name of the flag

defaultValue - the default value of the flag

Returns:

the instance of ExperimentFlag for the name and default value

registerConditionFactory

public static boolean registerConditionFactory(ConditionFactory factory)

Register the given ConditionFactory for creating new Condition instances from the serialized ExperimentSpace configuration.

If no factory is provided before the call to getHandler(), an IllegalStateException will be thrown.

Parameters:

factory - the configured factory

Returns:

true if the given factory was configured, false if another one had already been configured

registerLoader

public static boolean registerLoader(ExperimentSpaceLoader loader)

Register the given ExperimentSpaceLoader for retrieving serialized ExperimentSpace instances.

If no loader is provided before the call to getHandler(), an IllegalStateException will be thrown.

Parameters:

loader - the configured loader

Returns:

true if the given loader was configured, false if another one had already been configured

registerDeserializer

public static boolean registerDeserializer(ExperimentSpaceDeserializer deserializer)

Register the given ExperimentSpaceDeserializer for creating and validating new ExperimentSpace instances.

If no deserializer is provided before the call to getHandler(), an IllegalStateException will be thrown.

Parameters:

deserializer - the configured deserializer

Returns:

true if the given deserializer was configured, false if another one had already been configured

registerMetricRegistry

public static boolean registerMetricRegistry(com.codahale.metrics.MetricRegistry registry)

Register the given MetricRegistry for stat tracking with the framework.

If no registry is provided before the call to getHandler(), the framework will create its own instance and use that one.

Parameters:

registry - the registry instance to use

Returns:

true if the given registry was configured, false if another one had already been configured

getHandler

public static ExperimentHandler getHandler()