A set of constraints on the data contained in an Annotation. AnnotationType instances can be used to validate an Annotation to check that it has the appropriate properties and that they are of the right type.

Common Usage

 // annType is going to define ID as being a single String and
 // AC as being a list of Strings and accept any other properties at all
 AnnotationType annType = new AnnotationType.Impl();
 annType.setDefaultConstraints(PropertyConstraint.ANY, Cardinality.ANY)
 annType.setConstraints("ID",
                        new PropertyConstraint.ByClass(String.class),
                        CardinalityConstraint.ONE );
 annType.setConstraint("AC",
                       new PropertyConstraint.ByClass(String.class),
                       CardinalityConstraint.ANY );

 Annotation ann = ...;

 if(annType.accepts(ann)) {
   // we have proved that ann contains one ID property that is a String
   System.out.println("ID: " + (String) ann.getProperty("ID"));
   // we know that the AC property is potentialy more than one String -
   // let's use getProperty on AnnotationType to make sure that the
   // values get unpacked cleanly
   System.out.println("AC:");
   for(Iterator i = annType.getProperty(ann, "AC"); i.hasNext(); ) {
     System.out.println("\t" + (String) i.next());
   }
 } else {
   throw new IllegalArgumentException(
     "Expecting an annotation conforming to: "
     annType + " but got: " + ann
   );
 }
 

Description

AnnotationType is a constraint-based language for describing sets of Annotation bundles. It works by assuming that any given Annotation may have any set of properties defined. If it matches a particular AnnotationType instance, then each defined property must be of a value that is acceptable to the type, and each undefined property must be allowed to be absend in the type.

AnnotationType imposes a data model on Annotations where the value of each `slot' is considered as a Collection. Values which aren't actually Collection instances are treated as singleton sets. Undefined properties are treated as Collection.EMPTY_SET. The logic to validate a complete slot in an Annotation is encapsulated by a CollectionConstraint object. In the common case, slots are validated by CollectionConstraint.AllValuesIn which ensures that all members of the collection match a specified PropertyConstraint, and that the size of the collection matches a cardinality constraint. This is the most important type of constraint when defining datatypes. However, when using AnnotationTypes to specify a query over a set of Annotations, it may be more useful to ask whether a slot contains a given value: For example

 // Test that gene_name contains the value "BRCA2", ignoring other values (synonyms)
 // which might be present in that slot.
 AnnotationType at = new AnnotationType.Impl();
 at.setConstraint(
      "gene_name",
      new CollectionConstraint.Contains(
          new PropertyConstraint.ExactValue("BRCA2"),
          CardinalityConstraint.ONE
      )
 );
 

It is usually left up to the AnnotationType instance to work out how multiple values should be packed into a single property slot in an Annotation instance. Commonly, things that are allowed a cardinality of 1 will store one value directly in the slot. Things that allow multiple values (and optionaly things with one value) will usualy store them within a Collection in the slot. This complexity is hidden from you if you use the accessor methods built into AnnotationType, setProperty(), addProperty(), removeProperty() and getProperty().

Using AnnotationType instances that you have been provided with e.g. from UnigeneTools.LIBRARY_ANNOTATION AnnotationType instances can be used as queries to select from a set of Annotations based on the value of one or more properties. Commonly, this is used in conjunction with FeatureFilter.ByAnnotationType. Make AnnotationType instances that describe what should and should not appear in an Annotation bundle Constrain FeatureFilter schemas by Annotation associated with the features Provide meta-data to the tag-value parser for automatically generating object representations of flat-files Implementing your own AnnotationType implementations to reflect frame, schema or ontology definitions. For example, dynamically reflect an RDMBS schema or DAML/Oil deffinition as an AnnotationType.