Java > Open Source Codes > org > outerj > daisy > repository > Document


1 /*
2  * Copyright 2004 Outerthought bvba and Schaubroeck nv
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.outerj.daisy.repository;
17
18 import org.outerx.daisy.x10.DocumentDocument;
19
20 import java.util.Map ;
21 import java.util.Date ;
22
23 /**
24  * A document in the repository. This object actually always represents one
25  * particular variant (branch-language combination) of the document. There
26  * is no separate object representing a document itself as such, access to
27  * documents is always done through a certain variant of it (since access
28  * control is also determined based on the information that is part of the
29  * variant). Letting a document object represent both the document and
30  * document variant was also the most backwards-compatible way to introduce
31  * the variants feature.
32  *
33  * <p>Since one object is used to manipulate both the document and document
34  * variant, most methods include a mentioning of whether they apply to the
35  * document or the document variant.
36  *
37  * <p>A document can be created using {@link Repository#createDocument(String, String)}
38  * or retrieved using {@link Repository#getDocument(long, boolean)}.
39  *
40  */
41 public interface Document {
42     /**
43      * Returns the id of this document. For newly created documents, this method
44      * returns -1 until {@link #save()} is called.
45      */
46     public long getId();
47
48     public long getBranchId();
49
50     public long getLanguageId();
51
52     public VariantKey getVariantKey();
53
54     /**
55      * Returns true if the variant represented by this document object has
56      * never been stored yet.
57      */
58     public boolean isVariantNew();
59
60     /**
61      * Returns the available variants for this document. If the document is new and unsaved, this
62      * returns an empty list. If the document variant in this document is new and unsaved, the
63      * returned list will not yet contain this new variant. Thus only variants persisted in the
64      * repository are returned. This method does the same as {@link Repository#getAvailableVariants(long)}.
65      */
66     public AvailableVariants getAvailableVariants() throws RepositoryException;
67
68     /**
69      * Returns the id of the document type to which this document adheres.
70      * Document types themselve are managed via the {@link org.outerj.daisy.repository.schema.RepositorySchema}.
71      *
72      * <p>The document type is a variant-level property.
73      */
74     public long getDocumentTypeId();
75
76     /**
77      * Changes the document type of this document.
78      *
79      * <p>Will throw an exception if the document type does not exist.
80      *
81      * <p>Changing the documenttype does not influence the content of the document,
82      * you have to assure yourself that you update/add/remove parts and fields so
83      * that the document conforms to the document type.
84      *
85      * <p>The document type is a variant-level property.
86      */
87     public void changeDocumentType(long documentTypeId) throws RepositoryException;
88
89     /**
90      * See {@link #changeDocumentType(long)}.
91      */
92     public void changeDocumentType(String documentTypeName) throws RepositoryException;
93
94     /**
95      * Gets the name of this document.
96      *
97      * <p>The document name is a variant-level property.
98      */
99     public String getName();
100
101     /**
102      * Sets the name of the document. The document name is not required to be unique,
103      * and is versioned, ie changing the document name and then saving the document
104      * will create a new version.
105      *
106      * <p>The document name is a variant-level property.
107      */
108     public void setName(String name);
109
110     /**
111      * Returns the user id of the owner of this document. The owner is the user that
112      * created the document, unless changed.
113      *
114      * <p>The owner is a document-level property.
115      */
116     public long getOwner();
117
118     /**
119      * Change the owner of this document. Only users acting in the Administrator role,
120      * or the current owner, can change the owner.
121      *
122      * <p>The owner is a document-level property.
123      */
124     public void setOwner(long userId);
125
126     /**
127      * Is this a private document or not. A private document is a document that can
128      * only be accessed by its owner, or users having (and acting) in the role of
129      * Administrator.
130      *
131      * <p>This is a document-level property.
132      */
133     public boolean isPrivate();
134
135     /**
136      * Sets the private flag for this document, see also {@link #isPrivate()}.
137      * New documents are not private by default.
138      *
139      * <p>This is a document-level property.
140      */
141     public void setPrivate(boolean _private);
142
143     /**
144      * Gets the time this document was created.
145      *
146      * <p>This is a document-level property.
147      */
148     public Date getCreated();
149
150     /**
151      * Is this document retired or not. A retired document behaves very much likes
152      * a deleted document. Retired documents don't show up in query results (unless
153      * specifically requested).
154      *
155      * <p>This is a variant-level property.
156      */
157     public boolean isRetired();
158
159     /**
160      * Sets the retired flag for this document, see also {@link #isRetired()}.
161      *
162      * <p>This is a variant-level property.
163      */
164     public void setRetired(boolean retired);
165
166     /**
167      * The time this document was last saved. Returns null for documents that
168      * have never been saved yet.
169      *
170      * <p>This is a document-level property. See also {@link #getVariantLastModified()}.
171      */
172     public Date getLastModified();
173
174     /**
175      * Returns the user id of the last user who saved this document.
176      * Returns -1 for documents that have never been saved yet.
177      *
178      * <p>This is a document-level property. See also {@link #getVariantLastModifier()}.
179      */
180     public long getLastModifier();
181
182     /**
183      * The time the document variant was last saved. Returns null for document variants that
184      * have never been saved yet.
185      *
186      * <p>This is a variant-level property. See also {@link #getLastModified()}.
187      */
188     public Date getVariantLastModified();
189
190     /**
191      * Returns the user id of the last user who saved this document variant.
192      * Returns -1 for document variants that have never been saved yet.
193      *
194      * <p>This is a variant-level property. See also {@link #getLastModifier()}.
195      */
196     public long getVariantLastModifier();
197
198     /**
199      * Returns all versions stored for this document.
200      *
201      * <p>In a typical implementation, the returned Version objects will only contain
202      * basic information about the version (like its id and creation time) which is
203      * needed to show a version list, but the actual version content (fields,
204      * parts, ...) will only be loaded when requested.
205      *
206      * <p>This is a variant-level method.
207      */
208     public Versions getVersions() throws RepositoryException;
209
210     /**
211      * Returns the requested version.
212      *
213      * <p>Note that in contrast with the {@link #getVersions()} method, typical
214      * implementations will usually return a Version object containing all details
215      * about the version.
216      *
217      * <p>This is a variant-level method.
218      */
219     public Version getVersion(long id) throws RepositoryException;
220
221     /**
222      * Returns the id of the last stored version. For new, unsaved documents this
223      * returns -1.
224      *
225      * <p>This is a variant-level property.
226      */
227     public long getLastVersionId();
228
229     /**
230      * Returns the Version object for the last stored version, or null for unsaved
231      * documents.
232      *
233      * <p>This is a variant-level method.
234      */
235     public Version getLastVersion() throws RepositoryException;
236
237     /**
238      * Returns the live version of this document, or null if there is none.
239      * The live version is the most recent version that has the state 'publish'.
240      *
241      * <p>This is a variant-level method.
242      */
243     public Version getLiveVersion() throws RepositoryException;
244
245     /**
246      * Returns the id of the live version, or -1 if there is none.
247      *
248      * <p>This is a variant-level method.
249      */
250     public long getLiveVersionId();
251
252     /**
253      * Returns true if the current user can only access live data of the document.
254      */
255     public boolean canReadLiveOnly();
256
257     /**
258      * Sets the value of a field. The field must be part of the document type
259      * of this document.
260      *
261      * <p>This is a variant-level method.
262      *
263      * @param name name of the field type of the field to set.
264      * @param value the value of the field, the type of the object must be in correspondence with the ValueType of the field type.
265      * For multi-value fields, the value should be an array (i.e. Object[] or a more specifically typed array).
266      * For link field types, the value is a VariantKey object. The branch and language fields of the VariantKey
267      * object can be -1 to indicate they are the same as the containing document (recommended for most uses).
268      */
269     public void setField(String name, Object value) throws DocumentTypeInconsistencyException;
270
271     /**
272      * Same as {@link #setField(String, Object)} but using the id of the field type.
273      *
274      * <p>This is a variant-level method.
275      */
276     public void setField(long fieldTypeId, Object value) throws DocumentTypeInconsistencyException;
277
278     /**
279      * Removes the specified field. Silently ignored if the document doesn't have that field.
280      *
281      * <p>This is a variant-level method.
282      *
283      * @param name name of the field type
284      */
285     public void deleteField(String name);
286
287     /**
288      * Removes the specified field. Silently ignored if the document doesn't have that field.
289      *
290      * <p>This is a variant-level method.
291      */
292     public void deleteField(long fieldTypeId);
293
294     /**
295      * Gets a field by field type name. Throws a FieldNotFoundException if there is no
296      * such field in the document, use {@link #hasField(String)} to check if the
297      * document has the field.
298      *
299      * <p>This is a variant-level method.
300      */
301     public Field getField(String fieldTypeName) throws FieldNotFoundException;
302
303     /**
304      * Same as {@link #getField(String)} but using the field type id.
305      *
306      * <p>This is a variant-level method.
307      */
308     public Field getField(long fieldTypeId) throws FieldNotFoundException;
309
310     /**
311      * Checks if the document contains the field with the specified field type id.
312      *
313      * <p>This is a variant-level method.
314      */
315     public boolean hasField(long fieldTypeId);
316
317     /**
318      * Checks if the document contains the field with the specified field type name.
319      *
320      * <p>This is a variant-level method.
321      */
322     public boolean hasField(String fieldTypeName);
323
324     /**
325      * Gets all fields in the document.
326      *
327      * <p>This is a variant-level method.
328      */
329     public Fields getFields();
330
331     /**
332      * Gets all fields in the document, sorted in the same order as the fields are
333      * defined in the document type. Any fields this document has that are not part
334      * of the document type are added in unspecified order to the end of the list.
335      *
336      * <p>This is a variant-level method.
337      */
338     public Fields getFieldsInOrder();
339
340
341     /**
342      * Saves a document.
343      *
344      * <p>This is the same as calling {@link #save(boolean)} with argument true.
345      */
346     public void save() throws RepositoryException;
347
348     /**
349      * Saves the document and document variant.
350      *
351      * <p>If only changes have been done to document-level properties,
352      * only the document will be saved. If only changes have been done
353      * to variant-level properties, only the variant will be saved.
354      *
355      * <p>If this is a new document, it will cause an id to be assigned
356      * to this document object.
357      *
358      * <p>Saving the document variant might or might not cause the creation of a new
359      * version, depending on whether any versioned data has changed. Versioned
360      * data includes the parts, fields, links and the document's name. So if
361      * for example only the retired flag changed, customfields were changed,
362      * or collection membership changed, no new version will be created.
363      * After saving, you can get the new version id from the method
364      * {@link #getLastVersionId()}. The state of the new version can be
365      * influenced by using {@link #setNewVersionState(org.outerj.daisy.repository.VersionState)}
366      * before calling save().
367      *
368      *
369      * <p>If someone else holds a pessimistic lock on the document variant, saving it
370      * will fail. Likewise, if another person saved the document since you retrieved
371      * this document object (ie a concurrent modification), saving will also fail.
372      * Note that locks apply only to document variants, so don't protect from concurrent
373      * changes to document-level properties.
374      *
375      * <p>Saving a document will cause the server to send out an assynchronous
376      * event, to which other processes can listen, for example the full
377      * text indexer. (There are separate events for updates to the document and
378      * the variant)
379      *
380      * <p>Using the argument <tt>validate</tt> you can specify whether the document variant
381      * should be validated against its document type. Usually you will always
382      * provide true here. As an example use case for not using validation,
383      * it might be that you just want to mark a
384      * document as retired without bothering that its content doesn't correspond
385      * to the schema anymore.
386      */
387     public void save(boolean validate) throws RepositoryException;
388
389     /**
390      * Validates that this document confirms to its document type.
391      */
392     public void validate() throws DocumentTypeInconsistencyException;
393
394     /**
395      * Sets the VersionState that should be used if a new version is created
396      * when saving the document.
397      *
398      * <p>By default this is VersionState.PUBLISH.
399      */
400     public void setNewVersionState(VersionState versionState);
401
402     /**
403      * See {@link #setNewVersionState(VersionState)}.
404      */
405     public VersionState getNewVersionState();
406
407     /**
408      * Takes a lock on the document variant. If the lock type is "pessimistic", this will prevent
409      * others from saving the document variant while you're working on it. If the lock
410      * is "warn", the lock only serves for informational purposes and will
411      * not enforce anything. So called "optimistic locking" (ie checking against
412      * concurrent modifications) happens always, and doesn't require to take a lock.
413      *
414      * <p>Changing a lock doesn't need a {@link #save()} call afterwards,
415      * calling this method has immediate effect.
416      *
417      * <p>This is a variant-level method.
418      *
419      * @param duration indication of how long the lock should remain (in ms).
420      * Use -1 for a never-expiring lock.
421      * @return false if someone else already has a lock on this document, in
422      * which case you can call {@link #getLockInfo(boolean)} with false
423      * as parameter to know who is holding the lock.
424      */
425     public boolean lock(long duration, LockType lockType) throws RepositoryException;
426
427     /**
428      * Releases the lock on the document variant. This can only be done by the person
429      * holding this lock, or by an Administrator.
430      *
431      * <p>This is a variant-level method.
432      *
433      * @return true if the lock is removed (or if there was no lock). If a lock
434      * remains on the document, false will be returned, in which case
435      * you can call {@link #getLockInfo(boolean)} with false
436      * as parameter to know who is holding the lock.
437      */
438     public boolean releaseLock() throws RepositoryException;
439
440     /**
441      * Returns information about the current lock on the document variant.
442      *
443      * <p>This is a variant-level method.
444      *
445      * @param fresh if true, the lock information will be refetched. Otherwise
446      * the existing information stored in this Document object will
447      * be returned (which may be out of date).
448      */
449     public LockInfo getLockInfo(boolean fresh) throws RepositoryException;
450
451     /**
452      * Sets a custom field. A custom field is an arbitrary name/value pair.
453      * Custom fields are not versioned.
454      *
455      * <p>This is a variant-level method.
456      */
457     public void setCustomField(String name, String value);
458
459     /**
460      * Removes the specified custom field. Passes silently if there is no
461      * custom field with the given name.
462      *
463      * <p>This is a variant-level method.
464      */
465     public void deleteCustomField(String name);
466
467     /**
468      * Gets the value of the specified custom field, or null if there is no
469      * custom field with that name.
470      *
471      * <p>This is a variant-level method.
472      */
473     public String getCustomField(String name);
474
475     /**
476      * Returns true if there is a custom field with the specified name.
477      *
478      * <p>This is a variant-level method.
479      */
480     public boolean hasCustomField(String name);
481
482     /**
483      * Removes all custom fields.
484      *
485      * <p>This is a variant-level method.
486      */
487     public void clearCustomFields();
488
489     /**
490      * Returns a map containing the fields, with the field type name being the key.
491      * Making changes to this map will not be reflected in the document.
492      *
493      * <p>This is a variant-level method.
494      */
495     public Map getCustomFields();
496
497     /**
498      * Sets a part.
499      *
500      * <p>This is a variant-level method.
501      */
502     public void setPart(String partTypeName, String mimeType, byte[] data) throws DocumentTypeInconsistencyException;
503
504     /**
505      * Sets a part.
506      *
507      * <p>This is a variant-level method.
508      */
509     public void setPart(long partTypeId, String mimeType, byte[] data) throws DocumentTypeInconsistencyException;
510
511     /**
512      * Sets a part.
513      *
514      * <p>This is a variant-level method.
515      */
516     public void setPart(String partTypeName, String mimeType, PartDataSource partDataSource) throws DocumentTypeInconsistencyException;
517
518     /**
519      * Sets a part.
520      *
521      * <p>This is a variant-level method.
522      */
523     public void setPart(long partTypeId, String mimeType, PartDataSource partDataSource) throws DocumentTypeInconsistencyException;
524
525     /**
526      * Update the file name of an already existing part. Throws an exception if the document doesn't
527      * have the indicated part.
528      *
529      * <p>This is a variant-level method.
530      *
531      * @param fileName allowed to be null (to remove the filename information)
532      */
533     public void setPartFileName(String partTypeName, String fileName);
534
535     /**
536      * Update the file name of an already existing part. Throws an exception if the document doesn't
537      * have the indicated part.
538      *
539      * <p>This is a variant-level method.
540      *
541      * @param fileName allowed to be null (to remove the filename information)
542      */
543     public void setPartFileName(long partTypeId, String fileName);
544
545     /**
546      * Update the mime-type of an already existing part. Throws an exception if the document doesn't
547      * have the indicated part.
548      *
549      * <p>This is a variant-level method.
550      */
551     public void setPartMimeType(String partTypeName, String mimeType);
552
553     /**
554      * Update the mime-type of an already existing part. Throws an exception if the document doesn't
555      * have the indicated part.
556      *
557      * <p>This is a variant-level method.
558      */
559     public void setPartMimeType(long partTypeId, String mimeType);
560
561     /**
562      * Removes a part, passes silently if there is no part in the document with the given id.
563      *
564      * <p>This is a variant-level method.
565      */
566     public void deletePart(long partTypeId);
567
568     /**
569      * Removes a part, passes silently if there is no part in the document with the given name.
570      *
571      * <p>This is a variant-level method.
572      */
573     public void deletePart(String name);
574
575     /**
576      * Gets a part.
577      *
578      * <p>This is a variant-level method.
579      */
580     public Part getPart(long partTypeId) throws PartNotFoundException;
581
582     /**
583      * Gets a part.
584      *
585      * <p>This is a variant-level method.
586      */
587     public Part getPart(String name) throws PartNotFoundException;
588
589     /**
590      * Checks if the document variant has the part for the specified part type.
591      *
592      * <p>This is a variant-level method.
593      */
594     public boolean hasPart(long partTypeId);
595
596     /**
597      * Checks if the document variant has the part for the specified part type.
598      *
599      * <p>This is a variant-level method.
600      */
601     public boolean hasPart(String name);
602
603     /**
604      * Returns the parts contained in the document variant, in unspecified order.
605      */
606     public Parts getParts();
607
608     public Parts getPartsInOrder();
609
610     /**
611      * Adds an out-of-line link (at the end of the list).
612      *
613      * <p>This is a variant-level method.
614      */
615     public void addLink(String title, String target);
616
617     /**
618      * Removes an out-of-line link.
619      *
620      * <p>This is a variant-level method.
621      */
622     public void deleteLink(int index);
623
624     /**
625      * Removes all out-of-line links.
626      *
627      * <p>This is a variant-level method.
628      */
629     public void clearLinks();
630
631     /**
632      * Removes all out-of-line links.
633      *
634      * <p>This is a variant-level method.
635      */
636     public Links getLinks();
637     
638     /**
639      * Adds the document variant to a supplied Collection.
640      *
641      * @param collection the collection to add the current document to
642      */
643     public void addToCollection(DocumentCollection collection);
644
645     /**
646      * Removes the document variant from a collection
647      *
648      * @param collection the collection from which the document needs to be removed
649      */
650     public void removeFromCollection(DocumentCollection collection);
651     
652     /**
653      * Returns the collections the document variant belongs to, null if the document variant
654      * belongs to no Collections.
655      */
656     public DocumentCollections getCollections();
657
658     /**
659      * Checks if the document variant belongs to the specified collection.
660      */
661     public boolean inCollection(DocumentCollection collection);
662
663     /**
664      * Checks if the document variant belongs to the specified collection.
665      */
666     public boolean inCollection(long collectionId);
667
668     public DocumentDocument getXml() throws RepositoryException;
669
670     public DocumentDocument getXmlWithoutVariant() throws RepositoryException;
671
672     public DocumentDocument getXmlWithoutVersionedData() throws RepositoryException;
673
674     /**
675      * Gets the XML of the document but include the data from the
676      * specified version, instead of the current data. This only
677      * applies to the data of the document that is actually versionable, of course.
678      * For the rest of the data, you'll get what's currently in the document
679      * object, whether that data has already been saved or not.
680      */
681     public DocumentDocument getXml(long versionId) throws RepositoryException;
682
683     /**
684      * Removes the document variant from all the collections it belongs to.
685      */
686     public void clearCollections();
687
688     /**
689      * Returns a summary text for the document variant. The summary is only created/updated
690      * when the document is saved. Returns an empty string if there's no summary.
691      * The summary always corresponds to the live version of the document.
692      */
693     public String getSummary();
694
695     /**
696      * If the variant currently loaded in this document object is created from an existing
697      * branch, this method will return the id of that branch, otherwise it will return -1.
698      * Note that the branch could possibly no longer exist.
699      */
700     public long getVariantCreatedFromBranchId();
701
702     /**
703      * Similar to {@link #getVariantCreatedFromBranchId()}.
704      */
705     public long getVariantCreatedFromLanguageId();
706
707     /**
708      * Similar to {@link #getVariantCreatedFromBranchId()}.
709      */
710     public long getVariantCreatedFromVersionId();
711
712     public long getUpdateCount();
713
714     public long getVariantUpdateCount();
715 }
716

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags