nstream.h

Go to the documentation of this file.

/*
 * nstream.h
 *
 * Copyright (c) 2009 Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Simple library for abstracting read-only hierarchies of named streams.
 */

#ifndef WAVEPACKET_NSTREAM_H__
#define WAVEPACKET_NSTREAM_H__


// includes --------------------------------------------------------------------
#include "common/common.h"

#include <istream>

#include "geometry/geometry_3d.h"
#include "threadsafe/smart_ptr.h"


namespace nstream {

////////////////////////////////////////////////////////////////////////////////
///
/// \ingroup general
/// \defgroup nstream Named Stream Management
///
/// Simple library to abstract read-only hierarchies of named streams.
///
/// By "hierarchy of named streams", this refers to any set of resources that
/// have folder/file semantics, but may not be filesystems.  Concrete examples
/// may be:
///  - a local filesystem.  The "name" of each stream is its path, relative to
///     some specific root directory.  The hierarchy is the directory structure.
///  - a remote filesystem, accessed via URL.  The "name" of each stream is its
///     URL relative to the server (or a high-level directory of the server). 
///     The hierarchy is the URL naming scheme (which often maps to a
///     local filesystem on the server, but doesn't have to).
///  - a local archive.  For instance, a large tar file or a
///     proprietary compressed archiving format.  Some object that understands
///     how to parse the
///     compressed archive format will be able to provide named streams, and
///     let clients navigate the archive directory hierarchy.
///  - and so on (remote compressed archives?  a local process?  etc.)
///
/// <b>Why should code use this library?</b>  This is handy if you have code
/// that needs to know about multiple streams with relative paths, but should
/// be abstracted from the physical details of where the streams are.  One
/// example I've hit lately is a library that parses and displays 3D models.
/// You'll want that code to be able to access streams to read the data and
/// display, but you wouldn't want to limit that library to only work on a
/// local filesystem.
///
/// <b>Why read-only?  Why can't you use this library to create and write
/// new files?</b>  Allowing modifications starts getting complex.  For
/// instance, creating and writing new files to a remote webserver may
/// require special protocols depending on the server.  And writeable access
/// to a compressed archive may not be possible at all (it could require that
/// the archive be completely rebuilt).  In the future write concepts may
/// be included, but for now all use cases are read-only.
///
/// <b>How do you use this library?</b>  First, get or create a Manager
/// object.  From there, you can either look up Entry objects by name, or
/// you can start iterating over folders to discover Entry objects, starting
/// with getRoot().
///
////////////////////////////////////////////////////////////////////////////////
/*@{*/

// forward declarations
class Manager;
class File;


/// an instance of a read-only stream
class Stream {
public:
        // virtual destructor --------------------------------------------------
        virtual ~Stream(void) throw();

        // nstream::Stream class interface methods ----------------------------

        /// get access to the raw data stream
        virtual std::istream& getStream(void) = 0;

        /// get a pointer to the nstream::File object with which this Stream
        ///     is associated.
        virtual smart_ptr<File> getFile(void) = 0;

        /// helper method to get diagnostic information during errors etc
        virtual void writeDiagnostics(IO std::ostream& out);

        // syntactic sugar to make these more like std::istreams ---------------
        operator std::istream& (void) { return this->getStream(); }
        bool eof(void) { return this->getStream().eof(); }
        bool good(void) { return this->getStream().good(); }
        bool bad(void) { return this->getStream().bad(); }
};



/// a generic entry in the namespace.  This is either a Folder or File
class Entry {
public:
        // public enums --------------------------------------------------------
        enum eType {
                eType_Folder            = 1,    ///< this is a Folder object
                eType_File              = 2,    ///< this is a File object

                // keep this last!
                eType_Invalid           = 0
        };

        // virtual destructor --------------------------------------------------
        virtual ~Entry(void) throw();

        // nstream::Entry class interface methods -----------------------------

        /// what type of entry is this?
        virtual eType getType(void) const throw() = 0;

        /// this Entry's name in the namespace (that is, relative to the root of
        ///   the namespace).
        virtual const char * getName(void) const throw() =  0;

        /// the Manager of this namespace
        virtual smart_ptr<Manager> getManager(void) = 0;
};



/// an atom in the namespace: a File is a named object from which you can
///     request read-only streams.
class File : public Entry {
public:
        // virtual destructor --------------------------------------------------
        virtual ~File(void) throw();

        // nstream::File class interface methods ------------------------------

        /// creates a new instance of a read-only stream for this File's data
        virtual smart_ptr<Stream> openStream(void) = 0;
};



/// a folder in the namespace: contains other stream::Entry objects.
/// <b>The iteration model for Folders is very primitive.</b>  That is
/// intentional.  If you want multiple iterators for a given Folder at the
/// same time, create multiple Folder objects.  Remember that you may be
/// creating expensive iterators underneath (open directory handles, database
/// cursors, etc.) so in general keeping multiple iterators open at the same
/// time is discouraged anyway.
///
/// Notes to users and implementers:
///  - Keep in mind that Folders may contain many thousands of child Entry
///     objects--or more.
///  - The iteration should visit every sub-Entry once and only once, but
///     there is no guarantee about ordering.  In particular, callers should
///     assume that child objects are NOT in lexigraphic order.
///  - A new Folder object should have its iterator already reset and ready
///     for calls to getNextChild().  That is, it is not required to call
///     resetIteration() for the first iteration loop.  resetIteration() is
///     a convenience method in case people want to iterate multiple times.
///  - There are sometimes odd semantics about iteration.  For instance,
///     native filesystem directory listings often contain "." (self) and
///     ".." (parent).  The semantics of nstream::Folder iteration are clear:
///     any and all child Entry objects should be returned.  But non-child
///     Entries will not.  And so, for instance, "." and ".." would not be
///     returned when iterating over a filesystem-based Folder.
class Folder : public Entry {
public:
        // virtual destructor --------------------------------------------------
        virtual ~Folder(void) throw();

        // nstream::Folder class interface methods ----------------------------

        /// get a child entry directly by its name relative to the parent
        ///     (returns NULL if no such child exists)
        virtual smart_ptr<Entry> getChildByName(IN const char * name) = 0;

        /// reset the Folder iteration to point to the first Entry again.
        virtual void resetIteration(void) = 0;

        /// get the next child Entry object.  Returns null when done.
        virtual smart_ptr<Entry> getNextChild(void) = 0;
};



/// the object that manages a particular space of named streams
class Manager {
public:
        // virtual destructor --------------------------------------------------
        virtual ~Manager(void) throw();

        // nstream::Manager class interface methods ---------------------------

        /// get the entry with the given name.  Returns NULL if there is no
        ///     entry with that name.
        virtual smart_ptr<Entry> getEntry(IN const char * name) = 0;

        /// get the root Folder object for this namespace
        virtual smart_ptr<Folder> getRoot(void) = 0;

        /// get the full name (absolute path, URL, ...) for this name
        virtual std::string getFullName(IN const char * name) = 0;
};




////////////////////////////////////////////////////////////////////////////////
//
//      public API
//
////////////////////////////////////////////////////////////////////////////////

/// \ingroup nstream
/// \defgroup nstream_fs Named Streams: Filesystem
/// This is a reference implemenation of the nstream interface, for a local
/// filesystem.
/*@{*/

/// A reference nstream::Manager implementation: this API provides a namespace
///   object based on the local filesystem.
/// The caller must provide the local path which forms the root of this
///   namespace.
smart_ptr<Manager> getFilesystemManager(IN const char * root_dir);

/*@}*/  // end of nstream_fs



/// Helper method: given a Stream object, and a path relative to that stream
///     path, return a stream for that.  Returns null if no such stream exists,
///     although this function does a lot so throwing is also possible in some
///     cases.
smart_ptr<Stream> getStreamRelativeTo(IN Stream * startStream,
                                IN const char * relativePath);



/// Helper method: open a Stream for a given path on the specified Manager.
///     Throws on any error (no entry at that path, entry is not a file, etc.)
///     so the caller is guaranteed a non-NULL return value.
smart_ptr<Stream> openNamedStream(IN Manager * mgr,
                                IN const char * name);



/// Helper method: given a Stream, return its name
std::string getStreamName(IN Stream * stream);


/// used by nstream::walkChildFolders() callback
enum eIterationFlag {
        eIterate_Continue       = 1,    ///< keep iterating through entries
        eIterate_Stop           = 2,    ///< stop iterating

        // must be last!
        eIterate_Invalid        = 0
};


/// callback for nstream::walkChildFolders()
typedef eIterationFlag (*visit_entry_fn)(IN Entry * entry, IN void * context);


/// helper methods: given a Folder, walk all child Folders and Entries
///     recursively.  The callback (visit_entry_fn) is called per Entry.
///     If extensions is non-null then only Entries with a name with an
///     extension in the set will be visited.  If filter is non-null then
///     only Entries with the filter string somewhere in its path will
///     be visited.  Returns the final iteration flag (in other words,
///     will return eIterate_Stop if iteration halted early).
eIterationFlag walkChildFolders(IN Folder * root,
                        IN visit_entry_fn callback,
                        IN void * context,
                        IN const SetString * extensions = NULL,
                        IN const char * filter = NULL,
                        IN bool visitHidden = false);


};      // nstream namespace

/*@}*/  // end of documentation block

#endif  // WAVEPACKET_NSTREAM_H__