javax.ide.model
Class DocumentFactory

java.lang.Object
  javax.ide.Service
      javax.ide.model.DocumentFactory

public abstract class DocumentFactory
extends Service

The DocumentFactory interface is responsible for creating intances of Documents.

The type of Document that gets created depends on the URI that is passed into the findOrCreate(URI) method. The DocumentFactory makes use of registered Recognizer instances to determine what Document class corresponds to a particular URI.

JSR-198 specifies a number of ways to recognize documents:

• 1. By recognizing characteristics of the URI,
• 2. For XML documents by recognizing certain markups, and
• 3. By allowing extension writers to have full control of how a document should be recognized.

For case 1. extension writers need only map a file extension or some part of the URI to a document interface.

For case 2. extension writers can map the XML namespace, doctype, or root element to a document interface.

For case3. extension writers can introduce their own custom Recognizer.

Every Document instance created by the DocumentFactory is cached. An instance of an already created Document can be retrieved from the cache by calling the find(URI) method.

See Also:

Document

Constructor Summary

DocumentFactory()

Method Summary

abstract Document	find(java.net.URI uri) Find the Document associated with the URI.
abstract Document	findOrCreate(java.net.URI uri) Returns the Document associated with the URI.
abstract java.util.Collection	getCachedDocuments() Returns a Collection of the Document instances that are currently cached.
static DocumentFactory	getDocumentFactory() Get the DocumentFactory implementation for this IDE.
abstract Document	recache(java.net.URI oldURI, java.net.URI newURI) Removes the oldURI from the cache and puts the newURI in the cache so that it is associated with the original Document oldURI pointed at.
abstract Document	uncache(java.net.URI uri) Remove the specified URI from the cache.

Methods inherited from class javax.ide.Service

getService, initialize, resetAllServices

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DocumentFactory

public DocumentFactory()

Method Detail

findOrCreate

public abstract Document findOrCreate(java.net.URI uri)
                               throws java.lang.IllegalAccessException,
                                      java.lang.InstantiationException,
                                      java.lang.ClassNotFoundException

Returns the Document associated with the URI. If the Document does not exist and the URI corresponds to a resource that does exists, a new Document of the correct type is created.

Parameters:

uri - unique URI identifying the document. Must not be null.

Returns:

An existing document or a newly created one. Will return null if the specified uri does not exist.

Throws:

java.lang.IllegalAccessException - When the Document interface or its initializer is not accessible.

java.lang.InstantiationException - When the document is an abstract class, an interface, an array class, a primitive type, or void; or if the instantiation fails for some other reason.

java.lang.ClassNotFoundException - When the Class is not found.

find

public abstract Document find(java.net.URI uri)

Find the Document associated with the URI. If the Document does not exist, null is returned.

Parameters:

uri - URI identifying the Document. Must not be null.

Returns:

An existing Document, or null if none exists.

recache

public abstract Document recache(java.net.URI oldURI,
                                 java.net.URI newURI)

Removes the oldURI from the cache and puts the newURI in the cache so that it is associated with the original Document oldURI pointed at.

Parameters:

oldURI - the old URI of the document. Must not be null.

newURI - the new URI of the document. Must not be null.

Returns:

the cached document. May be null if no previous document was cached at this URI.

uncache

public abstract Document uncache(java.net.URI uri)

Remove the specified URI from the cache.

Parameters:

uri - the uri to remove from the cache. Must not be null.

Returns:

the document that was uncached, or null if no document was uncached.

getCachedDocuments

public abstract java.util.Collection getCachedDocuments()

Returns a Collection of the Document instances that are currently cached. The iteration order of the returned collection is not guaranteed.

Returns:

a collection of Documents. Never returns null, may return an empty collection. The collection is immutable.

getDocumentFactory

public static DocumentFactory getDocumentFactory()

Get the DocumentFactory implementation for this IDE.

Returns:

the DocumentFactory implementation for this IDE.