EntityFS programmer's guide

// Create a file system with default settings except for a custom name
FileSystem fs1 = new FSRWFileSystemBuilder().
  setName("My first file system").
  setRoot(new File("/tmp/fs1")).
  create();

// Create a file system with no event handling and relaxed validity controls
// for entities. (See FSRWFileSystemBuilder API docs.)
FileSystem fs2 = new FSRWFileSystemBuilder().
  setName("My second file system").
  setRoot(new File("/tmp/fs2")).
  disableEntityValidityControls().
  // Enable entity locking
  enableLocking().
  create();

// fs is another file system
EFile jarFile = Directories.getFile(fs.getRootDirectory(), "myapp.jar");

FileSystem jfs = new JarFileSystemBuilder().
  setName("My Jar file system").
  setJarFile(jarFile).
  create();

// d1 and d2 are directories, e1 is an entity of any type that currently is in
// the directory d1.
Collection<EntityLock> locks = new ArrayList<EntityLock>();
try
{
  locks.add(d1.lockForWriting());
  
  // The write lock on d1 is also a read lock. Get the entity to move.
  EntityView e1 = d1.getEntityOrNull("e1");
  locks.add(e1.lockForWriting());
  locks.add(d2.lockForWriting());
  
  // Move the entity
  e1.rename(d2, "e1");
}
finally
{
  // Use the utility class EntityLocks to unlock all locks
  EntityLocks.unlockAll(locks);
}
// The entity is still represented by the variable e1, even though it has
// moved.

// d1 and d2 are directories, e1 is an entity of any type that currently is in
// the directory d1.
//
// In a locking file system, the utility classes make sure to lock all entities
// that need to be locked to perform the requested operation. See the chapter
// on locking.
EntityView e1 = Directories.getEntity(d1, "e1");
Entities.move(e1, d2);

// fs is a locking file system. Get the root directory
Directory root = fs.getRootDirectory();

EFile myFile;

// Lock the root directory for writing
EntityLock wl = root.lockForWriting();
try
{
  // Create an entity of the type ETFile.TYPE called myFile
  myFile = (EFile) root.newEntity(ETFile.TYPE, "myFile", null);
}
finally
{
  // Unlock the directory
  wl.unlock();
}

// fs is a file system. Get the root directory
Directory root = fs.getRootDirectory();

// Create a file called "myFile".
EFile myFile = Directories.newFile(root, "myFile");

// d is a directory
// Create a directory under d with an empty file in it. This invocation
// returns a reference to the file, but we ignore it for the sake
// of the example
Directories.newFile(org.entityfs.util.Directories.newDirectory(d, "d"), "f");

// Directories.getDirectory returns a DirectoryView. Since the argument d
// is a Directory, the result can safely be cast to a Directory.
Directory dd = (Directory) Directories.getDirectory(d, "d");

// (We could have used the entity reference returned by newFile above.)
EFile f = Directories.getFile(d, new RelativeLocation("d/f"));

Set<EntityView> s;
// d is a directory in a locking file system. Lock it for reading.
EntityLock rl = d.lockForReading();
try
{
  s = d.listEntities();
}
finally
{
  // Unlock the directory.
  rl.unlock();
}

// d is a directory
Set<EntityView> s = Directories.listEntities(d);

// d is a directory
EFile f1 = Directories.newFile(d, "f1");
DirectoryView d1 = Directories.newDirectory(d, "d1");

// Create a view that only shows files
DirectoryView dv = d.newView(EFileFilter.FILTER);
Set<EntityView> s = Directories.listEntities(dv);

// d is a directory
EntityLock rl = d.lockForReading();
try
{
  for (EntityView ev : d)
  {
    // process child entities...
  }
}
finally
{
  rl.unlock();
}

// d is a directory (or a view)
// Create a view that only shows XML files.
DirectoryView dv = d.newView(new EFileNameExtensionFilter("xml"));

// Even though this is called on the view, it locks the viewed directory
Lock rl = dv.lockForReading();
try
{
  for (EntityView ev : dv)
  {
    EFile xmlFile = (EFile) ev;
    // process the XML files...
  }
}
finally
{
  rl.unlock();
}

// d is a directory
Directory dd = (Directory) Directories.newDirectory(d, "d");
Directory ddd = (Directory) Directories.newDirectory(dd, "d");
EFile f = Directories.newFile(ddd, "f");

Iterator<EntityView> itr = Directories.getDepthFirstIterator(d);

The iterator will return the entities f, ddd, dd and d, in that order.

// d is a directory
EFile f1txt = Directories.newFile(d, "f1.txt");
EFile f1xml = Directories.newFile(d, "f1.xml");
Directory d1 = (Directory) Directories.newDirectory(d, "d1");
EFile d1f1txt = Directories.newFile(d1, "d1f1.txt");
EFile d1f1xml = Directories.newFile(d1, "d1f1.xml");

// Create a view that only shows directories and XML files
DirectoryView dv = d.newView(
  DirectoryFilter.FILTER.
    or(new EFileNameExtensionFilter("xml")));

Iterator<EntityView> itr = Directories.getDepthLastIterator(dv);

itr will return the entities / (view of), f1.xml, d1 (view of) and d1f1.xml (d1 may be returned before f1.xml).

// d is a directory
EFile f = Directories.newFile(d, "f");

// Lock the file for writing
EntityLock wl = f.lockForWriting();
try
{
  OutputStream os = f.openForWrite();
  try
  {
    try
    {
      ... write to os
    }
    finally
    {
      os.close();
    }
  }
  catch (IOException e)
  {
    ... error handling
  }
}
finally
{
  wl.unlock();
}

// d is a directory
EFile f = Directories.newFile(d, "f");
Files.writeText(f, "Ceterum censeo Carthaginem esse delendam");

// f is a file
myStreamUsingMethod(Files.openForRead(f));
// The openForRead method locks the file for reading. The lock is released when 
// the stream is closed. (And that is a responsibility of the stream-using 
// class.)

// d is a directory
EntityLock rl = d.lockForReading();
try
{
  d.listEntities();
}
finally
{
  // This will always be called.
  rl.unlock();
}

Collection<EntityLock> locks = new ArrayList<EntityLock>();
try
{
  // d1 and d2 are directories
  locks.add(d1.lockForReading());
  locks.add(d2.lockForWriting());
  
  // do stuff...
}
finally
{
  EntityLocks.unlockAll(locks);
}

// Move the file f1 from directory d1 to directory d2 and append the text
// "moved" to it.
FileSystem fs = f1.getFileSystem();
AccessController ac = fs.getAccessController();
Collection<LockCommand> cmds = 
  new ArrayList<LockCommand>();

// Add the lock commands that are needed for moving the entity.
// Keep this lock command for future reference
LockCommand f1lc = new LockForWritingCommand(f1);
cmds.add(f1lc);
cmds.add(new LockForWritingCommand(d1));
cmds.add(new LockForWritingCommand(d2));

// Add the lock commands that are needed for performing access controls.
// Keep these lock commands for future reference
Collection<? extends LockCommand> f1acmds =
  ac.getLockCommandsForAccessControl(f1);
cmds.addAll(f1acmds);
cmds.addAll(ac.getLockCommandsForAccessControl(d1));
cmds.addAll(ac.getLockCommandsForAccessControl(d2));

// Lock all locks
LockCollection lc = fs.getLockCommandExecutor().execute(cmds);
try
{
  // Move the entity
  f1.rename(d2, f1.getName());
  
  // Keep all locks required for appending text to the file in a new lock 
  // collection.
  LockCollection lc2 = new LockCollection();
  try
  {
    // The write lock on f1
    lc2.addLock(f1lc, lc.removeLock(f1lc));
    // The locks required for access controls on f1
    lc2.addLocks(lc.removeLocks(f1acmds));
    
    // Unlock all other locks
    lc.unlockAll();
    
    Writer w = new OutputStreamWriter(
      f1.openForAppend(),
      Charset.forName("utf8"));
    try
    {
      w.write("moved");
    }
    finally
    {
      w.close();
    }
  }
  finally
  {
    lc2.unlockAll();
  }
}
finally
{
  // It is safe to call unlockAll several times an a LockCollection
  lc.unlockAll();
}

Compare the Directory entity method for creating a new file:

