org.biojava.bio.package.html Maven / Gradle / Ivy
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.