public abstract class Schema<I extends Iced,S extends Schema<I,S>> extends Iced
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 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.
Schemas have a State section (broken into Input, Output and InOut fields) and an Adapter section which fills the State to and from the Iced impl objects and from HTTP request parameters.
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.
Schema Fields must have a single API annotation describing in their direction of operation (all fields will be output by default), and any other properties such as "required". Transient and static fields are ignored.
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| Modifier and Type | Field and Description |
|---|---|
protected static java.util.regex.Pattern |
_version_pattern |
java.lang.String |
schema_name
The simple schema (class) name, e.g.
|
java.lang.String |
schema_type |
int |
schema_version |
| Constructor and Description |
|---|
Schema() |
| 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.
|
java.lang.Class<I> |
getImplClass() |
static java.lang.Class<? extends Iced> |
getImplClass(java.lang.Class<? extends Schema> clz) |
java.lang.StringBuffer |
markdown(SchemaMetadata meta,
java.lang.StringBuffer appendToMe)
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.
|
static void |
register(java.lang.Class<? extends Schema> clz)
Register the given schema class.
|
clone, frozenType, read_impl, read, readExternal, readJSON_impl, readJSON, write_impl, write, writeExternal, writeHTML_impl, writeHTML, writeJSON_impl, writeJSON@API(help="Version number of this Schema. Must not be changed after creation (treat as final).") public int schema_version
@API(help="Simple name of this Schema. NOTE: the schema_names form a single namespace.") public java.lang.String schema_name
@API(help="Simple name of H2O type that this Schema represents. Must not be changed after creation (treat as final).") public final java.lang.String schema_type
protected static java.util.regex.Pattern _version_pattern
public static int extractVersion(java.lang.String clz_name)
public static void register(java.lang.Class<? extends Schema> clz)
public I createImpl()
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.
public I fillImpl(I impl)
public final I createAndFillImpl()
public S fillFromImpl(I impl)
public static java.lang.Class<? extends Iced> getImplClass(java.lang.Class<? extends Schema> clz)
public java.lang.Class<I> getImplClass()
@Deprecated protected java.lang.String acceptsFrame(Frame fr)
public S fillFromParms(java.util.Properties parms)
public java.lang.StringBuffer markdown(java.lang.StringBuffer appendToMe)
public java.lang.StringBuffer markdown(SchemaMetadata meta, java.lang.StringBuffer appendToMe)