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.InputStream;
032: import java.io.Reader;
033:
034: /**
035: * User interface for deserializer from XML. This provides methods used to set
036: * up and control the marshalling process, as well as access to the
037: * unmarshalling object stack while unmarshalling.
038: *
039: * @author Dennis M. Sosnoski
040: */
041: public interface IUnmarshallingContext {
042:
043: /**
044: * Set document to be parsed from stream.
045: *
046: * @param ins stream supplying document data
047: * @param enc document input encoding, or <code>null</code> if to be
048: * determined by parser
049: * @throws JiBXException if error creating parser
050: */
051: void setDocument(InputStream ins, String enc) throws JiBXException;
052:
053: /**
054: * Set document to be parsed from reader.
055: *
056: * @param rdr reader supplying document data
057: * @throws JiBXException if error creating parser
058: */
059: void setDocument(Reader rdr) throws JiBXException;
060:
061: /**
062: * Set named document to be parsed from stream.
063: *
064: * @param ins stream supplying document data
065: * @param name document name
066: * @param enc document input encoding, or <code>null</code> if to be
067: * determined by parser
068: * @throws JiBXException if error creating parser
069: */
070: void setDocument(InputStream ins, String name, String enc)
071: throws JiBXException;
072:
073: /**
074: * Set named document to be parsed from reader.
075: *
076: * @param rdr reader supplying document data
077: * @param name document name
078: * @throws JiBXException if error creating parser
079: */
080: void setDocument(Reader rdr, String name) throws JiBXException;
081:
082: /**
083: * Reset unmarshalling information. This releases all references to
084: * unmarshalled objects and prepares the context for potential reuse.
085: * It is automatically called when input is set.
086: */
087: void reset();
088:
089: /**
090: * Unmarshal the current element. If not currently positioned at a start
091: * or end tag this first advances the parse to the next start or end tag.
092: * There must be an unmarshalling defined for the current element, and this
093: * unmarshalling is used to build an object from that element.
094: *
095: * @return unmarshalled object from element
096: * @throws JiBXException on any error (possibly wrapping other exception)
097: */
098: Object unmarshalElement() throws JiBXException;
099:
100: /**
101: * Unmarshal document from stream to object. The effect of this is the same
102: * as if {@link #setDocument} were called, followed by {@link
103: * #unmarshalElement}
104: *
105: * @param ins stream supplying document data
106: * @param enc document input encoding, or <code>null</code> if to be
107: * determined by parser
108: * @return unmarshalled object
109: * @throws JiBXException if error creating parser
110: */
111: Object unmarshalDocument(InputStream ins, String enc)
112: throws JiBXException;
113:
114: /**
115: * Unmarshal document from reader to object. The effect of this is the same
116: * as if {@link #setDocument} were called, followed by {@link
117: * #unmarshalElement}
118: *
119: * @param rdr reader supplying document data
120: * @return unmarshalled object
121: * @throws JiBXException if error creating parser
122: */
123: Object unmarshalDocument(Reader rdr) throws JiBXException;
124:
125: /**
126: * Unmarshal named document from stream to object. The effect of this is the
127: * same as if {@link #setDocument} were called, followed by {@link
128: * #unmarshalElement}
129: *
130: * @param ins stream supplying document data
131: * @param name document name
132: * @param enc document input encoding, or <code>null</code> if to be
133: * determined by parser
134: * @return unmarshalled object
135: * @throws JiBXException if error creating parser
136: */
137: Object unmarshalDocument(InputStream ins, String name, String enc)
138: throws JiBXException;
139:
140: /**
141: * Unmarshal named document from reader to object. The effect of this is the
142: * same as if {@link #setDocument} were called, followed by {@link
143: * #unmarshalElement}
144: *
145: * @param rdr reader supplying document data
146: * @param name document name
147: * @return unmarshalled object
148: * @throws JiBXException if error creating parser
149: */
150: Object unmarshalDocument(Reader rdr, String name)
151: throws JiBXException;
152:
153: /**
154: * Return the supplied document name.
155: *
156: * @return supplied document name (<code>null</code> if none)
157: */
158: public String getDocumentName();
159:
160: /**
161: * Check if next tag is start of element. If not currently positioned at a
162: * start or end tag this first advances the parse to the next start or end
163: * tag.
164: *
165: * @param ns namespace URI for expected element (may be <code>null</code>
166: * or the empty string for the empty namespace)
167: * @param name element name expected
168: * @return <code>true</code> if at start of element with supplied name,
169: * <code>false</code> if not
170: * @throws JiBXException on any error (possibly wrapping other exception)
171: */
172: public boolean isAt(String ns, String name) throws JiBXException;
173:
174: /**
175: * Check if next tag is a start tag. If not currently positioned at a
176: * start or end tag this first advances the parse to the next start or
177: * end tag.
178: *
179: * @return <code>true</code> if at start of element, <code>false</code> if
180: * at end
181: * @throws JiBXException on any error (possibly wrapping other exception)
182: */
183: public boolean isStart() throws JiBXException;
184:
185: /**
186: * Check if next tag is an end tag. If not currently positioned at a
187: * start or end tag this first advances the parse to the next start or
188: * end tag.
189: *
190: * @return <code>true</code> if at end of element, <code>false</code> if
191: * at start
192: * @throws JiBXException on any error (possibly wrapping other exception)
193: */
194: public boolean isEnd() throws JiBXException;
195:
196: /**
197: * Find the unmarshaller for a particular class index in the current
198: * context.
199: *
200: * @param index class index for unmarshalling definition
201: * @return unmarshalling handler for class
202: * @throws JiBXException if unable to create unmarshaller
203: */
204: public IUnmarshaller getUnmarshaller(int index)
205: throws JiBXException;
206:
207: /**
208: * Set a user context object. This context object is not used directly by
209: * JiBX, but can be accessed by all types of user extension methods. The
210: * context object is automatically cleared by the {@link #reset()} method,
211: * so to make use of this you need to first call the appropriate version of
212: * the <code>setDocument()</code> method, then this method, and finally the
213: * {@link #unmarshalElement} method.
214: *
215: * @param obj user context object, or <code>null</code> if clearing existing
216: * context object
217: * @see #getUserContext()
218: */
219: public void setUserContext(Object obj);
220:
221: /**
222: * Get the user context object.
223: *
224: * @return user context object, or <code>null</code> if no context object
225: * set
226: * @see #setUserContext(Object)
227: */
228: public Object getUserContext();
229:
230: /**
231: * Push created object to unmarshalling stack. This must be called before
232: * beginning the unmarshalling of the object. It is only called for objects
233: * with structure, not for those converted directly to and from text.
234: *
235: * @param obj object being unmarshalled
236: */
237: public void pushObject(Object obj);
238:
239: /**
240: * Pop unmarshalled object from stack.
241: *
242: * @throws JiBXException if stack empty
243: */
244: public void popObject() throws JiBXException;
245:
246: /**
247: * Get current unmarshalling object stack depth. This allows tracking
248: * nested calls to unmarshal one object while in the process of
249: * unmarshalling another object. The bottom item on the stack is always the
250: * root object being unmarshalled.
251: *
252: * @return number of objects in unmarshalling stack
253: */
254: public int getStackDepth();
255:
256: /**
257: * Get object from unmarshalling stack. This stack allows tracking nested
258: * calls to unmarshal one object while in the process of unmarshalling
259: * another object. The bottom item on the stack is always the root object
260: * being unmarshalled.
261: *
262: * @param depth object depth in stack to be retrieved (must be in the range
263: * of zero to the current depth minus one).
264: * @return object from unmarshalling stack
265: */
266: public Object getStackObject(int depth);
267:
268: /**
269: * Get top object on unmarshalling stack. This is safe to call even when no
270: * objects are on the stack.
271: *
272: * @return object from unmarshalling stack, or <code>null</code> if none
273: */
274: public Object getStackTop();
275: }
|