* JBoss, Home of Professional Open Source
* Copyright 2005, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
* This is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of
* the License, or (at your option) any later version.
* This software is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
* You should have received a copy of the GNU Lesser General Public
* License along with this software; if not, write to the Free
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
Each object model factory must implement methods
defined in this interface, plus a set of
methods that will be descovered by the framework at runtime with introspection.
The contract for methods discovered at runtime with introspection:
newChildmethod must have five arguments:
java.lang.Object) for this new child
newChild()method returns either a new instance of the child object that represents the XML element with the namespace URI and local name (in this case, the child XML element is said to be accepted, i.e. should be represented in the object graph) or
nullif this child XML element should be ignored, i.e. not be represented in the object graph.
java.lang.Object) of the child
newChildmethod that was called when parsing of this child XML element started)
addChildmethod is called, the child object is supposed to be populated with all the data from the corresponding XML element. The child object now can be validated and added to the parent.
java.lang.Object) which was returned earlier by the
newChildmethod (that was called when parsing of the parent XML element started) for which the value of an XML element was read
setValuemethod the object model factory is supposed to set the value on the field which represents the parsed XML element possibly converting the parsed XML element value to the field's Java type.
root argument is null, the factory is supposed to create and return a new one
that is going to be the real root object of the graph or an object that will represent the root object
during unmarshalling and which will be used to create the real root object when unmarshalling is complete
completeRoot if the real root object can't be created while its children are not available,
e.g. no no-arg constructor or other reasons.
root argument is not null (i.e. a user provided the root object through the
org.jboss.xml.binding.Unmarshaller) then the factory could just return it as is or
extract the real root from the
root argument based on the namespace URI and local name
root argument wraps/contains the real root.
rootan object that is the root or which contains the root of the object graph
namespaceURInamespace URI of the root
localNamelocal name of the root
attrsattributes of the root object
Object newRoot(Object root, UnmarshallingContext ctx, String namespaceURI, String localName, Attributes attrs);
newRootreturned not the real root object but an object that represented the root during unmarshalling, the real root object should be created and returned.
rootthe object returned by
newRootat the beginning of unmarshalling
namespaceURInamespace URI that corresponds to the root
localNamelocal element name the root of the object graph is bound to
Object completeRoot(Object root, UnmarshallingContext ctx, String namespaceURI, String localName);