Getting started with a Shell

This guide shows how to kick-start a TrueZIP application in a command line shell with the help of a Maven archetype. If you are using Eclipse, then please read the guide for Eclipse instead. If you are using NetBeans, then please read the guide for NetBeans instead.

Motivation

A typical issue for beginners is understanding the dependency of TrueZIP 7 on file system driver modules at run time: The modules TrueZIP File* and TrueZIP Path use a file system driver service locator singleton which scans the class path for file system driver services. These file system driver services are contained in file system driver modules. By adding the JAR artifacts of the file system driver modules to the run time class path of your application, you trigger the module TrueZIP File* to add their file system drivers to the initial set up of its archive detection.

Although it's straightforward, setting up the class path can be a daunting task for TrueZIP beginners, so a Maven archetype is provided as a template for TrueZIP File* applications. This archetype shows how to setup the run time dependencies and, as an alternative, how to avoid using the service locator by using dependency injection instead.

Prerequisites

You need to have the following software installed:

  • Apache Maven 3.0.3
  • JSE 6 for applications using the TrueZIP File* API.
  • JSE 7 for applications using the TrueZIP Path API.

Generate Maven Archetype

To generate the application archetype, type the following command in a shell while setting the groupId, artifactId and package properties to the appropriate values for your project:

$ mvn archetype:generate -B \
    -DarchetypeGroupId=de.schlichtherle.truezip \
    -DarchetypeArtifactId=truezip-archetype-file \
    -DarchetypeVersion=7.7.6 \
    -DgroupId=com.company \
    -DartifactId=project \
    -Dversion=0.1-SNAPSHOT \
    -Dpackage=com.company.project

Upon successful execution, a new directory with the value of the artifactId property as its name will have been created in the current directory. If you copy/paste the above command literally to a shell this would result in the following directory structure:

project
|-- pom.xml
`-- src
    `-- main
        `-- java
            `-- com
                `-- company
                    `-- project
                        |-- Application.java
                        |-- Cat.java
                        |-- Copy.java
                        |-- Pickr.java
                        `-- Tree.java

Explore Your Application

The project directory contains the following files:

pom.xml
This is the Maven Project Object Model (POM). The POM declares the properties of your project to Maven so that it can build, install and run it. Within the <project>/<dependencies> element is the declaration of the dependencies of your application, i.e. the JARs required to compile and run it. Each file system driver module on the run time class path adds to the initial set up of detected archive types by the TrueZIP File* and TrueZIP Path API as explained above, so please edit it later to meet your application requirements. For now, please leave this file alone.
src/main/java/com/company/project/Application.java
This abstract base class runs the setup-work-sync life cycle of a typical TrueZIP application. It overrides the method TApplication.setup() in order to customize the initial setup.
src/main/java/com/company/project/Cat.java
This command line utility recursively copies its file arguments to the standard output in order. If you name any archive file entries in the arguments, they get copied, too.

For example, if the JAR for the module truezip-driver-zip is present on the run time class path, you could use the argument archive.zip/readme.txt to print the contents of the entry readme.txt in the archive file archive.zip.

src/main/java/com/company/project/Copy.java
This command line utility recursively copies its first file or directory argument to its second file or directory argument. Instead of a directory, you can name any configured archive file type in the path names, too. If you name any archive files in the destination path name, they get automatically created.

For example, if the JAR for the module truezip-driver-zip is present on the run time class path and the destination path name is archive.zip, a ZIP file with this name gets created unless it already exists.

src/main/java/com/company/project/Pickr.java
This utility is only available with the archetype for the TrueZIP File* module. It llets you pick a file using a TFileChooser and prints it's path. Of course, TFileChooser can browse archive files, too.

For example, if the JAR for the module truezip-driver-zip is present on the run time class path and a ZIP file archive.zip exists, then you can double click it to browse its entries.

src/main/java/com/company/project/Tree.java
This command line utility prints the tree graph of the directory structure of its file or directory arguments to the standard output. Instead of a directory, you can name any configured archive file type as an argument, too.

For example, if the JAR for the module truezip-driver-zip is present on the run time class path and the path name argument is archive.zip and this file actually exists as a ZIP file, then the tree graph of the directory structure of this ZIP file gets printed.

Build And Run Your Application

To build and install your application in your local Maven repository, enter:

$ cd project
$ mvn clean install

Close to the end of the output of the Maven command, it should read [INFO] BUILD SUCCESS:

To run the main class Tree, enter:

$ mvn exec:java -Dexec.mainClass=com.company.project.Tree

This should produce a similar output to the following in the Console view:

.
|-- pom.xml
|-- src
|   `-- main
|       `-- java
|           `-- com
|               `-- company
|                   `-- project
|                       |-- Application.java
|                       |-- Cat.java
|                       |-- Copy.java
|                       |-- Pickr.java
|                       `-- Tree.java
`-- target
    |-- classes
    |   `-- com
    |       `-- company
    |           `-- project
    |               |-- Application.class
    |               |-- Cat.class
    |               |-- Copy.class
    |               |-- Pickr.class
    |               `-- Tree.class
    |-- generated-sources
    |   `-- annotations
    |-- maven-archiver
    |   `-- pom.properties
    |-- project-0.1-SNAPSHOT.jar
    |   |-- META-INF
    |   |   |-- MANIFEST.MF
    |   |   `-- maven
    |   |       `-- com.company
    |   |           `-- project
    |   |               |-- pom.xml
    |   |               `-- pom.properties
    |   `-- com
    |       `-- company
    |           `-- project
    |               |-- Application.class
    |               |-- Cat.class
    |               |-- Copy.class
    |               |-- Pickr.class
    |               `-- Tree.class
    `-- surefire

Note that the contents of the JAR file target/project-0.1-SNAPSHOT.jar get listed, too! This is because the configuration file pom.xml is set up to recognize JAR files as virtual directories by adding the module TrueZIP Driver ZIP with the artifactId truezip-driver-zip to the run time class path. You can change this by editing the configuration file pom.xml or the method Application.html.setup().

Edit Your Application

Now you're ready and set to edit your application to meet your requirements.

Mind that the class Application is just a template to show the setup-work-sync life cycle of a typical TrueZIP application: You don't need to use this class at all as long as your application implements this life cycle somehow.

Finally, don't forget to configure the run time dependencies in the pom.xml unless your application explicitly configures the archive detection in its setup phase.