SerializationContext


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;
60  import org.jboss.axis.MessageContext;
61  import org.w3c.dom.Element  ;
62  import org.xml.sax.Attributes  ;
63  
64  import javax.xml.namespace.QName  ;
65  import java.io.IOException  ;
66  import java.util.Stack  ;
67  
68  /**
69   * This interface describes the AXIS SerializationContext.
70   */
71  public interface SerializationContext extends javax.xml.rpc.encoding.SerializationContext  
72  {
73  
74     /**
75      * Serialize the indicated value as an element with the name
76      * indicated by elemQName.
77      * The attributes are additional attribute to be serialized on the element.
78      * The value is the object being serialized.  (It may be serialized
79      * directly or serialized as an mult-ref'd item)
80      * The value is an Object, which may be a wrapped primitive, the
81      * javaType is the actual unwrapped object type.
82      * The xmlType (if specified) is the QName of the type that is used to set
83      * xsi:type.  If not specified, xsi:type is set by using the javaType to
84      * find an appopriate xmlType from the TypeMappingRegistry.
85      * The sendNull flag indicates whether null values should be sent over the
86      * wire (default is to send such values with xsi:nil="true").
87      * The sendType flag indicates whether the xsi:type flag should be sent
88      * (default is true).
89      *
90      * @param elemQName  is the QName of the element
91      * @param attributes are additional attributes
92      * @param value      is the object to serialize
93      */
94     public void serialize(QName   elemQName,
95                           Attributes   attributes,
96                           Object   value)
97             throws IOException  ;
98  
99     /**
100     * Serialize the indicated value as an element with the name
101     * indicated by elemQName.
102     * The attributes are additional attribute to be serialized on the element.
103     * The value is the object being serialized.  (It may be serialized
104     * directly or serialized as an mult-ref'd item)
105     * The xmlType (if specified) is the QName of the type that is used to set
106     * xsi:type.
107     * The sendNull flag indicates whether null values should be sent over the
108     * wire (default is to send such values with xsi:nil="true").
109     * The sendType flag indicates whether the xsi:type flag should be sent
110     * (default is true).
111     *
112     * @param elemQName  is the QName of the element
113     * @param attributes are additional attributes
114     * @param value      is the object to serialize
115     * @param xmlType    is the qname of the type or null. (default is null)
116     * @param sendNull   determines whether to send null values. (default is true)
117     * @param sendType   determines whether to set xsi:type attribute. (default is true)
118     */
119    public void serialize(QName   elemQName,
120                          Attributes   attributes,
121                          Object   value,
122                          QName   xmlType,
123                          boolean sendNull,
124                          Boolean   sendType)
125            throws IOException  ;
126 
127 
128    /**
129     * Obtains the type attribute that should be serialized and returns the new list of Attributes
130     *
131     * @param attributes of the qname
132     * @param type       is the qname of the type
133     * @return new list of Attributes
134     */
135    public Attributes   setTypeAttribute(Attributes   attributes, QName   type);
136 
137    /**
138     * Convenience method to get the Serializer for a specific
139     * java type
140     *
141     * @param javaType is Class for a type to serialize
142     * @return Serializer
143     */
144    public Serializer getSerializerForJavaType(Class   javaType);
145 
146    /**
147     * Get whether the serialization should be pretty printed.
148     *
149     * @return true/false
150     */
151    public boolean getPretty();
152 
153    /**
154     * Indicate whether the serialization should be pretty printed.
155     *
156     * @param pretty true/false
157     */
158    public void setPretty(boolean pretty);
159 
160    /**
161     * Are we doing multirefs?
162     *
163     * @return true or false
164     */
165    public boolean getDoMultiRefs();
166 
167    /**
168     * Set whether we are doing multirefs.
169     *
170     * @param shouldDo true/false
171     */
172    public void setDoMultiRefs(boolean shouldDo);
173 
174    /**
175     * Set whether or not we should write XML declarations.
176     *
177     * @param sendDecl true/false
178     */
179    public void setSendDecl(boolean sendDecl);
180 
181    /**
182     * Get whether or not to write xsi:type attributes.
183     *
184     * @return true/false
185     */
186    public boolean shouldSendXSIType();
187 
188    /**
189     * Get the TypeMapping we're using.
190     *
191     * @return TypeMapping or null
192     */
193    public TypeMapping getTypeMapping();
194 
195    /**
196     * Get the TypeMappingRegistry we're using.
197     *
198     * @return TypeMapping or null
199     */
200    public TypeMappingRegistry getTypeMappingRegistry();
201 
202    /**
203     * Get a prefix for a namespace URI.  This method will ALWAYS
204     * return a valid prefix - if the given URI is already mapped in this
205     * serialization, we return the previous prefix.  If it is not mapped,
206     * we will add a new mapping and return a generated prefix of the form
207     * "ns&lt;num&gt;".
208     *
209     * @param uri is the namespace uri
210     * @return prefix
211     */
212    public String   getPrefixForURI(String   uri);
213 
214    /**
215     * Get a prefix for a namespace URI.  This method will ALWAYS
216     * return a valid prefix - if the given URI is already mapped in this
217     * serialization, we return the previous prefix.  If it is not mapped,
218     * we will add a new mapping and return a generated prefix of the form
219     * "ns&lt;num&gt;".
220     *
221     * @param uri           is the namespace uri
222     * @param defaultPrefix optional parameter which is the default prefix
223     * @return prefix
224     */
225    public String   getPrefixForURI(String   uri, String   defaultPrefix);
226 
227    /**
228     * Register prefix for the indicated uri
229     *
230     * @param prefix
231     * @param uri    is the namespace uri
232     */
233    public void registerPrefixForURI(String   prefix, String   uri);
234 
235    /**
236     * Get the current message.
237     *
238     * @return Message
239     */
240    public Message getCurrentMessage();
241 
242    /**
243     * Get the MessageContext we're operating with
244     */
245    public MessageContext getMessageContext();
246 
247    /**
248     * Convert QName to a string of the form <prefix>:<localpart>
249     *
250     * @param qName
251     * @return prefixed qname representation for serialization.
252     */
253    public String   qName2String(QName   qName);
254 
255    /**
256     * Convert attribute QName to a string of the form <prefix>:<localpart>
257     * There are some special rules for attributes
258     *
259     * @param qName
260     * @return prefixed qname representation for serialization.
261     */
262    public String   attributeQName2String(QName   qName);
263 
264    /**
265     * Get the QName associated with the specified class.
266     *
267     * @param cls Class of an object requiring serialization.
268     * @return appropriate QName associated with the class.
269     */
270    public QName   getQNameForClass(Class   cls);
271 
272    /**
273     * Indicates whether the object should be interpretted as a primitive
274     * for the purposes of multi-ref processing.  A primitive value
275     * is serialized directly instead of using id/href pairs.  Thus
276     * primitive serialization/deserialization is slightly faster.
277     *
278     * @param value to be serialized
279     * @return true/false
280     */
281    public boolean isPrimitive(Object   value);
282 
283    /**
284     * The serialize method uses hrefs to reference all non-primitive
285     * values.  These values are stored and serialized by calling
286     * outputMultiRefs after the serialize method completes.
287     */
288    public void outputMultiRefs() throws IOException  ;
289 
290    /**
291     * Output anything in the beginning.
292     *
293     * @throws IOException
294     */
295    public void startDocument() throws IOException  ;
296 
297    /**
298     * Output anything in the end.
299     *
300     * @throws IOException
301     */
302    public void endDocument() throws IOException  ;
303 
304    /**
305     * Writes (using the Writer) the start tag for element QName along with the
306     * indicated attributes and namespace mappings.
307     *
308     * @param qName      is the name of the element
309     * @param attributes are the attributes to write
310     */
311    public void startElement(QName   qName, Attributes   attributes) throws IOException  ;
312 
313    /**
314     * Writes the end element tag for the open element.
315     */
316    public void endElement() throws IOException  ;
317 
318    /**
319     * Convenience operation to write out (to Writer) the characters
320     * in p1 starting at index p2 for length p3.
321     *
322     * @param p1 character array to write
323     * @param p2 starting index in array
324     * @param p3 length to write
325     */
326    public void writeChars(char[] p1, int p2, int p3) throws IOException  ;
327 
328    /**
329     * Convenience operation to write out (to Writer) the String
330     *
331     * @param string is the String to write.
332     */
333    public void writeString(String   string) throws IOException  ;
334 
335    /**
336     * Convenience operation to write out (to Writer) the String
337     * properly encoded with xml entities (like &amp)
338     *
339     * @param string is the String to write.
340     */
341    public void writeSafeString(String   string) throws IOException  ;
342 
343    /**
344     * Output a DOM representation to a SerializationContext
345     *
346     * @param el is a DOM Element
347     */
348    public void writeDOMElement(Element   el) throws IOException  ;
349 
350    public String   getValueAsString(Object   value, QName   xmlType) throws IOException  ;
351 
352    /** Get the stack of element qnames.
353     */
354    public Stack   getElementStack();
355 
356    /**
357     * Get the currently prefered xmlType
358     * `* @return QName of xmlType or null
359     */
360    public QName   getCurrentXMLType();
361 
362    /**
363     * Get whether or not to write the default namespace.
364     *
365     * @return true/false
366     */
367    public boolean isNoDefaultNamespace();
368 
369    /**
370     * Set whether or not to write the default namespace.
371     */
372    public void setNoDefaultNamespace(boolean noDefaultNamespace);
373 }
374 
375 
376
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags