1 /* 2 * JBoss, the OpenSource J2EE webOS 3 * 4 * Distributable under LGPL license. 5 * See terms of license at gnu.org. 6 */ 7 package org.jboss.xml.binding; 8 9 import org.xml.sax.Attributes; 10 11 /** 12 * The interface all object model factories must implement. Object model factories are used on unmarshalling 13 * to build the object graph. 14 * <p>Each object model factory must implement one method <code>newRoot</code> defined in the ObjectModelFactory interface 15 * and a set of newChild, addChild and setValue methods descovered by the framework at runtime with introspection. 16 * So the following methods should be implemented: 17 * <p/> 18 * <ul> 19 * <li><code>newRoot</code> method 20 * <pre> 21 * public Object newRoot(java.lang.Object root, 22 * org.jboss.xml.binding.ContentNavigator navigator, 23 * java.lang.String namespaceURI, 24 * java.lang.String localName, 25 * org.xml.sax.Attributes attrs) 26 * </pre> 27 * This method is called on the object model factory by the framework and returns the root of the object model. 28 * If the <code>root</code> argument is null the factory is supposed to create and return a new one. 29 * If the <code>root</code> argument is not null (i.e. the user provided the root object through the 30 * org.jboss.xml.binding.Unmarshaller) the factory should either just return it as is or extract the real root 31 * from the <code>root</code> argument corresponding to the namespace URI and local name. 32 * </li> 33 * <li> 34 * a set of <code>newChild</code> methods. 35 * This method is called by the framework on the object model factory when parsing of a new XML element started. 36 * Each <code>newChild</code> method must have five arguments: 37 * <ol> 38 * <li>parent object of a concrete Java type (not java.lang.Object) for this new child</li> 39 * <li>instance of org.jboss.xml.binding.ContentNavigator</li> 40 * <li>namespace URI of the child XML element as java.lang.String</li> 41 * <li>local name of the child XML element as java.lang.String</li> 42 * <li>attributes of the child XML element as org.xml.sax.Attributes</li> 43 * </ol> 44 * Each <code>newChild()</code> method returns either a new instance of 45 * a child object that represents the XML element with the namespace URI and local name 46 * (in this case, the child XML element is accepted, i.e. should be represented in the object graph) 47 * or <code>null</code> if this child XML element should be ignored, i.e. not be represented in the object graph. 48 * </li> 49 * <li>a set of <code>addChild</code> methods 50 * This method is called on the object model factory by the framework when parsing of a child XML element is complete. 51 * The arguments of the <code>addChild()</code> method are: 52 * <ol> 53 * <li>parent object of a conrete Java type (not java.lang.Object) of the child</li> 54 * <li>child object of a concrete Java type (returned earlier by the <code>newChild</code>)</li> 55 * <li>instance of org.jboss.xml.binding.ContentNavigator</li> 56 * <li>namespace URI for the child XML element as java.lang.String</li> 57 * <li>local name for the child XML element as java.lang.String</li> 58 * </ol> 59 * When <code>addChild</code> method is called, the child object is supposed to be populated with all the data from 60 * the corresponding XML element. The child object now can be validated and added to the parent. 61 * </li> 62 * <li>a set of <code>setValue</code> methods 63 * This method is called on the object model factory by the framework when a new XML element with text content was parsed. 64 * The method must have four arguments: 65 * <ol> 66 * <li>an object of a concrete Java type (not java.lang.Object) which was returned earlier by a <code>newChild</code> 67 * for which the value of an XML element was read</li> 68 * <li>instance of org.jboss.xml.binding.ContentNavigator</li> 69 * <li>namespace URI of the child XML element as java.lang.String</li> 70 * <li>local name of the child XML element as java.lang.String</li> 71 * <li>the value of the child XML element as java.lang.String</li> 72 * </ol> 73 * In <code>setValue</code> method the object model factory is supposed to set a value on the field which represents 74 * the parsed XML element possibly converting the parsed XML element value to the field's Java type. 75 * </li> 76 * </ul> 77 * 78 * @author <a HREF="mailto:alex@jboss.org">Alexey Loubyansky</a> 79 * @version <tt>$Revision: 1.9.2.5 $</tt> 80 */ 81 public interface ObjectModelFactory 82 { 83 /** 84 * This method is called by the object model factory and returns the root of the object graph. 85 * If the <code>root</code> argument is null the factory is supposed to create and return a new one. 86 * If the <code>root</code> argument is not null (i.e. the user provided the root object through the 87 * org.jboss.xml.binding.Unmarshaller) then the factory should either just return it as is 88 * or extract the real root from the <code>root</code> argument based on the namespace URI and local name. 89 * 90 * @param root an object that is the root or which contains the root object 91 * @param navigator content navigator 92 * @param namespaceURI namespace URI of the root 93 * @param localName local name of the root 94 * @param attrs attributes of the root object 95 * @return the root of the object graph 96 */ 97 Object newRoot(Object root, 98 ContentNavigator navigator, 99 String namespaceURI, 100 String localName, 101 Attributes attrs); 102 } 103