001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036:
037: package com.sun.tools.xjc.model;
038:
039: import java.lang.annotation.Annotation;
040: import java.util.Collection;
041: import java.util.Map;
042:
043: import javax.xml.bind.annotation.XmlSchemaType;
044: import javax.xml.bind.annotation.XmlTransient;
045: import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
046: import javax.xml.namespace.QName;
047:
048: import com.sun.codemodel.JClass;
049: import com.sun.codemodel.JJavaName;
050: import com.sun.codemodel.JType;
051: import com.sun.tools.xjc.Plugin;
052: import com.sun.tools.xjc.generator.bean.field.FieldRenderer;
053: import com.sun.tools.xjc.model.nav.NClass;
054: import com.sun.tools.xjc.model.nav.NType;
055: import com.sun.xml.bind.api.impl.NameConverter;
056: import com.sun.xml.bind.v2.WellKnownNamespace;
057: import com.sun.xml.bind.v2.model.core.PropertyInfo;
058: import com.sun.xml.bind.v2.runtime.RuntimeUtil;
059: import com.sun.xml.xsom.XSComponent;
060:
061: import org.xml.sax.ErrorHandler;
062: import org.xml.sax.Locator;
063:
064: /**
065: * Model of a property to be generated.
066: *
067: * @author Kohsuke Kawaguchi
068: */
069: public abstract class CPropertyInfo implements
070: PropertyInfo<NType, NClass>, CCustomizable {
071:
072: @XmlTransient
073: private CClassInfo parent;
074: private String privateName;
075: private String publicName;
076: private final boolean isCollection;
077:
078: @XmlTransient
079: public final Locator locator;
080:
081: /**
082: * @see #getSchemaComponent()
083: */
084: private final XSComponent source;
085:
086: /**
087: * If the base type of the property is overriden,
088: * this field is set to non-null.
089: */
090: public JType baseType;
091:
092: /**
093: * Javadoc for this property. Must not be null.
094: */
095: public String javadoc = "";
096:
097: /**
098: * Property with {@link @XmlInlineBinaryData}.
099: */
100: public boolean inlineBinaryData;
101:
102: /**
103: * Specifies how the field is generated by the backedn.
104: */
105: @XmlJavaTypeAdapter(RuntimeUtil.ToStringAdapter.class)
106: public FieldRenderer realization;
107:
108: /**
109: * If non-null, keeps the default value in Java representation.
110: *
111: * If {@link #isCollection} is true, this field is always null,
112: * for we don't handle default values for a list.
113: */
114: public CDefaultValue defaultValue;
115:
116: private final CCustomizations customizations;
117:
118: protected CPropertyInfo(String name, boolean collection,
119: XSComponent source, CCustomizations customizations,
120: Locator locator) {
121: this .publicName = name;
122: String n = NameConverter.standard.toVariableName(name);
123: if (!JJavaName.isJavaIdentifier(n))
124: n = '_' + n; // avoid colliding with the reserved names like 'abstract'.
125: this .privateName = n;
126:
127: this .isCollection = collection;
128: this .locator = locator;
129: if (customizations == null)
130: this .customizations = CCustomizations.EMPTY;
131: else
132: this .customizations = customizations;
133: this .source = source;
134: }
135:
136: // called from CClassInfo when added
137: final void setParent(CClassInfo parent) {
138: assert this .parent == null;
139: assert parent != null;
140: this .parent = parent;
141: customizations.setParent(parent.model, this );
142: }
143:
144: public CTypeInfo parent() {
145: return parent;
146: }
147:
148: public Locator getLocator() {
149: return locator;
150: }
151:
152: /**
153: * If this model object is built from XML Schema,
154: * this property returns a schema component from which the model is built.
155: *
156: * @return
157: * null if the model is built from sources other than XML Schema
158: * (such as DTD.)
159: */
160: public final XSComponent getSchemaComponent() {
161: return source;
162: }
163:
164: public abstract CAdapter getAdapter();
165:
166: /**
167: * Name of the property.
168: *
169: * <p>
170: * This method is implemented to follow the contract of
171: * {@link PropertyInfo#getName()}, and therefore it always
172: * returns the name of the annotated field.
173: * <p>
174: * This name is normally not useful for the rest of XJC,
175: * which usually wants to access the "public name" of the property.
176: * A "public name" of the property is a name like "FooBar" which
177: * is used as a seed for generating the accessor methods.
178: * This is the name controlled by the schema customization via users.
179: *
180: * <p>
181: * If the caller is calling this method statically, it's usually
182: * the sign of a mistake. Use {@link #getName(boolean)} method instead,
183: * which forces you to think about which name you want to get.
184: *
185: * @deprecated
186: * marked as deprecated so that we can spot the use of this method.
187: *
188: * @see #getName(boolean)
189: */
190: public String getName() {
191: return getName(false);
192: }
193:
194: /**
195: * Gets the name of the property.
196: *
197: * @param isPublic
198: * if true, this method returns a name like "FooBar", which
199: * should be used as a seed for generating user-visible names
200: * (such as accessors like "getFooBar".)
201: *
202: * <p>
203: * if false, this method returns the "name of the property"
204: * as defined in the j2s side of the spec. This name is usually
205: * something like "fooBar", which often corresponds to the XML
206: * element/attribute name of this property (for taking advantage
207: * of annotation defaulting as much as possible)
208: */
209: public String getName(boolean isPublic) {
210: return isPublic ? publicName : privateName;
211: }
212:
213: /**
214: * Overrides the name of the property.
215: *
216: * This method can be used from {@link Plugin#postProcessModel(Model, ErrorHandler)}.
217: * But the caller should do so with the understanding that this is inherently
218: * dangerous method.
219: */
220: public void setName(boolean isPublic, String newName) {
221: if (isPublic)
222: publicName = newName;
223: else
224: privateName = newName;
225: }
226:
227: public String displayName() {
228: return parent.toString() + '#' + getName(false);
229: }
230:
231: public boolean isCollection() {
232: return isCollection;
233: }
234:
235: public abstract Collection<? extends CTypeInfo> ref();
236:
237: /**
238: * Returns true if this property is "unboxable".
239: *
240: * <p>
241: * In general, a property often has to be capable of representing null
242: * to indicate the absence of the value. This requires properties
243: * to be generated as <tt>@XmlElement Float f</tt>, not as
244: * <tt>@XmlElement float f;</tt>. But this is slow.
245: *
246: * <p>
247: * Fortunately, there are cases where we know that the property can
248: * never legally be absent. When this condition holds we can generate
249: * the optimized "unboxed form".
250: *
251: * <p>
252: * The exact such conditions depend
253: * on the kind of properties, so refer to the implementation code
254: * for the details.
255: *
256: * <p>
257: * This method returns true when the property can be generated
258: * as "unboxed form", false otherwise.
259: *
260: * <p>
261: * When this property is a collection, this method returns true
262: * if items in the collection is unboxable. Obviously, the collection
263: * itself is always a reference type.
264: */
265: public boolean isUnboxable() {
266: Collection<? extends CTypeInfo> ts = ref();
267: if (ts.size() != 1)
268: // if the property is heterogeneous, no way.
269: // ts.size()==0 is a special case that can happen for wildcards.
270: return false;
271:
272: if (baseType != null && (baseType instanceof JClass))
273: return false;
274:
275: CTypeInfo t = ts.iterator().next();
276: // only a primitive type is eligible.
277: return t.getType().isBoxedType();
278: }
279:
280: /**
281: * Returns true if this property needs to represent null
282: * just for the purpose of representing an absence of the property.
283: */
284: public boolean isOptionalPrimitive() {
285: return false;
286: }
287:
288: public CCustomizations getCustomizations() {
289: return customizations;
290: }
291:
292: public boolean inlineBinaryData() {
293: return inlineBinaryData;
294: }
295:
296: public abstract <V> V accept(CPropertyVisitor<V> visitor);
297:
298: /**
299: * Checks if the given {@link TypeUse} would need an explicit {@link XmlSchemaType}
300: * annotation with the given type name.
301: */
302: protected static boolean needsExplicitTypeName(TypeUse type,
303: QName typeName) {
304: if (typeName == null)
305: // this is anonymous type. can't have @XmlSchemaType
306: return false;
307:
308: if (!typeName.getNamespaceURI().equals(
309: WellKnownNamespace.XML_SCHEMA))
310: // if we put application-defined type name, it will be undefined
311: // by the time we generate a schema.
312: return false;
313:
314: if (type.isCollection())
315: // there's no built-in binding for a list simple type,
316: // so any collection type always need @XmlSchemaType
317: return true;
318:
319: QName itemType = type.getInfo().getTypeName();
320: if (itemType == null)
321: // this is somewhat strange case, as it means the bound type is anonymous
322: // but it's eventually derived by a named type and used.
323: // but we can certainly use typeName as @XmlSchemaType value here
324: return true;
325:
326: // if it's the default type name for this item, then no need
327: return !itemType.equals(typeName);
328: }
329:
330: /**
331: * Puts the element names that this property possesses to the map,
332: * so that we can find two properties that own the same element name,
333: * which is an error.
334: *
335: * @return
336: * null if no conflict was found. Otherwise return the QName that has the collision.
337: */
338: public QName collectElementNames(Map<QName, CPropertyInfo> table) {
339: return null;
340: }
341:
342: public final <A extends Annotation> A readAnnotation(
343: Class<A> annotationType) {
344: throw new UnsupportedOperationException();
345: }
346:
347: public final boolean hasAnnotation(
348: Class<? extends Annotation> annotationType) {
349: throw new UnsupportedOperationException();
350: }
351: }
|