Source code: org/apache/axis/encoding/Deserializer.java
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 <constructor>(Class javaType, QName xmlType)
41 * public <constructo>()
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