View Javadoc

1   /*
2    * $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 $
3    * $Revision: 1.1 $
4    * $Date: 2004-10-08 04:56:20 -0700 (Fri, 08 Oct 2004) $
5    *
6    * ====================================================================
7    *
8    * Copyright 2004 The Apache Software Foundation 
9    *
10   * Licensed under the Apache License, Version 2.0 (the "License");
11   * you may not use this file except in compliance with the License.
12   * You may obtain a copy of the License at
13   *
14   *     http://www.apache.org/licenses/LICENSE-2.0
15   *
16   * Unless required by applicable law or agreed to in writing, software
17   * distributed under the License is distributed on an "AS IS" BASIS,
18   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19   * See the License for the specific language governing permissions and
20   * limitations under the License.
21   *
22   */
23  
24  package org.apache.commons.xmlio.in;
25  
26  import org.xml.sax.helpers.AttributesImpl;
27  
28  /***
29   * Callback interface for {@link SimpleImporter}. 
30   *
31   */
32  public interface SimpleImportHandler {
33      
34      /*** Is called back when the parsed document begins. */
35      public void startDocument();
36  
37      /*** Is called back when the parsed document ends. */
38      public void endDocument();
39      
40      /*** 
41       * Is called back when the parser has found character data.
42       * <br>
43       * <em>Caution:</em> 
44       * This method will not be called when 
45       * SimpleImporter#setIncludeLeadingCDataIntoStartElementCallback(boolean)
46       * is enabled. In this case character data will
47       * be passed over together with {@link #startElement(SimplePath, String, AttributesImpl, String)}.
48       * <br>
49       * Unlike the character method in the SAX interface this callback guarantees
50       * maximum length chunks of character data. This means, on a contiguous text 
51       * block, i.e. text not intermitted by tagging, you will get exactly one
52       * callback.  
53       * 
54       * @see #startElement(SimplePath, String, AttributesImpl, String)
55       * 
56       * @param path path of the element closed by this end tag
57       * @param cdata The character data (like in SAX, but unlike from the
58       * {@link #startElement(SimplePath, String, AttributesImpl, String)} call a sequence of CDATA is not
59       * guaranteed to be grouped together into one callback)
60       * of this callbacks. If leading CDATA is delivered together with 
61       * {@link #startElement(SimplePath, String, AttributesImpl, String)} it will not be called back here.
62       */
63      public void cData(SimplePath path, String cdata);
64      
65      /*** 
66       * Is called back when the parser has found the start of an element. 
67       *
68       * This callback is especially convenient when your data does not have
69       * mixed content, i.e. the mixture of CDATA and tagging in one element 
70       * level. When this is the case you will always get the whole text content
71       * together with this callback in the <code>leadingCDdata</code> parameter.
72       * Unlike from {@link #cData(SimplePath, String)} callback all character data fragments will 
73       * be grouped together in this parameter.<br>
74       *
75       * If you have to deal with mixed content you can still leave this feature
76       * enabled, but you will have to be aware of the fact that you will then 
77       * get some character data via this callback and other via the 
78       * {@link #cData(SimplePath, String)} callback.
79       *
80       * @param path path of the element closed by this end tag
81       * @param name the name of the start tag
82       * @param attributes SAX attributes associated to this element
83       * @param leadingCDdata If enabled in 
84       * {@link SimpleImporter#setIncludeLeadingCDataIntoStartElementCallback(boolean)} 
85       * the text directly following the start tag, i.e. before any 
86       * other tagging. If this is enabled you will <em>not</em> get this text 
87       * via the {@link #cData(SimplePath, String)} callback.
88       */
89      public void startElement(SimplePath path, String name, AttributesImpl attributes, String leadingCDdata);
90  
91      /*** 
92       * Is called back when the parser has found the end of an element. 
93       * @param path path of the element closed by this end tag
94       * @param name the name of the element to be closed
95       */
96      public void endElement(SimplePath path, String name);
97  }