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 * <root> 86 * <foo> 87 * <bar> value of bar </bar> 88 * </foo> 89 * </root> 90 * </pre> 91 * 92 * Since <foo> 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 }