1/*
2 * reserved comment block
3 * DO NOT REMOVE OR ALTER!
4 */
5/*
6 * Licensed to the Apache Software Foundation (ASF) under one or more
7 * contributor license agreements.  See the NOTICE file distributed with
8 * this work for additional information regarding copyright ownership.
9 * The ASF licenses this file to You under the Apache License, Version 2.0
10 * (the "License"); you may not use this file except in compliance with
11 * the License.  You may obtain a copy of the License at
12 *
13 *      http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS,
17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
20 */
21
22package com.sun.org.apache.xerces.internal.impl;
23
24import java.io.IOException;
25import com.sun.org.apache.xerces.internal.xni.Augmentations;
26import com.sun.org.apache.xerces.internal.xni.XMLResourceIdentifier;
27import com.sun.org.apache.xerces.internal.xni.XNIException;
28
29/**
30 * The entity handler interface defines methods to report information
31 * about the start and end of entities.
32 *
33 * @xerces.internal
34 *
35 * @see com.sun.org.apache.xerces.internal.impl.XMLEntityScanner
36 *
37 * @author Andy Clark, IBM
38 *
39 */
40public interface XMLEntityHandler {
41
42    //
43    // XMLEntityHandler methods
44    //
45
46    /**
47     * This method notifies of the start of an entity. The DTD has the
48     * pseudo-name of "[dtd]" parameter entity names start with '%'; and
49     * general entities are just specified by their name.
50     *
51     * @param name     The name of the entity.
52     * @param identifier The resource identifier.
53     * @param encoding The auto-detected IANA encoding name of the entity
54     *                 stream. This value will be null in those situations
55     *                 where the entity encoding is not auto-detected (e.g.
56     *                 internal entities or a document entity that is
57     *                 parsed from a java.io.Reader).
58     * @param augs     Additional information that may include infoset augmentations
59     *
60     * @throws XNIException Thrown by handler to signal an error.
61     */
62    public void startEntity(String name,
63                            XMLResourceIdentifier identifier,
64                            String encoding, Augmentations augs) throws XNIException;
65
66    /**
67     * This method notifies the end of an entity. The DTD has the pseudo-name
68     * of "[dtd]" parameter entity names start with '%'; and general entities
69     * are just specified by their name.
70     *
71     * @param name The name of the entity.
72     * @param augs Additional information that may include infoset augmentations
73     *
74     * @throws IOException This exception might be thrown when there is premature end of entity
75     * @throws XNIException Thrown by handler to signal an error.
76     */
77    public void endEntity(String name, Augmentations augs) throws IOException, XNIException;
78
79} // interface XMLEntityHandler
80