org.openxml.beans
Class SourceBean

java.lang.Object
  |
  +--org.openxml.source.Source
        |
        +--org.openxml.source.holders.SourceImpl
              |
              +--org.openxml.beans.SourceBean

public class SourceBean
extends org.openxml.source.holders.SourceImpl

Defines the source for an XML document and parses the document. This class supports a bean-like and utility interfaces. An XML source is constructed to describe the location of an XML document, the document type and the default encoding. The document is then parsed and returned, including any errors generated during parsing.

The bean-like interface is realized through get/set methods that affect its properties. The document is then retrieved by calling SourceImpl.getDocument(). If a new document is required, the properties can be changed and the document retrieved by calling SourceImpl.forget() first.

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 Source.DOCUMENT_XML), an HTML document (Source.DOCUMENT_HTML) or an HTML document (Source.DOCUMENT_HTML). User XML documents may also be requested by passing a class that extends XMLDocument, 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 parsed and retrieved by calling SourceImpl.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 found or parsed completely, null is returned. The error exception may be obtained by calling SourceImpl.getLastException(). The returned exception class may be castable to ParseException.

The source may be parsed asynchronously by calling SourceImpl.asynch(). A new thread will be initiated for parsing the document in the background. SourceImpl.getDocument() will then return that document. Some setter methods will be blocked until SourceImpl.asynch() completes parsing the document.

A number of static methods are provided for directly reading documents or known types. These methods simply wrap a source constructor and call to SourceImpl.getDocument().

XML sources benefit from parsed document caching, public identifier mapping, and support for resourc documents that is provided by the holder mechanism. The following URI formats are natively supported by this mechanism:

Version:
$Revision: 1.2 $ $Date: 1999/02/25 04:00:49 $
Author:
Assaf Arkin
See Also:
Serialized Form

Field Summary
protected  java.beans.PropertyChangeSupport _propChange
          Helper object to implement property change events and listeners.
 
Fields inherited from class org.openxml.source.holders.SourceImpl
_asyncThread, _docClass, _document, _encoding, _holder, _lastException, _publicId, _readOnly, _uri
 
Fields inherited from class org.openxml.source.Source
DOCUMENT_DTD, DOCUMENT_HTML, DOCUMENT_XML
 
Constructor Summary
SourceBean()
          Constructs a new source with no parameters.
SourceBean(java.lang.String uri)
          Constructs a new source with the supplied parameters.
SourceBean(java.lang.String uri, java.lang.Class docClass)
          Constructs a new source with the supplied parameters.
SourceBean(java.lang.String uri, java.lang.String encoding)
          Constructs a new source with the supplied parameters.
SourceBean(java.lang.String uri, java.lang.String publicId, java.lang.String encoding)
          Constructs a new source with the supplied parameters.
SourceBean(java.lang.String uri, java.lang.String publicId, java.lang.String encoding, java.lang.Class docClass)
          Constructs a new source with the supplied parameters.
 
Method Summary
 void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
          Assigns a property change listener.
 java.lang.String getDocClassName()
          Returns the document class.
protected  void notifyComplete()
           
static Document readDTD(java.io.File file, java.lang.String encoding)
          Reads and returns an DTD document from the file.
static Document readDTD(java.lang.String uri, java.lang.String encoding)
          Reads and returns an DTD document from the URI.
static Document readHTML(java.io.File file, java.lang.String encoding)
          Reads and returns an HTML document from the file.
static Document readHTML(java.lang.String uri, java.lang.String encoding)
          Reads and returns an HTML document from the URI.
static Document readXML(java.io.File file, java.lang.String encoding)
          Reads and returns an XML document from the file.
static Document readXML(java.lang.String uri, java.lang.String encoding)
          Reads and returns an XML document from the URI.
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Removes a property change listener.
 void setDocClass(java.lang.Class docClass)
          Sets the requested document class.
 void setDocClassName(java.lang.String className)
          Sets the requested document class.
 void setEncoding(java.lang.String encoding)
          Sets the default source encoding.
 void setPublicId(java.lang.String publicId)
          Sets the public identifier for this document.
 void setReadOnly(boolean readOnly)
          If true, requests a read-only instance of the document that may be read, clones, but not modified.
 void setURI(java.lang.String uri)
          Sets the URI for this document.
 
Methods inherited from class org.openxml.source.holders.SourceImpl
asynch, forget, getClassDTD, getClassHTML, getClassXML, getDocClass, getDocument, getEncoding, getLastException, getPublicId, getURI, run, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

_propChange

protected transient java.beans.PropertyChangeSupport _propChange
Helper object to implement property change events and listeners.
Constructor Detail

SourceBean

public SourceBean(java.lang.String uri,
                  java.lang.String publicId,
                  java.lang.String encoding,
                  java.lang.Class docClass)
