Interface DocumentAccessBridge


  • @Role
    public interface DocumentAccessBridge
    Exposes methods for accessing Document data. This is temporary until we remodel the Model classes and the Document services.
    Since:
    1.6M1
    Version:
    $Id: 62adfd6ec7610d6e59326aace9679f2ed8bb5723 $
    • Method Detail

      • getDocumentReference

        default DocumentReference getDocumentReference​(EntityReference entityReference)
        Find the document reference corresponding to the entity reference based on what exist in the database (page reference can means two different documents for example).
        Parameters:
        entityReference - the reference to resolve
        Returns:
        the document reference
        Since:
        10.6RC1
      • getDocument

        @Deprecated
        DocumentModelBridge getDocument​(String documentReference)
                                 throws Exception
        Get the document object associated with the passed document name and context language.

        Note that the returned document does not contain objects and attachment so it should be used very carefully.

        Parameters:
        documentReference - the String reference of the document to find
        Returns:
        the document object matching the passed document name
        Throws:
        Exception - when the storage cannot be accessed
      • getDocument

        @Deprecated
        DocumentModelBridge getDocument​(DocumentReference documentReference)
                                 throws Exception
        Deprecated.
        deprecated since 10.2RC1, use getTranslatedDocumentInstance(DocumentReference) instead
        Get the document object associated with the passed document name and context language.

        Note that the returned document does not contain objects and attachment so it should be used very carefully.

        Parameters:
        documentReference - the name of the document to find
        Returns:
        the document object matching the passed document name
        Throws:
        Exception - when the storage cannot be accessed
        Since:
        2.2M1
      • getDocumentInstance

        default DocumentModelBridge getDocumentInstance​(DocumentReference documentReference)
                                                 throws Exception
        Get the document object associated with the passed document.
        Parameters:
        documentReference - the reference of the document instance to find
        Returns:
        the document instance matching the passed document reference
        Throws:
        Exception - when loading the document failed
        Since:
        10.2, 9.11.4
      • getDocumentInstance

        default DocumentModelBridge getDocumentInstance​(EntityReference reference)
                                                 throws Exception
        Get the document object associated with the passed reference.
        Parameters:
        reference - the direct or indicate reference of the document instance to find
        Returns:
        the document instance matching the passed reference
        Throws:
        Exception - when loading the document failed
        Since:
        10.6RC1
      • getTranslatedDocumentInstance

        default DocumentModelBridge getTranslatedDocumentInstance​(DocumentReference documentReference)
                                                           throws Exception
        Get the document object associated with the passed document name and context locale.

        Note that the returned document does not contain objects and attachments (unless it's the default version) so it should be used very carefully.

        Parameters:
        documentReference - the reference of the document instance to find
        Returns:
        the document instance matching the passed document reference and context locale
        Throws:
        Exception - when loading the document failed
        Since:
        10.2, 9.11.4
      • getTranslatedDocumentInstance

        default DocumentModelBridge getTranslatedDocumentInstance​(DocumentModelBridge documentReference)
                                                           throws Exception
        Get the document object associated with the passed document and context locale.

        Note that the returned document does not contain objects and attachments (unless it's the default version) so it should be used very carefully.

        Parameters:
        documentReference - the reference of the document instance to find
        Returns:
        the document instance matching the passed document reference and context locale
        Throws:
        Exception - when loading the document failed
        Since:
        11.8RC1
      • getTranslatedDocumentInstance

        default DocumentModelBridge getTranslatedDocumentInstance​(EntityReference entityReference)
                                                           throws Exception
        Get the document object associated with the passed entity reference and context locale.

        Note that the returned document does not contain objects and attachments (unless it's the default version) so it should be used very carefully.

        Parameters:
        entityReference - the reference of the entity instance to find
        Returns:
        the document instance matching the passed document reference and context locale
        Throws:
        Exception - when loading the document failed
        Since:
        10.6RC1
      • getCurrentDocumentReference

        DocumentReference getCurrentDocumentReference()
        Get the reference to the current document (found in the Context).
        Returns:
        the reference to the current document
        Since:
        2.2M1
      • exists

        boolean exists​(DocumentReference documentReference)
                throws Exception
        Check if a document exists or not in the wiki.

        Since 14.9, if the check fail an exception is thrown.

        Parameters:
        documentReference - The reference of the document to check.
        Returns:
        true if the document already exists, false otherwise.
        Throws:
        Exception - when failing to check document existence
        Since:
        2.2.1
      • exists

        @Deprecated
        boolean exists​(String documentReference)
                throws Exception
        Deprecated.
        replaced by exists(DocumentReference) since 2.2.1
        Check if a document exists or not in the wiki.

        Since 14.9, if the check fail an exception is thrown.

        Parameters:
        documentReference - The reference of the document to check.
        Returns:
        true if the document already exists, false otherwise.
        Throws:
        Exception - when failing to check document existence
      • setDocumentContent

        void setDocumentContent​(DocumentReference documentReference,
                                String content,
                                String editComment,
                                boolean isMinorEdit)
                         throws Exception
        Updates the target document with the new content provided. If the target document does not exists, a new one will be created.
        Parameters:
        documentReference - the reference to the target document
        content - Content to be set.
        editComment - Comment describing this particular change.
        isMinorEdit - Flag indicating if this change is a minor one.
        Throws:
        Exception - if the storage cannot be accessed.
        Since:
        2.2.1
      • setDocumentContent

        @Deprecated
        void setDocumentContent​(String documentReference,
                                String content,
                                String editComment,
                                boolean isMinorEdit)
                         throws Exception
        Updates the target document with the new content provided. If the target document does not exists, a new one will be created.
        Parameters:
        documentReference - the reference to the target document
        content - Content to be set.
        editComment - Comment describing this particular change.
        isMinorEdit - Flag indicating if this change is a minor one.
        Throws:
        Exception - if the storage cannot be accessed.
      • setDocumentSyntaxId

        void setDocumentSyntaxId​(DocumentReference documentReference,
                                 String syntaxId)
                          throws Exception
        Changes the syntax Id of the target document to the given syntaxId. If the target document does not exists, a new one will be created.
        Parameters:
        documentReference - the reference of the target document
        syntaxId - New syntax Id.
        Throws:
        Exception - If the storage cannot be accessed.
        Since:
        2.2.1
      • setDocumentSyntaxId

        @Deprecated
        void setDocumentSyntaxId​(String documentReference,
                                 String syntaxId)
                          throws Exception
        Deprecated.
        Changes the syntax Id of the target document to the given syntaxId. If the target document does not exists, a new one will be created.
        Parameters:
        documentReference - the reference of the target document
        syntaxId - New syntax Id.
        Throws:
        Exception - If the storage cannot be accessed.
      • setDocumentParentReference

        void setDocumentParentReference​(DocumentReference documentReference,
                                        DocumentReference parentReference)
                                 throws Exception
        Sets the parent document name attribute for this document.
        Parameters:
        documentReference - the reference of the target document
        parentReference - name of the parent document.
        Throws:
        Exception - If the storage cannot be accessed.
        Since:
        2.2
      • setDocumentTitle

        void setDocumentTitle​(DocumentReference documentReference,
                              String title)
                       throws Exception
        Sets the title of this document.
        Parameters:
        documentReference - the reference of the target document
        title - the title to be set.
        Throws:
        Exception - If the storage cannot be accessed.
        Since:
        2.2
      • getDocumentContentForDefaultLanguage

        String getDocumentContentForDefaultLanguage​(DocumentReference documentReference)
                                             throws Exception
        Retrieves the textual content of the document, in the document's default language.

        Note: you should always use getDocumentContent(String) unless you really need specifically the document's content for default language of the document.

        Parameters:
        documentReference - the reference of the document to access
        Returns:
        The document's content.
        Throws:
        Exception - If the document cannot be accessed.
        Since:
        2.2.1
      • getDocumentContentForDefaultLanguage

        @Deprecated
        String getDocumentContentForDefaultLanguage​(String documentReference)
                                             throws Exception
        Deprecated.
        Retrieves the textual content of the document, in the document's default language.

        Note: you should always use getDocumentContent(String) unless you really need specifically the document's content for default language of the document.

        Parameters:
        documentReference - the reference of the document to access
        Returns:
        The document's content.
        Throws:
        Exception - If the document cannot be accessed.
      • getDocumentContent

        String getDocumentContent​(DocumentReference documentReference,
                                  String language)
                           throws Exception
        Retrieves the textual content of the document, in the given language.
        Parameters:
        documentReference - the referenc of the document to access
        language - The desired translation of the document.
        Returns:
        The document's content.
        Throws:
        Exception - If the document cannot be accessed.
        Since:
        2.2.1
      • getDocumentContent

        @Deprecated
        String getDocumentContent​(String documentReference,
                                  String language)
                           throws Exception
        Deprecated.
        Retrieves the textual content of the document, in the given language.
        Parameters:
        documentReference - the referenc of the document to access
        language - The desired translation of the document.
        Returns:
        The document's content.
        Throws:
        Exception - If the document cannot be accessed.
      • getObjectNumber

        int getObjectNumber​(DocumentReference documentReference,
                            DocumentReference classReference,
                            String parameterName,
                            String valueToMatch)
        Get the number of the first object that has a property that match the expectation.
        Parameters:
        documentReference - the reference of the document to look for objects into
        classReference - the reference of the class to look objects of
        parameterName - the name of the parameter to check the value for
        valueToMatch - the value to match for this parameter
        Returns:
        the number of the first matching object, or -1 if none found
      • getProperty

        Object getProperty​(String documentReference,
                           String className,
                           int objectNumber,
                           String propertyName)
        Retrieves the value for an object property.
        Parameters:
        documentReference - the reference of the document to access
        className - The name of the class.
        objectNumber - The number of the object from the given class.
        propertyName - The name of the property to retrieve.
        Returns:
        the property value or null if it doesn't exist or an error occurred while looking for the property (the document doesn't exist for example)
      • getProperty

        @Deprecated
        Object getProperty​(String documentReference,
                           String className,
                           String propertyName)
        Retrieves the value for an object property, from the first object of the given class.
        Parameters:
        documentReference - the reference of the document to access
        className - The name of the class.
        propertyName - The name of the property to retrieve.
        Returns:
        the property value or null if it doesn't exist or an error occurred while looking for the property (the document doesn't exist for example)
      • getProperty

        Object getProperty​(ObjectReference objectReference,
                           String propertyName)
        Retrieves the value for an object property.
        Parameters:
        objectReference - the reference of the object to access
        propertyName - The name of the property to retrieve.
        Returns:
        the property value or null if it doesn't exist or an error occurred while looking for the property (the document doesn't exist for example)
        Since:
        3.2M3
      • getProperty

        Object getProperty​(ObjectPropertyReference objectPropertyReference)
        Retrieves the value for an object property.
        Parameters:
        objectPropertyReference - the reference of the property to access
        Returns:
        the property value or null if it doesn't exist or an error occurred while looking for the property (the document doesn't exist for example)
        Since:
        3.2M3
      • getProperty

        Object getProperty​(DocumentReference documentReference,
                           DocumentReference classReference,
                           String propertyName)
        Retrieves the value for an object property, from the first object of the given class.
        Parameters:
        documentReference - the reference of the document to access
        classReference - the reference to the XWiki Class
        propertyName - The name of the property to retrieve.
        Returns:
        the property value or null if it doesn't exist or an error occurred while looking for the property (the document doesn't exist for example)
        Since:
        2.2M1
      • getProperty

        Object getProperty​(DocumentReference documentReference,
                           DocumentReference classReference,
                           int objectNumber,
                           String propertyName)
        Retrieves the value for an object property, from the Nth object of the given class.
        Parameters:
        documentReference - the reference of the document to access
        classReference - the reference to the XWiki Class
        objectNumber - the number of the object to get the property for
        propertyName - The name of the property to retrieve.
        Returns:
        the property value or null if it doesn't exist or an error occurred while looking for the property (the document doesn't exist for example)
        Since:
        3.2M3
      • getProperty

        Object getProperty​(String documentReference,
                           String propertyName)
        Retrieves the value for an object property, from the first object of any class that has a property with that name.
        Parameters:
        documentReference - the reference of the document to access
        propertyName - The name of the property to retrieve.
        Returns:
        the property value or null if it doesn't exist or an error occurred while looking for the property (the document doesn't exist for example)
      • getProperties

        List<Object> getProperties​(String documentReference,
                                   String className)
        Parameters:
        documentReference - the reference of the document to access
        className - the name of the class in the passed document from which to get the properties
        Returns:
        the list of properties available in the passed document and class names
      • getPropertyType

        String getPropertyType​(String className,
                               String propertyName)
                        throws Exception
        Parameters:
        className - The name of the class.
        propertyName - The name of the property.
        Returns:
        class name of the property object or null if property is not found. For example StringProperty, IntegerProperty.
        Throws:
        Exception - if class cannot be accessed
      • isPropertyCustomMapped

        boolean isPropertyCustomMapped​(String className,
                                       String propertyName)
                                throws Exception
        Parameters:
        className - The name of the class.
        propertyName - The name of the property of the class.
        Returns:
        is the property stored in a special custom mapped class.
        Throws:
        Exception - if class cannot be accessed
      • setProperty

        @Deprecated
        void setProperty​(String documentReference,
                         String className,
                         String propertyName,
                         Object propertyValue)
                  throws Exception
        Sets the given property of the first object (of the given class) attached to the document. If no such object exists, this method will create a new object of the given class, attach it to the document and set the property.
        Parameters:
        documentReference - the reference of the document to access
        className - name of the class.
        propertyName - name of the property to set.
        propertyValue - value of the property to set.
        Throws:
        Exception - if the document cannot be accessed.
      • setProperty

        void setProperty​(DocumentReference documentReference,
                         DocumentReference classReference,
                         String propertyName,
                         Object propertyValue)
                  throws Exception
        Sets the given property of the first object (of the given class) attached to the document. If no such object exists, this method will create a new object of the given class, attach it to the document and set the property.
        Parameters:
        documentReference - the reference of the document to access
        classReference - the reference of the class.
        propertyName - name of the property to set.
        propertyValue - value of the property to set.
        Throws:
        Exception - if the document cannot be accessed.
      • getAttachmentContent

        @Deprecated
        byte[] getAttachmentContent​(String documentReference,
                                    String attachmentName)
                             throws Exception
        Returns the content of a document attachment.
        Parameters:
        documentReference - the reference of the document to access
        attachmentName - The filename of the attachment to access.
        Returns:
        The content of the attachment, as an array of bytes, which is empty if the attachment does not exist.
        Throws:
        Exception - If the document cannot be accessed.
      • getAttachmentContent

        @Unstable
        default InputStream getAttachmentContent​(EntityReference reference)
                                          throws Exception
        Returns the content of a document attachment.
        Parameters:
        reference - the reference to the attachment to access (can be an AttachmentReference or PageAttachmentReference, or any reference containing a Document reference and an attachment name)
        Returns:
        The content of the attachment as an input stream or null if the attachment doesn't exist
        Throws:
        Exception - If the document cannot be accessed.
        Since:
        14.7RC1
      • setAttachmentContent

        void setAttachmentContent​(AttachmentReference attachmentReference,
                                  byte[] attachmentData)
                           throws Exception
        Sets the content of a document attachment. If the document or the attachment does not exist, both will be created newly.
        Parameters:
        attachmentReference - the name of the attachment to access
        attachmentData - Attachment content.
        Throws:
        Exception - If the storage cannot be accessed.
        Since:
        2.2.1
      • setAttachmentContent

        @Deprecated
        void setAttachmentContent​(String documentReference,
                                  String attachmentFilename,
                                  byte[] attachmentData)
                           throws Exception
        Deprecated.
        Sets the content of a document attachment. If the document or the attachment does not exist, both will be created newly.
        Parameters:
        documentReference - the reference to the target document name
        attachmentFilename - the name of the attachment
        attachmentData - Attachment content.
        Throws:
        Exception - If the storage cannot be accessed.
      • getAttachmentVersion

        String getAttachmentVersion​(AttachmentReference attachmentReference)
                             throws Exception
        Returns the current version of a document attachment.
        Parameters:
        attachmentReference - identifies the attachment to access
        Returns:
        the current version of the specified attachment, null if the attachment does not exist
        Throws:
        Exception - if the document cannot be accessed
        Since:
        2.5M2
      • getDocumentURL

        String getDocumentURL​(DocumentReference documentReference,
                              String action,
                              String queryString,
                              String anchor)
        Retrieves the internal (without the hostname) URL that can be used to access a document, using a specific action.
        Parameters:
        documentReference - the reference of the document to access
        action - The "mode" in which the document is accessed, for example view to view the document, edit to open the document for modifications, etc.
        queryString - An optional query string to append to the URL, use null or an empty string to skip.
        anchor - An optional URL fragment to append to the URL, use null or an empty string to skip.
        Returns:
        A String representation of the URL, starting with the path segment of the URL (without protocol, host and port), for example /xwiki/bin/save/Main/WebHome?content=abc.
        Since:
        2.2.1
      • getDocumentURL

        default String getDocumentURL​(EntityReference entityReference,
                                      String action,
                                      String queryString,
                                      String anchor)
        Retrieves the internal (without the hostname) URL that can be used to access a document, using a specific action.
        Parameters:
        entityReference - the reference of the entity to access
        action - The "mode" in which the document is accessed, for example view to view the document, edit to open the document for modifications, etc.
        queryString - An optional query string to append to the URL, use null or an empty string to skip.
        anchor - An optional URL fragment to append to the URL, use null or an empty string to skip.
        Returns:
        A String representation of the URL, starting with the path segment of the URL (without protocol, host and port), for example /xwiki/bin/save/Main/WebHome?content=abc.
        Since:
        10.6RC1
      • getDocumentURL

        String getDocumentURL​(DocumentReference documentReference,
                              String action,
                              String queryString,
                              String anchor,
                              boolean isFullURL)
        Retrieves the relative (without the hostname) or absolute (with the hostname) URL that can be used to access a document, using a specific action.
        Parameters:
        documentReference - the reference of the document to access
        action - The "mode" in which the document is accessed, for example view to view the document, edit to open the document for modifications, etc.
        queryString - An optional query string to append to the URL, use null or an empty string to skip.
        anchor - An optional URL fragment to append to the URL, use null or an empty string to skip.
        isFullURL - if true then the URL will be an absolute URL which contains the host name, and protocol.
        Returns:
        A String representation of the URL, starting with the path segment of the URL (without protocol, host and port), for example /xwiki/bin/save/Main/WebHome?content=abc.
        Since:
        2.5M1
      • getDocumentURL

        default String getDocumentURL​(EntityReference entityReference,
                                      String action,
                                      String queryString,
                                      String anchor,
                                      boolean isFullURL)
        Retrieves the relative (without the hostname) or absolute (with the hostname) URL that can be used to access a document, using a specific action.
        Parameters:
        entityReference - the reference of the entity to access
        action - The "mode" in which the document is accessed, for example view to view the document, edit to open the document for modifications, etc.
        queryString - An optional query string to append to the URL, use null or an empty string to skip.
        anchor - An optional URL fragment to append to the URL, use null or an empty string to skip.
        isFullURL - if true then the URL will be an absolute URL which contains the host name, and protocol.
        Returns:
        A String representation of the URL, starting with the path segment of the URL (without protocol, host and port), for example /xwiki/bin/save/Main/WebHome?content=abc.
        Since:
        10.6RC1
      • getURL

        @Deprecated
        String getURL​(String documentReference,
                      String action,
                      String queryString,
                      String anchor)
        Retrieves the internal (without the hostname) URL that can be used to access a document, using a specific action.
        Parameters:
        documentReference - the reference of the document to access
        action - The "mode" in which the document is accessed, for example view to view the document, edit to open the document for modifications, etc.
        queryString - An optional query string to append to the URL, use null or an empty string to skip.
        anchor - An optional URL fragment to append to the URL, use null or an empty string to skip.
        Returns:
        A String representation of the URL, starting with the path segment of the URL (without protocol, host and port), for example /xwiki/bin/save/Main/WebHome?content=abc.
      • getAttachmentReferences

        List<AttachmentReference> getAttachmentReferences​(DocumentReference documentReference)
                                                   throws Exception
        Retrieves all attachments in the passed document.
        Parameters:
        documentReference - the reference to the document for which to retrieve all attachment references
        Returns:
        the list of attachment names in the passed document
        Throws:
        Exception - in case of a storage issue finding all attachments for the document matching the passed name
        Since:
        2.2M1
      • getAttachmentURL

        @Deprecated
        String getAttachmentURL​(String documentReference,
                                String attachmentFilename)
        Retrieves the relative URL (ie the path without the hostname and port) that can be used to access an attachment.
        Parameters:
        documentReference - the reference to the document containing the attachment (eg "wiki:Space.Page")
        attachmentFilename - the attachment name (eg "my.png")
        Returns:
        the attachment URL
      • getAttachmentURL

        String getAttachmentURL​(AttachmentReference attachmentReference,
                                boolean isFullURL)
        Retrieves the URL (either relative ie the path without the hostname and port, or the full URL) that can be used to access an attachment.
        Parameters:
        attachmentReference - the attachment name for which to find the URL
        isFullURL - whether the returned URL will a relative URL or the full URL
        Returns:
        the attachment URL
        Since:
        2.2M1
      • getAttachmentURL

        String getAttachmentURL​(AttachmentReference attachmentReference,
                                String queryString,
                                boolean isFullURL)
        Retrieves the URL (either relative ie the path without the hostname and port, or the full URL) that can be used to access an attachment.
        Parameters:
        attachmentReference - the attachment name for which to find the URL
        queryString - An optional query string to append to the URL, use null or an empty string to skip.
        isFullURL - whether the returned URL will a relative URL or the full URL
        Returns:
        the attachment URL
        Since:
        2.5RC1
      • getAttachmentURLs

        @Deprecated
        List<String> getAttachmentURLs​(DocumentReference documentReference,
                                       boolean isFullURL)
                                throws Exception
        Parameters:
        documentReference - the document for which to retrieve all attachment URLs
        isFullURL - whether the returned URL will a relative URL or the full URL
        Returns:
        the list of attachment URLs (either relative ie the path without the hostname and port, or the full URL) for all attachments in the passed document
        Throws:
        Exception - in case of a storage issue finding all attachments for the document matching the passed name
        Since:
        2.2M1
      • getCurrentUserReference

        DocumentReference getCurrentUserReference()
        Utility method to retrieve the current user document reference.
        Returns:
        the current user document reference.
        Since:
        4.0RC1
      • isAdvancedUser

        default boolean isAdvancedUser()
        Returns:
        true if current user is an advanced user
        Since:
        9.2RC1
      • isAdvancedUser

        default boolean isAdvancedUser​(EntityReference userReference)
        Parameters:
        userReference - the reference of the user
        Returns:
        true if passed user is an advanced user
        Since:
        9.2RC1
      • setCurrentUser

        void setCurrentUser​(String userName)
        Utility method to set the current user.
        Parameters:
        userName - the current user
        Since:
        2.4M2
      • getDefaultEncoding

        String getDefaultEncoding()
        Returns:
        The default encoding for the current wiki.
      • pushDocumentInContext

        @Deprecated
        void pushDocumentInContext​(Map<String,​Object> backupObjects,
                                   String documentReference)
                            throws Exception
        Sets the passed document as the current document in the XWiki Context and saves current values related to the current document into a backup object.
        Parameters:
        backupObjects - the object in which to some context properties will be saved
        documentReference - the reference to the document to set as the current document
        Throws:
        Exception - in case of an error like a problem loading the document from the database
      • pushDocumentInContext

        void pushDocumentInContext​(Map<String,​Object> backupObjects,
                                   DocumentReference documentReference)
                            throws Exception
        Sets the passed document as the current document in the XWiki Context and saves current values related to the current document into a backup object.
        Parameters:
        backupObjects - the object in which to some context properties will be saved
        documentReference - the reference to the document to set as the current document
        Throws:
        Exception - in case of an error like a problem loading the document from the database
        Since:
        2.2.1
      • pushDocumentInContext

        default void pushDocumentInContext​(Map<String,​Object> backupObjects,
                                           DocumentModelBridge document)
                                    throws Exception
        Sets the passed document as the current document in the XWiki Context and saves current values related to the current document into a backup object.
        Parameters:
        backupObjects - the object in which to some context properties will be saved
        document - the document to set as the current document
        Throws:
        Exception - in case of an error like a problem loading the document from the database
        Since:
        8.4M1
      • popDocumentFromContext

        void popDocumentFromContext​(Map<String,​Object> backupObjects)
        Restore values saved in a backup object in the XWiki Context and restore the current document with the same value before pushDocumentInContext(Map, String) was called.
        Parameters:
        backupObjects - the object containing the backed-up context properties to restore
      • getCurrentAuthorReference

        default DocumentReference getCurrentAuthorReference()
        Returns:
        the author of the current document.
        Since:
        10.10RC1, 10.8.2, 9.11.9