org.biojava.bio
Class AnnotationTools

java.lang.Object
  extended by org.biojava.bio.AnnotationTools

public final class AnnotationTools
extends java.lang.Object

AnnotationTools is a set of static utility methods for manipulating Annotations and AnnotationTypes.

The methods allIn() and allOut() let you compare an Annotation to an AnnotationType and produce a new Annotation with only those properties explicitly constrained by or not constrained by the type. This could be of use when using an Annotation as a template for some object. You could use allOut to make an Annotation that has all the properties that do not fit into normal constructor properties, and pass that in as the Annotation bundle.

intersection(AnnotationType) and union(AnnotationType) return new AnnotationType instances that will accept every Annotation instance that is accepted by both or either respectively. It is particularly informative to compare the result of this to the AnnotationType.NONE to see if the two types are mutualy disjoint.

intersection(PropertyConstraint) and union(PropertyConstraint) return new PropertyConstraint instances that will accept every Object that is accepted by both or either one respectively.

Since:
1.3
Author:
Matthew Pocock, Keith James (docs), Thomas Down
For advanced users:
Comparing types and annotations. For example, FilterTools uses these methods when comparing filters on features by their Annotation bundles.

Constructor Summary
AnnotationTools()
           
 
Method Summary
static Annotation allIn(Annotation annotation, AnnotationType annType)
           Destructive down-cast an annotation to a type.
static Annotation allOut(Annotation annotation, AnnotationType annType)
          allOut returns a new Annotation containing only those values in the Annotation argument which are not of a type specified by the AnnotationType.
static AnnotationType intersection(AnnotationType ann1, AnnotationType ann2)
          Calculate an AnnotationType that matches all Annotation instances matched by both types.
static CollectionConstraint intersection(CollectionConstraint cc1, CollectionConstraint cc2)
          Return the CollectionConstraint which accept only collections accepted by both of those specified.
static PropertyConstraint intersection(PropertyConstraint pc1, PropertyConstraint pc2)
          Calculate the intersection of two PropertyConstraint instances.
static java.util.Set searchAnnotation(Annotation ann, AnnotationType query)
           Scans an Annotation with an AnnotationType and returns all Annotation instances matching a Type.
static AnnotationType union(AnnotationType ann1, AnnotationType ann2)
          Create an AnnotationType that matches all Anntotations that are accepted by two others.
static CollectionConstraint union(CollectionConstraint cc1, CollectionConstraint cc2)
          Calculate a CollectionConstaint that will accept all items accepted by either constraint.
static PropertyConstraint union(PropertyConstraint pc1, PropertyConstraint pc2)
          Create a PropertyConstraint that matches all Objects that are accepted by two others.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AnnotationTools

public AnnotationTools()
Method Detail

allIn

public static Annotation allIn(Annotation annotation,
                               AnnotationType annType)

Destructive down-cast an annotation to a type.

allIn returns a new Annotation containing only those values in the Annotation argument which are of a type specified by the AnnotationType.

Parameters:
annotation - an Annotation to scan.
annType - an AnnotationType.
Returns:
an Annotation.
For advanced users:
When disecting an Annotation

allOut

public static Annotation allOut(Annotation annotation,
                                AnnotationType annType)
allOut returns a new Annotation containing only those values in the Annotation argument which are not of a type specified by the AnnotationType.

Parameters:
annotation - an Annotation.
annType - an AnnotationType.
Returns:
an Annotation value.
For advanced users:
When disecting an Annotation

searchAnnotation

public static java.util.Set searchAnnotation(Annotation ann,
                                             AnnotationType query)

Scans an Annotation with an AnnotationType and returns all Annotation instances matching a Type.

This differs from AnnotationType.instanceOf() as it will descend into properties of an Annotation if that property is itself an Annotation. This allows you to scan a tree of Annotations for nodes in the tree of a particular shape.

Parameters:
ann - the Annotation to scan
query - the AnnotationType to match against all nodes in the tree
Returns:
the set of all annotations matching the query
For general use:
when trying to find interesting bits of data presented as Annotations.
For developers:
as a fall-through implementation of AnnotationDB.search()

intersection

public static AnnotationType intersection(AnnotationType ann1,
                                          AnnotationType ann2)
Calculate an AnnotationType that matches all Annotation instances matched by both types.

Parameters:
ann1 - the first AnnotationType
ann2 - the seccond AnnotationType
Returns:
the intersection AnnotationType
For advanced users:
Usually you will either use this value blind or compare it to AnnotationType.NONE.

intersection

public static PropertyConstraint intersection(PropertyConstraint pc1,
                                              PropertyConstraint pc2)
Calculate the intersection of two PropertyConstraint instances.

Parameters:
pc1 - the first PropertyConstraint
pc2 - the seccond PropertyConstraint
Returns:
the intersection PropertyConstraint
For advanced users:
This method is realy only interesting when comparing each property in an AnnotationType in turn. Usually the return value is either compared to PropertyConstraint.NONE or is used blindly.

union

public static AnnotationType union(AnnotationType ann1,
                                   AnnotationType ann2)
Create an AnnotationType that matches all Anntotations that are accepted by two others.

Parameters:
ann1 - the first AnnotationType
ann2 - the seccond AnnotationType
Returns:
an AnnotationType that represents their unions
For advanced users:
This method is realy not very usefull in most cases. You may wish to compare the result of this to AnnotationType.ANY, or use it blindly.

union

public static PropertyConstraint union(PropertyConstraint pc1,
                                       PropertyConstraint pc2)
Create a PropertyConstraint that matches all Objects that are accepted by two others.

Parameters:
pc1 - the first PropertyConstraint
pc2 - the second PropertyConstraint
Returns:
the union PropertyConstraint
For advanced users:
In the general case, there is no clean way to represent the union of two PropertyConstraint instances. You may get back a PropertyConstraint.Or instance, or perhaps PropertyConstraint.ANY. Alternatively, there may be some comparrison possible. It is a thankless task introspecting this in code. You have been warned.

intersection

public static CollectionConstraint intersection(CollectionConstraint cc1,
                                                CollectionConstraint cc2)
Return the CollectionConstraint which accept only collections accepted by both of those specified.

Parameters:
cc1 - the first CollectionConstraint
cc2 - the seccond CollectionConstrant
Returns:
a CollectionConstraint representing the intersection of the other two

union

public static CollectionConstraint union(CollectionConstraint cc1,
                                         CollectionConstraint cc2)
Calculate a CollectionConstaint that will accept all items accepted by either constraint.

Parameters:
cc1 - the first CollectionConstraint
cc2 - the seccond collectionConstraint
Returns:
a CollectionConstraint representing the union of the other two