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 &lt;jamsden@us.ibm.com&gt;
27   */
28  public class Collection extends Resource  {
29      
30     /** shallow means copy just this resource. */
31      public static final String   shallow = "0";
32      /** deep means copy this resource and recursively all its members. */
33      public static final String   deep = "infinity";
34  
35  
36      /** thisResource means get properties on this resource only. */
37      public static final String   thisResource = "0";
38      /** immediateMembers means get properties on this resource and its
39      immediate members. */
40      public static final String   immediateMembers = "1";
41      /** allMembers means get properties on this resource and recursively
42      all its members. */
43      public static final String   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   url) throws WebDAVException {
61     try {
62        initialize(new URL(url), null);
63     } catch (java.io.IOException   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   url, TargetSelector targetSelector) throws WebDAVException {
81     try {
82        initialize(new URL(url), targetSelector);
83     } catch (java.io.IOException   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   protocol, String   host, int port, String   file) throws WebDAVException {
98     try {
99        initialize(new URL(protocol, host, port, file), null);
100    } catch (java.io.IOException   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   protocol, String   host, String   file) throws WebDAVException {
115    try {
116       initialize(new URL(protocol, host, file), null);
117    } catch (java.io.IOException   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   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   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   spec) throws WebDAVException {
175    try {
176       initialize(new URL(context, spec), null);
177    } catch (java.io.IOException   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   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   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   destinationURL, boolean overwrite, Vector propertiesToCopy, String   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   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   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   memberName = response.getResource();
314             URL uu = null;
315             try {
316                 uu = new URL( thisURLu, memberName );
317             } catch (java.net.MalformedURLException   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   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   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   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   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   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   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   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   scope, String   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   scope, String   type, int timeout, Element owner, String   depth) throws WebDAVException {
465     return ((IRCollection) impl).lock(context, scope, type, timeout, owner, depth);
466 }
467 }
468
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags