1. Project Clover database Sat Feb 2 2019 06:45:20 CET
  2. Package org.xwiki.bridge

File DocumentAccessBridge.java

 

Coverage histogram

../../../img/srcFileCovDistChart0.png
86% of files have more coverage

Code metrics

0
11
11
1
829
153
11
1
1
11
1

Classes

Class Line # Actions
DocumentAccessBridge 43 11 0% 11 22
0.00%
 

Contributing tests

No tests hitting this source file were found.

Source view

1    /*
2    * See the NOTICE file distributed with this work for additional
3    * information regarding copyright ownership.
4    *
5    * This is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU Lesser General Public License as
7    * published by the Free Software Foundation; either version 2.1 of
8    * the License, or (at your option) any later version.
9    *
10    * This software is distributed in the hope that it will be useful,
11    * but WITHOUT ANY WARRANTY; without even the implied warranty of
12    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13    * Lesser General Public License for more details.
14    *
15    * You should have received a copy of the GNU Lesser General Public
16    * License along with this software; if not, write to the Free
17    * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
18    * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
19    */
20    package org.xwiki.bridge;
21   
22    import java.io.InputStream;
23    import java.util.List;
24    import java.util.Map;
25   
26    import org.xwiki.component.annotation.Role;
27    import org.xwiki.model.EntityType;
28    import org.xwiki.model.reference.AttachmentReference;
29    import org.xwiki.model.reference.DocumentReference;
30    import org.xwiki.model.reference.EntityReference;
31    import org.xwiki.model.reference.ObjectPropertyReference;
32    import org.xwiki.model.reference.ObjectReference;
33    import org.xwiki.stability.Unstable;
34   
35    /**
36    * Exposes methods for accessing Document data. This is temporary until we remodel the Model classes and the Document
37    * services.
38    *
39    * @version $Id: 7ce6f8fea4d030a94bec2f75f88ccdb0b3de04f9 $
40    * @since 1.6M1
41    */
42    @Role
 
