Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep

Source code: javax/ide/model/DocumentFactory.java


1   package javax.ide.model;
2   
3   import java.net.URI;
4   import java.util.Collection;
5   
6   import javax.ide.spi.ProviderNotFoundException;
7   import javax.ide.Service;
8   import javax.ide.util.MetaClass;
9   
10  /**
11   *  The {@link DocumentFactory} interface is responsible for creating
12   *  intances of {@link Document}s.<P>
13   *
14   *  The type of {@link Document} that gets created depends on the
15   *  {@link URI} that is passed into the {@link #findOrCreate(URI)} and
16   *  {@link #findOrCreate(MetaClass, URI)} methods.  The {@link DocumentFactory}
17   *  makes use of registered {@link Recognizer} instances to determine
18   *  what {@link Document} class corresponds to a particular {@link URI}.<P>
19   *
20   *  JSR-198 specifies a number of ways to recognize documents:<p>
21   *
22   *  <ul>
23   *    <li>1. By recognizing characteristics of the <code>URI</code>,<li><p>
24   *    <li>2. For XML documents by recognizing certain markups, and <li><p>
25   *    <li>3. By allowing extension writers to have full control of how a 
26   *    document should be recognized.<li><p>
27   *  </ul>
28   *
29   *  For case 1. extension writers need only map a file extension or some
30   *  part of the <code>URI</code> to a document interface.<p>
31   *
32   *  For case 2. extension writers can map the XML namespace, doctype, or
33   *  root element to a document interface.<p>
34   *
35   *  For case3. extension writers can introduce their own custom 
36   *  <code>Recognizer</code>.<p>
37   *
38   *  Every {@link Document} instance created by the {@link DocumentFactory}
39   *  is cached.  An instance of an already created {@link Document} can be
40   *  retrieved from the cache by calling the {@link #find(URI)} method.
41   *
42   *  @see Document
43   */
44  public abstract class DocumentFactory extends Service
45  {
46    /**
47     *  Returns the {@link Document} associated with the {@link URI}.  If the
48     *  {@link Document} does not exist, a new {@link Document} is created.<P>
49     *
50     *  @return An existing document or a newly created one.
51     *
52     *  @param uri unique {@link URI} identifying the document.
53     *
54     *  @exception  IllegalAccessException When the {@link Document} interface or
55     *  its initializer is not accessible.
56     *
57     *  @exception  InstantiationException When the document is an abstract 
58     *  class, an interface, an array class, a primitive type,
59     *  or void; or if the instantiation fails for some other reason.
60     *
61     *  @exception ClassNotFoundException When the {@link Class} is not found.
62     */
63    public abstract Document findOrCreate( URI uri )
64                    throws IllegalAccessException, 
65                           InstantiationException,
66                           ClassNotFoundException;
67  
68    /**
69     *  Returns the {@link Document} associated with the {@link URI}.  If the
70     *  {@link Document} does not exist, a new {@link Document} is created.<P>
71     *
72     *  @return  an existing {@link Document} or a newly created one.
73     *
74     *  @param type The {@link MetaClass} of the document type to create.
75     *
76     *  @param uri  {@link URI} identifying the document's persistent location.
77     *
78     *  @exception  IllegalAccessException  if the {@link Class} or its
79     *  initializer is not accessible.
80     *
81     *  @exception  InstantiationException  if the {@link Class} is an
82     *  abstract class, an interface, an array class, a primitive type, or
83     *  void; or if the instantiation fails for some other reason.
84     *
85     *  @exception ClassNotFoundException When the {@link Class} is not found.
86     */
87    public abstract Document findOrCreate( MetaClass type, URI uri )
88                                                  throws IllegalAccessException, 
89                                                         InstantiationException,
90                                                         ClassNotFoundException;
91  
92    /**
93     *  Find the {@link Document} associated with the {@link URI}.  If the
94     *  {@link Document} does not exist, <CODE>null</CODE> is returned.
95     *
96     *  @return  An existing {@link Document}, or <CODE>null</CODE> if none
97     *  exists.
98     *
99     *  @param  uri  {@link URI} identifying the {@link Document}.
100    */
101   public abstract Document find( URI uri );
102 
103   /**
104    *  Removes the <CODE>oldURI</CODE> from the cache and puts the
105    *  <CODE>newURI</CODE> in the cache so that it is associated
106    *  with the given {@link Document}.
107    *
108    *  @param oldURI the old URI of the document.
109    *  @param newURI the new URI of the document.
110    *  @param document the document to recache.
111    *  @return the previously cached document.
112    */
113   public abstract Document recache( URI oldURI, URI newURI, Document document );
114 
115   /**
116    *  Returns a {@link Collection} of the {@link Document} instances that
117    *  are currently cached.  The iteration order of the returned collection is
118    *  not guaranteed.
119    *  
120    *  @return a collection of {@link Document}s.
121    */
122   public abstract Collection getCachedDocuments();
123 
124   /**
125    *  Returns the recognized {@link MetaClass} for a URI.
126    *  
127    *  @param uri the URI to look up.
128    *  @return the meta class that the specified uri is recognized as. Will
129    *      return null if the uri is not recognized.
130    */
131   public abstract MetaClass recognize( URI uri );
132 
133   /**
134    * Returns a {@link MetaClass} collection of recognized documents.
135    * 
136    * @return a collection of {@link MetaClass}es.
137    */
138   public abstract Collection getRecognizedDocuments();
139 
140   /**
141    * Find the document type identifier for the given document {@link Class}. 
142    * The identifier comes from the document declaration in the Extension 
143    * Deployment Descriptor.
144    *
145    * @param clazz The document class for which we need the <code>ID</code>.
146    * @param useInheritance If a type identifier is not found for the 
147    * specified <code>clazz</code>, the method will walk up the class 
148    * hierarchy until it finds a type identifier.
149    *
150    * @return A document type identifier or null if none found.
151    */
152   public abstract String findDocumentTypeIdentifier( Class clazz, 
153                                             boolean useInheritance );
154 
155 
156   /**
157    * Get the DocumentFactory implementation for this IDE.
158    * 
159    * @return the DocumentFactory implementation for this IDE.
160    */
161   public static DocumentFactory getDocumentFactory()
162   {
163     try
164     {
165       return (DocumentFactory) getService( DocumentFactory.class );
166     }
167     catch ( ProviderNotFoundException lnfe )
168     {
169       lnfe.printStackTrace();
170       throw new IllegalStateException( "No document factory." );
171     }
172   }
173 }
174