View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.tika.sax;
18  
19  import org.xml.sax.ContentHandler;
20  import org.xml.sax.SAXException;
21  
22  /**
23   * A content handler decorator that tags potential exceptions so that the
24   * handler that caused the exception can easily be identified. This is
25   * done by using the {@link TaggedSAXException} class to wrap all thrown
26   * {@link SAXException}s. See below for an example of using this class.
27   * <pre>
28   * TaggedContentHandler handler = new TaggedContentHandler(...);
29   * try {
30   *     // Processing that may throw an SAXException either from this handler
31   *     // or from some other XML parsing activity
32   *     processXML(handler);
33   * } catch (SAXException e) {
34   *     if (handler.isCauseOf(e)) {
35   *         // The exception was caused by this handler.
36   *         // Use e.getCause() to get the original exception.
37   *     } else {
38   *         // The exception was caused by something else.
39   *     }
40   * }
41   * </pre>
42   * <p>
43   * Alternatively, the {@link #throwIfCauseOf(Exception)} method can be
44   * used to let higher levels of code handle the exception caused by this
45   * stream while other processing errors are being taken care of at this
46   * lower level.
47   * <pre>
48   * TaggedContentHandler handler = new TaggedContentHandler(...);
49   * try {
50   *     processXML(handler);
51   * } catch (SAXException e) {
52   *     stream.throwIfCauseOf(e);
53   *     // ... or process the exception that was caused by something else
54   * }
55   * </pre>
56   *
57   * @see TaggedSAXException
58   */
59  public class TaggedContentHandler extends ContentHandlerDecorator {
60  
61      /**
62       * Creates a tagging decorator for the given content handler.
63       *
64       * @param proxy content handler to be decorated
65       */
66      public TaggedContentHandler(ContentHandler proxy) {
67          super(proxy);
68      }
69  
70      /**
71       * Tests if the given exception was caused by this handler.
72       *
73       * @param exception an exception
74       * @return <code>true</code> if the exception was thrown by this handler,
75       *         <code>false</code> otherwise
76       */
77      public boolean isCauseOf(SAXException exception) {
78          if (exception instanceof TaggedSAXException) {
79              TaggedSAXException tagged = (TaggedSAXException) exception;
80              return this == tagged.getTag();
81          } else {
82              return false;
83          }
84      }
85  
86      /**
87       * Re-throws the original exception thrown by this handler. This method
88       * first checks whether the given exception is a {@link TaggedSAXException}
89       * wrapper created by this decorator, and then unwraps and throws the
90       * original wrapped exception. Returns normally if the exception was
91       * not thrown by this handler.
92       *
93       * @param exception an exception
94       * @throws SAXException original exception, if any, thrown by this handler
95       */
96      public void throwIfCauseOf(Exception exception) throws SAXException {
97          if (exception instanceof TaggedSAXException) {
98              TaggedSAXException tagged = (TaggedSAXException) exception;
99              if (this == tagged.getTag()) {
100                 throw tagged.getCause();
101             }
102         }
103     }
104 
105     /**
106      * Tags any {@link SAXException}s thrown, wrapping and re-throwing.
107      * 
108      * @param e The SAXException thrown
109      * @throws SAXException if an XML error occurs
110      */
111     @Override
112     protected void handleException(SAXException e) throws SAXException {
113         throw new TaggedSAXException(e, this);
114     }
115 
116 }