001: /*
002: Copyright (c) 2002-2006, Dennis M. Sosnoski.
003: All rights reserved.
004:
005: Redistribution and use in source and binary forms, with or without modification,
006: are permitted provided that the following conditions are met:
007:
008: * Redistributions of source code must retain the above copyright notice, this
009: list of conditions and the following disclaimer.
010: * Redistributions in binary form must reproduce the above copyright notice,
011: this list of conditions and the following disclaimer in the documentation
012: and/or other materials provided with the distribution.
013: * Neither the name of JiBX nor the names of its contributors may be used
014: to endorse or promote products derived from this software without specific
015: prior written permission.
016:
017: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
018: ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
019: WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
020: DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
021: ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
022: (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
023: LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
024: ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
025: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
026: SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
027: */
028:
029: package org.jibx.runtime;
030:
031: import java.io.OutputStream;
032: import java.io.Writer;
033:
034: /**
035: * User interface for serializer to XML. This provides methods used to set up
036: * and control the marshalling process, as well as access to the marshalling
037: * object stack while marshalling.
038: *
039: * @author Dennis M. Sosnoski
040: */
041: public interface IMarshallingContext {
042: /**
043: * Set output stream with encoding and escaper. This forces handling of the
044: * output stream to use the Java character encoding support with the
045: * supplied escaper.
046: *
047: * @param outs stream for document data output
048: * @param enc document output encoding, or <code>null</code> uses UTF-8
049: * default
050: * @param esc escaper for writing characters to stream
051: * @throws JiBXException if error setting output
052: */
053: void setOutput(OutputStream outs, String enc, ICharacterEscaper esc)
054: throws JiBXException;
055:
056: /**
057: * Set output stream and encoding.
058: *
059: * @param outs stream for document data output
060: * @param enc document output encoding, or <code>null</code> uses UTF-8
061: * default
062: * @throws JiBXException if error setting output
063: */
064: void setOutput(OutputStream outs, String enc) throws JiBXException;
065:
066: /**
067: * Set output writer and escaper.
068: *
069: * @param outw writer for document data output
070: * @param esc escaper for writing characters
071: */
072: void setOutput(Writer outw, ICharacterEscaper esc);
073:
074: /**
075: * Set output writer. This assumes the standard UTF-8 encoding.
076: *
077: * @param outw writer for document data output
078: */
079: void setOutput(Writer outw);
080:
081: /**
082: * Get the writer being used for output.
083: *
084: * @return XML writer used for output
085: */
086: IXMLWriter getXmlWriter();
087:
088: /**
089: * Set the writer being used for output.
090: *
091: * @param xwrite XML writer used for output
092: */
093: void setXmlWriter(IXMLWriter xwrite);
094:
095: /**
096: * Get current nesting indent spaces. This returns the number of spaces used
097: * to show indenting, if used.
098: *
099: * @return number of spaces indented per level, or negative if indentation
100: * disabled
101: */
102: int getIndent();
103:
104: /**
105: * Set nesting indent spaces. This is advisory only, and implementations of
106: * this interface are free to ignore it. The intent is to indicate that the
107: * generated output should use indenting to illustrate element nesting.
108: *
109: * @param count number of spaces to indent per level, or disable
110: * indentation if negative
111: */
112: void setIndent(int count);
113:
114: /**
115: * Set nesting indentation. 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 character to indent per level, or disable
120: * indentation if negative (zero means new line only)
121: * @param newline sequence of characters used for a line ending
122: * (<code>null</code> means use the single character '\n')
123: * @param indent whitespace character used for indentation
124: */
125: public void setIndent(int count, String newline, char indent);
126:
127: /**
128: * Reset to initial state for reuse. The context is serially reusable,
129: * as long as this method is called to clear any retained state information
130: * between uses. It is automatically called when output is set.
131: */
132: void reset();
133:
134: /**
135: * Start document, writing the XML declaration. This can only be validly
136: * called immediately following one of the set output methods; otherwise the
137: * output document will be corrupt.
138: *
139: * @param enc document encoding, <code>null</code> uses UTF-8 default
140: * @param alone standalone document flag, <code>null</code> if not
141: * specified
142: * @throws JiBXException on any error (possibly wrapping other exception)
143: */
144: void startDocument(String enc, Boolean alone) throws JiBXException;
145:
146: /**
147: * Start document with output stream and encoding. The effect is the same
148: * as from first setting the output stream and encoding, then making the
149: * call to start document.
150: *
151: * @param enc document encoding, <code>null</code> uses UTF-8 default
152: * @param alone standalone document flag, <code>null</code> if not
153: * specified
154: * @param outs stream for document data output
155: * @throws JiBXException on any error (possibly wrapping other exception)
156: */
157: void startDocument(String enc, Boolean alone, OutputStream outs)
158: throws JiBXException;
159:
160: /**
161: * Start document with writer. The effect is the same as from first
162: * setting the writer, then making the call to start document.
163: *
164: * @param enc document encoding, <code>null</code> uses UTF-8 default
165: * @param alone standalone document flag, <code>null</code> if not
166: * specified
167: * @param outw writer for document data output
168: * @throws JiBXException on any error (possibly wrapping other exception)
169: */
170: void startDocument(String enc, Boolean alone, Writer outw)
171: throws JiBXException;
172:
173: /**
174: * End document. Finishes all output and closes the document. Note that if
175: * this is called with an imcomplete marshalling the result will not be
176: * well-formed XML.
177: *
178: * @throws JiBXException on any error (possibly wrapping other exception)
179: */
180: void endDocument() throws JiBXException;
181:
182: /**
183: * Marshal document from root object without XML declaration. This can only
184: * be validly called immediately following one of the set output methods;
185: * otherwise the output document will be corrupt. The effect of this method
186: * is the same as the sequence of a call to marshal the root object using
187: * this context followed by a call to {@link #endDocument}.
188: *
189: * @param root object at root of structure to be marshalled, which must have
190: * a top-level mapping in the binding
191: * @throws JiBXException on any error (possibly wrapping other exception)
192: */
193: public void marshalDocument(Object root) throws JiBXException;
194:
195: /**
196: * Marshal document from root object. This can only be validly called
197: * immediately following one of the set output methods; otherwise the output
198: * document will be corrupt. The effect of this method is the same as the
199: * sequence of a call to {@link #startDocument}, a call to marshal the root
200: * object using this context, and finally a call to {@link #endDocument}.
201: *
202: * @param root object at root of structure to be marshalled, which must have
203: * a top-level mapping in the binding
204: * @param enc document encoding, <code>null</code> uses UTF-8 default
205: * @param alone standalone document flag, <code>null</code> if not
206: * specified
207: * @throws JiBXException on any error (possibly wrapping other exception)
208: */
209: public void marshalDocument(Object root, String enc, Boolean alone)
210: throws JiBXException;
211:
212: /**
213: * Marshal document from root object to output stream with encoding. The
214: * effect of this method is the same as the sequence of a call to {@link
215: * #startDocument}, a call to marshal the root object using this context,
216: * and finally a call to {@link #endDocument}.
217: *
218: * @param root object at root of structure to be marshalled, which must have
219: * a top-level mapping in the binding
220: * @param enc document encoding, <code>null</code> uses UTF-8 default
221: * @param alone standalone document flag, <code>null</code> if not
222: * specified
223: * @param outs stream for document data output
224: * @throws JiBXException on any error (possibly wrapping other exception)
225: */
226: public void marshalDocument(Object root, String enc, Boolean alone,
227: OutputStream outs) throws JiBXException;
228:
229: /**
230: * Marshal document from root object to writer. The effect of this method
231: * is the same as the sequence of a call to {@link #startDocument}, a call
232: * to marshal the root object using this context, and finally a call to
233: * {@link #endDocument}.
234: *
235: * @param root object at root of structure to be marshalled, which must have
236: * a top-level mapping in the binding
237: * @param enc document encoding, <code>null</code> uses UTF-8 default
238: * @param alone standalone document flag, <code>null</code> if not
239: * specified
240: * @param outw writer for document data output
241: * @throws JiBXException on any error (possibly wrapping other exception)
242: */
243: public void marshalDocument(Object root, String enc, Boolean alone,
244: Writer outw) throws JiBXException;
245:
246: /**
247: * Set a user context object. This context object is not used directly by
248: * JiBX, but can be accessed by all types of user extension methods. The
249: * context object is automatically cleared by the {@link #reset()} method,
250: * so to make use of this you need to first call the appropriate version of
251: * the <code>setOutput()</code> method, then this method, and finally one of
252: * the <code>marshalDocument</code> methods which uses the previously-set
253: * output (not the ones which take a stream or writer as parameter, since
254: * they call <code>setOutput()</code> themselves).
255: *
256: * @param obj user context object, or <code>null</code> if clearing existing
257: * context object
258: * @see #getUserContext()
259: */
260: public void setUserContext(Object obj);
261:
262: /**
263: * Get the user context object.
264: *
265: * @return user context object, or <code>null</code> if no context object
266: * set
267: * @see #setUserContext(Object)
268: */
269: public Object getUserContext();
270:
271: /**
272: * Push created object to marshalling stack. This must be called before
273: * beginning the marshalling of the object. It is only called for objects
274: * with structure, not for those converted directly to and from text.
275: *
276: * @param obj object being marshalled
277: */
278: public void pushObject(Object obj);
279:
280: /**
281: * Pop marshalled object from stack.
282: *
283: * @throws JiBXException if no object on stack
284: */
285: public void popObject() throws JiBXException;
286:
287: /**
288: * Get current marshalling object stack depth. This allows tracking
289: * nested calls to marshal one object while in the process of marshalling
290: * another object. The bottom item on the stack is always the root object
291: * of the marshalling.
292: *
293: * @return number of objects in marshalling stack
294: */
295: public int getStackDepth();
296:
297: /**
298: * Get object from marshalling stack. This stack allows tracking nested
299: * calls to marshal one object while in the process of marshalling
300: * another object. The bottom item on the stack is always the root object
301: * of the marshalling.
302: *
303: * @param depth object depth in stack to be retrieved (must be in the range
304: * of zero to the current depth minus one).
305: * @return object from marshalling stack
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: public Object getStackTop();
316:
317: /**
318: * Find the marshaller for a particular class index
319: * in the current context.
320: *
321: * @param index class index for marshalling definition
322: * @param name fully qualified name of class to be marshalled (used only
323: * for validation)
324: * @return marshalling handler for class
325: * @throws JiBXException on any error (possibly wrapping other exception)
326: */
327: public IMarshaller getMarshaller(int index, String name)
328: throws JiBXException;
329: }
|