water.api

Class Schema<I extends Iced,S extends Schema<I,S>>

java.lang.Object

water.Iced

water.api.Schema<I,S>

All Implemented Interfaces:

java.io.Externalizable, java.io.Serializable, java.lang.Cloneable, Freezable

Direct Known Subclasses:

AboutHandler.AboutEntryV3, CloudV3.NodeV3, ConfusionMatrixBase, FrameBase, FrameV3.ColSpecifierV3, FrameV3.ColV3, GarbageCollectV3, H2OErrorV3, JobV3, JStackV3.DStackTraceV3, KeyV3, ModelMetricsBase, ModelOutputSchema, ModelParameterSchemaV3, ModelParametersSchema, ModelSchemaBase, NodePersistentStorageV3.NodePersistentStorageEntryV3, ProfilerNodeV3, ProfilerNodeV3.ProfilerNodeEntryV3, RequestSchema, RouteBase, SchemaMetadataBase, SchemaMetadataBase.FieldMetadataBase, TimelineV3.EventV3, TwoDimTableBase, TwoDimTableBase.ColumnSpecsBase, ValidationMessageBase, VarImpBase, WaterMeterIo.IoStatsEntry

public class Schema<I extends Iced,S extends Schema<I,S>>
extends Iced

Base Schema class. All REST API Schemas inherit from here.

The purpose of Schemas is to provide a stable, versioned interface to the functionality in H2O, which allows the back end implementation to change rapidly without breaking REST API clients such as the Web UI and R binding. Schemas also allow for functionality which exposes the schema metadata to clients, allowing them to do service discovery and to adapt dynamically to new H2O functionality (e.g., to be able to call any ModelBuilder, even new ones written since the client was built, without knowing any details about the specific algo).

Most schemas have a 1-to-1 mapping to an Iced implementation object. Both the Schema and the Iced object may have children, or (more often) not. Occasionally, e.g. in the case of schemas used only to handle HTTP request parameters, there will not be a backing impl object and the Schema will be parameterized by Iced.

Schemas have a State section (broken into Input, Output and InOut fields) and an Adapter section. The adapter methods fill the State to and from the Iced impl objects and from HTTP request parameters. In the simple case, where the backing object corresponds 1:1 with the Schema and no adapting need be done, the methods here in the Schema class will do all the work based on reflection.

Methods here allow us to convert from Schema to Iced (impl) and back in a flexible way. The default behaviour is to map like-named fields back and forth, often with some default type conversions (e.g., a Keyed object like a Model will be automagically converted back and forth to a Key). Subclasses can override methods such as fillImpl or fillFromImpl to provide special handling when adapting from schema to impl object and back. Usually they will want to call super to get the default behavior, and then modify the results a bit (e.g., to map differently-named fields, or to compute field values).

Schema Fields must have a single API annotation describing their direction of operation and any other properties such as "required". Fields are API.Direction.OUTPUT by default. Transient and static fields are ignored.

See Also:

for information on the field annotations

Some use cases:

To create a schema object and fill it from an existing impl object (the common case):
{@code S schema = schema(version); schema.fillFromImpl(impl); }

