ch.agent.crnickl.api

Interface UpdatableSchema

All Superinterfaces:

DBObject, IncompleteSchema, Schema, Updatable

All Known Implementing Classes:

UpdatableSchemaImpl

public interface UpdatableSchema
extends Schema, Updatable

An UpdatableSchema is a schema which can be modified. A schema can only be modified if it is not in use or if the modification has no consequence on existing use. For example a series can always be added but can only be deleted if no chronicle using the schema has actually created the series.

Updatable schemas are not only used in client applications like schema editors but also by CrNiCKL internally. Any schema can be defined as an extension to another schema. Schemas are kept in permanent storage without resolving these extensions. Before a schema is made available for use, CrNiCKL resolves the extensions. Extensions are visible to clients only in edit mode.

A hypothetical example will help to illustrate how schemas are constructed. The example uses 3 schemas: a, b, and c. Schema a defines two series, s1 and s2, and one attribute, a1. Schema b extends schema a; it removes series s2, and adds series s3. Schema c extends schema b; it adds attribute a2 and redefines attribute a1 (for example with a different default value). Given this design, a chronicle with effective schema c, will have two series, s1 and s3, and two attributes, a1 and a2. It will not be aware of the existence of schemas a and b.

Author:

Jean-Paul Vetterli

Method Summary

Modifier and Type	Method and Description
AttributeDefinition<?>	addAttribute(int attrNr) Add a new attribute to the schema.
AttributeDefinition<?>	addAttribute(int seriesNr, int attrNr) Add a new attribute to a series.
SeriesDefinition	addSeries(int seriesNr) Add a new series to the schema.
void	deleteAttribute(int attrNr) Delete an attribute from the schema.
void	deleteAttribute(int seriesNr, int attrNr) Delete an attribute from a series.
void	deleteSeries(int seriesNr) Delete a series from the schema.
void	destroy() Destroy the schema.
void	eraseAttribute(int attrNr) Set an attribute as erasing.
void	eraseAttribute(int seriesNr, int attrNr) Set a series attribute as erasing.
void	eraseSeries(int seriesNr) Set a series as erasing.
UpdatableSchema	getBase() Return the base schema if any.
Schema	resolve() Resolve into a schema.
void	setAttributeDefault(int seriesNr, int attrNr, Object defaultValue) Set the default value of a series attribute.
<T> void	setAttributeDefault(int attrNr, T defaultValue) Set the default value of an attribute.
void	setAttributeProperty(int seriesNr, int attrNr, Property<?> property) Set the property of a series attribute.
<T> void	setAttributeProperty(int attrNr, Property<T> property) Set the property of an attribute.
void	setBase(UpdatableSchema base) Set the base of the schema.
void	setName(String name) Set the name of the schema.
void	setSeriesDescription(int seriesNr, String description) Set the description of the series.
void	setSeriesName(int seriesNr, String name) Set the name of a series.
void	setSeriesSparsity(int seriesNr, boolean sparse) Set the sparsity of the series.
void	setSeriesTimeDomain(int seriesNr, ch.agent.t2.time.TimeDomain timeDomain) Set the time domain of the series.
void	setSeriesType(int seriesNr, String type) Set the value type of the series using the name of the value type.
void	setSeriesType(int seriesNr, ValueType<?> type) Set the value type of the series.

Methods inherited from interface ch.agent.crnickl.api.Schema

dependsOnSchema, edit, getSeriesDefinition, getSeriesDefinition, getSeriesDefinitions, isComplete

Methods inherited from interface ch.agent.crnickl.api.IncompleteSchema

getAttributeDefinition, getAttributeDefinition, getAttributeDefinitions, getName

Methods inherited from interface ch.agent.crnickl.api.DBObject

getDatabase, getId, getSurrogate, inConstruction, isValid

Methods inherited from interface ch.agent.crnickl.api.Updatable

applyUpdates

Method Detail

destroy

void destroy()
      throws T2DBException

Destroy the schema. The operation fails if the schema is used.

Throws:

T2DBException

resolve

Schema resolve()
        throws T2DBException

Resolve into a schema. Resolving an updatable schema resolves its base schema recursively, then adds, edits, and deletes attributes and series as specified in this updatable schema. Once resolved, the schema must be complete as determined by Schema.isComplete().

Returns:

a schema

Throws:

T2DBException

setName

void setName(String name)
      throws T2DBException

Set the name of the schema. May not be null or empty.

Parameters:

name - a string

Throws:

T2DBException

setBase

void setBase(UpdatableSchema base)
      throws T2DBException

Set the base of the schema. When not null, the base schema may not be in construction (see DBObject.inConstruction()).

Parameters:

base - an updatable schema or null

Throws:

T2DBException

addAttribute

AttributeDefinition<?> addAttribute(int attrNr)
                             throws T2DBException

Add a new attribute to the schema.

Parameters:

attrNr - a positive number not already used

Returns:

an attribute definition

Throws:

T2DBException

deleteAttribute

void deleteAttribute(int attrNr)
              throws T2DBException

Delete an attribute from the schema.

Parameters:

attrNr - the number of an existing attribute

Throws:

T2DBException

eraseAttribute

void eraseAttribute(int attrNr)
             throws T2DBException

Set an attribute as erasing. An erasing attribute deletes an attribute with the same number inherited from a base schema during schema resolution.

Parameters:

attrNr - the number of an existing attribute

Throws:

T2DBException

setAttributeProperty

<T> void setAttributeProperty(int attrNr,
                              Property<T> property)
                       throws T2DBException

Set the property of an attribute.

Parameters:

attrNr - the number of an existing attribute

property - a property

Throws:

T2DBException

setAttributeDefault

<T> void setAttributeDefault(int attrNr,
                             T defaultValue)
                      throws T2DBException

Set the default value of an attribute.

Parameters:

attrNr - the number of an existing attribute

defaultValue - a value

Throws:

T2DBException

addSeries

SeriesDefinition addSeries(int seriesNr)
                    throws T2DBException

Add a new series to the schema.

Parameters:

seriesNr - a positive number not already used

Returns:

a series definition

Throws:

T2DBException

deleteSeries

void deleteSeries(int seriesNr)
           throws T2DBException

Delete a series from the schema.

Parameters:

seriesNr - the number of an existing series

Throws:

T2DBException

eraseSeries

void eraseSeries(int seriesNr)
          throws T2DBException

Set a series as erasing. An erasing series deletes a series with the same number inherited from a base schema during schema resolution.

Parameters:

seriesNr - the number of an existing series

Throws:

T2DBException

setSeriesName

void setSeriesName(int seriesNr,
                   String name)
            throws T2DBException

Set the name of a series.

Parameters:

seriesNr - the number of an existing series

name - a string

Throws:

T2DBException

setSeriesDescription

void setSeriesDescription(int seriesNr,
                          String description)
                   throws T2DBException

Set the description of the series.

Parameters:

seriesNr - the number of an existing series

description - a string

Throws:

T2DBException

setSeriesType

void setSeriesType(int seriesNr,
                   ValueType<?> type)
            throws T2DBException

Set the value type of the series.

Parameters:

seriesNr - the number of an existing series

type - a value type

Throws:

T2DBException

setSeriesType

void setSeriesType(int seriesNr,
                   String type)
            throws T2DBException

Set the value type of the series using the name of the value type.

Parameters:

seriesNr - the number of an existing series

type - the name of a value type defined in the database

Throws:

T2DBException

setSeriesTimeDomain

void setSeriesTimeDomain(int seriesNr,
                         ch.agent.t2.time.TimeDomain timeDomain)
                  throws T2DBException

Set the time domain of the series.

Parameters:

seriesNr - the number of an existing series

timeDomain - a time domain

Throws:

T2DBException

setSeriesSparsity

void setSeriesSparsity(int seriesNr,
                       boolean sparse)
                throws T2DBException

Set the sparsity of the series. By default series are not sparse.

Parameters:

seriesNr - the number of an existing series

sparse - true to force the series to use sparse time series, else false

Throws:

T2DBException

addAttribute

AttributeDefinition<?> addAttribute(int seriesNr,
                                    int attrNr)
                             throws T2DBException

Add a new attribute to a series.

Parameters:

seriesNr - the number of an existing series

attrNr - a positive number not yet in use within the series

Returns:

an attribute definition

Throws:

T2DBException

deleteAttribute

void deleteAttribute(int seriesNr,
                     int attrNr)
              throws T2DBException

Delete an attribute from a series.

Parameters:

seriesNr - the number of an existing series

attrNr - the number of an existing attribute within the series

Throws:

T2DBException

eraseAttribute

void eraseAttribute(int seriesNr,
                    int attrNr)
             throws T2DBException

Set a series attribute as erasing.

Parameters:

seriesNr - the number of an existing series

attrNr - the number of an existing attribute within the series

Throws:

T2DBException

setAttributeProperty

void setAttributeProperty(int seriesNr,
                          int attrNr,
                          Property<?> property)
                   throws T2DBException

Set the property of a series attribute.

Parameters:

seriesNr - the number of an existing series

attrNr - the number of an existing attribute within the series

property - a property

Throws:

T2DBException

setAttributeDefault

void setAttributeDefault(int seriesNr,
                         int attrNr,
                         Object defaultValue)
                  throws T2DBException

Set the default value of a series attribute.

Parameters:

seriesNr - the number of an existing series

attrNr - the number of an existing attribute within the series

defaultValue - a value

Throws:

T2DBException

getBase

UpdatableSchema getBase()

Return the base schema if any.

Returns:

an updatable schema or null