// d is a directory
EFile f;
EntityLock wl = d.lockForWriting();
try
{
  f = (EFile) d.newEntity(ETFile.TYPE, "f", null);
}
finally
{
  wl.unlock();
}

With the Directories utility method:

EFile f = Directories.newFile(d, "f");

// d is a directory
EntityLock wl = d.lockForWriting();
try
{
  EFile f1 = Directories.newFile(d, "f1");
  // Since we hold a write lock on d here, no other thread can get access to
  // f1 since that would involve reading d.
  
  // writeDataToFile is a method that writes data to the file...
  writeDataToFile(f1);
  
  EFile f2 = Directories.newFile(d, "f2");
}
finally
{
  wl.unlock();
}

// d is a directory (or view)
Iterator<EntityView> itr = Directories.getDepthFirstIterator(d);
while(itr.hasNext())
{
  EntityView ev = itr.next();
  DirectoryView parent;

  // Get a temporary read lock on ev. We need it to get ev's parent.
  EntityLock rl = ev.lockForReading();
  try
  {
    // getParent requires a read lock (a write lock would also do)
    parent = ev.getParent();
  }
  finally
  {
    rl.unlock();
  }

  // parent == null means the root directory. We cannot delete that.
  if (parent != null)
  {  
    // Lock the parent before ev.
    EntityLock pwl = parent.lockForWriting();
    try
    {
      EntityLock wl = ev.lockForWriting();
      try
      {
        // Is the parent still the parent of the entity to delete?
        if (ev.getParent() == parent)
        {
          ev.delete();
        }
        else
        {
          ev.getFileSystem().getLogAdapter().
            logWarning("Cannot delete " + ev + ". It has been moved!");
        }
      }
      finally
      {
        wl.unlock();
      }
    }
    finally
    {
      pwl.unlock();
    }
  }
}

// d is a directory (or view)
Iterator<EntityView> itr = new FilteringIterator(
  Directories.getDepthLastIterator(d),
  new EFileNameExtensionFilter("xml"));

// f is a property file
Properties p = PropertiesUtil.loadFromFile(f);

int i = p.getIntValue("myIntProperty");

// The object value is stored as the object serialized to a 
// Base64-encoded String.
Object o = p.getObjectValue("myObjectProperty");

// If no default value is given, all getter methods throw
// a NoSuchPropertyException if a requested property is missing.

// Define a default value to use if the property is missing.
long l = p.getLongValue("myOptionalLongProperty", 17L);

// Synchronize the directory hierarchy under the directory target with the 
// hierarchy under the directory master.
//
// Assume the following hierarchy under master:
// master
// + f1
// + d1
//   + f2
//   + f3

new DirectoryTreeSynchronizer(master, target).run();

// target now mirrors the directory hierarchy under master, regardless of what
// it contained before synchronizing.

// d is the directory to monitor.
// Create a view that only shows XML files.
DirectoryView dv = d.newView(new EFileNameExtensionFilter("xml"));

// Create a timer that will tell the monitorer when to scan the directory
// for updates. Any old Observable should work; the monitorer will
// scan its directory every time the Observable generates an event.
// Scan every minute.
TimerTicker tt = new TimerTicker(60000);

// Create a polling monitorer on the directory view.
PollingDirectoryMonitorer mon = 
  new PollingDirectoryMonitorer(dv, tt);
  
// Register an observer on the monitorer
mon.addObserver(new EntityObserver() 
  {
    public void update(EntityEvent ee)
    {
      if (ee instanceof ChildEntitiesAddedEvent)
      {
        System.out.println("New child entities: " + ee);
      }
    }
  });

// Start the monitorer
mon.start();

// Start the timer ticker.
tt.start();

// This will generate an event sometime in the next minute
Directories.newFile(d, "foo.xml");

// This will not
Directories.newFile(d, "bar.txt");

// Neither will this
Directories.newDirectory(d, "baz.xml");

// But this will
new File(
  ECFileResolvableUtil.getFileObject(d) + 
    File.separator +
    "doh.xml").createNewFile();

// Our custom entity attributes
// Implement the attributes object to be immutable.
public class IndexAndBackupAttributes implements EntityAttributes
{
  private final Date m_indexDate;
  private final Date m_backupDate;
  
  public IndexAndBackupAttributes(Date indexDate, Date backupDate)
  {
    // Null checks
    indexDate.getClass();
    backupDate.getClass();
    m_indexDate = indexDate;
    m_backupDate = backupDate;
  }
  
  public Date getIndexDate()
  {
    return m_indexDate;
  }
  
  public Date getBackupDate()
  {
    return m_backupDate;
  }
  
  // EntityAttributes inherits Cloneable
  public Object clone()
  {
    return new IndexAndBackupAttributes(m_indexDate, m_backupDate);
  }
  
  // EntityAttributes recommends that we implement equals
  @Override
  public boolean equals(Object o)
  {
    if (o instanceof IndexAndBackupAttributes)
    {
      IndexAndBackupAttributes a2 = (IndexAndBackupAttributes) o;
      return a2.m_indexDate.equals(m_indexDate) && a2.m_backupDate.equals(m_backupDate);
    }
    else
    {
      return false;
    }
  }
  
  // We implemented equals, so now we have to implement hashCode too...
  @Override
  public int hashCode()
  {
    // Implement as suggested in Joshua Bloch's Effective Java
    int res = ((int) m_indexDate.getTime() ^ (int) (m_indexDate.getTime() >>> 32));
    return 31 * res + 
      (int) (m_backupDate.getTime() ^ (int) (m_backupDate.getTime() >>> 32));
  }
}

// This is the Serializer that is used to serialize
// attributes to and interpret attributes from the file where they are stored.
// One instance is used by all objects.
public class IndexAndBackupSerializer
  implements Serializer<IndexAndBackupAttributes>
{
  // The size of a serialized object in bytes.
  // A long is 8 bytes long
  private static final int SERIALIZED_SIZE = 8 + 8;
  
  // Get the size in bytes of the object when serialized.
  public int getSerializedSize()
  {
    return SERIALIZED_SIZE;
  }
  
  public boolean isNullValuesPermitted()
  {
    // No.
    return false;
  }
  
  // This is used by both serialization methods
  private void serializeInternal(IndexAndBackupAttributes o, byte[] barr, int offset)
    // We are allowed to throw this
    throws ArrayIndexOutOfBoundsException
  {
    // Serialize the dates to long:s. Use the LongSerializer.
    int pos = offset;
    LongSerializer.INSTANCE.serialize(o.getIndexDate().getTime(), barr, pos);
    pos += LongSerializer.DATA_SIZE;
    LongSerializer.INSTANCE.serialize(o.getBackupDate().getTime(), barr, pos);
  }
 
  public byte[] serialize(IndexAndBackupAttributes o)
  {
    byte[] res = new byte[SERIALIZED_SIZE];
    serializeInternal(o, res, 0);
    return res;
  }
 
  public int serialize(IndexAndBackupAttributes o, byte[] barr, int offset)
  {
    serializeInternal(o, barr, offset);
    return SERIALIZED_SIZE;
  } 
  
  private void validateSize(int size)
  {
    if (size != SERIALIZED_SIZE)
    {
      throw new SerializationException(
        "Invalid size of data " + size + 
        ". Must be " + SERIALIZED_SIZE + " bytes");
    }
  }
  
  // This is used by both interpret methods.
  private IndexAndBackupAttributes interpretInternal(byte[] barr, int offset)
  {
    // Use the LongSerializer to read the dates
    // that are serialized as longs
    int pos = offset;
    long indexDate = 
      LongSerializer.INSTANCE.interpret(barr, pos, LongSerializer.DATA_SIZE);
    pos += LongSerializer.DATA_SIZE;
    long backupDate =
      LongSerializer.INSTANCE.interpret(barr, pos, LongSerializer.DATA_SIZE);
    return new IndexAndBackupAttributes(
      new Date(indexDate),
      new Date(backupDate));
  }
  
  public IndexAndBackupAttributes interpret(byte[] barr) 
    throws SerializationException
  {
    validateSize(barr.length);
    return interpretInternal(barr, 0);
  }
  
  public IndexAndBackupAttributes interpret(byte[] barr, int offset, int length)
    throws SerializationException
  {
    validateSize(length);
    return interpretInternal(barr, offset);
  }
  
  public IndexAndBackupAttributes read(InputStream is, int size)
  {
    validateSize(size);
    byte[] barr = new byte[SERIALIZED_SIZE];
    try
    {
      int noRead = is.read(barr);
      if (noRead != SERIALIZED_SIZE)
      {
        throw new NotEnoughDataException(SERIALIZED_SIZE, noRead);
      }
      return interpret(barr);
    }
    catch (IOException e)
    {
      throw new WrappedIOException(e);
    }
  }
  
  public IndexAndBackupAttributes read(RandomAccess ra, int size)
  {
    validateSize(size);
    byte[] barr = new byte[SERIALIZED_SIZE];
    int noRead = ra.read(barr);
    if (noRead != SERIALIZED_SIZE)
    {
      throw new NotEnoughDataException(SERIALIZED_SIZE, noRead);
    }
    return interpret(barr);
  }
}

