Filter


1   package net.sf.saxon;
2   import net.sf.saxon.event.ContentHandlerProxy;
3   import org.xml.sax.*;
4   import org.xml.sax.ext.LexicalHandler  ;
5   
6   import javax.xml.parsers.SAXParserFactory  ;
7   import javax.xml.transform.Transformer  ;
8   import javax.xml.transform.TransformerException  ;
9   import javax.xml.transform.sax.SAXSource  ;
10  import java.io.IOException  ;
11  
12  
13  
14  /**
15    * <B>Filter</B> is an XMLFilter (a SAX2 filter) that performs a transformation
16    * taking a SAX stream as input and producing a SAX stream as output.
17    * @author Michael H. Kay
18    */
19  
20  public class Filter implements XMLFilter {
21  
22      private Controller controller;
23      private XMLReader parser;
24      private ContentHandler contentHandler;      // destination for output of this filter
25      private LexicalHandler   lexicalHandler;      // destination for output of this filter
26  
27  
28  
29      /**
30      * Create a Filter and initialise variables. The constructor is protected, because
31      * the Filter should be created using newXMLFilter() in the SAXTransformerFactory
32      * class
33      */
34  
35      protected Filter(Controller controller) {
36          this.controller = controller;
37      }
38  
39  
40      //////////////////////////////////////////////////////////////////
41      // Implement XMLFilter interface methods
42      //////////////////////////////////////////////////////////////////
43  
44      /**
45      * Set the parent reader.
46      *
47      * <p>This method allows the application to link the filter to
48      * a parent reader (which may be another filter).  The argument
49      * may not be null.</p>
50      *
51      * @param parent The parent reader (the supplier of SAX events).
52      */
53  
54      public void setParent (XMLReader parent) {
55          parser = parent;
56      }
57  
58      /**
59      * Get the parent reader.
60      *
61      * <p>This method allows the application to query the parent
62      * reader (which may be another filter).  It is generally a
63      * bad idea to perform any operations on the parent reader
64      * directly: they should all pass through this filter.</p>
65      *
66      * @return The parent filter, or null if none has been set.
67      */
68  
69      public XMLReader getParent() {
70          return parser;
71      }
72  
73      ///////////////////////////////////////////////////////////////////
74      // implement XMLReader interface methods
75      ///////////////////////////////////////////////////////////////////
76  
77      /**
78       * Look up the value of a feature.
79       *
80       * <p>The feature name is any fully-qualified URI.  It is
81       * possible for an XMLReader to recognize a feature name but
82       * to be unable to return its value; this is especially true
83       * in the case of an adapter for a SAX1 Parser, which has
84       * no way of knowing whether the underlying parser is
85       * performing validation or expanding external entities.</p>
86       *
87       * <p>All XMLReaders are required to recognize the
88       * http://xml.org/sax/features/namespaces and the
89       * http://xml.org/sax/features/namespace-prefixes feature names.</p>
90       *
91       * @param name The feature name, which is a fully-qualified URI.
92       * @return The current state of the feature (true or false).
93       * @exception org.xml.sax.SAXNotRecognizedException When the
94       *            XMLReader does not recognize the feature name.
95       * @exception org.xml.sax.SAXNotSupportedException When the
96       *            XMLReader recognizes the feature name but
97       *            cannot determine its value at this time.
98       * @see #setFeature
99       */
100 
101     public boolean getFeature (String   name)
102         throws SAXNotRecognizedException, SAXNotSupportedException {
103         if (name.equals("http://xml.org/sax/features/namespaces")) {
104             return true;
105         } else if (name.equals("http://xml.org/sax/features/namespace-prefixes")) {
106             return false;
107         } else {
108             throw new SAXNotRecognizedException(name);
109         }
110     }
111 
112 
113     /**
114      * Set the state of a feature.
115      *
116      * <p>The feature name is any fully-qualified URI.  It is
117      * possible for an XMLReader to recognize a feature name but
118      * to be unable to set its value</p>
119      *
120      * <p>All XMLReaders are required to support setting
121      * http://xml.org/sax/features/namespaces to true and
122      * http://xml.org/sax/features/namespace-prefixes to false.</p>
123      *
124      * <p>Some feature values may be immutable or mutable only
125      * in specific contexts, such as before, during, or after
126      * a parse.</p>
127      *
128      * @param name The feature name, which is a fully-qualified URI.
129      * @param value The requested state of the feature (true or false).
130      * @exception org.xml.sax.SAXNotRecognizedException When the
131      *            XMLReader does not recognize the feature name.
132      * @exception org.xml.sax.SAXNotSupportedException When the
133      *            XMLReader recognizes the feature name but
134      *            cannot set the requested value.
135      * @see #getFeature
136      */
137 
138     public void setFeature (String   name, boolean value)
139     throws SAXNotRecognizedException, SAXNotSupportedException {
140         if (name.equals("http://xml.org/sax/features/namespaces")) {
141             if (!value) {
142                 throw new SAXNotSupportedException(name);
143             }
144         } else if (name.equals("http://xml.org/sax/features/namespace-prefixes")) {
145             if (value) {
146                 throw new SAXNotSupportedException(name);
147             }
148         } else {
149             throw new SAXNotRecognizedException(name);
150         }
151     }
152 
153     /**
154      * Look up the value of a property.
155      *
156      * <p>The property name is any fully-qualified URI.  It is
157      * possible for an XMLReader to recognize a property name but
158      * to be unable to return its state.</p>
159      *
160      * <p>XMLReaders are not required to recognize any specific
161      * property names, though an initial core set is documented for
162      * SAX2.</p>
163      *
164      * <p>Some property values may be available only in specific
165      * contexts, such as before, during, or after a parse.</p>
166      *
167      * <p>Implementors are free (and encouraged) to invent their own properties,
168      * using names built on their own URIs.</p>
169      *
170      * @param name The property name, which is a fully-qualified URI.
171      * @return The current value of the property.
172      * @exception org.xml.sax.SAXNotRecognizedException When the
173      *            XMLReader does not recognize the property name.
174      * @exception org.xml.sax.SAXNotSupportedException When the
175      *            XMLReader recognizes the property name but
176      *            cannot determine its value at this time.
177      * @see #setProperty
178      */
179 
180     public Object   getProperty (String   name)
181     throws SAXNotRecognizedException, SAXNotSupportedException {
182         if (name.equals("http://xml.org/sax/properties/lexical-handler")) {
183             return lexicalHandler;
184         } else {
185             throw new SAXNotRecognizedException(name);
186         }
187     }
188 
189 
190     /**
191      * Set the value of a property.
192      *
193      * <p>The property name is any fully-qualified URI.  It is
194      * possible for an XMLReader to recognize a property name but
195      * to be unable to set its value.</p>
196      *
197      * <p>XMLReaders are not required to recognize setting
198      * any specific property names, though a core set is provided with
199      * SAX2.</p>
200      *
201      * <p>Some property values may be immutable or mutable only
202      * in specific contexts, such as before, during, or after
203      * a parse.</p>
204      *
205      * <p>This method is also the standard mechanism for setting
206      * extended handlers.</p>
207      *
208      * @param name The property name, which is a fully-qualified URI.
209      * @param value The requested value for the property.
210      * @exception org.xml.sax.SAXNotRecognizedException When the
211      *            XMLReader does not recognize the property name.
212      * @exception org.xml.sax.SAXNotSupportedException When the
213      *            XMLReader recognizes the property name but
214      *            cannot set the requested value.
215      */
216 
217     public void setProperty (String   name, Object   value)
218     throws SAXNotRecognizedException, SAXNotSupportedException {
219         if (name.equals("http://xml.org/sax/properties/lexical-handler")) {
220             if (value instanceof LexicalHandler  ) {
221                 lexicalHandler = (LexicalHandler  )value;
222             } else {
223                 throw new SAXNotSupportedException(
224                     "Lexical Handler must be instance of org.xml.sax.ext.LexicalHandler");
225             }
226         } else {
227             throw new SAXNotRecognizedException(name);
228         }
229     }
230 
231     /**
232     * Register a content handler to receive the output of the transformation
233     * filter. If the content handler is also a LexicalHandler, and if no LexicalHandler
234     * is separately registered, the ContentHandler will also act as the LexicalHandler
235     */
236 
237     public void setContentHandler(ContentHandler handler) {
238         contentHandler = handler;
239         if (handler instanceof LexicalHandler   && lexicalHandler==null) {
240             lexicalHandler = (LexicalHandler  )handler;
241         }
242     }
243 
244     /**
245     * Get the ContentHandler registered using setContentHandler()
246     */
247 
248     public ContentHandler getContentHandler() {
249         return contentHandler;
250     }
251 
252 
253     /**
254      * Allow an application to register an entity resolver.
255      *
256      * <p>If the application does not register an entity resolver,
257      * the XMLReader will perform its own default resolution.</p>
258      *
259      * <p>Applications may register a new or different resolver in the
260      * middle of a parse, and the SAX parser must begin using the new
261      * resolver immediately.</p>
262      *
263      * @param resolver The entity resolver.
264      * @exception java.lang.NullPointerException If the resolver
265      *            argument is null.
266      * @see #getEntityResolver
267      */
268 
269     public void setEntityResolver (EntityResolver resolver) {
270         // XSLT output does not use entities, so the resolver is never used
271     }
272 
273 
274     /**
275      * Return the current entity resolver.
276      *
277      * @return Always null, since no entity resolver is used even if one
278      * is supplied.
279      * @see #setEntityResolver
280      */
281 
282     public EntityResolver getEntityResolver () {
283         return null;
284     }
285 
286 
287     /**
288      * Allow an application to register a DTD event handler.
289      *
290      * <p>If the application does not register a DTD handler, all DTD
291      * events reported by the SAX parser will be silently ignored.</p>
292      *
293      * <p>Applications may register a new or different handler in the
294      * middle of a parse, and the SAX parser must begin using the new
295      * handler immediately.</p>
296      *
297      * @param handler The DTD handler.
298      * @exception java.lang.NullPointerException If the handler
299      *            argument is null.
300      * @see #getDTDHandler
301      */
302 
303     public void setDTDHandler (DTDHandler handler) {
304         // XSLT output does not include a DTD
305     }
306 
307 
308     /**
309      * Return the current DTD handler.
310      *
311      * @return Always null, since no DTD handler is used even if one has been
312      * supplied.
313      * @see #setDTDHandler
314      */
315 
316     public DTDHandler getDTDHandler () {
317         return null;
318     }
319 
320 
321 
322     /**
323      * Allow an application to register an error event handler.
324      *
325      * <p>If the application does not register an error handler, all
326      * error events reported by the SAX parser will be silently
327      * ignored; however, normal processing may not continue.  It is
328      * highly recommended that all SAX applications implement an
329      * error handler to avoid unexpected bugs.</p>
330      *
331      * <p>Applications may register a new or different handler in the
332      * middle of a parse, and the SAX parser must begin using the new
333      * handler immediately.</p>
334      *
335      * @param handler The error handler.
336      * @exception java.lang.NullPointerException If the handler
337      *            argument is null.
338      * @see #getErrorHandler
339      */
340 
341     public void setErrorHandler (ErrorHandler handler) {
342         // No effect
343     }
344 
345     /**
346      * Return the current error handler.
347      *
348      * @return The current error handler, or null if none
349      *         has been registered.
350      * @see #setErrorHandler
351      */
352     public ErrorHandler getErrorHandler () {
353         return null;
354     }
355 
356     /**
357      * Parse an XML document - In the context of a Transformer, this means
358      * perform a transformation. The method is equivalent to transform().
359      *
360      * @param input The input source (the XML document to be transformed)
361      * @exception org.xml.sax.SAXException Any SAX exception, possibly
362      *            wrapping another exception.
363      * @exception java.io.IOException An IO exception from the parser,
364      *            possibly from a byte stream or character stream
365      *            supplied by the application.
366      * @see org.xml.sax.InputSource
367      * @see #parse(java.lang.String)
368      * @see #setEntityResolver
369      * @see #setDTDHandler
370      * @see #setContentHandler
371      * @see #setErrorHandler
372      */
373 
374     public void parse (InputSource input) throws IOException  , SAXException {
375         if (parser==null) {
376             try {
377                 parser = SAXParserFactory.newInstance().newSAXParser().getXMLReader();
378             } catch (Exception   err) {
379                 throw new SAXException(err);
380             }
381         }
382         SAXSource   source = new SAXSource  ();
383         source.setInputSource(input);
384         source.setXMLReader(parser);
385         ContentHandlerProxy result = new ContentHandlerProxy();
386         result.setPipelineConfiguration(controller.makePipelineConfiguration());
387         result.setUnderlyingContentHandler(contentHandler);
388         if (lexicalHandler!=null) {
389             result.setLexicalHandler(lexicalHandler);
390         }
391         try {
392             controller.transform(source, result);
393         } catch (TransformerException   err) {
394             Throwable   cause = err.getException();
395             if (cause != null && cause instanceof SAXException) {
396                 throw (SAXException)cause;
397             } else if (cause != null && cause instanceof IOException  ) {
398                 throw (IOException  )cause;
399             } else {
400                 throw new SAXException(err);
401             }
402         }
403 
404 
405     }
406 
407     /**
408      * Parse (that is, transform) an XML document given a system identifier (URI).
409      *
410      * <p>This method is a shortcut for the common case of reading a
411      * document from a system identifier.  It is the exact
412      * equivalent of the following:</p>
413      *
414      * <pre>
415      * parse(new InputSource(systemId));
416      * </pre>
417      *
418      * <p>If the system identifier is a URL, it must be fully resolved
419      * by the application before it is passed to the parser.</p>
420      *
421      * @param systemId The system identifier (URI).
422      * @exception org.xml.sax.SAXException Any SAX exception, possibly
423      *            wrapping another exception.
424      * @exception java.io.IOException An IO exception from the parser,
425      *            possibly from a byte stream or character stream
426      *            supplied by the application.
427      * @see #parse(org.xml.sax.InputSource)
428      */
429 
430     public void parse (String   systemId) throws IOException  , SAXException {
431         InputSource input = new InputSource(systemId);
432         parse(input);
433     }
434 
435 
436     /**
437     * Get the underlying Transformer. This is a Saxon-specific method that allows the
438     * user to set parameters on the transformation, set a URIResolver or ErrorListener, etc.
439     * New in Saxon 7.2
440     */
441 
442     public Transformer   getTransformer() {
443         return controller;
444     }
445 
446 
447 }
448 
449 //
450 // The contents of this file are subject to the Mozilla Public License Version 1.0 (the "License");
451 // you may not use this file except in compliance with the License. You may obtain a copy of the
452 // License at http://www.mozilla.org/MPL/
453 //
454 // Software distributed under the License is distributed on an "AS IS" basis,
455 // WITHOUT WARRANTY OF ANY KIND, either express or implied.
456 // See the License for the specific language governing rights and limitations under the License.
457 //
458 // The Original Code is: all this file.
459 //
460 // The Initial Developer of the Original Code is Michael H. Kay.
461 //
462 // Portions created by (your name) are Copyright (C) (your legal entity). All Rights Reserved.
463 //
464 // Contributor(s): None
465 //
466
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags