Package de.unirostock.sems.cbarchive

Class CombineArchive

    • Constructor Detail

      • CombineArchive

        public CombineArchive​(File zipFile)
               throws IOException,
                      org.jdom2.JDOMException,
                      ParseException,
                      CombineArchiveException
        Instantiates a new empty combine archive. This is basically the same as calling new CombineArchive (zipFile, false)
        Parameters:
        zipFile - the archive to read, will be created if non-existent
        Throws:
        IOException - if we cannot create a temporary directory
        CombineArchiveException - Signals problems with the Combine Archive concept
        ParseException - Signals problems with the parser
        org.jdom2.JDOMException - Signals problems with the jDOM parser

      • CombineArchive

        public CombineArchive​(File zipFile,
                      boolean continueOnError)
               throws IOException,
                      org.jdom2.JDOMException,
                      ParseException,
                      CombineArchiveException
        Instantiates a new empty combine archive. If continueOnError is true we won't raise an exception in case of errors. So you can continue working on the archive even if a file is missing. But handle with care! You might worsen the whole situation. In any case you should make sure that there are no errors using hasErrors(). The list of occurred errors can then be obtained using getErrors().
        Parameters:
        zipFile - the archive to read, will be created if non-existent
        continueOnError - ignore errors and continue (as far as possible)
        Throws:
        IOException - if we cannot create a temporary directory
        CombineArchiveException - Signals problems with the Combine Archive concept
        ParseException - Signals problems with the parser
        org.jdom2.JDOMException - Signals problems with the jDOM parser

    • Method Detail

      • getZipLocation

        public File getZipLocation()
        Gets the location of the underlying zip file.
        Returns:
        the zipfile location

      • getMainEntry

        public ArchiveEntry getMainEntry()
        Deprecated.
        as of version 0.8.2, replaced by getMainEntries()
        Gets the the first main entry of this archive, if defined. As of RC2 of the spec there may be more than one main entry, so you should use getMainEntries() instead.
        Returns:
        the first main entry, or null if there is no main entry
        See Also:
        ArchiveEntry

      • getMainEntries

        public List<ArchiveEntry> getMainEntries()
        Gets the main entries as defined in the archive.
        Returns:
        the main entries

      • setMainEntry

        public void setMainEntry​(ArchiveEntry mainEntry)
        Sets a main entry of the archive. Other main entries get replaced. Use addMainEntry(ArchiveEntry) to add another main entry.
        Parameters:
        mainEntry - the new main entry

      • addMainEntry

        public void addMainEntry​(ArchiveEntry mainEntry)
        Adds an entry to the list of main entries in this archive.
        Parameters:
        mainEntry - the main entry

      • removeMainEntry

        public void removeMainEntry​(ArchiveEntry entry)
        Removes an entry from the list of main entries.
        Parameters:
        entry - the entry to be removed

      • getEntry

        public ArchiveEntry getEntry​(String location)
        Retrieves an entry stored at a specified location. The location should start with / (the root of the archive).
        Parameters:
        location - the location
        Returns:
        the entry

      • removeEntry

        public boolean removeEntry​(String location)
                    throws IOException
        Removes an entry defined by its relative location from the archive. The location should start with / (the root of the archive).
        Parameters:
        location - the location of the corresponding file
        Returns:
        true if we found that entry and removed it successfully
        Throws:
        IOException - Signals that an I/O exception has occurred.

      • removeEntry

        public boolean removeEntry​(ArchiveEntry entry)
                    throws IOException
        Removes an entry from the archive.
        Parameters:
        entry - the entry to remove
        Returns:
        true if we found that entry and removed it successfully
        Throws:
        IOException - Signals that an I/O exception has occurred.

      • getEntryByLocation

        public ArchiveEntry getEntryByLocation​(String location)
        Retireves an entry by its location.
        Parameters:
        location - the location of the entry, should start with / (root of the archive).
        Returns:
        the entry located at location, or null if there is no such entry

      • replaceFile

        public ArchiveEntry replaceFile​(File toInsert,
                                ArchiveEntry oldEntry)
                         throws IOException
        Replace the file associated with a certain entry while keeping the meta data.
        Parameters:
        toInsert - the new file to insert
        oldEntry - the old entry whose file should be replaced
        Returns:
        the new entry
        Throws:
        IOException - Signals that an I/O exception has occurred.

      • addEntry

        public ArchiveEntry addEntry​(File toInsert,
                             String targetName,
                             URI format)
                      throws IOException
        Adds an entry to the archive.

        The current version of the concerning file will be copied immediately. Thus, upcoming modifications of the source file won't affect the version in our archive. The path of this file in the archive will be targetName, it may include sub directories, e.g. /path/in/archive/file.ext. If there is already a file in the archive having the same path we'll overwrite it.

        Parameters:
        toInsert - the file to insert
        targetName - the target name of the file in the archive
        format - the format URI, see CombineFormatizer
        Returns:
        the archive entry or null if adding failed
        Throws:
        IOException - Signals that an I/O exception has occurred.

      • addEntry

        public ArchiveEntry addEntry​(File toInsert,
                             String targetName,
                             String format)
                      throws IOException
        Deprecated.
        as of version 0.9, replaced by addEntry(java.io.File,java.lang.String,java.net.URI)
        Adds an entry to the archive.

        The current version of the concerning file will be copied immediately. Thus, upcoming modifications of the source file won't affect the version in our archive. The path of this file in the archive will be targetName, it may include sub directories, e.g. /path/in/archive/file.ext. If there is already a file in the archive having the same path we'll overwrite it.

        Parameters:
        toInsert - the file to insert
        targetName - the target name of the file in the archive
        format - the format URI, see CombineFormatizer
        Returns:
        the archive entry or null if adding failed
        Throws:
        IOException - Signals that an I/O exception has occurred.

      • addEntry

        public ArchiveEntry addEntry​(File toInsert,
                             String targetName,
                             URI format,
                             boolean mainEntry)
                      throws IOException
        Adds an entry to the archive.

        The current version of the concerning file will be copied immediately. Thus, upcoming modifications of the source file won't affect the version in our archive. The path of this file in the archive will be targetName, it may include sub directories, e.g. /path/in/archive/file.ext. If there is already a file in the archive having the same path we'll overwrite it.

        Parameters:
        toInsert - the file to insert
        targetName - the target name of the file in the archive
        format - the format URI, see CombineFormatizer
        mainEntry - the main entry
        Returns:
        the archive entry or null if adding failed
        Throws:
        IOException - Signals that an I/O exception has occurred.

      • addEntry

        public ArchiveEntry addEntry​(File toInsert,
                             String targetName,
                             String format,
                             boolean mainEntry)
                      throws IOException
        Deprecated.
        as of version 0.9, replaced by addEntry(java.io.File,java.lang.String,java.net.URI,boolean)
        Adds an entry to the archive.

        The current version of the concerning file will be copied immediately. Thus, upcoming modifications of the source file won't affect the version in our archive. The path of this file in the archive will be targetName, it may include sub directories, e.g. /path/in/archive/file.ext. If there is already a file in the archive having the same path we'll overwrite it.

        Parameters:
        toInsert - the file to insert
        targetName - the target name of the file in the archive
        format - the format URI, see CombineFormatizer
        mainEntry - the main entry
        Returns:
        the archive entry or null if adding failed
        Throws:
        IOException - Signals that an I/O exception has occurred.

      • addEntry

        public ArchiveEntry addEntry​(File baseDir,
                             File file,
                             URI format,
                             boolean mainEntry)
                      throws IOException
        Adds an entry to the archive.

        The current version of the concerning file will be copied immediately. Thus, upcoming modifications of the source file won't affect the version in our archive. The path of this file in the archive will be the path of file relative to baseDir. If there is already a file in the archive having the same relative path we'll overwrite it.

        Parameters:
        baseDir - the base dir
        file - the file
        format - the format URI, see CombineFormatizer
        mainEntry - is this the main entry of the archive? (default: false)
        Returns:
        the archive entry or null if adding failed
        Throws:
        IOException - Signals that an I/O exception has occurred.

      • addEntry

        public ArchiveEntry addEntry​(File baseDir,
                             File file,
                             String format,
                             boolean mainEntry)
                      throws IOException
        Deprecated.
        as of version 0.9, replaced by addEntry(java.io.File,java.io.File,java.net.URI,boolean)
        Adds an entry to the archive.

        The current version of the concerning file will be copied immediately. Thus, upcoming modifications of the source file won't affect the version in our archive. The path of this file in the archive will be the path of file relative to baseDir. If there is already a file in the archive having the same relative path we'll overwrite it.

        Parameters:
        baseDir - the base dir
        file - the file
        format - the format URI, see CombineFormatizer
        mainEntry - is this the main entry of the archive? (default: false)
        Returns:
        the archive entry or null if adding failed
        Throws:
        IOException - Signals that an I/O exception has occurred.

      • addEntry

        public ArchiveEntry addEntry​(File baseDir,
                             File file,
                             URI format)
                      throws IOException
        Adds an entry to the archive. The current version of the concerning file will be copied immediately. Thus, upcoming modifications of the source file won't affect the version in our archive. The path of this file in the archive will be the path of file relative to baseDir. If there is already a file in the archive having the same relative path we'll delete it.
        Parameters:
        baseDir - the base dir
        file - the file
        format - the format URI, see CombineFormatizer
        Returns:
        the archive entry or null if adding failed
        Throws:
        IOException - Signals that an I/O exception has occurred.

      • addEntry

        public ArchiveEntry addEntry​(File baseDir,
                             File file,
                             String format)
                      throws IOException
        Deprecated.
        as of version 0.9, replaced by addEntry(java.io.File,java.io.File,java.net.URI)
        Adds an entry to the archive. The current version of the concerning file will be copied immediately. Thus, upcoming modifications of the source file won't affect the version in our archive. The path of this file in the archive will be the path of file relative to baseDir. If there is already a file in the archive having the same relative path we'll delete it.
        Parameters:
        baseDir - the base dir
        file - the file
        format - the format URI, see CombineFormatizer
        Returns:
        the archive entry or null if adding failed
        Throws:
        IOException - Signals that an I/O exception has occurred.

      • addEntry

        @Deprecated
