Skip to main content

Source code file content

Revision: 162

Added tag truezip-7.7.3 for changeset aa266d47404e
» Project Revision History

» Checkout URL

web / faq.html

Size: 50922 bytes, 1 line
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <link href="./css/prettify.css" type="text/css" rel="stylesheet"/>
    <script src="./js/prettify.js" type="text/javascript"></script>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
    <title>TrueZIP - Frequently Asked Questions</title>
    <style type="text/css" media="all">
      @import url("./css/site.css");
    </style>
    <link rel="stylesheet" href="./css/print.css" type="text/css" media="print"/>
    <meta name="Date-Revision-yyyymmdd" content="20130719"/>
    <meta http-equiv="Content-Language" content="en"/>
          <script type="text/javascript">
      var _gaq = _gaq || [];
      _gaq.push(['_setAccount', 'UA-25500668-1']);
      _gaq.push(['_trackPageview']);
      (function() {
        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
      })();
    </script>
                  <script>
        (function() {
          var cx = '003580521944097984334:0t01zxsxy6y';
          var gcse = document.createElement('script'); gcse.type = 'text/javascript'; gcse.async = true;
          gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
              '//www.google.com/cse/cse.js?cx=' + cx;
          var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(gcse, s);
        })();
      </script>
                                                          
<link title="The TrueZIP Blog - Announcements Feed" rel="alternate" type="application/rss+xml" href="http://truezip.schlichtherle.de/category/announcements/feed/"/>
                      
  </head>
  <body class="composite" onload="prettyPrint()">
    <div id="banner">
                    <div id="bannerLeft">
                TrueZIP
                </div>
                                <div id="gcse-search-form" class="gcse-searchbox-only"></div>
            <div class="clear"><hr/></div>
    </div>
    <div id="breadcrumbs">
            
                                  <div class="xleft">
        <span id="projectVersion">Version: 7.7.3</span>
                  |                         <a href="index.html" title="TrueZIP">TrueZIP</a>
      &raquo;
        Frequently Asked Questions
              </div>
            <div class="xright">        
                        </div>
      <div class="clear"><hr/></div>
    </div>
    <div id="leftColumn">
      <div id="navcolumn">
              
                                                   <h5>Documentation</h5>
                  <ul>
                  <li class="none">
                          <a href="index.html" title="About">About</a>
            </li>
                  <li class="none">
                          <a href="features.html" title="Key Features">Key Features</a>
            </li>
                                                                                                                                            <li class="collapsed">
                          <a href="usecases/index.html" title="Use Cases">Use Cases</a>
                  </li>
                                                                                                                                            <li class="collapsed">
                          <a href="kick-start/index.html" title="Getting Started">Getting Started</a>
                  </li>
                                                                                                                                    <li class="expanded">
                          <a href="help.html" title="Getting Help">Getting Help</a>
                    <ul>
                      <li class="none">
                          <a href="apidocs/index.html" title="Javadoc">Javadoc</a>
            </li>
                      <li class="none">
            <strong>Frequently Asked Questions</strong>
          </li>
                      <li class="none">
                          <a href="mail-lists.html" title="Mailing Lists">Mailing Lists</a>
            </li>
                      <li class="none">
                          <a href="issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
            </li>
              </ul>
        </li>
                  <li class="none">
                          <a href="concepts.html" title="Basic Concepts">Basic Concepts</a>
            </li>
                  <li class="none">
                          <a href="glossary.html" title="Glossary">Glossary</a>
            </li>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        <li class="collapsed">
                          <a href="6/index.html" title="TrueZIP 6 (Obsolete)">TrueZIP 6 (Obsolete)</a>
                  </li>
          </ul>
                       <h5>External Resources</h5>
                  <ul>
                  <li class="none">
                          <a href="http://java.net/jira/browse/TRUEZIP#selectedTab=com.atlassian.jira.plugin.system.project:roadmap-panel" class="externalLink" title="Road Map">Road Map</a>
            </li>
                  <li class="none">
                          <a href="http://java.net/jira/browse/TRUEZIP#selectedTab=com.atlassian.jira.plugin.system.project:changelog-panel" class="externalLink" title="Change Log">Change Log</a>
            </li>
                  <li class="none">
                          <a href="http://truezip.schlichtherle.de" class="externalLink" title="The TrueZIP Blog">The TrueZIP Blog</a>
            </li>
                  <li class="none">
                          <a href="http://java.net/projects/truezip" class="externalLink" title="Developer Site">Developer Site</a>
            </li>
          </ul>
                       <h5>Parent Module</h5>
                                 <h5>Sub-Modules</h5>
                  <ul>
                  <li class="none">
                          <a href="truezip-archetype/index.html" title="TrueZIP Archetype">TrueZIP Archetype</a>
            </li>
                  <li class="none">
                          <a href="truezip-driver/index.html" title="TrueZIP Driver">TrueZIP Driver</a>
            </li>
                  <li class="none">
                          <a href="truezip-extension/index.html" title="TrueZIP Extension">TrueZIP Extension</a>
            </li>
                  <li class="none">
                          <a href="truezip-file/index.html" title="TrueZIP File*">TrueZIP File*</a>
            </li>
                  <li class="none">
                          <a href="truezip-kernel/index.html" title="TrueZIP Kernel">TrueZIP Kernel</a>
            </li>
                  <li class="none">
                          <a href="truezip-samples/index.html" title="TrueZIP Samples">TrueZIP Samples</a>
            </li>
                  <li class="none">
                          <a href="truezip-swing/index.html" title="TrueZIP Swing">TrueZIP Swing</a>
            </li>
                  <li class="none">
                          <a href="truezip-path/index.html" title="TrueZIP Path">TrueZIP Path</a>
            </li>
          </ul>
                       <h5>Reports</h5>
                  <ul>
                                                                                                                                                                                                                                                                                                                                                  <li class="collapsed">
                          <a href="project-info.html" title="Project Information">Project Information</a>
                  </li>
                                                                                      <li class="collapsed">
                          <a href="project-reports.html" title="Project Reports">Project Reports</a>
                  </li>
          </ul>
                     
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
  <div class="paypalButton">
    <input name="cmd" value="_s-xclick" type="hidden"/>
    <input name="hosted_button_id" value="2QSQY9ECYES9E" type="hidden"/>
    <input style="border: 0" alt="PayPal - The safer, easier way to pay online!" name="submit" src="https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif" type="image"/>
  </div>
</form>
                                
                              </div>
    </div>
    <div id="bodyColumn" class="content">
      <div id="contentBox">
                                      <!-- - Copyright (C) 2005-2013 Schlichtherle IT Services
  -
  - All rights reserved. This program and the accompanying materials
  - are made available under the terms of the Eclipse Public License v1.0
  - which accompanies this distribution, and is available at
  - http://www.eclipse.org/legal/epl-v10.html --><div class="section">
<h2><a name="top">Frequently Asked Questions</a><a name="Frequently_Asked_Questions"></a></h2>
<p><b>TrueZIP File* API</b></p>
<ol style="list-style-type: decimal">
<li><a href="#cannotReadArchive">
                When trying to read an archive file, I get an exception saying
                I cannot read directories.
                What's wrong?
            </a></li>
<li><a href="#cannotWriteArchive">
                When trying to write an archive file, I get an exception saying
                I cannot write directories.
                What's wrong?
            </a></li>
<li><a href="#cannotCopyFileToArchive">
                Copying a file to an archive file does not seem to work.
                What's wrong?
            </a></li>
<li><a href="#filterTArchiveDetector">
                The set of detected suffixes for archive files is too large.
                How can I change it?
            </a></li>
<li><a href="#installDriverFile">
                How to install a (custom) file system driver?
            </a></li>
<li><a href="#cannotListArchive">
                The API is not detecting an archive file as a virtual directory.
                What's wrong?
            </a></li>
<li><a href="#ignoreArchiveFile">
                The API should <i>not</i> detect an individual archive file
                as a virtual directory.
                How can I do this?
            </a></li>
<li><a href="#corruptedArchive">
                When I create or update archive entries,
                the modified archive file gets corrupted.
                What's wrong?
            </a></li>
<li><a href="#http">
                How can I access an archive file via HTTP(S)?
            </a></li>
<li><a href="#accessAbsoluteEntryName">
                How can I access entries with absolute entry names in archive
                files?
            </a></li></ol>
<p><b>TrueZIP Path API</b></p>
<ol style="list-style-type: decimal">
<li><a href="#interoperability">
                Can I use the APIs of the modules TrueZIP Path and
                TrueZIP File* concurrently?
            </a></li>
<li><a href="#whichCopy">
                The NIO.2 API and the TrueZIP File* API both provide a copy
                method. Which one should I use?
            </a></li>
<li><a href="#installDriverPath">
                How to install a (custom) file system driver?
            </a></li>
<li><a href="#ignoreArchivePath">
                The API should <i>not</i> detect an individual archive file
                as a virtual directory.
                How can I do this?
            </a></li></ol>
<p><b>General Questions</b></p>
<ol style="list-style-type: decimal">
<li><a href="#whereAreNews">Where are the latest news and announcements?</a></li>
<li><a href="#no-maven">Do I have to use Maven to use TrueZIP?</a></li>
<li><a href="#whereIsJavadoc">Where is the Javadoc?</a></li>
<li><a href="#binaryCompatibility">
                How does TrueZIP deal with binary compatibility?
            </a></li>
<li><a href="#nestedArchives">
                How does TrueZIP deal with the compression of nested archive
                files like e.g. <tt>app.war/WEB-INF/lib/lib.jar</tt>?
            </a></li>
<li><a href="#absoluteEntryName">
                How does TrueZIP deal with entries with absolute entry names in
                archive files?
            </a></li>
<li><a href="#normalizeEntryName">
                How does TrueZIP deal with entries with dot <tt>&quot;.&quot;</tt>
                or dot-dot <tt>&quot;..&quot;</tt> segments in archive files?
            </a></li>
<li><a href="#windowsSeparator">
                How does TrueZIP deal with entries which use <tt>&quot;\&quot;</tt>
                as the separator character in archive files?
            </a></li>
<li><a href="#duplicateEntries">
                How does TrueZIP deal with duplicate entries in archive files?
            </a></li>
<li><a href="#support">
                I have another question or issue.
                How do I get it responded and resolved?
            </a></li></ol></div>
<div class="section">
<h2>TrueZIP File* API<a name="TrueZIP_File_API"></a></h2>
<dl>
<dt><a name="cannotReadArchive">
                When trying to read an archive file, I get an exception saying
                I cannot read directories.
                What's wrong?
            </a></dt>
<dd>
                
<p>
                    When configured correctly, the File* API will treat an
                    archive file like a virtual directory (that's what TrueZIP
                    is all about).
                    Like with plain directories, applications cannot read or
                    write virtual directories using an input or output stream.
               </p>
                
<p>
                    Use one of the 
                    <tt>list*(*)</tt> methods in the
                    <tt>TFile</tt> class instead.
               </p>
                
<p>
                    For example, to list the contents of the top level
                    (virtual) directory of the archive file
                    <tt>archive.zip</tt>, you could use...
               </p>
                
<div class="source">
<pre>TFile[] entries = new TFile(&quot;archive.zip&quot;).listFiles();</pre></div>
            <hr /></dd>
<dt><a name="cannotWriteArchive">
                When trying to write an archive file, I get an exception saying
                I cannot write directories.
                What's wrong?
            </a></dt>
<dd>
                
<p>
                    When configured correctly, the File* API will treat an
                    archive file like a virtual directory (that's what TrueZIP
                    is all about).
                    Like with plain directories, applications cannot read or
                    write virtual directories using an input or output stream.
               </p>
                
<p>
                    Use one of the 
                    <tt>mkdir*(*)</tt> methods in the
                    <tt>TFile</tt> class or directly write to the entry
                    within the archive file using a
                    <tt>TFileOutputStream</tt> instead.
                    For example, to (over)write the entry 
                    <tt>entry</tt> within the archive file
                    <tt>archive.zip</tt>, you could use...
               </p>

<div class="source">
<pre>
OutputStream out = new TFileOutputStream(&quot;archive.zip/entry&quot;);
try {
    ... // write something here
} finally {
    out.close();
}
</pre></div>
                
<p>
                    This would work even if
                    <tt>archive.zip</tt> would not initially exist unless
                    <tt>TFile.setLenient(false)</tt> had been called by
                    your application before.
                    In this case, you would need to create the archive file
                    <tt>archive.zip</tt> in advance by using...
               </p>
                
<div class="source">
<pre>new TFile(&quot;archive.zip&quot;).mkdir(false);</pre></div>
            <hr /></dd>
<dt><a name="cannotCopyFileToArchive">
                Copying a file to an archive file does not seem to work.
                What's wrong?
            </a></dt>
<dd>
                
<p>
                    Users often assume that when copying a file to an archive
                    file, the File* API would automatically complete the path
                    name of the destination archive file so that it ends with
                    the base name of the source file.
                    This is probably assumed because that's how it works with
                    command line utilities like 
                    <tt>cp</tt> on POSIX or
                    <tt>copy</tt> on Windows.
                    However, this is not true:
                    The File* API does 
                    <i>never</i> do path name completion.
                    Hence, the following code may behave unexpectedly:
               </p>

<div class="source">
<pre>
TFile src = new TFile(string1); // e.g. &quot;file&quot;
TFile dst = new TFile(string2); // e.g. &quot;archive.zip&quot;
src.cp_rp(dst);
</pre></div>
                
<p>
                    If successful, this would only result in a verbatim copy of 
                    <tt>file</tt> to 
                    <tt>archive.zip</tt>, which is probably unexpected.
                    However, the way the copy command line utilities work can
                    be easily emulated by using the following instead:
               </p>

<div class="source">
<pre>
TFile src = new TFile(string1); // e.g. &quot;file&quot;
TFile dst = new TFile(string2); // e.g. &quot;archive.zip&quot;
if (TFile.isLenient() &amp;&amp; dst.isArchive() || dst.isDirectory())
    dst = new TFile(dst, src.getName());
src.cp_rp(dst);
</pre></div>
                
<p>
                    This will append the base name of the source path to the
                    destination path if either the destination path name ends
                    with a recognized archive file suffix like e.g. &quot;.zip&quot; or
                    if the destination file system entry already exists as a
                    directory.
                    If 
                    <tt>TFile.setLenient(false)</tt> is never called by
                    your application, then you could shorten this to...
               </p>

<div class="source">
<pre>
TFile src = new TFile(string1); // e.g. &quot;file&quot;
TFile dst = new TFile(string2); // e.g. &quot;archive.zip&quot;
if (dst.isArchive() || dst.isDirectory())
    dst = new TFile(dst, src.getName());
src.cp_rp(dst);
</pre></div>
                
<p>
                    If you don't like path name completion for non-existent
                    files which just look like archive files according to their
                    file name, then you could even shorten this to...
               </p>

<div class="source">
<pre>
TFile src = new TFile(string1); // e.g. &quot;file&quot;
TFile dst = new TFile(string2); // e.g. &quot;archive.zip&quot;
if (dst.isDirectory())
    dst = new TFile(dst, src.getName());
src.cp_rp(dst);
</pre></div>
            <hr /></dd>
<dt><a name="filterTArchiveDetector">
                The set of detected suffixes for archive files is too large.
                How can I change it?
            </a></dt>
<dd>
                
<p>
                    You can easily filter the set of canonical suffixes
                    installed by the file system driver modules on the run time
                    class path.
                    For example, the TrueZIP Driver ZIP module will install a
                    large set of canonical file suffixes for ZIP files.
                    If all you want is to detect <tt>*.zip</tt> files
                    however, you can do so easily using the following statement:
               </p>

<div class="source">
<pre>
TConfig.get().setArchiveDetector(new TArchiveDetector(&quot;zip&quot;));
</pre></div>
                
<p>
                    Check the
                    <a href="kick-start/index.html">Maven archetypes</a> for
                    more options and to help you get started with this quickly.
               </p>
            <hr /></dd>
<dt><a name="installDriverFile">
                How to install a (custom) file system driver?
            </a></dt>
<dd>
                
<p>
                    Make the following call early in your application:
               </p>

<div class="source">
<pre>
TConfig.get().setArchiveDetector(
        new TArchiveDetector(
            TArchiveDetector.NULL,
            &quot;zip&quot;, new ZipDriver(IOPoolLocator.SINGLETON)));
</pre></div>
                
<p>
                    This example presumes that you are going to map the file
                    suffix <tt>.zip</tt> to the <tt>ZipDriver</tt>.
                    This is actually the default if you add the JAR artifact of
                    the module TrueZIPDriverZIP to the run time
                    class path.
               </p>
                
<p>
                    Furthermore, this example presumes that you want no other
                    archive file suffixes to get detected, hence the use of
                    <a href="apidocs/de/schlichtherle/truezip/file/TArchiveDetector.html#NULL"><tt>TArchiveDetector.NULL</tt></a>
                    as the decorated archive detector.
                    The class <tt>TArchiveDetector</tt> has many different
                    constructors.
                    Check the
                    <a href="apidocs/de/schlichtherle/truezip/file/TArchiveDetector.html">Javadoc</a>
                    to make sure you get what you need.
               </p>
            <hr /></dd>
<dt><a name="cannotListArchive">
                The API is not detecting an archive file as a virtual directory.
                What's wrong?
            </a></dt>
<dd>
                
<p>
                    Most likely the TrueZIP File* module is not set up
                    correctly in order to detect the file suffix of the archive
                    type you want to access.
                    To make sure it does, make the following call early in your
                    application:
               </p>

<div class="source">
<pre>
TConfig.get().setArchiveDetector(
        new TArchiveDetector(
            TArchiveDetector.NULL,
            new Object[][] {
                { &quot;tar&quot;, new TarDriver(IOPoolLocator.SINGLETON) },
                { &quot;tgz|tar.gz&quot;, new TarGZipDriver(IOPoolLocator.SINGLETON) },
                { &quot;tbz|tb2|tar.bz2&quot;, new TarBZip2Driver(IOPoolLocator.SINGLETON) },
                { &quot;zip&quot;, new ZipDriver(IOPoolLocator.SINGLETON)},
            }));
</pre></div>
                
<p>
                    Check the
                    <a href="kick-start/index.html">Maven archetypes</a> for
                    more options and to help you get started with this quickly.
               </p>
            <hr /></dd>
<dt><a name="ignoreArchiveFile">
                The API should <i>not</i> detect an individual archive file
                as a virtual directory.
                How can I do this?
            </a></dt>
<dd>
                
<p>
                    Every now and then you might want to treat an archive file
                    like a regular file rather than a virtual directory.
                    For example, when trying to obtain the length of the
                    archive file in bytes.
                    You would normally do this by calling the method
                    <tt>File.length()</tt>.
                    However, if the <tt>File</tt> object is an instance of
                    the <tt>TFile</tt> class and the path has been detected
                    to name a valid archive file, then this method would always
                    return zero.
                    This is because you might have changed the archive file and
                    then it would be impossible to return a precise result
                    until the changes have been committed to the target archive
                    file.
               </p>
                
<p>
                    You can easily solve this issue by committing any pending
                    changes and then calling <tt>length()</tt> on a new
                    <tt>TFile</tt> object which has been instructed to
                    ignore an archive file name suffix in the last path element.
                    This could look as follows:
               </p>

<div class="source">
<pre>
// Note that the actual path may refer to anything, even a nested archive file.
TFile inner = new TFile(&quot;outer.zip/inner.zip&quot;);
TFile file = inner.toNonArchiveFile(); // convert - since TrueZIP 7.5
... // there may be some I/O here
TVFS.umount(inner); // unmount potential archive file
// Now you can safely do any I/O to $file.
long length = file.length();
</pre></div>
                
<p>
                    Note that the path <tt>outer.zip/inner.zip</tt> refers
                    to a nested archive file, so using the <tt>TFile*</tt>
                    classes is required to access it.
               </p>
                
<p>
                    Last but not least, using the object <tt>file</tt>
                    for any I/O bypasses any state associated with the path
                    <tt>outer.zip/inner.zip</tt> in the TrueZIP Kernel.
                    This could result in an inconsistent state of the federated
                    file system space and may even incur <i>loss of data</i>!
                    In order to avoid this, it's a good idea <i>not</i> to
                    access the object <tt>inner</tt> again until you are
                    done with the object <tt>file</tt>.
               </p>
            <hr /></dd>
<dt><a name="corruptedArchive">
                When I create or update archive entries,
                the modified archive file gets corrupted.
                What's wrong?
            </a></dt>
<dd>
                
