KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jibx > runtime > IUnmarshallingContext


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.InputStream JavaDoc;
32 import java.io.Reader JavaDoc;
33
34 /**
35  * User interface for deserializer from XML. This provides methods used to set
36  * up and control the marshalling process, as well as access to the
37  * unmarshalling object stack while unmarshalling.
38  *
39  * @author Dennis M. Sosnoski
40  * @version 1.0
41  */

42  
43 public interface IUnmarshallingContext {
44
45     /**
46      * Set document to be parsed from stream.
47      *
48      * @param ins stream supplying document data
49      * @param enc document input encoding, or <code>null</code> if to be
50      * determined by parser
51      * @throws JiBXException if error creating parser
52      */

53     
54     void setDocument(InputStream JavaDoc ins, String JavaDoc enc) throws JiBXException;
55
56     /**
57      * Set document to be parsed from reader.
58      *
59      * @param rdr reader supplying document data
60      * @throws JiBXException if error creating parser
61      */

62
63     void setDocument(Reader JavaDoc rdr) throws JiBXException;
64
65     /**
66      * Set named document to be parsed from stream.
67      *
68      * @param ins stream supplying document data
69      * @param name document name
70      * @param enc document input encoding, or <code>null</code> if to be
71      * determined by parser
72      * @throws JiBXException if error creating parser
73      */

74     
75     void setDocument(InputStream JavaDoc ins, String JavaDoc name, String JavaDoc enc)
76         throws JiBXException;
77
78     /**
79      * Set named document to be parsed from reader.
80      *
81      * @param rdr reader supplying document data
82      * @param name document name
83      * @throws JiBXException if error creating parser
84      */

85
86     void setDocument(Reader JavaDoc rdr, String JavaDoc name) throws JiBXException;
87
88     /**
89      * Reset unmarshalling information. This releases all references to
90      * unmarshalled objects and prepares the context for potential reuse.
91      * It is automatically called when input is set.
92      */

93
94     void reset();
95
96     /**
97      * Unmarshal the current element. If not currently positioned at a start
98      * or end tag this first advances the parse to the next start or end tag.
99      * There must be an unmarshalling defined for the current element, and this
100      * unmarshalling is used to build an object from that element.
101      *
102      * @return unmarshalled object from element
103      * @throws JiBXException on any error (possibly wrapping other exception)
104      */

105     
106     Object JavaDoc unmarshalElement() throws JiBXException;
107
108     /**
109      * Unmarshal document from stream to object. The effect of this is the same
110      * as if {@link #setDocument} were called, followed by {@link
111      * #unmarshalElement}
112      *
113      * @param ins stream supplying document data
114      * @param enc document input encoding, or <code>null</code> if to be
115      * determined by parser
116      * @return unmarshalled object
117      * @throws JiBXException if error creating parser
118      */

119
120     Object JavaDoc unmarshalDocument(InputStream JavaDoc ins, String JavaDoc enc) throws JiBXException;
121
122     /**
123      * Unmarshal document from reader to object. The effect of this is the same
124      * as if {@link #setDocument} were called, followed by {@link
125      * #unmarshalElement}
126      *
127      * @param rdr reader supplying document data
128      * @return unmarshalled object
129      * @throws JiBXException if error creating parser
130      */

131
132     Object JavaDoc unmarshalDocument(Reader JavaDoc rdr) throws JiBXException;
133
134     /**
135      * Unmarshal named document from stream to object. The effect of this is the
136      * same as if {@link #setDocument} were called, followed by {@link
137      * #unmarshalElement}
138      *
139      * @param ins stream supplying document data
140      * @param name document name
141      * @param enc document input encoding, or <code>null</code> if to be
142      * determined by parser
143      * @return unmarshalled object
144      * @throws JiBXException if error creating parser
145      */

146
147     Object JavaDoc unmarshalDocument(InputStream JavaDoc ins, String JavaDoc name, String JavaDoc enc)
148         throws JiBXException;
149
150     /**
151      * Unmarshal named document from reader to object. The effect of this is the
152      * same as if {@link #setDocument} were called, followed by {@link
153      * #unmarshalElement}
154      *
155      * @param rdr reader supplying document data
156      * @param name document name
157      * @return unmarshalled object
158      * @throws JiBXException if error creating parser
159      */

160
161     Object JavaDoc unmarshalDocument(Reader JavaDoc rdr, String JavaDoc name) throws JiBXException;
162
163     /**
164      * Return the supplied document name.
165      *
166      * @return supplied document name (<code>null</code> if none)
167      */

168     
169     public String JavaDoc getDocumentName();
170
171     /**
172      * Check if next tag is start of element. If not currently positioned at a
173      * start or end tag this first advances the parse to the next start or end
174      * tag.
175      *
176      * @param ns namespace URI for expected element (may be <code>null</code>
177      * or the empty string for the empty namespace)
178      * @param name element name expected
179      * @return <code>true</code> if at start of element with supplied name,
180      * <code>false</code> if not
181      * @throws JiBXException on any error (possibly wrapping other exception)
182      */

183
184     public boolean isAt(String JavaDoc ns, String JavaDoc name) throws JiBXException;
185
186     /**
187      * Check if next tag is an end tag. If not currently positioned at a
188      * start or end tag this first advances the parse to the next start or
189      * end tag.
190      *
191      * @return <code>true</code> if at end of element, <code>false</code> if
192      * at start
193      * @throws JiBXException on any error (possibly wrapping other exception)
194      */

195
196     public boolean isEnd() throws JiBXException;
197
198     /**
199      * Find the unmarshaller for a particular class index in the current
200      * context.
201      *
202      * @param index class index for unmarshalling definition
203      * @return unmarshalling handler for class
204      * @throws JiBXException if unable to create unmarshaller
205      */

206     
207     public IUnmarshaller getUnmarshaller(int index) throws JiBXException;
208
209     /**
210      * Push created object to unmarshalling stack. This must be called before
211      * beginning the unmarshalling of the object. It is only called for objects
212      * with structure, not for those converted directly to and from text.
213      *
214      * @param obj object being unmarshalled
215      */

216
217     public void pushObject(Object JavaDoc obj);
218
219     /**
220      * Pop unmarshalled object from stack.
221      *
222      * @throws JiBXException if stack empty
223      */

224
225     public void popObject() throws JiBXException;
226     
227     /**
228      * Get current unmarshalling object stack depth. This allows tracking
229      * nested calls to unmarshal one object while in the process of
230      * unmarshalling another object. The bottom item on the stack is always the
231      * root object being unmarshalled.
232      *
233      * @return number of objects in unmarshalling stack
234      */

235
236     public int getStackDepth();
237     
238     /**
239      * Get object from unmarshalling stack. This stack allows tracking nested
240      * calls to unmarshal one object while in the process of unmarshalling
241      * another object. The bottom item on the stack is always the root object
242      * being unmarshalled.
243      *
244      * @param depth object depth in stack to be retrieved (must be in the range
245      * of zero to the current depth minus one).
246      * @return object from unmarshalling stack
247      */

248
249     public Object JavaDoc getStackObject(int depth);
250     
251     /**
252      * Get top object on unmarshalling stack. This is safe to call even when no
253      * objects are on the stack.
254      *
255      * @return object from unmarshalling stack, or <code>null</code> if none
256      */

257
258     public Object JavaDoc getStackTop();
259 }
Popular Tags