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 }