01 /*
02 * Copyright (c) 1995-2010, 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 12456 2010-04-08 15:11:28Z 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
22 * cannot be duplicated in the standard way (see
23 * {@link Factory#duplicate(Resource) Factory.duplicate}). If a Resource
24 * class requires custom duplication logic it should implement this
25 * interface and provide an implementation of the
26 * {@link #duplicate(Resource) duplicate} method to create a new
27 * resource instance that has the same behaviour as <code>this</code>.
28 *
29 * @author ian
30 */
31 public interface CustomDuplication {
32
33 /**
34 * <p>
35 * Create a <i>duplicate</i> of this resource. The object returned
36 * need not be of the same concrete class as <code>this</code>, but
37 * should behave the same and implement the same set of GATE core
38 * interfaces, i.e. if <code>this</code> implements
39 * {@link gate.ProcessingResource} then the duplicate should also
40 * implement {@link gate.ProcessingResource}, if <code>this</code>
41 * implements {@link gate.LanguageAnalyser} then the duplicate should
42 * also implement {@link gate.LanguageAnalyser}, etc.
43 * </p>
44 * <p>
45 * Typical uses for resource duplication are multi-threaded
46 * applications that require a number of identical resources for
47 * concurrent use in different threads. Therefore it is important that
48 * duplicates created by this method should be safe for concurrent use
49 * in multiple threads - in some cases it may be appropriate for the
50 * duplicate to share some state with the original object, but this
51 * must be handled in a thread-safe manner.
52 * </p>
53 * <p>
54 * Implementors of this interface should <i>not</i> use covariant
55 * return types, as to do so may limit the flexibility of subclasses
56 * to implement duplication in the most efficient manner.
57 * </p>
58 * <p>
59 * <b>NOTE</b> this method cannot be called directly, use
60 * {@link Factory#duplicate(Resource)} instead.
61 * </p>
62 *
63 * @param ctx the current {@link DuplicationContext duplication context}.
64 * If an implementation of this method needs to duplicate any
65 * other resources as part of the custom duplication process
66 * it should pass this context back to the two-argument form of
67 * {@link Factory#duplicate(Resource, DuplicationContext) Factory.duplicate}
68 * rather than using the single-argument form.
69 * @return an independent copy of this resource.
70 * @throws ResourceInstantiationException
71 */
72 public Resource duplicate(DuplicationContext ctx)
73 throws ResourceInstantiationException;
74 }
|