Examples of org.jdesktop.wonderland.tools.wfs.WFS

Package org.jdesktop.wonderland.tools.wfs

Examples of org.jdesktop.wonderland.tools.wfs.WFS

org.jdesktop.wonderland.tools.wfs.WFS
The Wonderland File System (WFS)
The WFS class represents a Wonderland File System (WFS). A WFS is a series of directories and files (cells) that describe a world or a portion of a world.
An instance of the WFS class is created through methods on the WFSFactory class. Instances of WFS (or any of its subclasses) should never be created directly.
The WFS class and its associated interfaces (WFSCell and WFSCellDirectory) enable the reading and writing of WFSs. These sets of abstractions are meant to be low-level: they are simply Java class representations of the directory and file concepts defined by WFS.
The cells contained within the root WFS directory are represented by the WFSRootDirectory class and obtained via the WFS.getRootDirectory() method.
Reading and Writing Model
A WFS is only read in when asked (i.e. the structure of the WFS is discovered progressively; it is not read all at once into memory). Once read, the WFS structure resides in memory. The underlying file system may be forceably re-read; otherwise changes made to the file system on the operation system level will not be seen in this software layer.
The structure and content of the WFS that resides in memory may be updated programmatically. Changes do not take effect to the underyling medium until explictly done so. Updating the WFS to its underlying medium (e.g. disk) can happen in one of several ways: only the configuration parameters of a cell may be updated, or a cell and all of its children may be updated (representing a subtree of the WFS), or the entire WFS tree may be updated. Updates to the medium are done with the minimum amount of disruption to any existing structure--new cells are added, while old cells are removed (versus obliterating an existing structure and rewriting from scratch).
Supported Underlying Mediums
A WFS may exist as a hierarchy of files and directories on a disk file system, or a new one may be created on disk. These WFSs are created by giving a URL with the 'file:' protocol. The WFSFactory.open(URL) method opens an existing WFS on disk, while the WFSFactory.create(URL) creates a new WFS on disk. This API supports both reading and writing for disk file systems.
A WFS may also exist as a jar file that encodes the proper directory and file structure. The jar file may be located on a disk locally, or it may be fetched from the network. The WFSFactory.open(URL) method opens a WFS encoded as a jar file, whether on disk locally (with the 'file:' protocol) or over the network (with the 'http:' protocol). See the ArchiveWFS class for more details on the format of the URL in these cases. This API supports only reading of jar files at this time.
In the final case, the WFS resides entirely in memory and may be serlialized at once to an output stream, encoded as a jar file. This usage is typically used if one wishes to create a WFS from scratch and write it out over a network connection.
Support for Multi-Threaded Access
This API is meant to be used in situations where multiple threads may be attempting to both read and write the WFS. Synchronization is based upon the concept that one thread may "own" an entire WFS tree and may read and write while it owns the tree. If no thread owns the tree, then anyone may read.
This locking scheme was implemented for a couple of reasons. First, updates to a WFS typically happen over a series of updates such as creating new cells, and deleting or modifying existing cells. Second, locking the entire WFS tree simplifies what is locked.
It is expected that threads that lock a WFS only do so to update the WFS tree quickly and then release the lock. It is up to the calling thread to release the lock, especially under exceptional conditions it may encounter.
Listeners
Threads may register listeners for changes on a WFS. These changes include: when new cells are added, when existing cells are removed, and when the properties of a cell have changed. Each event is delivered in its own thread of execution. If a cell is removed, only a single "remove" event is delivered for that thread--cell "remove" events are not delivered for any of its child cells, even though they are also implicitly removed from the WFS.
Reloading from the Underlying Medium
Normally, multiple threads interact with this WFS API to update its state and write it back out to the underlying medium. The WFS may also be updated directly on the underlying medium (e.g. modifying a disk directory structure or editing WFS cell files). This API provides a minimum facility to coordinate between the two.
It is generally expected that updates made directly to the underlying medium constitute significant re-arrangements of the layout of the world and that a mechanism that exists at a level higher than this API should first quiesce all activity related to updating the WFS.
The WFS (or any subcomponent thereof) may be told to "reload" itself via the WFS.setReload() method. (This method also exists on the WFSCell and WFSCellDirectory classes). This method call has the effect of marking the object, and all subobjects as "dirty", so that the next time information is read by threads from the API, information is re-read from the underlying medium. The objects within the API are updated intelligently: that is, when cells have been added or removed from a directory, existing WFSCell objects are left alone, and only the needed new cells are created or removed.
To note: the reload mechanism obeys the principle of the API to perform "lazy" loads of information from the underlying medium. For example, if a cell directory has been told to "reload", it does not fetch the information from the directory on the underlying medium until the next getCells() method call, for example.
The setReload() methods require the calling thread to own the write lock for the WFS. There is still, however, some synchronization risks:
1. If a user updates the WFS on the underlying medium and before he/she has the opportunity to flag a reload, a thread changes the WFS and writes the changes back to the underlying medium, the changes the user made directly to the underlying medium may be affected.
2. If a thread makes updates to the WFS but does not write them back out to the underyling medium, and a user updates the underlying medium directly and flags a reload, then the changes made by the thread to the WFS may be affected.
These two examples illustrate the necessity of insuring that all other activity that could interact with the WFS API quiesce before updates are made directly to the underlying medium. The decision on how to quiesce other activity is left to high software layers. @author Jordan Slott


        LOGGER.fine("Looking in WFS " + wfsName + " for path " + path);


        // Fetch the wfs manager and the WFS. If invalid, then return a bad
        // response.
        WFS wfs = WFSManager.getWFSManager().getWFS(wfsName);
        if (wfs == null) {
            LOGGER.warning("Unable to find WFS with name " + wfsName);
            return Response.status(Response.Status.BAD_REQUEST).build();
        }
        
        // Fetch the root directory, check if null, but should never be
        WFSCellDirectory dir = wfs.getRootDirectory();
        if (dir == null) {
            LOGGER.warning("Unable to find WFS root with name " + wfsName);
            return Response.status(Response.Status.BAD_REQUEST).build();
        }