// This ObjectFactory is used to create default values of the attributes
// for different entity types.
public class IndexAndBackupAttributesFactory 
  implements ObjectFactory<IndexAndBackupAttributes>
{
  public IndexAndBackupAttributes create()
  {
    // Initialize the object with the current time.
    Date d = new Date();
    return new IndexAndBackupAttributes(d, d);
  }
}

// This object creates a file system whose entities have 
// IndexAndBackupAttributes, creates a couple of entities and set their
// attribute values.
public class MyIndexAndBackupAttributesUsingClass
{
  public FileSystem createAndInitFileSystem(File root)
  {
    // Default attributes factories for the different entity types.
    IndexAndBackupAttributesFactory af = new IndexAndBackupAttributesFactory();
    Map<EntityType, ObjectFactory<IndexAndBackupAttributes>> daf =
      new HashMap <EntityType, ObjectFactory<IndexAndBackupAttributes>>();
    daf.put(ETFile.TYPE, af);
    daf.put(ETDirectory.TYPE, af);
    
    FileSystem res =
      new FSRWFileSystemBuilder().
        setRoot(root).
        // Add the necessary directory metadata capability provider first.
        addCapabilityProvider(
          new FileBasedDirectoryMetadataCapabilityProvider()).
        // Add the custom entity attributes capability provider
        addCapabilityProvider(
          new MetadataCustomAttributesCapabilityProvider().
            // Don't store entities' attributes lazily (this is the default, so
            // this invocation is unnecessary)
            setStoreAttributesLazily(false).
            setDefaultAttributesFactories(daf).
            // Set the types of attributes that will be handled by the 
            // capability
            setAttributesType(IndexAndBackupAttributes.class).
            // This factory creates ChildEntityAttributeManager
            // objects for all directories.
            setChildEntityAttributeManagerFactory(
              // This can be used for capabilities that store their attributes
              // in a HeliDB database.
              new DatabaseChildEntityAttributeManagerFactory<IndexAndBackupAttributes>(
                new IndexAndBackupSerializer(), daf, 8192))).create();
    Directory fsroot = res.getRootDirectory();
	
    EFile f = Directories.newFile(fsroot, "f");
    // This has not been backed up since the 28th of January 1982. Sorry.
    Calendar cal = Calendar.getInstance();
    cal.clear();
    cal.set(Calendar.YEAR, 1982);
    cal.set(Calendar.MONTH, 0);
    cal.set(Calendar.DAY_OF_MONTH, 28);
    IndexAndBackupAttributes iab = 
      new IndexAndBackupAttributes(new Date(), cal.getTime());
    ECEntityAttributesUtil.setAttributes(f, iab);
	
    return res;                
  }
}

// The access granter
public class MyAccessGranter implements AccessGranter
{
  public boolean hasAccess(Subject subj, Permission p)
  {
    // Alice may only write in directories on thursdays
    if (p instanceof WritePermission)
    {
      WritePermission wp = (WritePermission) p;

      // Is the entity we are controlling access to a directory entity?
      if (wp.getEntity().getType() == ETDirectory.TYPE)
      {
        String subjName = ((MySubject) subj).getName();
        if (subjName.equals("Alice"))
        {
          return Calendar.getInstance().get(Calendar.DAY_OF_WEEK) == 
            Calendar.THURSDAY;
        }
      }
    }
    
    // All other access is permitted
    return true;
  }
}

