XMLEntityHandler.java revision 628:2bfaf29cc90b 
1/*
2 * reserved comment block
3 * DO NOT REMOVE OR ALTER!
4 */
5/*
6 * The Apache Software License, Version 1.1
7 *
8 *
9 * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
10 * reserved.
11 *
12 * Redistribution and use in source and binary forms, with or without
13 * modification, are permitted provided that the following conditions
14 * are met:
15 *
16 * 1. Redistributions of source code must retain the above copyright
17 *    notice, this list of conditions and the following disclaimer.
18 *
19 * 2. Redistributions in binary form must reproduce the above copyright
20 *    notice, this list of conditions and the following disclaimer in
21 *    the documentation and/or other materials provided with the
22 *    distribution.
23 *
24 * 3. The end-user documentation included with the redistribution,
25 *    if any, must include the following acknowledgment:
26 *       "This product includes software developed by the
27 *        Apache Software Foundation (http://www.apache.org/)."
28 *    Alternately, this acknowledgment may appear in the software itself,
29 *    if and wherever such third-party acknowledgments normally appear.
30 *
31 * 4. The names "Xerces" and "Apache Software Foundation" must
32 *    not be used to endorse or promote products derived from this
33 *    software without prior written permission. For written
34 *    permission, please contact apache@apache.org.
35 *
36 * 5. Products derived from this software may not be called "Apache",
37 *    nor may "Apache" appear in their name, without prior written
38 *    permission of the Apache Software Foundation.
39 *
40 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
41 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
42 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
43 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
44 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
45 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
46 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
47 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
48 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
49 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
50 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
51 * SUCH DAMAGE.
52 * ====================================================================
53 *
54 * This software consists of voluntary contributions made by many
55 * individuals on behalf of the Apache Software Foundation and was
56 * originally based on software copyright (c) 1999, International
57 * Business Machines, Inc., http://www.apache.org.  For more
58 * information on the Apache Software Foundation, please see
59 * <http://www.apache.org/>.
60 */
61
62package com.sun.org.apache.xerces.internal.impl;
63
64import java.io.IOException;
65import com.sun.org.apache.xerces.internal.xni.Augmentations;
66import com.sun.org.apache.xerces.internal.xni.XMLResourceIdentifier;
67import com.sun.org.apache.xerces.internal.xni.XNIException;
68
69/**
70 * The entity handler interface defines methods to report information
71 * about the start and end of entities.
72 *
73 * @xerces.internal
74 *
75 * @see com.sun.org.apache.xerces.internal.impl.XMLEntityScanner
76 *
77 * @author Andy Clark, IBM
78 *
79 */
80public interface XMLEntityHandler {
81
82    //
83    // XMLEntityHandler methods
84    //
85
86    /**
87     * This method notifies of the start of an entity. The DTD has the
88     * pseudo-name of "[dtd]" parameter entity names start with '%'; and
89     * general entities are just specified by their name.
90     *
91     * @param name     The name of the entity.
92     * @param identifier The resource identifier.
93     * @param encoding The auto-detected IANA encoding name of the entity
94     *                 stream. This value will be null in those situations
95     *                 where the entity encoding is not auto-detected (e.g.
96     *                 internal entities or a document entity that is
97     *                 parsed from a java.io.Reader).
98     * @param augs     Additional information that may include infoset augmentations
99     *
100     * @throws XNIException Thrown by handler to signal an error.
101     */
102    public void startEntity(String name,
103                            XMLResourceIdentifier identifier,
104                            String encoding, Augmentations augs) throws XNIException;
105
106    /**
107     * This method notifies the end of an entity. The DTD has the pseudo-name
108     * of "[dtd]" parameter entity names start with '%'; and general entities
109     * are just specified by their name.
110     *
111     * @param name The name of the entity.
112     * @param augs Additional information that may include infoset augmentations
113     *
114     * @throws IOException This exception might be thrown when there is premature end of entity
115     * @throws XNIException Thrown by handler to signal an error.
116     */
117    public void endEntity(String name, Augmentations augs) throws IOException, XNIException;
118
119} // interface XMLEntityHandler
120