View Javadoc
1   /*
2    * Copyright (c) 1997, 2010, 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 <tt>createIfNotExist==false</tt> 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 }