1
2
3
4
5
6
7
8 package net.sf.jour.config.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
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
159
160
161
162
163
164
165
166
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
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
200
201
202
203
204
205
206 String resolveNamespacePrefix( String prefix );
207 String getBaseUri();
208 boolean isUnparsedEntity( String entityName );
209 boolean isNotation( String notationName );
210
211
212
213
214
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 }