1/*
2 * Copyright (c) 1997, 2012, 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 com.sun.xml.internal.xsom.XSSchema;
29
30import java.util.Set;
31
32/**
33 * Represents a parsed XML schema document.
34 *
35 * <p>
36 * Unlike schema components defined in {@code XS****} interfaces,
37 * which are inherently de-coupled from where it was loaded from,
38 * {@link SchemaDocument} represents a single XML infoset that
39 * is a schema document.
40 *
41 * <p>
42 * This concept is often useful in tracking down the reference
43 * relationship among schema documents.
44 *
45 * @see XSOMParser#getDocuments()
46 * @author Kohsuke Kawaguchi
47 */
48public interface SchemaDocument {
49    /**
50     * Gets the system ID of the schema document.
51     *
52     * @return
53     *      null if {@link XSOMParser} was not given the system Id.
54     */
55    String getSystemId();
56
57    /**
58     * The namespace that this schema defines.
59     *
60     * <p>
61     * More precisely, this method simply returns the {@code targetNamespace} attribute
62     * of the schema document. When schemas are referenced in certain ways
63     * (AKA chameleon schema), schema components in this schema document
64     * may end up defining components in other namespaces.
65     *
66     * @return
67     *      can be "" but never null.
68     */
69    String getTargetNamespace();
70
71    /**
72     * Gets {@link XSSchema} component that contains all the schema
73     * components defined in this namespace.
74     *
75     * <p>
76     * The returned {@link XSSchema} contains not just components
77     * defined in this {@link SchemaDocument} but all the other components
78     * defined in all the schemas that collectively define this namespace.
79     *
80     * @return
81     *      never null.
82     */
83    XSSchema getSchema();
84
85    /**
86     * Set of {@link SchemaDocument}s that are included/imported from this document.
87     *
88     * @return
89     *      can be empty but never null. read-only.
90     */
91    Set<SchemaDocument> getReferencedDocuments();
92
93    /**
94     * Gets the {@link SchemaDocument}s that are included from this document.
95     *
96     * @return
97     *      can be empty but never null. read-only.
98     *      this set is always a subset of {@link #getReferencedDocuments()}.
99     */
100    Set<SchemaDocument> getIncludedDocuments();
101
102    /**
103     * Gets the {@link SchemaDocument}s that are imported from this document.
104     *
105     * @param targetNamespace
106     *      The namespace URI of the import that you want to
107     *      get {@link SchemaDocument}s for.
108     * @return
109     *      can be empty but never null. read-only.
110     *      this set is always a subset of {@link #getReferencedDocuments()}.
111     */
112    Set<SchemaDocument> getImportedDocuments(String targetNamespace);
113
114    /**
115     * Returns true if this document includes the given document.
116     *
117     * <p>
118     * Note that this method returns false if this document
119     * imports the given document.
120     */
121    boolean includes(SchemaDocument doc);
122
123    /**
124     * Returns true if this document imports the given document.
125     *
126     * <p>
127     * Note that this method returns false if this document
128     * includes the given document.
129     */
130    boolean imports(SchemaDocument doc);
131
132    /**
133     * Set of {@link SchemaDocument}s that include/import this document.
134     *
135     * <p>
136     * This works as the opposite of {@link #getReferencedDocuments()}.
137     *
138     * @return
139     *      can be empty but never null. read-only.
140     */
141    Set<SchemaDocument> getReferers();
142}
143