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  ;
32  import java.io.Reader  ;
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   ins, String   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   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   ins, String   name, String   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   rdr, String   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   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   unmarshalDocument(InputStream   ins, String   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   unmarshalDocument(Reader   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   unmarshalDocument(InputStream   ins, String   name, String   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   unmarshalDocument(Reader   rdr, String   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   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   ns, String   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   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   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   getStackTop();
259 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags