VFS API

Last modified by Admin on 2017/10/16 00:08

cogAccess content of archives (Zip, Tar, Jar, GZip, etc)
TypeJAR
CategoryAPI
Developed by

XWiki Development Team

Active Installs2
Rating
Rate!
0 Votes
LicenseGNU Lesser General Public License 2.1
Installable with the Extension Manager

Description

This API replaces the Zip Explorer Plugin. It's both more generic and uses the XWiki Component Architecture.

See also the VFS Tree Macro.

API

  • Generate an XWiki URL for accessing the content of a file located inside an archive attached to a wiki page. Examples:

    From Velocity:

    {{velocity}}
    ## Get the URL to access the content of a file inside a zip:
    [[link to file in zip>>path:$services.vfs.url("attach:[email protected]/test.txt")]]

    ## Display inline an image from a zip attached to a wiki page:
    [[image:path:$services.vfs.url("attach:[email protected]/test.png")||width="100px"]]
    {{/velocity}}

    From Java:

    import org.xwiki.vfs.*;

    @Inject
    private VfsManager vfsManager;
    ...
    vfsManager.getURL(new VfsResourceReference(URI.create("attach:wiki:[email protected]"), "path/to/file"));
  • Access any supported VFS through the NIO2 API. See also the NIO Tool. Examples:

    From Velocity:

    {{velocity}}
    ## Read the content of a file inside a zip attached to a page:
    Content of test.txt inside test.zip:
    {{{
    $stringtool.toString($niotool.readAllBytes("attach:[email protected]/test.txt"), "utf-8")
    }}}

    ## List all entries inside a zip attached to a page:
    Content of test.zip:
    #set ($dirStream = $niotool.newDirectoryStream("attach:[email protected]/"))
    #foreach ($entry in $dirStream)
      * {{{$entry}}} - $niotool.isDirectory($entry)
    #end
    {{/velocity}}

When executed the previous Velocity examples give:

vfsapi.png

Security

Prior to version 7.4.6, 8.3 and 8.4RC1, there was an issue with authorization.
  • When accessing a VFS resource from an attached file from Velocity, permissions are checked in the converter used to convert a String into a NIO2 Path object. Thus if the current user doesn't have the View permission on the document on which the resource is attached to, then no code is executed.
  • This check is not performed from the Java API and it's thus the duty of the Java code writer to perform any check required. However, a helper component is provided to check permissions and generate a Path instance at the same time. Example (from Groovy):
    {{groovy}}
    import org.xwiki.vfs.*
    import java.nio.file.*

    def factory = services.component.getInstance(VfsPathFactory.class)
    def path = factory.create(URI.create("attach:[email protected]/"))
    def ds = Files.newDirectoryStream(path)
    ds.each() {
      println "* ${it.getFileName().toString()}"
    }
    {{/groovy}}

Architecture

architecture-vfs.jpg

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.


This extension must be installed on the Farm or it won't work (the VFS Type Resolver need to be found in the Root Extension Manager).

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-vfs-api 9.8.1):

  • org.xwiki.platform:xwiki-platform-resource-api 9.8.1
  • org.xwiki.platform:xwiki-platform-url-api 9.8.1
  • org.xwiki.platform:xwiki-platform-oldcore 9.8.1
  • org.xwiki.commons:xwiki-commons-script 9.8.1
  • net.java.truevfs:truevfs-access 0.11.0
  • net.java.truevfs:truevfs-driver-jar 0.11.0
  • net.java.truevfs:truevfs-driver-zip 0.11.0
  • net.java.truevfs:truevfs-kernel-impl 0.11.0
  • net.java.truecommons:truecommons-key-default 2.5.0
  • net.java.truevfs:truevfs-driver-http 0.11.0
  • net.java.truevfs:truevfs-driver-odf 0.11.0
  • net.java.truevfs:truevfs-driver-tar 0.11.0
  • net.java.truevfs:truevfs-driver-tar-bzip2 0.11.0
  • net.java.truevfs:truevfs-driver-tar-gzip 0.11.0
  • net.java.truevfs:truevfs-driver-tar-xz 0.11.0
  • net.java.truevfs:truevfs-driver-zip-raes 0.11.0
  • net.java.truecommons:truecommons-key-macosx 2.5.0
Tags:
Created by Vincent Massol on 2015/12/15 17:18
    

Get Connected