1 /** 2 * Redistribution and use of this software and associated documentation ("Software"), with or 3 * without modification, are permitted provided that the following conditions are met: 4 * 5 * 1. Redistributions of source code must retain copyright statements and notices. Redistributions 6 * must also contain a copy of this document. 7 * 8 * 2. Redistributions in binary form must reproduce the above copyright notice, this list of 9 * conditions and the following disclaimer in the documentation and/or other materials provided with 10 * the distribution. 11 * 12 * 3. The name "Exolab" must not be used to endorse or promote products derived from this Software 13 * without prior written permission of Intalio, Inc. For written permission, please contact 14 * info@exolab.org. 15 * 16 * 4. Products derived from this Software may not be called "Exolab" nor may "Exolab" appear in 17 * their names without prior written permission of Intalio, Inc. Exolab is a registered trademark of 18 * Intalio, Inc. 19 * 20 * 5. Due credit should be given to the Exolab Project (http://www.exolab.org/). 21 * 22 * THIS SOFTWARE IS PROVIDED BY INTALIO, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESSED OR 23 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 24 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTALIO, INC. OR ITS 25 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY 29 * WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 * 31 * Copyright 1999-2004 (C) Intalio, Inc. All Rights Reserved. 32 * 33 * $Id$ 34 */ 35 36 37 package org.exolab.castor.xml; 38 39 40 import org.exolab.castor.mapping.ClassDescriptor; 41 42 /** 43 * A class descriptor for describing relationships between a Class and an XML element or 44 * complexType. This class implements org.exolab.castor.mapping.ClassDescriptor, yet adds extra 45 * methods for handling XML. All fields are of type {@link XMLFieldDescriptor}. 46 * 47 * @author <a href="kvisco-at-intalio.com">Keith Visco</a> 48 * @version $Revision$ $Date: 2004-12-16 22:42:04 -0700 (Thu, 16 Dec 2004) $ 49 */ 50 public interface XMLClassDescriptor extends ClassDescriptor { 51 52 53 54 /** 55 * Returns the set of XMLFieldDescriptors for all members that should be marshalled as XML 56 * attributes. This includes namespace nodes. 57 * 58 * @return an array of XMLFieldDescriptors for all members that should be marshalled as XML 59 * attributes. 60 */ 61 public XMLFieldDescriptor[] getAttributeDescriptors(); 62 63 64 /** 65 * Returns the XMLFieldDescriptor for the member that should be marshalled as text content. 66 * 67 * @return the XMLFieldDescriptor for the member that should be marshalled as text content. 68 */ 69 public XMLFieldDescriptor getContentDescriptor(); 70 71 72 /** 73 * Returns the set of XMLFieldDescriptors for all members that should be marshalled as XML 74 * elements. 75 * 76 * @return an array of XMLFieldDescriptors for all members that should be marshalled as XML 77 * elements. 78 */ 79 public XMLFieldDescriptor[] getElementDescriptors(); 80 81 /** 82 * Returns the XML field descriptor matching the given xml name, namespace, and nodeType. If 83 * NodeType is null, then either an AttributeDescriptor, or ElementDescriptor may be returned. 84 * Null is returned if no matching descriptor is available. 85 * 86 * @param name The xml name to match against. 87 * @param nodeType The NodeType to match against, or null if the node type is not known. 88 * @return The matching descriptor, or null if no matching descriptor is available. 89 */ 90 public XMLFieldDescriptor getFieldDescriptor(String name, String namespace, NodeType nodeType); 91 92 /** 93 * Returns the namespace prefix to use when marshalling as XML. 94 * 95 * @return the namespace prefix to use when marshalling as XML. 96 */ 97 public String getNameSpacePrefix(); 98 99 /** 100 * Returns the namespace URI used when marshalling and unmarshalling as XML. 101 * 102 * @return the namespace URI used when marshalling and unmarshalling as XML. 103 */ 104 public String getNameSpaceURI(); 105 106 /** 107 * Returns a specific validator for the class described by this ClassDescriptor. A null value may 108 * be returned if no specific validator exists. 109 * 110 * @return the type validator for the class described by this ClassDescriptor. 111 */ 112 public TypeValidator getValidator(); 113 114 /** 115 * Returns the XML Name for the Class being described. 116 * 117 * @return the XML name. 118 */ 119 public String getXMLName(); 120 121 /** 122 * <p> 123 * Returns true if the given object, represented by this XMLClassDescriptor, can accept a value 124 * for the member associated with the given xml name and namespace. 125 * </p> 126 * 127 * <p> 128 * An XMLClassDescriptor can accept a value for a field if it contains a descriptor that matches 129 * the given xml name and namespace and if the given object can hold this field (i.e a value is 130 * not already set for this field). 131 * </p> 132 * 133 * @param name the xml name of the field to check 134 * @param namespace the namespace uri 135 * @param object the object instance represented by this XMLCLassDescriptor 136 * @return true if the given object represented by this XMLClassDescriptor can accept a member 137 * whose name is given. 138 */ 139 public boolean canAccept(String name, String namespace, Object object); 140 141 /** 142 * Checks whether the given XMLFieldDescriptor is the one actually expected, given the natural 143 * order as defined by a sequence definition 144 * 145 * @param elementDescriptor The XML field descriptor to be checked 146 * @param xmlName TODO 147 * @throws ValidationException If the descriptor is not the one expected 148 */ 149 public void checkDescriptorForCorrectOrderWithinSequence( 150 final XMLFieldDescriptor elementDescriptor, UnmarshalState parentState, String xmlName) 151 throws ValidationException; 152 153 /** 154 * Indicates whether the XML artifact described by this descriptor is a <xsd:choice>. 155 * 156 * @return True if the artifact described is a choice. 157 */ 158 public boolean isChoice(); 159 160 } // -- XMLClassDescriptor 161 162