View Full Code Here

        /*
         * Fetch the wfs manager and the WFS. If invalid, then return a bad
         * response.
         */
        WFSManager wfsm = WFSManager.getWFSManager();
        WFS wfs = wfsm.getWFS(wfsName);
        if (wfs == null) {
            logger.warning("Unable to find WFS with name " + wfsName);
            ResponseBuilder rb = Response.status(Response.Status.BAD_REQUEST);
            return rb.build();
        }
        
        /* Fetch the root directory, check if null, but should never be */
        WFSCellDirectory dir = wfs.getRootDirectory();
        if (dir == null) {
            logger.warning("WFSManager: Unable to find WFS root with name " + wfsName);
            ResponseBuilder rb = Response.status(Response.Status.BAD_REQUEST);
            return rb.build();
        }

View Full Code Here

        /*
         * Fetch the wfs manager and the WFS. If invalid, then return a bad
         * response.
         */
        WFSManager wfsm = WFSManager.getWFSManager();
        WFS wfs = wfsm.getWFS(wfsName);
        if (wfs == null) {
            logger.warning("Unable to find WFS with name " + wfsName);
            ResponseBuilder rb = Response.status(Response.Status.BAD_REQUEST);
            return rb.build();
        }
        
        /* Fetch the root directory, check if null, but should never be */
        WFSCellDirectory rootDir = wfs.getRootDirectory();
        if (rootDir == null) {
            logger.warning("WFSManager: Unable to find WFS root with name " + wfsName);
            ResponseBuilder rb = Response.status(Response.Status.BAD_REQUEST);
            return rb.build();
        }
        
        /*
         * Find out whether we should reload the WFS as we read it. We acquire
         * ownership of the WFS momentarily to tell it to reload
         */
        if (reload != null && reload.compareTo("true") == 0) {
            try {
                wfs.acquireOwnership();
                rootDir.setReload();
                wfs.release();
            } catch (InterruptedException excp) {
                logger.warning("WFSManager: Unable to set WFS to reload " + excp.toString());
            }
        }

View Full Code Here

        WFSManager manager = WFSManager.getWFSManager();
                
        // Fetch the WFS for the world root path, flag an error if it does
        // not yet exist.
        String rootPath = cellDescriptor.getRootPath().getRootPath();
        WFS wfs = manager.getWFS(cellDescriptor.getRootPath());
        if (wfs == null) {
            logger.warning("[WFS] The WFS " + rootPath + " does not exist.");
            return Response.status(Status.BAD_REQUEST).build();
        }
        
        // Fetch the root directory, this should exist
        WFSCellDirectory wfsDirectory = wfs.getRootDirectory();
        if (wfsDirectory == null) {
            logger.warning("[WFS] Unable to find root directory for " + rootPath);
            return Response.status(Response.Status.BAD_REQUEST).build();
        }
        
        // Iterate through all of the parents of the cell and fetch the proper
        // directory to place the new cell in. We fetch the names of the parent
        // cell individually and jump down through the list of directories. Note
        // that all of the directories, except perhaps the last should exist,
        // so we flag an error if that is not the case. If the parent path is
        // null, then this is a cell at the root of the wfs
        if (cellDescriptor.getParentPath() != null) {
            String parentCells[] = cellDescriptor.getParentPath().getParentPaths();
            for (int i = 0; i < parentCells.length; i++) {
                // First fetch the cell. If it does not exist, then return a bad
                // response.
                WFSCell parentCell = wfsDirectory.getCellByName(parentCells[i]);
                if (parentCell == null) {
                    logger.warning("[WFS] Unable to find cell " + parentCells[i] +
                            " in WFS " + rootPath);
                    return Response.status(Response.Status.BAD_REQUEST).build();
                }


                // Next, get the directory associated with the cell. It also needs
                // to exist, otherwise, return a bad response. The only exception
                // is the last parent in the cell, which may not have its child
                // directory yet created.
                wfsDirectory = parentCell.getCellDirectory();
                if (i < parentCells.length - 1 && wfsDirectory == null) {
                    // This means that a parent cell directory, other than the
                    // immediate parent does not exist (which means the immediate
                    // parent cell does not exist, which is very bad!
                    logger.warning("[WFS] Unable to find directory for cell " +
                            parentCells[i] + " in WFS " + rootPath);
                    return Response.status(Response.Status.BAD_REQUEST).build();
                }
                else if (wfsDirectory == null) {
                    // Unless we are talking about the cell directory associated
                    // with the parent. In which case we should create it.
                    try {
                        wfs.acquireOwnership();
                        wfsDirectory = parentCell.createCellDirectory();
                        parentCell.write();
                    } catch (java.lang.InterruptedException excp) {
                        logger.log(Level.WARNING, "[WFS] Unable to lock WFS " +
                                rootPath, excp);
                        return Response.status(Response.Status.BAD_REQUEST).build();
                    } catch (java.lang.Exception excp) {
                        logger.log(Level.WARNING, "[WFS] Failed to create WFS " +
                                " directory " + rootPath);
                        return Response.status(Response.Status.BAD_REQUEST).build();
                    } finally {
                        wfs.release();
                    }
                }
            }
        }
        
        // When we have reached here, the directory in which to place the new
        // cell is in 'wfsDirectory'. We create the cell and write the WFS
        // back out to its disk. In this case, the cell name is the name of
        // the file, which should be <Cell Name>-<Cell ID>.
        try {
            wfs.acquireOwnership();
            String cellName = cellDescriptor.getCellUniqueName();
            WFSCell cell = wfsDirectory.addCell(cellName);
            if (cell == null) {
                logger.warning("[WFS] Failed to create cell " + cellName +
                        " in WFS " + rootPath);
                return Response.status(Response.Status.BAD_REQUEST).build();
            }
            cell.setCellSetup(cellDescriptor.getSetupInfo());
            wfsDirectory.write();
        } catch (java.lang.Exception excp) {
            logger.log(Level.WARNING, "[WFS] Unable to lock WFS " + rootPath, excp);
            return Response.status(Response.Status.BAD_REQUEST).build();
        } finally {
            wfs.release();
        }
        return Response.ok().build();
    }

View Full Code Here

TOP

Related Classes of org.jdesktop.wonderland.tools.wfs.WFS

org.jdesktop.wonderland.tools.wfs.event.WFSEvent

org.jdesktop.wonderland.web.wfs.resources.CreateWFSCellResource

org.jdesktop.wonderland.web.wfs.resources.WFSCellResource

org.jdesktop.wonderland.web.wfs.resources.WFSDirectoryResource

org.jdesktop.wonderland.web.wfs.resources.WFSListCellsResource

java.util.jar.JarOutputStream

java.io.OutputStreamWriter

java.util.jar.JarEntry

All source code are property of their respective owners. Java is a trademark of Sun Microsystems, Inc and owned by ORACLE Inc. Contact coftware#gmail.com.

Examples of org.jdesktop.wonderland.tools.wfs.WFS

The Wonderland File System (WFS)

Reading and Writing Model

Supported Underlying Mediums

Support for Multi-Threaded Access

Listeners

Reloading from the Underlying Medium

Related Classes of org.jdesktop.wonderland.tools.wfs.WFS