public ArchiveEntry addEntry​(File baseDir,
                             File file,
                             String format,
                             OmexDescription description,
                             boolean mainEntry)
                      throws IOException
        Deprecated.
        as of version 0.5, replaced by addEntry(java.io.File,java.io.File,java.lang.String,boolean)
        Adds an entry to the archive. The current version of the concerning file will be copied immediately. Thus, upcoming modifications of the source file won't affect the version in our archive. The path of this file in the archive will be the path of file relative to baseDir. If there is already a file in the archive having the same relative path we'll delete it.
        Parameters:
        baseDir - the base dir
        file - the file
        format - the format URI, see CombineFormatizer
        description - the description
        mainEntry - is this the main entry of the archive? (default: false)
        Returns:
        the archive entry or null if adding failed
        Throws:
        IOException - Signals that an I/O exception has occurred.

      • addEntry

        @Deprecated
public ArchiveEntry addEntry​(File baseDir,
                             File file,
                             String format,
                             OmexDescription description)
                      throws IOException
        Deprecated.
        as of version 0.5, replaced by addEntry(java.io.File,java.io.File,java.lang.String)
        Adds an entry to the archive. The current version of the concerning file will be copied immediately. Thus, upcoming modifications of the source file won't affect the version in our archive. The path of this file in the archive will be the path of file relative to baseDir. If there is already a file in the archive having the same relative path we'll delete it.
        Parameters:
        baseDir - the base dir
        file - the file
        format - the format URI, see CombineFormatizer
        description - the description
        Returns:
        the archive entry or null if adding failed
        Throws:
        IOException - Signals that an I/O exception has occurred.

      • getEntriesWithFormat

        public List<ArchiveEntry> getEntriesWithFormat​(URI format)
        Gets entries sharing a certain format.
        Parameters:
        format - the format URI of interest, see CombineFormatizer
        Returns:
        the entries with that format

      • getNumEntriesWithFormat

        public int getNumEntriesWithFormat​(URI format)
        Counts entries with a certain format.
        Parameters:
        format - the format URI of interest, see CombineFormatizer
        Returns:
        the number of entries with that format

      • hasEntriesWithFormat

        public boolean hasEntriesWithFormat​(URI format)
        Checks whether there are entries with a certain format.
        Parameters:
        format - the format URI of interest, see CombineFormatizer
        Returns:
        true, if there is at least one entry in this archive having this format

      • HasEntriesWithFormat

        @Deprecated
