001 /*
002 * file Resource.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * (c) Copyright IBM Corporation 2004, 2008. All Rights Reserved.
008 * Note to U.S. Government Users Restricted Rights: Use, duplication or
009 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
010 */
011 package javax.wvcm;
012
013 import java.io.InputStream;
014 import java.io.OutputStream;
015 import java.util.Collection;
016 import java.util.Date;
017 import java.util.List;
018 import java.util.Locale;
019
020 import javax.wvcm.PropertyNameList.PropertyName;
021 import javax.wvcm.ResourceList.ResponseIterator;
022 import javax.wvcm.WvcmException.ReasonCode;
023
024
025 /**
026 * A proxy for a persistent resource.
027 *
028 * A proxy for a persistent resource is used to retrieve information from
029 * the resource and to perform operations on the resource.
030 * A resource has both standard properties, which are named values whose
031 * semantics are specified by the API, as well as custom properties
032 * whose names are arbitrary strings selected by the client.
033 * A custom property has a namespace which allows different clients
034 * to use simple property names without conflicting with each other.
035 * <p>
036 * A proxy for a persistent resource contains the location of
037 * that persistent resource on the server that maintains that resource.
038 * A proxy can be created as the return value of a request to the
039 * server, in which case the proxy is initialized with a set of
040 * properties reflecting the state of the persistent resource at
041 * the time of the request (the list of wanted
042 * properties is specified as an argument to the request).
043 * Alternatively, a proxy can be created locally by a client
044 * (using the Provider interface), in which case it is initialized
045 * with an empty set of properties.
046 * <p>
047 * Two proxies are equal if they are known to identify the same resource,
048 * where the identity of a proxy is determined by its {@link Resource#RESOURCE_IDENTIFIER}
049 * property if it has one loaded, and if not, by its {@link Resource#location}.
050 *
051 * @since 1.0
052 */
053 public interface Resource {
054
055 /**
056 * Get the location of this resource.<p>
057 * The format of the location string is specific to the repository that stores
058 * the persistent resource. A URL, a UNC filename, and an NFS filename
059 * are examples of possible formats for a location string.
060 *
061 * @return the location of the persistent resource for which this
062 * Resource is a proxy.
063 */
064 public Location location();
065
066 /**
067 * Modify the location of this resource.
068 * This does not affect the value of any property of this proxy.
069 */
070 public void modifyLocation(Location location);
071
072 /**
073 * Get the provider of this resource.
074 *
075 * @return the {@link Provider} for this Resource.
076 */
077 public Provider provider();
078
079 // Resource properties
080
081 /**
082 * Get the names of standard properties available on the server resource
083 * identified by this Resource.
084 *
085 * @param feedback Provides optional feedback to the caller for long-running requests.
086 * @return the list of names of standard properties available on the server
087 * resource identified by this Resource.
088 * @throws WvcmException if problems encountered communicating with server
089 */
090 public PropertyNameList doGetPropertyNameList(Feedback feedback)
091 throws WvcmException;
092
093 /**
094 * Get the names of properties in a given namespace available
095 * on the server resource identified by this Resource.
096 *
097 * @param namespace the namespace for the requested property names.
098 * @param feedback Provides optional feedback to the caller for long-running requests.
099 * @return the list of names of properties in the specified namespace
100 * available on the server resource identified by this Resource.
101 * If the namespace is null, the system property names are listed.
102 * If the namespace is not null, the user-defined properties
103 * in that namespace are listed.
104 * @throws WvcmException if problems encountered communicating with server
105 */
106 public PropertyNameList doGetPropertyNameList(String namespace, Feedback feedback)
107 throws WvcmException;
108
109 /**
110 * Get a set of properties of this Resource from the server.
111 * Like all doXyz methods, any modified properties in this Resource
112 * are first written to the resource before the properties are read
113 * from the resource. Note that this makes doReadProperties semantically
114 * identical to {@link #doWriteProperties}.
115 *
116 * @param feedback the properties to be available in the returned proxy,
117 * and any other feedback desired, such as progress indications.
118 * @return a Resource proxy for this resource containing the wanted properties.
119 * A requested property named XYZ can be retrieved from
120 * the resource with the <code>getXyz</code> method, when a
121 * <code>getXyz</code> method is defined in the interface.
122 * @throws WvcmException if problems encountered communicating with server or
123 * if modified properties cannot be written (see {@link #doWriteProperties}.
124 */
125 public Resource doReadProperties(Feedback feedback) throws WvcmException;
126
127 /**
128 * Get the names of properties available on this client proxy.
129 * A property is available if it would not throw an exception if
130 * retrieved from this proxy.
131 * One difference between this and wantedPropertyRequestList
132 * is that {@link #ALL_CUSTOM_PROPERTIES} would appear in wantedPropertyRequestList,
133 * but the actual property names would appear in propertyNameList.
134 * In addition, failing to retrieve a property would cause a property
135 * to not appear in propertyNameList,
136 * setting a property would add that property to propertyNameList,
137 * and forgetting or removing a property would remove that property
138 * from propertyNameList.
139 * @return the list of names of properties available on this client proxy.
140 */
141 public PropertyNameList propertyNameList();
142
143 /**
144 * Get a list of modified properties that have been updated in the proxy
145 * by setXyz operations, but not been successfully written to the
146 * corresponding persistent resource by a doXyz operation.
147 * @return the names of properties that have been updated in
148 * the proxy, but the updates have not yet been successfully
149 * applied to the resource.
150 */
151 public PropertyNameList updatedPropertyNameList();
152
153 /**
154 * Persists property changes to this Resource.
155 * An exception is thrown if any of properties cannot be written.
156 * If an exception is thrown, the properties that were not be written
157 * can be determined from {@link #updatedPropertyNameList}
158 * on this Resource.
159 * Note that since doWriteProperties returns a new proxy whose properties are
160 * specified in the feedback argument, doWriteProperties is semantically identical
161 * to {@link #doReadProperties}.
162 * <p>
163 * Postconditions:
164 * <li>(auto-checkout-controlled-property): If the property is controlled,
165 * and if this resource was a checked-in controlled,
166 * resource, this resource MUST have been checked out by this request.
167 *
168 * @param feedback Specifies optional feedback to the caller.
169 * @return a new proxy for this resource, whose properties are specified by feedback.
170 * @throws WvcmException ReasonCode:
171 * <li>{@link ReasonCode#PROPERTY_OVERWRITE_FORBIDDEN}:
172 * This property has been updated by another client after this proxy was created.
173 * <li>{@link ReasonCode#CANNOT_MODIFY_PROTECTED_PROPERTY}:
174 * Some properties cannot be directly updated.
175 * <li>{@link ReasonCode#CANNOT_MODIFY_VERSION}:
176 * If this proxy identifies a version, the request MUST fail
177 * unless the property is explicitly defined to be modifiable on a
178 * version.
179 * <li>Since this method may cause a checkout to be attempted on this resource,
180 * see {@link ControllableResource#doCheckin} for additional reason codes.
181 */
182 public Resource doWriteProperties(Feedback feedback) throws WvcmException;
183
184 /**
185 * Get both the content and selected properties of this resource.
186 *
187 * @param content the resource content is written to this
188 * byte stream. The stream is then closed.
189 * @param feedback Specifies optional feedback to the caller.
190 * @return a new proxy for this resource, whose properties are specified by feedback.
191 * @throws WvcmException ReasonCode:
192 * <li>{@link ReasonCode#METHOD_NOT_SUPPORTED}:
193 * This resource has no content.
194 */
195 public Resource doReadContent(
196 OutputStream content,
197 Feedback feedback)
198 throws WvcmException;
199
200 /**
201 * Persists content changes to a resource.
202 * <p>
203 * Postconditions:
204 * <li>(auto-checkout-controlled-content): If this resource was a checked-in controlled,
205 * resource, this resource MUST have been checked out by this request.
206 *
207 * @param content if <code>contentIdentifier</code> matches the current
208 * content identifier of the persistent resource,
209 * the content of the resource is replaced with the
210 * bytes read from <code>content</code>, and <code>content</code>
211 * is then closed.</p>
212 * @param contentIdentifier if this {@link #getContentIdentifier content identifier}
213 * does not match
214 * the content identifier of the persistent resource, the persistent
215 * resource is left unaltered, and a WvcmException is thrown.
216 * <p>
217 * If reading from the stream throws a <code>java.io.IOException</code>,
218 * then no further data will be read from the stream,
219 * and after attempting to close the stream, a <code>WvcmException</code>
220 * wrapping the <code>IOException</code> is thrown,
221 * possibly leading to incomplete data being stored on the resource.</p>
222 * @param feedback Specifies optional feedback to the caller.
223 * @return a new proxy for this resource, whose properties are specified by feedback.
224 * @throws WvcmException ReasonCode:
225 * <li>{@link ReasonCode#CANNOT_MODIFY_VERSION}:
226 * If this proxy identifies a version, the request MUST fail.
227 * <li>Since this method may cause a checkout to be attempted on this resource,
228 * see {@link ControllableResource#doCheckin} for additional reason codes.
229 */
230 public Resource doWriteContent(InputStream content, String contentIdentifier, Feedback feedback)
231 throws WvcmException;
232
233 /** Boolean flags for the doCopy method */
234 public static enum CopyFlag
235 {
236 /**
237 * Indicates whether to overwrite an existing binding in the destination folder
238 */
239 OVERWRITE("overwrite"); //$NON-NLS-1$
240
241 private CopyFlag(String flagName) { _flagName = flagName; }
242
243 /**
244 * Returns a string representation of this flag suitable for diagnostics.
245 */
246 @Override
247 public String toString() { return _flagName; }
248
249 /**
250 * The string form of this flag.
251 */
252 private final String _flagName;
253
254 }
255
256 /**
257 * Create a copy of the resource identified by this Resource
258 * at the location identified by the <code>destination</code>.
259 * The content of the copy is the same as the content of the
260 * resource identified by this Resource, but the properties of the
261 * copy are the default properties for a new resource.
262 * <p>
263 * Postconditions:
264 * <li>(must-not-copy-resource-identifier): The copy must be a different resource.
265 * In particular, it must have a different resource identifier.
266 * <li>(copy-creates-new-resource): If the source of a doCopy is a controlled resource
267 * or a version,
268 * and if there is no resource at the destination of the doCopy,
269 * then the doCopy creates a new uncontrolled resource at the destination of the doCopy.
270 *
271 * @param destination the location of the new resource created by doCopy.
272 * @param flags Array of boolean flags (may be null):
273 * <li>{@link CopyFlag#OVERWRITE}:
274 * Indicates whether an existing destination resource
275 * will be overwritten rather than the request failing.
276 * @param feedback Specifies optional feedback to the caller.
277 * @return a new proxy for this resource, whose properties are specified by feedback.
278 * @throws WvcmException ReasonCode:
279 * <li>{@link ReasonCode#CANNOT_OVERWRITE}:
280 * If there already is a resource at the destination,
281 * and the <code>overwrite</code> is <code>false</code>, the request MUST fail.
282 * <li>{@link ReasonCode#METHOD_NOT_SUPPORTED}:
283 * This proxy MUST NOT identify a folder version or a version history.
284 * In order to create another version history whose versions have the same content,
285 * the appropriate sequence of doVersionControl, doCheckout, doWriteContent, and doCheckin requests must be made.
286 */
287 public Resource doCopy(Location destination, CopyFlag[] flags, Feedback feedback)
288 throws WvcmException;
289
290 /**
291 * Unbinds the resource identified by this Resource
292 * from all folders in its {@link #PARENT_LIST}.
293 *
294 * See {@link Folder#doUnbindChild}.
295 */
296 public void doUnbindAll(Feedback feedback) throws WvcmException;
297
298 /**
299 * Find a persistent resource that "matches" this proxy.
300 * For example,
301 * <pre>
302 * Activity activityExample = WorkspaceProvider.activity(WorkspaceProvider.location("/my-act-repo")):
303 * activityExample.setCreatorDisplayName("Geoff Clemm");
304 * Activity activity = (Activity)activityExample.doFind(null);
305 * </pre>
306 * would return an activity in "/my-act-repo" created by "Geoff Clemm".
307 * Unlike most doXyz methods, this method does not save changes to the proxy
308 * before executing the query. In particular, it is valid to execute
309 * this method on a proxy that could not be saved by {@link #doWriteProperties}.
310 * <p>The precise rules for matching are as follows:
311 * <li>A proxy Q matches a resource R if the type of Q "matches" the type of R,
312 * if the location of Q "matches" the location of R,
313 * and if for each loaded property P of the proxy Q,
314 * Q.P.value (the value of the property P of the proxy Q) "matches" R.P.value
315 * (the value of the property P of the resource R).
316 * Note that a property is loaded into a proxy as the result of reading properties values
317 * from the repository when creating the proxy (e.g., {@link #doReadProperties})
318 * or by explicitly setting property values (e.g., {@link #setComment}
319 * or more generally, {@link #setProperty}).
320 * <li>The type of a proxy matches the type of a resource if the resource implements the
321 * result type of the method used to create the proxy. So for example, if the proxy was
322 * created by {@link WorkspaceProvider#workspace}, to match that proxy a resource
323 * must implement the {@link Workspace} interface.
324 * <li>The location of a proxy Q matches the location of a resource R
325 * if the resource identified by the location of Q would be in the same "repository" as R.
326 * Note that whether or not a resource would be in the same repository as another
327 * resource is decided by the implementation of the {@link #doFind} method.
328 * <li>If Q.P.value is not a list and R.P.value is a list, then Q.P.value matches
329 * R.P.value if Q.P.value matches at least one object in R.P.value.
330 * <li>If Q.P.value is a list of proxies, and R.P.value is not a list, then Q.P.value matches
331 * R.P.value if at least one proxy in Q.P.value matches R.P.value.
332 * <li>If Q.P.value is a list of proxies, and R.P.value is a list, then Q.P.value matches
333 * R.P.value if at least one proxy in Q.P.value matches at least one object in R.P.value.
334 * <li>If Q.P is Resource.PATHNAME_LOCATION, then Q matches R if R is the resource
335 * identified by Q.P.value.
336 * <li>Otherwise, Q.P.value matches R.P.value if Q.P.value {@link Object#equals} R.P.value.
337 *
338 * @param feedback the properties to be available in the returned resources.
339 * @return a proxy for a persistent resource that matches this Resource.
340 * If none found, <code>null</code> is returned.
341 * @throws WvcmException if problems encountered communicating with server
342 * or if the request could not be executed.
343 */
344 public Resource doFind(Feedback feedback)
345 throws WvcmException;
346
347
348 /**
349 * Find all persistent resources that "match" this proxy.
350 * For example,
351 * <pre>
352 * Activity activityExample = WorkspaceProvider.activity(WorkspaceProvider.location("/my-act-repo")):
353 * activityExample.setCreatorDisplayName("Geoff Clemm");
354 * ResponseIterator myActivities = activityExample.doFindAll(null);
355 * </pre>
356 * would return all activities in "/my-act-repo" created by "Geoff Clemm".
357 * See {@link #doFind}.
358 *
359 * @param feedback the properties to be available in the returned resources.
360 * @return proxies for persistent resources that that match this Resource.
361 * @throws WvcmException if problems encountered communicating with server
362 * or if the request could not be executed.
363 */
364 public <T extends Resource> ResponseIterator<T> doFindAll(Feedback feedback)
365 throws WvcmException;
366
367
368 // Resource Properties
369
370 /**
371 * A list of folders that contain workspaces that are being managed
372 * by the same server that is managing this resource.
373 */
374 public static final PropertyName<ResourceList<Folder>> WORKSPACE_FOLDER_LIST =
375 new PropertyName<ResourceList<Folder>>("workspace-folder-list"); //$NON-NLS-1$
376
377 /**
378 * Get the {@link #WORKSPACE_FOLDER_LIST} property.
379 *
380 * @return the {@link #WORKSPACE_FOLDER_LIST} property.
381 * @throws WvcmException if this Resource was not created with
382 * {@link #WORKSPACE_FOLDER_LIST} as a wanted property.
383 */
384 public ResourceList<Folder> getWorkspaceFolderList() throws WvcmException;
385
386 /**
387 * A list of names of alternative providers for the
388 * persistent resource identified by this resource.
389 * Provider names are class names, and {@link Provider} objects
390 * can be generated from provider names using {@link ProviderFactory#createProvider(String,ProviderFactory.Callback)}.
391 * The preferred providers are specified earlier in the list.
392 */
393 public static final PropertyName<List<String>> PROVIDER_LIST =
394 new PropertyName<List<String>>("provider-list"); //$NON-NLS-1$
395
396 /**
397 * Get the {@link #PROVIDER_LIST} property.
398 *
399 * @return the {@link #PROVIDER_LIST} property.
400 * @throws WvcmException if this Resource was not created with
401 * {@link #PROVIDER_LIST} as a wanted property.
402 */
403 public List<String> getProviderList()
404 throws WvcmException;
405
406 /**
407 * A resource identifier is an optional unique and immutable identifier for a resource.
408 * The resource identifier may be used to test whether two proxies
409 * identify the same persistent resource.
410 * The resource identifier is the string form of a stable location for the resource,
411 * where a stable location is a location that is not affected by moves/renames
412 * by {@link Folder#doRebindChild} or by the addition/removal of additional locations for the
413 * resource by {@link Folder#doBindChild} and {@link Folder#doUnbindChild}.
414 * <p>
415 * If {@link Provider#location} can be applied to the resource identifier of a resource
416 * to produces a valid location, then that location MUST identify that resource.
417 */
418 public static final PropertyName<String> RESOURCE_IDENTIFIER =
419 new PropertyName<String>("resource-id"); //$NON-NLS-1$
420
421 /**
422 * Get the {@link #RESOURCE_IDENTIFIER} property.
423 *
424 * @return the {@link #RESOURCE_IDENTIFIER} property.
425 * @throws WvcmException if this Resource was not created with
426 * {@link #RESOURCE_IDENTIFIER} as a wanted property.
427 */
428 public String getResourceIdentifier()
429 throws WvcmException;
430
431 /**
432 * A location for this resource to which {@link Location#parent} can be applied
433 * zero or more times to produce a location for a folder in either
434 * the {@link Resource#WORKSPACE_FOLDER_LIST} of this resource, or for a folder in
435 * the {@link Workspace#ACTIVITY_FOLDER_LIST} or {@link Workspace#VERSION_HISTORY_FOLDER_LIST}
436 * of some workspace that is a member of a folder in {@link Resource#WORKSPACE_FOLDER_LIST}.
437 */
438 public static final PropertyName<Location> PATHNAME_LOCATION =
439 new PropertyName<Location>("pathname-location"); //$NON-NLS-1$
440
441 /**
442 * Get the {@link #PATHNAME_LOCATION} property.
443 *
444 * @return the {@link #PATHNAME_LOCATION} property.
445 * @throws WvcmException if this Resource was not created with
446 * {@link #PATHNAME_LOCATION} as a wanted property.
447 */
448 public Location getPathnameLocation() throws WvcmException;
449
450 /**
451 * The PARENT_LIST property enables
452 * clients to discover what folders contain a binding to this resource
453 * (that is, which folders have this resource as a bound member).
454 * The value of the PARENT_LIST property is a list of
455 * {@link Folder} objects.
456 */
457 public static final PropertyName<ResourceList<Folder>> PARENT_LIST =
458 new PropertyName<ResourceList<Folder>>("parent-list"); //$NON-NLS-1$
459
460 /**
461 * Get the {@link #PARENT_LIST} property.
462 *
463 * @return the {@link #PARENT_LIST} property.
464 * @throws WvcmException if this Resource was not created with
465 * {@link #PARENT_LIST} as a wanted property.
466 */
467 public ResourceList<Folder> getParentList()
468 throws WvcmException;
469
470 /**
471 * Contains a description of the resource that is suitable
472 * for presentation to a user in a tree display.
473 * <p>
474 * Note that the {@link #DISPLAY_NAME} of a resource is in general
475 * not the binding name of that resource in its parent folder,
476 * because at a given time, a resource can be bound into
477 * multiple parent folders, and have a different binding name in
478 * each parent folder. </p>
479 */
480 public static final PropertyName<String> DISPLAY_NAME =
481 new PropertyName<String>("display-name"); //$NON-NLS-1$
482
483 /**
484 * Get the {@link #DISPLAY_NAME} property.
485 *
486 * @return the {@link #DISPLAY_NAME} property.
487 * @throws WvcmException if this property was not set and
488 * this Resource was not created with
489 * {@link #DISPLAY_NAME} as a wanted property.
490 * @see #setDisplayName
491 */
492 public String getDisplayName() throws WvcmException;
493
494 /**
495 * Set the {@link #DISPLAY_NAME} property.
496 *
497 * @param val the new display name to apply to the resource.
498 * @see #getDisplayName
499 */
500 public void setDisplayName(String val);
501
502 /**
503 * A brief comment about a resource that
504 * is suitable for presentation to a user. The comment of a version
505 * can be used to indicate why that version was created.
506 */
507 public static final PropertyName<String> COMMENT =
508 new PropertyName<String>("comment"); //$NON-NLS-1$
509
510 /**
511 * Get the {@link #COMMENT} property.
512 * @return the {@link #COMMENT} property.
513 * @throws WvcmException if this property was not set and
514 * this Resource was not created with
515 * {@link #COMMENT} as a wanted property.
516 * @see #setComment
517 */
518 public String getComment() throws WvcmException;
519
520 /**
521 * Set the {@link #COMMENT} property.
522 *
523 * @param comment the new comment to apply to this Resource.
524 * @see #getComment
525 */
526 public void setComment(String comment);
527
528 /**
529 * This property contains a description of the creator of the resource
530 * that is suitable for presentation to a user. The {@link #CREATOR_DISPLAY_NAME}
531 * of a version can be used to indicate who created that version.
532 * A server may automatically set the {@link #CREATOR_DISPLAY_NAME} property
533 * and not allow it to be changed by a client.
534 */
535 public static final PropertyName<String> CREATOR_DISPLAY_NAME =
536 new PropertyName<String>("creator-display-name"); //$NON-NLS-1$
537
538 /**
539 * Get the {@link #CREATOR_DISPLAY_NAME} property.
540 *
541 * @return the {@link #CREATOR_DISPLAY_NAME} property.
542 * @throws WvcmException if this property was not set and
543 * this Resource was not created with
544 * {@link #CREATOR_DISPLAY_NAME} as a wanted property.
545 * @see #setCreatorDisplayName
546 */
547 public String getCreatorDisplayName() throws WvcmException;
548
549 /**
550 * Set the {@link #CREATOR_DISPLAY_NAME} property.
551 *
552 * @param val the new creator display name to apply to the resource.
553 * @see #getCreatorDisplayName
554 */
555 public void setCreatorDisplayName(String val);
556
557 /** The date and time the resource was created. */
558 public static final PropertyName<Date> CREATION_DATE =
559 new PropertyName<Date>("creation-date"); //$NON-NLS-1$
560
561 /**
562 * Get the {@link #CREATION_DATE} property.
563 *
564 * @return the {@link #CREATION_DATE} property.
565 * @throws WvcmException if this Resource was not created with
566 * {@link #CREATION_DATE} as a wanted property
567 */
568 public Date getCreationDate() throws WvcmException;
569
570 /**
571 * The date and time the content of the resource was last modified.
572 */
573 public static final PropertyName<Date> LAST_MODIFIED =
574 new PropertyName<Date>("last-modified"); //$NON-NLS-1$
575
576 /**
577 * Get the {@link #LAST_MODIFIED} property.
578 *
579 * @return the {@link #LAST_MODIFIED} property.
580 * @throws WvcmException if this Resource was not created with
581 * {@link #LAST_MODIFIED} as a wanted property.
582 */
583 public Date getLastModified() throws WvcmException;
584
585 /**
586 * The name of the character set of the resource content.
587 * Character sets names must be registered; see RFC 2278 and 1700
588 */
589 public static final PropertyName<String> CONTENT_CHARACTER_SET =
590 new PropertyName<String>("content-character-set"); //$NON-NLS-1$
591
592 /**
593 * Get the {@link #CONTENT_CHARACTER_SET} property.
594 * @return the {@link #CONTENT_CHARACTER_SET} property.
595 * @throws WvcmException if this property was not set and
596 * this Resource was not created with
597 * {@link #CONTENT_CHARACTER_SET} as a wanted property.
598 * @see #setContentCharacterSet
599 */
600 public String getContentCharacterSet() throws WvcmException;
601
602 /**
603 * Set the {@link #CONTENT_CHARACTER_SET} property.
604 *
605 * @param contentCharacterSet the content character set for the resource.
606 * @see #getContentCharacterSet
607 */
608 public void setContentCharacterSet(String contentCharacterSet);
609
610 /**
611 * An implementation-defined String identifying the value of the content of a resource.
612 * The semantics of a Content Identifier are the same as that of an HTTP ETag (see RFC 2616).
613 */
614 public static final PropertyName<String> CONTENT_IDENTIFIER =
615 new PropertyName<String>("content-identifier"); //$NON-NLS-1$
616
617 /**
618 * Get the {@link #CONTENT_IDENTIFIER} property.
619 * @return the {@link #CONTENT_IDENTIFIER} property.
620 * @throws WvcmException if this Resource was not created with
621 * {@link #CONTENT_IDENTIFIER} as a wanted property.
622 */
623 public String getContentIdentifier() throws WvcmException;
624
625 /**
626 * The name of the natural language used in a resource content,
627 * represented by a {@link java.util.Locale Locale} object,
628 * with country, language, and variant if appropriate.
629 */
630 public static final PropertyName<Locale> CONTENT_LANGUAGE =
631 new PropertyName<Locale>("content-language"); //$NON-NLS-1$
632
633 /**
634 * Get the {@link #CONTENT_LANGUAGE} property.
635 * @return the {@link #CONTENT_LANGUAGE} property.
636 * @throws WvcmException if this property was not set and
637 * this Resource was not created with
638 * {@link #CONTENT_LANGUAGE} as a wanted property.
639 * @see #setContentLanguage
640 */
641 public Locale getContentLanguage() throws WvcmException;
642
643 /**
644 * Set the {@link #CONTENT_LANGUAGE} property.
645 *
646 * @param contentLanguage the content language for the resource.
647 * @see #getContentLanguage
648 */
649 public void setContentLanguage(Locale contentLanguage);
650
651 /** The size in bytes of the content of a resource. */
652 public static final PropertyName<Long> CONTENT_LENGTH =
653 new PropertyName<Long>("content-length"); //$NON-NLS-1$
654
655 /**
656 * Get the {@link #CONTENT_LENGTH} property.
657 *
658 * @return the {@link #CONTENT_LENGTH} property.
659 * @throws WvcmException if this Resource was not created with
660 * {@link #CONTENT_LENGTH} as a wanted property.
661 */
662 public long getContentLength() throws WvcmException;
663
664 /**
665 * A MIME type string (see RFC 1590) indicating the media type of the
666 * resource content.
667 */
668 public static final PropertyName<String> CONTENT_TYPE =
669 new PropertyName<String>("content-type"); //$NON-NLS-1$
670
671 /**
672 * Get the {@link #CONTENT_TYPE} property.
673 * A server may refuse to allow the {@link #CONTENT_TYPE} of a resource to be changed
674 * after the resource has been created.
675 *
676 * @return the {@link #CONTENT_TYPE} property.
677 * @throws WvcmException if this property was not set and
678 * this Resource was not created with
679 * {@link #CONTENT_TYPE} as a wanted property.
680 * @see #setContentType
681 */
682 public String getContentType() throws WvcmException;
683
684 /**
685 * Set the {@link #CONTENT_TYPE} property.
686 *
687 * @param contentType the content type for the resource.
688 * @see #getContentType
689 */
690 public void setContentType(String contentType);
691
692 /**
693 * Whether the content is executable (i.e, can be run as a program).
694 */
695 public static final PropertyName<Boolean> IS_EXECUTABLE =
696 new PropertyName<Boolean>("is-executable"); //$NON-NLS-1$
697
698 /**
699 * Get the {@link #IS_EXECUTABLE} property.
700 *
701 * @return the {@link #IS_EXECUTABLE} property.
702 * @throws WvcmException if this property was not set and
703 * this Resource was not created with
704 * {@link #IS_EXECUTABLE} as a wanted property.
705 * @see #setIsExecutable
706 */
707 public Boolean getIsExecutable() throws WvcmException;
708
709 /**
710 * Set the {@link #IS_EXECUTABLE} property.
711 *
712 * @param isExecutable whether the resource is executable.
713 * @see #getIsExecutable
714 */
715 public void setIsExecutable(Boolean isExecutable);
716
717 /**
718 * A generic PropertyName that selects all custom properties
719 * (i.e., properties with a non-null namespace)
720 * that are defined on the resource.
721 */
722 public static final PropertyName<Object> ALL_CUSTOM_PROPERTIES =
723 new PropertyName<Object>("all-custom-properties"); //$NON-NLS-1$
724
725 /**
726 * Get the value of the specified property of this Resource.
727 *
728 * @param name the name of the property.
729 * @return the value of the specified property of this Resource.
730 * @throws WvcmException if this property was not set and
731 * this Resource was not created with
732 * the specified property as a wanted property.
733 * @see #setProperty
734 */
735 public <T> T getProperty(PropertyName<T> name)
736 throws WvcmException;
737
738 /**
739 * Lookup the value of the specified property of this Resource.
740 *
741 * @param name the name of the property.
742 * @return the value of the specified property of this Resource,
743 * or a WvcmException if there was an error computing the property value
744 * or if this property was not set and this resource was not created
745 * with the specified property as a wanted property.
746 * @see #getProperty
747 */
748 public Object lookupProperty(PropertyName<?> name);
749
750 /**
751 * Adds or replaces the value of the specified property of this Resource.
752 *
753 * @param name the name of the property.
754 * @param value the new value of the specified property.
755 * @see #getProperty
756 */
757 public <T> void setProperty(PropertyName<T> name, T value);
758
759 /**
760 * Initializes the value of the specified property of this Resource.
761 * If that property of the Resource is non-null when it is written
762 * (e.g., by a {@link #doWriteProperties} request),
763 * {@link WvcmException} with {@link ReasonCode#CANNOT_OVERWRITE}
764 * is thrown and the property of the Resource is not changed.
765 *
766 * @param name the name of the property.
767 * @param value the value of the specified property.
768 * @see #getProperty
769 */
770 public <T> void initProperty(PropertyName<T> name, T value);
771
772 /**
773 * Adds and removes the specified values from the current value
774 * of the specified list-valued property.
775 *
776 * @param name the name of the property.
777 * @param additions the values to be added to the value of the specified property value.
778 * @param removals the values to be removed from the value of the specified property.
779 * @see #setProperty
780 */
781 public <V, U extends Collection<V>> void setProperty(PropertyName<U> name, U additions, U removals);
782
783 /**
784 * Removes the specified property of this Resource.
785 * This is just a local change to this proxy, and is not
786 * persisted back to the resource identified by this Resource.
787 * This is commonly used to clear an updated property that
788 * caused {@link #doWriteProperties} to fail.
789 *
790 * @param name the name of the property.
791 */
792 public void forgetProperty(PropertyName<?> name);
793
794 /**
795 * Removes the specified property of this Resource.
796 * The next doXyz() request will cause the server to remove this property
797 * from the resource on the server identified by this Resource.
798 *
799 * @param name the name of the property.
800 */
801 public void removeProperty(PropertyName<?> name);
802
803 }