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