Constructor Detail

• TApplication

  public TApplication()

Method Detail

• run

  protected final int run(String[] args)
                   throws E extends Exception,
                          FsSyncException

  Runs the setup-work-sync life cycle. At first, this method calls setup(). Then, a loop is entered which calls work(java.lang.String[]) and (in a finally block) sync(). If work(java.lang.String[]) returns a negative integer, then the loop is repeated. Otherwise, the return value is used as the exit status of the VM.

  Note that calling sync() in a finally-block ensures that all unsynchronized changes to the contents of all federated file systems (i.e. archive files) get committed to their respective parent file system, even if work(java.lang.String[]) throws an exception.

  Throws:

  Exception - At the discretion of the work(java.lang.String[]) method.

  FsSyncException - At the discretion of the sync() method.

• setup

  protected void setup()

  Runs the setup phase.

  This method is called by run(java.lang.String[]) at the start of the life cycle. Its task is to configure the default behavior of the TrueZIP File* API in order to answer the following questions:

  • Which file suffixes shall get detected to indicate archive files and hence as virtual directories?
  • Which kind of temporary buffers shall get used?
  • Shall missing archive files and directory entries get automatically created whenever required?

  Note that the method body of the implementation in the class TApplication is empty! This means that the initial setup is not changed. The initial setup is determined by loading service classes from the class path and applying reasonable defaults if nothing is found.

  As an alternative to overriding this method, the setup may get changed in a sub class constructor. This would ensure it's changed exactly only once and not on every call to run(java.lang.String[]).

  Examples

  As the most simple use case, a client application might want to filter the initial setup for the archive file suffixes it wants to detect. This is done as follows:

  
   TFile.setDefaultArchiveDetector(
           new TArchiveDetector("ear|jar|war"));
   

  This will filter all file system drivers found on the class path in the initial setup so that only files with the pattern *.ear, *.jar or *.war (case ignoring) are detected as prospective archive files. If no file system driver is present for a named suffix in the initial setup, an IllegalArgumentException is thrown.

  The beauty of this simple example is that it does not require to change the compile time class path. For more advanced examples however, the file pom.xml needs to get edited so that the respective modules get added to the compile time class path.

  The constructors of the TFile class use the TArchiveDetector class to scan a path name for suffixes of archive files which shall be treated like virtual directories. You can either explicitly inject this ArchiveDetector dependency into a TFile constructor or you can rely on the value of the class property defaultArchiveDetector.

  By default, all new TFile objects will use a default TArchiveDetector which recognizes the canonical archive file suffixes registered by all archive driver modules which are present on the class path at run time - these can be configured by editing the file pom.xml.

  However, if you use the following statement, all TFile objects will use the given default TArchiveDetector which recognizes only the given canonical file suffixes for TAR, TAR.GZ, TAR.BZ2 and ZIP files as archive files and hence as virtual directories. This requires the JARs for the archive driver modules truezip-driver-tar and truezip-driver-zip to be present on the class path at compile time:

  
   TFile.setDefaultArchiveDetector(
           new TArchiveDetector(
               TArchiveDetector.NULL,
               new Object[][] {
                   { "tar", new TarDriver(IOPoolLocator.SINGLETON) },
                   { "tgz|tar.gz", new TarGZipDriver(IOPoolLocator.SINGLETON) },
                   { "tbz|tb2|tar.bz2", new TarBZip2Driver(IOPoolLocator.SINGLETON) },
                   { "zip", new ZipDriver(IOPoolLocator.SINGLETON)},
               }));
   

  Another typical use case is to recognize only Java artifacts.

  
   TFile.setDefaultArchiveDetector(
           new TArchiveDetector(
               "ear|jar|war",
               new JarDriver(IOPoolLocator.SINGLETON)));
   

  ... or an application file format.

  
   TFile.setDefaultArchiveDetector(
           new TArchiveDetector(
               "foo",
               new JarDriver(IOPoolLocator.SINGLETON)));
   

  ... or an encrypted application file format. This driver authenticates input archive files up to 512 KB using the Message Authentication Code (MAC) specified by the RAES file format. For larger input archive files, it just checks the CRC-32 value whenever an archive entry input stream is closed. CRC-32 has frequent collisions when compared to a MAC. However, it should not be feasible to make an undetectable modification. The driver also uses unencrypted temporary files for archive entries whenever required.

  
   TFile.setDefaultArchiveDetector(
           new TArchiveDetector(
               "bar",
               new SafeZipRaesDriver(
                   IOPoolLocator.SINGLETON,
                   KeyManagerLocator.SINGLETON)));
   

  If you're a bit paranoid, then you could use the following driver instead: This driver authenticates every input archive file using the Message Authentication Code (MAC) specified by the RAES file format, which makes it comparably slow. The driver also uses unencrypted temporary files for archive entries whenever required.

  
   TFile.setDefaultArchiveDetector(
           new TArchiveDetector(
               "bar",
               new ParanoidZipRaesDriver(
                   IOPoolLocator.SINGLETON,
                   KeyManagerLocator.SINGLETON)));
   

  And finally, if you're quite paranoid, then this driver is for you: This driver authenticates every input archive file using the Message Authentication Code (MAC) specified by the RAES file format, which makes it comparably slow. The driver also uses unencrypted byte arrays for temporary storage of archive entries whenever required. If you were completely paranoid, you would even want to use encrypted byte arrays or wipe them with nulls after use. However, then you would have to write this yourself! ;-)

  
   TFile.setDefaultArchiveDetector(
           new TArchiveDetector(
               "bar",
               new ParanoidZipRaesDriver(
                   new ByteArrayIOPoolService(2048),
                   KeyManagerLocator.SINGLETON)));
   

  Last but not least, the following class property controls whether archive files and their member directories get automatically created whenever required. The default value of this class property is true!

  
   TFile.setLenient(false);
   

• sync

  protected void sync()
               throws FsSyncException

  Runs the sync phase.

  This method is called by run(java.lang.String[]) in a finally-block after each call to work(java.lang.String[]). Its task is to commit any unsynchronized changes to the contents of archive files and purge all cached data so that third parties can safely interact with these archive files until the next access by this TrueZIP application.

  The implementation in the class TApplication simply calls TFile.umount().

  Throws:

  FsSyncWarningException - if only warning conditions occur. This implies that the respective parent file system has been updated with constraints, such as a failure to set the last modification time of the entry for the federated file system (i.e. archive file) in its parent file system.

  FsSyncException - if any error conditions occur. This implies loss of data!

• work

  protected abstract int work(String[] args)
                       throws E extends Exception

  Runs the work phase.

  This method is called by run(java.lang.String[]) at least once and repeatedly called until it returns a non-negative integer for use as the exist status of the VM. After this method, the sync() method is called in a finally-block.

  Avoid repeating this method and updating the same archive file upon each call! This would degrade the overall performance from O(n) to O(m*n), where m is the number of new or modified entries and n is the number of all entries in the archive file!

  Parameters:

  args - an array of arguments for this application.

  Returns:

  A negative integer in order to continue calling this method in a loop. Otherwise, the return value is used as the exit status of the VM.

  Throws:

  E extends Exception