Package net.mtrop.doom

Class DoomPK3

java.lang.Object
java.util.zip.ZipFile
net.mtrop.doom.DoomPK3
All Implemented Interfaces:
Closeable, AutoCloseable
public class DoomPK3 extends ZipFile
Doom PK3 file. Contains a whole bunch of Doom resources, however, they are all zipped together. This class contains a bunch of methods for getting file information from the PK3, but if you want to read explicit info from it, see ZipFile.
Author:
Matthew Tropiano

  • Field Details

  • Constructor Details

    • DoomPK3

      public DoomPK3(String path) throws ZipException, IOException
      Opens a DoomPK3 file for reading and caches its contents.
      Parameters:
      path - the path to the file to open.
      Throws:
      ZipException - if this is not a PK3/ZIP archive.
      IOException - if the file cannot be read.

    • DoomPK3

      public DoomPK3(File pk3File) throws ZipException, IOException
      Opens a DoomPK3 file for reading and caches its contents.
      Parameters:
      pk3File - the file to open.
      Throws:
      ZipException - if this is not a PK3/ZIP archive.
      IOException - if the file cannot be read.

  • Method Details

    • getFilePath

      public final String getFilePath()
      Gets this file's path.
      Returns:
      this file's path.
      See Also:

    • getFileName

      public final String getFileName()
      Gets this file's name (and just the name).
      Returns:
      this file's name (and just the name).
      See Also:

    • refreshEntries

      public final void refreshEntries()
      Refreshes the entry lists, if ZIP contents changed.

    • getEntriesStartingWith

      public List<String> getEntriesStartingWith(String key)
      Returns a list of all entries that start with a type of key. This is treated case-insensitively.
      Parameters:
      key - the start of an entry.
      Returns:
      an array of entry names starting with the key string.

    • getEntryCount

      public int getEntryCount()
      Returns:
      the amount of entries in this archive.

    • contains

      public boolean contains(String entryName)
      Checks if this Wad contains a particular entry.

      The name is case-insensitive.

      Parameters:
      entryName - the name of the entry.
      Returns:
      true if so, false if not.

    • getData

      public byte[] getData(String entryName) throws IOException
      Gets the data in one entry in the PK3 by entry name (path and all).
      Parameters:
      entryName - the entry to extract and return as a byte array.
      Returns:
      a byte array of the entry's data, or null if the entry doesn't exist.
      Throws:
      IOException - if a read error occurs.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed

    • getInputStream

      public InputStream getInputStream(String entry) throws IOException
      Gets the data in one entry in the PK3 as an input stream by entry name (path and all).
      Parameters:
      entry - the entry to extract and return as a byte array.
      Returns:
      an InputStream of the entry's data, or null if the entry doesn't exist.
      Throws:
      IOException - if a read error occurs.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed

    • getFile

      public File getFile(String entryName, String outFilePath) throws IOException
      Gets the data in one entry in the PK3 and extracts it to a file. If the target file exists, it is overwritten.
      Parameters:
      entryName - the entry to extract and return as a byte array.
      outFilePath - the destination file path for the data.
      Returns:
      a reference to the file created, or null if the entry doesn't exist.
      Throws:
      IOException - if a read error occurs.
      FileNotFoundException - if the target file is a directory.
      SecurityException - if the file could not be created due to system permission.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed

    • getFile

      public File getFile(String entryName, File outFile) throws IOException
      Gets the data in one entry in the PK3 and extracts it to a file. If the target file exists, it is overwritten.
      Parameters:
      entryName - the entry to extract and return as a byte array.
      outFile - the destination file for the data.
      Returns:
      a reference to the file created, or null if the entry doesn't exist.
      Throws:
      IOException - if a read error occurs.
      FileNotFoundException - if the target file is a directory.
      SecurityException - if the file could not be created due to system permission.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed

    • getTextData

      public String getTextData(String entryName, Charset charset) throws IOException
      Retrieves the data for a particular entry as a decoded string of characters.

      The name is case-insensitive.

      Parameters:
      entryName - the name of the entry to find.
      charset - the source charset.
      Returns:
      the data, decoded, or null if the entry doesn't exist.
      Throws:
      IOException - if the data couldn't be retrieved.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed
      NullPointerException - if entryName is null.
      See Also:

    • getReader

      public Reader getReader(String entryName, Charset charset) throws IOException
      Retrieves a Reader for a particular entry as a decoded stream of characters.

      The name is case-insensitive.

      Parameters:
      entryName - the name of the entry to find.
      charset - the source charset.
      Returns:
      a Reader for reading the character stream, or null if the entry doesn't exist.
      Throws:
      IOException - if the data couldn't be retrieved.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed
      NullPointerException - if entryName is null.
      See Also:

    • getTextDataAs

      public <TO extends TextObject> TO getTextDataAs(String entryName, Charset charset, Class<TO> type) throws IOException
      Retrieves the data of the first occurrence of a particular entry as an interpreted text-originating object.

      The name is case-insensitive.

      Type Parameters:
      TO - the result type.
      Parameters:
      entryName - the name of the entry to find.
      charset - the source charset encoding.
      type - the object type to convert the text data to.
      Returns:
      the data, decoded, or null if the entry doesn't exist.
      Throws:
      IOException - if the data couldn't be retrieved or the entry's offsets breach the file extents.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed
      NullPointerException - if entryName is null.
      See Also:

    • getDataAs

      public <BO extends BinaryObject> BO getDataAs(String entryName, Class<BO> type) throws IOException
      Retrieves the data for a particular entry as a deserialized lump.

      The name is case-insensitive.

      Type Parameters:
      BO - a type that extends BinaryObject.
      Parameters:
      entryName - the name of the entry to find.
      type - the class type to deserialize into.
      Returns:
      the data, deserialized, or null if the entry doesn't exist.
      Throws:
      IOException - if the data couldn't be retrieved.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed
      NullPointerException - if entryName is null.
      See Also:

    • getDataAs

      public <BO extends BinaryObject> BO[] getDataAs(String entryName, Class<BO> type, int objectLength) throws IOException
      Retrieves the data for a particular entry as a deserialized lump of multiple objects.

      The name is case-insensitive.

      Type Parameters:
      BO - a type that extends BinaryObject.
      Parameters:
      entryName - the name of the entry to find.
      type - the class type to deserialize into.
      objectLength - the length of each individual object in bytes.
      Returns:
      the data, deserialized, or null if the entry doesn't exist.
      Throws:
      IOException - if the data couldn't be retrieved.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed
      NullPointerException - if entryName is null.
      See Also:

    • getDataAsList

      public <BO extends BinaryObject> List<BO> getDataAsList(String entryName, Class<BO> type, int objectLength) throws IOException
      Retrieves the data for a particular entry as a deserialized lump of multiple objects.

      The name is case-insensitive.

      Type Parameters:
      BO - a type that extends BinaryObject.
      Parameters:
      entryName - the name of the entry to find.
      type - the class type to deserialize into.
      objectLength - the length of each individual object in bytes.
      Returns:
      the data, deserialized, or null if the entry doesn't exist.
      Throws:
      IOException - if the data couldn't be retrieved.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed
      NullPointerException - if entryName is null.
      See Also:

    • getDataAsWadMap

      public WadMap getDataAsWadMap(String entryName) throws IOException
      Retrieves the data for a particular entry, presuming it to be a WAD of some kind, and returns it as a WadMap.
      Parameters:
      entryName - the name of the entry to find.
      Returns:
      a WadMap representing the contents of the entry, or null if the entry doesn't exist.
      Throws:
      IOException - if the data couldn't be retrieved.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed
      NullPointerException - if entryName is null.

    • getDataAsTempWadFile

      public WadFile getDataAsTempWadFile(String entryName, String outFilePath) throws IOException
      Retrieves the data for a particular entry, extracts it, and, presuming it to be a WAD of some kind, opens it as a WadFile. If the target file exists, it is overwritten.

      NOTE: The WadFile returned is special: as soon as it is closed, it is deleted!

      Parameters:
      entryName - the entry to extract and return as a byte array.
      outFilePath - the destination file path for the data.
      Returns:
      a reference to the open WAD file created, or null if the entry doesn't exist.
      Throws:
      IOException - if a read error occurs.
      FileNotFoundException - if the target file is a directory.
      SecurityException - if the file could not be created due to system permission.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed

    • getDataAsTempWadFile

      public WadFile getDataAsTempWadFile(String entryName, File outFile) throws IOException
      Retrieves the data for a particular entry, extracts it, and, presuming it to be a WAD of some kind, opens it as a WadFile. If the target file exists, it is overwritten.

      NOTE: The WadFile returned is special: as soon as it is closed, it is deleted!

      Parameters:
      entryName - the entry to extract and return as a byte array.
      outFile - the destination file for the data.
      Returns:
      a reference to the open WAD file created, or null if the entry doesn't exist.
      Throws:
      IOException - if a read error occurs.
      FileNotFoundException - if the target file is a directory.
      SecurityException - if the file could not be created due to system permission.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed

    • getDataAsWadBuffer

      public WadBuffer getDataAsWadBuffer(String entryName) throws IOException
      Retrieves the data for a particular entry, presuming it to be a WAD of some kind, and returns it as a fully read WadBuffer. Changing the WadBuffer does NOT change the entry data.
      Parameters:
      entryName - the name of the entry to find.
      Returns:
      a WadBuffer containing the contents of the entry, or null if the entry doesn't exist.
      Throws:
      IOException - if the data couldn't be retrieved.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed
      NullPointerException - if entryName is null.

    • getScanner

      public <BO extends BinaryObject> BinaryObject.Scanner<BO> getScanner(String entryName, Class<BO> type, int objectLength) throws IOException
      Retrieves the data for a particular entry and returns it as a deserializing scanner iterator that returns independent instances of objects.

      The name is case-insensitive.

      If you don't intend to read the entirety of the entry via the BinaryObject.InlineScanner, close it after you finish (or use a try-with-resources block)!

      Type Parameters:
      BO - a type that extends BinaryObject.
      Parameters:
      entryName - the name of the entry to find.
      type - the class type to deserialize into.
      objectLength - the length of each object in the entry in bytes.
      Returns:
      a scanner for the data, or null if the entry can't be found.
      Throws:
      IOException - if the data couldn't be retrieved.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed

    • getInlineScanner

      public <BO extends BinaryObject> BinaryObject.InlineScanner<BO> getInlineScanner(String entryName, Class<BO> type, int objectLength) throws IOException
      Retrieves the data for a particular entry and returns it as a deserializing scanner iterator that returns the same object instance with its contents changed.

      This is useful for when you would want to quickly scan through a set of serialized objects while ensuring low memory use. Do NOT store the references returned by next() anywhere as the contents of that reference will be changed by the next call to next().

      The name is case-insensitive.

      If you don't intend to read the entirety of the entry via the BinaryObject.InlineScanner, close it after you finish (or use a try-with-resources block)!

      Type Parameters:
      BO - a type that extends BinaryObject.
      Parameters:
      entryName - the name of the entry to find.
      type - the class type to deserialize into.
      objectLength - the length of each object in the entry in bytes.
      Returns:
      a scanner for the data, or null if the entry can't be found.
      Throws:
      IOException - if the data couldn't be retrieved.
      ZipException - if a ZIP format error has occurred
      IllegalStateException - if the zip file has been closed

    • getEntryName

      public static String getEntryName(ZipEntry ze)
      Gets the "entry name" for a ZipEntry, which is just the filename itself minus extension.
      Parameters:
      ze - the ZipEntry to use.
      Returns:
      the "entry name" for this ZipEntry.