Deserializer


1   /*
2    * The Apache Software License, Version 1.1
3    *
4    *
5    * Copyright (c) 2001-2003 The Apache Software Foundation.  All rights
6    * reserved.
7    *
8    * Redistribution and use in source and binary forms, with or without
9    * modification, are permitted provided that the following conditions
10   * are met:
11   *
12   * 1. Redistributions of source code must retain the above copyright
13   *    notice, this list of conditions and the following disclaimer.
14   *
15   * 2. Redistributions in binary form must reproduce the above copyright
16   *    notice, this list of conditions and the following disclaimer in
17   *    the documentation and/or other materials provided with the
18   *    distribution.
19   *
20   * 3. The end-user documentation included with the redistribution,
21   *    if any, must include the following acknowledgment:
22   *       "This product includes software developed by the
23   *        Apache Software Foundation (http://www.apache.org/)."
24   *    Alternately, this acknowledgment may appear in the software itself,
25   *    if and wherever such third-party acknowledgments normally appear.
26   *
27   * 4. The names "Axis" and "Apache Software Foundation" must
28   *    not be used to endorse or promote products derived from this
29   *    software without prior written permission. For written
30   *    permission, please contact apache@apache.org.
31   *
32   * 5. Products derived from this software may not be called "Apache",
33   *    nor may "Apache" appear in their name, without prior written
34   *    permission of the Apache Software Foundation.
35   *
36   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47   * SUCH DAMAGE.
48   * ====================================================================
49   *
50   * This software consists of voluntary contributions made by many
51   * individuals on behalf of the Apache Software Foundation.  For more
52   * information on the Apache Software Foundation, please see
53   * <http://www.apache.org/>.
54   */
55  
56  
57  package org.jboss.axis.encoding;
58  
59  import org.jboss.axis.message.SOAPHandler;
60  import org.xml.sax.Attributes  ;
61  import org.xml.sax.SAXException  ;
62  
63  import javax.xml.namespace.QName  ;
64  import java.util.Vector  ;
65  
66  /**
67   * This interface describes the AXIS Deserializer.
68   * A compliant implementiation must extend either
69   * the AXIS SoapHandler (org.jboss.axis.message.SOAPHandler)
70   * or the AXIS DeserializerImpl (org.jboss.axis.encoding.DeserializerImpl)
71   * <p/>
72   * The DeserializerImpl provides a lot of the default behavior including the
73   * support for id/href.  So you may want to try extending it as opposed to
74   * extending SoapHandler.
75   * <p/>
76   * An Axis compliant Deserializer must provide one or more
77   * of the following methods:
78   * <p/>
79   * public &lt;constructor&gt;(Class javaType, QName xmlType)
80   * public &lt;constructo&gt;()
81   * <p/>
82   * This will allow for construction of generic factories that introspect the class
83   * to determine how to construct a deserializer.
84   * The xmlType, javaType arguments are filled in with the values known by the factory.
85   */
86  public interface Deserializer extends javax.xml.rpc.encoding.Deserializer  , Callback
87  {
88  
89     /**
90      * Get the deserialized value.
91      *
92      * @return Object representing deserialized value or null
93      */
94     public Object   getValue();
95  
96     /**
97      * Set the deserialized value.
98      *
99      * @param value Object representing deserialized value
100     */
101    public void setValue(Object   value);
102 
103    /**
104     * If the deserializer has component values (like ArrayDeserializer)
105     * this method gets the specific component via the hint.
106     * The default implementation returns null.
107     *
108     * @return Object representing deserialized value or null
109     */
110    public Object   getValue(Object   hint);
111 
112    /**
113     * If the deserializer has component values (like ArrayDeserializer)
114     * this method sets the specific component via the hint.
115     * The default implementation does nothing.
116     *
117     * @param value Object representing deserialized value or null
118     */
119    public void setChildValue(Object   value, Object   hint) throws SAXException  ;
120 
121    /**
122     * In some circumstances an element may not have
123     * a type attribute, but a default type qname is known from
124     * information in the container.  For example,
125     * an element of an array may not have a type= attribute,
126     * so the default qname is the component type of the array.
127     * This method is used to communicate the default type information
128     * to the deserializer.
129     */
130    public void setDefaultType(QName   qName);
131 
132    public QName   getDefaultType();
133 
134    /**
135     * For deserializers of non-primitives, the value may not be
136     * known until later (due to multi-referencing).  In such
137     * cases the deserializer registers Target object(s).  When
138     * the value is known, the set(value) will be invoked for
139     * each Target registered with the Deserializer.  The Target
140     * object abstracts the function of setting a target with a
141     * value.  See the Target interface for more info.
142     *
143     * @param target Target
144     */
145    public void registerValueTarget(Target target);
146 
147    /**
148     * Get the Value Targets of the Deserializer.
149     *
150     * @return Vector of Target objects or null
151     */
152    public Vector   getValueTargets();
153 
154    /**
155     * Remove the Value Targets of the Deserializer.
156     */
157    public void removeValueTargets();
158 
159    /**
160     * Move someone else's targets to our own (see DeserializationContext)
161     * <p/>
162     * The DeserializationContext only allows one Deserializer to
163     * wait for a unknown multi-ref'ed value.  So to ensure
164     * that all of the targets are updated, this method is invoked
165     * to copy the Target objects to the waiting Deserializer.
166     *
167     * @param other is the Deserializer to copy targets from.
168     */
169    public void moveValueTargets(Deserializer other);
170 
171    /**
172     * Some deserializers (ArrayDeserializer) require
173     * all of the component values to be known before the
174     * value is complete.
175     * (For the ArrayDeserializer this is important because
176     * the elements are stored in an ArrayList, and all values
177     * must be known before the ArrayList is converted into the
178     * expected array.
179     * <p/>
180     * This routine is used to indicate when the components are ready.
181     * The default (true) is useful for most Deserializers.
182     */
183    public boolean componentsReady();
184 
185    /**
186     * The valueComplete() method is invoked when the
187     * end tag of the element is read.  This results
188     * in the setting of all registered Targets (see
189     * registerValueTarget).
190     * Note that the valueComplete() only processes
191     * the Targets if componentReady() returns true.
192     * So if you override componentReady(), then your
193     * specific Deserializer will need to call valueComplete()
194     * when your components are ready (See ArrayDeserializer)
195     */
196    public void valueComplete() throws SAXException  ;
197 
198 
199    /**
200     * The following are the SAX specific methods.
201     * DeserializationImpl provides default behaviour, which
202     * in most cases is appropriate.
203     */
204 
205    /**
206     * This method is invoked when an element start tag is encountered.
207     * DeserializerImpl provides default behavior, which involves the following:
208     * - directly handling the deserialization of a nill value
209     * - handling the registration of the id value.
210     * - handling the registration of a fixup if this element is an href.
211     * - calling onStartElement to do the actual deserialization if not nill or href cases.
212     *
213     * @param namespace  is the namespace of the element
214     * @param localName  is the name of the element
215     * @param qName      is the prefixed qName of the element
216     * @param attributes are the attributes on the element...used to get the type
217     * @param context    is the DeserializationContext
218     *                   <p/>
219     *                   Normally a specific Deserializer (FooDeserializer) should extend DeserializerImpl.
220     *                   Here is the flow that will occur in such cases:
221     *                   1) DeserializerImpl.startElement(...) will be called and do the id/href/nill stuff.
222     *                   2) If real deserialization needs to take place DeserializerImpl.onStartElement will be
223     *                   invoked, which will attempt to install the specific Deserializer (FooDeserializer)
224     *                   3) The FooDeserializer.startElement(...) will be called to do the Foo specific stuff.
225     *                   This results in a call to FooDeserializer.onStartElement(...) if startElement was
226     *                   not overridden.
227     *                   4) The onChildElement(...) method is called for each child element.  Nothing occurs
228     *                   if not overridden.  The FooDeserializer.onStartChild(...) method should return
229     *                   the deserializer for the child element.
230     *                   5) When the end tag is reached, the endElement(..) method is invoked.  The default
231     *                   behavior is to handle hrefs/ids, call onEndElement and then call the Deserializer
232     *                   valueComplete method.
233     *                   <p/>
234     *                   So the methods that you potentially want to override are:
235     *                   onStartElement, onStartChild, componentsReady, set(object, hint)
236     *                   <p/>
237     *                   You probably should not override startElement or endElement.
238     *                   If you need specific behaviour at the end of the element consider overriding
239     *                   onEndElement.
240     *                   <p/>
241     *                   See the pre-existing Deserializers for more information.
242     */
243    public void startElement(String   namespace, String   localName,
244                             String   qName, Attributes   attributes,
245                             DeserializationContext context)
246            throws SAXException  ;
247 
248    /**
249     * This method is invoked after startElement when the element requires
250     * deserialization (i.e. the element is not an href and the value is not nil.)
251     * DeserializerImpl provides default behavior, which simply
252     * involves obtaining a correct Deserializer and plugging its handler.
253     *
254     * @param namespace  is the namespace of the element
255     * @param localName  is the name of the element
256     * @param prefix     is the prefix of the element
257     * @param attributes are the attributes on the element...used to get the type
258     * @param context    is the DeserializationContext
259     */
260    public void onStartElement(String   namespace, String   localName,
261                               String   prefix, Attributes   attributes,
262                               DeserializationContext context)
263            throws SAXException  ;
264 
265    /**
266     * onStartChild is called on each child element.
267     * The default behavior supplied by DeserializationImpl is to do nothing.
268     * A specific deserializer may perform other tasks.  For example a
269     * BeanDeserializer will construct a deserializer for the indicated
270     * property and return it.
271     *
272     * @param namespace  is the namespace of the child element
273     * @param localName  is the local name of the child element
274     * @param prefix     is the prefix used on the name of the child element
275     * @param attributes are the attributes of the child element
276     * @param context    is the deserialization context.
277     * @return is a Deserializer to use to deserialize a child (must be
278     *         a derived class of SOAPHandler) or null if no deserialization should
279     *         be performed.
280     */
281    public SOAPHandler onStartChild(String   namespace, String   localName,
282                                    String   prefix, Attributes   attributes,
283                                    DeserializationContext context)
284            throws SAXException  ;
285 
286    /**
287     * endElement is called when the end element tag is reached.
288     * It handles href/id information for multi-ref processing
289     * and invokes the valueComplete() method of the deserializer
290     * which sets the targets with the deserialized value.
291     *
292     * @param namespace is the namespace of the child element
293     * @param localName is the local name of the child element
294     * @param context   is the deserialization context
295     */
296    public void endElement(String   namespace, String   localName,
297                           DeserializationContext context)
298            throws SAXException  ;
299 
300    /**
301     * onEndElement is called by endElement.  It is not called
302     * if the element has an href.
303     *
304     * @param namespace is the namespace of the child element
305     * @param localName is the local name of the child element
306     * @param context   is the deserialization context
307     */
308    public void onEndElement(String   namespace, String   localName,
309                             DeserializationContext context)
310            throws SAXException  ;
311 
312 }
313 
314 
315
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags