Schema (h2o-core 3.42.0 API)

java.lang.Object
- water.Iced
- - water.api.Schema<I,S>

Type Parameters:

I - "implementation" (Iced) class for this schema
S - reference to self: this should always be the same class as being declared. For example:
```
public class TimelineV3 extends Schema<Timeline, TimelineV3>
```
All Implemented Interfaces:

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

Direct Known Subclasses:

InputSchemaV4, OutputSchemaV4, SchemaV3
```
public abstract class Schema<I extends Iced,S extends Schema<I,S>>
extends Iced
```
Base Schema class; all REST API Schemas inherit from here.
Schema is a primary interface of the REST APIs: all endpoints consume some schema object as an input, and produce another schema object as an output (though some endpoints may return nothing).
Schemas, as an external interface, are required to be stable: fields may not be renamed or removed, their types or meaning may not change, etc. It is allowed to add new fields to a schema, provided that they are optional, and that their default values correspond to the old behavior of the endpoint. If these requirements cannot be met, then a new version of a schema class must be created.
Many schemas are in direct correspondence with H2O objects. For example, JobV3 schema represents the Job object. These "representative" Iced objects are called "implementation" or "impl", and are parametrized with type I. Such representation is necessary in order to ensure stability of the interface: even as Job class evolves, the interface of JobV3 schema must not. In the simplest case, when there is 1-to-1 correspondence between fields in the impl class and in the schema, we use reflection magic to copy those fields over. The reflection magic is smart enough to perform simple field name translations, and even certain type translations (like Keyed objects into Keys). If there is no such correspondence, then special type adapters must be written. Right now this is done by overriding the fillImpl and fillFromImpl methods. 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). Transient and static fields are ignored by the reflection magic.
There are also schemas that do not correspond to any H2O object. These are mostly the input schemas (schemas used for inputs of api requests). Such schemas should be "implemented" by Iced.
All schemas are expected to be self-documenting, in the sense that all fields within those schemas should carry detailed documentation about their meaning, as well as any additional hints about the field's usage. These should be annotated using the @API interface. If a schema contains a complicated object, then that object itself should derive from Schema, so that its fields can also be properly documented. However if the internal object is sufficiently simple (say, a Map), then it may be sufficient to document it as a whole and have it derived from Iced, not from Schema.
Schema names (getSimpleName()) must be unique within an application. During Schema discovery and registration there are checks to ensure this. Each schema is associated with exactly one implementation object, however some Iced objects are mapped into multiple schemas.
For V3 Schemas each field had a "direction" (input / output / both), which allowed us to use the same schema as both input and output for an endpoint. This is no longer possible in V4: two separate schema classes for input / output should be created.
Usage

Handler creates an input schema from the body/parameters of the HTTP request (using fillFromParms(), and passes it on to the corresponding handler method.
Each handler method may modify the input schema and return it as the output schema (common for V3 endpoints, should be avoided in V4).
Alternatively, a handler method may create a new output schema object from scratch, or from an existing implementation object.
Internal details

Most Java developers need not be concerned with the details that follow, because the framework will make these calls as necessary.
To create a schema object and fill it from an existing impl object:
```
    S schema = new SomeSchemaClass().fillFromImpl(impl);
```
To create an impl object and fill it from an existing schema object:
```
    I impl = schema.createAndFillImpl();
```
Schemas that are used for HTTP requests are filled with the default values of their impl class, and then any present HTTP parameters override those default values. To create a schema object filled from the default values of its impl class and then overridden by HTTP request params:
```
    S schema = new SomeSchemaClass().fillFromImpl().fillFromParms(parms);
```
See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`Schema.AutoParseable` This "Marker Interface" denotes classes that can directly be parsed by GSON parser (skip H2O's own parser)

Constructor Summary

Constructors
Constructor and Description

Schema()
Default constructor; triggers lazy schema registration.

Schema(I impl)
Create a new Schema instance from an existing impl object.

Constructors
Constructor and Description
`Schema()` Default constructor; triggers lazy schema registration.
`Schema(I impl)` Create a new Schema instance from an existing impl object.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`I`	`createAndFillImpl()` Convenience helper which creates and fills an impl object from this schema.
`I`	`createImpl()` Create an appropriate implementation object and any child objects but does not fill them.
`static int`	`extractVersionFromSchemaName(java.lang.String clz_name)` Extract the version number from the schema class name.
`S`	`fillFromAny(java.lang.Object o)`
`S`	`fillFromBody(java.lang.String body)` Fills this Schema from the body content when available.
`S`	`fillFromImpl()` Fill this schema from the default impl, and then return self.
`S`	`fillFromImpl(I impl)` Fill this Schema from the given implementation object.
`protected S`	`fillFromImpl(I impl, java.lang.String[] fieldsToSkip)`
`S`	`fillFromParms(java.util.Properties parms)` Fill this Schema object from a set of parameters.
`S`	`fillFromParms(java.util.Properties parms, boolean checkRequiredFields)` Fill this Schema object from a set of parameters.
`S`	`fillFromParms(java.util.Properties parms, java.util.Properties unknownParms, boolean checkRequiredFields)` Fill this Schema from a set of (generally HTTP) parameters.
`I`	`fillImpl(I impl)` Fill an impl object and any children from this schema and its children.
`protected I`	`fillImpl(I impl, java.lang.String[] fieldsToSkip)`
`java.lang.Class<I>`	`getImplClass()` Return the class of the implementation type parameter I for this Schema.
`static java.lang.Class<? extends Iced>`	`getImplClass(java.lang.Class<? extends Schema> clz)` Return the class of the implementation type parameter I for the given Schema class.
`java.lang.String`	`getSchemaName()`
`java.lang.String`	`getSchemaType()`
`int`	`getSchemaVersion()` Get the version number of this schema, for example 3 or 99.
`void`	`init_meta()`
`java.lang.StringBuffer`	`markdown(boolean include_input_fields, boolean include_output_fields)` Generate Markdown documentation for this Schema possibly including only the input or output fields.
`java.lang.StringBuffer`	`markdown(SchemaMetadata meta, boolean include_input_fields, boolean include_output_fields)` Generate Markdown documentation for this Schema, given we already have the metadata constructed.
`static <T extends Schema> T`	`newInstance(java.lang.Class<T> clz)` Returns a new Schema instance.
`protected static Schema`	`newInstance(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 <T extends Schema> void`	`setField(T o, java.lang.reflect.Field f, java.lang.String key, java.lang.String value, boolean required, java.lang.Class thisSchemaClass)` Safe method to set the field on given schema object
`void`	`setSchemaType_doNotCall(java.lang.String s)`

Methods inherited from class water.Iced
asBytes, clone, copyOver, frozenType, read, readExternal, readJSON, reloadFromBytes, toJsonBytes, toJsonString, write, writeExternal, writeJSON

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Schema
```
public Schema()
```
    Default constructor; triggers lazy schema registration.
    
    Throws:
    
    H2OFailException - if there is a name collision or there is more than one schema which maps to the same Iced class
  - Schema
```
public Schema(I impl)
```
    Create a new Schema instance from an existing impl object.
- Method Detail
  - init_meta
```
public void init_meta()
```
  - extractVersionFromSchemaName
```
public static int extractVersionFromSchemaName(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()
```
    Get the version number of this schema, for example 3 or 99. Note that 99 is the "experimental" version, meaning that there are no stability guarantees between H2O versions.
  - getSchemaName
```
public java.lang.String getSchemaName()
```
  - getSchemaType
```
public java.lang.String getSchemaType()
```
  - setSchemaType_doNotCall
```
public void setSchemaType_doNotCall(java.lang.String s)
```
  - createImpl
```
public I createImpl()
```
    Create an appropriate implementation object and any child objects but does not fill them. The standard 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
```
protected I fillImpl(I impl,
                     java.lang.String[] fieldsToSkip)
```
  - fillImpl
```
public I fillImpl(I impl)
```
    Fill an impl object and any children from this schema and its children. If a schema doesn't need to adapt any fields if does not need to override this method.
  - createAndFillImpl
```
public final I createAndFillImpl()
```
    Convenience helper which creates and fills an impl object from this schema.
  - fillFromImpl
```
public final S fillFromImpl()
```
    Fill this schema from the default impl, and then return self.
  - fillFromImpl
```
public S fillFromImpl(I impl)
```
    Fill this Schema from the given implementation object. If a schema doesn't need to adapt any fields if does not need to override this method.
  - fillFromImpl
```
protected S fillFromImpl(I impl,
                         java.lang.String[] fieldsToSkip)
```
  - getImplClass
```
public static java.lang.Class<? extends Iced> getImplClass(java.lang.Class<? extends Schema> clz)
```
    Return the class of the implementation type parameter I for the given Schema class. Used by the metadata facilities and the reflection-base field-copying magic in PojoUtils.
  - getImplClass
```
public java.lang.Class<I> getImplClass()
```
    Return the class of the implementation type parameter I for this Schema. Used by generic code which deals with arbitrary schemas and their backing impl classes. Never returns null.
  - fillFromParms
```
public S fillFromParms(java.util.Properties parms)
```
    Fill this Schema object from a set of parameters.
    
    Parameters:
    
    parms - parameters - set of tuples (parameter name, parameter value)
    
    Returns:
    
    this schema
    
    See Also:
    
    fillFromParms(Properties, Properties, boolean)
  - fillFromParms
```
public S fillFromParms(java.util.Properties parms,
                       boolean checkRequiredFields)
```
    Fill this Schema object from a set of parameters.
    
    Parameters:
    
    parms - parameters - set of tuples (parameter name, parameter value)
    
    checkRequiredFields - perform check for missing required fields
    
    Returns:
    
    this schema
    
    See Also:
    
    fillFromParms(Properties, Properties, boolean)
  - fillFromParms
```
public S fillFromParms(java.util.Properties parms,
                       java.util.Properties unknownParms,
                       boolean checkRequiredFields)
```
    Fill this Schema from a set of (generally HTTP) parameters.
    Using reflection this process determines the type of the target field and conforms the types if possible. For example, if the field is a Keyed type the name (ID) will be looked up in the DKV and mapped appropriately.
    The process ignores parameters which are not fields in the schema, and it verifies that all fields marked as required are present in the parameters list.
    It also does various sanity checks for broken Schemas, for example fields must not be private, and since input fields get filled here they must not be final.
    
    Parameters:
    
    parms - Properties map of parameter values
    
    unknownParms - if not null, bad parameters won't cause an exception, they will be collected in this Properties object instead
    
    checkRequiredFields - perform check for missing required fields
    
    Returns:
    
    this schema
    
    Throws:
    
    H2OIllegalArgumentException - for bad/missing parameters
  - fillFromBody
```
public S fillFromBody(java.lang.String body)
```
    Fills this Schema from the body content when available. By default the body is interpreted as JSON object. We use PojoUtils.fillFromJson() rather than just using "schema = Gson.fromJson(post_body)" so that we have defaults: we only overwrite fields that the client has specified.
    
    Parameters:
    
    body - the post body (can't be null), converted to JSON by default
    
    Returns:
    
    the filled schema
  - fillFromAny
```
public S fillFromAny(java.lang.Object o)
```
    Parameters:
    
    o -
    
    Returns:
  - setField
```
public static <T extends Schema> void setField(T o,
                                               java.lang.reflect.Field f,
                                               java.lang.String key,
                                               java.lang.String value,
                                               boolean required,
                                               java.lang.Class thisSchemaClass)
                                        throws java.lang.IllegalAccessException
```
    Safe method to set the field on given schema object
    
    Parameters:
    
    o - schema object to modify
    
    f - field to modify
    
    key - name of field to modify
    
    value - string-based representation of value to set
    
    required - is field required by API
    
    thisSchemaClass - class of schema handling this (can be null)
    
    Throws:
    
    java.lang.IllegalAccessException
  - newInstance
```
public static <T extends Schema> T newInstance(java.lang.Class<T> clz)
```
    Returns a new Schema instance. Does not throw, nor returns null.
    
    Returns:
    
    New instance of Schema Class 'clz'.
  - newInstance
```
protected static Schema newInstance(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).
  - markdown
```
public java.lang.StringBuffer markdown(boolean include_input_fields,
                                       boolean include_output_fields)
```
    Generate Markdown documentation for this Schema possibly including only the input or output fields.
    
    Throws:
    
    H2ONotFoundArgumentException - if reflection on a field fails
  - markdown
```
public java.lang.StringBuffer markdown(SchemaMetadata meta,
                                       boolean include_input_fields,
                                       boolean include_output_fields)
```
    Generate Markdown documentation for this Schema, given we already have the metadata constructed.
    
    Throws:
    
    H2ONotFoundArgumentException - if reflection on a field fails

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

Usage

Internal details

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class water.Iced

Methods inherited from class java.lang.Object

Constructor Detail

Schema

Schema

Method Detail

init_meta

extractVersionFromSchemaName

getSchemaVersion

getSchemaName

getSchemaType

setSchemaType_doNotCall

createImpl

fillImpl

fillImpl

createAndFillImpl

fillFromImpl

fillFromImpl

fillFromImpl

getImplClass

getImplClass

fillFromParms

fillFromParms

fillFromParms

fillFromBody

fillFromAny

setField

newInstance

newInstance

markdown

markdown