Description

Right now the Zip Explorer feature is implemented as a plugin and is using the download action to extend the URL format. This is causing problem to support Nested Spaces.

Thus the idea is to:

• Introduce a new internal URL format for any file in a VFS Path (zip, tar, jar, http, filesystem, etc)
• Refactor it to use the new ability to register a new ResourceReferenceHandler (similar to what we do for webjars)
• Refactor the code to use Components

As a consequence we have the ability to improve the API if need be.

Use Cases

• UC1: Ability to have an XWiki URL pointing to a file inside an archive attached to a wiki page, to display its content.
• UC2: Java API + Script Service to generate the URLs from UC1 so that users never use the URL directly. We'll mention in the documentation that the URL format is subject to change.
• UC3: Java API + Script Service to list all content of a VFS FileSystem (e.g. all content in a ZIP file)
• UC4: Support zip format + ability to plug other formats in the future (extensibility)
• UC5: (Performance) Ensure that the VFS data is not re-downloaded nor re-extracted again for improved performances
• UC6: Don't throw an Exception when a VFS Path is corrupted, instead display a nice error message in the UI
• UC7: The URL format from UC1 and UC2 needs to allow navigation in that VFS FileSystem, ie if there are relative links in the VFS FileSystem (such as HTML links) they should work as is
• UC8: Address authorization so that not all VFS can be accessed by the user in the scripting API (e.g. a user shouldn't be allowed by default to access a File System VFS).

Future:

• Supports a list of known VFS formats: HTTP, FILE, JAR, ODF, SFX, TAR, TAR.BZIP2, TAR.GZIP, TAR.XZ, ZIP, ZIP.RAES (TZP), etc
• Add a {{vfsTree/}} macro to display all entries from a VFS FileSystem as a visual tree
• Add a new org.xwiki.rendering.listener.reference.ResourceReference for accessing a resource inside a VFS (e.g. "vfs:...").
• API to get content of VFS paths.
• API to create/update VFS Paths.

URL Format

Generic format for VFS Paths (added as attachment in wiki pages): .../vfs/<uri>.

Example for attachment archived attached to a wiki page: .../vfs/attach:space1.space2.page@attachment/path/inside/vfs

Specialized URL for accessing attachments archived attached to a wiki page: .../attachment/space1.space2.page@attachment/path/inside/vfs

API

## Note: first parameter is of type URI.
#set ($vfsurl = $services.vfs.url("attach:space1.space2.page@attachment", "path/inside/vfs"))
#set ($vfsurl = $services.vfs.url("http://server/path/to/vfs", "path/inside/vfs"))

## Display links to all file entries in the VFS FileSystem
## Note: first parameter is of type URI, second is Path, third is DirectoryStream.Filter. The method returns a DirectoryStream<ScriptPath>.
## ScriptPath extends Path with some methods like isDirectory().
#foreach ($path in $services.vfs.getAllPaths("attach:space1.space2.page@attachment", "some/relative/path", 'FILE'))
  * [[$path>>$services.vfs.url("attach:space1.space2.page@attachment", $path)]]
#end

## Generate a tree (this is basically what the {{vfsTree/}} macro would do.
## The call to entries() guarantees that the entries will have an order from parent to children.
{{tree}}
...
$services.vfs.getPaths("attach:space1.space2.page@attachment", "some/relative/path", (optional filter here))
...
{{/tree}}

Macro

Example:

{{vfsTree reference="attach:space1.space2.page@attachment"/}}

Implementation

• Located in xwiki-platform-vfs (in the future we could have xwiki-commons-vfs + xwiki-platform-vfs)
• Use TrueVFS. Need to figure out how to reference an attachment from the TrueVFS API. Probably by implementing a (T)FileSystemProvider with a xwikiattachment URI scheme.