Constructs a new source with the supplied parameters. All parameters are optional. For more information, see the related get methods.
Parameters:
uri - The source URI, or null
publicId - The source public identifier, or null
encoding - Default encoding, or null
docClass - Requested document class, or null

SourceBean

public SourceBean(java.lang.String uri,
                  java.lang.String publicId,
                  java.lang.String encoding)
Constructs a new source with the supplied parameters. All parameters are optional. For more information, see the related get methods.
Parameters:
uri - The source URI, or null
publicId - The source public identifier, or null
encoding - Default encoding, or null

SourceBean

public SourceBean(java.lang.String uri,
                  java.lang.String encoding)
Constructs a new source with the supplied parameters. All parameters are optional. For more information, see the related get methods.
Parameters:
uri - The source URI, or null
encoding - Default encoding, or null

SourceBean

public SourceBean(java.lang.String uri,
                  java.lang.Class docClass)
Constructs a new source with the supplied parameters. All parameters are optional. For more information, see the related get methods.
Parameters:
uri - The source URI, or null
docClass - Requested document class, or null

SourceBean

public SourceBean(java.lang.String uri)
Constructs a new source with the supplied parameters. All parameters are optional. For more information, see the related get methods.
Parameters:
uri - The source URI, or null

SourceBean

public SourceBean()
Constructs a new source with no parameters.
Method Detail

readXML

public static Document readXML(java.lang.String uri,
                               java.lang.String encoding)
Reads and returns an XML document from the URI. If the source could not be found or accessed, null is returned. The returned document is of the specified type, unless type has been modified based on the source.
Parameters:
uri - The source URI
encoding - The source encoding, or null
Returns:
An XML document, or null

readXML

public static Document readXML(java.io.File file,
                               java.lang.String encoding)
Reads and returns an XML document from the file. If the source could not be found or accessed, null is returned. The returned document is of the specified type, unless type has been modified based on the source.
Parameters:
file - The source file
encoding - The source encoding, or null
Returns:
An XML document, or null

readHTML

public static Document readHTML(java.lang.String uri,
                                java.lang.String encoding)
Reads and returns an HTML document from the URI. If the source could not be found or accessed, null is returned. The returned document is of the specified type, unless type has been modified based on the source.
Parameters:
uri - The source URI
encoding - The source encoding, or null
Returns:
An HTML document, or null

readHTML

public static Document readHTML(java.io.File file,
                                java.lang.String encoding)
Reads and returns an HTML document from the file. If the source could not be found or accessed, null is returned. The returned document is of the specified type, unless type has been modified based on the source.
Parameters:
file - The source file
encoding - The source encoding, or null
Returns:
An HTML document, or null

readDTD

public static Document readDTD(java.lang.String uri,
                               java.lang.String encoding)
Reads and returns an DTD document from the URI. If the source could not be found or accessed, null is returned. The returned document is of the specified type, unless type has been modified based on the source.
Parameters:
uri - The source URI
encoding - The source encoding, or null
Returns:
An DTD document, or null

readDTD

public static Document readDTD(java.io.File file,
                               java.lang.String encoding)
Reads and returns an DTD document from the file. If the source could not be found or accessed, null is returned. The returned document is of the specified type, unless type has been modified based on the source.
Parameters:
file - The source file
encoding - The source encoding, or null
Returns:
An DTD document, or null

setURI

public 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 SourceImpl.forget() is called.
Parameters:
uri - The document URI, or null
Overrides:
setURI in class org.openxml.source.holders.SourceImpl

setPublicId

public 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 SourceImpl.forget() is called.
Parameters:
publicId - The document public identifer, or null
Overrides:
setPublicId in class org.openxml.source.holders.SourceImpl

setDocClass

public 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, DTDDocument or any class derived from XMLDocument may be used.
Parameters:
className - The requested document class
Overrides:
setDocClass in class org.openxml.source.holders.SourceImpl

setReadOnly

public 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
Overrides:
setReadOnly in class org.openxml.source.holders.SourceImpl

setEncoding

public 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
Overrides:
setEncoding in class org.openxml.source.holders.SourceImpl

setDocClassName

public void setDocClassName(java.lang.String className)
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, DTDDocument or any class derived from XMLDocument may be used.
Parameters:
className - The requested document class

getDocClassName

public java.lang.String getDocClassName()
Returns the document class. This is the class requested for the parsed document, or if parsed the actual class of the parsed document.
Returns:
The document class

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Assigns a property change listener. This listener will recieve a property change event whenever a property of this bean has changed, either as a result of changing the property, or of retrieving a document.

Property change events are fired for changed on the following properties:

Parameters:
listener - The listener to assign

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Removes a property change listener. This listener will not longer recieve property change events for this bean.
Parameters:
listener - The listener to remove

notifyComplete

protected void notifyComplete()
Overrides:
notifyComplete in class org.openxml.source.holders.SourceImpl