public boolean HasEntriesWithFormat​(URI format)
        Deprecated.
        as of version 0.9.5.2, replaced by hasEntriesWithFormat(URI)
        Checks whether there are entries with a certain format.
        Parameters:
        format - the format URI of interest, see CombineFormatizer
        Returns:
        true, if there is at least one entry in this archive having this format

      • getNumEntries

        public int getNumEntries()
        Gets the number of entries stored in this archive.
        Returns:
        the number of entries

      • getEnumerator

        public Iterator<ArchiveEntry> getEnumerator()
        Gets the enumerator of entries.
        Returns:
        the iterator

      • getMetaOfMeta

        public MetaDataHolder getMetaOfMeta()
        Gets the meta data holder of the meta data. This meta data holder will contain all the meta data for the meta data, thus describing the meta data of the archive and its entries.
        Returns:
        the meta of meta

      • pack

        public void pack​(boolean multipleMetaFiles)
          throws IOException,
                 TransformerException
        Pack this archive: generates manifest and meta data files.

        While we're working directly in the ZIP this generates manifest and meta data files. If multipleMetaFiles is set to true (default: false, see pack()) we will generate one meta data file for each archive entry (instead of combining all meta data in a single file).

        Parameters:
        multipleMetaFiles - should we create one meta file per archive entry or combine all meta data in a single file?
        Throws:
        TransformerException - Signals problems with converting the DOM to a text document
        IOException - Signals that an I/O exception has occurred.

      • pack

        public void pack()
          throws IOException,
                 TransformerException
        Pack this archive.

        While we're working directly in the ZIP this generates manifest and meta data files. This method will generate a single meta data file for all meta data associated to the entries in this archive. See pack(boolean) if you prefer creating multiple meta data files.

        Throws:
        TransformerException - Signals problems with converting the DOM to a text document
        IOException - Signals that an I/O exception has occurred.

      • moveEntry

        public void moveEntry​(String oldPath,
                      String newPath)
               throws IOException
        Move an entry. (rename it)
        Parameters:
        oldPath - the old path to the entry
        newPath - the target path
        Throws:
        IOException - Signals that an I/O exception has occurred.

      • extract

        public File extract​(Path archivePath,
                    File destination)
             throws IOException
        Extract an entry from this archive.
        Parameters:
        archivePath - the path of the entry in our archive, should start with an /
        destination - the destination to write the entry to
        Returns:
        the file that was written (=destination)
        Throws:
        IOException - Signals that an I/O exception has occurred.

      • extractTo

        public File extractTo​(File destination)
               throws IOException
        Extract the whole archive to the disk.
        Parameters:
        destination - the destination
        Returns:
        the destination
        Throws:
        IOException

      • getErrors

        public List<String> getErrors()
        Gets the errors that occurred during creating/reading of an archive.
        Returns:
        the errors

      • hasErrors

        public boolean hasErrors()
        Checks for errors.
        Returns:
        true, if there are errors

      • clearErrors

        public void clearErrors()
        Clear all errors.