<p>
                    The TrueZIP Kernel module applies neat caching and
                    buffering strategies for archive entries.
                    So whenever your application creates or updates archive
                    entries, the changes need to get committed to the archive
                    file when done.
                    On certain events, e.g. whenever the JVM terminates
                    normally with or without a throwable (= doesn't crash),
                    this happens automatically.
                    However, in a long running application you may want to do
                    this manually in order to allow <i>third parties</i> to
                    access the archive file.
                    The term <i>third party</i> in this context includes any
                    other process in the operating system, the plain
                    <tt>File*</tt> API and even a <tt>TFile</tt> object
                    which uses <tt>TArchiveDetector.NULL</tt>.
               </p>
                
<p>
                    Committing any unsynchronized changes to all archive files
                    is easy - just call...
               </p>
                
<div class="source">
<pre>TVFS.umount();</pre></div>
                
<p>
                    Please have a look at the method's
                    <a href="apidocs/de/schlichtherle/truezip/file/TVFS.html#umount">Javadoc</a>
                    for more options.
               </p>
            <hr /></dd>
<dt><a name="http">
                How can I access an archive file via HTTP(S)?
            </a></dt>
<dd>
                
<p>
                    The TrueZIP File* API can only access the platform file
                    system because the <tt>TFile</tt> class extends the
                    <tt>File</tt> class.
                    To access an archive file via HTTP(S) or any other procotol
                    scheme, you have two options:
               </p>
                
<ul>
                
<li>If your application uses a JSE&#xa0;7 compliant JVM,
                    you can simply use the API of the
                    <a href="truezip-path/index.html">TrueZIP Path</a>
                    module.</li>
                
<li>Otherwise, you can use the API of the
                    <a href="truezip-kernel/index.html">TrueZIP Kernel</a>
                    module.
               </li>
               </ul>
            <hr /></dd>
<dt><a name="accessAbsoluteEntryName">
                How can I access entries with absolute entry names in archive
                files?
            </a></dt>
<dd>
                
<p>
                    You can't because there is no addressing scheme for this.
                    For example, the expression
                    <tt>new TFile(&quot;archive.zip/entry&quot;)</tt> gets decomposed
                    into the file system path <tt>archive.zip</tt> as the
                    mount point of the archive file and the relative entry name
                    <tt>entry</tt> as the entry name within this archive
                    file.
                    There's no expression to address the absolute entry name
                    <tt>/entry</tt> within the archive file instead.
                    Even if you tried
                    <tt>new TFile(&quot;archive.zip//entry&quot;)</tt>, it would
                    just get normalized to the previous expression.
               </p>
                
<p>
                    See also <a href="#absoluteEntryName">here</a>.
               </p>
            </dd></dl></div>
<div class="section">
<h2>TrueZIP Path API<a name="TrueZIP_Path_API"></a></h2>
<dl>
<dt><a name="interoperability">
                Can I use the APIs of the modules TrueZIP Path and
                TrueZIP File* concurrently?
            </a></dt>
<dd>
                
<p>
                    Absolutely yes, because both module APIs are just facades
                    for the TrueZIP Kernel.
                    The NIO.2 API defines some methods for the interoperability
                    of <tt>File</tt> and <tt>Path</tt> objects:
               </p>
                
<ul>
                    
<li>
                        <tt>Path.toFile()</tt> returns a <tt>File</tt>
                        object for this <tt>Path</tt>.
                        However, according to the interface contract for this
                        method, it's supposed to work with the default file
                        system provider only (e.g. if it's a
                        <tt>WindowsPath</tt>).
                   </li>
                    
<li>
                        <tt>File.toPath()</tt> returns a <tt>Path</tt>
                        object for this <tt>File</tt>.
                        However, according to the interface contract for this
                        method, the returned object is associated with the
                        default file system provider (e.g. it's a
                        <tt>WindowsPath</tt>).
                        Furthermore, this method puts a compile time dependency
                        on the NIO.2 API.
                   </li>
               </ul>
                
<p>
                    To solve these issues, in TrueZIP this is implemented as
                    follows:
               </p>
                
<ul>
                    
<li>
                        <tt>TPath.toFile()</tt> returns a <tt>TFile</tt>
                        object for this <tt>TPath</tt>.
                        This works for any (virtual) file system.
                   </li>
                    
<li>
                        To avoid a compile time dependency in the TrueZIP File*
                        module on the TrueZIP Path module,
                        <tt>TFile.toPath()</tt> throws an
                        <tt>UnsupportedOperationException</tt>.
                        To create a <tt>TPath</tt> from a
                        <tt>File</tt> object, call
                        <tt>new TPath(File)</tt> instead.
                        Note that this works for plain <tt>File</tt>
                        objects too, not just <tt>TFile</tt> objects.
                   </li>
               </ul>
             <hr /></dd>
<dt><a name="whichCopy">
                The NIO.2 API and the TrueZIP File* API both provide a copy
                method. Which one should I use?
            </a></dt>
<dd>
                
<p>
                    Currently, the NIO.2 API supports only the copying of a
                    single file: <tt>Files.copy(Path, Path, CopyOption)</tt>.
                    Unfortunately, these methods use a simple
                    read-then-write-in-a-loop implementation which results in
                    bad performance.
                    Furthermore, there are no methods for recursive copying of
                    directory trees, so you'ld have to write this yourselve.
               </p>
                
<p>
                    With TrueZIP however, you can easily &quot;back out&quot;
                    from a <tt>TPath</tt> object to a <tt>TFile</tt>
                    object to use the advanced copy methods of the TrueZIP
                    File* API.
                    So instead of calling...
               </p>

<div class="source">
<pre>
Path src = ...
Path dst = ...
Files.copy(src, dst, REPLACE_EXISTING);
</pre></div>
                
<p>
                    You could call...
               </p>

<div class="source">
<pre>
Path src = ...
Path dst = ...
TFile.cp(src.toFile(), dst.toFile());
</pre></div>
                
<p>
                    in order to benefit from its superior performance.
                    Likewise, you could call any other
                    <tt>TFile.cp*(*)</tt> method, e.g.
                    <tt>TFile.cp_r(File src, File dst, TArchiveDetector detector)</tt>
                    for recursive copying of a directory tree.
               </p>
            <hr /></dd>
<dt><a name="installDriverPath">
                How to install a (custom) file system driver?
            </a></dt>
<dd>
                
<p>
                    In exactly the same way as with the module
                    TrueZIPFile*,
                    see <a href="#installDriverFile">here</a>.
               </p>
            <hr /></dd>
<dt><a name="ignoreArchivePath">
                The API should <i>not</i> detect an individual archive file
                as a virtual directory.
                How can I do this?
            </a></dt>
<dd>
                
<p>
                    Every now and then you might want to treat an archive file
                    like a regular file rather than a virtual directory.
                    For example, when trying to obtain the length of the
                    archive file in bytes.
                    You would normally do this by calling the method
                    <tt>Files.size(Path)</tt>.
                    However, if the <tt>Path</tt> object is an instance of
                    the <tt>TPath</tt> class and the path has been detected
                    to name a valid archive file, then this method would always
                    return zero.
                    This is because you might have changed the archive file and
                    then it would be impossible to return a precise result
                    until the changes have been committed to the target archive
                    file.
               </p>
                
<p>
                    You can easily solve this issue by committing any pending
                    changes and then calling <tt>Files.size(Path)</tt> with
                    a new <tt>TPath</tt> object which has been instructed to
                    ignore an archive file name suffix in the last path element.
                    This could look as follows:
               </p>

<div class="source">
<pre>
TPath inner = new TPath(&quot;outer.zip/inner.zip&quot;);
TPath path = inner.toNonArchivePath(); // convert - since TrueZIP 7.5
... // there may be some I/O here
inner.getFileSystem().close(); // unmount potential archive file
// Now you can safely do any I/O to $path.
long size = Files.size(path);
</pre></div>
                
<p>
                    Note that the path <tt>outer.zip/inner.zip</tt> refers
                    to a nested archive file, so using the <tt>TPath</tt>
                    class is required to access it.
               </p>
                
<p>
                    Last but not least, using the object <tt>path</tt>
                    for any I/O bypasses any state associated with the path
                    <tt>outer.zip/inner.zip</tt> in the TrueZIP Kernel.
                    This could result in an inconsistent state of the federated
                    file system space and may even incur <i>loss of data</i>!
                    In order to avoid this, it's a good idea <i>not</i> to
                    access the object <tt>inner</tt> again until you are
                    done with the object <tt>path</tt>.
               </p>
            </dd></dl></div>
<div class="section">
<h2>General Questions<a name="General_Questions"></a></h2>
<dl>
<dt><a name="whereAreNews">Where are the latest news and announcements?</a></dt>
<dd>
                
<p>
                    Starting from version 7.0, the TrueZIP project has it's
                    own blog for announcements, release notes, feature show
                    cases and more named
                    <a class="externalLink" href="http://truezip.schlichtherle.de">The TrueZIP Blog</a>.
               </p>
            <hr /></dd>
<dt><a name="no-maven">Do I have to use Maven to use TrueZIP?</a></dt>
<dd>
                
<p>
                    Absolutely not!
                    To learn about your options, please read the article
                    <a href="kick-start/no-maven.html">Using TrueZIP Without Maven</a>.
               </p>
            <hr /></dd>
<dt><a name="whereIsJavadoc">Where is the Javadoc?</a></dt>
<dd>
                
<p>
                    You can find the Javadoc for the entire TrueZIP API
                    including all modules in the navigation bar by clicking
                    <i>Project Reports</i> -&gt; <i>Project Reports</i> -&gt;
                    <i>JavaDocs</i>, or you could simply click
                    <a href="apidocs/index.html">here</a>.
               </p>
            <hr /></dd>
<dt><a name="binaryCompatibility">
                How does TrueZIP deal with binary compatibility?
            </a></dt>
<dd>
                
<p>
                    TrueZIP uses the same version numbering scheme like Maven,
                    i.e.
                    <tt>&lt;major&gt;.&lt;minor&gt;.&lt;incremental&gt;-&lt;qualifier&gt;</tt>.
                    Within the same major version number, binary compatibility
                    should be retained so that recompilation of a client
                    application should not be necessary.
               </p>
                
<p>
                    However, there is one exception:
                    Binary compatibility may be broken in a subsquent release
                    if all of the following conditions apply:
               </p>
                
<ol style="list-style-type: decimal">
                
<li>A feature's design is broken.</li>
                
<li>The feature is assumed to be rarely used by client
                    applications or the implications of not changing it are
                    considered to be unacceptable.</li>
                
<li>This issue is documented as a ticket in the project's
                    <a class="externalLink" href="http://java.net/jira/browse/TRUEZIP">Issue Tracking System</a>
                    (ITS) with the tag <tt>binary-compatibility</tt>.</li>
                
<li>A workaround is explained in the ITS ticket.</li>
                
<li>The ITS ticket is referenced in the Release Notes.</li>
               </ol>
                
<p>
                    In case your client application is affected by a change and
                    the documented workaround is unacceptable for any reason,
                    please address this using the ITS at
                    <a class="externalLink" href="http://java.net/jira/browse/TRUEZIP">http://java.net/jira/browse/TRUEZIP</a>.
               </p>
            <hr /></dd>
<dt><a name="nestedArchives">
                How does TrueZIP deal with the compression of nested archive
                files like e.g. <tt>app.war/WEB-INF/lib/lib.jar</tt>?
            </a></dt>
<dd>
                
<p>
                    With the advent of release 7.1, TrueZIP implements a new
                    strategy to avoid compressing already compressed archive
                    files in an enclosing archive file again.
                    In contrast, the old stragegy of TrueZIP 7.0 and earlier
                    was to compress everything - even if it was already
                    compressed.
               </p>
                
<p>
                    The new strategy results in a better overall compression
                    ratio than the old strategy because compressing already
                    compressed data again just inflates the data a bit because
                    of some algorithm specific overhead.
               </p>
                
<p>
                    For the example in the question, the new strategy uses the
                    DEFLATE method to compress the entries of the inner archive
                    file <tt>lib.jar</tt> while it uses the STORE method
                    for the corresponding entry <tt>WEB-INF/lib/lib.jar</tt>
                    within the outer archive file <tt>app.war</tt>.
                    This behavior is in conformance to the JEE specs.
               </p>
                
<p>
                    The new strategy is implemented by the archive drivers, so
                    it works best with all supported archive types.
                    For example, when storing a TAR file within a ZIP file,
                    the ZIP entry for the TAR file would use the DEFLATE
                    method because the TAR driver knows that plain TAR
                    files are not compressed.
                    In contrast, when storing a TAR.GZ file within a ZIP file,
                    the ZIP entry for the TAR.GZ file would use the STORE
                    method because the TAR.GZ driver knows that TAR.GZ
                    files are already compressed.
               </p>
            <hr /></dd>
<dt><a name="absoluteEntryName">
                How does TrueZIP deal with entries with absolute entry names in
                archive files?
            </a></dt>
<dd>
                
<p>
                    As answered <a href="#accessAbsoluteEntryName">here</a>,
                    you cannot access entries with absolute entry names in
                    archive files.
                    This implies that you cannot create archive files which
                    contain entries with absolute entry names.
               </p>
                
<p>
                    However, you can use TrueZIP to read, modify or delete
                    archive files which contain entries with absolute entry
                    names:
                    If you use TrueZIP to modify an archive file which
                    contains entries with absolute entry names, these entry 
                    names are preserved.
                    Likewise, an archive file can get deleted like any empty
                    directory if it contains only entries with absolute entry
                    names.
               </p>
            <hr /></dd>
<dt><a name="normalizeEntryName">
                How does TrueZIP deal with entries with dot <tt>&quot;.&quot;</tt>
                or dot-dot <tt>&quot;..&quot;</tt> segments in archive files?
            </a></dt>
<dd>
                
<p>
                    Wherever possible, redundant segments are removed by a
                    normalization of the entry name
                    before the corresponding archive entry is mounted into the
                    file system.
                    When updating the archive file however, the original
                    archive entry name is preserved.
                    If a dot-dot segment remains at the start of the entry name,
                    the corresponding entry will not be accessible by the
                    application, but preserved with its original entry name
                    upon an update of its archive file.
               </p>
            <hr /></dd>
<dt><a name="windowsSeparator">
                How does TrueZIP deal with entries which use <tt>&quot;\&quot;</tt>
                as the separator character in archive files?
            </a></dt>
<dd>
                
<p>
                    Any occurence of this illegal separator character is
                    replaced by the correct separator character <tt>&quot;/&quot;</tt>
                    before the entry name is
                    <a href="#normalizeEntryName">normalized</a> and the
                    corresponding archive entry is mounted into the file system.
                    When updating the archive file however, the original
                    archive entry name is preserved.
               </p>
            <hr /></dd>
<dt><a name="duplicateEntries">
                How does TrueZIP deal with duplicate entries in archive files?
            </a></dt>
<dd>
                
<p>
                    When mounting an archive file system, TrueZIP 7.1 and later
                    use <i>covariant file system entries</i> in order to enable
                    an application to access archive entries of different types
                    (FILE, DIRECTORY, SYMLINK or SPECIAL) which share the same
                    <a href="#normalizeEntryName">normalized</a> entry name.
               </p>
                
<p>
                    For example, the ZIP and TAR file formats use a trailing
                    slash <tt>'/'</tt> character in entry names to indicate
                    a directory entry.
                    In case an archive file contains two entries which, after
                    normalization of their name, differ only in a trailing
                    slash character, then both archive entries are mounted into
                    a covariant file system entry for the otherwise equal
                    normalized entry name.
                    Then, an application can read the contents of the file
                    entry by using e.g.
                    <a href="apidocs/de/schlichtherle/truezip/file/TFileInputStream.html"><tt>TFileInputStream</tt></a>
                    and list the members of the directory entry by using
                    <a href="apidocs/de/schlichtherle/truezip/file/TFile.html#listFiles"><tt>TFile.listFiles()</tt></a>.
               </p>
                
<p>
                    Note that this feature solely exists to enable applications
                    to read the contents of all archive files, even if they
                    have a strange directory layout.
                    Note again that a TrueZIP application cannot create a
                    covariant archive entry because this is considered to be a
                    bad practice.
               </p>
            <hr /></dd>
<dt><a name="support">
                I have another question or issue.
                How do I get it responded and resolved?
            </a></dt>
<dd>
                
<p>
                    For any bug report, improvement request, feature request,
                    task request, help request etc. please
                    <a class="externalLink" href="mailto:users@truezip.java.net">post</a>
                    it to the User Mailing List once you have
                    <a class="externalLink" href="mailto:sympa@truezip.java.net?subject=subscribe%20users">subscribed</a>
                    to it.
                    The User Mailing List is your direct connection to the
                    community.
                    My response time is usually less than a day - this goes
                    without warranties!
               </p>
                
<p>
                    Once&#xa0;your question or issue has been approved as a bug
                    report, improvement request, feature request or task
                    request it gets tracked in
                    <a class="externalLink" href="http://java.net/jira/browse/TRUEZIP">JIRA</a>.
                    You can then use JIRA to monitor and discuss its progress,
                    vote for it, add file attachments to it etc.
                    JIRA is now also used to schedule new TrueZIP versions and
                    prepare their Release Notes.
               </p>
            </dd></dl></div>
              </div>
    </div>
    <div class="clear"><hr/></div>
    <div id="footer">
      <div class="xright">
              Copyright &#169;                    2005-2013
                        <a href="http://schlichtherle.de">Schlichtherle IT Services</a>.
            All Rights Reserved.      
                                   <span id="publishDate">Last Published: 2013-07-19</span>
                        </div>
      <div class="clear"><hr/></div>
    </div>
  </body>
</html>
 
 
Close
loading
Please Confirm
Close