IRResource


1   package com.ibm.webdav.impl;
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   * Portions Copyright (C) Simulacra Media Ltd, 2004.
16   */
17  import java.io.*;
18  import java.util.*;
19  
20  import org.w3c.dom.*;
21  
22  import com.ibm.webdav.*;
23  
24  
25  /** A Resource represents any network data object or service that can be
26   * identified by a URL. Resources may be available in multiple 
27   * representations (e.g., multiple languages, data formats, size, resolutions)
28   * or vary in other ways.
29   * <p>
30   * Resources may have arbitrary properties consisting of name/value pairs that
31   * define additional meta-data about the resource. A resource may be locked
32   * in order to serialize updates by multiple users in a distributed environment.
33   * Resources may be copied and moved in the network, and may be deleted when 
34   * no longer needed.</p>
35   * <p>
36   * Resources may be logically grouped into collections for content management.
37   * A resource collection may have properties of its own, and can be moved and
38   * copied just like any other resource.</p>
39   * <p>
40   * The Resource methods correspond to the capabilities defined 
41   * by the WebDAV extensions to HTTP. These methods allow clients to perform
42   * remote web content authoring operations.</p>
43   * <p>
44   * Note: all methods that may modify a locked resource (either this resource or one
45   * of its collaborators) must include the lock token of the effected resources
46   * as a Precondition in the resource request context before the method is called. See
47   * Precondition.addStateTokenCondition() for a method that provides a convenient
48   * way to set these preconditions.</p>
49   * @see com.ibm.webdav.Collection
50   * @see com.ibm.webdav.ResourceP
51   * @see com.ibm.webdav.Precondition#addStateTokenCondition
52   * @author Jim Amsden &lt;jamsden@us.ibm.com&gt;
53   *
54   */
55  public interface IRResource extends java.rmi.Remote  
56  {
57  /** This method must be called after the client has completed writing to the contents
58   * output stream that was obtained from <code>getContentsOutputStream()</code>.
59   * @exception com.ibm.webdav.WebDAVException
60   */
61  public void closeContentsOutputStream(ResourceContext context) throws WebDAVException;
62  /** Copy this resource to the destination URL.
63   * Partial results are possible, check the returned status for details.
64   *
65   * @param destinationURL the destination
66   * @param overwrite true implies overwrite the destination if it exists
67   * @param propertiesToCopy a collection of properties that must be copied or
68   * the method will fail. propertiesToCopy may have one of the following values:
69   * <ul>
70   *    <li>null - ignore properties that cannot be copied</li>
71   *    <li>empty collection - all properties must be copied or the method will fail</li>
72   *    <li>a collection of URIs - a list of the properties that must be copied 
73   *        or the method will fail</li>
74   * </ul>
75   *
76   * @return the status of the copy operation for each resource copied
77   * @exception com.ibm.webdav.WebDAVException
78   */
79  public MultiStatus copy(ResourceContext context, String   destinationURL, boolean overwrite, Vector propertiesToCopy) throws WebDAVException;
80  /** Delete this resouce from the server. The actual effect of the delete operation is
81   * determined by the underlying repository manager. The visible effect to WebDAV
82   * is that the resource is no longer available.
83   *
84   * @return a MultiStatus containing the status of the delete method on each
85   *         effected resource.
86   * @exception com.ibm.webdav.WebDAVException
87   */
88  public MultiStatus delete(ResourceContext context) throws WebDAVException;
89  /** Get an InputStream for accessing the contents of this resource. This method may provide
90   * more efficient access for resources that have large contents. Clients may want to create
91   * a Reader to perform appropriate character conversions on this stream.
92   *
93   * @return an InputStream on the contents
94   * @exception com.ibm.webdav.WebDAVException
95   */
96  public InputStream getContentsInputStream(ResourceContext context) throws WebDAVException;
97  /** Get an OutputStream for setting the contents of this resource. This method may provide
98   * more efficient access for resources that have large contents. Remember to call
99   * closeContentsOutputStream() when all the data has been written.
100  *
101  * @return an OutputStream to set the contents
102  * @exception com.ibm.webdav.WebDAVException
103  */
104 public OutputStream getContentsOutputStream(ResourceContext context) throws WebDAVException;
105 /** This method can be used for obtaining meta-information about this resource without
106  * actually reading the resource contents. This meta-information is maintained by the server
107  * in addition to the resource properties.</p>
108  * <p>
109  * After this call, the resource context has been updated and 
110  * <code>getStatusCode()</code>, <code>getStatusMessage()</code>, and <code>getResponseContext()</code>
111  * as well as all the ResourceContext methods return updated values based on the current
112  * state of the resource.</p>
113  * <p>This methods corresponds to the HTTP HEAD method.</p>
114  *
115  * @exception com.ibm.webdav.WebDAVException
116  */
117 public void getMetaInformation(ResourceContext context) throws WebDAVException;
118 /** Get all the properties of this resource.
119  *
120  * @return a MultiStatus of PropertyResponses. It should contain only one
121  * response element.
122  * @see com.ibm.webdav.MultiStatus
123  * @see com.ibm.webdav.PropertyResponse
124  * @exception com.ibm.webdav.WebDAVException
125  */
126 public MultiStatus getProperties(ResourceContext context) throws WebDAVException;
127 /** Get the named properties of this resource. 
128  * 
129  * @param names an array of property names to retrieve
130  *
131  * @return a MultiStatus of PropertyResponses
132  * @exception com.ibm.webdav.WebDAVException
133  * @see com.ibm.webdav.PropertyResponse
134  */
135 public MultiStatus getProperties(ResourceContext context, PropertyName names[]) throws WebDAVException;
136 /** Get the names of all properties for this resource. The result is similar to
137  * getProperties(), but the properties have no values.
138  *
139  * @return a MultiStatus of PropertyResponses
140  * (PropertyValue.value is always null, PropertyValue.status contains the status)
141  * @exception com.ibm.webdav.WebDAVException
142  * @see com.ibm.webdav.PropertyResponse
143  */
144 public MultiStatus getPropertyNames(ResourceContext context) throws WebDAVException;
145 /** Lock this resource based on the given parameters. This allows control of
146  * the lock scope (exclusive or shared) the lock type (write), owner information, etc.
147  *
148  * @param scope the scope of the lock, exclusive or shared
149  * @param type the type of the lock, currently only write
150  * @param timeout the number of seconds before the lock times out or
151  *     -1 for infinite timeout.
152  * @param owner an XML element containing useful information that can be
153  *     used to identify the owner of the lock. An href to a home page, an
154  *     email address, phone number, etc. Can be null if no owner information
155  *     is provided.
156  *
157  * @return a MultiStatus containing a lockdiscovery property indicating
158  * the results of the lock operation.
159  * @exception com.ibm.webdav.WebDAVException
160 */
161 public MultiStatus lock(ResourceContext context, String   scope, String   type, int timeout, Element owner) throws WebDAVException;
162 /** Move this resource to the destination URL.
163  * Partial results are possible, check the returned status for details
164  *
165  * @param destinationURL the destination
166  * @param overwrite true implies overrite the destination if it exists
167  * @param propertiesToMove a collection of properties that must be moved or
168  * the method will fail. propertiesToMove may have one of the following values:
169  * <ul>
170  *    <li>null - ignore properties that cannot be moved</li>
171  *    <li>empty collection - all properties must be moved or the method will fail</li>
172  *    <li>a collection of URIs - a list of the properties that must be moved 
173  *        or the method will fail</li>
174  * </ul>
175  *
176  * @return the status of the move operation for each resource moved
177  * @exception com.ibm.webdav.WebDAVException
178  */
179 public MultiStatus move(ResourceContext context, String   destinationURL, boolean overwrite, Vector propertiesToMove) throws WebDAVException;
180 /** This method treats this resource as a method or service, and sends its parameter to
181  * this resource where it is handled in a resource-specific way. For example,
182  * sending data from an HTML form to a URL representing a Servlet or CGI script that processes
183  * the form data to produce some result.
184  *
185  * @param args a string representing the arguments to the method represented by this URL. The
186  * arguments are in the form ?parameterName1=value1&amp;parameterName2=value2... as specified
187  * for URL queries.
188  *
189  * @return the results of sending the arguments to the URL
190  * @exception com.ibm.webdav.WebDAVException
191  */
192 public byte[] performWith(ResourceContext context, String   args) throws WebDAVException;
193 /** Refresh the lock on this resource by resetting the lock timeout.
194  * The context must contain the proper authorization for the requesting
195  * principal.
196  *
197  * @param lockToken the lock token identifying the lock.
198  * @param timeout the new timeout in seconds. -1 means infinite timeout.
199  *
200  * @return updated information about the lock status of this resource
201  * @exception com.ibm.webdav.WebDAVException
202  */
203 public MultiStatus refreshLock(ResourceContext context, String   lockToken, int timeout) throws WebDAVException;
204 /** Edit the properties of a resource. The updates must refer to a Document containing a WebDAV
205  * DAV:propertyupdates element as the document root.
206  *
207  * @param updates an XML Document containing DAV:propertyupdate elements 
208  * describing the edits to be made
209  * @return a MultiStatus indicating the status of the updates
210  * @exception com.ibm.webdav.WebDAVException
211  */
212 public MultiStatus setProperties(ResourceContext context, Document updates) throws WebDAVException;
213 /** Unlock the lock identified by the lockToken on this resource. The request context
214  * must contain the proper authorization.
215  *
216  * @param lockToken the lock token obtained from the ActiveLock of a previous <code>lock() </code>
217  * or <code>getLocks()</code>.
218  *
219  * @return a MultiStatus containing any responses on resources that could not
220  *     be unlocked.
221  * @exception com.ibm.webdav.WebDAVException
222  */
223 public MultiStatus unlock(ResourceContext context, String   lockToken) throws WebDAVException;
224 /**
225  * @param context
226  * @param sContentType
227  */
228 public void closeContentsOutputStream(ResourceContext context, String   sContentType) throws WebDAVException;
229 }
230
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags