1   /*
2    *  Copyright (c) 1998-2004, The University of Sheffield.
3    *
4    *  This file is part of GATE (see http://gate.ac.uk/), and is free
5    *  software, licenced under the GNU Library General Public License,
6    *  Version 2, June 1991 (in the distribution as file licence.html,
7    *  and also available at http://gate.ac.uk/gate/licence.html).
8    *
9    *  Valentin Tablan, 01 Feb 2000
10   *
11   *  $Id: Transducer.java,v 1.26 2004/07/21 17:10:03 akshay Exp $
12   */
13  
14  package gate.creole;
15  
16  import gate.Resource;
17  import gate.jape.Batch;
18  import gate.jape.JapeException;
19  
20  /**
21   * A cascaded multi-phase transducer using the Jape language which is a
22   * variant of the CPSL language.
23   */
24  public class Transducer extends AbstractLanguageAnalyser {
25  
26    public static final String
27      TRANSD_DOCUMENT_PARAMETER_NAME = "document";
28  
29    public static final String
30      TRANSD_INPUT_AS_PARAMETER_NAME = "inputASName";
31  
32    public static final String
33      TRANSD_OUTPUT_AS_PARAMETER_NAME = "outputASName";
34  
35    public static final String
36      TRANSD_ENCODING_PARAMETER_NAME = "encoding";
37  
38    public static final String
39      TRANSD_GRAMMAR_URL_PARAMETER_NAME = "grammarURL";
40  
41    /**
42     * Default constructor. Does nothing apart from calling the default
43     * constructor from the super class. The actual object initialisation is done
44     * via the {@link #init} method.
45     */
46    public Transducer() {
47    }
48  
49    /*
50    private void writeObject(ObjectOutputStream oos) throws IOException {
51      Out.prln("writing transducer");
52      oos.defaultWriteObject();
53      Out.prln("finished writing transducer");
54    } // writeObject
55    */
56  
57    /**
58     * This method is the one responsible for initialising the transducer. It
59     * assumes that all the needed parameters have been already set using the
60     * appropiate setXXX() methods.
61     *@return a reference to <b>this</b>
62     */
63    public Resource init() throws ResourceInstantiationException {
64      if(grammarURL != null && encoding != null){
65        try{
66          fireProgressChanged(0);
67          batch = new Batch(grammarURL, encoding, new InternalStatusListener());
68          if(enableDebugging != null) {
69            batch.setEnableDebugging(enableDebugging.booleanValue());
70          } else {
71            batch.setEnableDebugging(false);
72          }
73          batch.setOntology(ontology);
74          fireProcessFinished();
75        }catch(Exception e){
76          throw new ResourceInstantiationException(e);
77        }
78      } else
79        throw new ResourceInstantiationException (
80          "Both the URL (was " + grammarURL + ") and the encoding (was " +
81          encoding + ") are needed to create a JapeTransducer!"
82        );
83  
84        batch.addProgressListener(new IntervalProgressListener(0, 100));
85  
86      return this;
87    }
88  
89    /**
90     * Implementation of the run() method from {@link java.lang.Runnable}.
91     * This method is responsible for doing all the processing of the input
92     * document.
93     */
94    public void execute() throws ExecutionException{
95      interrupted = false;
96      if(document == null) throw new ExecutionException("No document provided!");
97      if(inputASName != null && inputASName.equals("")) inputASName = null;
98      if(outputASName != null && outputASName.equals("")) outputASName = null;
99      try{
100       batch.transduce(document,
101                       inputASName == null ?
102                         document.getAnnotations() :
103                         document.getAnnotations(inputASName),
104                       outputASName == null ?
105                         document.getAnnotations() :
106                         document.getAnnotations(outputASName));
107     }catch(JapeException je){
108       throw new ExecutionException(je);
109     }
110   }
111 
112 
113   /**
114    * Notifies all the PRs in this controller that they should stop their
115    * execution as soon as possible.
116    */
117   public synchronized void interrupt(){
118     interrupted = true;
119     batch.interrupt();
120   }
121   /**
122    * Sets the grammar to be used for building this transducer.
123    * @param newGrammarURL an URL to a file containing a Jape grammar.
124    */
125   public void setGrammarURL(java.net.URL newGrammarURL) {
126     grammarURL = newGrammarURL;
127   }
128 
129   /**
130    * Gets the URL to the grammar used to build this transducer.
131    * @return a {@link java.net.URL} pointing to the grammar file.
132    */
133   public java.net.URL getGrammarURL() {
134     return grammarURL;
135   }
136 
137   /**
138    *
139    * Sets the encoding to be used for reding the input file(s) forming the Jape
140    * grammar. Note that if the input grammar is a multi-file one than the same
141    * encoding will be used for reding all the files. Multi file grammars with
142    * different encoding across the composing files are not supported!
143    * @param newEncoding a {link String} representing the encoding.
144    */
145   public void setEncoding(String newEncoding) {
146     encoding = newEncoding;
147   }
148 
149   /**
150    * Gets the encoding used for reding the grammar file(s).
151    */
152   public String getEncoding() {
153     return encoding;
154   }
155 
156   /**
157    * Sets the {@link gate.AnnotationSet} to be used as input for the transducer.
158    * @param newInputASName a {@link gate.AnnotationSet}
159    */
160   public void setInputASName(String newInputASName) {
161     inputASName = newInputASName;
162   }
163 
164   /**
165    * Gets the {@link gate.AnnotationSet} used as input by this transducer.
166    * @return a {@link gate.AnnotationSet}
167    */
168   public String getInputASName() {
169     return inputASName;
170   }
171 
172   /**
173    * Sets the {@link gate.AnnotationSet} to be used as output by the transducer.
174    * @param newOutputASName a {@link gate.AnnotationSet}
175    */
176   public void setOutputASName(String newOutputASName) {
177     outputASName = newOutputASName;
178   }
179 
180   /**
181    * Gets the {@link gate.AnnotationSet} used as output by this transducer.
182    * @return a {@link gate.AnnotationSet}
183    */
184   public String getOutputASName() {
185     return outputASName;
186   }
187 
188   public Boolean getEnableDebugging() {
189     return enableDebugging;
190   }
191 
192   public void setEnableDebugging(Boolean enableDebugging) {
193     this.enableDebugging = enableDebugging;
194   }
195 
196   /**
197    * The URL to the jape file used as grammar by this transducer.
198    */
199   private java.net.URL grammarURL;
200 
201 
202   /**
203    * The actual JapeTransducer used for processing the document(s).
204    */
205   protected Batch batch;
206 
207   /**
208    * The encoding used for reding the grammar file(s).
209    */
210   private String encoding;
211 
212   /**
213    * The {@link gate.AnnotationSet} used as input for the transducer.
214    */
215   private String inputASName;
216 
217   /**
218    * The {@link gate.AnnotationSet} used as output by the transducer.
219    */
220   private String outputASName;
221 
222   /**
223    * The ontology that will be available on the RHS of JAPE rules.
224    */
225   private gate.creole.ontology.Ontology ontology;
226 
227   /**
228    * Gets the ontology used by this transducer.
229    * @return an {@link gate.creole.ontology.Ontology} value.
230    */
231   public gate.creole.ontology.Ontology getOntology() {
232     return ontology;
233   }
234 
235   /**
236    * Sets the ontology used by this transducer.
237    * @param ontology an {@link gate.creole.ontology.Ontology} value.
238    */
239   public void setOntology(gate.creole.ontology.Ontology ontology) {
240     this.ontology = ontology;
241   }
242   
243   
244   /**
245    * A switch used to activate the JAPE debugger.
246    */
247   private Boolean enableDebugging;
248 }