Package net.mtrop.doom

Class WadFile

java.lang.Object

net.mtrop.doom.WadFile

All Implemented Interfaces:

AutoCloseable, Iterable<WadEntry>, Wad

public class WadFile
extends Object
implements Wad, AutoCloseable

The class that reads WadFile information and provides random access to Wad files.

Use of this class is recommended for reading WAD information or small additions of data, as the overhead needed to do so is minimal in this class.

Many writing I/O operations will cause the opened file to be changed many times, the length of time of which being dictated by the length of the entry list (as the list grows, so does the time it takes to write/change it). Bulk reads/additions/writes/changes are best left for the WadBuffer class, however, if only additions need to happen, using WadFile.Adder via createAdder() is a viable method for bulk addition with little overhead.

Since this WadFile maintains current file position for reads and writes, most operations are not thread-safe!

Author:

Matthew Tropiano

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	WadFile.Adder	Bulk add mechanism for WadFile.

Nested classes/interfaces inherited from interface net.mtrop.doom.Wad

Wad.Type

Field Summary

Fields inherited from interface net.mtrop.doom.Wad

NO_DATA, NO_ENTRIES

Constructor Summary

Constructors

Constructor	Description
WadFile(File f)	Opens a WadFile from a file.
WadFile(File f, Boolean readOnly)	Opens a WadFile from a file.
WadFile(String path)	Opens a WadFile from a file specified by "path." The file will be opened in a mode appropriate for file permission capabilities.
WadFile(String path, Boolean readOnly)	Opens a WadFile from a file specified by "path."

Method Summary

Modifier and Type	Method	Description
WadEntry	addDataAt(int index, String entryName, InputStream in, int maxLength)	Adds data to this Wad at a particular entry offset, using entryName as the name of the entry.
WadEntry	addEntryAt(int index, WadEntry entry)	Adds a new entry to the Wad.
void	addFromAt(int destIndex, Wad source, WadEntry... entries)	Takes entries and their data from another Wad and adds it to this one at a specific index.
void	close()	Closes this Wad, but calls flushEntries() first to commit any changes that happened that did not auto-flush the entries, if writing is enabled on this file.
WadFile.Adder	createAdder()	Creates an object for bulk-adding data to this WadFile and ensuring that the entry list gets written on completion.
static WadFile	createWadFile(File f)	Creates a new, empty WadFile (PWAD Type) and returns a reference to it.
static WadFile	createWadFile(String path)	Creates a new, empty WadFile and returns a reference to it.
WadEntry	deleteEntry(int n)	Deletes a Wad's entry and its contents.
static WadFile	extract(File targetFile, Wad source, int startIndex, int maxLength)	Creates a new WadFile from a subset of entries (and their data) from another Wad.
static WadFile	extract(File targetFile, Wad source, WadEntry... entries)	Creates a new WadFile from a subset of entries (and their data) from another Wad.
void	fetchContent(int offset, int length, byte[] dest, int destOffset)	Fetches a series of bytes from an arbitrary place in the Wad and puts them into a provided array.
final void	flushEntries()	Writes the header and the entry list out to the Wad file.
int	getContentLength()
WadEntry	getEntry(int n)	Gets the WadEntry at index n.
int	getEntryCount()
final int	getEntryListOffset()
final String	getFileAbsolutePath()	Returns this Wad's file absolute path.
final String	getFileName()	Returns this Wad's file name.
final String	getFilePath()	Gets this Wad's file path.
final Wad.Type	getType()	Gets the type of WAD that this is.
boolean	isIWAD()	Checks if this WAD is an Internal WAD.
boolean	isPWAD()	Checks if this WAD is a Patch WAD.
Iterator<WadEntry>	iterator()
WadEntry	removeEntry(int n)	Remove a Wad's entry (but not contents).
void	renameEntry(int index, String newName)	Renames the entry at an index in the Wad.
void	replaceEntry(int index, byte[] data)	Replaces the entry at an index in the Wad.
void	setEntries(WadEntry... entryList)	Completely replaces the list of entries in this Wad with a completely different set of entries.
final void	setType(Wad.Type type)	Sets the type of WAD that this is.
void	unmapEntries(int startIndex, WadEntry... entryList)	Replaces a series of WadEntry objects in this Wad, using the provided list of entries as the replacement list.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface net.mtrop.doom.Wad

