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/XMLObject.h>
\r
27 #include <xmltooling/io/Unmarshaller.h>
\r
29 namespace xmltooling {
\r
32 * A thread-safe abstract unmarshaller.
\r
34 class XMLTOOL_API AbstractXMLObjectUnmarshaller : public virtual Unmarshaller
\r
37 virtual ~AbstractXMLObjectUnmarshaller() {}
\r
40 * @see Unmarshaller::unmarshall()
\r
42 XMLObject* unmarshall(DOMElement* element, bool bindDocument=false) const;
\r
49 * @param targetNamespaceURI the namespace URI of either the schema type QName or element QName of the elements this
\r
50 * unmarshaller operates on
\r
51 * @param targetLocalName the local name of either the schema type QName or element QName of the elements this
\r
52 * unmarshaller operates on
\r
54 AbstractXMLObjectUnmarshaller(const XMLCh* targetNamespaceURI, const XMLCh* targetLocalName);
\r
57 * Checks that the given DOM Element's XSI type or namespace qualified element name matches the target QName of this
\r
60 * @param domElement the DOM element to check
\r
62 * @throws UnmarshallingException thrown if the DOM Element does not match the target of this unmarshaller
\r
64 void checkElementIsTarget(const DOMElement* domElement) const;
\r
67 * Constructs the XMLObject that the given DOM Element will be unmarshalled into. If the DOM element has an XML
\r
68 * Schema type defined this method will attempt to retrieve an XMLObjectBuilder using the schema type. If no
\r
69 * schema type is present or no builder is registered for the schema type, the element's QName is used. Once
\r
70 * the builder is found the XMLObject is created by invoking XMLObjectBuilder::buildObject().
\r
71 * Extending classes may wish to override this logic if more than just schema type or element name
\r
72 * (e.g. element attributes or content) need to be used to determine how to create the XMLObject.
\r
74 * @param domElement the DOM Element the created XMLObject will represent
\r
75 * @return the empty XMLObject that DOM Element can be unmarshalled into
\r
77 * @throws UnmarshallingException thrown if there is now XMLObjectBuilder registered for the given DOM Element
\r
79 virtual XMLObject* buildXMLObject(const DOMElement* domElement) const;
\r
82 * Unmarshalls the attributes from the given DOM Element into the given XMLObject. If the attribute is an XML
\r
83 * namespace declaration the namespace is added to the given element via XMLObject::addNamespace().
\r
84 * If it is a schema type (xsi:type) the schema type is added to the element via XMLObject::setSchemaType().
\r
85 * All other attributes are passed to the processAttribute hook.
\r
87 * @param domElement the DOM Element whose attributes will be unmarshalled
\r
88 * @param xmlObject the XMLObject that will recieve information from the DOM attribute
\r
90 * @throws UnmarshallingException thrown if there is a problem unmarshalling an attribute
\r
92 virtual void unmarshallAttributes(const DOMElement* domElement, XMLObject* xmlObject) const;
\r
95 * Unmarshalls a given Element's children. For each child an unmarshaller is retrieved using
\r
96 * getUnmarshaller(). The unmarshaller is then used to unmarshall the child element and the
\r
97 * resulting XMLObject is passed to processChildElement() for further processing.
\r
99 * @param domElement the DOM Element whose children will be unmarshalled
\r
100 * @param xmlObject the parent object of the unmarshalled children
\r
102 * @throws UnmarshallingException thrown if an error occurs unmarshalling the child elements
\r
104 virtual void unmarshallChildElements(const DOMElement* domElement, XMLObject* xmlObject) const;
\r
107 * Called after a child element has been unmarshalled so that it can be added to the parent XMLObject.
\r
109 * @param parent the parent XMLObject
\r
110 * @param child the child XMLObject
\r
112 * @throws UnmarshallingException thrown if there is a problem adding the child to the parent
\r
114 virtual void processChildElement(XMLObject* parent, XMLObject* child) const=0;
\r
117 * Called after an attribute has been unmarshalled so that it can be added to the XMLObject.
\r
119 * @param xmlObject the XMLObject
\r
120 * @param attribute the attribute being unmarshalled
\r
122 * @throws UnmarshallingException thrown if there is a problem adding the attribute to the XMLObject
\r
124 virtual void processAttribute(XMLObject* xmlObject, const DOMAttr* attribute) const=0;
\r
127 * Called if the element being unmarshalled contained textual content so that it can be added to the XMLObject.
\r
129 * @param xmlObject XMLObject the content will be given to
\r
130 * @param elementContent the Element's text content
\r
132 virtual void processElementContent(XMLObject* xmlObject, const XMLCh* elementContent) const=0;
\r
136 QName m_targetQName;
\r
141 #endif /* __xmltooling_xmlunmarshaller_h__ */
\r