Source Code Cross Referenced for ContentHandler.java in  » Development » Javolution » org » xml » sax » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » Development » Javolution » org.xml.sax 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


001:        // ContentHandler.java - handle main document content.
002:        // http://www.saxproject.org
003:        // Written by David Megginson
004:        // NO WARRANTY!  This class is in the public domain.
005:
006:        package org.xml.sax;
007:
008:        /**
009:         * Receive notification of the logical content of a document.
010:         *
011:         * <blockquote>
012:         * <em>This module, both source code and documentation, is in the
013:         * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
014:         * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
015:         * for further information.
016:         * </blockquote>
017:         *
018:         * <p>This is the main interface that most SAX applications
019:         * implement: if the application needs to be informed of basic parsing 
020:         * events, it implements this interface and registers an instance with 
021:         * the SAX parser using the {@link org.xml.sax.XMLReader#setContentHandler 
022:         * setContentHandler} method.  The parser uses the instance to report 
023:         * basic document-related events like the start and end of elements 
024:         * and character data.</p>
025:         *
026:         * <p>The order of events in this interface is very important, and
027:         * mirrors the order of information in the document itself.  For
028:         * example, all of an element's content (character data, processing
029:         * instructions, and/or subelements) will appear, in order, between
030:         * the startElement event and the corresponding endElement event.</p>
031:         *
032:         * <p>This interface is similar to the now-deprecated SAX 1.0
033:         * DocumentHandler interface, but it adds support for Namespaces
034:         * and for reporting skipped entities (in non-validating XML
035:         * processors).</p>
036:         *
037:         * <p>Implementors should note that there is also a 
038:         * <code>ContentHandler</code> class in the <code>java.net</code>
039:         * package; that means that it's probably a bad idea to do</p>
040:         *
041:         * <pre>import java.net.*;
042:         * import org.xml.sax.*;
043:         * </pre>
044:         *
045:         * <p>In fact, "import ...*" is usually a sign of sloppy programming
046:         * anyway, so the user should consider this a feature rather than a
047:         * bug.</p>
048:         *
049:         * @since SAX 2.0
050:         * @author David Megginson
051:         * @version 2.0.1+ (sax2r3pre1)
052:         * @see org.xml.sax.XMLReader
053:         * @see org.xml.sax.DTDHandler
054:         * @see org.xml.sax.ErrorHandler
055:         */
056:        public interface ContentHandler {
057:
058:            /**
059:             * Receive an object for locating the origin of SAX document events.
060:             *
061:             * <p>SAX parsers are strongly encouraged (though not absolutely
062:             * required) to supply a locator: if it does so, it must supply
063:             * the locator to the application by invoking this method before
064:             * invoking any of the other methods in the ContentHandler
065:             * interface.</p>
066:             *
067:             * <p>The locator allows the application to determine the end
068:             * position of any document-related event, even if the parser is
069:             * not reporting an error.  Typically, the application will
070:             * use this information for reporting its own errors (such as
071:             * character content that does not match an application's
072:             * business rules).  The information returned by the locator
073:             * is probably not sufficient for use with a search engine.</p>
074:             *
075:             * <p>Note that the locator will return correct information only
076:             * during the invocation SAX event callbacks after
077:             * {@link #startDocument startDocument} returns and before
078:             * {@link #endDocument endDocument} is called.  The
079:             * application should not attempt to use it at any other time.</p>
080:             *
081:             * @param locator an object that can return the location of
082:             *                any SAX document event
083:             * @see org.xml.sax.Locator
084:             */
085:            public void setDocumentLocator(Locator locator);
086:
087:            /**
088:             * Receive notification of the beginning of a document.
089:             *
090:             * <p>The SAX parser will invoke this method only once, before any
091:             * other event callbacks (except for {@link #setDocumentLocator 
092:             * setDocumentLocator}).</p>
093:             *
094:             * @throws org.xml.sax.SAXException any SAX exception, possibly
095:             *            wrapping another exception
096:             * @see #endDocument
097:             */
098:            public void startDocument() throws SAXException;
099:
100:            /**
101:             * Receive notification of the end of a document.
102:             *
103:             * <p><strong>There is an apparent contradiction between the
104:             * documentation for this method and the documentation for {@link
105:             * org.xml.sax.ErrorHandler#fatalError}.  Until this ambiguity is
106:             * resolved in a future major release, clients should make no
107:             * assumptions about whether endDocument() will or will not be
108:             * invoked when the parser has reported a fatalError() or thrown
109:             * an exception.</strong></p>
110:             *
111:             * <p>The SAX parser will invoke this method only once, and it will
112:             * be the last method invoked during the parse.  The parser shall
113:             * not invoke this method until it has either abandoned parsing
114:             * (because of an unrecoverable error) or reached the end of
115:             * input.</p>
116:             *
117:             * @throws org.xml.sax.SAXException any SAX exception, possibly
118:             *            wrapping another exception
119:             * @see #startDocument
120:             */
121:            public void endDocument() throws SAXException;
122:
123:            /**
124:             * Begin the scope of a prefix-URI Namespace mapping.
125:             *
126:             * <p>The information from this event is not necessary for
127:             * normal Namespace processing: the SAX XML reader will 
128:             * automatically replace prefixes for element and attribute
129:             * names when the <code>http://xml.org/sax/features/namespaces</code>
130:             * feature is <var>true</var> (the default).</p>
131:             *
132:             * <p>There are cases, however, when applications need to
133:             * use prefixes in character data or in attribute values,
134:             * where they cannot safely be expanded automatically; the
135:             * start/endPrefixMapping event supplies the information
136:             * to the application to expand prefixes in those contexts
137:             * itself, if necessary.</p>
138:             *
139:             * <p>Note that start/endPrefixMapping events are not
140:             * guaranteed to be properly nested relative to each other:
141:             * all startPrefixMapping events will occur immediately before the
142:             * corresponding {@link #startElement startElement} event, 
143:             * and all {@link #endPrefixMapping endPrefixMapping}
144:             * events will occur immediately after the corresponding
145:             * {@link #endElement endElement} event,
146:             * but their order is not otherwise 
147:             * guaranteed.</p>
148:             *
149:             * <p>There should never be start/endPrefixMapping events for the
150:             * "xml" prefix, since it is predeclared and immutable.</p>
151:             *
152:             * @param prefix the Namespace prefix being declared.
153:             *	An empty string is used for the default element namespace,
154:             *	which has no prefix.
155:             * @param uri the Namespace URI the prefix is mapped to
156:             * @throws org.xml.sax.SAXException the client may throw
157:             *            an exception during processing
158:             * @see #endPrefixMapping
159:             * @see #startElement
160:             */
161:            public void startPrefixMapping(String prefix, String uri)
162:                    throws SAXException;
163:
164:            /**
165:             * End the scope of a prefix-URI mapping.
166:             *
167:             * <p>See {@link #startPrefixMapping startPrefixMapping} for 
168:             * details.  These events will always occur immediately after the
169:             * corresponding {@link #endElement endElement} event, but the order of 
170:             * {@link #endPrefixMapping endPrefixMapping} events is not otherwise
171:             * guaranteed.</p>
172:             *
173:             * @param prefix the prefix that was being mapped.
174:             *	This is the empty string when a default mapping scope ends.
175:             * @throws org.xml.sax.SAXException the client may throw
176:             *            an exception during processing
177:             * @see #startPrefixMapping
178:             * @see #endElement
179:             */
180:            public void endPrefixMapping(String prefix) throws SAXException;
181:
182:            /**
183:             * Receive notification of the beginning of an element.
184:             *
185:             * <p>The Parser will invoke this method at the beginning of every
186:             * element in the XML document; there will be a corresponding
187:             * {@link #endElement endElement} event for every startElement event
188:             * (even when the element is empty). All of the element's content will be
189:             * reported, in order, before the corresponding endElement
190:             * event.</p>
191:             *
192:             * <p>This event allows up to three name components for each
193:             * element:</p>
194:             *
195:             * <ol>
196:             * <li>the Namespace URI;</li>
197:             * <li>the local name; and</li>
198:             * <li>the qualified (prefixed) name.</li>
199:             * </ol>
200:             *
201:             * <p>Any or all of these may be provided, depending on the
202:             * values of the <var>http://xml.org/sax/features/namespaces</var>
203:             * and the <var>http://xml.org/sax/features/namespace-prefixes</var>
204:             * properties:</p>
205:             *
206:             * <ul>
207:             * <li>the Namespace URI and local name are required when 
208:             * the namespaces property is <var>true</var> (the default), and are
209:             * optional when the namespaces property is <var>false</var> (if one is
210:             * specified, both must be);</li>
211:             * <li>the qualified name is required when the namespace-prefixes property
212:             * is <var>true</var>, and is optional when the namespace-prefixes property
213:             * is <var>false</var> (the default).</li>
214:             * </ul>
215:             *
216:             * <p>Note that the attribute list provided will contain only
217:             * attributes with explicit values (specified or defaulted):
218:             * #IMPLIED attributes will be omitted.  The attribute list
219:             * will contain attributes used for Namespace declarations
220:             * (xmlns* attributes) only if the
221:             * <code>http://xml.org/sax/features/namespace-prefixes</code>
222:             * property is true (it is false by default, and support for a 
223:             * true value is optional).</p>
224:             *
225:             * <p>Like {@link #characters characters()}, attribute values may have
226:             * characters that need more than one <code>char</code> value.  </p>
227:             *
228:             * @param uri the Namespace URI, or the empty string if the
229:             *        element has no Namespace URI or if Namespace
230:             *        processing is not being performed
231:             * @param localName the local name (without prefix), or the
232:             *        empty string if Namespace processing is not being
233:             *        performed
234:             * @param qName the qualified name (with prefix), or the
235:             *        empty string if qualified names are not available
236:             * @param atts the attributes attached to the element.  If
237:             *        there are no attributes, it shall be an empty
238:             *        Attributes object.  The value of this object after
239:             *        startElement returns is undefined
240:             * @throws org.xml.sax.SAXException any SAX exception, possibly
241:             *            wrapping another exception
242:             * @see #endElement
243:             * @see org.xml.sax.Attributes
244:             * @see org.xml.sax.helpers.SaxAttributes
245:             */
246:            public void startElement(String uri, String localName,
247:                    String qName, Attributes atts) throws SAXException;
248:
249:            /**
250:             * Receive notification of the end of an element.
251:             *
252:             * <p>The SAX parser will invoke this method at the end of every
253:             * element in the XML document; there will be a corresponding
254:             * {@link #startElement startElement} event for every endElement 
255:             * event (even when the element is empty).</p>
256:             *
257:             * <p>For information on the names, see startElement.</p>
258:             *
259:             * @param uri the Namespace URI, or the empty string if the
260:             *        element has no Namespace URI or if Namespace
261:             *        processing is not being performed
262:             * @param localName the local name (without prefix), or the
263:             *        empty string if Namespace processing is not being
264:             *        performed
265:             * @param qName the qualified XML name (with prefix), or the
266:             *        empty string if qualified names are not available
267:             * @throws org.xml.sax.SAXException any SAX exception, possibly
268:             *            wrapping another exception
269:             */
270:            public void endElement(String uri, String localName, String qName)
271:                    throws SAXException;
272:
273:            /**
274:             * Receive notification of character data.
275:             *
276:             * <p>The Parser will call this method to report each chunk of
277:             * character data.  SAX parsers may return all contiguous character
278:             * data in a single chunk, or they may split it into several
279:             * chunks; however, all of the characters in any single event
280:             * must come from the same external entity so that the Locator
281:             * provides useful information.</p>
282:             *
283:             * <p>The application must not attempt to read from the array
284:             * outside of the specified range.</p>
285:             *
286:             * <p>Individual characters may consist of more than one Java
287:             * <code>char</code> value.  There are two important cases where this
288:             * happens, because characters can't be represented in just sixteen bits.
289:             * In one case, characters are represented in a <em>Surrogate Pair</em>,
290:             * using two special Unicode values. Such characters are in the so-called
291:             * "Astral Planes", with a code point above U+FFFF.  A second case involves
292:             * composite characters, such as a base character combining with one or
293:             * more accent characters. </p>
294:             *
295:             * <p> Your code should not assume that algorithms using
296:             * <code>char</code>-at-a-time idioms will be working in character
297:             * units; in some cases they will split characters.  This is relevant
298:             * wherever XML permits arbitrary characters, such as attribute values,
299:             * processing instruction data, and comments as well as in data reported
300:             * from this method.  It's also generally relevant whenever Java code
301:             * manipulates internationalized text; the issue isn't unique to XML.</p>
302:             *
303:             * <p>Note that some parsers will report whitespace in element
304:             * content using the {@link #ignorableWhitespace ignorableWhitespace}
305:             * method rather than this one (validating parsers <em>must</em> 
306:             * do so).</p>
307:             *
308:             * @param ch the characters from the XML document
309:             * @param start the start position in the array
310:             * @param length the number of characters to read from the array
311:             * @throws org.xml.sax.SAXException any SAX exception, possibly
312:             *            wrapping another exception
313:             * @see #ignorableWhitespace 
314:             * @see org.xml.sax.Locator
315:             */
316:            public void characters(char ch[], int start, int length)
317:                    throws SAXException;
318:
319:            /**
320:             * Receive notification of ignorable whitespace in element content.
321:             *
322:             * <p>Validating Parsers must use this method to report each chunk
323:             * of whitespace in element content (see the W3C XML 1.0
324:             * recommendation, section 2.10): non-validating parsers may also
325:             * use this method if they are capable of parsing and using
326:             * content models.</p>
327:             *
328:             * <p>SAX parsers may return all contiguous whitespace in a single
329:             * chunk, or they may split it into several chunks; however, all of
330:             * the characters in any single event must come from the same
331:             * external entity, so that the Locator provides useful
332:             * information.</p>
333:             *
334:             * <p>The application must not attempt to read from the array
335:             * outside of the specified range.</p>
336:             *
337:             * @param ch the characters from the XML document
338:             * @param start the start position in the array
339:             * @param length the number of characters to read from the array
340:             * @throws org.xml.sax.SAXException any SAX exception, possibly
341:             *            wrapping another exception
342:             * @see #characters
343:             */
344:            public void ignorableWhitespace(char ch[], int start, int length)
345:                    throws SAXException;
346:
347:            /**
348:             * Receive notification of a processing instruction.
349:             *
350:             * <p>The Parser will invoke this method once for each processing
351:             * instruction found: note that processing instructions may occur
352:             * before or after the main document element.</p>
353:             *
354:             * <p>A SAX parser must never report an XML declaration (XML 1.0,
355:             * section 2.8) or a text declaration (XML 1.0, section 4.3.1)
356:             * using this method.</p>
357:             *
358:             * <p>Like {@link #characters characters()}, processing instruction
359:             * data may have characters that need more than one <code>char</code>
360:             * value. </p>
361:             *
362:             * @param target the processing instruction target
363:             * @param data the processing instruction data, or null if
364:             *        none was supplied.  The data does not include any
365:             *        whitespace separating it from the target
366:             * @throws org.xml.sax.SAXException any SAX exception, possibly
367:             *            wrapping another exception
368:             */
369:            public void processingInstruction(String target, String data)
370:                    throws SAXException;
371:
372:            /**
373:             * Receive notification of a skipped entity.
374:             * This is not called for entity references within markup constructs
375:             * such as element start tags or markup declarations.  (The XML
376:             * recommendation requires reporting skipped external entities.
377:             * SAX also reports internal entity expansion/non-expansion, except
378:             * within markup constructs.)
379:             *
380:             * <p>The Parser will invoke this method each time the entity is
381:             * skipped.  Non-validating processors may skip entities if they
382:             * have not seen the declarations (because, for example, the
383:             * entity was declared in an external DTD subset).  All processors
384:             * may skip external entities, depending on the values of the
385:             * <code>http://xml.org/sax/features/external-general-entities</code>
386:             * and the
387:             * <code>http://xml.org/sax/features/external-parameter-entities</code>
388:             * properties.</p>
389:             *
390:             * @param name the name of the skipped entity.  If it is a 
391:             *        parameter entity, the name will begin with '%', and if
392:             *        it is the external DTD subset, it will be the string
393:             *        "[dtd]"
394:             * @throws org.xml.sax.SAXException any SAX exception, possibly
395:             *            wrapping another exception
396:             */
397:            public void skippedEntity(String name) throws SAXException;
398:        }
399:
400:        // end of ContentHandler.java
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.