Generated by
JDiff

org.xml.sax Documentation Differences

This file contains all the changes in documentation in the package org.xml.sax as colored differences. Deletions are shown like this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Class AttributeList

Interface for an element's attribute specifications.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

This is the original SAX1 interface for reporting an element's attributes. Unlike the new Attributes interface it does not support Namespace-related information.

When an attribute list is supplied as part of a startElement event the list will return valid results only during the scope of the event; once the event handler returns control to the parser the attribute list is invalid. To save a persistent copy of the attribute list use the SAX1 AttributeListImpl helper class.

An attribute list includes only attributes that have been specified or defaulted: #IMPLIED attributes will not be included.

There are two ways for the SAX application to obtain information from the AttributeList. First it can iterate through the entire list:

 public void startElement (String name AttributeList atts) { for (int i = 0; i  

(Note that the result of getLength() will be zero if there are no attributes.)

As an alternative the application can request the value or type of specific attributes:

 public void startElement (String name AttributeList atts) { String identifier = atts.getValue("id"); String label = atts.getValue("label"); [...] } 
@deprecated This interface has been replaced by the SAX2 Attributes interface which includes Namespace support. @since SAX 1.0 @author David Megginson sax@megginson.com @version 2.00r2pre @see org.xml.sax.DocumentHandler#startElement startElement @see org.xml.sax.helpers.AttributeListImpl AttributeListImpl

Class Attributes

Interface for a list of XML attributes.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

This interface allows access to a list of attributes in three different ways:

  1. by attribute index;
  2. by Namespace-qualified name; or
  3. by qualified (prefixed) name.

The list will not contain attributes that were declared #IMPLIED but not specified in the start tag. It will also not contain attributes used as Namespace declarations (xmlns*) unless the http://xml.org/sax/features/namespace-prefixes feature is set to true (it is false by default).

If the namespace-prefixes feature (see above) is false access by qualified name may not be available; if the http://xml.org/sax/features/namespaces feature is false access by Namespace-qualified names may not be available.

This interface replaces the now-deprecated SAX1 AttributeList interface which does not contain Namespace support. In addition to Namespace support it adds the getIndex methods (below).

The order of attributes in the list is unspecified and will vary from implementation to implementation.

@since SAX 2.0 @author David Megginson sax@megginson.com @version 2.00r2pre @see org.xml.sax.helpers.AttributeListImpl

Class ContentHandler

Receive notification of the logical content of a document.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

This is the main interface that most SAX applications implement: if the application needs to be informed of basic parsing events it implements this interface and registers an instance with the SAX parser using the setContentHandler method. The parser uses the instance to report basic document-related events like the start and end of elements and character data.

The order of events in this interface is very important and mirrors the order of information in the document itself. For example all of an element's content (character data processing instructions and/or subelements) will appear in order between the startElement event and the corresponding endElement event.

This interface is similar to the now-deprecated SAX 1.0 DocumentHandler interface but it adds support for Namespaces and for reporting skipped entities (in non-validating XML processors).

Implementors should note that there is also a Java class ContentHandler in the java.net package; that means that it's probably a bad idea to do

import java.net.*; import org.xml.sax.*;

In fact "import ...*" is usually a sign of sloppy programming anyway so the user should consider this a feature rather than a bug.

@since SAX 2.0 @author David Megginson sax@megginson.com @version 2.00r2pre @see org.xml.sax.XMLReader @see org.xml.sax.DTDHandler @see org.xml.sax.ErrorHandler

Class DTDHandler

Receive notification of basic DTD-related events.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

If a SAX application needs information about notations and unparsed entities then the application implements this interface and registers an instance with the SAX parser using the parser's setDTDHandler method. The parser uses the instance to report notation and unparsed entity declarations to the application.

Note that this interface includes only those DTD events that the XML recommendation requires processors to report: notation and unparsed entity declarations.

The SAX parser may report these events in any order regardless of the order in which the notations and unparsed entities were declared; however all DTD events must be reported after the document handler's startDocument event and before the first startElement event.

It is up to the application to store the information for future use (perhaps in a hash table or object tree). If the application encounters attributes of type "NOTATION" "ENTITY" or "ENTITIES" it can use the information that it obtained through this interface to find the entity and/or notation corresponding with the attribute value.

@since SAX 1.0 @author David Megginson sax@megginson.com @version 2.00r2pre @see org.xml.sax.Parser#setDTDHandler @see org.xml.sax.HandlerBase

Class DocumentHandler

Receive notification of general document events.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

This was the main event-handling interface for SAX1; in SAX2 it has been replaced by ContentHandler which provides Namespace support and reporting of skipped entities. This interface is included in SAX2 only to support legacy SAX1 applications.

The order of events in this interface is very important and mirrors the order of information in the document itself. For example all of an element's content (character data processing instructions and/or subelements) will appear in order between the startElement event and the corresponding endElement event.

Application writers who do not want to implement the entire interface can derive a class from HandlerBase which implements the default functionality; parser writers can instantiate HandlerBase to obtain a default handler. The application can find the location of any document event using the Locator interface supplied by the Parser through the setDocumentLocator method.

@deprecated This interface has been replaced by the SAX2 ContentHandler interface which includes Namespace support. @since SAX 1.0 @author David Megginson sax@megginson.com @version 2.00r2pre @see org.xml.sax.Parser#setDocumentHandler @see org.xml.sax.Locator @see org.xml.sax.HandlerBase

Class EntityResolver

Basic interface for resolving entities.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

If a SAX application needs to implement customized handling for external entities it must implement this interface and register an instance with the SAX driver using the setEntityResolver method.

The XML reader will then allow the application to intercept any external entities (including the external DTD subset and external parameter entities if any) before including them.

Many SAX applications will not need to implement this interface but it will be especially useful for applications that build XML documents from databases or other specialised input sources or for applications that use URI types other than URLs.

The following resolver would provide the application with a special character stream for the entity with the system identifier "http://www.myhost.com/today":

 import org.xml.sax.EntityResolver; import org.xml.sax.InputSource; public class MyResolver implements EntityResolver { public InputSource resolveEntity (String publicId String systemId) { if (systemId.equals("http://www.myhost.com/today")) { // return a special input source MyReader reader = new MyReader(); return new InputSource(reader); } else { // use the default behaviour return null; } } } 

The application can also use this interface to redirect system identifiers to local URIs or to look up replacements in a catalog (possibly by using the public identifier).

@since SAX 1.0 @author David Megginson sax@megginson.com @version 2.00r2pre @see org.xml.sax.Parser#setEntityResolver @see org.xml.sax.InputSource

Class ErrorHandler

Basic interface for SAX error handlers.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

If a SAX application needs to implement customized error handling it must implement this interface and then register an instance with the XML reader using the setErrorHandler method. The parser will then report all errors and warnings through this interface.

WARNING: If an application does not register an ErrorHandler XML parsing errors will go unreported and bizarre behaviour may result.

For XML processing errors a SAX driver must use this interface instead of throwing an exception: it is up to the application to decide whether to throw an exception for different types of errors and warnings. Note however that there is no requirement that the parser continue to provide useful information after a call to fatalError (in other words a SAX driver class could catch an exception and report a fatalError).

@since SAX 1.0 @author David Megginson sax@megginson.com @version 2.00r2pre @see org.xml.sax.Parser#setErrorHandler @see org.xml.sax.SAXParseException

Class HandlerBase

Default base class for handlers.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

This class implements the default behaviour for four SAX1 interfaces: EntityResolver DTDHandler DocumentHandler and ErrorHandler. It is now obsolete but is included in SAX2 to support legacy SAX1 applications. SAX2 applications should use the DefaultHandler class instead.

Application writers can extend this class when they need to implement only part of an interface; parser writers can instantiate this class to provide default handlers when the application has not supplied its own.

Note that the use of this class is optional.

@deprecated This class works with the deprecated DocumentHandler interface. It has been replaced by the SAX2 DefaultHandler class. @since SAX 1.0 @author David Megginson sax@megginson.com @version 2.00r2pre @see org.xml.sax.EntityResolver @see org.xml.sax.DTDHandler @see org.xml.sax.DocumentHandler @see org.xml.sax.ErrorHandler

Class InputSource

A single input source for an XML entity.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

This class allows a SAX application to encapsulate information about an input source in a single object which may include a public identifier a system identifier a byte stream (possibly with a specified encoding) and/or a character stream.

There are two places that the application will deliver this input source to the parser: as the argument to the Parser.parse method or as the return value of the EntityResolver.resolveEntity method.

The SAX parser will use the InputSource object to determine how to read XML input. If there is a character stream available the parser will read that stream directly; if not the parser will use a byte stream if available; if neither a character stream nor a byte stream is available the parser will attempt to open a URI connection to the resource identified by the system identifier.

An InputSource object belongs to the application: the SAX parser shall never modify it in any way (it may modify a copy if necessary).

@since SAX 1.0 @author David Megginson sax@megginson.com @version 2.00r2pre @see org.xml.sax.Parser#parse @see org.xml.sax.EntityResolver#resolveEntity @see java.io.InputStream @see java.io.Reader
Class InputSource, String getSystemId()

Get the system identifier for this input source.

The getEncoding method will return the character encoding of the object pointed to or null if unknown.

If the system ID is a URL it will be fully resolved.

@return The system identifier or null if none was supplied. @see #setSystemId @see #getEncoding

Class Locator

Interface for associating a SAX event with a document location.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

If a SAX parser provides location information to the SAX application it does so by implementing this interface and then passing an instance to the application using the content handler's setDocumentLocator method. The application can use the object to obtain the location of any other content handler event in the XML source document.

Note that the results returned by the object will be valid only during the scope of each content handler method: the application will receive unpredictable results if it attempts to use the locator at any other time.

SAX parsers are not required to supply a locator but they are very strongly encouraged to do so. If the parser supplies a locator it must do so before reporting any other document events. If no locator has been set by the time the application receives the startDocument event the application should assume that a locator is not available.

@since SAX 1.0 @author David Megginson sax@megginson.com @version 2.00r2pre @see org.xml.sax.ContentHandler#setDocumentLocator
Class Locator, int getColumnNumber()

Return the column number where the current document event ends.

Warning: The return value from the method is intended only as an approximation for the sake of error reporting; it is not intended to provide sufficient information to edit the character content of the original XML document.

The return value is an approximation of the column number in the document entity or external parsed entity where the markup triggering the event appears.

If possible the SAX driver should provide the line position of the first character after the text associated with the document event.

If possible the SAX driver should provide the line position of the first character after the text associated with the document event. The first column in each line is column 1.

@return The column number or -1 if none is available. @see #getLineNumber

Class Parser

Basic interface for SAX (Simple API for XML) parsers.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

This was the main event supplier interface for SAX1; it has been replaced in SAX2 by XMLReader which includes Namespace support and sophisticated configurability and extensibility.

All SAX1 parsers must implement this basic interface: it allows applications to register handlers for different types of events and to initiate a parse from a URI or a character stream.

All SAX1 parsers must also implement a zero-argument constructor (though other constructors are also allowed).

SAX1 parsers are reusable but not re-entrant: the application may reuse a parser object (possibly with a different input source) once the first parse has completed successfully but it may not invoke the parse() methods recursively within a parse.

@deprecated This interface has been replaced by the SAX2 XMLReader interface which includes Namespace support. @since SAX 1.0 @author David Megginson sax@megginson.com @version 2.00r2pre @see org.xml.sax.EntityResolver @see org.xml.sax.DTDHandler @see org.xml.sax.DocumentHandler @see org.xml.sax.ErrorHandler @see org.xml.sax.HandlerBase @see org.xml.sax.InputSource

Class SAXException

Encapsulate a general SAX error or warning.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

This class can contain basic error or warning information from either the XML parser or the application: a parser writer or application writer can subclass it to provide additional functionality. SAX handlers may throw this exception or any exception subclassed from it.

If the application needs to pass through other types of exceptions it must wrap those exceptions in a SAXException or an exception derived from a SAXException.

If the parser or application needs to include information about a specific location in an XML document it should use the SAXParseException subclass.

@since SAX 1.0 @author David Megginson sax@megginson.com @version 2.00r2pre w/ JAXP 1.1 signatures @see org.xml.sax.SAXParseException

Class SAXNotRecognizedException

Exception class for an unrecognized identifier.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

An XMLReader will throw this exception when it finds an unrecognized feature or property identifier; SAX applications and extensions may use this class for other similar purposes.

@since SAX 2.0 @author David Megginson sax@megginson.com @version 2.00r2pre w/ JAXP 1.1 signatures @see org.xml.sax.SAXNotSupportedException

Class SAXNotSupportedException

Exception class for an unsupported operation.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

An XMLReader will throw this exception when it recognizes a feature or property identifier but cannot perform the requested operation (setting a state or value). Other SAX2 applications and extensions may use this class for similar purposes.

@since SAX 2.0 @author David Megginson sax@megginson.com @version 2.00r2pre w/ JAXP 1.1 signatures @see org.xml.sax.SAXNotRecognizedException

Class SAXParseException

Encapsulate an XML parse error or warning.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

This exception will include information for locating the error in the original XML document. Note that although the application will receive a SAXParseException as the argument to the handlers in the ErrorHandler interface the application is not actually required to throw the exception; instead it can simply read the information in it and take a different action.

Since this exception is a subclass of SAXException it inherits the ability to wrap another exception.

@since SAX 1.0 @author David Megginson sax@megginson.com @version 2.00r2pre @see org.xml.sax.SAXException @see org.xml.sax.Locator @see org.xml.sax.ErrorHandler

Class XMLFilter

Interface for an XML filter.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

An XML filter is like an XML reader except that it obtains its events from another XML reader rather than a primary source like an XML document or database. Filters can modify a stream of events as they pass on to the final application.

The XMLFilterImpl helper class provides a convenient base for creating SAX2 filters by passing on all EntityResolver DTDHandler ContentHandler and ErrorHandler events automatically.

@since SAX 2.0 @author David Megginson sax@megginson.com @version 2.00r2pre @see org.xml.sax.helpers.XMLFilterImpl

Class XMLReader

Interface for reading an XML document using callbacks.
This module both source code and documentation is in the Public Domain and comes with NO WARRANTY.

Note: despite its name this interface does not extend the standard Java Reader interface because reading XML is a fundamentally different activity than reading character data.

XMLReader is the interface that an XML parser's SAX2 driver must implement. This interface allows an application to set and query features and properties in the parser to register event handlers for document processing and to initiate a document parse.

All SAX interfaces are assumed to be synchronous: the parse methods must not return until parsing is complete and readers must wait for an event-handler callback to return before reporting the next event.

This interface replaces the (now deprecated) SAX 1.0 Parser interface. The XMLReader interface contains two important enhancements over the old Parser interface:

  1. it adds a standard way to query and set features and properties; and
  2. it adds Namespace support which is required for many higher-level XML standards.

There are adapters available to convert a SAX1 Parser to a SAX2 XMLReader and vice-versa.

@since SAX 2.0 @author David Megginson sax@megginson.com @version 2.00r2pre @see org.xml.sax.XMLFilter @see org.xml.sax.helpers.ParserAdapter @see org.xml.sax.helpers.XMLReaderAdapter