001 /*
002 * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons-sandbox//xmlio/src/java/org/apache/commons/xmlio/in/SimpleImportHandler.java,v 1.1 2004/10/08 11:56:20 ozeigermann Exp $
003 * $Revision: 155476 $
004 * $Date: 2005-02-26 13:31:24 +0000 (Sat, 26 Feb 2005) $
005 *
006 * ====================================================================
007 *
008 * Copyright 2004 The Apache Software Foundation
009 *
010 * Licensed under the Apache License, Version 2.0 (the "License");
011 * you may not use this file except in compliance with the License.
012 * You may obtain a copy of the License at
013 *
014 * http://www.apache.org/licenses/LICENSE-2.0
015 *
016 * Unless required by applicable law or agreed to in writing, software
017 * distributed under the License is distributed on an "AS IS" BASIS,
018 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
019 * See the License for the specific language governing permissions and
020 * limitations under the License.
021 *
022 */
023
024 package org.apache.commons.xmlio.in;
025
026 import org.xml.sax.helpers.AttributesImpl;
027
028 /**
029 * Callback interface for {@link SimpleImporter}.
030 *
031 */
032 public interface SimpleImportHandler {
033
034 /** Is called back when the parsed document begins. */
035 public void startDocument();
036
037 /** Is called back when the parsed document ends. */
038 public void endDocument();
039
040 /**
041 * Is called back when the parser has found character data.
042 * <br>
043 * <em>Caution:</em>
044 * This method will not be called when
045 * SimpleImporter#setIncludeLeadingCDataIntoStartElementCallback(boolean)
046 * is enabled. In this case character data will
047 * be passed over together with {@link #startElement(SimplePath, String, AttributesImpl, String)}.
048 * <br>
049 * Unlike the character method in the SAX interface this callback guarantees
050 * maximum length chunks of character data. This means, on a contiguous text
051 * block, i.e. text not intermitted by tagging, you will get exactly one
052 * callback.
053 *
054 * @see #startElement(SimplePath, String, AttributesImpl, String)
055 *
056 * @param path path of the element closed by this end tag
057 * @param cdata The character data (like in SAX, but unlike from the
058 * {@link #startElement(SimplePath, String, AttributesImpl, String)} call a sequence of CDATA is not
059 * guaranteed to be grouped together into one callback)
060 * of this callbacks. If leading CDATA is delivered together with
061 * {@link #startElement(SimplePath, String, AttributesImpl, String)} it will not be called back here.
062 */
063 public void cData(SimplePath path, String cdata);
064
065 /**
066 * Is called back when the parser has found the start of an element.
067 *
068 * This callback is especially convenient when your data does not have
069 * mixed content, i.e. the mixture of CDATA and tagging in one element
070 * level. When this is the case you will always get the whole text content
071 * together with this callback in the <code>leadingCDdata</code> parameter.
072 * Unlike from {@link #cData(SimplePath, String)} callback all character data fragments will
073 * be grouped together in this parameter.<br>
074 *
075 * If you have to deal with mixed content you can still leave this feature
076 * enabled, but you will have to be aware of the fact that you will then
077 * get some character data via this callback and other via the
078 * {@link #cData(SimplePath, String)} callback.
079 *
080 * @param path path of the element closed by this end tag
081 * @param name the name of the start tag
082 * @param attributes SAX attributes associated to this element
083 * @param leadingCDdata If enabled in
084 * {@link SimpleImporter#setIncludeLeadingCDataIntoStartElementCallback(boolean)}
085 * the text directly following the start tag, i.e. before any
086 * other tagging. If this is enabled you will <em>not</em> get this text
087 * via the {@link #cData(SimplePath, String)} callback.
088 */
089 public void startElement(SimplePath path, String name, AttributesImpl attributes, String leadingCDdata);
090
091 /**
092 * Is called back when the parser has found the end of an element.
093 * @param path path of the element closed by this end tag
094 * @param name the name of the element to be closed
095 */
096 public void endElement(SimplePath path, String name);
097 }