Deserializer


1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  
18  package org.apache.axis.encoding;
19  
20  import org.apache.axis.message.SOAPHandler;
21  import org.xml.sax.Attributes  ;
22  import org.xml.sax.SAXException  ;
23  
24  import javax.xml.namespace.QName  ;
25  import java.util.Vector  ;
26  
27  /**
28   * This interface describes the AXIS Deserializer.
29   * A compliant implementiation must extend either
30   * the AXIS SoapHandler (org.apache.axis.message.SOAPHandler)
31   * or the AXIS DeserializerImpl (org.apache.axis.encoding.DeserializerImpl)
32   *
33   * The DeserializerImpl provides a lot of the default behavior including the
34   * support for id/href.  So you may want to try extending it as opposed to
35   * extending SoapHandler.
36   *
37   * An Axis compliant Deserializer must provide one or more
38   * of the following methods:
39   *
40   * public &lt;constructor&gt;(Class javaType, QName xmlType)
41   * public &lt;constructo&gt;()
42   *
43   * This will allow for construction of generic factories that introspect the class
44   * to determine how to construct a deserializer.
45   * The xmlType, javaType arguments are filled in with the values known by the factory.
46   */
47  public interface Deserializer extends javax.xml.rpc.encoding.Deserializer  , Callback {
48  
49      /**
50       * Get the deserialized value.
51       * @return Object representing deserialized value or null
52       */
53      public Object   getValue();
54  
55      /**
56       * Set the deserialized value.
57       * @param value Object representing deserialized value
58       */
59      public void setValue(Object   value);
60  
61      /**
62       * If the deserializer has component values (like ArrayDeserializer)
63       * this method gets the specific component via the hint.
64       * The default implementation returns null.
65       * @return Object representing deserialized value or null
66       */
67      public Object   getValue(Object   hint);
68  
69      /**
70       * If the deserializer has component values (like ArrayDeserializer)
71       * this method sets the specific component via the hint.
72       * The default implementation does nothing.
73       * @param value Object representing deserialized value or null
74       */
75      public void setChildValue(Object   value, Object   hint) throws SAXException  ;
76  
77     /**
78       * In some circumstances an element may not have
79       * a type attribute, but a default type qname is known from
80       * information in the container.  For example,
81       * an element of an array may not have a type= attribute,
82       * so the default qname is the component type of the array.
83       * This method is used to communicate the default type information
84       * to the deserializer.
85       */
86      public void setDefaultType(QName   qName);
87      public QName   getDefaultType();
88  
89      /**
90       * For deserializers of non-primitives, the value may not be
91       * known until later (due to multi-referencing).  In such
92       * cases the deserializer registers Target object(s).  When
93       * the value is known, the set(value) will be invoked for
94       * each Target registered with the Deserializer.  The Target
95       * object abstracts the function of setting a target with a
96       * value.  See the Target interface for more info.
97       * @param target Target
98       */
99      public void registerValueTarget(Target target);
100 
101     /**
102      * Get the Value Targets of the Deserializer.
103      * @return Vector of Target objects or null
104      */
105     public Vector   getValueTargets();
106 
107     /**
108      * Remove the Value Targets of the Deserializer.
109      */
110     public void removeValueTargets() ;
111 
112    /**
113      * Move someone else's targets to our own (see DeserializationContext)
114      *
115      * The DeserializationContext only allows one Deserializer to
116      * wait for a unknown multi-ref'ed value.  So to ensure
117      * that all of the targets are updated, this method is invoked
118      * to copy the Target objects to the waiting Deserializer.
119      * @param other is the Deserializer to copy targets from.
120      */
121     public void moveValueTargets(Deserializer other);
122 
123     /**
124      * Some deserializers (ArrayDeserializer) require
125      * all of the component values to be known before the
126      * value is complete.
127      * (For the ArrayDeserializer this is important because
128      * the elements are stored in an ArrayList, and all values
129      * must be known before the ArrayList is converted into the
130      * expected array.
131      *
132      * This routine is used to indicate when the components are ready.
133      * The default (true) is useful for most Deserializers.
134      */
135     public boolean componentsReady();
136 
137     /**
138      * The valueComplete() method is invoked when the
139      * end tag of the element is read.  This results
140      * in the setting of all registered Targets (see
141      * registerValueTarget).
142      * Note that the valueComplete() only processes
143      * the Targets if componentReady() returns true.
144      * So if you override componentReady(), then your
145      * specific Deserializer will need to call valueComplete()
146      * when your components are ready (See ArrayDeserializer)
147      */
148     public void valueComplete() throws SAXException  ;
149 
150 
151     /**
152      * The following are the SAX specific methods.
153      * DeserializationImpl provides default behaviour, which
154      * in most cases is appropriate.
155      */
156 
157     /**
158      * This method is invoked when an element start tag is encountered.
159      * DeserializerImpl provides default behavior, which involves the following:
160      *   - directly handling the deserialization of a nill value
161      *   - handling the registration of the id value.
162      *   - handling the registration of a fixup if this element is an href.
163      *   - calling onStartElement to do the actual deserialization if not nill or href cases.
164      * @param namespace is the namespace of the element
165      * @param localName is the name of the element
166      * @param qName is the prefixed qName of the element
167      * @param attributes are the attributes on the element...used to get the type
168      * @param context is the DeserializationContext
169      *
170      * Normally a specific Deserializer (FooDeserializer) should extend DeserializerImpl.
171      * Here is the flow that will occur in such cases:
172      *   1) DeserializerImpl.startElement(...) will be called and do the id/href/nill stuff.
173      *   2) If real deserialization needs to take place DeserializerImpl.onStartElement will be
174      *      invoked, which will attempt to install the specific Deserializer (FooDeserializer)
175      *   3) The FooDeserializer.startElement(...) will be called to do the Foo specific stuff.
176      *      This results in a call to FooDeserializer.onStartElement(...) if startElement was
177      *      not overridden.
178      *   4) The onChildElement(...) method is called for each child element.  Nothing occurs
179      *      if not overridden.  The FooDeserializer.onStartChild(...) method should return
180      *      the deserializer for the child element.
181      *   5) When the end tag is reached, the endElement(..) method is invoked.  The default
182      *      behavior is to handle hrefs/ids, call onEndElement and then call the Deserializer
183      *      valueComplete method.
184      *
185      * So the methods that you potentially want to override are:
186      *   onStartElement, onStartChild, componentsReady, set(object, hint)
187      *
188      * You probably should not override startElement or endElement.
189      * If you need specific behaviour at the end of the element consider overriding
190      * onEndElement.
191      *
192      * See the pre-existing Deserializers for more information.
193      */
194     public void startElement(String   namespace, String   localName,
195                              String   qName, Attributes   attributes,
196                              DeserializationContext context)
197         throws SAXException  ;
198 
199     /**
200      * This method is invoked after startElement when the element requires
201      * deserialization (i.e. the element is not an href and the value is not nil.)
202      * DeserializerImpl provides default behavior, which simply
203      * involves obtaining a correct Deserializer and plugging its handler.
204      * @param namespace is the namespace of the element
205      * @param localName is the name of the element
206      * @param prefix is the prefix of the element
207      * @param attributes are the attributes on the element...used to get the type
208      * @param context is the DeserializationContext
209      */
210     public void onStartElement(String   namespace, String   localName,
211                              String   prefix, Attributes   attributes,
212                              DeserializationContext context)
213         throws SAXException  ;
214 
215     /**
216      * onStartChild is called on each child element.
217      * The default behavior supplied by DeserializationImpl is to do nothing.
218      * A specific deserializer may perform other tasks.  For example a
219      * BeanDeserializer will construct a deserializer for the indicated
220      * property and return it.
221      * @param namespace is the namespace of the child element
222      * @param localName is the local name of the child element
223      * @param prefix is the prefix used on the name of the child element
224      * @param attributes are the attributes of the child element
225      * @param context is the deserialization context.
226      * @return is a Deserializer to use to deserialize a child (must be
227      * a derived class of SOAPHandler) or null if no deserialization should
228      * be performed.
229      */
230     public SOAPHandler onStartChild(String   namespace, String   localName,
231                              String   prefix, Attributes   attributes,
232                              DeserializationContext context)
233         throws SAXException  ;
234 
235     /**
236      * endElement is called when the end element tag is reached.
237      * It handles href/id information for multi-ref processing
238      * and invokes the valueComplete() method of the deserializer
239      * which sets the targets with the deserialized value.
240      * @param namespace is the namespace of the child element
241      * @param localName is the local name of the child element
242      * @param context is the deserialization context
243      */
244     public void endElement(String   namespace, String   localName,
245                            DeserializationContext context)
246         throws SAXException  ;
247 
248    /**
249      * onEndElement is called by endElement.  It is not called
250      * if the element has an href.
251      * @param namespace is the namespace of the child element
252      * @param localName is the local name of the child element
253      * @param context is the deserialization context
254      */
255     public void onEndElement(String   namespace, String   localName,
256                            DeserializationContext context)
257         throws SAXException  ;
258 
259 }
260 
261 
262
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags