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