Sharable.java
01 /*
02  *  Optional.java
03  *
04  *  Copyright (c) 2011, The University of Sheffield.
05  *
06  *  This file is part of GATE (see http://gate.ac.uk/), and is free
07  *  software, licenced under the GNU Library General Public License,
08  *  Version 2, June 1991 (in the distribution as file licence.html,
09  *  and also available at http://gate.ac.uk/gate/licence.html).
10  *
11  *  Ian Roberts, 29/Jun/2011
12  *
13  *  $Id: Sharable.java 14240 2011-08-12 09:46:14Z ian_roberts $
14  */
15 package gate.creole.metadata;
16 
17 import gate.Factory;
18 
19 import java.lang.annotation.Documented;
20 import java.lang.annotation.ElementType;
21 import java.lang.annotation.Retention;
22 import java.lang.annotation.RetentionPolicy;
23 import java.lang.annotation.Target;
24 
25 
26 /**
27  <p>Marker interface used to mark the setter methods of JavaBean
28  * properties that are <i>sharable</i>.  When a resource is
29  * duplicated using {@link Factory#duplicate(gate.Resource)}
30  * the values of any sharable properties from the original
31  * resource will be copied by reference into the duplicate.
32  * In particular, and sharable properties that are themselves
33  * resources will <i>not</i> be recursively duplicated, even
34  * if the properties are also marked as {@link CreoleParameter}s.</p>
35  
36  <p>The Sharable marker is typically used for cases where a
37  * resource creates at initialization time a data structure which
38  * it subsequently accesses in a read-only fashion. Duplicates
39  * of this resource can share a reference to the original's copy
40  * of this data structure rather than having to build their
41  * own identical copy.</p>
42  
43  <p>The default {@link Factory#duplicate(gate.Resource)}
44  * implementation sets sharable properties at the same time as
45  * init parameters (i.e. after the constructor call but before
46  * init() is called).  So resources that make use of sharable
47  * properties need to check in their init() methods whether
48  * the sharable properties have been set, and only do the
49  * necessary initialization logic if the property values are
50  <code>null</code>.</p>
51  */
52 @Documented
53 @Target( {ElementType.METHOD})
54 @Retention(RetentionPolicy.RUNTIME)
55 public @interface Sharable {
56   /**
57    * Defaults to true but can be set to false to explicitly mark a property as
58    * not sharable when a superclass has marked it as sharable.
59    */
60   boolean value() default true;
61 }