Package com.j3d.storage.files.protocol.proj

Class ProjectFile

java.lang.Object

com.j3d.storage.files.protocol.GenericFileProtocol

com.j3d.storage.files.protocol.proj.ProjectFile

All Implemented Interfaces:

FileProtocol

Direct Known Subclasses:

PF1, PF2, PF3

public class ProjectFile
extends GenericFileProtocol
implements FileProtocol

ProjectFile is an abstract base class for J3D project file protocols. It defines the common interface and properties for reading and writing project files (typically .j3p files) of different versions.

Concrete implementations, such as PF1, PF2 or PF3, handle the specific serialization and deserialization logic for their respective file formats.

This class also provides utility methods for retrieving specific protocol versions based on an integer identifier.

Author:

Lehlogonolo Poole

See Also:

• PF1
• PF2
• PF3

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	ProjectFile.PF

Field Summary

Fields

Modifier and Type	Field	Description
private final Set<ProjectFile.PF>	convertibleFrom
private final Set<ProjectFile.PF>	convertibleTo
private final String	EXTENSION
private final String	HEADER
private final int	VERSION

Constructor Summary

Constructors

Constructor	Description
ProjectFile(int version, Set<ProjectFile.PF> convertibleTo, Set<ProjectFile.PF> convertibleFrom)	Da default constructor

Method Summary

Modifier and Type	Method	Description
static int	colToInt(Color col)	Converts a Color object to its integer ARGB representation.
Set<ProjectFile.PF>	convertibleFromLower()	Returns a set of FileProtocol instances from which this protocol can be converted (downgraded or upgraded from).
Set<ProjectFile.PF>	convertibleToHigher()	Returns a set of FileProtocol instances to which this protocol can be converted (upgraded).
String	getExtension()	The protocol's extension
static ProjectFile	getFromVersion(int version)
BiConsumer<DataInputStream,Integer>	getHeaderReader()	Gets a Consumer that reads the protocol-specific header information from a DataInputStream.
Consumer<DataOutputStream>	getHeaderWriter()	Gets a Consumer that writes the protocol-specific header information to a DataOutputStream.
String	getProtocolHeader()	Gets the protocol header string that uniquely identifies this specific file protocol.
int	getProtocolVersion()	Gets the version number of the protocol.
static void	handleErr(ProjectFile vers, Exception err, BiConsumer<Integer,ProjectFile> loadable)	Handles errors that occur during file loading, particularly UnsupportedVersionException which indicates an attempt to load an older version of a project file.
static Color	intToCol(int col)	Converts an integer RGB representation back to a Color object.
<T extends ArrayList> T	readFile(String path, String name, Spinner throbber)	Reads a file from the specified path and returns its content as an object of type T.
<T extends ArrayList> void	writeFile(String path, String name, T data)	Writes the provided data to a file at the specified path.

Methods inherited from class com.j3d.storage.files.protocol.GenericFileProtocol

readHeader, writeHeader

Methods inherited from class java.lang.Object

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

Field Details

VERSION

private final int VERSION

HEADER

private final String HEADER

See Also:

• Constant Field Values

EXTENSION

private final String EXTENSION

See Also:

• Constant Field Values

convertibleTo

private final Set<ProjectFile.PF> convertibleTo

convertibleFrom

private final Set<ProjectFile.PF> convertibleFrom

Constructor Details

ProjectFile

public ProjectFile(int version,
 Set<ProjectFile.PF> convertibleTo,
 Set<ProjectFile.PF> convertibleFrom)

Da default constructor

Parameters:

version - The version of this project file protocol

convertibleTo - The set of FileProtocol that this can be upgraded to.

convertibleFrom - The set of FileProtocol that can upgrade to this.

Method Details

colToInt

public static int colToInt(Color col)

Converts a Color object to its integer ARGB representation. The integer includes the alpha component.

Parameters:

col - The Color object to convert.

Returns:

The integer representation of the color, including alpha.

