Last modified by Admin on 2024/05/11 01:33

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

XWiki Development Team

Active Installs5
0 Votes
LicenseGNU Lesser General Public License 2.1

Installable with the Extension Manager


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

See also the VFS Tree Macro.


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

    From 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"]]

    From Java:

    import org.xwiki.vfs.*;

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

    From 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)

When executed the previous Velocity examples give:


Content type

Since XWiki 12.3.

It's possible to explicitly indicate the Content-Type to return with the HTTP response containing the file being the VFS API. This is done using the URL parameter contentType. The script service provide a helper to pass this value. For example:

[[link to an UTF8 encoded html file located in a zip>>path:$services.vfs.url('attach:[email protected]/test.html', 'text/html; charset=UTF-8')]]

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type for more about the format of the content type.


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):
    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()}"



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).

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 for this extension (org.xwiki.platform:xwiki-platform-vfs-api 16.3.1):

  • org.xwiki.platform:xwiki-platform-resource-api 16.3.1
  • org.xwiki.platform:xwiki-platform-url-api 16.3.1
  • org.xwiki.platform:xwiki-platform-oldcore 16.3.1
  • org.xwiki.commons:xwiki-commons-script 16.3.1
  • net.java.truevfs:truevfs-access 0.14.0
  • net.java.truevfs:truevfs-driver-jar 0.14.0
  • net.java.truevfs:truevfs-driver-zip 0.14.0
  • net.java.truecommons:truecommons-key-default 2.5.0
  • net.java.truevfs:truevfs-driver-http 0.14.0
  • net.java.truevfs:truevfs-driver-odf 0.14.0
  • net.java.truevfs:truevfs-driver-tar 0.14.0
  • net.java.truevfs:truevfs-driver-tar-bzip2 0.14.0
  • net.java.truevfs:truevfs-driver-tar-gzip 0.14.0
  • net.java.truevfs:truevfs-driver-tar-xz 0.14.0
  • net.java.truevfs:truevfs-driver-zip-raes 0.14.0
  • net.java.truecommons:truecommons-key-macosx 2.5.0
  • com.google.code.findbugs:jsr305 3.0.2
  • org.bouncycastle:bcprov-jdk18on 1.78

Get Connected