KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > ibm > webdav > Collection


1 package com.ibm.webdav;
2
3 /*
4  * (C) Copyright IBM Corp. 2000 All rights reserved.
5  *
6  * The program is provided "AS IS" without any warranty express or
7  * implied, including the warranty of non-infringement and the implied
8  * warranties of merchantibility and fitness for a particular purpose.
9  * IBM will not be liable for any damages suffered by you as a result
10  * of using the Program. In no event will IBM be liable for any
11  * special, indirect or consequential damages or lost profits even if
12  * IBM has been advised of the possibility of their occurrence. IBM
13  * will not be liable for any third party claims against you.
14  */

15 import java.net.*;
16 import java.util.*;
17
18 import org.w3c.dom.*;
19
20 import com.ibm.webdav.impl.*;
21
22
23 /** A Collection is a Resource that contains other
24  * resources including other Collections. It provides a
25  * concrete, client side implementation of Collection.
26  * @author Jim Amsden <jamsden@us.ibm.com>
27  */

28 public class Collection extends Resource {
29     
30    /** shallow means copy just this resource. */
31     public static final String JavaDoc shallow = "0";
32     /** deep means copy this resource and recursively all its members. */
33     public static final String JavaDoc deep = "infinity";
34
35
36     /** thisResource means get properties on this resource only. */
37     public static final String JavaDoc thisResource = "0";
38     /** immediateMembers means get properties on this resource and its
39     immediate members. */

40     public static final String JavaDoc immediateMembers = "1";
41     /** allMembers means get properties on this resource and recursively
42     all its members. */

43     public static final String JavaDoc allMembers = "infinity";
44
45    private Vector members = null; // lazy retrieve the members of the collection for the server
46

47 public Collection() {
48     super();
49 }
50 /** Construct a Collection with the given URL. This is the constructor most clients
51 * will use to construct and access collections using WebDAV. The collection having
52 * the url may not exist as this constructor does not access the resource from
53 * the server. Use exists() or attmept to get the members of the collection to
54 * see if it exists. Other constructors are provided using parameters for the
55 * various parts of the URL. See java.net.URLConnection.
56 *
57 * @param url the URL of the resource.
58 * @exception com.ibm.webdav.WebDAVException
59 */

60 public Collection(String JavaDoc url) throws WebDAVException {
61    try {
62       initialize(new URL(url), null);
63    } catch (java.io.IOException JavaDoc exc) {
64       throw new WebDAVException(WebDAVStatus.SC_BAD_REQUEST, "Bad URL");
65    }
66 }
67 /** Construct a Collection with the given URL. The resource having
68  * the url may not exist as this constructor does not access the resource from
69  * the server. Use exists() or attmept to get the contents of the resource to
70  * see if it exists. Other constructors are provided using parameters for the
71  * various parts of the URL. See java.net.URLConnection for details. A ResourceFactory
72  * may also be used to construct instances of a Resource.
73  *
74  * @param url the URL of the resource.
75  * @param targetSelector the revision target selector for this Collection
76  * @exception com.ibm.webdav.WebDAVException
77  * @see URLConnection
78  * @see com.ibm.webdav.ResourceFactory
79  */

80 public Collection(String JavaDoc url, TargetSelector targetSelector) throws WebDAVException {
81    try {
82       initialize(new URL(url), targetSelector);
83    } catch (java.io.IOException JavaDoc exc) {
84       throw new WebDAVException(WebDAVStatus.SC_BAD_REQUEST, "Bad URL");
85    }
86 }
87 /** Create a Collection from the given URL components.
88  * @param protocol the protocol to use, http:, rmi:, or iiop:
89  * @param host the name or IP addres of the server host. Using the client host name,
90  * or 'localhost' without a port uses local access with no RPC or server required.
91  * @param port the TCP port to use. HTTP uses 80 by default.
92  * @param file the resource URL relative to the server including any query string, etc.
93  * @exception com.ibm.webdav.WebDAVException
94  * @see URLConnection
95  * @see com.ibm.webdav.ResourceFactory
96  */

97 public Collection(String JavaDoc protocol, String JavaDoc host, int port, String JavaDoc file) throws WebDAVException {
98    try {
99       initialize(new URL(protocol, host, port, file), null);
100    } catch (java.io.IOException JavaDoc exc) {
101       throw new WebDAVException(WebDAVStatus.SC_BAD_REQUEST, "Bad URL");
102    }
103 }
104 /** Create a Collection from the given URL components. This constructor uses the default
105  * HTTP port.
106  * @param protocol the protocol to use, http:, rmi:, or iiop:
107  * @param host the name or IP addres of the server host. Using the client host name,
108  * or 'localhost' without a port uses local access with no RPC or server required.
109  * @param file the resource URL relative to the server including any query string, etc.
110  * @exception com.ibm.WebDAVException
111  * @see URLConnection
112  * @see com.ibm.webdav.ResourceFactory
113  */

114 public Collection(String JavaDoc protocol, String JavaDoc host, String JavaDoc file) throws WebDAVException {
115    try {
116       initialize(new URL(protocol, host, file), null);
117    } catch (java.io.IOException JavaDoc exc) {
118       throw new WebDAVException(WebDAVStatus.SC_BAD_REQUEST, "Bad URL");
119    }
120 }
121 /** Construct a Collection with the given URL. The resource having
122  * the url may not exist as this constructor does not access the resource from
123  * the server. Use exists() or attmept to get the contents of the resource to
124  * see if it exists. Other constructors are provided using parameters for the
125  * various parts of the URL. See java.net.URLConnection for details. A ResourceFactory
126  * may also be used to construct instances of a Resource.
127  *
128  * @param url the URL of the resource.
129  * @exception com.ibm.webdav.WebDAVException
130  * @see URLConnection
131  * @see com.ibm.webdav.ResourceFactory
132  */

133 public Collection(URL url) throws WebDAVException {
134    try {
135       initialize(url, null);
136    } catch (java.io.IOException JavaDoc exc) {
137       throw new WebDAVException(WebDAVStatus.SC_BAD_REQUEST, "Bad URL");
138    }
139 }
140 /** Construct a Collection with the given URL. The resource having
141  * the url may not exist as this constructor does not access the resource from
142  * the server. Use exists() or attmept to get the contents of the resource to
143  * see if it exists. Other constructors are provided using parameters for the
144  * various parts of the URL. See java.net.URLConnection for details. A ResourceFactory
145  * may also be used to construct instances of a Resource.
146  *
147  * @param url the URL of the resource.
148  * @param targetSelector the revision target selector for this Collection
149  * @exception com.ibm.webdav.WebDAVException
150  * @see URLConnection
151  * @see com.ibm.webdav.ResourceFactory
152  */

153 public Collection(URL url, TargetSelector targetSelector) throws WebDAVException {
154    try {
155       initialize(url, targetSelector);
156    } catch (java.io.IOException JavaDoc exc) {
157       throw new WebDAVException(WebDAVStatus.SC_BAD_REQUEST, "Bad URL");
158    }
159 }
160 /** Construct a Collection with the given URL specification in the given context.
161  * The resource having
162  * the url may not exist as this constructor does not access the resource from
163  * the server. Use exists() or attmept to get the contents of the resource to
164  * see if it exists. Other constructors are provided using parameters for the
165  * various parts of the URL. See java.net.URLConnection for details. A ResourceFactory
166  * may also be used to construct instances of a Collection.
167  *
168  * @param context a URL giving the context in which the spec is evaluated
169  * @param spec a URL whose missing parts are provided by the context
170  * @exception com.ibm.webdav.Exception
171  * @see URLConnection
172  * @see com.ibm.webdav.ResourceFactory
173  */

174 public Collection(URL context, String JavaDoc spec) throws WebDAVException {
175    try {
176       initialize(new URL(context, spec), null);
177    } catch (java.io.IOException JavaDoc exc) {
178       throw new WebDAVException(WebDAVStatus.SC_BAD_REQUEST, "Bad URL");
179    }
180 }
181 /**
182  * Put this collection under baseline control.
183  */

184 public void baseline() throws WebDAVException {
185 }
186 /** Deep copy this resource to the destination URL overwriting any existing contents.
187 * All live properties must remain live at the destination server.
188 * Partial results are possible, check the returned status for details.
189 *
190 * @param destinationURL the destination
191 *
192 * @return the status of the copy operation for each resource copied
193 * @exception com.ibm.webdav.WebDAVException
194 */

195 public MultiStatus copy(String JavaDoc destinationURL) throws WebDAVException {
196     return copy(destinationURL, true, null, Collection.deep);
197 }
198 /** Deep copy this resource to the destination URL.
199 * Partial results are possible, check the returned status for details.
200 *
201 * @param destinationURL the destination
202 * @param overwrite true implies overwrite the destination if it exists
203 * @param propertiesToCopy a collection of properties that must be copied or
204 * the method will fail. propertiesToCopy may have one of the following values:
205 * <ul>
206 * <li>null - ignore properties that cannot be copied</li>
207 * <li>empty collection - all properties must be copied or the method will fail</li>
208 * <li>a collection of URIs - a list of the properties that must be copied
209 * or the method will fail</li>
210 * </ul>
211 *
212 * @return the status of the copy operation for each resource copied
213 * @exception com.ibm.webdav.WebDAVException
214 */

215 public MultiStatus copy(String JavaDoc destinationURL, boolean overwrite, Vector propertiesToCopy) throws WebDAVException {
216     return copy(destinationURL, overwrite, propertiesToCopy, Collection.deep);
217 }
218 /** Copy this resource to the destination URL.
219 * Partial results are possible, check the returned status for details.
220 *
221 * @param destinationURL the destination
222 * @param overwrite true implies overrite the destination if it exists
223 * @param propertiesToCopy a collection of properties that must be copied or
224 * the method will fail. propertiesToCopy may have one of the following values:
225 * <ul>
226 * <li>null - ignore properties that cannot be copied</li>
227 * <li>empty collection - all properties must be copied or the method will fail</li>
228 * <li>a collection of URIs - a list of the properties that must be copied
229 * or the method will fail</li>
230 * @param depth an indicator for immediate members or recursively all children.
231 * </ul>
232 * <ul>
233 * <li>shallow: copy only this resource</li>
234 * <li>deep: copy this resource and recursively all of its children</li>
235 * </ul>
236 *
237 * @return the status of the copy operation for each resource copied
238 * @exception com.ibm.webdav.WebDAVException
239 */

240 public MultiStatus copy(String JavaDoc destinationURL, boolean overwrite, Vector propertiesToCopy, String JavaDoc depth) throws WebDAVException {
241     flushCaches();
242     return ((IRCollection)impl).copy(context, destinationURL, overwrite, propertiesToCopy, depth);
243 }
244 /** Actually create the collection in the repository. The resource indicated
245 * by the URL must not already exist. All ancestors of this URL must already
246 * exist.
247 * @exception com.ibm.webdav.WebDAVException
248 */

249 public void createCollection() throws WebDAVException {
250     createCollection((Document) null);
251 }
252 /** Actually create the collection in the repository. The resource indicated
253 * by the URL must not already exist. All ancestors of this URL must already
254 * exist.
255 *
256 * @param contents an XML Document describing the members of this collection, bodies
257 * of members, and properties on the collections or members. Not completely defined in
258 * version 10 of the WebDAV specification
259 *
260 * @return Multistatus describing the result
261 * of the operation
262 * @exception com.ibm.webdav.WebDAVException
263 */

264 public MultiStatus createCollection(Document contents) throws WebDAVException {
265     MultiStatus result = null;
266     result = ((IRCollection)impl).createCollection(context, contents);
267     return result;
268 }
269 /** Create a sub-collection of this collection. The resource indicated
270 * by the URL must not already exist. All ancestors of this URL must already
271 * exist.
272 * @param collectionName the name of the collection to create relative to the
273 * URL of this resource.
274 * @return the newly created Collection
275 * @exception com.ibm.webdav.WebDAVException
276 */

277 public Collection createSubCollection(String JavaDoc collectionName) throws WebDAVException {
278     Collection subCollection = null;
279     try {
280         subCollection = new Collection(getURL().toString() + collectionName);
281     } catch (WebDAVException exc) {
282         throw exc;
283     }
284     subCollection.getRequestContext().precondition(getRequestContext().precondition());
285     subCollection.getRequestContext().authorization(getRequestContext().authorization());
286     subCollection.createCollection();
287     return subCollection;
288 }
289 /** Flush any caches so that subsequent methods obtain fresh data from the server. Currently,
290 * only the contents of the resource and members of a resource collection are cached.
291 * @exception com.ibm.webdav.WebDAVException
292 */

293 public void flushCaches() throws WebDAVException {
294     super.flushCaches();
295     members = null;
296 }
297 /** Get the members of this Collection.
298 *
299 * @return a Vector of CollectionMembers
300 * @exception com.ibm.webdav.WebDAVException
301 */

302 public Vector getMembers() throws WebDAVException {
303     if (members == null) {
304         members = new Vector();
305         MultiStatus multiStatus = getProperties(Collection.immediateMembers);
306         URL thisURLu = getURL();
307         String JavaDoc thisURL = thisURLu.toString();
308
309         // each response contains a reference to an element in the collection
310
Enumeration responses = multiStatus.getResponses();
311         while (responses.hasMoreElements()) {
312             PropertyResponse response = ((Response)responses.nextElement()).toPropertyResponse();
313             String JavaDoc memberName = response.getResource();
314             URL uu = null;
315             try {
316                 uu = new URL( thisURLu, memberName );
317             } catch (java.net.MalformedURLException JavaDoc exc) {
318                 throw new WebDAVException(WebDAVStatus.SC_BAD_REQUEST, "Malformed URL");
319             }
320             memberName = uu.toString();
321             // don't put myself in my own collection
322
if (!memberName.equals(thisURL)) {
323                 Resource resource = null;
324                 // resource might contain a URI rather than a URL, but
325
// the Resource*P constructors need a full URL, so
326
// we construct one here.
327
try {
328                     URL urll = new URL(getURL(), response.getResource());
329                     if (response.isOnACollection()) {
330                         resource = new Collection(urll);
331                     } else {
332                         resource = new Resource(urll);
333                     }
334                 } catch (Exception JavaDoc exc) {
335                     throw new WebDAVException(WebDAVStatus.SC_BAD_REQUEST, "Malformed URL");
336                 }
337                 MultiStatus childProperties = new MultiStatus();
338                 childProperties.addResponse(response);
339                 CollectionMember member = new CollectionMember(this, resource, childProperties);
340                 members.addElement(member);
341             }
342         }
343     }
344     return members;
345 }
346 /** Get the named properties for this resource and (potentially) its children.
347 *
348 * @param names an arrary of property names to retrieve.
349 * @param depth an indicator for immediate members or recursively all children.
350 * <ul>
351 * <li>immediateMembers: propeprties of this resource and its immediate children</li>
352 * <li>allMembers: properties of this resource and recursively all its children</li>
353 * </ul>
354 *
355 * @return a MultiStatus of PropertyResponses
356 * @exception com.ibm.webdav.WebDAVException
357 */

358 public MultiStatus getProperties(PropertyName names[], String JavaDoc depth) throws WebDAVException {
359     return ((IRCollection)impl).getProperties(context, names, depth);
360 }
361 /** Get all the properties for this resource and (potentially) its children.
362 *
363 * @param depth an indicator for immediate members or recursively all children.
364 * <ul>
365 * <li>thisResource: propeprties of this resource</li>
366 * <li>immediateMembers: propeprties of this resource and its immediate children</li>
367 * <li>allMembers: properties of this resource and recursively all its children</li>
368 * </ul>
369 *
370 * @return a MultiStatus of PropertyResponses
371 * @exception com.ibm.webdav.WebDAVException
372 */

373 public MultiStatus getProperties(String JavaDoc depth) throws WebDAVException {
374     return ((IRCollection)impl).getProperties(context, depth);
375 }
376 /** Get the named property for this resource and (potentially) its children.
377 *
378 * @param name the name of the property to retrieve.
379 * @param depth an indicator for immediate members or recursively all children.
380 * <ul>
381 * <li>immediateMembers: propeprties of this resource and its immediate children</li>
382 * <li>allMembers: properties of this resource and recursively all its children</li>
383 * </ul>
384 *
385 * @return a MultiStatus of PropertyResponses
386 * @exception com.ibm.webdav.WebDAVException
387 */

388 public MultiStatus getProperty(PropertyName name, String JavaDoc depth) throws WebDAVException {
389     PropertyName[] names = new PropertyName[1];
390     names[0] = name;
391     return getProperties(names, depth);
392 }
393 /** Get the names of all properties for this resource and (potentially) its children.
394 *
395 * @param depth an indicator for immediate members or recursively all children.
396 * <ul>
397 * <li>thisResource: propeprties of this resource</li>
398 * <li>immediateMembers: propeprties of this resource and its immediate children</li>
399 * <li>allMembers: properties of this resource and recursively all its children</li>
400 * </ul>
401 *
402 * @return a MultiStatus of PropertyResponses
403 * (PropertyValue.value is always null, PropertyValue.status contains the status)
404 * @exception com.ibm.webdav.WebDAVException
405 */

406 public MultiStatus getPropertyNames(String JavaDoc depth) throws WebDAVException {
407     return ((IRCollection)impl).getPropertyNames(context, depth);
408 }
409 /** Initialize this collection instance. Make sure the URL ends in a '/'.
410 */

411 protected void initialize(URL url, TargetSelector targetSelector) throws WebDAVException {
412     String JavaDoc file = url.getFile();
413     if (!file.endsWith("/")) {
414         file = file + "/";
415     }
416     try {
417         this.url = new URL(url, file);
418         impl = ResourceFactory.createCollection(url, targetSelector);
419     } catch (Exception JavaDoc exc) {
420         throw new WebDAVException(WebDAVStatus.SC_BAD_REQUEST, "Malformed URL");
421     }
422 }
423 /** Lock this resource collection and recursively all its members based
424 * on the given parameters. This allows control of the lock scope
425 *(exclusive or shared) the lock type (write), owner information, etc.
426 *
427 * @param scope the scope of the lock, exclusive or shared
428 * @param type the type of the lock, currently only write
429 * @param timeout the number of seconds before the lock times out or
430 * 0 for infinite timeout.
431 * @param owner an XML element containing useful information that can be
432 * used to identify the owner of the lock. An href to a home page, an
433 * email address, phone number, etc. Can be null if no owner information
434 * is provided.
435 *
436 * @return a MultiStatus containing a lockdiscovery property indicating
437 * the results of the lock operation.
438 * @exception com.ibm.webdav.WebDAVException
439 */

440 public MultiStatus lock(String JavaDoc scope, String JavaDoc type, int timeout, Element owner) throws WebDAVException {
441     return lock(scope, type, timeout, owner, Collection.deep);
442 }
443 /** Lock this resource based on the given parameters. This allows control of
444 * the lock scope (exclusive or shared) the lock type (write), owner information, etc.
445 *
446 * @param scope the scope of the lock, exclusive or shared
447 * @param type the type of the lock, currently only write
448 * @param timeout the number of seconds before the lock times out or
449 * 0 for infinite timeout.
450 * @param owner an XML element containing useful information that can be
451 * used to identify the owner of the lock. An href to a home page, an
452 * email address, phone number, etc. Can be null if no owner information
453 * is provided.
454 * @param depth
455 * <ul>
456 * <li>shallow lock only this resource</li>
457 * <li>deep lock this resource and all its children</li>
458 * </ul>
459 *
460 * @return a MultiStatus containing a lockdiscovery property indicating
461 * the results of the lock operation.
462 * @exception com.ibm.webdav.WebDAVException
463 */

464 public MultiStatus lock(String JavaDoc scope, String JavaDoc type, int timeout, Element owner, String JavaDoc depth) throws WebDAVException {
465     return ((IRCollection) impl).lock(context, scope, type, timeout, owner, depth);
466 }
467 }
468
Popular Tags