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.bind.v2.model.core;
27
28 import java.util.List;
29
30 import javax.xml.bind.annotation.XmlTransient;
31 import javax.xml.bind.annotation.XmlValue;
32
33 /**
34 * Information about JAXB-bound class.
35 *
36 * <p>
37 * All the JAXB annotations are already reflected to the model so that
38 * the caller doesn't have to worry about them. For this reason, you
39 * cannot access annotations on properties.
40 *
41 * <h2>XML representation</h2>
42 * <p>
43 * A JAXB-bound class always have at least one representation
44 * (called "type representation"),but it can optionally have another
45 * representation ("element representation").
46 *
47 * <p>
48 * In the type representaion, a class
49 * is represented as a set of attributes and (elements or values).
50 * You can inspect the details of those attributes/elements/values by {@link #getProperties()}.
51 * This representation corresponds to a complex/simple type in XML Schema.
52 * You can obtain the schema type name by {@link #getTypeName()}.
53 *
54 * <p>
55 * If a class has an element representation, {@link #isElement()} returns true.
56 * This representation is mostly similar to the type representation
57 * except that the whoe attributes/elements/values are wrapped into
58 * one element. You can obtain the name of this element through {@link #asElement()}.
59 *
60 * @author Kohsuke Kawaguchi (kk@kohsuke.org)
61 */
62 public interface ClassInfo<T,C> extends MaybeElement<T,C> {
63
64 /**
65 * Obtains the information about the base class.
66 *
67 * @return null
68 * if this info extends from {@link Object}.
69 */
70 ClassInfo<T,C> getBaseClass();
71
72 /**
73 * Gets the declaration this object is wrapping.
74 */
75 C getClazz();
76
77 /**
78 * Gets the fully-qualified name of the class.
79 */
80 String getName();
81
82 /**
83 * Returns all the properties newly declared in this class.
84 *
85 * <p>
86 * This excludes properties defined in the super class.
87 *
88 * <p>
89 * If the properties are {@link #isOrdered() ordered},
90 * it will be returned in the order that appear in XML.
91 * Otherwise it will be returned in no particular order.
92 *
93 * <p>
94 * Properties marked with {@link XmlTransient} will not show up
95 * in this list. As far as JAXB is concerned, they are considered
96 * non-existent.
97 *
98 * @return
99 * always non-null, but can be empty.
100 */
101 List<? extends PropertyInfo<T,C>> getProperties();
102
103 /**
104 * Returns true if this class or its ancestor has {@link XmlValue}
105 * property.
106 */
107 boolean hasValueProperty();
108
109 /**
110 * Gets the property that has the specified name.
111 *
112 * <p>
113 * This is just a convenience method for:
114 * <pre>
115 * for( PropertyInfo p : getProperties() ) {
116 * if(p.getName().equals(name))
117 * return p;
118 * }
119 * return null;
120 * </pre>
121 *
122 * @return null
123 * if the property was not found.
124 *
125 * @see PropertyInfo#getName()
126 */
127 PropertyInfo<T,C> getProperty(String name);
128
129 /**
130 * If the class has properties, return true. This is only
131 * true if the Collection object returned by {@link #getProperties()}
132 * is not empty.
133 */
134 boolean hasProperties();
135
136 /**
137 * If this class is abstract and thus shall never be directly instanciated.
138 */
139 boolean isAbstract();
140
141 /**
142 * Returns true if the properties of this class is ordered in XML.
143 * False if it't not.
144 *
145 * <p>
146 * In RELAX NG context, ordered properties mean {@code <group>} and
147 * unordered properties mean {@code <interleave>}.
148 */
149 boolean isOrdered();
150
151 /**
152 * If this class is marked as final and no further extension/restriction is allowed.
153 */
154 boolean isFinal();
155
156 /**
157 * True if there's a known sub-type of this class in {@link TypeInfoSet}.
158 */
159 boolean hasSubClasses();
160
161 /**
162 * Returns true if this bean class has an attribute wildcard.
163 *
164 * <p>
165 * This is true if the class declares an attribute wildcard,
166 * or it is inherited from its super classes.
167 *
168 * @see #inheritsAttributeWildcard()
169 */
170 boolean hasAttributeWildcard();
171
172 /**
173 * Returns true iff this class inherits a wildcard attribute
174 * from its ancestor classes.
175 */
176 boolean inheritsAttributeWildcard();
177
178 /**
179 * Returns true iff this class declares a wildcard attribute.
180 */
181 boolean declaresAttributeWildcard();
182 }