addData, addData, addData, addData, addData, addData, addData, addDataAt, addDataAt, addDataAt, addDataAt, addDataAt, addDataAt, addEntry, addEntry, addEntryAt, addFrom, addFrom, addFromAt, addMarker, addMarkerAt, contains, contains, contains, fetchData, fetchData, fetchData, fetchData, fetchData, getAllEntries, getAllEntries, getAllEntryIndices, getContent, getData, getData, getData, getData, getData, getDataAs, getDataAs, getDataAs, getDataAs, getDataAs, getDataAs, getDataAs, getDataAs, getDataAs, getDataAs, getDataAsList, getDataAsList, getDataAsList, getDataAsList, getDataAsList, getEntry, getEntry, getEntry, getInlineScanner, getInlineScanner, getInlineScanner, getInlineScanner, getInlineScanner, getInputStream, getInputStream, getInputStream, getInputStream, getInputStream, getLastEntry, getNthEntry, getReader, getReader, getReader, getReader, getReader, getScanner, getScanner, getScanner, getScanner, getScanner, getTextData, getTextData, getTextData, getTextData, getTextData, getTextDataAs, getTextDataAs, getTextDataAs, getTextDataAs, getTextDataAs, indexOf, indexOf, indexOf, lastIndexOf, mapEntries, replaceEntry, replaceEntry, replaceEntry, setEntry, transformData, transformData, transformData, transformData, transformData, transformData, transformData, transformData, transformTextData, transformTextData, transformTextData, transformTextData

Constructor Details

WadFile

public WadFile(String path)
        throws IOException

Opens a WadFile from a file specified by "path." The file will be opened in a mode appropriate for file permission capabilities.

Parameters:

path - the path to the File.

Throws:

IOException - if the file can't be read or an incompatible mode was used for access.

FileNotFoundException - if the file can't be found.

SecurityException - if you don't have permission to access the file.

WadException - if the file isn't a Wad file.

NullPointerException - if path is null.

WadFile

public WadFile(String path,
 Boolean readOnly)
        throws IOException

Opens a WadFile from a file specified by "path."

Parameters:

path - the path to the File.

readOnly - if true, the file will be opened in read-only mode. If false, this will attempt to open the file in a mode that allows writing. If null, this will attempt to detect whether or not the file can be written to. If so, open in a writable mode. If not, open in read-only mode.

Throws:

IOException - if the file can't be read or an incompatible mode was used for access.

FileNotFoundException - if the file can't be found.

SecurityException - if you don't have permission to access the file.

WadException - if the file isn't a Wad file.

NullPointerException - if path is null.

Since:

2.14.0

See Also:

• File.canWrite()

WadFile

public WadFile(File f)
        throws IOException

Opens a WadFile from a file. The file will be opened in a mode appropriate for file permission capabilities.

Parameters:

f - the file.

Throws:

IOException - if the file can't be read or an incompatible mode was used for access.

FileNotFoundException - if the file can't be found.

SecurityException - if you don't have permission to access the file.

WadException - if the file isn't a Wad file.

NullPointerException - if f is null.

WadFile

public WadFile(File f,
 Boolean readOnly)
        throws IOException

Opens a WadFile from a file.

Parameters:

f - the file.

readOnly - if true, the file will be opened in read-only mode. If false, this will attempt to open the file in a mode that allows writing. If null, this will attempt to detect whether or not the file can be written to. If so, open in a writable mode. If not, open in read-only mode.

Throws:

IOException - if the file can't be read or an incompatible mode was used for access.

FileNotFoundException - if the file can't be found.

SecurityException - if you don't have permission to access the file.

WadException - if the file isn't a Wad file.

NullPointerException - if f is null.

Since:

2.14.0

Method Details

createWadFile

public static WadFile createWadFile(String path)
                             throws IOException

Creates a new, empty WadFile and returns a reference to it.

Parameters:

path - the path of the new file in the form of a String.

Returns:

a reference to the newly created WadFile, already open.

Throws:

IOException - if the file can't be written.

NullPointerException - if path is null.

createWadFile

public static WadFile createWadFile(File f)
                             throws IOException

Creates a new, empty WadFile (PWAD Type) and returns a reference to it.

Parameters:

f - the file object referring to the new Wad.

Returns:

a reference to the newly created WadFile, already open.

Throws:

IOException - if the file can't be written.

NullPointerException - if f is null.

extract

public static WadFile extract(File targetFile,
 Wad source,
 int startIndex,
 int maxLength)
                       throws IOException

Creates a new WadFile from a subset of entries (and their data) from another Wad.