intToCol

public static Color intToCol(int col)

Converts an integer RGB representation back to a Color object. The integer is expected to include the alpha component (ARGB format).

Parameters:

col - The integer representation of the colour.

Returns:

A new Color object.

getProtocolHeader

public String getProtocolHeader()

Description copied from interface: FileProtocol

Gets the protocol header string that uniquely identifies this specific file protocol.

Specified by:

getProtocolHeader in interface FileProtocol

Returns:

The protocol header.

getProtocolVersion

public int getProtocolVersion()

Description copied from interface: FileProtocol

Gets the version number of the protocol.

Specified by:

getProtocolVersion in interface FileProtocol

Returns:

The protocol version.

getExtension

public String getExtension()

Description copied from interface: FileProtocol

The protocol's extension

Specified by:

getExtension in interface FileProtocol

Returns:

The protocol's extension

convertibleToHigher

public Set<ProjectFile.PF> convertibleToHigher()

Description copied from interface: FileProtocol

Returns a set of FileProtocol instances to which this protocol can be converted (upgraded). These are typically newer versions of the protocol.

Specified by:

convertibleToHigher in interface FileProtocol

Returns:

A set of higher version protocols this protocol can convert to.

convertibleFromLower

public Set<ProjectFile.PF> convertibleFromLower()

Description copied from interface: FileProtocol

Returns a set of FileProtocol instances from which this protocol can be converted (downgraded or upgraded from). These are typically older versions of the protocol that can be read and converted into this protocol.

Specified by:

convertibleFromLower in interface FileProtocol

Returns:

A set of lower version protocols that can be converted to this protocol.

readFile

public <T extends ArrayList> T readFile(String path,
 String name,
 Spinner throbber)
                                 throws Exception

Description copied from interface: FileProtocol

Reads a file from the specified path and returns its content as an object of type T. This should be a direct inverse of the corresponding FileProtocol.writeFile(String, String, ArrayList) method.

Specified by:

readFile in interface FileProtocol

Type Parameters:

T - The type of the object to be returned.

Parameters:

path - The path to the file to be read.

name - The name of the file to be read.

throbber - The Spinner instance

Returns:

The content of the file as an object of type T.

Throws:

Exception

writeFile

public <T extends ArrayList> void writeFile(String path,
 String name,
 T data)

Description copied from interface: FileProtocol

Writes the provided data to a file at the specified path. This should be a direct inverse of the corresponding FileProtocol.readFile(String, String, Spinner) method.

Specified by:

writeFile in interface FileProtocol

Type Parameters:

T - The type of the data to be written, which must extend ArrayList.

Parameters:

path - The path to the file to be written.

data - The data to be written to the file.

getHeaderWriter

public Consumer<DataOutputStream> getHeaderWriter()

Description copied from interface: FileProtocol

Gets a Consumer that writes the protocol-specific header information to a DataOutputStream.

Specified by:

getHeaderWriter in interface FileProtocol

Returns:

A Consumer that writes the header.

getHeaderReader

public BiConsumer<DataInputStream,Integer> getHeaderReader()
                                                    throws IOException

Description copied from interface: FileProtocol

Gets a Consumer that reads the protocol-specific header information from a DataInputStream.

Specified by:

getHeaderReader in interface FileProtocol

Returns:

A Consumer that reads the header.

Throws:

IOException - If an I/O error occurs.

getFromVersion

public static ProjectFile getFromVersion(int version)

handleErr

public static void handleErr(ProjectFile vers,
 Exception err,
 BiConsumer<Integer,ProjectFile> loadable)

Handles errors that occur during file loading, particularly UnsupportedVersionException which indicates an attempt to load an older version of a project file.

Parameters:

vers - The current ProjectFile instance being used for loading.

err - The exception that occurred during loading.

loadable - A BiConsumer that accepts the current protocol version and the convertible protocol if an UnsupportedVersionException is caught and a conversion is possible.