External annotation files

External annotations are specified in XML files, outside of the source code.

When you generate the external library files, pure function annotations can be automatically created in the resources/extannotations folder. You can have one external annotation file per package.

You can copy an external annotation file into the reference folder of the library to edit it, or create a new external annotation file in this same folder.

External annotation file format

External annotation files contain a <root> element and at least one <item> element, as shown in the following example:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item name="org.apache.commons.math3.complex.Complex org.apache.commons.math3.complex.ComplexField getField()">
    <annotation name="ilog.rules.bom.annotations.NotBusiness"/>
  </item>
</root>

<item> element

The <item> element can represent a class, a class member (field, method, or constructor), or a parameter. It contains a name attribute.

The following table describes the format to use for each type of item:

Item type name format and example
Class name="<class name>"

The class name is the name of the class as returned by Class.getName(). The separator for a nested class is $.

For example:

<item name="stuff.Customer">
Field name="<class name> <canonical name of the field type> <field name>"

The canonical name of a class is the name of the class as returned by Class.getCanonicalName(). The separator for a nested class is ..

For example:

<item name="stuff.Customer java.lang.String name">
Constructor name="<class name> <short class name>(<canonical name of the parameter types>)"

The short class name is the class name without the namespace.

Each parameter type is separated by a comma and a space (', ').

For example:

<item name="stuff.Customer Customer(java.lang.String)">
Method name="<class name> <method return type> <method name>(<canonical name of the parameter types>)"

Each parameter type is separated by a comma and a space (', ').

For example:

<item name="stuff.Customer void addAge(int, java.lang.String)">
Constructor parameter name="<constructor information> <number of parameters>"

For example:

<item name="stuff.Customer Customer(java.lang.String) 0">
Method parameter name="<method information> <number of parameters>"

For example:

<item name="stuff.Customer void addAge(int,java.lang.String) 1">

<annotation> element

The <annotation> element represents an annotation. It contains a name attribute. The value of the name attribute is the canonical name of the annotation type.

You can define annotations without parameters (or that use default parameters), annotations with parameters, and nested annotations.
Annotation type Example Comments
Annotation without parameters <annotation name="ilog.rules.bom.annotations.NotBusiness"/>  
Annotation with parameters 
<annotation name='ilog.rules.bom.annotations.BoundedIntDomain'>
  <val name="min" val="0"/>
  <val name="max" val="32"/>
</annotation>

Each <val> element represents a parameter.

The name attribute specifies the name of the parameter. This attribute is optional if the parameter name is value.
Nested annotation 
<annotation name="ilog.rules.bom.annotations.VocabularyLabels">
  <val>
    <annotation name='ilog.rules.bom.annotations.VocabularyLabel'>
      <val val="le vv"/>
      <val name="locale" val="fr"/>
    </annotation>
    <annotation name='ilog.rules.bom.annotations.VocabularyLabel'>
      <val val="the vv"/>
      <val name="locale" val="en"/>
    </annotation>
  </val>
</annotation>
 The <val> parent element contains a list of <annotation> elements.