org.openxml.source
Class Holder

java.lang.Object
  |
  +--org.openxml.source.Holder

public abstract class Holder
extends java.lang.Object

Interface describing a document holder. Holder classes are used to provide access to documents through various protocols and storages locations (network, file system, JAR, etc) and to support document caching.

The holder implements methods for determining whether the source document can be cached (canCache()) and whether the cached image is up to date (hasModified()). It also provides access to the document source through getReader(). It is up to the particular holder to determine how to implement these features.

The document is obtained using two methods. getReadOnly() returns a read-only instance of the document that should not be modified by the application. If the document supports caching, newInstance() returns a new modifiable instance of the document each time. The application may modify a given instance without affecting other instances. If the document does not support caching, then both methods return the same single instance, but calling HolderFactory.newHolder(org.openxml.source.Source) will return a different holder each time.

Version:
$Revision: 1.5 $ $Date: 1999/04/18 01:51:58 $
Author:
Assaf Arkin
See Also:
HolderFactory

Constructor Summary
Holder()
           
 
Method Summary
abstract  boolean canCache()
          Returns true if document can be cached.
abstract  java.lang.String getEncoding()
          Returns the encoding for reading the source.
abstract  SAXException getLastException()
          Returns the last exception generated when parsing the document.
abstract  java.io.Reader getReader()
          Returns a reader for the source.
abstract  Document getReadOnly()
          Returns a read-only instance of the document.
abstract  java.lang.String getURI()
          Returns the source URI.
abstract  boolean hasModified()
          Returns true if the source has been modified since it was created.
abstract  Document newInstance()
          Returns a new modifiable instance of the document.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Holder

public Holder()
Method Detail

canCache

public abstract boolean canCache()
Returns true if document can be cached. Some document can be cached and will only be reloaded if the original source has been updated. The holder must be capable of determining if the document can be cached, if in doubt, it should return false.
Returns:
True if document can be cached

hasModified

public abstract boolean hasModified()
Returns true if the source has been modified since it was created. The holder must be capable of determining whether the source has been modified since construction, if in doubt, it should return true.
Returns:
True if source has been modified

getURI

public abstract java.lang.String getURI()
Returns the source URI. This name might be different than the one by which the source was requested and will be used for caching the source.
Returns:
The resource URI

getReader

public abstract java.io.Reader getReader()
                                  throws java.io.IOException
Returns a reader for the source. This reader is used by the parser and should assume the specified encoding, unless a different encoding has been determined. A new reader is returned each time this method is called.
Returns:
The reader for the source
Throws:
java.io.IOException - Failed to create a reader for this source

getEncoding

public abstract java.lang.String getEncoding()
Returns the encoding for reading the source. A default encoding might have been specified when the holder was created, or derived from the source itself (e.g. the content type returned by a Web server).
Returns:
Default encoding or null

getReadOnly

public abstract Document getReadOnly()
Returns a read-only instance of the document. The read-only instance is the one cached by this holder (if caching is supported) and the caller agrees not to modify its contents. The same document will be returned each time this method is called.

A default implementation would call getReader() to obtain a reader to the source, parse the document using the selected document class, and returns that document. The document is rendered read-only only if this holder can be cached.

Returns:
A read-only instance of the document

newInstance

public abstract Document newInstance()
Returns a new modifiable instance of the document. This instance can be modified by the caller without affecting other callers requesing the same source. A new instance will be returned each time this method is called. However, if caching is not supported by this holder, this method is equivalent to calling getReadOnly().

A default implementation would obtain the instance from getReadOnly(); if caching is supported, a new modifiable instance woudld be created and returned, otherwise, the same instance would be returned.

Returns:
A new modifiable instance of the document

getLastException

public abstract SAXException getLastException()
Returns the last exception generated when parsing the document. The return value is only valid after obtaining a document instance, and will indicate a validity or well formed parsing exception. I/O exceptions are thrown directly by the document retrieving methods.
Returns:
Last error generated when parsing document