Access content of archives (Zip, Tar, Jar, GZip, etc)

Description

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:Sandbox.WebHome@test.zip/test.txt")]]
  
  ## Display inline an image from a zip attached to a wiki page:
  [[image:path:$services.vfs.url("attach:Sandbox.WebHome@test.zip/test.png")||width="100px"]]
  {{/velocity}}

  From Java:

  import org.xwiki.vfs.*;
  
  @Inject
  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:

  {{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:Sandbox.WebHome@test.zip/test.txt"), "utf-8")
  }}}
  
  ## List all entries inside a zip attached to a page:
  Content of test.zip:
  #set ($dirStream = $niotool.newDirectoryStream("attach:Sandbox.WebHome@test.zip/"))
  #foreach ($entry in $dirStream)
    * {{{$entry}}} - $niotool.isDirectory($entry)
  #end
  {{/velocity}}

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:

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

Security

• 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:VfsTest.testVfsMacro@test.zip/"))
  def ds = Files.newDirectoryStream(path)
  ds.each() {
    println "* ${it.getFileName().toString()}"
  }
  {{/groovy}}

Architecture

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.

Dependencies

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

• org.xwiki.platform:xwiki-platform-resource-api 16.9.0
• org.xwiki.platform:xwiki-platform-url-api 16.9.0
• org.xwiki.platform:xwiki-platform-oldcore 16.9.0
• org.xwiki.commons:xwiki-commons-script 16.9.0
• 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.1