Entry extraction is sequential - if you have memory to spare, you may be better off using WadBuffer.extract(Wad, int, int) since it will have far less overhead.

NOTE: This will overwrite the destination file, if it exists!

Parameters:

targetFile - the file to create.

source - the the source Wad.

startIndex - the starting entry index.

maxLength - the maximum amount of entries from the starting index to copy.

Returns:

a new WadBuffer that only contains the desired entries, plus their data.

Throws:

IOException - if an error occurs on read from the source Wad.

Since:

2.1.0

extract

public static WadFile extract(File targetFile,
 Wad source,
 WadEntry... entries)
                       throws IOException

Creates a new WadFile from a subset of entries (and their data) from another Wad.

Entry extraction is sequential - if you have memory to spare, you may be better off using WadBuffer.extract(Wad, WadEntry...) since it will have far less overhead.

NOTE: This will overwrite the destination file, if it exists!

Parameters:

targetFile - the file to create.

source - the the source Wad.

entries - the entries to copy over.

Returns:

a new WadBuffer that only contains the desired entries, plus their data.

Throws:

IOException - if an error occurs on read from the source Wad.

Since:

2.1.0

flushEntries

public final void flushEntries()
                        throws IOException

Writes the header and the entry list out to the Wad file.

Throws:

IOException - if the header/entry list cannot be written.

setType

public final void setType(Wad.Type type)
                   throws IOException

Sets the type of WAD that this is.

Parameters:

type - the WAD type.

Throws:

IOException - if the header could not be written.

getType

public final Wad.Type getType()

Gets the type of WAD that this is.

Returns:

the WAD type.

getFileName

public final String getFileName()

Returns this Wad's file name.

Returns:

this file's name (and just the name).

See Also:

• File.getName()

getFilePath

public final String getFilePath()

Gets this Wad's file path.

Returns:

this file's path.

See Also:

• File.getPath()

getFileAbsolutePath

public final String getFileAbsolutePath()

Returns this Wad's file absolute path.

Returns:

this file's name (and just the name).

See Also:

• File.getAbsolutePath()

getEntryListOffset

public final int getEntryListOffset()

Returns:

the starting byte offset of the entry list (where the content ends).

getContentLength

public int getContentLength()

Specified by:

getContentLength in interface Wad

Returns:

the amount of content data in this Wad in bytes.

isIWAD

public boolean isIWAD()

Description copied from interface: Wad

Checks if this WAD is an Internal WAD.

Specified by:

isIWAD in interface Wad

Returns:

true if so, false if not.

isPWAD

public boolean isPWAD()

Description copied from interface: Wad

Checks if this WAD is a Patch WAD.

Specified by:

isPWAD in interface Wad

Returns:

true if so, false if not.

getEntryCount

public int getEntryCount()

Specified by:

getEntryCount in interface Wad

Returns:

the number of entries in this Wad.

getEntry

public WadEntry getEntry(int n)

Description copied from interface: Wad

Gets the WadEntry at index n.

Specified by:

getEntry in interface Wad

Parameters:

n - the index of the entry in the entry list.

Returns:

the entry at n.

fetchContent

public void fetchContent(int offset,
 int length,
 byte[] dest,
 int destOffset)
                  throws IOException

Description copied from interface: Wad

Fetches a series of bytes from an arbitrary place in the Wad and puts them into a provided array. This is will attempt to get the full provided length, throwing an exception if it does not.

Specified by:

fetchContent in interface Wad

Parameters:

offset - the offset byte into that data to start at.

length - the amount of bytes to fetch.

dest - the destination array of bytes.

destOffset - the offset into the destination array to put the bytes into.

Throws:

IOException - if an error occurs during read.

removeEntry

public WadEntry removeEntry(int n)
                     throws IOException

Description copied from interface: Wad

Remove a Wad's entry (but not contents). This will leave abandoned, un-addressed data in a Wad file and will not be removed until the data is purged.

Specified by:

removeEntry in interface Wad

Parameters:

n - the index of the entry to delete.

Returns:

the entry removed from the Wad.

Throws:

IOException - if the entry cannot be removed.

deleteEntry

public WadEntry deleteEntry(int n)
                     throws IOException

Description copied from interface: Wad

Deletes a Wad's entry and its contents. The overhead for multiple deletions may be expensive I/O-wise.

Specified by:

deleteEntry in interface Wad

Parameters:

n - the index of the entry to delete.

Returns:

the entry deleted.

Throws:

IOException - if the entry cannot be deleted.

renameEntry

public void renameEntry(int index,
 String newName)
                 throws IOException

Description copied from interface: Wad

Renames the entry at an index in the Wad.

Specified by:

renameEntry in interface Wad

Parameters:

index - the index of the entry to rename.

newName - the new name of the entry.

Throws:

IOException - if the entry cannot be renamed.

replaceEntry

public void replaceEntry(int index,
 byte[] data)
                  throws IOException

Description copied from interface: Wad

Replaces the entry at an index in the Wad. If the incoming data is the same size as the entry at the index, this will change the data in-place without deleting and adding.

Specified by:

replaceEntry in interface Wad

Parameters:

index - the index of the entry to replace.

data - the data to replace the entry with.

Throws:

IOException - if the entry cannot be replaced.

unmapEntries

public void unmapEntries(int startIndex,
 WadEntry... entryList)
                  throws IOException

Description copied from interface: Wad

Replaces a series of WadEntry objects in this Wad, using the provided list of entries as the replacement list. If the list of entries plus the starting index would breach the original list of entries, the excess is appended to the Wad.

Specified by:

unmapEntries in interface Wad

Parameters:

startIndex - the starting index to replace from (inclusive).

entryList - the set of entries to replace (in order) from the starting index.

Throws:

IOException - if the entries could not be written.

setEntries

public void setEntries(WadEntry... entryList)
                throws IOException

Description copied from interface: Wad

Completely replaces the list of entries in this Wad with a completely different set of entries.

Specified by:

setEntries in interface Wad

Parameters:

entryList - the set of entries that will make up this Wad.

Throws:

IOException - if the entries could not be written.

addEntryAt

public WadEntry addEntryAt(int index,
 WadEntry entry)
                    throws IOException

Description copied from interface: Wad

Adds a new entry to the Wad. Exercise caution with this method, as this entry is added as-is, and an entry can reference anywhere in the Wad!

Specified by:

addEntryAt in interface Wad

Parameters:

index - the index at which to add the entry.

entry - the entry to add.

Returns:

the entry added.

Throws:

IOException - if the entry cannot be written.

addDataAt

public WadEntry addDataAt(int index,
 String entryName,
 InputStream in,
 int maxLength)
                   throws IOException

Description copied from interface: Wad

Adds data to this Wad at a particular entry offset, using entryName as the name of the entry. The provided input stream is read until the end of the stream is reached or maxLength bytes are read. The input stream is NOT CLOSED, afterward. The rest of the entries in the wad are shifted down one index. The overhead for multiple individual additions may be expensive I/O-wise depending on the Wad implementation.

Specified by:

addDataAt in interface Wad

Parameters:

index - the index at which to add the entry.

entryName - the name of the entry to add this as.

in - the input stream to read.

maxLength - the maximum amount of bytes to read from the InputStream, or a value < 0 to keep reading until end-of-stream.

Returns:

a WadEntry that describes the added data.

Throws:

IOException - if the data cannot be written or the stream could not be read.

addFromAt

public void addFromAt(int destIndex,
 Wad source,
 WadEntry... entries)
               throws IOException

Description copied from interface: Wad

Takes entries and their data from another Wad and adds it to this one at a specific index.

Specified by:

addFromAt in interface Wad

Parameters:

destIndex - the index at which to add the entries.

source - the the source Wad.

entries - the entries to copy over.

Throws:

IOException - if an error occurs on read from the source Wad or write to this Wad.

createAdder

public WadFile.Adder createAdder()

Creates an object for bulk-adding data to this WadFile and ensuring that the entry list gets written on completion.

All methods on this object manipulate the WadFile it is created from, and defers the final writing of the entry list until it is closed. The object returned is meant to be created via a try-with-resources block, like so:

 try (WadFile.Adder adder = wad.createAdder())
 {
     adder.addData(....);
     ...
 }
 

...upon which the entries are committed to the file on close (but they are still available via getEntry(int) and associated methods). This will still commit the list even on an error occurring during add, unless the the writing of the list results in an error as well.

Returns:

a new WadFile.Adder instance.

iterator

public Iterator<WadEntry> iterator()

Specified by:

iterator in interface Iterable<WadEntry>

close

public void close()
           throws IOException

Closes this Wad, but calls flushEntries() first to commit any changes that happened that did not auto-flush the entries, if writing is enabled on this file.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Wad

Throws:

IOException - if an error occurred during close.