Bridje VFS

Introduction

Bridje VFS can be used with maven from central repository.

    <dependencies>
        ....
        <dependency>
            <groupId>org.bridje</groupId>
            <artifactId>bridje-vfs</artifactId>
            <version>${bridje.version}</version>
        </dependency>
        ....
    </dependencies>

This pages explains the basic concepts of Bridje VFS

Bridje VFS provides a unified file tree for the framework and your application. Instead of working with physical files directly you can mount folders and class path resources into any path you whant inside the VFS tree and then others components can pull the information from there.

Bridje VFS is NOT a full file system implementation, nor is it intention to be, this API provides merly the tools to access a unified files tree that is assamble from real file system. In other words Bridje VFS is just a layer for several sources to converge into one big files and folders hierarchy. The main goal of this API is the convinient access and the flexibility of such virtual tree of files and folders.

VFiles

Virtual Files VFile are the basic entity of the API, The VFile class is similar to the java.io.File class. You can create a VFile just by specifiying the path for it.

    VFile file = new VFile("/path/to/virtual/resources");

VFiles can either be folders or files, they even may not exists, so the VFile class provides convinient methods to test all this conditions.

    VFile f = new VFile("/some/path");
    if(f.exists()) System.out.println("the file exists");
    if(f.isFile()) System.out.println("is a file");
    if(f.isDirectory()) System.out.println("is a directory");

Mounting folders and classpath resources.

The files tree that this API provides is constructed out of real file system, the mount funtionality, that all VFile objects have is the way add file hierarchies to the main tree.

    VFile file = new VFile("/path/to/virtual/resources");
    file.mount(new FileSource(new File("some/physical/resources")));

The mount method accepts a instances of the VfsSource class witch is the base interface for all file sources. Any one can implemente this interface and pass an instance to it to the mount method. Bridje VFS in particular provides two of then, the FileSource and the CpSource. Both of this sources provide access to diferent file systems.

• FileSource is used to mount standard java.io.File instances into the hierarchy.
• CpSource is used to mount classpath base resources into the hierarchy. This is resources that exists withing the classpath of the application, and can be access with a ClassLoader, as java standards dictate.

The API allows you to mount several sources into the same folder.

    VFile file = new VFile("/path/to/virtual/resources");
    file.mount(new FileSource(new File("some/physical/resources1")));
    file.mount(new FileSource(new File("some/physical/resources2")));

The two sources will be combined and will act like if they where one. If the both of then have the same file in the same location the last mounted source will have the priority.

Listing files and folders.

If a VFile points to a directory it`s children can be listed like this.

    VFile file = new VFile("/path/to/a/directory");
    //The list method will return the names of the children.
    String[] names = file.list();
    //The listFiles method will return the actual VFile objects for the children.
    VFile[] files = file.list();

If the VFile points to a file instead of a directory this methods will return null.

Listing a directory that is a child or is it self the result of multiple mounted sources will result in the combination of the listing for the multiple sources. This allows the user sees the multiple sources like if they where one.

File search

Files can be found using [[glob][https://en.wikipedia.org/wiki/Glob_(programming)]] expressions, the search method allows this.

    VFile videos = new VFile("/path/to/videos/folder");
    VFile[] files = videos.search(new GlobExpr("**.mp4"));

Creating folders and files.

Files and folders can be created using the mkdir and createNewFile methods, This methods will create the folder or the file for the given path, if the source of the virtual path allows it to be.

    VFile newFolder = new VFile("/path/to/virtual/resources/newfolder");
    boolean folderWasCreated = newFolder.mkdir();
    VFile myFile = new VFile("/path/to/virtual/resources/newfolder/myFile.txt");
    boolean fileWasCreated = myFile.createNewFile();

The folder or the file won be created if the source of the virtual file does not allow it and this methods will return false in that case, for example the CpSource source is read only and does not allow files or folders to be created, On the other hand the FileSource is read-write source and will allow both to create files and folder, unless the underliying file system on with the source is base forbides this.

Deleting folders and files.

The delete method allows to do just this, the method is subscribe to the same rules of the createNewFile and mkdir methods. If the underliying source allows to delete the file or the folder it will do so, if not it will return false.

    VFile myFile = new VFile("/path/to/virtual/resources/newfolder/myFile.txt");
    boolean fileWasDelete = myFile.delete();
    VFile newFolder = new VFile("/path/to/virtual/resources/newfolder");
    boolean folderWasDelete = newFolder.delete();

Reading and Writing VFiles

The VFileInputStream and VFileOutputStream allows VFiles to be read or write. They are the equivalents to FileInputStream and FileOutputStream for the java.io.File class.

    if(vFile.canRead())
    {
        VFile file = new VFile("/path/to/virtual/file.txt");
        try(InputStream input = new VFileInputStream(file))
        {
            //read input.
        }
    }

    if(vFile.canWrite())
    {
        VFile file = new VFile("/path/to/virtual/file.txt");
        try(OutputStream output = new VFileOutputStream(file))
        {
            //write output.
        }
    }