Source Code Cross Referenced for EntityResolver2.java in  » Web-Server » Rimfaxe-Web-Server » org » xml » sax » ext » 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.ext 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


001:        // EntityResolver2.java - Extended SAX entity resolver.
002:        // http://www.saxproject.org
003:        // No warranty; no copyright -- use this as you will.
004:        // $Id: EntityResolver2.java,v 1.3 2002/02/01 20:06:20 db Exp $
005:
006:        package org.xml.sax.ext;
007:
008:        import java.io.IOException;
009:
010:        import org.xml.sax.EntityResolver;
011:        import org.xml.sax.InputSource;
012:        import org.xml.sax.XMLReader;
013:        import org.xml.sax.SAXException;
014:
015:        /**
016:         * Extended interface for mapping external entity references to input
017:         * sources, or providing a missing external subset.  The
018:         * {@link XMLReader#setEntityResolver XMLReader.setEntityResolver()} method
019:         * is used to provide implementations of this interface to parsers.
020:         * When a parser uses the methods in this interface, the
021:         * {@link EntityResolver2#resolveEntity EntityResolver2.resolveEntity()}
022:         * method (in this interface) is used <em>instead of</em> the older (SAX 1.0)
023:         * {@link EntityResolver#resolveEntity EntityResolver.resolveEntity()} method.
024:         *
025:         * <blockquote>
026:         * <em>This module, both source code and documentation, is in the
027:         * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
028:         * </blockquote>
029:         *
030:         * <p>If a SAX application requires the customized handling which this
031:         * interface defines for external entities, it must ensure that it uses
032:         * an XMLReader with the
033:         * <em>http://xml.org/sax/features/use-entity-resolver2</em> feature flag
034:         * set to <em>true</em> (which is its default value when the feature is
035:         * recognized).  If that flag is unrecognized, or its value is false,
036:         * or the resolver does not implement this interface, then only the
037:         * {@link EntityResolver} method will be used.
038:         * </p>
039:         *
040:         * <p>That supports three categories of application that modify entity
041:         * resolution.  <em>Old Style</em> applications won't know about this interface;
042:         * they will provide an EntityResolver.
043:         * <em>Transitional Mode</em> provide an EntityResolver2 and automatically
044:         * get the benefit of its methods in any systems (parsers or other tools)
045:         * supporting it, due to polymorphism.
046:         * Both <em>Old Style</em> and <em>Transitional Mode</em> applications will
047:         * work with any SAX2 parser.
048:         * <em>New style</em> applications will fail to run except on SAX2 parsers
049:         * that support this particular feature.
050:         * They will insist that feature flag have a value of "true", and the
051:         * EntityResolver2 implementation they provide  might throw an exception
052:         * if the original SAX 1.0 style entity resolution method is invoked.
053:         * </p>
054:         *
055:         * @see org.xml.sax.XMLReader#setEntityResolver
056:         *
057:         * @since SAX 2.0 (extensions 1.1 alpha)
058:         * @author David Brownell
059:         * @version TBD
060:         */
061:        public interface EntityResolver2 extends EntityResolver {
062:            /**
063:             * Allows applications to provide an external subset for documents
064:             * that don't explicitly define one.  Documents with DOCTYPE declarations
065:             * that omit an external subset can thus augment the declarations
066:             * available for validation, entity processing, and attribute processing
067:             * (normalization, defaulting, and reporting types including ID).
068:             * This augmentation is reported
069:             * through the {@link LexicalHandler#startDTD startDTD()} method as if
070:             * the document text had originally included the external subset;
071:             * this callback is made before any internal subset data or errors
072:             * are reported.</p>
073:             *
074:             * <p>This method can also be used with documents that have no DOCTYPE
075:             * declaration.  When the root element is encountered,
076:             * but no DOCTYPE declaration has been seen, this method is
077:             * invoked.  If it returns a value for the external subset, that root
078:             * element is declared to be the root element, giving the effect of
079:             * splicing a DOCTYPE declaration at the end the prolog of a document
080:             * that could not otherwise be valid.  The sequence of parser callbacks
081:             * in that case logically resembles this:</p>
082:             *
083:             * <pre>
084:             * ... comments and PIs from the prolog (as usual)
085:             * startDTD ("rootName", source.getPublicId (), source.getSystemId ());
086:             * startEntity ("[dtd]");
087:             * ... declarations, comments, and PIs from the external subset
088:             * endEntity ("[dtd]");
089:             * endDTD ();
090:             * ... then the rest of the document (as usual)
091:             * startElement (..., "rootName", ...);
092:             * </pre>
093:             *
094:             * <p>Note that the InputSource gets no further resolution.
095:             * Implementations of this method may wish to invoke
096:             * {@link #resolveEntity resolveEntity()} to gain benefits such as use
097:             * of local caches of DTD entities.  Also, this method will never be
098:             * used by a (non-validating) processor that is not including external
099:             * parameter entities. </p>
100:             *
101:             * <p>Uses for this method include facilitating data validation when
102:             * interoperating with XML processors that would always require
103:             * undesirable network accesses for external entities, or which for
104:             * other reasons adopt a "no DTDs" policy.
105:             * Non-validation motives include forcing documents to include DTDs so
106:             * that attributes are handled consistently.
107:             * For example, an XPath processor needs to know which attibutes have
108:             * type "ID" before it can process a widely used type of reference.</p>
109:             * 
110:             * <p><strong>Warning:</strong> Returning an external subset modifies
111:             * the input document.  By providing definitions for general entities,
112:             * it can make a malformed document appear to be well formed.
113:             * </p>
114:             *
115:             * @param name Identifies the document root element.  This name comes
116:             *	from a DOCTYPE declaration (where available) or from the actual
117:             *	root element. 
118:             * @param baseURI The document's base URI, serving as an additional
119:             *	hint for selecting the external subset.  This is always an absolute
120:             *	URI, unless it is null because the XMLReader was given an InputSource
121:             *	without one.
122:             *
123:             * @return An InputSource object describing the new external subset
124:             *	to be used by the parser, or null to indicate that no external
125:             *	subset is provided.
126:             *
127:             * @exception SAXException Any SAX exception, possibly wrapping
128:             *	another exception.
129:             * @exception IOException Probably indicating a failure to create
130:             *	a new InputStream or Reader, or an illegal URL.
131:             */
132:            public InputSource getExternalSubset(String name, String baseURI)
133:                    throws SAXException, IOException;
134:
135:            /**
136:             * Allows applications to map references to external entities into input
137:             * sources, or tell the parser it should use conventional URI resolution.
138:             * This method is only called for external entities which have been
139:             * properly declared.
140:             * This method provides more flexibility than the {@link EntityResolver}
141:             * interface, supporting implementations of more complex catalogue
142:             * schemes such as the one defined by the <a href=
143:            "http://www.oasis-open.org/committees/entity/spec-2001-08-06.html"
144:            >OASIS XML Catalogs</a> specification.</p>
145:             *
146:             * <p>Parsers configured to use this resolver method will call it
147:             * to determine the input source to use for any external entity
148:             * being included because of a reference in the XML text.
149:             * That excludes the document entity, and any external entity returned
150:             * by {@link #getExternalSubset getExternalSubset()}.
151:             * When a (non-validating) processor is configured not to include
152:             * a class of entities (parameter or general) through use of feature
153:             * flags, this method is not invoked for such entities.  </p>
154:             *
155:             * <p>Note that the entity naming scheme used here is the same one
156:             * used in the {@link LexicalHandler}, or in the {@link
157:            org.xml.sax.ContentHandler#skippedEntity
158:            ContentHandler.skippedEntity()}
159:             * method. </p>
160:             *
161:             * @param name Identifies the external entity being resolved.
162:             *	Either "[dtd]" for the external subset, or a name starting
163:             *	with "%" to indicate a parameter entity, or else the name of
164:             *	a general entity.  This is never null when invoked by a SAX2
165:             *	parser.
166:             * @param publicId The public identifier of the external entity being
167:             *	referenced (normalized as required by the XML specification), or
168:             *	null if none was supplied.
169:             * @param baseURI The URI with respect to which relative systemIDs
170:             *	are interpreted.  This is always an absolute URI, unless it is
171:             *	null (likely because the XMLReader was given an InputSource without
172:             *  one).  This URI is defined by the XML specification to be the one
173:             *	associated with the "&lt;" starting the relevant declaration.
174:             * @param systemId The system identifier of the external entity
175:             *	being referenced; either a relative or absolute URI.
176:             *  This is never null when invoked by a SAX2 parser; only declared
177:             *	entities, and any external subset, are resolved by such parsers.
178:             *
179:             * @return An InputSource object describing the new input source to
180:             *	be used by the parser.  Returning null directs the parser to
181:             *	resolve the system ID against the base URI and open a connection
182:             *	to resulting URI.
183:             *
184:             * @exception SAXException Any SAX exception, possibly wrapping
185:             *	another exception.
186:             * @exception IOException Probably indicating a failure to create
187:             *	a new InputStream or Reader, or an illegal URL.
188:             */
189:            public InputSource resolveEntity(String name, String publicId,
190:                    String baseURI, String systemId) throws SAXException,
191:                    IOException;
192:        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.