org.openxml.source
Class Source

java.lang.Object
  |
  +--org.openxml.source.Source
Direct Known Subclasses:
org.openxml.source.holders.SourceImpl

public abstract class Source
extends java.lang.Object

Defines the source for an XML document. This interface describes the location of an XML document, the document type and the default encoding. It is used to retrieve an in-memory document tree and check for any errors in the retrieval process. It is not specified how the retrieval is implemented, parsing is assumed.

A source is identified by four parameters. The URI specifies a source that can be a network URL, file URL, resource contained in JAR file, etc. The public identifier is an alternative named that may be mapped to a URI. A default character encoding may be specified and will be used, unless the document source enforces another encoding, e.g. in the content type returned from a Web server, or in the document declaration.

A specific document type may be requested and will be returned, unless the document source indicates a different document type, e.g. in the content type returned from a Web server. The document type is specified by requesting an XML document (null, or DOCUMENT_XML), an HTML document (DOCUMENT_HTML) or an HTML document (DOCUMENT_HTML). User XML documents may also be requested by passing a class that extends Document, see the later for more details.

setReadOnly(boolean) may be set to request a read only image of the document. That document may not be edited, but may wholly or partly cloned into an editable document. The default behavior returns a new document instance each time and that document may be modified without affecting previously returned instances. Put otherwise, getDocument() != getDocument().

The source is retrieved by calling getDocument(). This will return a document of the requested class, unless the source forced a different class to be parsed. If the document cannot be retrieved completely, null is returned. The error exception may be obtained by calling getLastException().

Version:
$Revision: 1.1 $ $Date: 1999/02/20 02:19:00 $
Author:
Assaf Arkin

Field Summary
static java.lang.Class DOCUMENT_DTD
          Request a DTD document from the source.
static java.lang.Class DOCUMENT_HTML
          Request a HTML document from the source.
static java.lang.Class DOCUMENT_XML
          Request a XML document from the source.
 
Constructor Summary
Source()
           
 
Method Summary
abstract  void forget()
          Forget about the and be prepared to retrieve from a different source.
abstract  java.lang.Class getDocClass()
          Returns the document class.
abstract  Document getDocument()
          Returns the document read from this source.
abstract  java.lang.String getEncoding()
          Returns the source encoding.
abstract  java.lang.Exception getLastException()
          Returns the last exception generated by an attempt to parse the source.
abstract  java.lang.String getPublicId()
          Return the public identifier for this document.
abstract  java.lang.String getURI()
          Returns the URI for this document.
abstract  void setDocClass(java.lang.Class docClass)
          Sets the requested document class.
abstract  void setEncoding(java.lang.String encoding)
          Sets the default source encoding.
abstract  void setPublicId(java.lang.String publicId)
          Sets the public identifier for this document.
abstract  void setReadOnly(boolean readOnly)
          If true, requests a read-only instance of the document that may be read, clones, but not modified.
abstract  void setURI(java.lang.String uri)
          Sets the URI for this document.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DOCUMENT_XML

public static final java.lang.Class DOCUMENT_XML
Request a XML document from the source. The returned document will be of type Document, unless otherwise specified by the source.

DOCUMENT_HTML

public static final java.lang.Class DOCUMENT_HTML
Request a HTML document from the source. The returned document will be of type HTMLDocument, unless otherwise specified by the source.

DOCUMENT_DTD

public static final java.lang.Class DOCUMENT_DTD
Request a DTD document from the source. The returned document will be of type DocumentType, unless otherwise specified by the source.
Constructor Detail

Source

public Source()
Method Detail

getDocument

public abstract Document getDocument()
Returns the document read from this source. If the document could not be found or parsed, null is returned and the last error could be found with getLastException(). The returned document type is based on the requested document type (Document by default) or the the document type specified by the source.

If in read-only mode, a single instance of a read-only document will be returned. If not in read-only mode, a new modifiable instance of the document will be returned each time this method is called.


getLastException

public abstract java.lang.Exception getLastException()
Returns the last exception generated by an attempt to parse the source. This exception may be due to inability to access the source (@link Exception}) or a result of parsing the source (ParseException).
Returns:
The last parsing exception

forget

public abstract void forget()
Forget about the and be prepared to retrieve from a different source. The URI or public identifier may be changed, but to retrieve a document from the new source, this method must be called first.

setURI

public abstract void setURI(java.lang.String uri)
Sets the URI for this document. Most document are identified by a URI that might be a network URL, a file URL, or some other regcognized identifier. Changing the URI will not return a new document until after forget() is called.
Parameters:
uri - The document URI, or null

getURI

public abstract java.lang.String getURI()
Returns the URI for this document.
Returns:
The document URI, or null

setPublicId

public abstract void setPublicId(java.lang.String publicId)
Sets the public identifier for this document. Some documents are located by a public identifier that is not a valid URI but might be translated into one. If the public identifier is not recognized, the document URI must be used. Changing the public identifier will not return a new document until after forget() is called.
Parameters:
publicId - The document public identifer, or null

getPublicId

public abstract java.lang.String getPublicId()
Return the public identifier for this document. Some documents are located by a public identifier that is not a valid URI.
Returns:
The document public identifer, or null

setEncoding

public abstract void setEncoding(java.lang.String encoding)
Sets the default source encoding. This encoding is used to parse the source, unless a different encoding is specified, e.g. by the content type returned from a Web server, or in the document declaration. If no encoding is specified, the default "UTF8" is assumed.
Parameters:
encoding - The default document encoding, or null

getEncoding

public abstract java.lang.String getEncoding()
Returns the source encoding. This encoding was used to parse the source.
Returns:
The document encoding, or null

setDocClass

public abstract void setDocClass(java.lang.Class docClass)
Sets the requested document class. The source will be parsed and returned in a document of this class, unless otherwise specified, e.g. by the content type returned from a Web server. The default document type is Document; HTMLDocument, DocumentType or any class derived from Document may be used.
Parameters:
className - The requested document class

getDocClass

public abstract java.lang.Class getDocClass()
Returns the document class. This is the class requested for the parsed document.
Returns:
The document class

setReadOnly

public abstract void setReadOnly(boolean readOnly)
If true, requests a read-only instance of the document that may be read, clones, but not modified. If false (default), a new instance of the document will be returned each time and this instance may be modified without affecting other instances.
Parameters:
readOnly - True if read-only instance is required