Metadata and Annotations

Metadata is used in order for the application to be able to obtain information for the set of Properties/Operations of particular FI. Annotations are used for defining Functional Items Metadata.

Metadata

Metadata is used in order for the application to be able to obtain information for the set of Properties/Operations of particular FI. Also the type of each property and the types of arguments for the operation and the result. Functional Items may use different metadata types. To obtain specific information about the metadata of Item/Property/Operation the following commands may be executed. They invoke different methods (e.g. getItemMetadata). For more information check the metadata package.

fim>$info 1

Information for Functional Item

-----------------------------------------------------------------------------------------------------------------------

UID

demo:fim:BinarySwitch:1

Name BS Room 1

Version 2.0.0

Tags lamp

Interfaces com.prosyst.mbs.demo.fim.BinarySwitch

Properties

state Switched On

Operations turnOff

toggle

turnOn

fim>$info 1 state
Property                      state
Value                         Switched On
classes                       com.prosyst.mbs.demo.fim.BinarySwitch$State
consts                        {name: OFF, value: Switched Off}
                              {name: ON, value: Switched On}
description                   Switch state.
getter                        getState
isEventable                   true
name                          state

fim>$info 1 turnOn
Operation                     turnOn
description                   Turns on the binary switch.
name                          turnOn
parameters                    N/A
return                        N/A

Different Types of Metadata

The following properties are required for defining all Functional Items:

Key	Description
name	Name of the Functional Item (e.g. Alarm).
description	User-friendly description of the FI function.
type	The type of FI Metadata that will be used (e.g. Numeric, Enum, Bean, etc.).
classes	The Metadata Classes.

Types of Metadata:

Numeric – Identifies the annotated element as holding a numeric value with the specified range and step. This annotation is optional. If not applied the value of the element can be still a numeric. It can be applied to a property, an operation parameter or an operation return type. The element must also be marked with the corresponding annotation for its type – Property or Operation.

Key	Description
min	The minimum value (inclusive) that is allowed for this numeric. If not specified, the minimum is the minimum number allowed for its type.
max	The maximum value (inclusive) that is allowed for this numeric. If not specified, the maximum is the maximum number allowed for its type.
step	The step value that is used for this numeric. It must be a positive number. If not specified, the step is the smallest number allowed for its type.

Enum – Identifies the annotated element as holding an enumeration with constants. It can be applied to a property, an operation parameter or an operation return type. The element must also be marked with the corresponding annotation for its type – Item, Property or Operation.

Key	Description
enumConstants	Array used for the list of Enum Constants (EnumConst[]) that have name/value pair. Each array (EnumConst[]) has name (The name of the enum constant) and value (The value of the enum constant).

Bean – Bean represents a map structure annotation. The BeanMetadata provides the metadata of TypeMetadata.Type#BEAN, such as: bean version and bean fields metadata.

Key

Description

version

The bean version.

fields

The fields metadata. The keys in the returned map are the fields names and the values are the metadata for each bean field.

There are several special cases when:
- the bean has no fields - then the result is an empty map.
- the bean is a FunctionalItem - then the result is a map with one key FunctionalItem.UID.
- the bean field class is already declared in the parent metadata (a metadata cycle) - then the result is null. It should be used to protect the cycles when another bean has a field with the same type (or the type of one of its parents).
Item - Identifies the annotated interface as a functional item interface. Every functional item interface must be marked with this annotation otherwise it will not be processed as such.
@Documented@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface Item

Key	Description
version	The bean version.
fields	The fields metadata. The keys in the returned map are the fields names and the values are the metadata for each bean field.

Annotations

The FIM annotations (com.prosyst.mbs.services.fim.annotations) are used for defining Functional Items Metadata. They can be used in java interfaces, their constants and methods or in class (beans) methods.

The table below displays the possible use of annotations. "@" means "annotated".

