CustomDuplication.java
01 /*
02  *  Copyright (c) 1995-2012, The University of Sheffield. See the file
03  *  COPYRIGHT.txt in the software or at http://gate.ac.uk/gate/COPYRIGHT.txt
04  *
05  *  This file is part of GATE (see http://gate.ac.uk/), and is free
06  *  software, licenced under the GNU Library General Public License,
07  *  Version 2, June 1991 (in the distribution as file licence.html,
08  *  and also available at http://gate.ac.uk/gate/licence.html).
09  *
10  *  Ian Roberts 23/03/2010
11  *
12  *  $Id: CustomDuplication.java 15333 2012-02-07 13:18:33Z ian_roberts $
13  */
14 package gate.creole;
15 
16 import gate.Resource;
17 import gate.Factory;
18 import gate.Factory.DuplicationContext;
19 
20 /**
21  * Interface which should be implemented by any Resource type which cannot be
22  * duplicated in the standard way (see {@link Factory#duplicate(Resource)
23  * Factory.duplicate}). If a Resource class requires custom duplication logic it
24  * should implement this interface and provide a method to create a new resource
25  * instance that has the same behaviour as <code>this</code>.
26  
27  @author ian
28  */
29 public interface CustomDuplication {
30 
31   /**
32    <p>
33    * Create a <i>duplicate</i> of this resource. The object returned
34    * need not be of the same concrete class as <code>this</code>, but
35    * should behave the same and implement the same set of GATE core
36    * interfaces, i.e. if <code>this</code> implements
37    {@link gate.ProcessingResource} then the duplicate should also
38    * implement {@link gate.ProcessingResource}, if <code>this</code>
39    * implements {@link gate.LanguageAnalyser} then the duplicate should
40    * also implement {@link gate.LanguageAnalyser}, etc.
41    </p>
42    <p>
43    * Typical uses for resource duplication are multi-threaded
44    * applications that require a number of identical resources for
45    * concurrent use in different threads. Therefore it is important that
46    * duplicates created by this method should be safe for concurrent use
47    * in multiple threads - in some cases it may be appropriate for the
48    * duplicate to share some state with the original object, but this
49    * must be handled in a thread-safe manner.
50    </p>
51    <p>
52    * Implementors of this interface should <i>not</i> use covariant
53    * return types, as to do so may limit the flexibility of subclasses
54    * to implement duplication in the most efficient manner.
55    </p>
56    <p>
57    <b>NOTE</b> this method cannot be called directly, use
58    {@link Factory#duplicate(Resource)} instead.
59    </p>
60    
61    @param ctx the current {@link DuplicationContext duplication context}.
62    *          If an implementation of this method needs to duplicate any
63    *          other resources as part of the custom duplication process
64    *          it should pass this context back to the two-argument form of
65    *          {@link Factory#duplicate(Resource, DuplicationContext) Factory.duplicate}
66    *          rather than using the single-argument form.
67    @return an independent copy of this resource.
68    @throws ResourceInstantiationException
69    */
70   public Resource duplicate(DuplicationContext ctx)
71           throws ResourceInstantiationException;
72 }