File:Trove-3.0.2.jar

2012-03-06T20:00:23Z

Toni Kalajainen:

Org.simantics.databoard

2012-03-06T20:00:02Z

Development Practices

2011-11-08T14:23:06Z

Toni Kalajainen:

== Contributing to the Simantics codebase ==

The development of the Simantics platform is coordinated by the ''Simantics Technical Board''. The Technical Board consists of three to six members that are selected among the THTH Simantics Division member organisations by the Simantics General Meeting. The duties of the Simantics Technical Board are defined in the [https://www.simantics.org/simantics/about-simantics/thth-simantics#thth-simantics-division-rules THTH Simantics Division Rules and Regulations].

The Simantics Technical Board shall:
# prepare a proposal for the Management Board for the exact content of the new releases of Simantics
# prepare a proposal for the Management Board for the content of the training sessions
# update simantics.org website both public and member areas

'''All contributions made to Simantics modules go through the Simantics Technical Board.''' The Simantics Technical Board meetings are arranged every week. These meetings are documented in the Simantics ticket management system ([https://www.simantics.org/redmine Redmine]).

== Using version control ==

First things first, read through [http://svn.apache.org/repos/asf/subversion/trunk/doc/user/svn-best-practices.html Subversion best practices].

=== Branching ===

In Simantics, only new major releases may contain breaking changes. Therefore in Simantics we strive to use a specialization of the ''Branch-When-Needed'' system, i.e. '''Branch-Every-Major-Change'''. This allows us to keep continuous builds (hudson) working with less disruption, and enables easier pre-release testing, migration and peer review.

The rules are:
* Users commit their day-to-day work on /trunk.
* '''Rule #1''': /trunk must compile and pass regression tests at all times. Committers who violate this rule are publically humiliated.
* '''Rule #2''': a single commit (changeset) must not be so large so as to discourage peer-review.
* '''Rule #3''': if rules #1 and #2 come into conflict (i.e. it's impossible to make a series of small commits without disrupting the trunk), then the user should create a branch and commit a series of smaller changesets there. This allows peer-review without disrupting the stability of /trunk.
* '''Rule #4''': if API is changed, old version in the trunk must be tagged, and version number of the trunk must be increased. If API changes break other trunk code, development must continue in its own branch. Non-incremental change in an ontology is counted as major change (prevents using existing databases); new branch must be created.

;Pros: /trunk is guaranteed to be stable at all times. The hassle of branching/merging is somewhat rare.

The word '''stable''' here implies mainly API stability but also functional stability. Functional stability must be enforced through both automatic and manual testing. If there are no test cases, functional stability becomes really hard to enforce. Therefore testing is key.

Violating these rules will result removal of your breaking commits from the SVN.

=== Integrating Branches ===
We obviously do not want development to continue eternally in branches so that changes are never merged between branches or integrated back to trunk. Branches are usually private or shared between a group of developers that work on a particular task. The process for integration to trunk is as follows:
* The Simantics Technical Board ('''STB''') and its weekly meetings will be the place for the developers to advertise and present their changes to the board.
* The following things need to be documented for the changes in some way:
** The '''what''' and '''why''' for the changes
** Migration instructions from previous version (trunk):
*** A direct patch to fix problems
*** or plain-text instructions
** When integration is done, mail must be sent to [mailto:simantics-developers@lists.simantics.org Simantics developers list] about the change.
** ...

TODO more description

=== Versioning ===

In Eclipse/OSGi conventions, components (bundles, plug-ins) are versioned <major>.<minor>.<service>[.<qualifier>].

Our approach to component versioning is as follows:
* All components are in one of two states: '''incubation''' or '''production'''
* Incubation components: <major> = 0, API breakage is allowed between <minor> versions
* Production components: <major> ≥ 1, API breakage is allowed between <major> versions

== Creating a new plugin ==

Before a release, the plugin is in incubation phase and there are no quality or other requirements. The repository https://www.simulationsite.net/svn/simantics-incubator may be used to share or co-develop the plugin with other developers, but
the plugin must not be included in the features defined in https://www.simulationsite.net/svn/simantics repository.

If the new plugin is a result of refactoring some already existing plugin into two pieces or otherwise is closely related to an other plugin under development, the new plugin can be committed to the same branch of https://www.simulationsite.net/svn/simantics where the other plugin is developed in. Note that whenever this kind of piecing happens, it has the potential to affect the consistency of other components or products. In such cases the refactor should be carried out in branches, not in trunk.

=== Naming a plugin ===

If the plugin is intended to be part of the official Simantics release, its name should begin with ''org.simantics'' followed by a word that describes the plugin. If the functionality of the same domain is divided into multiple plugins, the name may have more parts. The following suffixes are used:
* ''.feature'' for feature projects.
* ''.product'' A plugin defining a product.
* ''<plugin>.ui'' Provides UI-functionality for ''<plugin>''. Separating base functionality and UI (that depends on SWT) is usually recommendable so that headless applications do not have unnecessary dependencies.
** Example: org.simantics.simulation, org.simantics.simulation.ui

'''NOTE!''' If the the UI is light (e.g. wizards, dialogs, renderers, few external dependencies) the UI code can reside in ''<plugin>'', a separate ''<plugin>.ui'' is not required. In such a case, the UI dependencies (to plugins such as ''org.eclipse.swt'') are ''optional''.

==== Naming in feature projects ====

Features have two distinct names: '''project name''' and '''feature ID'''. The '''project name''' is defined in the ''.project'' file. It shall contain the ''.feature'' suffix since the project name affects how Eclipse checks the project out into workspaces from version control systems. The '''feature ID''' is defined in feature.xml and it shall not contain the ''.feature'' suffix.

This naming convention exists for many reasons:
* P2 automatically appends '''.feature.group''' to to identification of installable units (IU) generated from features. Artifacts with '''.feature.feature.group''' ID tail .
* Works well with [http://www.eclipse.org/buckminster/ Buckminster] and its [http://wiki.eclipse.org/Buckminster_Resource_Map resource maps].

== Modifying a feature ==

When a plug-in is added to or removed from a feature, the following steps must be performed:
# Increment the version number of the feature, primarily the service version number part.
# Increment service version of all other features dependent on this feature
# Fix .product files that refer to the re-versioned features

This is necessary most of all to keep Eclipse IDE happy and working properly with checked out plug-ins and the P2-based target platforms.

If these steps are not performed, Eclipse will keep using the target platform version of the modified feature not realizing the changes you've made to it. This results often in products failing to work properly or not starting at all.

== Publising a standalone plugin ==

# Ensure that the plugin satisfies the following quality requirements:
#* The plugin contains no compilation errors (against which dependencies???)
#* All public classes and interfaces are documented (javadoc)
#* Each public package contains a package-info.java containing package-related comments and annotations (see [http://java.sun.com/docs/books/jls/third_edition/html/packages.html] ''chapter 7.4'')
#* examples/
#* unittests/
#* Version information
#* (optional) Build Script (targets: ''clean'', ''build'', ''clean-build'')
#** [name]_[version]-src.zip
#** [name]_[version].jar
#** [name]_[version].zip
#*** doc/
#**** manual.pdf
#**** changelog.txt
#*** examples/
#*** unittests/
#*** javadoc/ (''optional'')
#*** [name]_[version]-src.zip
#*** [name]_[version].jar
#** [name]_[version]-project.zip (Contains everything in workspace)
#** See Example: [[svn:foundation/databoard/trunk/org.simantics.databoard/build2.xml|Non-OSGi]]
# Create a homepage for the plugin in wiki (for example [[org.simantics.databoard]]) that contains:
#* Development documentation that is not written in javadoc (basic concepts, components etc.) [We should discuss more about what and how to document] and links to user documentation if the plugin contributes new user interfaces.
#* Change log
#* Plugin roadmap
#* Who are responsible for the plugin
#* (optional) Download to artifacts created by Build script
# Commit the plugin to https://www.simulationsite.net/svn/simantics/<moduleName>/trunk
# Create a tag of the plugin to https://www.simulationsite.net/svn/simantics/<moduleName>/tags/<version>
# Inform other developers about the new plugin through the mailing list [simantics-developers@simantics.org]. See also [https://www.simantics.org/wiki/index.php/Mailing_Lists Mailing Lists].

=== Including a new plug-in to existing features ===

Inclusion of a plug-in in a feature must always be carefully considered. Consider the following before including anything:
* '''Cohesion''': Does the plug-in logically belong in the considered feature.xml?
* '''Dependencies''': What does the new plug-in depend on? Which dependencies are optional? Do the dependencies of the feature's other plug-ins intersect naturally with those of the new plug-in?
* '''Permission''': do not add anything without permission from the feature maintainer or send a patch and hope it will be merged.

It is highly recommended to have plug-ins included in a single feature only. Instead of including plug-ins in multiple features, prefer creating highly logical and cohesive features that can acyclically include each other. In general completely new functionality should be put in its own feature. If you are unable to decide where a plug-in should be included, ask yourself is the plug-in properly cohesive, are its dependencies minimal?

Note that it is not technically mandatory that each plug-in only resides in one feature - it is simply good practice and will most likely help in training people to use the platform and also make maintainance easier. Having multiple features including the same plug-in will not break builds, but will make the product structure more difficult to understand.

Modifying a feature may break:
# [[svn:project-set/|Project sets]]
#* FIX: add a line in the related PSF file(s) for the new plug-in in all project sets that include the modified feature
# [http://www.simantics.org/jenkins Jenkins jobs] that depend on the feature
#* See [[#Building Products]] for instructions on how to define headless product builds

== Releasing a new version of a component ==

Here, a component stands for ''a plug-in'', ''a set of plug-ins'' or ''a feature''.

# Increment version number(s), incl. MANIFEST.MF, plugin.xml, feature.xml, build.xml, homepage.
#* Bug fixes increment service number, API changes minor number and large releases major number.
# Run test cases or test suite
# Check java docs are compiled without errors. Read Javadocs
# Update homepage
# (optional) run build.xml and upload generated artifacts to homepage
# Create SVN tag: trunk/ → tags/[version]
# Inform other developers [mailto:simantics-developers@lists.simantics.org Simantics developers list].

== Making refactorizations that affect other plugins ==

# Plan refactorization beforehand with the maintainers of all affected plugins
# Create a new branch for all affected plugins
# Refactor, different possibilities
#* One person refactors all plugins
#* Every maintainer refactors his/her own plugins
#** Create rename scripts for other maintainers to help them
# Check that everything works
# If changes were large inform other developers in the mailing list
# Commit plugins to trunk

== Developing and maintaining a released plugin ==

Generally, people need to be able to commit their changes continuously to the SVN location dedicated for a component. Often committing is necessary for transferring their changes to another machine or just to keep their code safe. We can't allow developers committing API changes or broken temporary code into SVN locations that other projects are using - those need to be stable to some degree. Hence, the active development and API breaking '''must''' occur in SVN locations that are documented to be unstable and modifiable only by component maintainer(s). These locations shall be released to the general public according to the roadmap of the component. For every release, a ''tag'' shall be created. For every release external dependencies need to be documented: component name, version to use (tag). Releases are versioned. Version numbers are composed of three (3) segments: 3 integers and a string respectively named major.minor.service. Read [http://wiki.eclipse.org/index.php/Version_Numbering] and [http://wiki.eclipse.org/Evolving_Java-based_APIs].

# the major segment indicates breakage in the API
# the minor segment indicates "externally visible" changes
# the service segment indicates bug fixes and the change of development stream (the semantics attached to development stream is new to this proposal, see below)

By default, the following SVN layout should be used for components:
: component/
:: trunk/
:::* The main development branch, unstable by nature. This version should only be used by active developers of this component.
:: branches/
:::* Branches should be created:
:::** when preparing for a release, for stabilizing the component while letting active development run along in ''trunk''.
:::** for working on bug-fix releases.
:::** when working on larger changes, trying out things or working with other developers. These kinds of branches should either be integrated back to where they were branched from or removed as obsolete.
:: tags/
:::* Released versions of the component. Other developers and project-sets should be using these for development if the component isn't already deployed into the target platform or it is necessary to have the code in your workspace for some other reason.

Developers may initially feel that creating tickets for every measly issue is too time consuming but it is necessary to make any kind of change tracking possible for releases. Obviously during the initial development of a component the code changes a lot and all the time. This is exactly why we have an ''incubator'' for starting projects that does not impose these strict rules but is more like a playground where the developer can freely "hack around" disregarding all these policies. A good developer will get started on design, testing and documentation also right from the start. When the developer feels his component is ready for consumption of the general public and the component passes peer review, it shall be ceremonially transferred from incubation into the official project. Each official component should have documentation, unit tests and possibly examples or '''really good''' reasons for not having any.

== Modifying the target platform ==

The target platform is a composition of features and plug-ins that contains all the bundles that you as a developer can build your code against when starting from a blank table. It is a mixture of the standard Eclipse RCP platform, other general Eclipse components and also some Simantics components.

It makes sense to deploy into the target platform only if your plug-ins:
* are general, i.e. reusable by many other components
* have little dependencies
* are stable, both by API and functionally

Deploying plug-ins into the target platform will most likely break:

# [http://www.simantics.org/jenkins Headless PDE builds] that depend on the feature
#* Remove the deployed plug-ins from the plugins/ directory of the build structure to take the deployed plug-ins from the target platform
#* The target platform(s) used by the builds must be updated
#* TODO: link to instructions for general hudson and PDE build configuration
# [[svn:project-set/|Project sets]]
#* FIX: remove lines matching the plug-ins that were moved into the target platform

=== Deploying plug-ins for the target platform ===

TODO: these instructions are out-of-date for Simantics 1.4 and the proper use of P2 repositories

;Standard Procedure:
# Test your deployed components.
# Read the instructions below and deploy your plug-ins and features as P2 repositories
# Make your built P2 repository available on the internet and notify the [[Target Platform#Maintainer|target platform maintainer]] to grab your changes and update the official target platform.

There are two main ways of deploying for the target platform:
* deploying plug-ins and fragments directly
* deploying plug-ins and fragments through features

These steps can be performed using the Eclipse ''export wizard'' through the ''Plug-in Development/Deployable features'' and ''Plug-in Development/Deployable plug-ins and fragments'' wizards

When considering whether your component should have a feature or not, consider these points:
* Eclipse products/applications are always made up of either a set of features or a set of plug-ins. In order for someone to use your component in an product, either your features or your plug-ins need to be included somewhere in the product. If a product is using features and you don't provide one, the product either has to create a new feature and include it or include your plug-ins in his own features.
* Features can be used as a way to give a collective version all plug-ins of a component. The feature will identify the versions of its included plug-ins but these need not be identical to the feature version. Not all plug-ins have to change versions while a feature version changes each time a new release of the component is made.
** '''IMPORTANT''': The feature deployment build will produce a ''P2 repository'' containing ''content.jar'', ''artifacts.jar'' and two directories, ''features/'' and ''plugins/''. The features-directory will contain the feature as JAR files which is correct when used as a P2 repository. But if you want to install your deployed features into the current target platforms, the feature jars must be unpacked with the JAR file names as the directory names' '''Don't unpack directly into the features directory''', the feature JARs do not contain a common parent folder. For example, if you've built your feature with an ID '''my.feature''' and version '''1.0.0''', the build will produce a file '''my.feature_1.0.0.jar'''. The contents of this jar must be unpacked into '''features/my.feature_1.0.0/'''. If you copied the JAR files into the features directory and unpack them there, '''do not leave the JARs in the features directory'''. This will also break the features.

== Building Products ==

The best way to currently build products is to use the Eclipse tool [http://www.eclipse.org/buckminster/ Buckminster] for the job.

;Pre-requisites:
# You have a product configuration (.product file) for your product.
# Your product configuration is based on ''features'', not plug-ins
# Buckminster locally installed or a jenkins installation with buckminster available

; Example
To create your own (headless) buckminster product build follow these steps:
# Export [[svn:tutorials/trunk/com.acme.movie.product.site.feature]] as a template for making your own headless buckminster product build.
# To customize for your purposes, the following contents need to be configured:
## feature.xml
##* Change ID, version, name, provider and everything else to match your purposes.
##* Include all the features your .product file depends on, nothing else.
## Resources.rmap
##* Define mappings for all resources (features and plug-ins) needed by your product. See [[#External links|Buckminster definitive guide]] for help on defining resource maps.
## .credentials.properties
##* Insert any credentials needed to access resources defined in your resource map.
## site.cquery
##* Modify cq:rootRequest name to match your site feature ID.
## jenkins.buckminster.script
##* Replace '''com.acme.movie.product.site''' with what ever is your site feature's ID.
##* Replace p2.profileName with a new profile name for your product.
##* Replace p2.rootId to match the '''uid''' attribute defined in your Product Configuration file (.product).
##* Set build.label to what ever you want your built product .zip files to be named like.

=== Using Continuous Integration (Jenkins) ===

# Install [http://jenkins-ci.org/ jenkins] (see [http://www.simantics.org/jenkins simantics.org jenkins])
# Create new ''free-style software project'' job with appropriate name
# Configure the project:
## In the ''Source code management'' section, use your version control system of choice to checkout the '''...product.site.feature''' you've created for your build in the previous section. For the com.acme.movie example the proper settings would be:
##* Select ''Subversion Modules''
##* Repository URL: https://www.simantics.org/svn/simantics/tutorials/trunk/com.acme.movie.product.site.feature
##* Local Module directory (optional): com.acme.movie.product.site
##* Check-out strategy: Always check out a fresh copy
## In the ''Build'' section:
### Add new '''Run Buckminster''' build step
### Select a Buckminster 3.7 installation to use
### Copy the contents of '''jenkins.buckminster.script''' into the ''commands'' text box
## Last, you'll want to archive the vital artifacts produced by your build. In the ''Post-build Actions'' section:
### Check ''Archive the artifacts''
### Set value of ''Files to archive'' to '''buckminster.output/com.acme.movie.product.site_*-eclipse.feature/*.zip''' (obviously changing the value according to the name of your product site feature).

That should do it. Further configuration of the build is up to you, i.e. scheduling, parsing warnings, and so on.

== External links ==

* [http://www.eclipse.org/buckminster/ Buckminster Homepage]
* [http://www.eclipse.org/downloads/download.php?file=/tools/buckminster/doc/BuckyBook.pdf Eclipse Buckminster, The Definitive Guide]

[[Category: Miscellaneous Documents]]

2011-09-19T06:54:51Z

Toni Kalajainen:

This plugin''(org.simantics.history'') contains a library for history service.

== Details ==

HistoryManager manages persistent and stateful objects called "Subscription".
Subscription has globally unique id (GUID).

When a subscription is recorded, it is opened and a handle is received.
To record the user supplies time code and values for each variable.

A subscription consists of items that describe how a variable is to be recorded
and stored in a file. For each item: interval, deadband, variableId, enabled,
and the sample format are provided.

Sample format describes the format how the data is stored in the stream file, the
primitive types and fields to record. There is a well-known set of
fields that the recording supports. Unknown fields are left unchanged.
Fields "time", "endTime", and "value" are mandatory.

Sample = {
// Time
time : Double, // Time of the first sample (mandatory field)
endTime : Double, // Time of the last sample (mandatory field)

// Values
value : Double, // First value (mandatory field)
lastValue : Double, // Last value
avg : Double, // Avg value of source valus within the band's time range
median : Double, // Median value
min : Double,
max : Double,

count : Integer // The number of source values acquired
}

One variable is typically subscribed with multiple items. For instance, simantics
chart subscribes the chart_raw, chart_1s, chart_10s, chart_60s, and chart_min-max
items. 1s, 10s, and 60s have corresponding interval value (eg. max. 1 entry per 10s of data).
"min-max" is an subscription item that tracks down the minimum and maximum
value of the variable. It has infinitely long interval value and thus records
only one sample (unless there is discontinuation).

The sample entry is basically a band of values. The entry is packed even if
deadband and interval are disabled. The system packs the unchanged set of values
into a single entry.

Simple = {
time : Double,
endTime : Double,
value : Double
}

The system can write down any primitive fields. Even arrays, enums, records
and strings. Time and endTime fields must be numeric, values not.

Example1 = {
time : Long,
endTime : Long,
value : Double,
avg : Float
}

VectorSample = {
time : Long,
endTime : Long,
value : Double[ 3 ]
}

==Discontinuity==
The assumption is that two consecutive steram entries describe a data that is sampled
continuously from the source. If there is non-continuation in the source data or
if the recording was disabled temporarily, a discontinuation marker is added.

To support discontinuation in the data stream, the value-field must have Optional value.

Example = {
time : Long,
endTime : Long,
value : Optional( Double )
}

Other value-fields need not be Optional().

==File History==

File based implementation is the only existing implementation. Files are
managed in workarea (folder). Subscription state and recording metadata is in one
file, and all subscription items each in a separate file.

Subscription - [SubscriptionId].dbb
SubscriptionItem - [SubscriptionId]-VariableId-[sampling hash hex]-[sampling name].stm

When a subscription is created, it prepares all related files. If a subscription
is modified, it reflects to files by deleting and creating new.

An open subscription recording can be closed and opened, the state data is persisted
when the handle is closed.

Org.simantics.history

2011-09-19T06:54:17Z

Toni Kalajainen:

Org.simantics.history

2011-09-19T06:53:10Z

Toni Kalajainen:

This plugin''(org.simantics.history'') contains a library for history service.

== Details ==

HistoryManager manages persistent and stateful objects called "Subscription".
Subscription has globally unique id (GUID).

When a subscription is recorded, it is opened and a handle is received.
To record the user supplies time code and values for each variable.

A subscription consists of items that describe how a variable is to be recorded
and stored in a file. For each item: interval, deadband, variableId, enabled,
and the sample format are provided.

Sample format describes the format how the data is stored in the stream file, the
primitive types and fields to record. There is a well-known set of
fields that the recording supports. Unknown fields are left unchanged.
Fields "time", "endTime", and "value" are mandatory.

Sample = {
// Time
time : Double, // Time of the first sample (mandatory field)
endTime : Double, // Time of the last sample (mandatory field)

// Values
value : Double, // First value (mandatory field)
lastValue : Double, // Last value
avg : Double, // Avg value of source valus within the band's time range
median : Double, // Median value
min : Double,
max : Double,

count : Integar // The number of source values acquired
}

One variable is typically subscribed with multiple items. For instance, simantics
chart subscribes the chart_raw, chart_1s, chart_10s, chart_60s, and chart_min-max
items. 1s, 10s, and 60s have corresponding interval value (eg. max. 1 entry per 10s of data).
"min-max" is an subscription item that tracks down the minimum and maximum
value of the variable. It has infinitely long interval value and thus records
only one sample (unless there is discontinuation).

The sample entry is basically a band of values. The entry is packed even if
deadband and interval are disabled. The system packs the unchanged set of values
into a single entry.

Simple = {
time : Double,
endTime : Double,
value : Double
}

The system can write down any primitive fields. Even arrays, enums, records
and strings. Time and endTime fields must be numeric, values not.

Example1 = {
time : Long,
endTime : Long,
value : Double,
avg : Float
}

VectorSample = {
time : Long,
endTime : Long,
value : Double[ 3 ]
}

==Discontinuity==
The assumption is that two consecutive steram entries describe a data that is sampled
continuously from the source. If there is non-continuation in the source data or
if the recording was disabled temporarily, a discontinuation marker is added.

To support discontinuation in the data stream, the value-field must have Optional value.

Example = {
time : Long,
endTime : Long,
value : Optional( Double )
}

Other value-fields need not be Optional().

==File History==

File based implementation is the only existing implementation. Files are
managed in workarea (folder). Subscription state and recording metadata is in one
file, and all subscription items each in a separate file.

Subscription - [SubscriptionId].dbb
SubscriptionItem - [SubscriptionId]-VariableId-[sampling hash hex]-[sampling name].stm

When a subscription is created, it prepares all related files. If a subscription
is modified, it reflects to files by deleting and creating new.

An open subscription recording can be closed and opened, the state data is persisted
when the handle is closed.

Org.simantics.history

2011-09-19T06:52:33Z

Toni Kalajainen: Created page with "This plugin''(org.simantics.history'') contains a library for history service. == Details == HistoryManager manages persistent and stateful objects called "Subscription". Subsc..."

This plugin''(org.simantics.history'') contains a library for history service.

== Details ==

HistoryManager manages persistent and stateful objects called "Subscription".
Subscription has globally unique id (GUID).

When a subscription is recorded, it is opened and a handle is received.
To record the user supplies time code and values for each variable.

A subscription consists of items that describe how a variable is to be recorded
and stored in a file. For each item: interval, deadband, variableId, enabled,
and the sample format are provided.

Sample format describes the format how the data is stored in the stream file, the
primitive types and fields to record. There is a well-known set of
fields that the recording supports. Unknown fields are left unchanged.
Fields "time", "endTime", and "value" are mandatory.

Sample = {
// Time
time : Double, // Time of the first sample (mandatory field)
endTime : Double, // Time of the last sample (mandatory field)

// Values
value : Double, // First value (mandatory field)
lastValue : Double, // Last value
avg : Double, // Avg value of source valus within the band's time range
median : Double, // Median value
min : Double,
max : Double,

count : Integar // The number of source values acquired
}

One variable is typically subscribed with multiple items. For instance, simantics
chart subscribes the chart_raw, chart_1s, chart_10s, chart_60s, and chart_min-max
items. 1s, 10s, and 60s have corresponding interval value (eg. max. 1 entry per 10s of data).
"min-max" is an subscription item that tracks down the minimum and maximum
value of the variable. It has infinitely long interval value and thus records
only one sample (unless there is discontinuation).

The sample entry is basically a band of values. The entry is packed even if
deadband and interval are disabled. The system packs the unchanged set of values
into a single entry.

Simple = {
time : Double,
endTime : Double,
value : Double
}

The system can write down any primitive fields. Even arrays, enums, records
and strings. Time and endTime fields must be numeric, values not.

Example1 = {
time : Long,
endTime : Long,
value : Double,
avg : Float
}

VectorSample = {
time : Long,
endTime : Long,
value : Double[ 3 ]
}

===Discontinuity==
The assumption is that two consecutive steram entries describe a data that is sampled
continuously from the source. If there is non-continuation in the source data or
if the recording was disabled temporarily, a discontinuation marker is added.

To support discontinuation in the data stream, the value-field must have Optional value.

Example = {
time : Long,
endTime : Long,
value : Optional( Double )
}

Other value-fields need not be Optional().

==File History==

File based implementation is the only existing implementation. Files are
managed in workarea (folder). Subscription state and recording metadata is in one
file, and all subscription items each in a separate file.

Subscription - [SubscriptionId].dbb
SubscriptionItem - [SubscriptionId]-VariableId-[sampling hash hex]-[sampling name].stm

When a subscription is created, it prepares all related files. If a subscription
is modified, it reflects to files by deleting and creating new.

An open subscription recording can be closed and opened, the state data is persisted
when the handle is closed.

Plugins

2011-09-19T06:45:53Z

Toni Kalajainen:

Database Feature:
*[[org.simantics.db]]
*[[org.simantics.db.procore.server]]
*[[org.simantics.db.tests]]
*[[org.simantics.objmap]]
*[[org.simantics.scl]]

Diagram Feature:
*[[org.simantics.g2d]]
*[[org.simantics.g2d.feature]]
*[[org.simantics.diagram]]
*[[org.simantics.scenegraph]]
*[[org.simantics.scenegraph.ui]]

Simulation Feature:
*[[org.simantics.history]]

Browsing Feature:
*[[org.simantics.browsing.ui.feature]]
*[[org.simantics.browsing.ui]]

Databoard Feature:
*[[org.simantics.databoard]]

Project Management Feature:
* [[org.simantics.project]]

Utility plugins:
* [[org.simantics.fastlz]]
* [[org.simantics.wiki]]
* [[org.simantics.message.feature]]
* [[org.simantics.message]]

Eclipse IDE Features:
*[[org.simantics.graph]]

Databoard Tutorials

2011-09-07T11:17:55Z

Toni Kalajainen:

This document contains a some Java coding snippets for Databoard.

==Object Deep-Copy==
The binding class can be used for cloning objects. All copied objects are deep. Mutable objects are duplicated, and immutable are referenced.

<syntaxHighlight lang="java">
// Binding can copy objects. All copies are deep.
// Mutable objects are duplicated, immutable are referenced.

// For instance, in object array, the array is copied, but its
// immutable literal instances (e.g. 1) is referenced.

Object[] original = new Object[] { 1, "X", 123.456 };
Binding binding = Bindings.getBinding( original.getClass() );
Object[] copy = (Object[]) binding.cloneUnchecked( original );

// Print the objects
System.out.println( "Original: "+binding.toString( original ) );
System.out.println( "Clone : "+binding.toString( copy ) );
</syntaxHighlight>

Recursive classes can also be cloned, but they must be annotated with @Referable tag.
<syntaxHighlight lang="java">
static @Referable class X {
public X reference;
}

public static void main(String[] args) throws BindingConstructionException, BindingException {
// Create recursive instance
X original = new X();
original.reference = original;

Binding binding = Bindings.getBinding( original.getClass() );
X copy = (X) binding.cloneUnchecked( original );

// Print the objects
System.out.println( "Original: "+binding.toString( original ) );
System.out.println( "Clone : "+binding.toString( copy ) );
}
</syntaxHighlight>

==Object Deep-Compare==
Binding can compare any two instances. The compare function is deep.

<syntaxHighlight lang="java">
Binding binding = Bindings.getBindingUnchecked( int[].class );

int[] array1 = new int[] { 1, 2, 3 };
int[] array2 = new int[] { 1, 2, 3 };
int[] array3 = new int[] { 2, 3, 4 };

if ( binding.compare(array1, array2) == 0 ) {
System.out.println( "array1 is equal to array2" );
} else {
System.out.println( "array1 is not equal to array2" );
}

if ( binding.compare(array1, array3) == 0 ) {
System.out.println( "array1 is equal to array3" );
} else {
System.out.println( "array1 is not equal to array3" );
}
</syntaxHighlight>

Two bindings can compare instances of same datatype, even if they are of different classes.
<syntaxHighlight lang="java">
ArrayList<Integer> array4 = new ArrayList<Integer>();
Binding binding2 = Bindings.getBindingUnchecked( ArrayList.class, Integer.class );
array4.add( 1 );
array4.add( 2 );
array4.add( 3 );

if ( Bindings.compare(binding, array1, binding2, array4) == 0 ) {
System.out.println( "array1 is equal to array4" );
} else {
System.out.println( "array1 is not equal to array4" );
}
</syntaxHighlight>

== Object deep-hashcode ==
Binding can calculate deep hashcode for any instance

<syntaxHighlight lang="java">
Binding binding = Bindings.getBindingUnchecked( int[].class );

int[] array1 = new int[] { 1, 2, 3 };
int[] array2 = new int[] { 1, 2, 3 };
int[] array3 = new int[] { 2, 3, 4 };

System.out.println( "Hashcode for array1 is " + binding.hashValue( array1 ) );
System.out.println( "Hashcode for array2 is " + binding.hashValue( array2 ) );
System.out.println( "Hashcode for array3 is " + binding.hashValue( array3 ) );
</syntaxHighlight>