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