001/* 002 * BioJava development code 003 * 004 * This code may be freely distributed and modified under the 005 * terms of the GNU Lesser General Public Licence. This should 006 * be distributed with the code. If you do not have a copy, 007 * see: 008 * 009 * http://www.gnu.org/copyleft/lesser.html 010 * 011 * Copyright for this code is held jointly by the individual 012 * authors. These should be listed in @author doc comments. 013 * 014 * For more information on the BioJava project and its aims, 015 * or to join the biojava-l mailing list, visit the home page 016 * at: 017 * 018 * http://www.biojava.org/ 019 * 020 */ 021 022 023package org.biojava.nbio.ontology.utils; 024 025 026 027/** 028 * <p>Indicates that an object has an associated annotation.</p> 029 * 030 * <p>Many BioJava objects will have associated unstructured 031 * data. This should be stored in an Annotation instance. However, the 032 * BioJava object itself will probably not want to extend the 033 * Annotation interface directly, but rather delegate off that 034 * functionality to an Annotation property. The Annotatable interface 035 * indicates that there is an Annotation property. When implementing 036 * Annotatable, you should always create a protected or private field 037 * containing an instance of ChangeForwarder, and register it as a 038 * ChangeListener with the associated Annotation delegate 039 * instance.</p> 040 * 041 * <pre> 042 * public class Foo extends AbstractChangeable implements Annotatable { 043 * private Annotation ann; // the associated annotation delegate 044 * protected ChangeForwarder annFor; // the event forwarder 045 * 046 * public Foo() { 047 * // make the ann delegate 048 * ann = new SimpleAnnotation(); 049 * // construct the forwarder so that it emits Annotatable.ANNOTATION ChangeEvents 050 * // for the Annotation.PROPERTY events it will listen for 051 * annFor = new ChangeForwarder.Retyper(this, getChangesupport( Annotatable.ANNOTATION ), 052 * Annotatable.ANNOTATION ); 053 * // connect the forwarder so it listens for Annotation.PROPERTY events 054 * ann.addChangeListener( annFor, Annotation.PROPERTY ); 055 * } 056 * 057 * public Annotation getAnnotation() { 058 * return ann; 059 * } 060 * } 061 * </pre> 062 * Check if BioJava classes and interfaces extend Annotatable. This 063 * will tell you if you should look for associated annotation. 064 * 065 * If an object implements Annotatable, it may well propagate 066 * ChangeEvent notifications from the associated Annotation. You may 067 * need to track these to maintain the state of your applications. 068 * 069 * Be careful to hook up the appropriate event forwarders. 070 * 071 * The getAnnotation() method can be implemented lazily 072 * (instantiate the Annotation instance and event forwarders when the first 073 * request comes in). It can also be implemented by returning throw-away 074 * immutable Annotation instances that are built from scratch each time. 075 * @author Matthew Pocock 076 * @author <a href="mailto:kdj@sanger.ac.uk">Keith James</a> (docs). 077 * @author Kalle Näslund (docs) 078 * @see org.biojavax.RichAnnotatable 079 * @since 1.0 080 */ 081public interface Annotatable { 082 083 084 /** 085 * Should return the associated annotation object. 086 * 087 * @return an Annotation object, never null 088 */ 089 Annotation getAnnotation(); 090 091 092}