// A custom Subject implementation that has a name.
public class MySubject extends SimpleAccessControllerSubject
{
  private final String m_name;
  
  public MySubject(AccessController ac, String name)
  {
    super(ac);
    m_name = name;
  }
  
  public String getName()
  {
    return m_name;
  }
}

// A PrivilegedAction that creates a new temporary file in a directory
public class MyWriteToDirectoryAction implements PrivilegedAction<EFile>
{
  private final Directory m_directory;
  
  public MyWriteToDirectoryAction(Directory d)
  {
    m_directory = d;
  }
  
  public EFile run()
  {
    return Directories.newTempFile(m_directory, "privileged", ".tmp");
  }
}

// A class that uses the privileged action to try to create a temporary file.
public class MyDirectoryWriter
{
  public EFile createTempFile(MySubject subj, Directory dir)
  {
    try
    {
      return subj.doAs(new MyWriteToDirectoryAction(dir));
    }
    catch (AccessDeniedException e)
    {
      dir.getFileSystem().getLogAdapter().logWarning("Not today");
      throw e;
    }
  }
}

// A PrivilegedAction that creates a new text file in a directory
public class NewTextFileAction implements PrivilegedAction<EFile>
{
  private final Directory m_directory;
  
  public NewTextFileAction(Directory d)
  {
    m_directory = d;
  }
  
  public EFile run()
  {
    EFile res = (EFile) m_directory.newEntity(ETFile.TYPE, "t.txt", null);
    Files.writeText(res, "Quidquid latine dictum sit, altum sonatur");
    return res;
  }
}

// A class that makes sure that the file is written
public class MyFileWriter
{
  public EFile createFile(Directory d)
  {
    // Create a subject with UID = 1, primary GID = 2 and one secondary GID = 3
    UidGidSubject subj = new SimpleAccessControllerUidGidSubject(
      d.getFileSystem().getAccessController(), 1, 2, 
      Arrays.asList(new Integer[] { Integer.valueOf(3) }));
      
    // Get the entity attributes for the directory. Make no assumption about 
    // what exact kind of entity attributes that the directory has, other than
    // that it implements UidGidConfigurable and UnixEntityModeConfigurable
    EntityAttributes ea = ECEntityAttributesUtil.getAttributes(d);

    // Set the directory's owner to be the new subject
    ((UidGidConfigurable) ea).setUid(1);
    
    // Set the directory's mode to permit write and execution by its
    // owner. 0755 is the mode's octal representation. It will allow writes only
    // by the directory's owner. See UnixEntityMode for more documentation.
    ((UnixEntityModeConfigurable) ea).setUnixEntityMode(0755);
    
    // Save the directory's attributes
    ECEntityAttributesUtil.setAttributes(d, ea);
    
    // Create the text file. It will automatically be owned by the creating
    // Subject
    return subj.doAs(new NewTextFileAction(d));
  }
}

// A PrivilegedAction that creates a new text file in a directory
public class NewTextFileAction implements PrivilegedAction<EFile>
{
  private final Directory m_directory;
  
  public NewTextFileAction(Directory d)
  {
    m_directory = d;
  }
  
  public EFile run()
  {
    FileSystem fs = m_directory.getFileSystem();

    // Create the file.
    
    // Use the file system's LockCommandExecutor to
    // execute the lock commands according to the file system's locking strategy.
    Collection<LockCommand> lcmds = new ArrayList<LockCommand>();
	
    // We need lock commands for access controls on the directory
    lcmds.addAll(fs.getAccessController().getLockCommandsForAccessControl(m_directory));
    
    // ...and lock commands for locking the directory for writing
    lcmds.add(new LockForWritingCommand(m_directory));
    
    EFile res;
    LockCollection lc = fs.getLockCommandExecutor().execute(lcmds);
    try
    {
      res = (EFile) m_directory.newEntity(ETFile.TYPE, "t.txt", null);
    }
    finally
    {
      lc.unlockAll();
    }
    
    // Write to the file
    lcmds = new ArrayList<LockCommand>();
    
    // Lock commands for access controls on the file
    lcmds.addAll(fs.getAccessController().getLockCommandsForAccessControl(res));
    
    // ... and for locking the file for writing
    lcmds.add(new LockForWritingCommand(res));

    lc = fs.getLockCommandExecutor().execute(lcmds);
    try
    {
      Files.writeText(res, "Vescere bracis meis!");
    }
    finally
    {
      lc.unlockAll();
    }
    return res;
  }
}

