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.bind.v2.model.core;
27
28import java.util.List;
29
30import javax.xml.bind.annotation.XmlTransient;
31import 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 */
62public 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}
183