001: package com.ibm.webdav.impl;
002:
003: /*
004: * (C) Copyright IBM Corp. 2000 All rights reserved.
005: *
006: * The program is provided "AS IS" without any warranty express or
007: * implied, including the warranty of non-infringement and the implied
008: * warranties of merchantibility and fitness for a particular purpose.
009: * IBM will not be liable for any damages suffered by you as a result
010: * of using the Program. In no event will IBM be liable for any
011: * special, indirect or consequential damages or lost profits even if
012: * IBM has been advised of the possibility of their occurrence. IBM
013: * will not be liable for any third party claims against you.
014: *
015: * Portions Copyright (C) Simulacra Media Ltd, 2004.
016: */
017: import java.io.*;
018: import java.util.*;
019:
020: import org.w3c.dom.*;
021:
022: import com.ibm.webdav.*;
023:
024: /** A Resource represents any network data object or service that can be
025: * identified by a URL. Resources may be available in multiple
026: * representations (e.g., multiple languages, data formats, size, resolutions)
027: * or vary in other ways.
028: * <p>
029: * Resources may have arbitrary properties consisting of name/value pairs that
030: * define additional meta-data about the resource. A resource may be locked
031: * in order to serialize updates by multiple users in a distributed environment.
032: * Resources may be copied and moved in the network, and may be deleted when
033: * no longer needed.</p>
034: * <p>
035: * Resources may be logically grouped into collections for content management.
036: * A resource collection may have properties of its own, and can be moved and
037: * copied just like any other resource.</p>
038: * <p>
039: * The Resource methods correspond to the capabilities defined
040: * by the WebDAV extensions to HTTP. These methods allow clients to perform
041: * remote web content authoring operations.</p>
042: * <p>
043: * Note: all methods that may modify a locked resource (either this resource or one
044: * of its collaborators) must include the lock token of the effected resources
045: * as a Precondition in the resource request context before the method is called. See
046: * Precondition.addStateTokenCondition() for a method that provides a convenient
047: * way to set these preconditions.</p>
048: * @see com.ibm.webdav.Collection
049: * @see com.ibm.webdav.ResourceP
050: * @see com.ibm.webdav.Precondition#addStateTokenCondition
051: * @author Jim Amsden <jamsden@us.ibm.com>
052: *
053: */
054: public interface IRResource extends java.rmi.Remote {
055: /** This method must be called after the client has completed writing to the contents
056: * output stream that was obtained from <code>getContentsOutputStream()</code>.
057: * @exception com.ibm.webdav.WebDAVException
058: */
059: public void closeContentsOutputStream(ResourceContext context)
060: throws WebDAVException;
061:
062: /** Copy this resource to the destination URL.
063: * Partial results are possible, check the returned status for details.
064: *
065: * @param destinationURL the destination
066: * @param overwrite true implies overwrite the destination if it exists
067: * @param propertiesToCopy a collection of properties that must be copied or
068: * the method will fail. propertiesToCopy may have one of the following values:
069: * <ul>
070: * <li>null - ignore properties that cannot be copied</li>
071: * <li>empty collection - all properties must be copied or the method will fail</li>
072: * <li>a collection of URIs - a list of the properties that must be copied
073: * or the method will fail</li>
074: * </ul>
075: *
076: * @return the status of the copy operation for each resource copied
077: * @exception com.ibm.webdav.WebDAVException
078: */
079: public MultiStatus copy(ResourceContext context,
080: String destinationURL, boolean overwrite,
081: Vector propertiesToCopy) throws WebDAVException;
082:
083: /** Delete this resouce from the server. The actual effect of the delete operation is
084: * determined by the underlying repository manager. The visible effect to WebDAV
085: * is that the resource is no longer available.
086: *
087: * @return a MultiStatus containing the status of the delete method on each
088: * effected resource.
089: * @exception com.ibm.webdav.WebDAVException
090: */
091: public MultiStatus delete(ResourceContext context)
092: throws WebDAVException;
093:
094: /** Get an InputStream for accessing the contents of this resource. This method may provide
095: * more efficient access for resources that have large contents. Clients may want to create
096: * a Reader to perform appropriate character conversions on this stream.
097: *
098: * @return an InputStream on the contents
099: * @exception com.ibm.webdav.WebDAVException
100: */
101: public InputStream getContentsInputStream(ResourceContext context)
102: throws WebDAVException;
103:
104: /** Get an OutputStream for setting the contents of this resource. This method may provide
105: * more efficient access for resources that have large contents. Remember to call
106: * closeContentsOutputStream() when all the data has been written.
107: *
108: * @return an OutputStream to set the contents
109: * @exception com.ibm.webdav.WebDAVException
110: */
111: public OutputStream getContentsOutputStream(ResourceContext context)
112: throws WebDAVException;
113:
114: /** This method can be used for obtaining meta-information about this resource without
115: * actually reading the resource contents. This meta-information is maintained by the server
116: * in addition to the resource properties.</p>
117: * <p>
118: * After this call, the resource context has been updated and
119: * <code>getStatusCode()</code>, <code>getStatusMessage()</code>, and <code>getResponseContext()</code>
120: * as well as all the ResourceContext methods return updated values based on the current
121: * state of the resource.</p>
122: * <p>This methods corresponds to the HTTP HEAD method.</p>
123: *
124: * @exception com.ibm.webdav.WebDAVException
125: */
126: public void getMetaInformation(ResourceContext context)
127: throws WebDAVException;
128:
129: /** Get all the properties of this resource.
130: *
131: * @return a MultiStatus of PropertyResponses. It should contain only one
132: * response element.
133: * @see com.ibm.webdav.MultiStatus
134: * @see com.ibm.webdav.PropertyResponse
135: * @exception com.ibm.webdav.WebDAVException
136: */
137: public MultiStatus getProperties(ResourceContext context)
138: throws WebDAVException;
139:
140: /** Get the named properties of this resource.
141: *
142: * @param names an array of property names to retrieve
143: *
144: * @return a MultiStatus of PropertyResponses
145: * @exception com.ibm.webdav.WebDAVException
146: * @see com.ibm.webdav.PropertyResponse
147: */
148: public MultiStatus getProperties(ResourceContext context,
149: PropertyName names[]) throws WebDAVException;
150:
151: /** Get the names of all properties for this resource. The result is similar to
152: * getProperties(), but the properties have no values.
153: *
154: * @return a MultiStatus of PropertyResponses
155: * (PropertyValue.value is always null, PropertyValue.status contains the status)
156: * @exception com.ibm.webdav.WebDAVException
157: * @see com.ibm.webdav.PropertyResponse
158: */
159: public MultiStatus getPropertyNames(ResourceContext context)
160: throws WebDAVException;
161:
162: /** Lock this resource based on the given parameters. This allows control of
163: * the lock scope (exclusive or shared) the lock type (write), owner information, etc.
164: *
165: * @param scope the scope of the lock, exclusive or shared
166: * @param type the type of the lock, currently only write
167: * @param timeout the number of seconds before the lock times out or
168: * -1 for infinite timeout.
169: * @param owner an XML element containing useful information that can be
170: * used to identify the owner of the lock. An href to a home page, an
171: * email address, phone number, etc. Can be null if no owner information
172: * is provided.
173: *
174: * @return a MultiStatus containing a lockdiscovery property indicating
175: * the results of the lock operation.
176: * @exception com.ibm.webdav.WebDAVException
177: */
178: public MultiStatus lock(ResourceContext context, String scope,
179: String type, int timeout, Element owner)
180: throws WebDAVException;
181:
182: /** Move this resource to the destination URL.
183: * Partial results are possible, check the returned status for details
184: *
185: * @param destinationURL the destination
186: * @param overwrite true implies overrite the destination if it exists
187: * @param propertiesToMove a collection of properties that must be moved or
188: * the method will fail. propertiesToMove may have one of the following values:
189: * <ul>
190: * <li>null - ignore properties that cannot be moved</li>
191: * <li>empty collection - all properties must be moved or the method will fail</li>
192: * <li>a collection of URIs - a list of the properties that must be moved
193: * or the method will fail</li>
194: * </ul>
195: *
196: * @return the status of the move operation for each resource moved
197: * @exception com.ibm.webdav.WebDAVException
198: */
199: public MultiStatus move(ResourceContext context,
200: String destinationURL, boolean overwrite,
201: Vector propertiesToMove) throws WebDAVException;
202:
203: /** This method treats this resource as a method or service, and sends its parameter to
204: * this resource where it is handled in a resource-specific way. For example,
205: * sending data from an HTML form to a URL representing a Servlet or CGI script that processes
206: * the form data to produce some result.
207: *
208: * @param args a string representing the arguments to the method represented by this URL. The
209: * arguments are in the form ?parameterName1=value1&parameterName2=value2... as specified
210: * for URL queries.
211: *
212: * @return the results of sending the arguments to the URL
213: * @exception com.ibm.webdav.WebDAVException
214: */
215: public byte[] performWith(ResourceContext context, String args)
216: throws WebDAVException;
217:
218: /** Refresh the lock on this resource by resetting the lock timeout.
219: * The context must contain the proper authorization for the requesting
220: * principal.
221: *
222: * @param lockToken the lock token identifying the lock.
223: * @param timeout the new timeout in seconds. -1 means infinite timeout.
224: *
225: * @return updated information about the lock status of this resource
226: * @exception com.ibm.webdav.WebDAVException
227: */
228: public MultiStatus refreshLock(ResourceContext context,
229: String lockToken, int timeout) throws WebDAVException;
230:
231: /** Edit the properties of a resource. The updates must refer to a Document containing a WebDAV
232: * DAV:propertyupdates element as the document root.
233: *
234: * @param updates an XML Document containing DAV:propertyupdate elements
235: * describing the edits to be made
236: * @return a MultiStatus indicating the status of the updates
237: * @exception com.ibm.webdav.WebDAVException
238: */
239: public MultiStatus setProperties(ResourceContext context,
240: Document updates) throws WebDAVException;
241:
242: /** Unlock the lock identified by the lockToken on this resource. The request context
243: * must contain the proper authorization.
244: *
245: * @param lockToken the lock token obtained from the ActiveLock of a previous <code>lock() </code>
246: * or <code>getLocks()</code>.
247: *
248: * @return a MultiStatus containing any responses on resources that could not
249: * be unlocked.
250: * @exception com.ibm.webdav.WebDAVException
251: */
252: public MultiStatus unlock(ResourceContext context, String lockToken)
253: throws WebDAVException;
254:
255: /**
256: * @param context
257: * @param sContentType
258: */
259: public void closeContentsOutputStream(ResourceContext context,
260: String sContentType) throws WebDAVException;
261: }
|