UnmarshallingContext


1   //
2   // This file was generated by the JavaTM Architecture for XML Binding(JAXB) Reference Implementation, v1.0.3-b18-fcs 
3   // See <a HREF="http://java.sun.com/xml/jaxb">http://java.sun.com/xml/jaxb</a> 
4   // Any modifications to this file will be lost upon recompilation of the source schema. 
5   // Generated on: 2005.06.14 at 12:02:17 PDT 
6   //
7   
8   package com.sun.japex.testsuite.impl.runtime;
9   
10  import javax.xml.bind.ValidationEvent;
11  import javax.xml.namespace.NamespaceContext  ;
12  
13  import org.xml.sax.Attributes  ;
14  import org.xml.sax.Locator  ;
15  import org.xml.sax.SAXException  ;
16  
17  import com.sun.xml.bind.unmarshaller.Tracer;
18  
19  /**
20   * Methods exposed by the unmarshalling coordinator object
21   * to the generated code.
22   * 
23   * This interface will be implemented by the coordinator, which
24   * converts whatever events (e.g., SAX) into unmarshalling events.
25   *
26   * <p>
27   * Errors detected by the AbstractUnmarshallingEventHandlerImpl-derived classes should
28   * be either thrown as {@link UnrepotedException} or reported through
29   * the handleEvent method of this interface.
30   *
31   * @author
32   *  <a HREF="mailto:kohsuke.kawaguchi@sun.com">Kohsuke KAWAGUCHI</a>
33   */
34  public interface UnmarshallingContext extends NamespaceContext  
35  {
36      /** Obtains a reference to the current grammar info. */
37      GrammarInfo getGrammarInfo();
38      
39      
40      
41      /**
42       * Pushes the current content handler into the stack
43       * and registers the newly specified content handler so
44       * that it can receive SAX events.
45       * 
46       * @param memento
47       *      When this newly specified handler will be removed from the stack,
48       *      the leaveChild event will be fired to the parent handler
49       *      with this memento.
50       */
51      void pushContentHandler( UnmarshallingEventHandler handler, int memento );
52      
53      /**
54       * Pops a content handler from the stack and registers
55       * it as the current content handler.
56       * 
57       * <p>
58       * This method will also fire the leaveChild event with the
59       * associated memento.
60       */
61      void popContentHandler() throws SAXException  ;
62      
63      /**
64       * Gets the current handler.
65       */
66      UnmarshallingEventHandler getCurrentHandler();
67  
68      /**
69       * Returns a list of prefixes newly declared on this element.
70       * 
71       * This method has to be called after the {@link #pushAttributes}
72       * method is called.
73       * 
74       * @return
75       *      A possible zero-length array of prefixes. The default prefix
76       *      is represented by the empty string.
77       */    
78      String  [] getNewlyDeclaredPrefixes();    
79      
80      /**
81       * Returns a list of all in-scope prefixes. 
82       * 
83       * @return
84       *      A possible zero-length array of prefixes. The default prefix
85       *      is represented by the empty string.
86       */
87      String  [] getAllDeclaredPrefixes();
88      
89      
90      /**
91       * Stores a new attribute set.
92       * This method should be called by the generated code
93       * when it "eats" an enterElement event.
94       * 
95       * @param collectText
96       *      false if the context doesn't need to fire text events
97       *      for texts inside this element. True otherwise. 
98       */
99      void pushAttributes( Attributes   atts, boolean collectText );
100     
101     /**
102      * Discards the previously stored attribute set.
103      * This method should be called by the generated code
104      * when it "eats" a leaveElement event.
105      */
106     void popAttributes();
107     
108     /**
109      * Gets the index of the attribute with the specified name.
110      * This is usually faster when you only need to test with
111      * a simple name.
112      * 
113      * @return
114      *      -1 if not found.
115      */
116     int getAttribute( String   uri, String   name );
117     
118     /**
119      * Gets all the unconsumed attributes.
120      * If you need to find attributes based on more complex filter,
121      * you need to use this method.
122      */
123     Attributes   getUnconsumedAttributes();
124     
125     /**
126      * Fires an attribute event for the specified attribute,
127      * and marks the attribute as "used".
128      */
129     void consumeAttribute( int idx ) throws SAXException  ;
130     
131     /**
132      * Marks the attribute as "used" and return the value of the attribute.
133      */
134     String   eatAttribute( int idx ) throws SAXException  ;
135     
136     /**
137      * Adds a job that will be executed at the last of the unmarshalling.
138      * This method is used to support ID/IDREF feature, but it can be used
139      * for other purposes as well.
140      * 
141      * @param   job
142      *      The run method of this object is called.
143      */
144     void addPatcher( Runnable   job );
145     // the patcher can throw JAXBException?
146     
147     /**
148      * Adds the object which is currently being unmarshalled
149      * to the ID table.
150      * 
151      * @return
152      *      Returns the value passed as the parameter.
153      *      This is a hack, but this makes it easier for ID
154      *      transducer to do its job.
155      */
156     String   addToIdTable( String   id );
157     //
158     // throwing an exception is one way. Overwriting the previous one
159     // is another way. The latter allows us to process invalid documents,
160     // while the former makes it impossible to handle them.
161     //
162     // I prefer to be flexible in terms of invalid document handling,
163     // so chose not to throw an exception.
164     //
165     // I believe this is an implementation choice, not the spec issue.
166     // -kk
167     
168     /**
169      * Looks up the ID table and gets associated object.
170      * 
171      * @return
172      *      If there is no object associated with the given id,
173      *      this method returns null.
174      */
175     Object   getObjectFromId( String   id );
176     // if we don't find ID.
177     
178     
179     /**
180      * Gets the current source location information.
181      */
182     Locator   getLocator();
183     
184     /**
185      * Reports an error to the user, and asks if s/he wants
186      * to recover. If the canRecover flag is false, regardless
187      * of the client instruction, an exception will be thrown.
188      * 
189      * Only if the flag is true and the user wants to recover from an error,
190      * the method returns normally.
191      * 
192      * The thrown exception will be catched by the unmarshaller.
193      */
194     void handleEvent( ValidationEvent event, boolean canRecover ) throws SAXException  ;
195     
196     
197 //
198 //
199 // the copy of the org.relaxng.datatype.ValidationContext interface.
200 //
201 // this interface doesn't derive from that interface so that we don't have
202 // a direct dependency to it, but we provide the same functionality so that
203 // we can adopt this interface into the ValidationContext interface.
204 //
205 // see the ValidationContextAdaptor class.
206     String   resolveNamespacePrefix( String   prefix );
207     String   getBaseUri();
208     boolean isUnparsedEntity( String   entityName );
209     boolean isNotation( String   notationName );
210     
211     
212     
213     
214 // DBG
215     /**
216      * Gets a tracer object.
217      * 
218      * Tracer can be used to trace the unmarshalling behavior.
219      * Note that to debug the unmarshalling process,
220      * you have to configure XJC so that it will emit trace codes
221      * in the unmarshaller.
222      */
223     Tracer getTracer();
224 }
225
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags