001 //
002 // This file was generated by the JavaTM Architecture for XML Binding(JAXB) Reference Implementation, v1.0.1-05/30/2003 05:06 AM(java_re)-fcs
003 // See <a href="http://java.sun.com/xml/jaxb">http://java.sun.com/xml/jaxb</a>
004 // Any modifications to this file will be lost upon recompilation of the source schema.
005 // Generated on: 2004.10.11 at 12:13:34 EDT
006 //
007
008 /*
009 * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
010 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
011 */
012
013 /*
014 * @(#)$Id: UnmarshallingContext.java,v 1.8 2003/05/21 01:18:16 kk122374 Exp $
015 */
016 package astronomy.data.spectra.impl.runtime;
017
018 import javax.xml.bind.ValidationEvent;
019 import javax.xml.namespace.NamespaceContext;
020
021 import org.relaxng.datatype.ValidationContext;
022 import org.xml.sax.Attributes;
023 import org.xml.sax.Locator;
024 import org.xml.sax.SAXException;
025
026 import com.sun.xml.bind.unmarshaller.Tracer;
027
028 /**
029 * Methods exposed by the unmarshalling coordinator object
030 * to the generated code.
031 *
032 * This interface will be implemented by the coordinator, which
033 * converts whatever events (e.g., SAX) into unmarshalling events.
034 *
035 * <p>
036 * Errors detected by the AbstractUnmarshallingEventHandlerImpl-derived classes should
037 * be either thrown as {@link UnrepotedException} or reported through
038 * the handleEvent method of this interface.
039 *
040 * @author
041 * <a href="mailto:kohsuke.kawaguchi@sun.com>Kohsuke KAWAGUCHI</a>
042 */
043 public interface UnmarshallingContext extends
044 ValidationContext, NamespaceContext
045 {
046 /** Obtains a reference to the current grammar info. */
047 GrammarInfo getGrammarInfo();
048
049
050
051 /**
052 * Pushes the current content handler into the stack
053 * and registers the newly specified content handler so
054 * that it can receive SAX events.
055 *
056 * @param memento
057 * When this newly specified handler will be removed from the stack,
058 * the leaveChild event will be fired to the parent handler
059 * with this memento.
060 */
061 void pushContentHandler( UnmarshallingEventHandler handler, int memento );
062
063 /**
064 * Pops a content handler from the stack and registers
065 * it as the current content handler.
066 *
067 * <p>
068 * This method will also fire the leaveChild event with the
069 * associated memento.
070 *
071 * @return
072 * The new content handler. This method DOES NOT return
073 * the previous content handler.
074 */
075 void popContentHandler() throws SAXException;
076
077 /**
078 * Gets the current handler.
079 */
080 UnmarshallingEventHandler getCurrentHandler();
081
082 // those two methods are defined in SAX ContentHandler
083 /**
084 * Adds a new namespace declaration.
085 * This method should be called by the generated code.
086 */
087 void startPrefixMapping( String prefix, String namespaceUri );
088
089 /**
090 * Removes a namespace declaration.
091 * This method should be called by the generated code.
092 */
093 void endPrefixMapping( String prefix );
094
095
096
097 /**
098 * Stores a new attribute set.
099 * This method should be called by the generated code
100 * when it "eats" an enterElement event.
101 *
102 * @param collectText
103 * false if the context doesn't need to fire text events
104 * for texts inside this element. True otherwise.
105 */
106 void pushAttributes( Attributes atts, boolean collectText );
107
108 /**
109 * Discards the previously stored attribute set.
110 * This method should be called by the generated code
111 * when it "eats" a leaveElement event.
112 */
113 void popAttributes();
114
115 /**
116 * Gets the index of the attribute with the specified name.
117 * This is usually faster when you only need to test with
118 * a simple name.
119 *
120 * @return
121 * -1 if not found.
122 */
123 int getAttribute( String uri, String name );
124
125 /**
126 * Gets all the unconsumed attributes.
127 * If you need to find attributes based on more complex filter,
128 * you need to use this method.
129 */
130 Attributes getUnconsumedAttributes();
131
132 /**
133 * Fires an attribute event for the specified attribute,
134 * and marks the attribute as "used".
135 */
136 void consumeAttribute( int idx ) throws SAXException;
137
138 /**
139 * Marks the attribute as "used" and return the value of the attribute.
140 */
141 String eatAttribute( int idx ) throws SAXException;
142
143 /**
144 * Adds a job that will be executed at the last of the unmarshalling.
145 * This method is used to support ID/IDREF feature, but it can be used
146 * for other purposes as well.
147 *
148 * @param job
149 * The run method of this object is called.
150 */
151 void addPatcher( Runnable job );
152 // TODO: shall we use a modified version of Runnable so that
153 // the patcher can throw JAXBException?
154
155 /**
156 * Adds the object which is currently being unmarshalled
157 * to the ID table.
158 *
159 * @return
160 * Returns the value passed as the parameter.
161 * This is a hack, but this makes it easier for ID
162 * transducer to do its job.
163 */
164 String addToIdTable( String id );
165 // TODO: what shall we do if the ID is already declared?
166 //
167 // throwing an exception is one way. Overwriting the previous one
168 // is another way. The latter allows us to process invalid documents,
169 // while the former makes it impossible to handle them.
170 //
171 // I prefer to be flexible in terms of invalid document handling,
172 // so chose not to throw an exception.
173 //
174 // I believe this is an implementation choice, not the spec issue.
175 // -kk
176
177 /**
178 * Looks up the ID table and gets associated object.
179 *
180 * @return
181 * If there is no object associated with the given id,
182 * this method returns null.
183 */
184 Object getObjectFromId( String id );
185 // TODO: maybe we should throw UnmarshallingException
186 // if we don't find ID.
187
188
189 /**
190 * Gets the current source location information.
191 */
192 Locator getLocator();
193
194 /**
195 * Reports an error to the user, and asks if s/he wants
196 * to recover. If the canRecover flag is false, regardless
197 * of the client instruction, an exception will be thrown.
198 *
199 * Only if the flag is true and the user wants to recover from an error,
200 * the method returns normally.
201 *
202 * The thrown exception will be catched by the unmarshaller.
203 */
204 void handleEvent( ValidationEvent event, boolean canRecover ) throws SAXException;
205
206
207 // DBG
208 /**
209 * Gets a tracer object.
210 *
211 * Tracer can be used to trace the unmarshalling behavior.
212 * Note that to debug the unmarshalling process,
213 * you have to configure XJC so that it will emit trace codes
214 * in the unmarshaller.
215 */
216 Tracer getTracer();
217 }