{"id":21387161,"url":"https://github.com/sshtools/vfs2nio","last_synced_at":"2025-09-25T15:15:20.888Z","repository":{"id":49222156,"uuid":"145483178","full_name":"sshtools/vfs2nio","owner":"sshtools","description":"Library that bridges Commons VFS 2 to Java's NIO.2 virtual file system","archived":false,"fork":false,"pushed_at":"2022-06-16T15:26:55.000Z","size":41,"stargazers_count":15,"open_issues_count":5,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-07-13T15:43:09.610Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sshtools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-08-21T00:07:31.000Z","updated_at":"2025-04-05T08:06:54.000Z","dependencies_parsed_at":"2022-08-25T20:51:46.489Z","dependency_job_id":null,"html_url":"https://github.com/sshtools/vfs2nio","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sshtools/vfs2nio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshtools%2Fvfs2nio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshtools%2Fvfs2nio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshtools%2Fvfs2nio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshtools%2Fvfs2nio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sshtools","download_url":"https://codeload.github.com/sshtools/vfs2nio/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshtools%2Fvfs2nio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276937605,"owners_count":25731714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-25T02:00:09.612Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-22T12:12:01.242Z","updated_at":"2025-09-25T15:15:20.862Z","avatar_url":"https://github.com/sshtools.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vfs2nio\n\nProvides a bridge between the [JSR 203](https://jcp.org/en/jsr/detail?id=203) ([The Java NIO.2 File System in JDK 7](http://www.oracle.com/technetwork/articles/javase/nio-139333.html)) and [Apache's Commons VFS 2](https://commons.apache.org/proper/commons-vfs/). This allows you to use the standard\nJava API with all [file systems](https://commons.apache.org/proper/commons-vfs/filesystems.html) in Commons VFS, and any 3rd party\nadd-ons that implement the Commons VFS API. This includes :-\n\n### Default File Systems\n * [Bzip2](https://commons.apache.org/proper/commons-vfs/filesystems.html#gzip_and_bzip2)\n * [File](https://commons.apache.org/proper/commons-vfs/filesystems.html#Local_Files)\n * [FTP](https://commons.apache.org/proper/commons-vfs/filesystems.html#FTP)\n * [FTPS](https://commons.apache.org/proper/commons-vfs/filesystems.html#FTPS)\n * [GZip](https://commons.apache.org/proper/commons-vfs/filesystems.html#gzip_and_bzip2)\n * [HDFS](https://commons.apache.org/proper/commons-vfs/filesystems.html#HDFS)\n * [HTTP](https://commons.apache.org/proper/commons-vfs/filesystems.html#HTTP_and_HTTPS)\n * [Jar](https://commons.apache.org/proper/commons-vfs/filesystems.html#Zip_Jar_and_Tar)\n * [RAM](https://commons.apache.org/proper/commons-vfs/filesystems.html#ram)\n * [Res](https://commons.apache.org/proper/commons-vfs/filesystems.html#res)\n * [SFTP](https://commons.apache.org/proper/commons-vfs/filesystems.html#SFTP)\n * [Tar](https://commons.apache.org/proper/commons-vfs/filesystems.html#Zip_Jar_and_Tar)\n * [Temp](https://commons.apache.org/proper/commons-vfs/filesystems.html#Temporary_Fils)\n * [WebDAV](https://commons.apache.org/proper/commons-vfs/WebDAV)\n * [Zip](https://commons.apache.org/proper/commons-vfs/filesystems.html#Zip_Jar_and_Tar)\n\n### Require Commons VFS Sandbox Library\n * [CIFS](https://commons.apache.org/proper/commons-vfs/filesystems.html#CIFS)\n * [mime](https://commons.apache.org/proper/commons-vfs/filesystems.html#mime)\n \n### SSHTools Provided\n * [Azure](https://github.com/sshtools/vfs)\n * [AFP](https://github.com/sshtools/vfs) (Prototype)\n * [Dropbox](https://github.com/sshtools/vfs)\n * [GCS](https://github.com/sshtools/vfs)\n * [GoogleDrive](https://github.com/sshtools/vfs)\n * [NFS](https://github.com/sshtools/vfs) (Prototype)\n * [RFBFTP](https://github.com/sshtools/vfs)\n * [S3](https://github.com/sshtools/vfs)\n * [SFTP](https://www.sshtools.com/en/products/java-ssh-client/) (Maverick 1.6 provider)\n * [SFTP](https://github.com/sshtools/sshapi) (SSHAPI version with multiple SSH providers)\n * [WebDAV](https://github.com/sshtools/vfs)\n \nDifferent providers may have different requirements, but in general, it is just a case of including an additional library into your project configuration. See below for more information.\n\n\n## Configuring Your Project\n\nThis library is provided on Maven Central, so if you are using Maven, all you need to do is add this to your POM.\n\n```\n\t...\n\t\t\u003cdependency\u003e\n\t\t\t\u003cgroupId\u003ecom.sshtools\u003c/groupId\u003e\n\t\t\t\u003cartifactId\u003evfs2nio\u003c/artifactId\u003e\n\t\t\t\u003cversion\u003e0.9.0-SNAPSHOT-SNAPSHOT\u003c/version\u003e\n\t\t\u003c/dependency\u003e\n\t...\n```\n\nAdjust for this use with other project systems such as Ivy, Gradle etc, or download directly from the [SSHTools](http://mvnrepository.com/artifact/com.sshtools) group.\n\nThis will get you support for the built-in file systems provided by Commons VFS that do not require addtional libraries.\nThis includes file systems such as *file*, *ram*, *temp*, *jar, *res*.\n\n_For any other file systems you will always need this library, plus all of the others you would have to use if you were using Commons VFS directly._\n\n### Additional Official File Systems\n\nTo get access to the officially supported Commons VFS providers, you may need to add additional libraries.\n\n```\n\t...\n\t\t\u003cdependency\u003e\n\t\t\t\u003cgroupId\u003ecom.sshtools\u003c/groupId\u003e\n\t\t\t\u003cartifactId\u003evfs2nio\u003c/artifactId\u003e\n           \u003cversion\u003e0.9.0-SNAPSHOT\u003c/version\u003e\n\t\t\u003c/dependency\u003e\n\t\t\u003cdependency\u003e\n    \t\t\u003cgroupId\u003eorg.apache.commons\u003c/groupId\u003e\n    \t\t\u003cartifactId\u003ecommons-compress\u003c/artifactId\u003e\n    \t\t\u003cversion\u003e1.18\u003c/version\u003e\n\t\t\u003c/dependency\u003e\n\t...\n\n```\n\nWill add support for *gzip*, *bzip*, *tar*, *zip*. See Commons VFS documentation for exactly what libraries are needed for what file systems. \n\n### Third Party Libraries\n\nFor some filesystems, you may need additional 3rd party libraries. For example, for Dropbox support, you would need to add \nthe SSHTools VFS libraries :-\n\n```\n\t\t\u003cdependency\u003e\n\t\t\t\u003cgroupId\u003ecom.sshtools\u003c/groupId\u003e\n\t\t\t\u003cartifactId\u003evfs2nio\u003c/artifactId\u003e\n\t\t\t\u003cversion\u003e0.9.0-SNAPSHOT\u003c/version\u003e\n\t\t\u003c/dependency\u003e\n\t\t\u003cdependency\u003e\n\t\t\t\u003cgroupId\u003ecom.sshtools\u003c/groupId\u003e\n\t\t\t\u003cartifactId\u003evfs-dropbox\u003c/artifactId\u003e\n\t\t\t\u003cversion\u003e3.0.0\u003c/version\u003e\n\t\t\u003c/dependency\u003e\n```\n\nWith this added, you would get support for a URI in the format `vfs:dropbox://`.\n\nAnother slightly more complex example would be using the 'Maverick' library, accessing it's SFTP support via SSHAPI's commons VFS library. You need to exclude the _jSch_ library to prevent Commons VFS seeing this and using it over the SSHAPI provider, so it\nis probably a good idea to add an exclusion (note, this isn't strictly required at the moment but may be in the future).\n\n```\n\t\t\u003cdependency\u003e\n\t\t\t\u003cgroupId\u003ecom.sshtools\u003c/groupId\u003e\n\t\t\t\u003cartifactId\u003evfs2nio\u003c/artifactId\u003e\n           \u003cversion\u003e0.9.0-SNAPSHOT\u003c/version\u003e\n\t\t\t\u003cexclusions\u003e\n\t\t        \u003cexclusion\u003e\n\t\t\t\t    \u003cgroupId\u003ecom.jcraft\u003c/groupId\u003e\n\t\t\t\t    \u003cartifactId\u003ejsch\u003c/artifactId\u003e\n\t\t        \u003c/exclusion\u003e\n\t\t    \u003c/exclusions\u003e\n\t\t\u003c/dependency\u003e\n\t\t\u003cdependency\u003e\n\t\t\t\u003cgroupId\u003ecom.sshtools\u003c/groupId\u003e\n\t\t\t\u003cartifactId\u003esshapi-commons-vfs\u003c/artifactId\u003e\n\t\t\t\u003cversion\u003e1.1.2\u003c/version\u003e\n\t\t\u003c/dependency\u003e\n\t\t\u003cdependency\u003e\n\t\t\t\u003cgroupId\u003ecom.sshtools\u003c/groupId\u003e\n\t\t\t\u003cartifactId\u003esshapi-maverick-16\u003c/artifactId\u003e\n\t\t\t\u003cversion\u003e1.1.2\u003c/version\u003e\n\t\t\u003c/dependency\u003e\n```\n\nWith this added, you would get support for a URI in the format `vfs:sftp://user:password@host/path`. \n\n \n##Example 1 - Create A Directory\n\nCreate a new directory at the root of the file system.\n\n```\n        try (var fs = FileSystems.newFileSystem(URI.create(vfsUri), opts)) {\n            Files.createDirectory(fs.getPath(\"mydir1\"));\n        }\n```\n \n##Example 2 - List Directory\n\nThe following would list all of the root directories on an SFTP server (if you have SFTP provider installed).\n \n```\ntry (var fs = FileSystems.newFileSystem(URI.create(\"vfs:sftp://myuser:mypassword@myserver/\"), new HashMap\u003c\u003e())) {\n    for (var root : fs.getRootDirectories()) {\n        System.out.println(root);\n        try (var dir = Files.newDirectoryStream(root)) {\n            for (var path : dir) {\n                System.out.println(\"  \" + path);\n            }\n        }\n    }\n}\n```\n\n##Example 3 - Writing Files\n\nThe following will create a file in the root of the VFS URI and fill it with some content.\n \n```\ntry (var fs = FileSystems.newFileSystem(URI.create(\"vfs:sftp://myuser:mypassword@myserver/\"), new HashMap\u003c\u003e())) {\n    try (var out = Files.newBufferedWriter(fs.getPath(\"myfile.txt\"))) {\n        var wrt = new PrintWriter(out, true);\n        wrt.println(\"My test content\");\n        wrt.println(\"Another line\");\n        wrt.println(\"The end\");\n    }\n}\n```\n\n##Example 4 - Reading Files\n\nThe following will reads the file created in the previous example and displays it back to `sysout`.\n \n```\ntry (var fs = FileSystems.newFileSystem(URI.create(\"vfs:sftp://myuser:mypassword@myserver/\"), new HashMap\u003c\u003e())) {\n    try (var in = Files.newBufferedReader(fs.getPath(\"myfile.txt\"))) {\n        String line;\n        while( ( line = in.readLine() ) != null) {\n            System.out.println(line);\n        }\n    }\n}\n```\n\n##Example 5 - Copying Files\n\nThe following will copy the file created in Example 2 to another file.\n \n```\ntry (var fs = FileSystems.newFileSystem(URI.create(\"vfs:sftp://myuser:mypassword@myserver/\"), new HashMap\u003c\u003e())) {\n    Files.copy(fs.getPath(\"myfile.txt\"), fs.getPath(\"myfilecopy.txt\"));\n}\n```\n\n##TODO Example 6 - File Attributes\n\n##TODO Example 7 - File Attributes\n\n##TODO Example 8- Deleting Files\n\n##TODO Example 9 - Renaming Files\n\n## Authentication\n\nThere are 3 different techniques that may be used if the virtual file system requires authentication.\n\nIf the username is not supplied, the system property `user.name` will be queried for the default. If the password is not supplied, is will be interactively asked for in the `Console`, if the `Console` is available. \n\n### 1. Encoding The User Information And Password In The URI\n\nThe username and password are provided as URL encoded text into the URI itself when you create the file system. The syntax is ..\n\n```\nvfs:\u003cvfsScheme\u003e://\u003cusername\u003e[:\u003cpassword\u003e]/.......\n```\n\nBoth the username and password must be [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding). \n\nThe `\u003cusername\u003e` may further encode the *Domain Name* (if the underlying VFS requires it). In this case, the syntax of `\u003cusername\u003e` is ..\n\n```\n    \u003cusername\u003e[@\u003cdomain\u003e]\n```\n\n.. or ..\n\n```\n    [\u003cdomain\u003e\\]\u003cusername\u003e\n```\n\n### 2. Providing User Information As File System Options \n\n\n\n```\n    var opts = new HashMap\u003cString, Object\u003e();\n    opts.put(Vfs2NioFileSystemProvider.DOMAIN, \"mycompany\"); // Optional\n    opts.put(Vfs2NioFileSystemProvider.USERNAME, \"myuser\"); // Defaults to user.name\n    opts.put(Vfs2NioFileSystemProvider.PASSWORD, \"mypassword\"); // May be a String or char[] \n    var fs = FileSystems.newFileSystem(URI.create(\"vfs:sftp://myserver/\"), opts);\n```\n\n\n### 3. Providing A org.apache.commons.vfs2.UserAuthenticator\n\nCommons VFS's native authentication mechanism is the `UserAuthenticator`. You may provide a class that implements this interface, and pass that to a NIO.2 file system via the `HashMap` argument of `FileSystems.newFileSystem()`. The option should have a key of `com.sshtools.vfs2nio.vfsAuthenticator` (or the constant  `Vfs2NioFileSystemProvider.AUTHENTICATOR`) and the value should be an instance of a `UserAuthenticator`. See the [Commons VFS documentation](https://commons.apache.org/proper/commons-vfs/api.html) for further information.\n\nIn this case, the root URI's user information is ignored, as are the other file system options described in Example 2 above. \n\nUse this technique if you want to interactively provide authentication details, e.g. in a GUI.\n\n```\n    var opts = new HashMap\u003cString, Object\u003e();\n    opts.put(Vfs2NioFileSystemProvider.AUTHENTICATOR, myAuthenticatorInstance); \n    var fs = FileSystems.newFileSystem(URI.create(\"vfs:sftp://myserver/\"), opts);\n```\n\n## FileSystemOptions\n\nCommons VFS uses `FileSystemOptions` to configure scheme specific options for the various file systems.\nPass an instance of this class as a file system option with the key `com.sshtools.vfs2nio.fileSystemOptions` (or use the constant `Vfs2NioFileSystemProvider.FILE_SYSTEM_OPTIONS`).\n\nFor example, to configure use of private key for authentication with an SFTP file system.\n\n```\n    var opts = new HashMap\u003cString, Object\u003e();\n    var fsOpts = new FileSystemOptions();\n    SftpFileSystemConfigBuilder.getInstance().setIdentities(fsOptions, new File[] { new File(\"/path/to/private/key\"); });\n    opts.put(Vfs2NioFileSystemProvider.FILE_SYSTEM_OPTIONS, fsOpts)\n    var fs = FileSystems.newFileSystem(URI.create(\"vfs:sftp://myserver/\"), opts);\n```\n\n## FileSystemManager\n\nIt is also possible to extend Commons VFS's `FileSystemManager` for your needs, and pass this as a file system option. Pass an instance of this class as a file system option with the key `com.sshtools.vfs2nio.vfsManager` (or use the constant `Vfs2NioFileSystemProvider.VFS_MANAGER`).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsshtools%2Fvfs2nio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsshtools%2Fvfs2nio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsshtools%2Fvfs2nio/lists"}