43    public interface DocumentAccessBridge
44    {
45    /**
46    * Find the document reference corresponding to the entity reference based on what exist in the database (page
47    * reference can means two different documents for example).
48    *
49    * @param entityReference the reference to resolve
50    * @return the document reference
51    * @since 10.6RC1
52    */
 
53  0 toggle @Unstable
54    default DocumentReference getDocumentReference(EntityReference entityReference)
55    {
56  0 return new DocumentReference(entityReference.extractReference(EntityType.DOCUMENT));
57    }
58   
59    /**
60    * Get the document object associated with the passed document name and context language.
61    * <p>
62    * Note that the returned document does not contain objects and attachment so it should be used very carefully.
63    *
64    * @param documentReference the String reference of the document to find
65    * @return the document object matching the passed document name
66    * @throws Exception when the storage cannot be accessed
67    * @deprecated use {@link #getTranslatedDocumentInstance(DocumentReference)} instead
68    */
69    @Deprecated
70    DocumentModelBridge getDocument(String documentReference) throws Exception;
71   
72    /**
73    * Get the document object associated with the passed document name and context language.
74    * <p>
75    * Note that the returned document does not contain objects and attachment so it should be used very carefully.
76    *
77    * @param documentReference the name of the document to find
78    * @return the document object matching the passed document name
79    * @throws Exception when the storage cannot be accessed
80    * @since 2.2M1
81    * @deprecated deprecated since 10.2RC1, use {@link #getTranslatedDocumentInstance(DocumentReference)} instead
82    */
83    @Deprecated
84    DocumentModelBridge getDocument(DocumentReference documentReference) throws Exception;
85   
86    /**
87    * Get the document object associated with the passed document.
88    *
89    * @param documentReference the reference of the document instance to find
90    * @return the document instance matching the passed document reference
91    * @throws Exception when loading the document failed
92    * @since 10.2
93    * @since 9.11.4
94    */
 
95  0 toggle default DocumentModelBridge getDocumentInstance(DocumentReference documentReference) throws Exception
96    {
97  0 return null;
98    }
99   
100    /**
101    * Get the document object associated with the passed reference.
102    *
103    * @param reference the direct or indicate reference of the document instance to find
104    * @return the document instance matching the passed reference
105    * @throws Exception when loading the document failed
106    * @since 10.6RC1
107    */
 
108  0 toggle default DocumentModelBridge getDocumentInstance(EntityReference reference) throws Exception
109    {
110  0 return null;
111    }
112   
113    /**
114    * Get the document object associated with the passed document name and context locale.
115    * <p>
116    * Note that the returned document does not contain objects and attachment so it should be used very carefully.
117    *
118    * @param documentReference the reference of the document instance to find
119    * @return the document instance matching the passed document reference and context locale
120    * @throws Exception when loading the document failed
121    * @since 10.2
122    * @since 9.11.4
123    */
 
124  0 toggle default DocumentModelBridge getTranslatedDocumentInstance(DocumentReference documentReference) throws Exception
125    {
126  0 return getDocument(documentReference);
127    }
128   
129    /**
130    * Get the document object associated with the passed entity reference and context locale.
131    * <p>
132    * Note that the returned document does not contain objects and attachment so it should be used very carefully.
133    *
134    * @param entityReference the reference of the entity instance to find
135    * @return the document instance matching the passed document reference and context locale
136    * @throws Exception when loading the document failed
137    * @since 10.6RC1
138    */
 
139  0 toggle default DocumentModelBridge getTranslatedDocumentInstance(EntityReference entityReference) throws Exception
140    {
141  0 return getTranslatedDocumentInstance(new DocumentReference(entityReference));
142    }
143   
144    /**
145    * Get the reference to the current document (found in the Context).
146    *
147    * @return the reference to the current document
148    * @since 2.2M1
149    */
150    DocumentReference getCurrentDocumentReference();
151   
152    /**
153    * Check if a document exists or not in the wiki.
154    *
155    * @param documentReference The reference of the document to check.
156    * @return <code>true</code> if the document already exists, <code>false</code> otherwise.
157    * @since 2.2.1
158    */
159    boolean exists(DocumentReference documentReference);
160   
161    /**
162    * Check if a document exists or not in the wiki.
163    *
164    * @param documentReference The reference of the document to check.
165    * @return <code>true</code> if the document already exists, <code>false</code> otherwise.
166    * @deprecated replaced by {@link #exists(DocumentReference)} since 2.2.1
167    */
168    @Deprecated
169    boolean exists(String documentReference);
170   
171    /**
172    * Updates the target document with the new content provided. If the target document does not exists, a new one will
173    * be created.
174    *
175    * @param documentReference the reference to the target document
176    * @param content Content to be set.
177    * @param editComment Comment describing this particular change.
178    * @param isMinorEdit Flag indicating if this change is a minor one.
179    * @throws Exception if the storage cannot be accessed.
180    * @since 2.2.1
181    */
182    void setDocumentContent(DocumentReference documentReference, String content, String editComment,
183    boolean isMinorEdit) throws Exception;
184   
185    /**
186    * Updates the target document with the new content provided. If the target document does not exists, a new one will
187    * be created.
188    *
189    * @param documentReference the reference to the target document
190    * @param content Content to be set.
191    * @param editComment Comment describing this particular change.
192    * @param isMinorEdit Flag indicating if this change is a minor one.
193    * @throws Exception if the storage cannot be accessed.
194    * @deprecated replaced by {@link #setDocumentContent(DocumentReference, String, String, boolean)} since 2.2.1
195    */
196    @Deprecated
197    void setDocumentContent(String documentReference, String content, String editComment, boolean isMinorEdit)
198    throws Exception;
199   
200    /**
201    * Retrieves the textual content of the document, in the current language.
202    *
203    * @param documentReference the reference of the document to access
204    * @return The document's content.
205    * @throws Exception If the document cannot be accessed.
206    * @deprecated replaced by {@link #getDocument(DocumentReference)} and {@link DocumentModelBridge#getContent()}
207    * since 2.2.1
208    */
209    @Deprecated
210    String getDocumentContent(String documentReference) throws Exception;
211   
212    /**
213    * Get the syntax Id of the target document. If the target document does not exists, the default syntax of a new
214    * document is returned.
215    *
216    * @param documentReference the reference of the target document
217    * @return the syntax id.
218    * @throws Exception If the storage cannot be accessed.
219    * @deprecated replaced by {@link #getDocument(DocumentReference)} and {@link DocumentModelBridge#getSyntaxId()}
220    * since 2.2.1
221    */
222    @Deprecated
223    String getDocumentSyntaxId(String documentReference) throws Exception;
224   
225    /**
226    * Changes the syntax Id of the target document to the given syntaxId. If the target document does not exists, a new
227    * one will be created.
228    *
229    * @param documentReference the reference of the target document
230    * @param syntaxId New syntax Id.
231    * @throws Exception If the storage cannot be accessed.
232    * @since 2.2.1
233    */
234    void setDocumentSyntaxId(DocumentReference documentReference, String syntaxId) throws Exception;
235   
236    /**
237    * Changes the syntax Id of the target document to the given syntaxId. If the target document does not exists, a new
238    * one will be created.
239    *
240    * @param documentReference the reference of the target document
241    * @param syntaxId New syntax Id.
242    * @throws Exception If the storage cannot be accessed.
243    * @deprecated replaced by {@link #setDocumentSyntaxId(DocumentReference, String)} since 2.2.1
244    */
245    @Deprecated
246    void setDocumentSyntaxId(String documentReference, String syntaxId) throws Exception;
247   
248    /**
249    * Sets the parent document name attribute for this document.
250    *
251    * @param documentReference the reference of the target document
252    * @param parentReference name of the parent document.
253    * @throws Exception If the storage cannot be accessed.
254    * @since 2.2
255    */
256    void setDocumentParentReference(DocumentReference documentReference, DocumentReference parentReference)
257    throws Exception;
258   
259    /**
260    * Sets the title of this document.
261    *
262    * @param documentReference the reference of the target document
263    * @param title the title to be set.
264    * @throws Exception If the storage cannot be accessed.
265    * @since 2.2
266    */
267    void setDocumentTitle(DocumentReference documentReference, String title) throws Exception;
268   
269    /**
270    * Retrieves the textual content of the document, in the document's default language.
271    * <p>
272    * Note: you should always use {@link #getDocumentContent(String)} unless you really need specifically the
273    * document's content for default language of the document.
274    *
275    * @param documentReference the reference of the document to access
276    * @return The document's content.
277    * @throws Exception If the document cannot be accessed.
278    * @since 2.2.1
279    */
280    String getDocumentContentForDefaultLanguage(DocumentReference documentReference) throws Exception;
281   
282    /**
283    * Retrieves the textual content of the document, in the document's default language.
284    * <p>
285    * Note: you should always use {@link #getDocumentContent(String)} unless you really need specifically the
286    * document's content for default language of the document.
287    *
288    * @param documentReference the reference of the document to access
289    * @return The document's content.
290    * @throws Exception If the document cannot be accessed.
291    * @deprecated replaced by {@link #getDocumentContentForDefaultLanguage(DocumentReference)} since 2.2.1
292    */
293    @Deprecated
294    String getDocumentContentForDefaultLanguage(String documentReference) throws Exception;
295   
296    /**
297    * Retrieves the textual content of the document, in the given language.
298    *
299    * @param documentReference the referenc of the document to access
300    * @param language The desired translation of the document.
301    * @return The document's content.
302    * @throws Exception If the document cannot be accessed.
303    * @since 2.2.1
304    */
305    String getDocumentContent(DocumentReference documentReference, String language) throws Exception;
306   
307    /**
308    * Retrieves the textual content of the document, in the given language.
309    *
310    * @param documentReference the referenc of the document to access
311    * @param language The desired translation of the document.
312    * @return The document's content.
313    * @throws Exception If the document cannot be accessed.
314    * @deprecated replaced by {@link #getDocumentContent(DocumentReference, String)} since 2.2.1
315    */
316    @Deprecated
317    String getDocumentContent(String documentReference, String language) throws Exception;
318   
319    /**
320    * Get the number of the first object that has a property that match the expectation.
321    *
322    * @param documentReference the reference of the document to look for objects into
323    * @param classReference the reference of the class to look objects of
324    * @param parameterName the name of the parameter to check the value for
325    * @param valueToMatch the value to match for this parameter
326    * @return the number of the first matching object, or -1 if none found
327    */
328    int getObjectNumber(DocumentReference documentReference, DocumentReference classReference, String parameterName,
329    String valueToMatch);
330   
331    /**
332    * Retrieves the value for an object property.
333    *
334    * @param documentReference the reference of the document to access
335    * @param className The name of the class.
336    * @param objectNumber The number of the object from the given class.
337    * @param propertyName The name of the property to retrieve.
338    * @return the property value or null if it doesn't exist or an error occurred while looking for the property (the
339    * document doesn't exist for example)
340    */
341    Object getProperty(String documentReference, String className, int objectNumber, String propertyName);
342   
343    /**
344    * Retrieves the value for an object property, from the first object of the given class.
345    *
346    * @param documentReference the reference of the document to access
347    * @param className The name of the class.
348    * @param propertyName The name of the property to retrieve.
349    * @return the property value or null if it doesn't exist or an error occurred while looking for the property (the
350    * document doesn't exist for example)
351    * @deprecated since 2.2M1 use {@link #getProperty(DocumentReference, DocumentReference, String)} instead
352    */
353    @Deprecated
354    Object getProperty(String documentReference, String className, String propertyName);
355   
356    /**
357    * Retrieves the value for an object property.
358    *
359    * @param objectReference the reference of the object to access
360    * @param propertyName The name of the property to retrieve.
361    * @return the property value or null if it doesn't exist or an error occurred while looking for the property (the
362    * document doesn't exist for example)
363    * @since 3.2M3
364    */
365    Object getProperty(ObjectReference objectReference, String propertyName);
366   
367    /**
368    * Retrieves the value for an object property.
369    *
370    * @param objectPropertyReference the reference of the property to access
371    * @return the property value or null if it doesn't exist or an error occurred while looking for the property (the
372    * document doesn't exist for example)
373    * @since 3.2M3
374    */
375    Object getProperty(ObjectPropertyReference objectPropertyReference);
376   
377    /**
378    * Retrieves the value for an object property, from the first object of the given class.
379    *
380    * @param documentReference the reference of the document to access
381    * @param classReference the reference to the XWiki Class
382    * @param propertyName The name of the property to retrieve.
383    * @return the property value or null if it doesn't exist or an error occurred while looking for the property (the
384    * document doesn't exist for example)
385    * @since 2.2M1
386    */
387    Object getProperty(DocumentReference documentReference, DocumentReference classReference, String propertyName);
388   
389    /**
390    * Retrieves the value for an object property, from the Nth object of the given class.
391    *
392    * @param documentReference the reference of the document to access
393    * @param classReference the reference to the XWiki Class
394    * @param objectNumber the number of the object to get the property for
395    * @param propertyName The name of the property to retrieve.
396    * @return the property value or null if it doesn't exist or an error occurred while looking for the property (the
397    * document doesn't exist for example)
398    * @since 3.2M3
399    */
400    Object getProperty(DocumentReference documentReference, DocumentReference classReference, int objectNumber,
401    String propertyName);
402   
403    /**
404    * Retrieves the value for an object property, from the first object of any class that has a property with that
405    * name.
406    *
407    * @param documentReference the reference of the document to access
408    * @param propertyName The name of the property to retrieve.
409    * @return the property value or null if it doesn't exist or an error occurred while looking for the property (the
410    * document doesn't exist for example)
411    */
412    Object getProperty(String documentReference, String propertyName);
413   
414    /**
415    * @param documentReference the reference of the document to access
416    * @param className the name of the class in the passed document from which to get the properties
417    * @return the list of properties available in the passed document and class names
418    */
419    List<Object> getProperties(String documentReference, String className);
420   
421    /**
422    * @param className The name of the class.
423    * @param propertyName The name of the property.
424    * @return class name of the property object or null if property is not found. For example StringProperty,
425    * IntegerProperty.
426    * @throws Exception if class cannot be accessed
427    */
428    String getPropertyType(String className, String propertyName) throws Exception;
429   
430    /**
431    * @param className The name of the class.
432    * @param propertyName The name of the property of the class.
433    * @return is the property stored in a special custom mapped class.
434    * @throws Exception if class cannot be accessed
435    */
436    boolean isPropertyCustomMapped(String className, String propertyName) throws Exception;
437   
438    /**
439    * Sets the given property of the first object (of the given class) attached to the document. If no such object
440    * exists, this method will create a new object of the given class, attach it to the document and set the property.
441    *
442    * @param documentReference the reference of the document to access
443    * @param className name of the class.
444    * @param propertyName name of the property to set.
445    * @param propertyValue value of the property to set.
446    * @throws Exception if the document cannot be accessed.
447    * @deprecated use {@link DocumentAccessBridge#setProperty(DocumentReference, DocumentReference, String, Object)}
448    */
449    @Deprecated
450    void setProperty(String documentReference, String className, String propertyName, Object propertyValue)
451    throws Exception;
452   
453    /**
454    * Sets the given property of the first object (of the given class) attached to the document. If no such object
455    * exists, this method will create a new object of the given class, attach it to the document and set the property.
456    *
457    * @param documentReference the reference of the document to access
458    * @param classReference the reference of the class.
459    * @param propertyName name of the property to set.
460    * @param propertyValue value of the property to set.
461    * @throws Exception if the document cannot be accessed.
462    */
463    void setProperty(DocumentReference documentReference, DocumentReference classReference, String propertyName,
464    Object propertyValue) throws Exception;
465   
466    /**
467    * Returns the content of a document attachment.
468    *
469    * @param documentReference the reference of the document to access
470    * @param attachmentName The filename of the attachment to access.
471    * @return The content of the attachment, as an array of <code>byte</code>s, which is empty if the attachment does
472    * not exist.
473    * @throws Exception If the document cannot be accessed.
474    * @deprecated use {@link #getAttachmentContent(org.xwiki.model.reference.AttachmentReference)} instead
475    */
476    @Deprecated
477    byte[] getAttachmentContent(String documentReference, String attachmentName) throws Exception;
478   
479    /**
480    * Returns the content of a document attachment.
481    *
482    * @param attachmentReference the name of the attachment to access
483    * @return The content of the attachment as an input stream
484    * @throws Exception If the document cannot be accessed.
485    * @since 2.2M1
486    */
487    InputStream getAttachmentContent(AttachmentReference attachmentReference) throws Exception;
488   
489    /**
490    * Sets the content of a document attachment. If the document or the attachment does not exist, both will be created
491    * newly.
492    *
493    * @param attachmentReference the name of the attachment to access
494    * @param attachmentData Attachment content.
495    * @throws Exception If the storage cannot be accessed.
496    * @since 2.2.1
497    */
498    void setAttachmentContent(AttachmentReference attachmentReference, byte[] attachmentData) throws Exception;
499   
500    /**
501    * Sets the content of a document attachment. If the document or the attachment does not exist, both will be created
502    * newly.
503    *
504    * @param documentReference the reference to the target document name
505    * @param attachmentFilename the name of the attachment
506    * @param attachmentData Attachment content.
507    * @throws Exception If the storage cannot be accessed.
508    * @deprecated replaced by {@link #setAttachmentContent(AttachmentReference, byte[])} since 2.2.1
509    */
510    @Deprecated
511    void setAttachmentContent(String documentReference, String attachmentFilename, byte[] attachmentData)
512    throws Exception;
513   
514    /**
515    * Returns the current version of a document attachment.
516    *
517    * @param attachmentReference identifies the attachment to access
518    * @return the current version of the specified attachment, {@code null} if the attachment does not exist
519    * @throws Exception if the document cannot be accessed
520    * @since 2.5M2
521    */
522    String getAttachmentVersion(AttachmentReference attachmentReference) throws Exception;
523   
524    /**
525    * Retrieves the internal (without the hostname) URL that can be used to access a document, using a specific action.
526    *
527    * @param documentReference the reference of the document to access
528    * @param action The "mode" in which the document is accessed, for example <code>view</code> to view the document,
529    * <code>edit</code> to open the document for modifications, etc.
530    * @param queryString An optional query string to append to the URL, use <code>null</code> or an empty string to
531    * skip.
532    * @param anchor An optional URL fragment to append to the URL, use <code>null</code> or an empty string to skip.
533    * @return A <code>String</code> representation of the URL, starting with the path segment of the URL (without
534    * protocol, host and port), for example <code>/xwiki/bin/save/Main/WebHome?content=abc</code>.
535    * @since 2.2.1
536    */
537    String getDocumentURL(DocumentReference documentReference, String action, String queryString, String anchor);
538   
539    /**
540    * Retrieves the internal (without the hostname) URL that can be used to access a document, using a specific action.
541    *
542    * @param entityReference the reference of the entity to access
543    * @param action The "mode" in which the document is accessed, for example <code>view</code> to view the document,
544    * <code>edit</code> to open the document for modifications, etc.
545    * @param queryString An optional query string to append to the URL, use <code>null</code> or an empty string to
546    * skip.
547    * @param anchor An optional URL fragment to append to the URL, use <code>null</code> or an empty string to skip.
548    * @return A <code>String</code> representation of the URL, starting with the path segment of the URL (without
549    * protocol, host and port), for example <code>/xwiki/bin/save/Main/WebHome?content=abc</code>.
550    * @since 10.6RC1
551    */
 
552  0 toggle default String getDocumentURL(EntityReference entityReference, String action, String queryString, String anchor)
553    {
554  0 return getDocumentURL(entityReference, action, queryString, anchor, false);
555    }
556   
557    /**
558    * Retrieves the relative (without the hostname) or absolute (with the hostname) URL that can be used to access a
559    * document, using a specific action.
560    *
561    * @param documentReference the reference of the document to access
562    * @param action The "mode" in which the document is accessed, for example <code>view</code> to view the document,
563    * <code>edit</code> to open the document for modifications, etc.
564    * @param queryString An optional query string to append to the URL, use <code>null</code> or an empty string to
565    * skip.
566    * @param anchor An optional URL fragment to append to the URL, use <code>null</code> or an empty string to skip.
567    * @param isFullURL if true then the URL will be an absolute URL which contains the host name, and protocol.
568    * @return A <code>String</code> representation of the URL, starting with the path segment of the URL (without
569    * protocol, host and port), for example <code>/xwiki/bin/save/Main/WebHome?content=abc</code>.
570    * @since 2.5M1
571    */
572    String getDocumentURL(DocumentReference documentReference, String action, String queryString, String anchor,
573    boolean isFullURL);
574   
575    /**
576    * Retrieves the relative (without the hostname) or absolute (with the hostname) URL that can be used to access a
577    * document, using a specific action.
578    *
579    * @param entityReference the reference of the entity to access
580    * @param action The "mode" in which the document is accessed, for example <code>view</code> to view the document,
581    * <code>edit</code> to open the document for modifications, etc.
582    * @param queryString An optional query string to append to the URL, use <code>null</code> or an empty string to
583    * skip.
584    * @param anchor An optional URL fragment to append to the URL, use <code>null</code> or an empty string to skip.
585    * @param isFullURL if true then the URL will be an absolute URL which contains the host name, and protocol.
586    * @return A <code>String</code> representation of the URL, starting with the path segment of the URL (without
587    * protocol, host and port), for example <code>/xwiki/bin/save/Main/WebHome?content=abc</code>.
588    * @since 10.6RC1
589    */
 
590  0 toggle default String getDocumentURL(EntityReference entityReference, String action, String queryString, String anchor,
591    boolean isFullURL)
592    {
593  0 return getDocumentURL(entityReference.extractReference(EntityType.DOCUMENT), action, queryString, anchor,
594    isFullURL);
595    }
596   
597    /**
598    * Retrieves the internal (without the hostname) URL that can be used to access a document, using a specific action.
599    *
600    * @param documentReference the reference of the document to access
601    * @param action The "mode" in which the document is accessed, for example <code>view</code> to view the document,
602    * <code>edit</code> to open the document for modifications, etc.
603    * @param queryString An optional query string to append to the URL, use <code>null</code> or an empty string to
604    * skip.
605    * @param anchor An optional URL fragment to append to the URL, use <code>null</code> or an empty string to skip.
606    * @return A <code>String</code> representation of the URL, starting with the path segment of the URL (without
607    * protocol, host and port), for example <code>/xwiki/bin/save/Main/WebHome?content=abc</code>.
608    * @deprecated replaced by {@link #getDocumentURL(DocumentReference, String, String, String)} since 2.2.1
609    */
610    @Deprecated
611    String getURL(String documentReference, String action, String queryString, String anchor);
612   
613    /**
614    * Retrieves all attachments in the passed document.
615    *
616    * @param documentReference the reference to the document for which to retrieve all attachment references
617    * @return the list of attachment names in the passed document
618    * @throws Exception in case of a storage issue finding all attachments for the document matching the passed name
619    * @since 2.2M1
620    */
621    List<AttachmentReference> getAttachmentReferences(DocumentReference documentReference) throws Exception;
622   
623    /**
624    * Retrieves the relative URL (ie the path without the hostname and port) that can be used to access an attachment.
625    *
626    * @param documentReference the reference to the document containing the attachment (eg "wiki:Space.Page")
627    * @param attachmentFilename the attachment name (eg "my.png")
628    * @return the attachment URL
629    * @deprecated use {@link #getAttachmentURL(org.xwiki.model.reference.AttachmentReference , boolean)} instead
630    */
631    @Deprecated
632    String getAttachmentURL(String documentReference, String attachmentFilename);
633   
634    /**
635    * Retrieves the URL (either relative ie the path without the hostname and port, or the full URL) that can be used
636    * to access an attachment.
637    *
638    * @param attachmentReference the attachment name for which to find the URL
639    * @param isFullURL whether the returned URL will a relative URL or the full URL
640    * @return the attachment URL
641    * @since 2.2M1
642    */
643    String getAttachmentURL(AttachmentReference attachmentReference, boolean isFullURL);
644   
645    /**
646    * Retrieves the URL (either relative ie the path without the hostname and port, or the full URL) that can be used
647    * to access an attachment.
648    *
649    * @param attachmentReference the attachment name for which to find the URL
650    * @param queryString An optional query string to append to the URL, use <code>null</code> or an empty string to
651    * skip.
652    * @param isFullURL whether the returned URL will a relative URL or the full URL
653    * @return the attachment URL
654    * @since 2.5RC1
655    */
656    String getAttachmentURL(AttachmentReference attachmentReference, String queryString, boolean isFullURL);
657   
658    /**
659    * @param documentReference the document for which to retrieve all attachment URLs
660    * @param isFullURL whether the returned URL will a relative URL or the full URL
661    * @return the list of attachment URLs (either relative ie the path without the hostname and port, or the full URL)
662    * for all attachments in the passed document
663    * @throws Exception in case of a storage issue finding all attachments for the document matching the passed name
664    * @deprecated use {@link #getAttachmentReferences(org.xwiki.model.reference.DocumentReference)} instead
665    * @since 2.2M1
666    */
667    @Deprecated
668    List<String> getAttachmentURLs(DocumentReference documentReference, boolean isFullURL) throws Exception;
669   
670    /**
671    * @param documentReference the reference of the document to access
672    * @return true if current user can view provided document.
673    * @since 2.2.1
674    * @deprecated since 6.1, use
675    * {@link org.xwiki.security.authorization.ContextualAuthorizationManager#checkAccess(org.xwiki.security.authorization.Right, org.xwiki.model.reference.EntityReference)}
676    * with {@link org.xwiki.security.authorization.Right#VIEW} instead
677    */
678    @Deprecated
679    boolean isDocumentViewable(DocumentReference documentReference);
680   
681    /**
682    * @param documentReference the reference of the document to access
683    * @return true if current user can view provided document.
684    * @deprecated use {@link #isDocumentViewable(org.xwiki.model.reference.DocumentReference)} instead
685    */
686    @Deprecated
687    boolean isDocumentViewable(String documentReference);
688   
689    /**
690    * @param documentReference the reference of the document to be edited
691    * @return True if current user has 'edit' access on the target document.
692    * @deprecated use {@link #isDocumentEditable(org.xwiki.model.reference.DocumentReference)} instead
693    */
694    @Deprecated
695    boolean isDocumentEditable(String documentReference);
696   
697    /**
698    * @param documentReference the name of the document to be edited.
699    * @return True if current user has 'edit' access on the target document.
700    * @since 2.2M1
701    * @deprecated since 6.1, use
702    * {@link org.xwiki.security.authorization.ContextualAuthorizationManager#checkAccess(org.xwiki.security.authorization.Right, org.xwiki.model.reference.EntityReference)}
703    * with {@link org.xwiki.security.authorization.Right#EDIT} instead
704    */
705    @Deprecated
706    boolean isDocumentEditable(DocumentReference documentReference);
707   
708    /**
709    * @return true if the current document's author has programming rights.
710    * @deprecated since 6.1RC1, use
711    * {@link org.xwiki.security.authorization.ContextualAuthorizationManager#hasAccess(org.xwiki.security.authorization.Right)}
712    * instead
713    */
714    @Deprecated
715    boolean hasProgrammingRights();
716   
717    /**
718    * Utility method to retrieve the current user.
719    *
720    * @return the current user full reference.
721    * @deprecated replaced by {@link org.xwiki.bridge.DocumentAccessBridge#getCurrentUserReference()} since 4.0RC1
722    */
723    @Deprecated
724    String getCurrentUser();
725   
726    /**
727    * Utility method to retrieve the current user document reference.
728    *
729    * @return the current user document reference.
730    * @since 4.0RC1
731    */
732    DocumentReference getCurrentUserReference();
733   
734    /**
735    * @return true if current user is an advanced user
736    * @since 9.2RC1
737    */
 
738  0 toggle default boolean isAdvancedUser()
739    {
740  0 return true;
741    }
742   
743    /**
744    * @param userReference the reference of the user
745    * @return true if passed user is an advanced user
746    * @since 9.2RC1
747    */
 
748  0 toggle default boolean isAdvancedUser(EntityReference userReference)
749    {
750  0 return true;
751    }
752   
753    /**
754    * Utility method to set the current user.
755    *
756    * @param userName the current user
757    * @since 2.4M2
758    */
759    void setCurrentUser(String userName);
760   
761    /**
762    * @return The default encoding for the current wiki.
763    */
764    String getDefaultEncoding();
765   
766    /**
767    * Sets the passed document as the current document in the XWiki Context and saves current values related to the
768    * current document into a backup object.
769    *
770    * @param backupObjects the object in which to some context properties will be saved
771    * @param documentReference the reference to the document to set as the current document
772    * @throws Exception in case of an error like a problem loading the document from the database
773    * @deprecated use {@link #pushDocumentInContext(Map, DocumentReference)} instead
774    */
775    @Deprecated
776    void pushDocumentInContext(Map<String, Object> backupObjects, String documentReference) throws Exception;
777   
778    /**
779    * Sets the passed document as the current document in the XWiki Context and saves current values related to the
780    * current document into a backup object.
781    *
782    * @param backupObjects the object in which to some context properties will be saved
783    * @param documentReference the reference to the document to set as the current document
784    * @throws Exception in case of an error like a problem loading the document from the database
785    * @since 2.2.1
786    */
787    void pushDocumentInContext(Map<String, Object> backupObjects, DocumentReference documentReference) throws Exception;
788   
789    /**
790    * Sets the passed document as the current document in the XWiki Context and saves current values related to the
791    * current document into a backup object.
792    *
793    * @param backupObjects the object in which to some context properties will be saved
794    * @param document the document to set as the current document
795    * @throws Exception in case of an error like a problem loading the document from the database
796    * @since 8.4M1
797    */
 
798  0 toggle default void pushDocumentInContext(Map<String, Object> backupObjects, DocumentModelBridge document) throws Exception
799    {
800  0 pushDocumentInContext(backupObjects, document.getDocumentReference());
801    }
802   
803    /**
804    * Restore values saved in a backup object in the XWiki Context and restore the current document with the same value
805    * before {@link #pushDocumentInContext(Map, String)} was called.
806    *
807    * @param backupObjects the object containing the backed-up context properties to restore
808    */
809    void popDocumentFromContext(Map<String, Object> backupObjects);
810   
811    /**
812    * @return the current wiki
813    * @deprecated replaced by {@link org.xwiki.model.ModelContext#getCurrentEntityReference()} since 2.2M1
814    */
815    @Deprecated
816    String getCurrentWiki();
817   
818    /**
819    * @return the author of the current document.
820    * @since 10.10RC1
821    * @since 10.8.2
822    * @since 9.11.9
823    */
 
824  0 toggle @Unstable
825    default DocumentReference getCurrentAuthorReference()
826    {
827  0 return null;
828    }
829    }