ObjectModelFactory


1   /*
2     * JBoss, Home of Professional Open Source
3     * Copyright 2005, JBoss Inc., and individual contributors as indicated
4     * by the @authors tag. See the copyright.txt in the distribution for a
5     * full listing of individual contributors.
6     *
7     * This is free software; you can redistribute it and/or modify it
8     * under the terms of the GNU Lesser General Public License as
9     * published by the Free Software Foundation; either version 2.1 of
10    * the License, or (at your option) any later version.
11    *
12    * This software is distributed in the hope that it will be useful,
13    * but WITHOUT ANY WARRANTY; without even the implied warranty of
14    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15    * Lesser General Public License for more details.
16    *
17    * You should have received a copy of the GNU Lesser General Public
18    * License along with this software; if not, write to the Free
19    * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20    * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
21    */
22  package org.jboss.xb.binding;
23  
24  import org.xml.sax.Attributes  ;
25  
26  /**
27   * All object model factories must implement this interface. Object model factories are used on unmarshalling
28   * to build an object graph that is a representation of the XML content unmarshalled.
29   * <p/>Each object model factory must implement methods <code>newRoot</code> and <code>completeRoot</code>
30   * defined in this interface, plus a set of <code>newChild</code>, <code>addChild</code> and <code>setValue</code>
31   * methods that will be descovered by the framework at runtime with introspection.
32   * <p/>The contract for methods discovered at runtime with introspection:
33   * <ul>
34   * <li><b><code>newChild</code> methods</b>
35   * <br/>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 <code>java.lang.Object</code>) for this new child</li>
39   * <li>instance of <code>org.jboss.xml.binding.UnmarshallingContext</code></li>
40   * <li>namespace URI of the child XML element as <code>java.lang.String</code></li>
41   * <li>local name of the child XML element as <code>java.lang.String</code></li>
42   * <li>attributes of the child XML element as <code>org.xml.sax.Attributes</code></li>
43   * </ol>
44   * Each <code>newChild()</code> method returns either a new instance of
45   * the child object that represents the XML element with the namespace URI and local name
46   * (in this case, the child XML element is said to be 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   * <br/>
50   * <li><b><code>addChild</code> methods</b>
51   * <br/>This method is called on the object model factory by the framework when parsing
52   * of a child XML element completed. The arguments of the <code>addChild()</code> method are:
53   * <ol>
54   * <li>parent object of a conrete Java type (not <code>java.lang.Object</code>) of the child</li>
55   * <li>child object of a concrete Java type (returned earlier by the <code>newChild</code>
56   * method that was called when parsing of this child XML element started)</li>
57   * <li>instance of <code>org.jboss.xml.binding.UnmarshallingContext</code></li>
58   * <li>namespace URI for the child XML element <code>as java.lang.String</code></li>
59   * <li>local name for the child XML element as <code>java.lang.String</code></li>
60   * </ol>
61   * When <code>addChild</code> method is called, the child object is supposed to be populated with all the data from
62   * the corresponding XML element. The child object now can be validated and added to the parent.
63   * </li>
64   * <br/>
65   * <li><b><code>setValue</code> methods</b>
66   * <br/>This method is called on the object model factory by the framework when a new XML element
67   * with text content was parsed.
68   * The method must have four arguments:
69   * <ol>
70   * <li>an object of a concrete Java type (not <code>java.lang.Object</code>) which was returned earlier
71   * by the <code>newChild</code> method (that was called when parsing of the parent XML element started)
72   * for which the value of an XML element was read</li>
73   * <li>instance of <code>org.jboss.xml.binding.UnmarshallingContext</code></li>
74   * <li>namespace URI of the child XML element as <code>java.lang.String</code></li>
75   * <li>local name of the child XML element as <code>java.lang.String</code></li>
76   * <li>the value of the child XML element as <code>java.lang.String</code></li>
77   * </ol>
78   * In <code>setValue</code> method the object model factory is supposed to set the value on the field which represents
79   * the parsed XML element possibly converting the parsed XML element value to the field's Java type.
80   * </li>
81   * </ul>
82   *
83   * @author <a HREF="mailto:alex@jboss.org">Alexey Loubyansky</a>
84   * @version <tt>$Revision: 1958 $</tt>
85   */
86  public interface ObjectModelFactory
87  {
88     /**
89      * This method is called by the framework and returns the root of the object graph.
90      * <p/>If <code>root</code> argument is null, the factory is supposed to create and return a new one
91      * that is going to be the real root object of the graph or an object that will represent the root object
92      * during unmarshalling and which will be used to create the real root object when unmarshalling is complete
93      * in <code>completeRoot</code> if the real root object can't be created while its children are not available,
94      * e.g. no no-arg constructor or other reasons.
95      * <p/>If <code>root</code> argument is not null (i.e. a user provided the root object through the
96      * <code>org.jboss.xml.binding.Unmarshaller</code>) then the factory could just return it as is or
97      * extract the real root from the <code>root</code> argument based on the namespace URI and local name
98      * if <code>root</code> argument wraps/contains the real root.
99      *
100     * @param root         an object that is the root or which contains the root of the object graph
101     * @param ctx          unmarshalling context
102     * @param namespaceURI namespace URI of the root
103     * @param localName    local name of the root
104     * @param attrs        attributes of the root object
105     * @return the root of the object graph
106     */
107    Object   newRoot(Object   root, UnmarshallingContext ctx, String   namespaceURI, String   localName, Attributes   attrs);
108 
109    /**
110     * This method is called by the framework when unmarshalling of the object graph completed.
111     * The method returns the root object of the object graph.
112     * If at the beginning of unmarshalling <code>newRoot</code> returned not the real root object but an
113     * object that represented the root during unmarshalling, the real root object should be created
114     * and returned.
115     *
116     * @param root         the object returned by <code>newRoot</code> at the beginning of unmarshalling
117     * @param ctx          unmarshalling context
118     * @param namespaceURI namespace URI that corresponds to the root
119     * @param localName    local element name the root of the object graph is bound to
120     * @return the root of the object graph
121     */
122    Object   completeRoot(Object   root, UnmarshallingContext ctx, String   namespaceURI, String   localName);
123 }
124
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags