## Package org.biojava.bio

The core classes that will be used throughout the bio packages.

See:
Description

Interface Summary
Annotatable: Indicates that an object has an associated annotation.
Annotation: Arbitrary annotation associated with one or more objects.
AnnotationType: A set of constraints on the data contained in an `Annotation`.
CollectionConstraint: Used by `AnnotationType` to represent the constraint on the collection of values in a property-slot.
EcNumber: An ec (enzyme classification) number.
PropertyConstraint: `PropertyConstraint`s describes a constraint applied to the members of an annotation bundle.

Class Summary
AbstractAnnotation: A utility class to ease the problem of implementing an Annotation to that of providing an apropreate implementation of Map.
Annotatable.AnnotationForwarder: Deprecated. use `new ChangeForwarder.Retyper(source, cs, Annotation.PROPERTY)` instead
AnnotationChanger: `AnnotationChanger` remaps the values of an `Annotation` to new values specified by a `ValueChanger`.
AnnotationRenamer: `AnnotationRenamer` remaps the keys of an `Annotation` to new keys specified by a `TagMapper`.
AnnotationTools: `AnnotationTools` is a set of static utility methods for manipulating `Annotation`s and `AnnotationType`s.
AnnotationType.Abstract: An abstract base class useful for implementing AnnotationType instances.
AnnotationType.Impl: An implementation of `AnnotationType`.
BeanAsAnnotation: Create an Annotation with properties matching those of a JavaBean instance.
CardinalityConstraint: A constraint on the number of values a property can have.
CollectionConstraint.AllValuesIn: CollectionConstraint which validates all members of a Collection.
CollectionConstraint.And: A collection constraint that accpepts collections iff they are accepted by both child constraints.
CollectionConstraint.Contains: CollectionConstraint which validates a portion of a Collection.
CollectionConstraint.Or: A collection constraint that accepts items iff they are accepted by either child constraints.
EcNumber.Impl: A simple implementation of EcNumber.
MergeAnnotation: Merged view onto a list of underlying Annotation objects.
OverlayAnnotation: Annotation implementation which allows new key-value pairs to be layered on top of an underlying Annotation.
PropertyConstraint.And: A property constraint that accpepts items iff they are accepted by both child constraints.
PropertyConstraint.ByAnnotationType: `ByAnnotationType` accepts a property value if it belongs to type defined by AnnotationType.
PropertyConstraint.ByClass: `ByClass` accepts a property value if it is an instance of a specific Java class.
PropertyConstraint.Enumeration: `Enumeration` accepts a property if it is present in the specified set of values.
PropertyConstraint.ExactValue: Matches properties if they have exactly this one value.
PropertyConstraint.Or: A property constraint that accepts items iff they are accepted by either child constraints.
SimpleAnnotation: A no-frills implementation of Annotation that is just a wrapper around a `LinkedHashMap`.
SmallAnnotation: Annotation that is optimized for memory usage.

Exception Summary
BioException: A nestable biological exception.
BioRuntimeException: A nestable biological exception.

Error Summary
BioError: A nestable biological error.

## Package org.biojava.bio Description

The core classes that will be used throughout the bio packages.

## Throwables

The classes BioException and BioError form the basis of error-handling within the core classes. They both can optionally wrap a source Throwable and carry a message. The stack-trace printed should contain a single merged stack-trace, together with all messages inserted in the proper places. These exceptions can be nested to any depth, providing an organic and natural way to trace errors and bugs.

## Annotations

The Annotation classes are used throughout the org.biojava.bio interface hierachy to indicate that there is un-typed information that may optionally be associated with an object. The Annotation object takes the form of a paranoid Map, and Annotatable flags an object as having an associated Annotation object.

Annotations would be used where the designer of an API knew that users may wish to associate further information with instances of an interface or class, but it is inapropreate to add get/set pairs and properties, either because the properties will frequently be absent, or the names and types of the properties will not be known untill objects are populated.

To help bring some order to this potential chaos, there is a loose-typing system available. AnnotationType defines an instanceOf method that will return true if an annotation is considered to be an instance of that type, and false otherwise. In practice, this choice will tend to be made on the basis of the available annotation properties, their names and values. PropertyConstraint allows restrictions on the range of property values to be bound to names within a PropertyType. These may restrict a property to being of a particular java class, within a set of possible values (enumerated type), being an annotation of a particular AnnotationType, or being a collection of one of these (set, list).

It is not expected that in the general case Annotations will publish an AnnotationType they conform to in a well-known slot such as ISA. In the general case, annotations will be dynamicaly validated by calling AnnotatoinType.instanceOf(Annotation). Annotations are symultaneously instances of all AnnotationType instances that they match to. In particular, all Annotation instances are of type AnnotationType.ANY which places no restrictions upon the presence or value of properties.

AnnotationType and PropopertyConstraint both have operators to check if another instance matches a subset of the items it matches. These are subTypeOf and subConstraintOf respectively. In the same way that the type of an Annotation is inferred as needed, these relationships will in general be proved when required. It is not likely that AnnotatoinType or PropertyConstraint instances will maintain references between super- and sub-types, but rather they will introspect the class and properties of the type or constraints and prove that the sub-type instanceOf method returns true for a subset of the cases returning true for the super-type.

This typing system is able to validate the type of an annotation by the names and types of its properties. It is unable to (and it is outside the scope of this API to attempt to) validate the type of an annotation by other annotations or objects that may refer to it. We only validate part-whole hierachies.