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
26 package com.sun.xml.internal.xsom;
27
28 import com.sun.xml.internal.xsom.parser.SchemaDocument;
29 import com.sun.xml.internal.xsom.visitor.XSFunction;
30 import com.sun.xml.internal.xsom.visitor.XSVisitor;
31 import org.xml.sax.Locator;
32
33 import javax.xml.namespace.NamespaceContext;
34 import java.util.List;
35 import java.util.Collection;
36
37 /**
38 * Base interface for all the schema components.
39 *
40 * @author
41 * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
42 */
43 public interface XSComponent
44 {
45 /** Gets the annotation associated to this component, if any. */
46 XSAnnotation getAnnotation();
47
48 /**
49 * Works like {@link #getAnnotation()}, but allow a new empty {@link XSAnnotation} to be created
50 * if not exist.
51 *
52 * @param createIfNotExist
53 * true to create a new {@link XSAnnotation} if it doesn't exist already.
54 * false to make this method behavel like {@link #getAnnotation()}.
55 *
56 * @return
57 * null if {@code createIfNotExist==false} and annotation didn't exist.
58 * Otherwise non-null.
59 */
60 XSAnnotation getAnnotation(boolean createIfNotExist);
61
62 /**
63 * Gets the foreign attributes on this schema component.
64 *
65 * <p>
66 * In general, a schema component may match multiple elements
67 * in a schema document, and those elements can individually
68 * carry foreign attributes.
69 *
70 * <p>
71 * This method returns a list of {@link ForeignAttributes}, where
72 * each {@link ForeignAttributes} object represent foreign attributes
73 * on one element.
74 *
75 * @return
76 * can be an empty list but never be null.
77 */
78 List<? extends ForeignAttributes> getForeignAttributes();
79
80 /**
81 * Gets the foreign attribute of the given name, or null if not found.
82 *
83 * <p>
84 * If multiple occurences of the same attribute is found,
85 * this method returns the first one.
86 *
87 * @see #getForeignAttributes()
88 */
89 String getForeignAttribute(String nsUri, String localName);
90
91 /**
92 * Gets the locator that indicates the source location where
93 * this component is created from, or null if no information is
94 * available.
95 */
96 Locator getLocator();
97
98 /**
99 * Gets a reference to the {@link XSSchema} object to which this component
100 * belongs.
101 * <p>
102 * In case of <code>XSEmpty</code> component, this method
103 * returns null since there is no owner component.
104 */
105 XSSchema getOwnerSchema();
106
107 /**
108 * Gets the root schema set that includes this component.
109 *
110 * <p>
111 * In case of <code>XSEmpty</code> component, this method
112 * returns null since there is no owner component.
113 */
114 XSSchemaSet getRoot();
115
116 /**
117 * Gets the {@link SchemaDocument} that indicates which document this component
118 * was defined in.
119 *
120 * @return
121 * null for components that are built-in to XML Schema, such
122 * as anyType, or "empty" {@link XSContentType}. This method also
123 * returns null for {@link XSSchema}.
124 * For all other user-defined
125 * components this method returns non-null, even if they are local.
126 */
127 SchemaDocument getSourceDocument();
128
129 /**
130 * Evaluates a schema component designator against this schema component
131 * and returns the resulting schema components.
132 *
133 * @throws IllegalArgumentException
134 * if SCD is syntactically incorrect.
135 *
136 * @param scd
137 * Schema component designator. See {@link SCD} for more details.
138 * @param nsContext
139 * The namespace context in which SCD is evaluated. Cannot be null.
140 * @return
141 * Can be empty but never null.
142 */
143 Collection<XSComponent> select(String scd, NamespaceContext nsContext);
144
145 /**
146 * Evaluates a schema component designator against this schema component
147 * and returns the first resulting schema component.
148 *
149 * @throws IllegalArgumentException
150 * if SCD is syntactically incorrect.
151 *
152 * @param scd
153 * Schema component designator. See {@link SCD} for more details.
154 * @param nsContext
155 * The namespace context in which SCD is evaluated. Cannot be null.
156 * @return
157 * null if the SCD didn't match anything. If the SCD matched more than one node,
158 * the first one will be returned.
159 */
160 XSComponent selectSingle(String scd, NamespaceContext nsContext);
161
162 /**
163 * Accepts a visitor.
164 */
165 void visit( XSVisitor visitor );
166 /**
167 * Accepts a functor.
168 */
169 <T> T apply( XSFunction<T> function );
170 }