ch.agent.crnickl.api

Interface Database

All Known Subinterfaces:

DatabaseBackend

All Known Implementing Classes:

DatabaseBackendImpl

public interface Database

Database is the hub of CrNiCKL (pronounced chronicle). A client gets one or more Database objects using DatabaseFactory. Five interfaces play an important role in the data model underlying CrNiCKL:

• Chronicle
• Series
• Schema
• Property
• ValueType

These interfaces provide read access to the objects. When writing to the database, read/write versions of the interfaces are required:

• UpdatableChronicle
• UpdatableSeries
• UpdatableSchema
• UpdatableProperty
• UpdatableValueType

Read/write objects are obtained from the read only objects using the edit() method.

Two methods are provided for transactions management: commit() and rollback(). These methods are not used internally by CrNiCKL. Managing transactions and implementing transaction boundaries is the client's responsibility.

Applications control a database using four methods: configure(ch.agent.crnickl.api.DatabaseConfiguration), open(), close(), and clear(). Depending on the implementation, only the first of these methods is mandatory.

Author:

Jean-Paul Vetterli

Method Summary

Modifier and Type	Method and Description
void	clear() Clear the internal state of the database.
void	close() Close the database.
void	commit() Write all updates since the last commit or rollback to permanent storage.
void	configure(DatabaseConfiguration configuration) Configure the database.
<T> UpdatableProperty<T>	createProperty(String name, ValueType<T> valueType, boolean indexed) Create a property with the parameters specified.
UpdatableSchema	createSchema(String name, String nameOfBase) Create a schema with the parameters specified.
<T> UpdatableValueType<T>	createValueType(String name, boolean restricted, String scannerClassOrKeyword) Create a value type with the parameters specified.
Chronicle	getChronicle(String name, boolean mustExist) Return the chronicle with the given full name.
Chronicle	getChronicle(Surrogate surrogate) Return the chronicle identified by a surrogate.
MessageListener	getMessageListener() Return the message listener.
NamingPolicy	getNamingPolicy() Return the naming policy of the database.
Collection<Property<?>>	getProperties(String pattern) Return properties with names matching a pattern.
Property<?>	getProperty(String name, boolean mustExist) Return the property with the given name.
Property<?>	getProperty(Surrogate surrogate) Return the property identified by a surrogate.
Schema	getSchema(Surrogate surrogate) Return the schema identified by a surrogate.
Collection<Schema>	getSchemas(String pattern) Return schemas with names matching a pattern.
<T> Series<T>	getSeries(String name, boolean mustExist) Return the series with the given full name.
<T> Series<T>	getSeries(Surrogate surrogate) Return the series identified by a surrogate.
Property<?>	getSparsityBuiltInProperty() Return the built-in property for sparsity.
Property<?>	getSymbolBuiltInProperty() Return the built-in property for symbols.
Property<?>	getTimeDomainBuiltInProperty() Return the built-in property for time domains.
ch.agent.t2.time.TimeDomainCatalog	getTimeDomainCatalog() Return the time domain catalog.
Chronicle	getTopChronicle() Return the top chronicle.
Property<?>	getTypeBuiltInProperty() Return the built-in property for value types.
Collection<UpdatableSchema>	getUpdatableSchemas(String pattern) Return updatable schemas with names matching a pattern.
<T> UpdatableSeries<T>	getUpdatableSeries(String name, boolean mustExist) Return an updatable series.
UpdateEventPublisher	getUpdateEventPublisher() Return the event publisher for this database.
<T> ValueType<T>	getValueType(String name) Return the value type with the given name.
<T> ValueType<T>	getValueType(Surrogate surrogate) Return the value type identified by a surrogate.
Collection<ValueType<?>>	getValueTypes(String pattern) Return value types with names matching a pattern.
Surrogate	makeSurrogate(String string) Return a Surrogate corresponding to the input.
void	open() Open the database.
void	rollback() Forget all updates since the last commit or rollback.
void	setMessageListener(MessageListener listener) Set the message listener used for logging messages.

Method Detail

configure

void configure(DatabaseConfiguration configuration)
        throws T2DBException

Configure the database.

Parameters:

configuration - a database configuration

Throws:

T2DBException

open

void open()
   throws T2DBException

Open the database. This method must not be called before configure(ch.agent.crnickl.api.DatabaseConfiguration). What the method does depends on the implementation. On some implementations it is not necessary to invoke the method before using the database. Depending on the implementation it is possible to continue using the database after a fatal error by invoking close() then open().

Throws:

T2DBException

close

void close()
    throws T2DBException

Close the database. What the method does depends on the implementation. Depending on the implementation it is possible to continue using the database after a fatal error by invoking close() then open().

Throws:

T2DBException

clear

void clear()
    throws T2DBException

Clear the internal state of the database. What the method does depends on the implementation. The typical one clears any cached information.

Throws:

T2DBException

commit

void commit()
     throws T2DBException

Write all updates since the last commit or rollback to permanent storage. It is the client's responsibility to call this method.

Throws:

T2DBException

rollback

void rollback()
       throws T2DBException

Forget all updates since the last commit or rollback. It is the client's responsibility to call this method.

Throws:

T2DBException

getTimeDomainCatalog

ch.agent.t2.time.TimeDomainCatalog getTimeDomainCatalog()

Return the time domain catalog. The catalog provides access to all time domains configured in the application.

Returns:

a time domain catalog

getNamingPolicy

NamingPolicy getNamingPolicy()

Return the naming policy of the database.

Returns:

a naming policy

getUpdateEventPublisher

UpdateEventPublisher getUpdateEventPublisher()

Return the event publisher for this database.

Returns:

an update event publisher

setMessageListener

void setMessageListener(MessageListener listener)

Set the message listener used for logging messages. When no message listener has been set, or when a null listener is set, the database installs a default listener which always drops all messages.

Parameters:

listener - a message listener or null

getMessageListener

MessageListener getMessageListener()

Return the message listener. The result is never null. The default listener behaves like a listener with a filtering level set to Level.OFF.

Returns:

the message listener

makeSurrogate

Surrogate makeSurrogate(String string)
                 throws T2DBException

Return a Surrogate corresponding to the input. The input is typically a string returned by Surrogate.toString(). An exception is thrown if there is a syntax error or if the database of the surrogate is unknown.

Parameters:

string - a string representation of a surrogate

Returns:

a surrogate corresponding to the string

Throws:

T2DBException

getChronicle

Chronicle getChronicle(Surrogate surrogate)
                throws T2DBException

Return the chronicle identified by a surrogate.

Parameters:

surrogate - a surrogate

Returns:

a chronicle

Throws:

T2DBException

getSeries

<T> Series<T> getSeries(Surrogate surrogate)
                 throws T2DBException

Return the series identified by a surrogate.

Parameters:

surrogate - a surrogate

Returns:

a series

Throws:

T2DBException

getSchema

Schema getSchema(Surrogate surrogate)
          throws T2DBException

Return the schema identified by a surrogate.

Parameters:

surrogate - a surrogate

Returns:

a schema

Throws:

T2DBException

getProperty

Property<?> getProperty(Surrogate surrogate)
                 throws T2DBException

Return the property identified by a surrogate.

Parameters:

surrogate - a surrogate

Returns:

a property

Throws:

T2DBException

getValueType

<T> ValueType<T> getValueType(Surrogate surrogate)
                       throws T2DBException

Return the value type identified by a surrogate.

Parameters:

surrogate - a surrogate

Returns:

a value type

Throws:

T2DBException

getChronicle

Chronicle getChronicle(String name,
                       boolean mustExist)
                throws T2DBException

Return the chronicle with the given full name. The mustExist parameter determines behavior when nothing is found: exception or null result.

Parameters:

name - a full name

mustExist - if true throw an exception instead of returning null

Returns:

a chronicle or null (only when mustExist is false)

Throws:

T2DBException

getSeries

<T> Series<T> getSeries(String name,
                        boolean mustExist)
                 throws T2DBException

Return the series with the given full name. If the series is defined but has not yet been set up, the result is null. If the series is undefined in the schema, the result is null or an exception is thrown depending on the value of the mustExist parameter.

Type Parameters:

T - the data type of the underlying time series

Parameters:

name - a full name

mustExist - if true throw an exception instead of returning null

Returns:

a series or null (only when mustExist is false)

Throws:

T2DBException

getUpdatableSeries

<T> UpdatableSeries<T> getUpdatableSeries(String name,
                                          boolean mustExist)
                                   throws T2DBException

Return an updatable series. If the series exists and is accessible, it is returned. If it does not exist, the outcome depends on the mustExist parameter. If set, the series is created on the fly, unless something is wrong, in which case an exception is thrown. If not set the method returns null (unless something is wrong). Something is wrong when the chronicle does not exist or is not accessible, or when the series is not defined in the schema.

After a new series has been created, the client must execute Updatable.applyUpdates() on the series's chronicle or on the series itself.

Type Parameters:

T - the data type of the underlying time series

Parameters:

name - a full name

mustExist - if true throw an exception instead of returning null

Returns:

an updatable series or null (only when mustExist is false)

Throws:

T2DBException

getTopChronicle

Chronicle getTopChronicle()

Return the top chronicle. The top chronicle is virtual, it is not stored in the database. The name of the top chronicle is the name given to the database during database configuration. The top chronicle is also known as the name space.

Returns:

the top chronicle

getProperties

Collection<Property<?>> getProperties(String pattern)
                               throws T2DBException

Return properties with names matching a pattern. Patterns use a simple syntax, with an asterisk standing for zero or more characters.

Parameters:

pattern - a name pattern

Returns:

a collection of properties

Throws:

T2DBException

getProperty

Property<?> getProperty(String name,
                        boolean mustExist)
                 throws T2DBException

Return the property with the given name. If it does not exist return null or throw an exception, depending on the value of the parameter mustExist.

Parameters:

name - the name of the property

mustExist - if true throw an exception instead of returning null

Returns:

a property or null (only when mustExist is false)

Throws:

T2DBException

getSymbolBuiltInProperty

Property<?> getSymbolBuiltInProperty()
                              throws T2DBException

Return the built-in property for symbols.

Returns:

the symbol property

Throws:

T2DBException

getTimeDomainBuiltInProperty

Property<?> getTimeDomainBuiltInProperty()
                                  throws T2DBException

Return the built-in property for time domains.

Returns:

the time domain property

Throws:

T2DBException

getTypeBuiltInProperty

Property<?> getTypeBuiltInProperty()
                            throws T2DBException

Return the built-in property for value types.

Returns:

the value type property

Throws:

T2DBException

getSparsityBuiltInProperty

Property<?> getSparsityBuiltInProperty()
                                throws T2DBException

Return the built-in property for sparsity.

Returns:

the sparsity property

Throws:

T2DBException

createProperty

<T> UpdatableProperty<T> createProperty(String name,
                                        ValueType<T> valueType,
                                        boolean indexed)
                                 throws T2DBException

Create a property with the parameters specified. The client must execute Updatable.applyUpdates() on the result.

Parameters:

name - the name of the property

valueType - the value type of the attribute values

indexed - true if the property is suitable as a search criterion

Returns:

an updatable property

Throws:

T2DBException

getSchemas

Collection<Schema> getSchemas(String pattern)
                       throws T2DBException

Return schemas with names matching a pattern. Patterns use a simple syntax, with an asterisk standing for zero or more characters.

Parameters:

pattern - a name pattern

Returns:

a collection of schemas

Throws:

T2DBException

getUpdatableSchemas

Collection<UpdatableSchema> getUpdatableSchemas(String pattern)
                                         throws T2DBException

Return updatable schemas with names matching a pattern. Patterns use a simple syntax, with an asterisk standing for zero or more characters.

Parameters:

pattern - a name pattern

Returns:

a collection of updatable schemas

Throws:

T2DBException

createSchema

UpdatableSchema createSchema(String name,
                             String nameOfBase)
                      throws T2DBException

Create a schema with the parameters specified. When a base schema is specified, the new schema extends it by adding, removing, or modifying attributes and series definitions. The client must execute Updatable.applyUpdates() on the result.

Parameters:

name - the name of the schema

nameOfBase - the name of the base schema or null if there is no base schema

Returns:

an updatable schema

Throws:

T2DBException

getValueType

<T> ValueType<T> getValueType(String name)
                       throws T2DBException

Return the value type with the given name. Throw an exception if it does not exist.

Parameters:

name - a value type name

Returns:

a value type

Throws:

T2DBException

getValueTypes

Collection<ValueType<?>> getValueTypes(String pattern)
                                throws T2DBException

Return value types with names matching a pattern. Patterns use a simple syntax, with an asterisk standing for zero or more characters.

Parameters:

pattern - a name pattern

Returns:

a collection of value types

Throws:

T2DBException

createValueType

<T> UpdatableValueType<T> createValueType(String name,
                                          boolean restricted,
                                          String scannerClassOrKeyword)
                                   throws T2DBException

Create a value type with the parameters specified. The value type can be specified using a string corresponding to a value provided in ValueType.StandardValueType or the name of a class implementing ValueScanner. The client must execute Updatable.applyUpdates() on the result.

Parameters:

name - the name of the value type

restricted - true if the value type has a list of allowed values

scannerClassOrKeyword - a keyword or the name of a scanner class

Returns:

an updatable value type

Throws:

T2DBException