Package dw.xmlrpc

Class DokuJClient


  • public class DokuJClient
    extends java.lang.Object
    Main public class to actually make an xmlrpc query Instantiate one such client for a given wiki and a given user, then make xmlrpc query using its methods. Most methods may throw DokuException because many things can go wrong (bad url, wrong credential, no network, unreachable server, ...), so you may want to make sure you handle them correcty
    • Constructor Summary

      Constructors 
      Constructor Description
      DokuJClient​(DokuJClientConfig dokuConfig)  
      DokuJClient​(java.lang.String url)
      Instantiate a client for an anonymous user on the given wiki Likely to be unsuitable for most wiki since anonymous user are often not authorized to use the xmlrpc interface
      DokuJClient​(java.lang.String url, java.lang.String user, java.lang.String password)
      Instantiate a client for the given user on the given wiki The wiki should be configured in a way to let this user access the xmlrpc interface
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.Integer aclCheck​(java.lang.String pageId)
      Returns the permission of the given wikipage.
      boolean addAcl​(java.lang.String scope, java.lang.String username, int permission)
      Only available for dokuwiki-2013-12-08 (Binky) or newer
      void appendPage​(java.lang.String pageId, java.lang.String rawWikiText)
      Appends text to a Wiki Page.
      void appendPage​(java.lang.String pageId, java.lang.String rawWikiText, java.lang.String summary, boolean minor)
      Appends text to a Wiki Page.
      void appendPage​(java.lang.String pageId, java.lang.String rawWikiText, java.util.Map<java.lang.String,​java.lang.Object> options)
      Appends text to a Wiki Page.
      java.util.Map<java.lang.String,​java.lang.String> cookies()  
      boolean delAcl​(java.lang.String scope, java.lang.String username)
      Only available for dokuwiki-2013-12-08 (Binky) or newer
      void deleteAttachment​(java.lang.String fileId)
      Deletes a file.
      java.lang.Object genericQuery​(java.lang.String action)
      Let execute any xmlrpc query without argument
      java.lang.Object genericQuery​(java.lang.String action, java.lang.Object param)
      Let execute any xmlrpc query with one argument
      java.lang.Object genericQuery​(java.lang.String action, java.lang.Object[] params)
      Let execute any xmlrpc query with an arbitrary number of arguments
      java.util.List<Page> getAllPages()
      Returns a list of all Wiki pages in the remote Wiki
      byte[] getAttachment​(java.lang.String fileId)
      Let download a file from the wiki
      java.io.File getAttachment​(java.lang.String fileId, java.lang.String localPath)
      Let download a file from the wiki
      AttachmentInfo getAttachmentInfo​(java.lang.String fileId)
      Returns information about a media file
      java.util.List<AttachmentDetails> getAttachments​(java.lang.String namespace)
      Returns information about a list of media files in a given namespace
      java.util.List<AttachmentDetails> getAttachments​(java.lang.String namespace, java.util.Map<java.lang.String,​java.lang.Object> additionalParams)
      Returns information about a list of media files in a given namespace
      java.util.List<java.lang.String> getBackLinks​(java.lang.String pageId)
      Returns a list of backlinks of a Wiki page
      java.lang.String getPage​(java.lang.String pageId)
      Returns the raw Wiki text for a page
      java.lang.String getPageHTML​(java.lang.String pageId)
      Returns the rendered XHTML body of a Wiki page
      java.lang.String getPageHTMLVersion​(java.lang.String pageId, java.lang.Integer timestamp)
      Returns the rendered HTML of a specific version of a Wiki page
      PageInfo getPageInfo​(java.lang.String pageId)
      Returns information about a Wiki page
      PageInfo getPageInfoVersion​(java.lang.String pageId, java.lang.Integer timestamp)
      Returns information about a specific version of a Wiki page
      java.util.List<PageDW> getPagelist​(java.lang.String namespace)
      Lists all pages within a given namespace
      java.util.List<PageDW> getPagelist​(java.lang.String namespace, java.util.Map<java.lang.String,​java.lang.Object> options)
      Lists all pages within a given namespace
      java.lang.String getPageVersion​(java.lang.String pageId, java.lang.Integer timestamp)
      Returns the raw Wiki text for a specific revision of a Wiki page.
      java.util.List<PageVersion> getPageVersions​(java.lang.String pageId)
      Returns the available versions of a Wiki page.
      java.util.List<PageVersion> getPageVersions​(java.lang.String pageId, java.lang.Integer offset)
      Returns the available versions of a Wiki page.
      java.util.List<PageChange> getRecentChanges​(java.lang.Integer timestamp)
      Returns a list of recent changes since a given timestamp According to Dokuwiki documentation (https://www.dokuwiki.org/recent_changes): * Only the most recent change for each page is listed, regardless of how many times that page was changed.
      java.util.List<PageChange> getRecentChanges​(java.util.Date date)
      java.util.List<MediaChange> getRecentMediaChanges​(java.lang.Integer timestamp)
      Returns a list of recent changed media since given timestamp
      java.util.List<MediaChange> getRecentMediaChanges​(java.util.Date date)
      java.lang.Integer getRPCVersionSupported()
      Returns the supported RPC API version cf http://www.jspwiki.org/wiki/WikiRPCInterface2 for more info
      java.lang.Integer getTime()
      Returns the current time at the remote wiki server as Unix timestamp
      java.lang.String getTitle()
      Returns the title of the wiki
      java.lang.String getVersion()
      Returns the DokuWiki version of the remote Wiki
      java.lang.Integer getXMLRPCAPIVersion()
      Returns the XML RPC interface version of the remote Wiki.
      boolean hasDokuwikiCookies()  
      java.util.List<LinkInfo> listLinks​(java.lang.String pageId)
      Returns a list of all links contained in a Wiki page
      boolean lock​(java.lang.String pageId)
      Lock a page
      java.lang.Boolean login​(java.lang.String user, java.lang.String password)  
      void logoff()
      Tries to logoff by expiring auth cookies and the associated PHP session
      void putAttachment​(java.lang.String attachmentId, byte[] localFile, boolean overwrite)
      Uploads a file to the wiki
      void putAttachment​(java.lang.String attachmentId, java.io.File localFile, boolean overwrite)
      Uploads a file to the wiki
      void putAttachment​(java.lang.String attachmentId, java.lang.String localPath, boolean overwrite)
      Uploads a file to the wiki
      void putPage​(java.lang.String pageId, java.lang.String rawWikiText)
      Saves a Wiki Page
      void putPage​(java.lang.String pageId, java.lang.String rawWikiText, java.lang.String summary, boolean minor)
      Saves a Wiki Page
      void putPage​(java.lang.String pageId, java.lang.String rawWikiText, java.util.Map<java.lang.String,​java.lang.Object> options)
      Saves a Wiki Page
      java.util.List<SearchResult> search​(java.lang.String pattern)
      Performs a fulltext search
      LockResult setLocks​(java.util.List<java.lang.String> pagesToLock, java.util.List<java.lang.String> pagesToUnlock)
      Allows to lock or unlock a whole bunch of pages at once.
      void setLogger​(java.util.logging.Logger logger)
      Let override the default Logger
      boolean unlock​(java.lang.String pageId)
      Unlock a page
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • DokuJClient

        public DokuJClient​(java.lang.String url,
                           java.lang.String user,
                           java.lang.String password)
                    throws java.net.MalformedURLException,
                           DokuException
        Instantiate a client for the given user on the given wiki The wiki should be configured in a way to let this user access the xmlrpc interface
        Parameters:
        url - Should looks like http[s]://server/mywiki/lib/exe/xmlrpc.php
        user - Login of the user
        password - Password of the user
        Throws:
        java.net.MalformedURLException
        DokuException
      • DokuJClient

        public DokuJClient​(java.lang.String url)
                    throws java.net.MalformedURLException
        Instantiate a client for an anonymous user on the given wiki Likely to be unsuitable for most wiki since anonymous user are often not authorized to use the xmlrpc interface
        Parameters:
        url - Should looks like http[s]://server/mywiki/lib/exe/xmlrpc.php
        Throws:
        java.net.MalformedURLException
    • Method Detail

      • setLogger

        public void setLogger​(java.util.logging.Logger logger)
        Let override the default Logger
      • hasDokuwikiCookies

        public boolean hasDokuwikiCookies()
      • cookies

        public java.util.Map<java.lang.String,​java.lang.String> cookies()
      • login

        public java.lang.Boolean login​(java.lang.String user,
                                       java.lang.String password)
                                throws DokuException
        Throws:
        DokuException
      • putAttachment

        public void putAttachment​(java.lang.String attachmentId,
                                  java.lang.String localPath,
                                  boolean overwrite)
                           throws java.io.IOException,
                                  DokuException
        Uploads a file to the wiki
        Parameters:
        attachmentId - Id the file should have once uploaded (eg: ns1:ns2:myfile.gif)
        localPath - The path to the file to upload
        overwrite - TRUE to overwrite if a file with this id already exist on the wiki
        Throws:
        java.io.IOException
        DokuException
      • putAttachment

        public void putAttachment​(java.lang.String attachmentId,
                                  java.io.File localFile,
                                  boolean overwrite)
                           throws java.io.IOException,
                                  DokuException
        Uploads a file to the wiki
        Parameters:
        attachmentId - Id the file should have once uploaded (eg: ns1:ns2:myfile.gif)
        localFile - The file to upload
        overwrite - TRUE to overwrite if a file with this id already exist on the wiki
        Throws:
        java.io.IOException
        DokuException
      • putAttachment

        public void putAttachment​(java.lang.String attachmentId,
                                  byte[] localFile,
                                  boolean overwrite)
                           throws DokuException
        Uploads a file to the wiki
        Parameters:
        attachmentId - Id the file should have once uploaded (eg: ns1:ns2:myfile.gif)
        localFile - base64 encoded file
        overwrite - TRUE to overwrite if a file with this id already exist on the wiki
        Throws:
        java.io.IOException
        DokuException
      • getAttachmentInfo

        public AttachmentInfo getAttachmentInfo​(java.lang.String fileId)
                                         throws DokuException
        Returns information about a media file
        Parameters:
        fileId - Id of the file on the wiki (eg: ns1:ns2:myfile.gif)
        Throws:
        DokuException
      • deleteAttachment

        public void deleteAttachment​(java.lang.String fileId)
                              throws DokuException
        Deletes a file. Fails if the file is still referenced from any page in the wiki.
        Parameters:
        fileId - Id of the file on the wiki (eg: ns1:ns2:myfile.gif)
        Throws:
        DokuException
      • getAttachment

        public java.io.File getAttachment​(java.lang.String fileId,
                                          java.lang.String localPath)
                                   throws DokuException,
                                          java.io.IOException
        Let download a file from the wiki
        Parameters:
        fileId - Id of the file on the wiki (eg: ns1:ns2:myfile.gif)
        localPath - Where to put the file
        Throws:
        DokuException
        java.io.IOException
      • getAttachment

        public byte[] getAttachment​(java.lang.String fileId)
                             throws DokuException
        Let download a file from the wiki
        Parameters:
        fileId - Id of the file on the wiki (eg: ns1:ns2:myfile.gif)
        Returns:
        the data of the file, encoded in base64
        Throws:
        DokuException
      • getAttachments

        public java.util.List<AttachmentDetails> getAttachments​(java.lang.String namespace)
                                                         throws DokuException
        Returns information about a list of media files in a given namespace
        Parameters:
        namespace - Where to look for files
        Throws:
        DokuException
      • getAttachments

        public java.util.List<AttachmentDetails> getAttachments​(java.lang.String namespace,
                                                                java.util.Map<java.lang.String,​java.lang.Object> additionalParams)
                                                         throws DokuException
        Returns information about a list of media files in a given namespace
        Parameters:
        namespace - Where to look for files
        additionalParams - Potential additional parameters directly sent to Dokuwiki. Available parameters are: * recursive: TRUE if also files in subnamespaces are to be included, defaults to FALSE * pattern: an optional PREG compatible regex which has to match the file id
        Throws:
        DokuException
      • getRecentMediaChanges

        public java.util.List<MediaChange> getRecentMediaChanges​(java.lang.Integer timestamp)
                                                          throws DokuException
        Returns a list of recent changed media since given timestamp
        Parameters:
        timestamp -
        Throws:
        DokuException
      • getTime

        public java.lang.Integer getTime()
                                  throws DokuException
        Returns the current time at the remote wiki server as Unix timestamp
        Throws:
        DokuException
      • getXMLRPCAPIVersion

        public java.lang.Integer getXMLRPCAPIVersion()
                                              throws DokuException
        Returns the XML RPC interface version of the remote Wiki. This is DokuWiki implementation specific and independent of the supported standard API version returned by wiki.getRPCVersionSupported
        Throws:
        DokuException
      • getVersion

        public java.lang.String getVersion()
                                    throws DokuException
        Returns the DokuWiki version of the remote Wiki
        Throws:
        DokuException
      • getPageVersions

        public java.util.List<PageVersion> getPageVersions​(java.lang.String pageId)
                                                    throws DokuException
        Returns the available versions of a Wiki page. The number of pages in the result is controlled via the "recent" configuration setting of the wiki.
        Parameters:
        pageId - Id of the page (eg: ns1:ns2:mypage)
        Throws:
        DokuException
      • getPageVersions

        public java.util.List<PageVersion> getPageVersions​(java.lang.String pageId,
                                                           java.lang.Integer offset)
                                                    throws DokuException
        Returns the available versions of a Wiki page. The number of pages in the result is controlled via the recent configuration setting of the wiki.
        Parameters:
        pageId - Id of the page (eg: ns1:ns2:mypage)
        offset - Can be used to list earlier versions in the history.
        Throws:
        DokuException
      • getPageVersion

        public java.lang.String getPageVersion​(java.lang.String pageId,
                                               java.lang.Integer timestamp)
                                        throws DokuException
        Returns the raw Wiki text for a specific revision of a Wiki page.
        Parameters:
        pageId - Id of the page (eg: ns1:ns2:mypage)
        timestamp - Version of the page
        Throws:
        DokuException
      • getPagelist

        public java.util.List<PageDW> getPagelist​(java.lang.String namespace)
                                           throws DokuException
        Lists all pages within a given namespace
        Parameters:
        namespace - Namespace to look for (eg: ns1:ns2)
        Throws:
        DokuException
      • getPagelist

        public java.util.List<PageDW> getPagelist​(java.lang.String namespace,
                                                  java.util.Map<java.lang.String,​java.lang.Object> options)
                                           throws DokuException
        Lists all pages within a given namespace
        Parameters:
        namespace - Namespace to look for (eg: ns1:ns2)
        options - Options passed directly to dokuwiki's search_all_pages()
        Throws:
        DokuException
      • aclCheck

        public java.lang.Integer aclCheck​(java.lang.String pageId)
                                   throws DokuException
        Returns the permission of the given wikipage.
        Parameters:
        pageId - Id of the page (eg: ns1:ns2:mypage)
        Throws:
        DokuException
      • getRPCVersionSupported

        public java.lang.Integer getRPCVersionSupported()
                                                 throws DokuException
        Returns the supported RPC API version cf http://www.jspwiki.org/wiki/WikiRPCInterface2 for more info
        Throws:
        DokuException
      • setLocks

        public LockResult setLocks​(java.util.List<java.lang.String> pagesToLock,
                                   java.util.List<java.lang.String> pagesToUnlock)
                            throws DokuException
        Allows to lock or unlock a whole bunch of pages at once. Useful when you are about to do a operation over multiple pages
        Parameters:
        pagesToLock - Ids of pages to lock
        pagesToUnlock - Ids of pages to unlock
        Throws:
        DokuException
      • lock

        public boolean lock​(java.lang.String pageId)
                     throws DokuException
        Lock a page
        Parameters:
        pageId - Id of the page to lock (eg: ns1:ns2:mypage)
        Returns:
        TRUE the page has been successfully locked, FALSE otherwise
        Throws:
        DokuException
      • unlock

        public boolean unlock​(java.lang.String pageId)
                       throws DokuException
        Unlock a page
        Parameters:
        pageId - Id of the page to unlock (eg: ns1:ns2:mypage)
        Returns:
        TRUE the page has been successfully unlocked, FALSE otherwise
        Throws:
        DokuException
      • appendPage

        public void appendPage​(java.lang.String pageId,
                               java.lang.String rawWikiText)
                        throws DokuException
        Appends text to a Wiki Page.
        Parameters:
        pageId - Id of the page to edit (eg: ns1:ns2:mypage)
        rawWikiText - Text to add to the current page content
        Throws:
        DokuException
      • appendPage

        public void appendPage​(java.lang.String pageId,
                               java.lang.String rawWikiText,
                               java.lang.String summary,
                               boolean minor)
                        throws DokuException
        Appends text to a Wiki Page.
        Parameters:
        pageId - Id of the page to edit (eg: ns1:ns2:mypage)
        rawWikiText - Text to add to the current page content
        summary - A summary of the modification
        minor - Whether it's a minor modification
        Throws:
        DokuException
      • appendPage

        public void appendPage​(java.lang.String pageId,
                               java.lang.String rawWikiText,
                               java.util.Map<java.lang.String,​java.lang.Object> options)
                        throws DokuException
        Appends text to a Wiki Page.
        Parameters:
        pageId - Id of the page to edit (eg: ns1:ns2:mypage)
        rawWikiText - Text to add to the current page content
        options - Options passed to Dokuwiki. ie: 'sum' and/or 'minor'
        Throws:
        DokuException
      • getPage

        public java.lang.String getPage​(java.lang.String pageId)
                                 throws DokuException
        Returns the raw Wiki text for a page
        Parameters:
        pageId - Id of the page to fetch (eg: ns1:ns2:mypage)
        Throws:
        DokuException
      • putPage

        public void putPage​(java.lang.String pageId,
                            java.lang.String rawWikiText)
                     throws DokuException
        Saves a Wiki Page
        Parameters:
        pageId - Id of the page to save
        rawWikiText - Text to put
        Throws:
        DokuException
      • putPage

        public void putPage​(java.lang.String pageId,
                            java.lang.String rawWikiText,
                            java.lang.String summary,
                            boolean minor)
                     throws DokuException
        Saves a Wiki Page
        Parameters:
        pageId - Id of the page to save
        rawWikiText - Text to put
        summary - Summary of the edition
        minor - Whether it's a minor edition
        Throws:
        DokuException
      • putPage

        public void putPage​(java.lang.String pageId,
                            java.lang.String rawWikiText,
                            java.util.Map<java.lang.String,​java.lang.Object> options)
                     throws DokuException
        Saves a Wiki Page
        Parameters:
        pageId - Id of the page to save
        rawWikiText - Text to put
        options - Options passed to Dokuwiki. ie: 'sum' and/or 'minor' * @throws DokuException
        Throws:
        DokuException
      • search

        public java.util.List<SearchResult> search​(java.lang.String pattern)
                                            throws DokuException
        Performs a fulltext search
        Parameters:
        pattern - A query string as described on https://www.dokuwiki.org/search
        Returns:
        Matching pages. Snippets are provided for the first 15 results.
        Throws:
        DokuException
      • getPageInfo

        public PageInfo getPageInfo​(java.lang.String pageId)
                             throws DokuException
        Returns information about a Wiki page
        Parameters:
        pageId - Id of the page wanted (eg: ns1:ns2:mypage)
        Throws:
        DokuException
      • getPageInfoVersion

        public PageInfo getPageInfoVersion​(java.lang.String pageId,
                                           java.lang.Integer timestamp)
                                    throws DokuException
        Returns information about a specific version of a Wiki page
        Parameters:
        pageId - Id of the page wanted(eg: ns1:ns2:mypage)
        timestamp - version wanted
        Throws:
        DokuException
      • getAllPages

        public java.util.List<Page> getAllPages()
                                         throws DokuException
        Returns a list of all Wiki pages in the remote Wiki
        Throws:
        DokuException
      • getBackLinks

        public java.util.List<java.lang.String> getBackLinks​(java.lang.String pageId)
                                                      throws DokuException
        Returns a list of backlinks of a Wiki page
        Parameters:
        pageId - Id of the page wanted (eg: ns1:ns2:mypage)
        Throws:
        DokuException
      • getPageHTML

        public java.lang.String getPageHTML​(java.lang.String pageId)
                                     throws DokuException
        Returns the rendered XHTML body of a Wiki page
        Parameters:
        pageId - Id of the wanted page (eg: ns1:ns2:mypage)
        Throws:
        DokuException
      • getPageHTMLVersion

        public java.lang.String getPageHTMLVersion​(java.lang.String pageId,
                                                   java.lang.Integer timestamp)
                                            throws DokuException
        Returns the rendered HTML of a specific version of a Wiki page
        Parameters:
        pageId - Id of the wanted page (eg: ns1:ns2:mypage)
        timestamp - Version wanted
        Throws:
        DokuException
      • listLinks

        public java.util.List<LinkInfo> listLinks​(java.lang.String pageId)
                                           throws DokuException
        Returns a list of all links contained in a Wiki page
        Parameters:
        pageId - Id of the wanted page (eg: ns1:ns2:mypage)
        Throws:
        DokuException
      • getRecentChanges

        public java.util.List<PageChange> getRecentChanges​(java.lang.Integer timestamp)
                                                    throws DokuException
        Returns a list of recent changes since a given timestamp According to Dokuwiki documentation (https://www.dokuwiki.org/recent_changes): * Only the most recent change for each page is listed, regardless of how many times that page was changed. * The number of changes shown per page is controlled by the "recent" setting. * Users are only shown pages to which they have read access
        Parameters:
        timestamp - Do not return changes older than this timestamp
        Throws:
        DokuException
      • logoff

        public void logoff()
                    throws DokuException
        Tries to logoff by expiring auth cookies and the associated PHP session
        Throws:
        DokuException
      • addAcl

        public boolean addAcl​(java.lang.String scope,
                              java.lang.String username,
                              int permission)
                       throws DokuException
        Only available for dokuwiki-2013-12-08 (Binky) or newer
        Throws:
        DokuException
      • delAcl

        public boolean delAcl​(java.lang.String scope,
                              java.lang.String username)
                       throws DokuException
        Only available for dokuwiki-2013-12-08 (Binky) or newer
        Throws:
        DokuException
      • genericQuery

        public java.lang.Object genericQuery​(java.lang.String action)
                                      throws DokuException
        Let execute any xmlrpc query without argument
        Parameters:
        action - The name of the xmlrpc method to invoke
        Returns:
        Whatever the xmlrpc should return, as an Object
        Throws:
        DokuException
      • genericQuery

        public java.lang.Object genericQuery​(java.lang.String action,
                                             java.lang.Object param)
                                      throws DokuException
        Let execute any xmlrpc query with one argument
        Parameters:
        action - The name of the xmlrpc method to invoke
        param - The unique parameter, as an Object
        Returns:
        Whatever the xmlrpc should return, as an Object
        Throws:
        DokuException
      • genericQuery

        public java.lang.Object genericQuery​(java.lang.String action,
                                             java.lang.Object[] params)
                                      throws DokuException
        Let execute any xmlrpc query with an arbitrary number of arguments
        Parameters:
        action - The name of the xmlrpc method to invoke
        params - The parameters, as an array of Objects
        Returns:
        Whatever the xmlrpc should return, as an Object
        Throws:
        DokuException