View Javadoc

1   /***
2    * 
3    */
4   package org.astrogrid.desktop.modules.votech;
5   
6   import java.net.URI;
7   import java.util.Iterator;
8   
9   import org.astrogrid.acr.ivoa.resource.Resource;
10  import org.astrogrid.desktop.modules.util.Selftest;
11  
12  
13  
14  /*** A component that provides additional metadata (annotations) for resources from various sources.
15   * @author Noel.Winstanley@manchester.ac.uk
16   * @since Jun 18, 20077:21:46 PM
17   */
18  public interface AnnotationService extends Selftest {
19  
20  	// control annotation sources.
21  	/*** List the locations that annotation sources are being read from
22  	 * - this includes dynamic and static sources. */
23  	AnnotationSource[] listSources();
24  	
25  	/*** add a new annotation source to the list. 
26  	 * it's expected that this will be persisted so that
27  	 * it's permently added to the list of sources.
28  	 * 
29  	 * unused, and not fully implemented.
30  	 * @param nu
31  	 */
32  	void addSource(AnnotationSource nu);
33  	/*** remove the user annotation for a resource
34  	 * unused, and not fully implemented
35  	 *  */
36  	public void removeUserAnnotation(Resource r);	
37  	
38  	
39  	// editing annotations.
40  	
41  	/*** the source of user annotations  - useful for disinguishing them */
42  	AnnotationSource getUserAnnotationSource();
43  	/*** access the user annotation for this resource
44  	 * may return 'null' if no annotation available for this resource
45  	 */
46  	UserAnnotation getUserAnnotation(Resource r);
47  	UserAnnotation getUserAnnotation(URI resourceId);
48  	
49  	/*** set the annotation for a particular resource */
50  	void setUserAnnotation(Resource r, UserAnnotation ann);
51  	
52  	
53  	// query for annotations.
54  	
55  	/*** access annotations that are local.
56  	 * this is static sources, and dynamic sources that were previously queried,
57  	 * and their result cached.
58  	 * 
59  	 * A low cost operation.
60  	 */
61  	void processLocalAnnotations(final Resource r,AnnotationProcessor procesor);
62  	
63  	/*** an alternative to the annotationprocessor approach - returns the data directly as
64  	 * an iterator
65  	 * @param r
66  	 * @return an iterator of Annotatino objects
67  	 */
68  	Iterator getLocalAnnotations(Resource r);
69  	
70  	
71  	/*** access the remaining annotations - i.e. those from dynamic services
72  	 * that were not cached previously
73  	 * 
74  	 * as each remaining annotaiton is received, the processor will be passed the
75  	 * annotation and called. 
76  	 * 
77  	 * If no further results are returned, the closure is never called.
78  	 * 
79  	 * If some results are returned, these are will be cached, so that next time
80  	 * getLocalAnnotations will return them all.
81  	 *  */
82  	void processRemainingAnnotations(Resource r,AnnotationProcessor processor);
83  
84  	/*** a bulk operation - pass an array of resouces and process all remaining
85  	 * annotations for them.
86  	 * @param r
87  	 * @return a non-null array, whose elements will be as for {@link #getRemainingAnnotations(Resource)}
88  	 */
89  //	void processRemainingAnnotationsForAll(Resource[] r,ResourceAnnotationProcessor processor);
90  	
91  	/*** interface to a class that processes an annotation in some way */
92  	public interface AnnotationProcessor {
93  		void process(UserAnnotation a);
94  		void process(Annotation a);
95  	}
96  	/*** interface to a class that process an annotation (with resoufce specified) */
97  	public interface ResourceAnnotationProcessor {
98  		void process(Resource r, Annotation a);
99  	}
100 	
101 }