de.schlichtherle.io.archive.spi.ArchiveEntry Maven / Gradle / Ivy
Show all versions of truezip Show documentation
/*
* Copyright (C) 2006-2010 Schlichtherle IT Services
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package de.schlichtherle.io.archive.spi;
import de.schlichtherle.io.ArchiveEntryMetaData;
import javax.swing.Icon;
/**
* A simple interface for entries in an archive.
* Drivers need to implement this interface in order to allow TrueZIP to
* read and write entries for the supported archive types.
*
* Implementations do not need to be thread safe:
* Multithreading is addressed in the package {@code de.schlichtherle.io}.
*
*
Requirements for Archive Entry Names
*
* TrueZIP 6 has the following requirements for archive entry names:
*
* - An entry name is a list of directory or file names whichs elements
* are separated by single separators ({@link #SEPARATOR}).
*
- An empty string ({@code ""}), a dot
* ({@code "."}), or a dot-dot ({@code ".."})
* is not permissible as a directory or file name.
*
- If an entry name starts with a separator, it's said to be
* absolute.
* Absolute entries are not accessible by client applications, but are
* retained if the archive is updated.
*
- If an entry name ends with a separator, it denotes a directory
* and vice versa.
*
* For example, {@code "foo/bar"} denotes a valid entry
* name for a file, but {@code "./abc/../foo/./def/./../bar/."}
* would not, although both refer to the same entry.
*
* As another example, {@code "dir/"} denotes a valid entry
* name for a directory, but {@code "dir"} would not.
*
* If an archive driver is to be written for an archive type which does not
* support these requirements, an adapter for the entry name must be
* implemented.
*
* For example, the ZIP and TAR file formats conform to all but the second
* requirement.
* So the driver implementations for the archive types use
* {@link de.schlichtherle.io.util.Paths#normalize(String, char)} to remove
* any redundant elements from the path.
*
* It's hoped that these requirements can be relaxed, but this would imply
* some minor changes in the service provider interface for archive drivers,
* so it's not going to happen in this major version number.
*
* @see de.schlichtherle.io.util.Paths#normalize(String, char) A utility
* method to remove empty and dot and dot-dot elements from an archive
* entry name
* @author Christian Schlichtherle
* @version $Id: ArchiveEntry.java,v 1.5 2010/08/22 13:08:39 christian_schlichtherle Exp $
* @since TrueZIP 6.0
*/
public interface ArchiveEntry {
/**
* The entry name separator as a string.
*
* @since TrueZIP 6.5
* @see #SEPARATOR_CHAR
*/
String SEPARATOR = "/";
/**
* The entry name separator as a character.
*
* @since TrueZIP 6.5
* @see #SEPARATOR
*/
char SEPARATOR_CHAR = '/';
/** The unknown value for numeric properties. */
byte UNKNOWN = -1;
/**
* Returns the archive entry name.
*
* @return A valid archive entry name.
* @see Requirements for Archive Entry Names
*/
String getName();
/**
* Returns {@code true} if and only if this entry represents a
* directory.
*/
boolean isDirectory();
/**
* Returns the (uncompressed) size of the archive entry in bytes,
* or {@code UNKNOWN} if not specified.
* This method is not meaningful for directory entries.
*/
long getSize();
// TODO: Add this in TrueZIP 7.
/**
* Sets the size of this archive entry.
*
* @param size The size of this archive entry in bytes.
* @see #getSize
*/
//void setSize(long size);
/**
* Returns the last modification time of this archive entry since the
* epoch, or {@code UNKNOWN} if not specified.
*
* @see #setTime
*/
long getTime();
/**
* Sets the last modification time of this archive entry.
*
* @param time The last modification time of this archive entry in
* milliseconds since the epoch.
* @see #getTime
*/
void setTime(long time);
/**
* Returns the icon that {@link de.schlichtherle.io.swing.tree.FileTreeCellRenderer}
* should display for this entry if it is open/expanded in the view.
* If {@code null} is returned, a default icon will be used,
* depending on the type of this entry and its state in the view.
*/
Icon getOpenIcon();
/**
* Returns the icon that {@link de.schlichtherle.io.swing.FileSystemView}
* and {@link de.schlichtherle.io.swing.tree.FileTreeCellRenderer} should
* display for this entry if it is closed/collapsed in the view.
* If {@code null} is returned, a default icon will be used,
* depending on the type of this entry and its state in the view.
*/
Icon getClosedIcon();
/**
* Returns the meta data for this archive entry.
* The default value is {@code null}.
*/
ArchiveEntryMetaData getMetaData();
/**
* Sets the meta data for this archive entry.
*
* @param metaData The meta data - may not be {@code null}.
*/
void setMetaData(ArchiveEntryMetaData metaData);
}