// A class that makes sure that the file is written
public class MyFileWriter
{
  public EFile createFile(Directory d)
  {
    // Create a subject with UID = 1, primary GID = 2 and one secondary GID = 3
    UidGidSubject subj = new SimpleAccessControllerUidGidSubject(
      d.getFileSystem().getAccessController(), 1, 2, 
      Arrays.asList(new Integer[] { Integer.valueOf(3) }));
      
    // Get the entity attributes for the directory. Make no assumption about 
    // what exact kind of entity attributes that the directory has, other than
    // that it implements UidGidConfigurable and UnixEntityModeConfigurable
    EntityAttributes ea = ECEntityAttributesUtil.getAttributes(d);

    // Set the directory's owner to be the new subject
    ((UidGidConfigurable) ea).setUid(1);
    
    // Set the directory's mode to permit write and execution by its owner.
    // 0755 is the mode's octal representation. It will allow writes only by the
    // directory's owner. See UnixEntityMode for more documentation.
    ((UnixEntityModeConfigurable) ea).setUnixEntityMode(0755);
    
    // Save the directory's attributes
    ECEntityAttributesUtil.setAttributes(d, ea);
    
    // Create the text file. It will automatically be owned by the creating
    // Subject
    return subj.doAs(new NewTextFileAction(d));
  }
}

// Build a Zip file containing all files and directories under the directory d1.
// Put the new file zip.zip in the directory d2.
new ZipCreator(
  new EntityIteratorToZipEntryInfoIteratorAdapter(d1, 
    Directories.getDepthLastIterator(d1)),
  d2, "zip.zip").create();

// The ZipCreator will acquire read locks on the files and directories
// added to the Zip file when it needs them.

// Build a Zip file containing all files and directories under the directory d1,
// stored under /dirs/d1 and all directories and XML files under the directory 
// d2, stored under /xmldirs/d2 in the Zip file. Put the new file zip.zip in the
// directory d3.
new ZipCreator(
  new AggregatingIterator(
    new EntityIteratorToZipEntryInfoIteratorAdapter(d1, 
      Directories.getDepthLastIterator(d1),
      new AbsoluteLocation("/dirs/d1")),
    new EntityIteratorToZipEntryInfoIteratorAdapter(d2, 
      new FilteringIterator(
        Directories.getDepthLastIterator(d2),
        new EFileNameExtensionFilter("xml")),
      new AbsoluteLocation("/xmldirs/d2"))),
  d3, "zip.zip").create();

// Build a Jar file containing all files and directories under the directory d1.
// Use a custom manifest. Put the new file jar.jar in the directory d2.
new JarCreator(
  new EntityIteratorToJarEntryInfoIteratorAdapter(d1, 
    Directories.getDepthLastIterator(d1)),
  d2, "jar.jar").
  setManifest(
    new Manifest(
      new ByteArrayInputStream(
        // Note the trailing \n after the last row...
        "Manifest-Version: 1.0\nCreated-By: 1.0 me\n".getBytes()))).create();

// Read the file d1/text2.txt from the Zip file texts.zip in the directory d
FileSystem fs = new ZipFileSystemBuilder().
  setZipFile(Directories.getFile(d, "texts.zip")).
  create();
try
{
  info("Contents of text2.txt: " +
    Files.readTextFile(
      Directories.getFile(
        fs.getRootDirectory(),
        new RelativeLocation("d1/text2.txt"))));
}
finally
{
  // Don't forget to close the Zip file system when you're done with it.
  fs.close();
}
  

// Extract all text files from the Zip file texts.zip in directory d into a
// directory tree under the directory d1.
ZipFiles.unzip(
  Directories.getFile(d, "texts.zip"),
  d1,
  new EFileNameExtensionFilter("txt"));