Aspose.TeX's output interface | Java

Please, refer to Aspose.TeX for Java API reference for formal definitions of I/O implementation.

The file system, ZIP and terminal examples typeset hello-world.tex to XPS. Set inputDirectory to a folder containing the TeX file and outputDirectory to an existing output folder. For ZIP output, set outputZip to a java.nio.file.Path in an existing folder. Import the Aspose.TeX classes used in the selected snippet, com.aspose.tex.rendering.XpsDevice, and the relevant java.io and java.nio.file classes. The calling method must handle or declare exceptions. Apply a license as described in the licensing guide to avoid evaluation restrictions.

The concept of the output directory

Since I/O primitives of the TeX language can only deal with file names, Aspose.TeX defines a directory as a mapping between names and bulks of data. The bulks of data are supposed to be files, streams, arrays, or whatever else.The API allows us to specify the input and output working directories separately. It provides the general IOutputWorkingDirectory interface for the output, which the user can implement for their own purposes. It also provides its own implementations, which will be discussed below. The interface extends IInputWorkingDirectory, since the engine may first create and write a file, and then read it back. The interface’s own method getOuputFile() returns the stream to write to, as opposed to the stream to read returned by getFile().

Writing file output to the disk file system

As we mentioned above, the most common value for the OutputWorkingDirectory would likely be an instance of the OutputFileSystemDirectory class.

Here’s how we would set it:

// inputDirectory contains hello-world.tex; outputDirectory is an existing output folder.
TeXOptions options = TeXOptions.consoleAppOptions(TeXConfig.objectTeX());
InputFileSystemDirectory input = new InputFileSystemDirectory(inputDirectory);
OutputFileSystemDirectory output = new OutputFileSystemDirectory(outputDirectory);
options.setInputWorkingDirectory(input);
options.setOutputWorkingDirectory(output);
options.setInteraction(Interaction.NonstopMode);
options.setTerminalOut(new OutputMemoryTerminal());

XpsDevice device = new XpsDevice();
TeXJobResult result;
try {
    result = new TeXJob("hello-world", device, options).run();
} finally {
    device.dispose();
    output.close();
    input.close();
}

This use case is quite simple, so we won’t dwell on it for a long time.

Writing file output to a ZIP archive

We can also create a file (or stream) and let the TeX engine use it as a ZIP archive to store the output files. Here it is:

// Store the XPS document and TeX transcript in a ZIP archive.
// inputDirectory contains hello-world.tex; outputZip is the java.nio.file.Path to create.
TeXJobResult result;
try (OutputStream zipStream = Files.newOutputStream(outputZip)) {
    TeXOptions options = TeXOptions.consoleAppOptions(TeXConfig.objectTeX());
    InputFileSystemDirectory input = new InputFileSystemDirectory(inputDirectory);
    OutputZipDirectory output = new OutputZipDirectory(zipStream);
    options.setInputWorkingDirectory(input);
    options.setOutputWorkingDirectory(output);
    options.setInteraction(Interaction.NonstopMode);
    options.setTerminalOut(new OutputMemoryTerminal());
    XpsDevice device = new XpsDevice();
    try {
        result = new TeXJob("hello-world", device, options).run();
        // Finalize the archive while its underlying stream is still open.
        output.finish();
    } finally {
        device.dispose();
        output.close();
        input.close();
    }
}

First, we create an output stream for the ZIP file. Then, after creating the conversion options, we set the OutputWorkingDirectory option to be an instance of the OutputZipDirectory class. The example stores hello-world.xps and hello-world.log in the archive. After the job, call finish() on the output directory before closing the underlying stream. The snippets keep their streams and working directories open until the job finishes and close them afterward.

The concept of the output terminal

There’s another important part of the output — the terminal output. As for this one, Aspose.TeX for Java defines the general IOutputTerminal interface as having two methods. One of them returns a BufferedWriter instance. Another one returns an OutputStream instance as the underlying stream. Provided implementations of the interface are discussed below.

Writing terminal output to the console

To do this, we need to set the TerminalOut option to be an instance of the OutputConsoleTerminal class.

// inputDirectory contains hello-world.tex; outputDirectory is an existing output folder.
TeXOptions options = TeXOptions.consoleAppOptions(TeXConfig.objectTeX());
InputFileSystemDirectory input = new InputFileSystemDirectory(inputDirectory);
OutputFileSystemDirectory output = new OutputFileSystemDirectory(outputDirectory);
options.setInputWorkingDirectory(input);
options.setOutputWorkingDirectory(output);
options.setInteraction(Interaction.NonstopMode);
// This is also the default output terminal.
options.setTerminalOut(new OutputConsoleTerminal());

XpsDevice device = new XpsDevice();
TeXJobResult result;
try {
    result = new TeXJob("hello-world", device, options).run();
} finally {
    device.dispose();
    output.close();
    input.close();
}

OutputConsoleTerminal is the default value of this option. The example explicitly selects it and writes terminal output to the console during conversion. All four examples use noninteractive execution; the file system and ZIP examples capture terminal output in memory.

Writing terminal output to a file

Unlike the input terminal, Aspose.TeX for Java provides an implementation of the IOutputTerminal, which allows us to write the terminal output to a file in some output directory.

// inputDirectory contains hello-world.tex; outputDirectory is an existing output folder.
TeXOptions options = TeXOptions.consoleAppOptions(TeXConfig.objectTeX());
InputFileSystemDirectory input = new InputFileSystemDirectory(inputDirectory);
OutputFileSystemDirectory output = new OutputFileSystemDirectory(outputDirectory);
options.setInputWorkingDirectory(input);
options.setOutputWorkingDirectory(output);
options.setInteraction(Interaction.NonstopMode);
// Set the output directory first: the terminal writes <job_name>.trm there.
options.setTerminalOut(new OutputFileTerminal(options.getOutputWorkingDirectory()));

XpsDevice device = new XpsDevice();
TeXJobResult result;
try {
    result = new TeXJob("hello-world", device, options).run();
} finally {
    device.dispose();
    output.close();
    input.close();
}

Set the output working directory before constructing OutputFileTerminal. It writes terminal output to <job_name>.trm, here hello-world.trm, in that directory. This terminal file is separate from the TeX transcript hello-world.log. To write terminal output elsewhere, pass a different IOutputWorkingDirectory implementation to the constructor.