KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jibx > runtime > 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 JavaDoc;
32 import java.io.Writer JavaDoc;
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 JavaDoc outs, String JavaDoc 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 JavaDoc outs, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc enc, Boolean JavaDoc 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 JavaDoc enc, Boolean JavaDoc alone, OutputStream JavaDoc 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 JavaDoc enc, Boolean JavaDoc alone, Writer JavaDoc 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 JavaDoc 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 JavaDoc root, String JavaDoc enc, Boolean JavaDoc 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 JavaDoc root, String JavaDoc enc, Boolean JavaDoc alone,
247         OutputStream JavaDoc 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 JavaDoc root, String JavaDoc enc, Boolean JavaDoc alone,
265         Writer JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc name)
330         throws JiBXException;
331 }
Popular Tags