review of the Storage interface

[Dietmar Maurer <dietmar maurer-it com>]

I suggest the following changes for the Storage interface:

/*
  Changes:

  New get_info method (something like unix stat).
  Also used to read the contents of a Storage (replaces
  list_contents)

  added locking interface

  added more exceptions

  removed copy_to from stream

  use long long for indexing into files

  new revert method

  more open modes

  removed eos, length and list_contents method (see get_info)

  add a content type parameter to create_stream and
  create_storage
 

 */

module Bonobo {
 
 typedef string ContentType;
 typedef long long StreamOffset;
 typedef unsigned long long StreamSize;

 enum StorageType {
  STORAGE,
  STREAM
 };

 struct StorageInfo {
  string name;
  StorageType type;
  ContentType content_type;
  StreamSize size;
 };

 interface Stream : Unknown {
  typedef sequence<octet> iobuf;

  exception IOError {}; /* driver internal error */
  exception NoPermission {};
  exception NotSupported {};
  exception Locked {};
  exception EOS {};

  enum SeekType {
   SEEK_SET,
   SEEK_CUR,
   SEEK_END
  };

  enum LockType {
   READ_LOCK,
   WRITE_LOCK,
   UNLOCK
  };
 
  /**
   * get_info:
   *
   * Returns a StorageInfo structure which contains
   * the name, content_type and size info.
   */
  StorageInfo get_info ()
   raises (IOError);
 
  /**
   * read:
   * @count:  number of bytes to read.
   * @buffer: the buffer where the data is returned.
   */
  void read (in long count, out iobuf buffer)
   raises (NoPermission, IOError, EOS);
 
  /**
   * write:
   * @buffer: a buffer to write.
   *
   * writes the buffer to this stream.
   */
  long write (in iobuf buffer)
   raises (NoPermission, IOError);

  /**
   * seek:
   * @offset: offset
   * @whence:
   *
   * Sets the read/write pointer to @offset (relative to @whence)
   */
  long seek (StreamOffset offset, in SeekType whence)
   raises (IOError, NotSupported);

  /**
   * truncate:
   * @length: new size of the stream
   *
   */
  void truncate (StreamSize length)
   raises (IOError, NoPermission, NotSupported);
 
  /**
   * commit:
   *
   * Commits any pending changes to the Storage
   */
  void commit ()
   raises (IOError, NoPermission, NotSupported);
 

  /**
   * revert:
   *
   * Discards any changes since the last commit.
   */
  void revert ()
   raises (IOError, NoPermission, NotSupported);

  /**
   * close:
   *
   * Close the Stream
   */
  void close ()
   raises (IOError);

  /**
   * lock_region:
   *
   */
  void lock_region (LockType type, StreamOffset offset,
      SeekType whence, StreamSize length)
   raises (IOError, NotSupported, Locked);
 };

 interface Storage : Unknown {
 
  typedef long OpenMode;
  const OpenMode READ  = 1;
  const OpenMode WRITE = 2;
  const OpenMode CREATE = 4;
  const OpenMode FAILIFEXIST = 8;
  const OpenMode COMPRESSED = 16; /* try to compress */
  const OpenMode DENY_READ = 32;
  const OpenMode DENY_WRITE = 64;
  const OpenMode TRANSACTED = 128;

  exception IOError {}; /* driver internal error */
  exception NameExists {};
  exception NotStream {};
  exception NotStorage {};
  exception EOS {};
  exception NotFound {};
  exception NoPermission {};
  exception Locked {};

  /**
   * get_info:
   *
   * Returns a StorageInfo structure which contains
   * the name, content_type of the directory entry
   * at position. position zero means the storage itself.
   */
  StorageInfo get_info (in long position)
   raises (IOError, EOS);

  /**
   * create_stream:
   * @path: path of the Stream to create
   * @mode: creation flags
   *
   * Creates a stream inside the Storage.
   */
  Stream create_stream (in string path, in ContentType type)
   raises (IOError, NameExists);

  /**
   * open_stream:
   * @path: path of the stream to open
   * @mode: open flags
   *
   * Opens a Stream whose name is @path.
   */
  Stream open_stream   (in string path, in OpenMode mode)
   raises (IOError, NotFound, NoPermission);

  /**
   * create_storage:
   * @path: path of the storage root directory
   *
   * Creates a new storage whose root directory will be
   * path.
   */
  Storage create_storage (in string path, in ContentType type)
   raises (IOError, NameExists);
 
  /**
   * open_storage:
   * @path: path of the storage to open.
   * @mode: open mode.
   *
   * Returns a storage object for @path.
   */
  Storage open_storage   (in string path, in OpenMode mode)
   raises (IOError, NotFound, NoPermission);

  /**
   * copy_to:
   * @target: where to copy this storage to.
   *
   * Copies this storages contents to the @target storage
   */
  void copy_to (in Storage target);

  /**
   * rename:
   * @path_name: element name to rename
   * @new_path_name: new name we want to use
   *
   * Renames a Stream or Storage component inside a Storage.
   */
  void rename (in string path_name, in string new_path_name)
   raises (IOError, NameExists, NotFound);

  /**
   * erase:
   * @path: path to the element to erase.
   *
   * Destroys the element pointed to by @path.  The element
   * can be a Storage or a Stream.
   */
  void erase (in string path)
                       raises (IOError, NoPermission, NotFound);

  /**
   * commit:
   *
   * Commits any pending changes to the Storage
   */
  void commit ()
   raises (IOError, NoPermission, NotSupported);
 
  /**
   * revert:
   *
   * Discards any changes since the last commit.
   */
  void revert ()
   raises (IOError, NoPermission, NotSupported);
 };
};