View Javadoc
1   /*
2    * Copyright 2006 Assaf Arkin, Keith Visco, Ralf Joachim
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5    * in compliance with the License. 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 distributed under the License
10   * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11   * or implied. See the License for the specific language governing permissions and limitations under
12   * the License.
13   */
14  package org.exolab.castor.xml;
15  
16  import java.util.List;
17  
18  import org.exolab.castor.mapping.FieldDescriptor;
19  import org.exolab.castor.xml.util.XMLFieldDescriptorImpl;
20  
21  /**
22   * XML field descriptor. Wraps {@link FieldDescriptor} and adds XML-related information, type
23   * conversion, and so on.
24   *
25   * @author <a href="mailto:arkin AT intalio DOT com">Assaf Arkin</a>
26   * @author <a href="mailto:keith AT kvisco DOT com">Keith Visco</a>
27   * @author <a href="mailto:ralf DOT joachim AT syscon DOT eu">Ralf Joachim</a>
28   * @version $Revision$ $Date: 2004-09-17 00:47:41 -0600 (Fri, 17 Sep 2004) $
29   */
30  public interface XMLFieldDescriptor extends FieldDescriptor {
31    /** The xml:space property. */
32    String PROPERTY_XML_SPACE = "xml:space";
33  
34    /** The xml:lang property. */
35    String PROPERTY_XML_LANG = "xml:lang";
36  
37    /**
38     * Returns the index within the constructor argument array where the value of this field should
39     * be. A value less than zero indicates that the value of this field is set via a normal setter
40     * method and not via the constructor.
41     * <p>
42     * Note: This only applies to attribute mapped fields at this time.
43     *
44     * @return the index within the constructor argument array for this field.
45     * @see #isConstructorArgument()
46     */
47    int getConstructorArgumentIndex();
48  
49    /**
50     * Returns true if the value of the field represented by this descriptor should be set via the
51     * constructor of the containing class. This is only valid for attribute mapped fields.
52     *
53     * @return true if the value of the field represented by this descriptor should be set via the
54     *         constructor of the containing class.
55     */
56    boolean isConstructorArgument();
57  
58    /**
59     * Returns the "relative" XML path for the field being described.
60     * <p>
61     * In most cases, this will be null. However sometimes a field may be mapped to a nested element.
62     * In which case the value returned by this method should be the nested element name. If more than
63     * one level of nesting is needed each nested element name should be separated by by a path
64     * separator (forward slash '/').
65     * <p>
66     * The location path name is "relative" to the parent Class. The name of the parent must not be
67     * included in the path.
68     * <p>
69     * For example, give the following two classes:
70     * 
71     * <pre>
72     * class Root {
73     *   Bar bar;
74     * }
75     *
76     * 
77     * class Bar {
78     *   String value;
79     * }
80     * </pre>
81     *
82     * And the following XML:
83     *
84     * <pre>
85     *    &lt;root&gt;
86     *       &lt;foo&gt;
87     *          &lt;bar&gt; value of bar &lt;/bar&gt;
88     *       &lt;/foo&gt;
89     *    &lt;/root&gt;
90     * </pre>
91     *
92     * Since &lt;foo&gt; has no associated class, the path for 'bar' would be: "foo"
93     *
94     * @return The "relative" XML path for the field being described.
95     */
96    String getLocationPath();
97  
98    /**
99     * Return the "suggested" namespace prefix to use when marshaling as XML.
100    *
101    * @return the "suggested" namespace prefix.
102    */
103   String getNameSpacePrefix();
104 
105   /**
106    * Returns the namespace URI to be used when marshaling and unmarshaling as XML.
107    *
108    * @return the namespace URI.
109    */
110   String getNameSpaceURI();
111 
112   /**
113    * Returns the node type of the field being described. The {@link NodeType} represents the type of
114    * node that the field will be marshaled into XML as.
115    *
116    * @return the {@link NodeType} of the Field being described.
117    */
118   NodeType getNodeType();
119 
120   /**
121    * Returns the value property with the given name or null if no such property exists. This method
122    * is useful for future evolutions of this interface as well as for user-defined extensions. See
123    * class declared properties for built-in properties.
124    *
125    * @param propertyName the name of the property whose value should be returned.
126    *
127    * @return the value of the property, or null.
128    */
129   String getXMLProperty(String propertyName);
130 
131   /**
132    * Returns the XML Schema type of the XML field being described.
133    *
134    * @return the XML Schema type of the XML field being described.
135    */
136   String getSchemaType();
137 
138   /**
139    * Returns a specific validator for the field described by this descriptor. A null value may be
140    * returned if no specific validator exists.
141    *
142    * @return the field validator for the described field
143    */
144   FieldValidator getValidator();
145 
146   /**
147    * Returns the XML Name for the field being described.
148    *
149    * @return the XML name.
150    */
151   String getXMLName();
152 
153   /**
154    * Returns true if the field described by this descriptor is a container field. A container is a
155    * field that is not a first-class object, and should therefore have no XML representation.
156    *
157    * @return true if the field is a container
158    */
159   boolean isContainer();
160 
161   /**
162    * Returns the incremental flag which when true indicates that this member may be safely added
163    * before the unmarshaler is finished unmarshaling it.
164    *
165    * @return true if the Object can safely be added before the unmarshaler is finished unmarshaling
166    *         the Object.
167    */
168   boolean isIncremental();
169 
170   /**
171    * Returns true if the field described by this descriptor is Map or Hashtable. If this method
172    * returns true, it must also return true for any call to {@link #isMultivalued}.
173    *
174    * @return true if the field described by this desciptor is a Map or Hashtable, otherwise false.
175    */
176   boolean isMapped();
177 
178   /**
179    * Returns true if the field described by this descriptor can contain more than one value.
180    *
181    * @return true if the field described by this descriptor can contain more than one value
182    */
183   boolean isMultivalued();
184 
185   /**
186    * Returns true if the field described by this descriptor may be nillable. A nillable field is one
187    * that may have empty content and still be valid. Please see the XML Schema 1.0 Recommendation
188    * for more information on nillable.
189    *
190    * @return true if the field may be nillable.
191    */
192   boolean isNillable();
193 
194   /**
195    * Returns true if the field described by this descriptor is a reference (ie. IDREF) to another
196    * object in the "Object Model" (e.g., XML tree).
197    *
198    * @return true if the field described by this descriptor is a reference to another object in the
199    *         "Object Model"
200    */
201   boolean isReference();
202 
203   /**
204    * Returns true if this descriptor can be used to handle elements or attributes with the given XML
205    * name. By default this method simply compares the given XML name with the internal XML name.
206    * This method can be overridden to provide more complex matching.
207    *
208    * @param xmlName the XML name to compare
209    * @return true if this descriptor can be used to handle elements or attributes with the given XML
210    *         name.
211    */
212   boolean matches(String xmlName);
213 
214   /**
215    * Returns true if this descriptor can be used to handle elements or attributes with the given XML
216    * name. By default this method simply compares the given XML name with the internal XML name.
217    * This method can be overridden to provide more complex matching.
218    *
219    * @param xmlName the XML name to compare
220    * @param namespace the namespace URI
221    *
222    * @return true if this descriptor can be used to handle elements or attributes with the given XML
223    *         name.
224    */
225   boolean matches(String xmlName, String namespace);
226 
227   /**
228    * Returns the possible substitution groups for this class.
229    * 
230    * @return the possible substitution groups for this class.
231    */
232   List<String> getSubstitutes();
233 
234   /**
235    * Sets the possible substitution groups for this class.
236    * 
237    * @param substitutes Possible substitution groups for this class.
238    */
239   void setSubstitutes(List<String> substitutes);
240 
241   /**
242    * Sets whether the field described by this {@link XMLFieldDescriptorImpl} is created as a result
243    * of a <xs:list> definition.
244    * 
245    * @param derivedFromXSList A boolean value, true or false.
246    */
247   void setDerivedFromXSList(boolean derivedFromXSList);
248 
249   /**
250    * Indicates whether the field described by this {@link XMLFieldDescriptorImpl} is created as a
251    * result of a <xs:list> definition.
252    * 
253    * @param derivedFromXSList Trueif the field described by this {@link XMLFieldDescriptorImpl} is
254    *        created as a result of a <xs:list> definition. .
255    */
256   boolean isDerivedFromXSList();
257 
258   /**
259    * Returns the component type of this {@link XMLFieldDescriptor} instance, if the field described
260    * represents a collection of values.
261    * 
262    * @return The collection's component type.
263    * @see XMLFieldDescriptor#getSchemaType()
264    */
265   String getComponentType();
266 
267 
268 }