To create an impl object and fill it from an existing schema object (the common case):
{@code I impl = schema.createImpl(); // create an empty impl object and any empty children schema.fillImpl(impl); // fill the empty impl object and any children from the Schema and its children }

or {@code I impl = schema.createAndFillImpl(); // helper which does schema.fillImpl(schema.createImpl()) }

To create a schema object filled from the default values of its impl class and then overridden by HTTP request params: {@code S schema = schema(version); I defaults = schema.createImpl(); schema.fillFromImpl(defaults); schema.fillFromParms(parms); }, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Schema.Meta

Field Summary

Fields

Modifier and Type	Field and Description
Schema.Meta	__meta
protected java.lang.Class<I>	_impl_class
protected static java.util.regex.Pattern	_version_pattern
static java.lang.String	EXCLUDE_FIELDS
static java.lang.String	INCLUDE_FIELDS

Constructor Summary

Constructors

Constructor and Description
Schema()

Method Summary

Methods

Modifier and Type	Method and Description
protected java.lang.String	acceptsFrame(Frame fr) Deprecated.
I	createAndFillImpl() Convenience helper which creates and fill an impl.
I	createImpl() Create an implementation object and any child objects but DO NOT fill them.
static int	extractVersion(java.lang.String clz_name) Extract the version number from the schema class name.
S	fillFromImpl(I impl) Version and Schema-specific filling from the implementation object.
S	fillFromParms(java.util.Properties parms)
I	fillImpl(I impl) Fill an impl object and any children from this schema and its children.
static int	getExperimentalVersion()
static int	getHighestSupportedVersion()
java.lang.Class<I>	getImplClass()
static java.lang.Class<? extends Iced>	getImplClass(java.lang.Class<? extends Schema> clz)
static int	getLatestVersion()
int	getSchemaVersion()
java.lang.StringBuffer	markdown(SchemaMetadata meta, java.lang.StringBuffer appendToMe)
java.lang.StringBuffer	markdown(SchemaMetadata meta, java.lang.StringBuffer appendToMe, boolean include_input_fields, boolean include_output_fields) Generate Markdown documentation for this Schema, given we already have the metadata constructed.
java.lang.StringBuffer	markdown(java.lang.StringBuffer appendToMe) Generate Markdown documentation for this Schema.
java.lang.StringBuffer	markdown(java.lang.StringBuffer appendToMe, boolean include_input_fields, boolean include_output_fields) Generate Markdown documentation for this Schema possibly including only the input or output fields.
static Schema	newInstance(java.lang.Class<? extends Schema> clz)
static void	register(java.lang.Class<? extends Schema> clz) Register the given schema class.
static void	registerAllSchemasIfNecessary() Find all schemas using reflection and register them.
static Schema	schema(java.lang.Class<? extends Schema> clz) For a given schema class (e.g., water.api.FrameV2) return a new instance (e.g., a water.api.Framev2).
static Schema	schema(int version, java.lang.Class<? extends Iced> impl_class) For a given version and Iced class return an appropriate Schema instance, if any.
static Schema	schema(int version, Iced impl) For a given version and Iced object return an appropriate Schema instance, if any.
static Schema	schema(int version, java.lang.String type) For a given version and type (Iced class simpleName) return an appropriate new Schema object, if any.
static Schema	schema(java.lang.String schema_name) For a given schema_name (e.g., "FrameV2") return an appropriate new schema object (e.g., a water.api.Framev2).
static java.lang.Class<? extends Schema>	schemaClass(int version, java.lang.Class<? extends Iced> impl_class) For a given version and Iced class return the appropriate Schema class, if any.f
static java.lang.Class<? extends Schema>	schemaClass(int version, Iced impl) For a given version and Iced object return the appropriate Schema class, if any.
static java.lang.Class<? extends Schema>	schemaClass(int version, java.lang.String type) For a given version and type (Iced class simpleName) return the appropriate Schema class, if any.
static java.lang.Class<? extends Schema>	schemaClass(java.lang.String schema_name) For a given schema_name (e.g., "FrameV2") return the schema class (e.g., water.api.Framev2).
static java.util.Map<java.lang.String,java.lang.Class<? extends Schema>>	schemas() Return an immutable Map of all the schemas: schema_name -> schema Class.

Methods inherited from class water.Iced

clone, frozenType, read_impl, read, readExternal, readJSON_impl, readJSON, toJsonString, write_impl, write, writeExternal, writeHTML_impl, writeHTML, writeJSON_impl, writeJSON

Methods inherited from class java.lang.Object

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

Field Detail

_impl_class

protected transient java.lang.Class<I extends Iced> _impl_class

EXCLUDE_FIELDS

public static final java.lang.String EXCLUDE_FIELDS

See Also:

Constant Field Values

INCLUDE_FIELDS

public static final java.lang.String INCLUDE_FIELDS

See Also:

Constant Field Values

__meta

@API(help="Metadata on this schema instance, to make it self-describing.",
     direction=OUTPUT)
public Schema.Meta __meta

_version_pattern

protected static java.util.regex.Pattern _version_pattern

Constructor Detail

Schema

public Schema()

Method Detail

extractVersion

public static int extractVersion(java.lang.String clz_name)

Extract the version number from the schema class name. Returns -1 if there's no version number at the end of the classname.

getSchemaVersion

public int getSchemaVersion()

getLatestVersion

public static final int getLatestVersion()

getHighestSupportedVersion

public static final int getHighestSupportedVersion()

getExperimentalVersion

public static final int getExperimentalVersion()

register

public static void register(java.lang.Class<? extends Schema> clz)

Register the given schema class.

createImpl

public I createImpl()

Create an implementation object and any child objects but DO NOT fill them. The purpose of a createImpl without a fillImpl is to be able to get the default values for all the impl's fields.

For objects without children this method does all the required work. For objects with children the subclass will need to override, e.g. by calling super.createImpl() and then calling createImpl() on its children.

Note that impl objects for schemas which override this method don't need to have a default constructor (e.g., a Keyed object constructor can still create and set the Key), but they must not fill any fields which can be filled later from the schema.

TODO: We *could* handle the common case of children with the same field names here by finding all of our fields that are themselves Schemas.

fillImpl

public I fillImpl(I impl)

Fill an impl object and any children from this schema and its children.

createAndFillImpl

public final I createAndFillImpl()

Convenience helper which creates and fill an impl.

fillFromImpl

public S fillFromImpl(I impl)

Version and Schema-specific filling from the implementation object.

getImplClass

public static java.lang.Class<? extends Iced> getImplClass(java.lang.Class<? extends Schema> clz)

getImplClass

public java.lang.Class<I> getImplClass()

acceptsFrame

@Deprecated
protected java.lang.String acceptsFrame(Frame fr)

Deprecated.

fillFromParms

public S fillFromParms(java.util.Properties parms)

registerAllSchemasIfNecessary

public static void registerAllSchemasIfNecessary()

Find all schemas using reflection and register them.

schemas

public static java.util.Map<java.lang.String,java.lang.Class<? extends Schema>> schemas()

Return an immutable Map of all the schemas: schema_name -> schema Class.

schemaClass

public static java.lang.Class<? extends Schema> schemaClass(int version,
                                            Iced impl)

For a given version and Iced object return the appropriate Schema class, if any.

See Also:

schemaClass(int, java.lang.String)

schemaClass

public static java.lang.Class<? extends Schema> schemaClass(int version,
                                            java.lang.Class<? extends Iced> impl_class)

For a given version and Iced class return the appropriate Schema class, if any.f

See Also:

schemaClass(int, java.lang.String)

schemaClass

public static java.lang.Class<? extends Schema> schemaClass(int version,
                                            java.lang.String type)

For a given version and type (Iced class simpleName) return the appropriate Schema class, if any.

If a higher version is asked for than is available (e.g., if the highest version of Frame is FrameV2 and the client asks for the schema for (Frame, 17) then FrameV2 will be returned. This compatibility lookup is cached.

schemaClass

public static java.lang.Class<? extends Schema> schemaClass(java.lang.String schema_name)

For a given schema_name (e.g., "FrameV2") return the schema class (e.g., water.api.Framev2).

schema

public static Schema schema(int version,
            Iced impl)

For a given version and Iced object return an appropriate Schema instance, if any.

See Also:

schema(int, java.lang.String)

schema

public static Schema schema(int version,
            java.lang.Class<? extends Iced> impl_class)

For a given version and Iced class return an appropriate Schema instance, if any.

See Also:

schema(int, java.lang.String)

newInstance

public static Schema newInstance(java.lang.Class<? extends Schema> clz)

schema

public static Schema schema(int version,
            java.lang.String type)

For a given version and type (Iced class simpleName) return an appropriate new Schema object, if any.

If a higher version is asked for than is available (e.g., if the highest version of Frame is FrameV2 and the client asks for the schema for (Frame, 17) then an instance of FrameV2 will be returned. This compatibility lookup is cached.

schema

public static Schema schema(java.lang.String schema_name)

For a given schema_name (e.g., "FrameV2") return an appropriate new schema object (e.g., a water.api.Framev2).

schema

public static Schema schema(java.lang.Class<? extends Schema> clz)

For a given schema class (e.g., water.api.FrameV2) return a new instance (e.g., a water.api.Framev2).

markdown

public java.lang.StringBuffer markdown(java.lang.StringBuffer appendToMe)

Generate Markdown documentation for this Schema.

markdown

public java.lang.StringBuffer markdown(java.lang.StringBuffer appendToMe,
                              boolean include_input_fields,
                              boolean include_output_fields)

Generate Markdown documentation for this Schema possibly including only the input or output fields.

markdown

public java.lang.StringBuffer markdown(SchemaMetadata meta,
                              java.lang.StringBuffer appendToMe)

markdown

public java.lang.StringBuffer markdown(SchemaMetadata meta,
                              java.lang.StringBuffer appendToMe,
                              boolean include_input_fields,
                              boolean include_output_fields)

Generate Markdown documentation for this Schema, given we already have the metadata constructed.