1 /* Copyright 2004 The Apache Software Foundation
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16 package org.apache.xmlbeans;
17
18 import java.math.BigInteger;
19
20 import javax.xml.namespace.QName;
21
22 /**
23 * Represents a summary of similar SchemaFields in a complex type.
24 * <p>
25 * In a schema type, every element with the same name must have the
26 * same type. Therefore, all together, elements with the same name
27 * form a coherent collection of similar elements. Similarly, attributes
28 * can only be defined once, so each attribute obviously is a coherent
29 * group on its own.
30 * <p>
31 * A SchemaProperty represents a summary of the the elements with a
32 * given name or the attribute with a given name. It represents the
33 * summary cardinality of the fields, the summary default and fixed
34 * values, and so on. When inferring information about an element
35 * or attribute, it is typically easier to consult then SchemaProperty
36 * than to hunt for the exact SchemaField in the particle tree or
37 * attribute model.
38 *
39 * @see SchemaType#getProperties
40 * @see SchemaType#getAttributeProperties
41 * @see SchemaType#getElementProperties
42 * @see SchemaType#getAttributeProperty
43 * @see SchemaType#getElementProperty
44 */
45 public interface SchemaProperty
46 {
47 /**
48 * The type within which this property appears
49 */
50 SchemaType getContainerType();
51
52 /**
53 * The name of this element or attribute
54 */
55 QName getName();
56
57 /**
58 * For element properties the set of names that are accepted for this property
59 * if this element is the head of a substitution group. This will always
60 * have at least one element, ie, the property's name.
61 */
62 QName[] acceptedNames();
63
64 /**
65 * The Java name for this property. For example, if the method to
66 * access this property is called getFirstName, then this method
67 * returns the string "FirstName". May be null if the schema type
68 * has not been compiled to Java.
69 */
70 String getJavaPropertyName();
71
72 /**
73 * True for read-only properties.
74 */
75 boolean isReadOnly();
76
77 /**
78 * True for attributes.
79 */
80 boolean isAttribute();
81
82 /**
83 * The schema type for the property.
84 */
85 SchemaType getType();
86
87 // note that in the inheritance hierarchy, if the array getter shows up first,
88 // then the singelton getter is never allowed to show up.
89
90 /**
91 * The schema type returned from the Java getter for this property.
92 * Applies only to types that have been code generated to Java; may
93 * be a base type of getType().
94 */
95 public SchemaType javaBasedOnType(); // Java property type based on this base type
96
97 /**
98 * True if there is a Java getter that returns a singleton.
99 */
100 boolean extendsJavaSingleton(); // has singleton getter
101
102 /**
103 * True if there is an Java isSet method that tests for presence.
104 */
105 boolean extendsJavaOption(); // has isSet tester
106
107 /**
108 * True if there is a Java getter that returns an array.
109 */
110 boolean extendsJavaArray(); // has array getter (called -Array, if singleton is present)
111
112 /**
113 * Returns the natural Java type for this property. Returns either
114 * XML_OBJECT (for complex types) or one of the JAVA_* constants described
115 * in this interface.
116 */
117 int getJavaTypeCode();
118
119 /**
120 * Returns the set of element names which should appear strictly after all
121 * occurences of the elements described by this property. For element properties only.
122 */
123 QNameSet getJavaSetterDelimiter();
124
125 /**
126 * Returns a summarized minimum occurrance number.
127 * For example, a sequence containing a nonoptional singleton element repeated twice will
128 * result in a property getMinOccurs() of 2.
129 */
130 BigInteger getMinOccurs();
131
132 /**
133 * Returns a summarized minimum occurrance number.
134 * For example, a sequence containing a nonoptional singleton element repeated twice will
135 * result in a property getMaxOccurs() of 2.
136 */
137 BigInteger getMaxOccurs();
138
139 /**
140 * Returns {@link #NEVER}, {@link #VARIABLE}, or {@link #CONSISTENTLY} nillable, depending on the
141 * nillability of the elements in this property.
142 */
143 int hasNillable();
144
145 /**
146 * Returns {@link #NEVER}, {@link #VARIABLE}, or {@link #CONSISTENTLY} defaulted, depending on the
147 * defaults present in the elements in this property.
148 */
149 int hasDefault();
150
151 /**
152 * Returns {@link #NEVER}, {@link #VARIABLE}, or {@link #CONSISTENTLY} fixed, depending on the
153 * fixed constraints present in the elements in this property.
154 */
155 int hasFixed();
156
157 /** Applies to no elements for this property. See {@link #hasNillable}, {@link #hasDefault}, {@link #hasFixed} */
158 static final int NEVER = 0;
159 /** Applies to some, but not other elements for this property. See {@link #hasNillable}, {@link #hasDefault}, {@link #hasFixed} */
160 static final int VARIABLE = 1;
161 /** Applies to all elements for this property. See {@link #hasNillable}, {@link #hasDefault}, {@link #hasFixed} */
162 static final int CONSISTENTLY = 2;
163
164 /** An XML Bean type that inherits from {@link XmlObject}. See {@link #getJavaTypeCode}. */
165 static final int XML_OBJECT = 0;
166
167 /** Java primitive type codes (for non-nullable Java types) are between JAVA_FIRST_PRIMITIVE and JAVA_LAST_PRIMITIVE, inclusive. */
168 static final int JAVA_FIRST_PRIMITIVE = 1;
169
170 /** A Java boolean. See {@link #getJavaTypeCode}. */
171 static final int JAVA_BOOLEAN = 1;
172 /** A Java float. See {@link #getJavaTypeCode}. */
173 static final int JAVA_FLOAT = 2;
174 /** A Java double. See {@link #getJavaTypeCode}. */
175 static final int JAVA_DOUBLE = 3;
176 /** A Java byte. See {@link #getJavaTypeCode}. */
177 static final int JAVA_BYTE = 4;
178 /** A Java short. See {@link #getJavaTypeCode}. */
179 static final int JAVA_SHORT = 5;
180 /** A Java int. See {@link #getJavaTypeCode}. */
181 static final int JAVA_INT = 6;
182 /** A Java long. See {@link #getJavaTypeCode}. */
183 static final int JAVA_LONG = 7;
184
185 /** Java primitive type codes (for non-nullable Java types) are between JAVA_FIRST_PRIMITIVE and JAVA_LAST_PRIMITIVE, inclusive. */
186 static final int JAVA_LAST_PRIMITIVE = 7;
187
188 /** A {@link java.math.BigDecimal}. See {@link #getJavaTypeCode}. */
189 static final int JAVA_BIG_DECIMAL = 8;
190 /** A {@link java.math.BigInteger}. See {@link #getJavaTypeCode}. */
191 static final int JAVA_BIG_INTEGER = 9;
192 /** A {@link String}. See {@link #getJavaTypeCode}. */
193 static final int JAVA_STRING = 10;
194 /** A byte[]. See {@link #getJavaTypeCode}. */
195 static final int JAVA_BYTE_ARRAY = 11;
196 /** A {@link GDate}. See {@link #getJavaTypeCode}. */
197 static final int JAVA_GDATE = 12;
198 /** A {@link GDuration}. See {@link #getJavaTypeCode}. */
199 static final int JAVA_GDURATION = 13;
200 /** A {@link java.util.Date}. See {@link #getJavaTypeCode}. */
201 static final int JAVA_DATE = 14;
202 /** A {@link javax.xml.namespace.QName}. See {@link #getJavaTypeCode}. */
203 static final int JAVA_QNAME = 15;
204 /** A {@link java.util.List}. See {@link #getJavaTypeCode}. */
205 static final int JAVA_LIST = 16;
206 /** A {@link java.util.Calendar}. See {@link #getJavaTypeCode}. */
207 static final int JAVA_CALENDAR = 17;
208
209 /** A generated {@link StringEnumAbstractBase} subclass. See {@link #getJavaTypeCode}. */
210 static final int JAVA_ENUM = 18;
211 /** A {@link java.lang.Object}, used for some simple type unions. See {@link #getJavaTypeCode}. */
212 static final int JAVA_OBJECT = 19; // for some unions
213
214 /** A user specified type. */
215 static final int JAVA_USER = 20;
216
217 /**
218 * Returns the default or fixed value,
219 * if it is consistent. If it is not consistent,
220 * then returns null.
221 * See {@link #hasDefault} and {@link #hasFixed}.
222 */
223 String getDefaultText();
224
225 /**
226 * Returns the default or fixed value as a strongly-typed value,
227 * if it is consistent. If it is not consistent,
228 * then returns null.
229 * See {@link #hasDefault} and {@link #hasFixed}.
230 */
231 XmlAnySimpleType getDefaultValue();
232 }