2 * Copyright 2001-2006 Internet2
\r
4 * Licensed under the Apache License, Version 2.0 (the "License");
\r
5 * you may not use this file except in compliance with the License.
\r
6 * You may obtain a copy of the License at
\r
8 * http://www.apache.org/licenses/LICENSE-2.0
\r
10 * Unless required by applicable law or agreed to in writing, software
\r
11 * distributed under the License is distributed on an "AS IS" BASIS,
\r
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
\r
13 * See the License for the specific language governing permissions and
\r
14 * limitations under the License.
\r
18 * @file AbstractXMLObjectUnmarshaller.h
\r
20 * A thread-safe abstract unmarshaller.
\r
23 #if !defined(__xmltooling_xmlunmarshaller_h__)
\r
24 #define __xmltooling_xmlunmarshaller_h__
\r
26 #include <xmltooling/DOMCachingXMLObject.h>
\r
27 #include <xmltooling/exceptions.h>
\r
28 #include <xmltooling/XMLObjectBuilder.h>
\r
29 #include <xmltooling/io/Unmarshaller.h>
\r
30 #include <xmltooling/util/XMLConstants.h>
\r
31 #include <xmltooling/util/XMLHelper.h>
\r
33 namespace xmltooling {
\r
36 * A thread-safe abstract unmarshaller.
\r
38 class XMLTOOL_API AbstractXMLObjectUnmarshaller : public virtual Unmarshaller
\r
41 virtual ~AbstractXMLObjectUnmarshaller() {}
\r
44 * @see Unmarshaller::unmarshall()
\r
46 XMLObject* unmarshall(DOMElement* element, bool bindDocument=false) const;
\r
53 * @param targetNamespaceURI the namespace URI of either the schema type QName or element QName of the elements this
\r
54 * unmarshaller operates on
\r
55 * @param targetLocalName the local name of either the schema type QName or element QName of the elements this
\r
56 * unmarshaller operates on
\r
58 AbstractXMLObjectUnmarshaller(const XMLCh* targetNamespaceURI, const XMLCh* targetLocalName)
\r
59 : m_targetQName(targetNamespaceURI, targetLocalName) {
\r
60 if (!targetLocalName || !*targetLocalName)
\r
61 throw UnmarshallerException("targetLocalName cannot be null or empty");
\r
65 * Checks that the given DOM Element's XSI type or namespace qualified element name matches the target QName of this
\r
68 * @param domElement the DOM element to check
\r
70 * @throws UnmarshallingException thrown if the DOM Element does not match the target of this unmarshaller
\r
72 void checkElementIsTarget(DOMElement* domElement) const;
\r
75 * Constructs the XMLObject that the given DOM Element will be unmarshalled into. If the DOM element has an XML
\r
76 * Schema type defined this method will attempt to retrieve an XMLObjectBuilder using the schema type. If no
\r
77 * schema type is present or no builder is registered for the schema type, the element's QName is used. Once
\r
78 * the builder is found the XMLObject is created by invoking XMLObjectBuilder::buildObject().
\r
79 * Extending classes may wish to override this logic if more than just schema type or element name
\r
80 * (e.g. element attributes or content) need to be used to determine how to create the XMLObject.
\r
82 * @param domElement the DOM Element the created XMLObject will represent
\r
83 * @return the empty XMLObject that DOM Element can be unmarshalled into
\r
85 * @throws UnmarshallingException thrown if there is now XMLObjectBuilder registered for the given DOM Element
\r
87 virtual XMLObject* buildXMLObject(DOMElement* domElement) const;
\r
90 * Unmarshalls the attributes from the given DOM Element into the given XMLObject. If the attribute is an XML
\r
91 * namespace declaration the namespace is added to the given element via XMLObject::addNamespace().
\r
92 * If it is a schema type (xsi:type) the schema type is added to the element via XMLObject::setSchemaType().
\r
93 * All other attributes are passed to the processAttribute hook.
\r
95 * @param domElement the DOM Element whose attributes will be unmarshalled
\r
96 * @param xmlObject the XMLObject that will recieve information from the DOM attribute
\r
98 * @throws UnmarshallingException thrown if there is a problem unmarshalling an attribute
\r
100 virtual void unmarshallAttributes(DOMElement* domElement, XMLObject* xmlObject) const;
\r
103 * Unmarshalls a given Element's children. For each child an unmarshaller is retrieved using
\r
104 * getUnmarshaller(). The unmarshaller is then used to unmarshall the child element and the
\r
105 * resulting XMLObject is passed to processChildElement() for further processing.
\r
107 * @param domElement the DOM Element whose children will be unmarshalled
\r
108 * @param xmlObject the parent object of the unmarshalled children
\r
110 * @throws UnmarshallingException thrown if an error occurs unmarshalling the child elements
\r
112 virtual void unmarshallChildElements(DOMElement* domElement, XMLObject* xmlObject) const;
\r
115 * Gets the Unmarshaller for the given Element. If the child element has an explicit XML Schema type,
\r
116 * that is used to get the unmarshaller. If there is no unmarshaller registered for the schema type,
\r
117 * or the element does not have an explicit schema type, the element's QName is used.
\r
119 * @param domElement the DOM Element to get the Unmarshaller for
\r
120 * @return the Unmarshaller for the given DOM Element
\r
122 * @throws UnmarshallingException thrown if no unmarshaller is available for the given DOM Element
\r
124 const Unmarshaller* getUnmarshaller(DOMElement* domElement) const;
\r
127 * Called after a child element has been unmarshalled so that it can be added to the parent XMLObject.
\r
129 * @param parent the parent XMLObject
\r
130 * @param child the child XMLObject
\r
132 * @throws UnmarshallingException thrown if there is a problem adding the child to the parent
\r
134 virtual void processChildElement(XMLObject* parent, XMLObject* child) const=0;
\r
137 * Called after an attribute has been unmarshalled so that it can be added to the XMLObject.
\r
139 * @param xmlObject the XMLObject
\r
140 * @param name the attribute's name
\r
141 * @param value the attribute's value
\r
143 * @throws UnmarshallingException thrown if there is a problem adding the attribute to the XMLObject
\r
145 virtual void processAttribute(XMLObject* xmlObject, const XMLCh* name, const XMLCh* value) const=0;
\r
148 * Called if the element being unmarshalled contained textual content so that it can be added to the XMLObject.
\r
150 * @param xmlObject XMLObject the content will be given to
\r
151 * @param elementContent the Element's text content
\r
153 virtual void processElementContent(XMLObject* xmlObject, const XMLCh* elementContent) const=0;
\r
156 QName m_targetQName;
\r
161 #endif /* __xmltooling_xmlunmarshaller_h__ */
\r