Annotations are used to specify resources within a class that relate to its use as a modeling component for OMS3. Such annotations may have different relevance and importance to different aspects of the use of component use. The same annotations can also play different roles depending on their context. There are three main annotation categories:
Such meta data is essential information for component execution (in addition to the documentation purpose). Thee describe method invocation points and data flow between components. This is required meta data.
Such meta data supports the execution by providing additional information about the kind of data flow, physical units, and range constraints that might be used during execution. This is optional meta data.
Those annotations are being used for documentations, presentation layers, databases, and other content management system. This is required meta data for component publication, but optional for execution.
What are Annotations? Annotations are a Java feature since version 1.5. They are an add-on to the Java language to allow for custom and domain specific markups of language elements. They do not affect directly the class semantics, but they do affect the way classes are treated by tools, such as a modeling framework. Annotations can be seen as extension of the Java Classes with meta information that can be obtained up from sources files, compiled classes, or loaded classes at runtime. They respect also languages scopes and are supported by Java IDEs with code completion and syntax highlighting.
The table below shows all modeling annotations categorized by language elements they are describing.
Table 1. Component Annotations Overview
| Class | Field | Method |
|---|---|---|
@Description | @Description | @Execute 1) |
@Author | @In 1) | @Initialize |
@Bibliography | @Out 1) | @Finalize |
@Status | @Unit | |
@VersionInfo | @Range | |
@Keywords | @Role | |
@Label | @Bound | |
@SourceInfo | @Label | |
@License | ||
@Documentation | ||
@DLL 2) |
1) Required annotation for a component.
2) Interface annotation for Native Language integration
Annotation names always start with the '@' character, indicating the difference to a regular class. The @ (at) sign was chosen because 'AT' can be seen as abbreviation for 'Annotation Type'. Annotations can only appear once for a given language element. For example it is illegal to use the @Author annotation twice for a component. Instead, the name field of an @Author should list the two names, separated by some delimiter.
The following sections introduce all modeling annotations in detail, examples are given.
The @Description annotation provides for component summary information, such as a brief paragraph about its purpose, scientific background, etc. It is being used for automatic capturing the purpose of a component by archiving tools, online presentation or documentation tools, or to supplement database integration. The component selection during the process of model building and repository management can be supported by this annotation which should not exceed a few sentences. If more context information need to be provided, the @Documentation annotation should be used in addition.
@Description(<String>)
arg - the description paragraph
The description can be localized for different languages. Add the ISO language code (http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt) to provide description in a different language. Description for multiple languages is supported.
Documentation Annotation
Class, Field
@Description ("Circle Area Calculation.") public class CircleArea { ... @Description("Radius") @In public double r; ... } ..
@Description (en="Circle Area Calculation.", de="Berechnung der Kreisflaeche") public class CircleArea { ... @Description("Radius") @In public double r; ... } ..
The @Documentation annotation serves as a connector or link to more detailed background documentation about the component. It allows to reference other documents via a URL. Usually those documents reside on a public server or local hard drive as PDF, HTML, Docbook, or an other text document. The reference is provided as using different URL protocols such as http://..., https://..., file://...
@Documentation(<URL>)
arg - URL reference to more detailed documentation.
Documentation Annotation
Class
@Documentation
("http://myserver.com/docs/CricleArea.pdf")
public class CircleArea {
...
}The optional @Author annotation provides information about the authorship of the component. The annotation has sub the fields name, org, and contact provide more details about the name, the affiliated organization, and some contact information such as an email address, or a link to a home page.
@Author(name=<String>, org=<String>, contact=<String>)
name - the name of the authors(s)
org - organization name (optional)
contact - contract information such as email or address (optional)
Documentation Annotation
Class
@Author
(name="Joe Scientist",
org="Research Org",
contact="joe.scientist@research-org.edu")
public class HamonET {
...
}This annotation enriches a component with some development and deployment status information. A status is a component quality indicator. A developer can specify the level of completeness or maturity of a component with this tag.
@Status(<Enum>)
arg - Status.DRAFT (Initial development status, private prototype)
Status.SHARED, (component worth sharing, still in development)
Status.TESTED, (component is tested in a model, test datasets and unit tests available)
Status.VERIFIED, (component is implemented properly, complete)
Status.VALIDATED, (Component fulfills requirements, validation tests available
Status.CERTIFIED (Component accepted and certified by authorty)
Documentation Annotation
Class
@Description
("Circle Area Calculation.")
@Status
(Status.TESTED)
public class CircleArea {
...
}This annotation might be consumed by tools that publish the component to a component repository, it should control the publication process. Another use case would be the pre-run check of a deployed model that all of its components are certified by a authority.
The @VersionInfo annotation takes a argument that represents the version of this component. A developer might use version control system supported keyword substitution for this. The example below shows the use of the Subversion keywords $Id to provide revision number, modification time, and developer name as version information record. Major version control systems (CVS, Subversion,...) either have a built-in support for this feature or it can be used in conjunction with external tools (Mercurial, GIT). Therefore this annotation should not only contain an arbitrary version number, but a full version record instead is good common practice.
@VersionInfo(<String>)
arg - Version information record
Documentation Annotation
Class
@VersionInfo
("$Id: ET.java 20 2008-07-25 22:31:07Z od $")
public class ET {
...
}Component repositories can use and present this information, archiving tools or documentation generators might pick this up too.
The @SourceInfo annotation captures information about the source. This should be some hint about source availability, maybe the source location or some contact information. The example below shows the use of Subversion's keyword substitution for the head URL of a source file. It can also point to a specific tagged version with a repository.
@SourceInfo(<String>)
arg - source URL reference
Documentation Annotation
Class
@SourceInfo
("$HeadURL: http://www.test.org/repo/ET.java $")
public class ET {
...
}@SourceInfo is optional. Component repositories or documentation generators can use and present this information
A component an be tagged with the @Keywords annotation to characterize/categorize it. It does have the same purpose like a keyword list in a scientific paper. This is optional meta data and can be used to index, search, and retrieve archived and stored components. It is optional meta data.
@Keywords(<String>)
arg - list of kerwords separated by comma
Documentation Annotation
Class
@Description
("Circle Area Calculation.")
@Keywords
("Geometry, 2D")
public class CircleArea {
...
}The @License annotation to specify the license for a component. It is optional meta data. If not present it is assumed the component is in the public domain and there are no restrictions for its reuse. The license can be in lined text, however it is recommended to use a URL to point to the license text.
@License(<String>)
arg - the license text or a URL to its location
Documentation Annotation
Class
@Description("Circle Area Calculation.")
@License("http://www.gnu.org/licenses/gpl-2.0.html")
public class CircleArea {
...
}Labels relate to ontologies (label is an OWL annotation). Labeling a field or component maybe provides for alternative names. They can be used to relate components or fields to another naming convention, terminology, or ontologies.
@Label(<String>)
arg - an alternative name
Documentation Annotation
Class, Field
public class Calc {
@Label("latitude")
@In public double lat;
...
}Labels are optional.
The @In annotation on a field specifies it as input to the component. The field must be public. It indicates a read (or input access) from within the Execute method to the field. There are no arguments for this annotation.
@In
execution, documentation annotation
Field
...
@In public double latitude;
...This annotation is a required annotation for execution to enable data flow between components. @Out fields of one component might be connected to an @In field of a second component.
The @Out annotation on a field specifies it as output of the component. The field must be public and the Execute method will write to it. It is used to connect to an @In field of another component. There are no arguments for this annotation.
@Out
execution, documentation annotation
Field
...
@Out public double daylen;
...This annotation is a required annotation for execution to enable data flow between components. @Out fields of one component might be connected to an @In field of a second component.
The @Range annotation is supporting an @In or an @Out field. If present, it defines a min/max range in which the value of the field is considered valid. It is up to the execution runtime to handle the range information. Violating a ranges might lead to execution abortion if it is a serious problem or just a warning message. Another use of the range information would be in component testing, see Section ???.
@Range(min=<double>, max=<double>)
min - the minimum value, (default=Double.MIN)
max - the maximum value, (default=Double.MAX)
Execution Annotation
Field
...
@Range (min=-90, max=90)
@In public double latitude;
...In the example above the latitude value can only be in the range of -90 to +90 degree. A value out of this range would probably break any equation that is using latitude. The range use above is similar to a pre-execution check.
The @Role annotation gives an @In or @Out tagged field a certain meaning within the modeling domain. It allows someone to understand the meaning of a data field within the modeling context. A @Role annotation categorizes a field. Such categories might be "Parameter", "Variable", "Output", "Input", "Simulated" and others. The Role annotation takes the category as a String parameter. There are predefined categories defined in @Role, however categories can be defined by the component developer.
If the @Role annotation is not provided, the default Role.VARIABLE it is assumed.
@Role(<String>)
arg - the role that this field is playing in context of the component.
predefined:
Role.PARAMETER, Role.VARIABLE, Role.SIMULATED, Role.OBSERVED, Role.STATE, Role.OUTPUT
Documentation Annotation, Testing
Field
@Role(Role.PARAMETER)
@In public double latitude;
This example tags 'latitude' as Parameter.
@Role(Role.OUTPUT_FILE + Role.PARAMETER)
@In public File input;Roles can be combined too. Now the 'input' field is a parameter and an output file.
A @Unit annotation binds a physical unit to a component field that is tagged as @In or @Out. Units are usually attached to scalars and arrays fields. This information allows the frameworks to perform unit checking/validation and unit conversion. There are several open source unit conversion libraries available that could be used to perform unit conversion. An example unit conversion implementation is given in Section ???.
@Unit(<String>)
arg - the physical unit of the field
Documentation Annotation, execution support
Field
public class Calc {
@Unit("degree")
@In public double latitude;
...
}.
A @Bound defines a binding to another field. It allows to express dependencies between fields. An array field could be bound to another field that holds the size for that particular array.
@Bound(<String>)
arg - the name of the field that this field is bould to.
Documentation Annotation, execution support.
Field
public class ET {
@Bound("nsim") // 'jh_coeff' is bound to 'nsim'
@In public double[] jh_coeff;
...
@In public int nsim;
...
}The method that is tagged with the @Execute annotation provides the implementation logic of the component. In this method the component Input is being transformed to output. The execution method can have any name, it has to be non-static, public, void return type, no arguments.
This is required meta data for a component.
@Execute
Execution Annotation
Method
public class Component {
@Execute
public void executemethod() {
// execute code here
}
}Within the @Initialize method the internal state of a component is initialized. For example opening a file for reading, or a creating a data base connection would be something that should be done within @Initialize
@Initialize
Execution Annotation
Method
public class Component {
@Initialize
public void start() {
// initialization code
}
}
Name the initialize method any name you want, but annotate it with @Initialize The initialize methods has to be non-static, public, void, and has no arguments. This method gets called once after component instantiation and before the first execution. This is optional meta data.
This method provides the notion of a final cleanup after model execution (e.g. Closing a DB connection). Usually the @Finalize method and the @Initialize method are both present.
@Finalize
Execution Annotation
Method
public class Component {
@Finalize
public void cleanup() {
// execute code here
}
}The @Finalize method gets called after the final @Execute and the termination of the model.
The @DLL Annotation simplifies the integration of native Libraries written in C++, C, and FORTRAN. It takes an argument that corresponds to the name of the DLL (Windows), Shared Object (Linux/Unix), or Library (OSX).
If for example the argument is
@DLL(<String>)
arg - the core name of the DLL (without lib prefix in Linux, no file extension).
Interface Annotation
Interface<T extends Library>
import oms3.annotation.*; @DLL("F90Dyn") interface F95Test extends com.sun.jna.Library { // java interface method to FORTRAN int foomult(int a, int b); } // Bind 'F90Dyn.dll' to the interface 'F95Test' F95Test lib = Libraries.bindLibrary(F95Test.class);
Note: This annotation is supported by the