Annotation	Item annotated interface	Interface constant	Method/Method return	Method parameter	Class
Item	Yes	No	No	No	No
Name	Yes	No	No	No	No
Description	Yes	Yes if @Property	Yes if FI @Operation return or Bean field @Getter	Yes if @Operation	No
Version	Yes	No	No	No	Yes
Attribute(s)	Yes	Yes if @Property	Yes if @Operation	No	No
Property	No	Yes	No	No	No
Operation	No	No	Yes in FI Interface	No	No
OperationEvent (since 2.3.0)	No	Yes (since 2.3.2000)	Yes in FI Interface	No	No
OperationEventProperty (since 2.3.0)	No	Yes	No	No	No
Getter	No	No	Yes in FI Interface or Bean	No	No
Setter	No	No	Yes in FI Interface	No	No
Ignore	Yes	No	Yes in FI Interface or Bean	No	No
Regex (since 2.3.0)	No	Yes If @Property	Yes if FI @Operation return or Bean field @Getter	Yes if @Operation	No
Numeric	No	Yes if @Property	Yes if FI @Operation return or Bean field @Getter	Yes if @Operation	No
Enum (deprecated since 2.3.0, automatically detected for java enums)	No	Yes if @Property	Yes if FI @Operation return or Bean field @Getter	Yes if @Operation	No
Constructor	No	No	No	No	Yes, for one of the constructors
Status (deprecated since 2.3.0)	No	No	Yes if FI @Operation or property setter	No	No

Tooling

Add this maven dependency:

<groupId>com.prosyst.mbs.fim</groupId>

<artifactId>com.prosyst.mbs.fim.validator</artifactId>

<scope>compile</scope>

</dependency>

It will validate your annotations. For more information refer to FIM Annotations Validator.

Functional Item Interface Guidelines

Item Interface

Always start with @Item annotation. This annotation marks that the interface will be used by FIM.
Be careful about the default Item name! It's the qualified name. Usually, you need a readable name. For example: @Name("Binary Switch") instead of com.prosyst.mbs.demo.fim.BinarySwitch.
Set a version, because the default one is "0.0.0". An example: @Version("1.5.0").
On the last position, put the description. Actually, the order is not mandatory, but it's more readable and the description can take up some extra space.
It is recommended for each functional item interface to extend the FunctionalItem interface and define its supported properties and operations. If it doesn't extend the FunctionalItem, it will be a responsibility for its implementations and will cause additional java object type-casting.
@Item
@Name("Binary Switch")
@Version("1.5.0")
@Description("Provides support for binary switches control.")
public interface BinarySwitch extends FunctionalItem {

Property Constant

Don't specify the default access i.e. "RE".
Set the property type, if the property access is "E". In this case, the type cannot be automatically detected from the property getter/setter method.
Use @Numeric is there are min, max and/or step numeric values (there are default values for the skipped ones). This annotation could be skipped for a numeric java type if it has the default min and max.
If the property values can be enumerated, but Java Enum is not used, @Enum annotation is our friend. Note, that the set of values must be predefined and custom values are not allowed.
Boolean properties could be annotated with @Enum annotation.
On the last position, put the description. Actually, the order is not mandatory, but it's more readable and the description can take some space.
Use @Getter and/or @Setter annotations, if you getter and/or setter doesn't follow "get/set" rule. The full rule definition is available in the javadoc.
@Property
@Enum({
@EnumConst(name = "Low Battery", value = "true"), @EnumConst(name = "No Low Battery", value = "false")
})
@Description("Indicates if the battery is low. Value true denotes low battery.")
public static final String PROPERTY_LOW_BATTERY = "lowBattery";

@Property(access = "E", type = Alarm.class)
@Description("Alarm sensor event.")
public static final String PROPERTY_ALARM = "alarm";

Operation Method

Annotate the operations with @Operation. If you operation method is not annotated, it's for a local usage and will not be visible as FI operation.
There is no return value annotation. Use the method annotations instead.
Annotate the operation arguments: @Numeric, @Enum, @Description, etc. See the full list in the table.
@Operation
@Description("Changes the current color with new target HSB.")
public void changeHsb(
    @Description("Target HSB color.") HSB hsb,
    @Numeric(min = "0")
    @Description("The time for which the color is changing. The minimum value of transition time is 0.") long transitionTime)
    throws HomeDeviceException;

Bean

Use @Constructor, if the constructor doesn't use unique type combination. Unique means no duplicated argument types.
The bean fields are gathered from all the methods explicitly annotated with @Getter or the ones starting with get. Use @Ignore, if there is a method starting with get and it should not be a bean field getter method.
The bean getters can be annotation with the FI property annotation like: Numeric, @Description, etc. see the full list in the table.
You don't need to annotate the bean class, because the bean used as property, operation result or argument and it's annotated there.
You don't need to use empty constructor and setters any more.
@Constructor({
"name", "age"
})
public MemberBean(String name, int age) {