1/*
2 * Copyright (c) 1997, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package com.sun.xml.internal.xsom.parser;
27
28import org.xml.sax.ContentHandler;
29import org.xml.sax.EntityResolver;
30import org.xml.sax.ErrorHandler;
31
32/**
33 * Used to parse {@code <xs:annotation>}.
34 *
35 * @author Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
36 */
37public abstract class AnnotationParser {
38    /**
39     * Called every time a new {@code <xs:annotation>} element
40     * is found.
41     *
42     * The sub-tree rooted at {@code <xs:annotation>} will be
43     * sent to this ContentHandler as if it is a whole document.
44     *
45     * @param context
46     *      indicates the schema component that owns this annotation.
47     *      Always non-null.
48     * @param parentElementName
49     *      local name of the element that contains {@code <xs:annotation>}.
50     *      (e.g., "element", "attribute", ... )
51     * @param errorHandler
52     *      The error handler that the client application specifies.
53     *      The returned content handler can send its errors to this
54     *      object.
55     * @param entityResolver
56     *      The entity resolver that is currently in use. Again,
57     *      The returned content handler can use this object
58     *      if it needs to resolve entities.
59     */
60    public abstract ContentHandler getContentHandler(
61        AnnotationContext context,
62        String parentElementName,
63        ErrorHandler errorHandler,
64        EntityResolver entityResolver );
65
66    /**
67     * Once the SAX events are fed to the ContentHandler,
68     * this method will be called to retrieve the parsed result.
69     *
70     * @param existing
71     *      An annotation object which was returned from another
72     *      AnnotationParser before. Sometimes, one schema component
73     *      can have multiple {@code <xs:annotation>} elements and
74     *      this parameter is used to merge all those annotations
75     *      together. If there is no existing object, null will be
76     *      passed.
77     * @return
78     *      Any object, including null.
79     */
80    public abstract Object getResult( Object existing );
81}
82