IMarshallingContext


1   /*
2   Copyright (c) 2002-2004, Dennis M. Sosnoski.
3   All rights reserved.
4   
5   Redistribution and use in source and binary forms, with or without modification,
6   are permitted provided that the following conditions are met:
7   
8    * Redistributions of source code must retain the above copyright notice, this
9      list of conditions and the following disclaimer.
10   * Redistributions in binary form must reproduce the above copyright notice,
11     this list of conditions and the following disclaimer in the documentation
12     and/or other materials provided with the distribution.
13   * Neither the name of JiBX nor the names of its contributors may be used
14     to endorse or promote products derived from this software without specific
15     prior written permission.
16  
17  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
18  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
19  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
20  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
21  ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
24  ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
26  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27  */
28  
29  package org.jibx.runtime;
30  
31  import java.io.OutputStream  ;
32  import java.io.Writer  ;
33  
34  /**
35   * User interface for serializer to XML. This provides methods used to set up
36   * and control the marshalling process, as well as access to the marshalling
37   * object stack while marshalling.
38   *
39   * @author Dennis M. Sosnoski
40   * @version 1.0
41   */
42  
43  public interface IMarshallingContext
44  {
45      /**
46       * Set output stream with encoding and escaper. This forces handling of the
47       * output stream to use the Java character encoding support with the
48       * supplied escaper.
49       *
50       * @param outs stream for document data output
51       * @param enc document output encoding, or <code>null</code> uses UTF-8
52       * default
53       * @param esc escaper for writing characters to stream
54       * @throws JiBXException if error setting output
55       */
56       
57      void setOutput(OutputStream   outs, String   enc, ICharacterEscaper esc)
58          throws JiBXException;
59      
60      /**
61       * Set output stream and encoding.
62       *
63       * @param outs stream for document data output
64       * @param enc document output encoding, or <code>null</code> uses UTF-8
65       * default
66       * @throws JiBXException if error setting output
67       */
68       
69      void setOutput(OutputStream   outs, String   enc) throws JiBXException;
70      
71      /**
72       * Set output writer and escaper.
73       *
74       * @param outw writer for document data output
75       * @param esc escaper for writing characters
76       */
77      
78      void setOutput(Writer   outw, ICharacterEscaper esc);
79      
80      /**
81       * Set output writer. This assumes the standard UTF-8 encoding.
82       *
83       * @param outw writer for document data output
84       */
85      
86      void setOutput(Writer   outw);
87  
88      /**
89       * Get the writer being used for output.
90       *
91       * @return XML writer used for output
92       */
93  
94      IXMLWriter getXmlWriter();
95  
96      /**
97       * Set the writer being used for output.
98       *
99       * @param xwrite XML writer used for output
100      */
101 
102     void setXmlWriter(IXMLWriter xwrite);
103     
104     /**
105      * Get current nesting indent spaces. This returns the number of spaces used
106      * to show indenting, if used.
107      *
108      * @return number of spaces indented per level, or negative if indentation
109      * disabled
110      */
111     
112     int getIndent();
113     
114     /**
115      * Set nesting indent spaces. This is advisory only, and implementations of
116      * this interface are free to ignore it. The intent is to indicate that the
117      * generated output should use indenting to illustrate element nesting.
118      *
119      * @param count number of spaces to indent per level, or disable
120      * indentation if negative
121      */
122     
123     void setIndent(int count);
124     
125     /**
126      * Set nesting indentation. This is advisory only, and implementations of
127      * this interface are free to ignore it. The intent is to indicate that the
128      * generated output should use indenting to illustrate element nesting.
129      *
130      * @param count number of character to indent per level, or disable
131      * indentation if negative (zero means new line only)
132      * @param newline sequence of characters used for a line ending
133      * (<code>null</code> means use the single character '\n')
134      * @param indent whitespace character used for indentation
135      */
136     
137     public void setIndent(int count, String   newline, char indent);
138         
139     /**
140      * Reset to initial state for reuse. The context is serially reusable,
141      * as long as this method is called to clear any retained state information
142      * between uses. It is automatically called when output is set.
143      */
144     
145     void reset();
146     
147     /**
148      * Start document, writing the XML declaration. This can only be validly
149      * called immediately following one of the set output methods; otherwise the
150      * output document will be corrupt.
151      *
152      * @param enc document encoding, <code>null</code> uses UTF-8 default
153      * @param alone standalone document flag, <code>null</code> if not
154      * specified
155      * @throws JiBXException on any error (possibly wrapping other exception)
156      */
157 
158     void startDocument(String   enc, Boolean   alone) throws JiBXException;
159     
160     /**
161      * Start document with output stream and encoding. The effect is the same
162      * as from first setting the output stream and encoding, then making the
163      * call to start document.
164      *
165      * @param enc document encoding, <code>null</code> uses UTF-8 default
166      * @param alone standalone document flag, <code>null</code> if not
167      * specified
168      * @param outs stream for document data output
169      * @throws JiBXException on any error (possibly wrapping other exception)
170      */
171 
172     void startDocument(String   enc, Boolean   alone, OutputStream   outs)
173         throws JiBXException;
174     
175     /**
176      * Start document with writer. The effect is the same as from first
177      * setting the writer, then making the call to start document.
178      *
179      * @param enc document encoding, <code>null</code> uses UTF-8 default
180      * @param alone standalone document flag, <code>null</code> if not
181      * specified
182      * @param outw writer for document data output
183      * @throws JiBXException on any error (possibly wrapping other exception)
184      */
185 
186     void startDocument(String   enc, Boolean   alone, Writer   outw)
187         throws JiBXException;
188     
189     /**
190      * End document. Finishes all output and closes the document. Note that if
191      * this is called with an imcomplete marshalling the result will not be
192      * well-formed XML.
193      *
194      * @throws JiBXException on any error (possibly wrapping other exception)
195      */
196 
197     void endDocument() throws JiBXException;
198     
199     /**
200      * Marshal document from root object without XML declaration. This can only
201      * be validly called immediately following one of the set output methods;
202      * otherwise the output document will be corrupt. The effect of this method
203      * is the same as the sequence of a call to marshal the root object using
204      * this context followed by a call to {@link #endDocument}.
205      *
206      * @param root object at root of structure to be marshalled, which must have
207      * a top-level mapping in the binding
208      * @throws JiBXException on any error (possibly wrapping other exception)
209      */
210 
211     public void marshalDocument(Object   root) throws JiBXException;
212     
213     /**
214      * Marshal document from root object. This can only be validly called
215      * immediately following one of the set output methods; otherwise the output
216      * document will be corrupt. The effect of this method is the same as the
217      * sequence of a call to {@link #startDocument}, a call to marshal the root
218      * object using this context, and finally a call to {@link #endDocument}.
219      *
220      * @param root object at root of structure to be marshalled, which must have
221      * a top-level mapping in the binding
222      * @param enc document encoding, <code>null</code> uses UTF-8 default
223      * @param alone standalone document flag, <code>null</code> if not
224      * specified
225      * @throws JiBXException on any error (possibly wrapping other exception)
226      */
227 
228     public void marshalDocument(Object   root, String   enc, Boolean   alone)
229         throws JiBXException;
230     
231     /**
232      * Marshal document from root object to output stream with encoding. The
233      * effect of this method is the same as the sequence of a call to {@link
234      * #startDocument}, a call to marshal the root object using this context,
235      * and finally a call to {@link #endDocument}.
236      *
237      * @param root object at root of structure to be marshalled, which must have
238      * a top-level mapping in the binding
239      * @param enc document encoding, <code>null</code> uses UTF-8 default
240      * @param alone standalone document flag, <code>null</code> if not
241      * specified
242      * @param outs stream for document data output
243      * @throws JiBXException on any error (possibly wrapping other exception)
244      */
245 
246     public void marshalDocument(Object   root, String   enc, Boolean   alone,
247         OutputStream   outs) throws JiBXException;
248     
249     /**
250      * Marshal document from root object to writer. The effect of this method
251      * is the same as the sequence of a call to {@link #startDocument}, a call
252      * to marshal the root object using this context, and finally a call to
253      * {@link #endDocument}.
254      *
255      * @param root object at root of structure to be marshalled, which must have
256      * a top-level mapping in the binding
257      * @param enc document encoding, <code>null</code> uses UTF-8 default
258      * @param alone standalone document flag, <code>null</code> if not
259      * specified
260      * @param outw writer for document data output
261      * @throws JiBXException on any error (possibly wrapping other exception)
262      */
263 
264     public void marshalDocument(Object   root, String   enc, Boolean   alone,
265         Writer   outw) throws JiBXException;
266 
267     /**
268      * Push created object to marshalling stack. This must be called before
269      * beginning the marshalling of the object. It is only called for objects
270      * with structure, not for those converted directly to and from text.
271      *
272      * @param obj object being marshalled
273      */
274 
275     public void pushObject(Object   obj);
276 
277     /**
278      * Pop marshalled object from stack.
279      *
280      * @throws JiBXException if no object on stack
281      */
282 
283     public void popObject() throws JiBXException;
284     
285     /**
286      * Get current marshalling object stack depth. This allows tracking
287      * nested calls to marshal one object while in the process of marshalling
288      * another object. The bottom item on the stack is always the root object
289      * of the marshalling.
290      *
291      * @return number of objects in marshalling stack
292      */
293 
294     public int getStackDepth();
295     
296     /**
297      * Get object from marshalling stack. This stack allows tracking nested
298      * calls to marshal one object while in the process of marshalling
299      * another object. The bottom item on the stack is always the root object
300      * of the marshalling.
301      *
302      * @param depth object depth in stack to be retrieved (must be in the range
303      * of zero to the current depth minus one).
304      * @return object from marshalling stack
305      */
306 
307     public Object   getStackObject(int depth);
308     
309     /**
310      * Get top object on marshalling stack. This is safe to call even when no
311      * objects are on the stack.
312      *
313      * @return object from marshalling stack, or <code>null</code> if none
314      */
315 
316     public Object   getStackTop();
317     
318     /**
319      * Find the marshaller for a particular class index
320      * in the current context.
321      *
322      * @param index class index for marshalling definition
323      * @param name fully qualified name of class to be marshalled (used only
324      * for validation)
325      * @return marshalling handler for class
326      * @throws JiBXException on any error (possibly wrapping other exception)
327      */
328     
329     public IMarshaller getMarshaller(int index, String   name)
330         throws JiBXException;
331 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags