com.serotonin.m2m2.module
Class DataSourceDefinition

java.lang.Object
  com.serotonin.m2m2.module.ModuleElementDefinition
      com.serotonin.m2m2.module.DataSourceDefinition

public abstract class DataSourceDefinition
extends ModuleElementDefinition

A data source is the means by which m2m2 gets values into a data point, and writes set point values back to source equipment (if possible). m2m2's primary object is a data point. There are many common attributes of points, such as data type, engineering units, logging, etc. But points differ in how they get their values, and these differences are encapsulated in a "point locator". For example, a Modbus point locator consists of a slave id, register range, offset, etc. An HTTP retriever point consists of a regular expression that extracts data from a web page. The data source is (in this sense, but not literally) the container for the point locators, and has appropriate attributes. Data points, locators, and data sources (and other concepts as well) are split into VO (value object) and RT (runtime) objects. The VO represents the configuration of the object, i.e. what is saved to the database. The RT is the code (usually a thread or scheduled process) that does the actual work of connecting or listening or whatever is appropriate for the given protocol. When you are editing a data source, you are changing the attributes of the VO. When you start the data source, you are providing a VO to an RT, and then running the RT. DWR is how m2m2 realizes AJAX. More information is available here: http://directwebremoting.org/dwr/index.html. When creating a data source for m2m2, the following components are required:

Subclass of DataSourceVO

A configuration object of a data source

Subclass of PointLocatorVO

A configuration object of a point locator

Subclass of DataSourceRT

A runtime implementation of the data source. Convenience base classes are available including PollingDataSource and EventDataSource

Subclass of PointLocatorRT

A runtime implementation of the point locator

Editing JSP

The page on which a user can edit an instance of the data source

Subclass of DataSourceEditDwr

The server-side AJAX controller for the editing JSP

Optional

Online documentation files, translation files (strongly recommended), data source commissioning tools.

Author:

Matthew Lohbihler

Nested Class Summary

static class

DataSourceDefinition.StartPriority The available start priorities for data sources.

Constructor Summary

DataSourceDefinition()

Method Summary

com.serotonin.m2m2.vo.dataSource.DataSourceVO<?>	baseCreateDataSourceVO() Used by m2m2 core code to create a new data source instance as required.
protected abstract com.serotonin.m2m2.vo.dataSource.DataSourceVO<?>	createDataSourceVO() Create and return an instance of the data source.
abstract java.lang.String	getDataSourceTypeName() An internal identifier for this type of data source.
abstract java.lang.String	getDescriptionKey() A reference to a human readable and translatable brief description of the data source.
abstract java.lang.Class<?>	getDwrClass() The class of the DWR with which the data source editing page communicates.
abstract java.lang.String	getEditPagePath() The path to the data source editing page relative to the module.
DataSourceDefinition.StartPriority	getStartPriority() Override this method as required.
void	uninstall() If the module is uninstalled, delete any data sources of this type.

Methods inherited from class com.serotonin.m2m2.module.ModuleElementDefinition

getModule, initialize

Methods inherited from class java.lang.Object

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

Constructor Detail

DataSourceDefinition

public DataSourceDefinition()

Method Detail

baseCreateDataSourceVO

public final com.serotonin.m2m2.vo.dataSource.DataSourceVO<?> baseCreateDataSourceVO()

Used by m2m2 core code to create a new data source instance as required. Should not be used by client code.

getDataSourceTypeName

public abstract java.lang.String getDataSourceTypeName()

An internal identifier for this type of data source. Must be unique within an m2m2 instance, and is recommended to be unique inasmuch as possible across all modules.

Returns:

the data source type name.

getDescriptionKey

public abstract java.lang.String getDescriptionKey()

A reference to a human readable and translatable brief description of the data source. Key reference values in i18n.properties files. Descriptions are used in drop down select boxes, and so should be as brief as possible.

Returns:

the reference key to the data source short description.

createDataSourceVO

protected abstract com.serotonin.m2m2.vo.dataSource.DataSourceVO<?> createDataSourceVO()

Create and return an instance of the data source.

Returns:

a new instance of the data source.

getEditPagePath

public abstract java.lang.String getEditPagePath()

The path to the data source editing page relative to the module.

Returns:

the relative path to the editing page.

getDwrClass

public abstract java.lang.Class<?> getDwrClass()

The class of the DWR with which the data source editing page communicates. This class will be instantiated upon startup and registered as a DWR proxy. Typically this will be a subclass of DataSourceEditDwr.

Returns:

the class of the DWR proxy.

getStartPriority

public DataSourceDefinition.StartPriority getStartPriority()

Override this method as required. The start priority determines the order in which data sources are started by m2m2. By default this method returns NORMAL, and should only be overridden when absolutely necessary. For example, the Meta data source has a start priority of LAST because it depends up on the points from other data sources.

Returns:

the data source's DataSourceDefinition.StartPriority value.

uninstall

public void uninstall()

If the module is uninstalled, delete any data sources of this type. If this method is overridden, be sure to call super.uninstall so that this code still runs.

Overrides:

uninstall in class ModuleElementDefinition