ObjectModelFactory


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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags