1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
|
/*******************************************************************************
* Copyright (c) 2005, 2006 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
* yyyymmdd bug Email and other contact information
* -------- -------- -----------------------------------------------------------
* 20060906 141796 gilberta@ca.ibm.com - Gilbert Andrews
*******************************************************************************/
package org.eclipse.wst.ws.internal.registry;
import java.net.MalformedURLException;
import java.net.URL;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.wst.ws.internal.model.v10.registry.Registry;
import org.eclipse.wst.ws.internal.model.v10.taxonomy.Taxonomy;
/**
* An IRegistryManager manages a family of <code>Registry</code>
* and <code>Taxonomy</code> models persisted within some
* addressable location such as under a directory in the
* filesystem or under a folder in the Eclipse workspace,
* and referenced from an index document at the same location.
* <p>
* Call <code>RegisteryService.getDefaultRegistryManager()</code>
* or <code>RegisteryService.getRegistryManager(URL)</code> to
* get a new IRegistryManager.
*
* @see org.eclipse.wst.ws.internal.registry.RegistryService#instance()
* @see org.eclipse.wst.ws.internal.model.v10.registry.Registry
* @see org.eclipse.wst.ws.internal.model.v10.taxonomy.Taxonomy
* @author cbrealey
*/
public interface IRegistryManager
{
/**
* A constant for use in the <code>removeRegistry(...)</code>
* and <code>removeTaxonomy(...)</code> methods that will
* cause the given registry or taxonomy document to be removed
* from the index, but not deleted.
*
* @see #removeRegistry(String, boolean)
* @see #removeTaxonomy(String, boolean)
*/
public boolean KEEP_DOCUMENT = false;
/**
* A constant for use in the <code>removeRegistry(...)</code>
* and <code>removeTaxonomy(...)</code> methods that will
* cause the given registry or taxonomy document to be removed
* from the index and deleted.
*
* @see #removeRegistry(String, boolean)
* @see #removeTaxonomy(String, boolean)
*/
public boolean DELETE_DOCUMENT = true;
/**
* Returns the URL of the XML index document that references
* the XML registry and taxonomy models managed by this
* Registry Manager.
*
* @return The URL of the managing document.
* @throws MalformedURLException If a URL to the managing
* document cannot be determined or created.
*/
public URL getURL () throws MalformedURLException;
/**
* Adds an <code>ITaxonomyFinder</code> that the
* <code>IRegistryManager</code> can use to find
* the set of <code>Taxonomy</code> models used
* by a given <code>Registry</code> model.
* <code>IRegistryManager.save(registry)</code> needs help finding
* the <code>Taxonomy</code> models used by a <code>Registry</code>,
* if any.
*
* @param className The name of the concrete <code>Registry<code>
* class for which the <code>ITaxonomyFinder</code> is being added.
* @param taxonomyFinder An <code>ITaxonomyFinder</code> that knows
* how to determine the set of <code>Taxonomy</code> models a given
* concrete <code>Registry</code> model is using.
* @see ITaxonomyFinder
* @see #saveRegistry(Registry)
*/
public void addTaxonomyFinder ( String className, ITaxonomyFinder taxonomyFinder );
/**
* Destroys the index of registries and taxonomies in memory.
* Subsequent calls to <code>getIndex()</code> and other methods
* of this interface will cause the index to be reloaded.
* This method should be called anytime the caller suspects the
* persistent index has changed and wishes to load the changes
* into the current <code>IRegistryManager</code>.
*/
public void refreshManager ();
/**
* Saves a <code>Taxonomy</code> model to an XML document
* located relative to the index XML document as identified by
* <code>getURL()</code>, and updates the index XML document
* with references to the saved taxonomy document.
* The relative pathname to the taxonomy XML document is
* computed by the <code>IRegistryManager</code> and cannot
* be influenced by the caller.
*
* @param registry The <code>Registry</code> model (and
* referenced <code>Taxonomy</code> models) to save.
* @return A <code>Registry</code> reference.
* @throws CoreException If the operation fails for any reason,
* including but not limited to malformed location URIs in the
* index or general input/output error conditions.
* @see Registry
* @see #addTaxonomyFinder(String, ITaxonomyFinder)
*/
public Registry saveRegistry ( Registry registry ) throws CoreException;
/**
* Loads as necessary and returns a full <code>Registry</code>
* model as identified by the given URI and referenced from
* the index XML document located at <code>getURL()</code>.
*
* @param uri The URI identifier of the registry.
* @return The <code>Registry</code> model
* or null if no such model can be found.
* @throws CoreException If the operation fails for any reason,
* including but not limited to malformed location URIs in the
* index or general input/output error conditions.
* @see Registry
*/
public Registry loadRegistry ( String uri ) throws CoreException;
/**
* Loads as necessary and returns an array of full <code>Registry</code>
* models as identified by the given array of URIs and referenced from
* the index XML document located at <code>getURL()</code>.
* Useful in conjunction with <code>getRegistryURIs()</code>.
* Note that the length of the returned array may be less than
* the length of the array of URIs in cases where one or more
* URIs fail to resolve to a loadable model.
*
* @param uris The URI identifiers of the registries.
* @return The array of <code>Registry</code> models,
* never null, but possibly empty.
* @throws CoreException If the operation fails for any reason,
* including but not limited to malformed location URIs in the
* index or general input/output error conditions.
* @see Registry
*/
public Registry[] loadRegistries ( String[] uris ) throws CoreException;
/**
* Returns an array of URI identifiers to <code>Registry</code>
* models in the index managed by this <code>IRegistryManager</code>.
*
* @return An array of URI identifiers, possibly empty but never null,
* to registered <code>Registry</code> models.
* @throws CoreException If the operation fails for any reason,
* including but not limited to malformed location URIs in the
* index or general input/output error conditions.
* @see Registry
*/
public String[] getRegistryURIs () throws CoreException;
/**
* Removes the <code>Registry</code> model identified by the
* given <code>uri</code> from the index and either keeps or
* deletes the corresponding <code>Registry</code> document
* based on the value given for <code>deleteDocument</code>.
*
* @param uri The URI identifier of the model to delete.
* @param deleteDocument Either <code>KEEP_DOCUMENT</code>
* or <code>DELETE_DOCUMENT</code> depending on whether the
* model document should be kept or deleted.
* @throws CoreException If the operation fails for any reason,
* including but not limited to malformed location URIs in the
* index or general input/output error conditions.
* @see Registry
* @see #KEEP_DOCUMENT
* @see #DELETE_DOCUMENT
*/
public void removeRegistry ( String uri, boolean deleteDocument ) throws CoreException;
/**
* Saves a <code>Taxonomy</code> model to an XML document
* located relative to the index XML document as identified by
* <code>getURL()</code>, and updates the index XML document
* with references to the saved taxonomy document.
* The relative pathname to the taxonomy XML document is
* computed by the <code>IRegistryManager</code> and cannot
* be influenced by the caller.
*
* @param taxonomy The <code>Taxonomy</code> model to save.
* @return A <code>Taxonomy</code> reference.
* @throws CoreException If the operation fails for any reason,
* including but not limited to malformed location URIs in the
* index or general input/output error conditions.
* @see Taxonomy
*/
public Taxonomy saveTaxonomy ( Taxonomy taxonomy ) throws CoreException;
/**
* Loads as necessary and returns a full <code>Taxonomy</code>
* model as identified by the given URI and referenced from
* the index XML document located at <code>getURL()</code>.
*
* @param uri The URI identifier of the taxonomy.
* @return The <code>Taxonomy</code> model
* or null if no such model can be found.
* @throws CoreException If the operation fails for any reason,
* including but not limited to malformed location URIs in the
* index or general input/output error conditions.
* @see Taxonomy
*/
public Taxonomy loadTaxonomy ( String uri ) throws CoreException;
/**
* Loads as necessary and returns an array of full <code>Taxonomy</code>
* models as identified by the given array of URIs and referenced from
* the index XML document located at <code>getURL()</code>.
* Useful in conjunction with <code>getTaxonomyURIs()</code>.
* Note that the length of the returned array may be less than
* the length of the array of URIs in cases where one or more
* URIs fail to resolve to a loadable model.
*
* @param uris The URI identifiers of the taxonomies.
* @return The array of <code>Taxonomy</code> models,
* never null, but possibly empty.
* @throws CoreException If the operation fails for any reason,
* including but not limited to malformed location URIs in the
* index or general input/output error conditions.
* @see Registry
*/
public Taxonomy[] loadTaxonomies ( String[] uris ) throws CoreException;
/**
* Returns an array of URI identifiers to <code>Taxonomy</code>
* models in the index managed by this <code>IRegistryManager</code>.
*
* @return An array of URI identifiers, possibly empty but never null,
* to registered <code>Taxonomy</code> models.
* @throws CoreException If the operation fails for any reason,
* including but not limited to malformed location URIs in the
* index or general input/output error conditions.
* @see Taxonomy
*/
public String[] getTaxonomyURIs () throws CoreException;
/**
* Removes the <code>Taxonomy</code> model identified by the
* given <code>uri</code> from the index and either keeps or
* deletes the corresponding <code>Taxonomy</code> document
* based on the value given for <code>deleteDocument</code>.
*
* @param uri The URI identifier of the model to delete.
* @param deleteDocument Either <code>KEEP_DOCUMENT</code>
* or <code>DELETE_DOCUMENT</code> depending on whether the
* model document should be kept or deleted.
* @throws CoreException If the operation fails for any reason,
* including but not limited to malformed location URIs in the
* index or general input/output error conditions.
* @see Taxonomy
* @see #KEEP_DOCUMENT
* @see #DELETE_DOCUMENT
*/
public void removeTaxonomy ( String uri, boolean deleteDocument ) throws CoreException;
}
|
