ObjectModelProvider


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  /**
25   * The interface all object model providers must implement. Object model providers are used on marshalling
26   * providing data for XML content based on the object model and XML schema or DTD.
27   * <p/>
28   * Each object model provider must implement one method <code>getRoot</code> defined in ObjectModelProvider interface
29   * and a set of getChildren, getElementValue and getAttributeValue methods descovered by the framework at runtime
30   * with introspection.
31   * <p/>So, the following methods should be implemented:
32   * <ul>
33   * <li><code>getRoot</code> method
34   * <pre>
35   *    java.lang.Object getRoot(java.lang.Object o, java.lang.String namespaceURI, java.lang.String localName)
36   * </pre>
37   * This method is called on the object model provider by the framework when a root XML element is marshalled.
38   * The method returns an object that represents the root of the XML content corresponding to the namespace URI and
39   * local name.
40   * </li>
41   * <li>a set of <code>getChildren</code> methods
42   * This method is called on the object model provider by the framework when marshalling of a new XML element started.
43   * Each <code>getChildren</code> method must have three arguments:
44   * <ol>
45   * <li>parent object of a concrete Java type (not java.lang.Object) that is "asked" for its children</li>
46   * <li>namespace URI of the child XML element as java.lang.String</li>
47   * <li>local name of the child element as java.lang.String</li>
48   * </ol>
49   * A <code>getChildren</code> method returns children that represent the namespace URI and local name in XML content.
50   * The method can return null if there are no children in this object graph corresponding to the namespace and local name.
51   * The method can return a single object if there is only one child object corresponding to the namespace and local name.
52   * If there are many children that match the namespace URI and local name, the method can return them as an array,
53   * java.util.List, java.util.Collection or java.util.Iterator.
54   * </li>
55   * <li>a set of <code>getElementValue</code> methods
56   * This method is called on the object model provider by the framework for objects that represent XML elements with
57   * simple content, i.e. elements that don't contain nested XML elements.
58   * The method must have three arguments:
59   * <ol>
60   * <li>an object of a concrete Java type (not java.lang.Object) that is "asked" to provide a value of the XML element
61   * being marshalled</li>
62   * <li>namespace URI as java.lang.String of the XML element being marshalled</li>
63   * <li>local name as java.lang.String of the XML element being marshalled</li>
64   * </ol>
65   * The method returns either null if the object model does not have any value corresponding to the namespace URI
66   * and local name (in this case the XML content will not contain this XML element) or the actual value of the XML element.
67   * </li>
68   * <li>a set of <code>getAttributeValue</code> methods
69   * This method is called on the object model provider by the framework for objects that represent XML elements with
70   * attributes.
71   * The method must have three arguments:
72   * <ol>
73   * <li>an object of a concrete Java type (not java.lang.Object) that is "asked" to provide a value for the XML attribute
74   * being marshalled</li>
75   * <li>namespace URI of the XML attribute being marshalled</li>
76   * <li>local name of the XML attribute being marshalled</li>
77   * </ol>
78   * The method returns either null if the object graph does not have any value corresponding to the namespace URI
79   * and local name (in this case the XML content will not contain this attribute) or the actual value of the XML attribute.
80   * </li>
81   * </ol>
82   *
83   * @author <a HREF="mailto:alex@jboss.org">Alexey Loubyansky</a>
84   * @version <tt>$Revision: 1958 $</tt>
85   */
86  public interface ObjectModelProvider
87  {
88     /**
89      * Called by the framework when a root XML element is marshalled.
90      *
91      * @param o            the root of the object graph
92      * @param ctx
93      * @param namespaceURI namespace URI of the root XML element being marshalled
94      * @param localName    local name of the root XML element being marshalled
95      * @return an object that represents the root XML element corresponding to the namespace URI and local name
96      */
97     Object   getRoot(Object   o, MarshallingContext ctx, String   namespaceURI, String   localName);
98  }
99
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags