Package com.pdftools.pdfa.conversion

Class Converter

java.lang.Object

com.pdftools.internal.NativeBase

com.pdftools.internal.NativeObject

com.pdftools.pdfa.conversion.Converter

public class Converter
extends NativeObject

The class to convert PDF documents to PDF/A

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	Converter.ConversionEvent	The event for errors, warnings, and informational messages that occur during conversion
static interface	Converter.ConversionEventListener	Listener interface for the Converter.ConversionEvent event.

Constructor Summary

Constructors

Constructor	Description
Converter()

Method Summary

Modifier and Type	Method	Description
void	addAssociatedFile(Stream embeddedFile, String name)	Prepares the associated file for embedding.
void	addAssociatedFile(Stream embeddedFile, String name, Integer associate)	Prepares the associated file for embedding.
void	addAssociatedFile(Stream embeddedFile, String name, Integer associate, AFRelationship afRelationship)	Prepares the associated file for embedding.
void	addAssociatedFile(Stream embeddedFile, String name, Integer associate, AFRelationship afRelationship, String mimeType)	Prepares the associated file for embedding.
void	addAssociatedFile(Stream embeddedFile, String name, Integer associate, AFRelationship afRelationship, String mimeType, String description)	Prepares the associated file for embedding.
void	addAssociatedFile(Stream embeddedFile, String name, Integer associate, AFRelationship afRelationship, String mimeType, String description, OffsetDateTime modificationDate)	Prepares the associated file for embedding.
void	addConversionEventListener(Converter.ConversionEventListener listener)	Add a listener for the Converter.ConversionEvent event.
void	addInvoiceXml(InvoiceType invoiceType, Stream invoice)	Prepares the invoice XML file (ZUGFeRD or Factur-X) for embedding.
void	addInvoiceXml(InvoiceType invoiceType, Stream invoice, AFRelationship afRelationship)	Prepares the invoice XML file (ZUGFeRD or Factur-X) for embedding.
Document	convert(AnalysisResult analysis, Document document, Stream outStream)	Convert a document to PDF/A.
Document	convert(AnalysisResult analysis, Document document, Stream outStream, ConversionOptions options)	Convert a document to PDF/A.
Document	convert(AnalysisResult analysis, Document document, Stream outStream, ConversionOptions options, OutputOptions outOptions)	Convert a document to PDF/A.
void	removeConversionEventListener(Converter.ConversionEventListener listener)	Remove registered listener for the Converter.ConversionEvent event.

Methods inherited from class com.pdftools.internal.NativeObject

equals, hashCode

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Converter

public Converter()

Method Details

addConversionEventListener

public void addConversionEventListener(Converter.ConversionEventListener listener)

Add a listener for the Converter.ConversionEvent event.

Parameters:

listener - Listener for the Converter.ConversionEvent event. If a listener is added that is already registered, it is ignored.

removeConversionEventListener

public void removeConversionEventListener(Converter.ConversionEventListener listener)

Remove registered listener for the Converter.ConversionEvent event.

Parameters:

listener - Listener for the Converter.ConversionEvent event that should be removed. If the listener is not registered, it is ignored.

addInvoiceXml

public void addInvoiceXml(InvoiceType invoiceType,
 Stream invoice)

Prepares the invoice XML file (ZUGFeRD or Factur-X) for embedding.

Note: This requires the compliance to be set to PDF/A-3.

Parameters:

invoiceType - The type of invoice.

invoice - The XML invoice stream.

Throws:

IllegalArgumentException - The invoice stream could not be opened for reading.

IllegalArgumentException - if invoiceType is null

IllegalArgumentException - if invoice is null

addInvoiceXml

public void addInvoiceXml(InvoiceType invoiceType,
 Stream invoice,
 AFRelationship afRelationship)

Prepares the invoice XML file (ZUGFeRD or Factur-X) for embedding.

Note: This requires the compliance to be set to PDF/A-3.

Parameters:

invoiceType - The type of invoice.

invoice - The XML invoice stream.

afRelationship - If no value is provided, a sensible default value is chosen based on the invoice type and version.

Throws:

IllegalArgumentException - The invoice stream could not be opened for reading.

IllegalArgumentException - if invoiceType is null

IllegalArgumentException - if invoice is null

addAssociatedFile

public void addAssociatedFile(Stream embeddedFile,
 String name)
                       throws IOException

Prepares the associated file for embedding.

Add a file to the document’s embedded files. For PDF/A-3, the embedded file is associated with an object of the document, i.e. it is an associated file. The file is embedded as-is. Embedding files is not allowed for PDF/A-1 and restricted to PDF/A conforming files for PDF/A-2.

Parameters:

embeddedFile - The stream of the embedded file.

name - The name used for the embedded file. This name is presented to the user when viewing the list of embedded files.

Throws:

IllegalArgumentException - The associated file stream could not be opened for reading.

IllegalArgumentException - The associate argument is invalid.

IOException - Error reading from embeddedFile.

IllegalArgumentException - if embeddedFile is null

IllegalArgumentException - if name is null

addAssociatedFile

public void addAssociatedFile(Stream embeddedFile,
 String name,
 Integer associate)
                       throws IOException

Prepares the associated file for embedding.

Add a file to the document’s embedded files. For PDF/A-3, the embedded file is associated with an object of the document, i.e. it is an associated file. The file is embedded as-is. Embedding files is not allowed for PDF/A-1 and restricted to PDF/A conforming files for PDF/A-2.

Parameters:

embeddedFile - The stream of the embedded file.

name - The name used for the embedded file. This name is presented to the user when viewing the list of embedded files.

associate - The object to associate the embedded file with, -1 for none, 0 for document, number greater than 0 for respective page. If null, the default value is 0 for PDF/A-3 and -1 otherwise.

Throws:

IllegalArgumentException - The associated file stream could not be opened for reading.

IllegalArgumentException - The associate argument is invalid.

IOException - Error reading from embeddedFile.

IllegalArgumentException - if embeddedFile is null

IllegalArgumentException - if name is null

addAssociatedFile

public void addAssociatedFile(Stream embeddedFile,
 String name,
 Integer associate,
 AFRelationship afRelationship)
                       throws IOException

Prepares the associated file for embedding.

Add a file to the document’s embedded files. For PDF/A-3, the embedded file is associated with an object of the document, i.e. it is an associated file. The file is embedded as-is. Embedding files is not allowed for PDF/A-1 and restricted to PDF/A conforming files for PDF/A-2.

Parameters:

embeddedFile - The stream of the embedded file.

name - The name used for the embedded file. This name is presented to the user when viewing the list of embedded files.

associate - The object to associate the embedded file with, -1 for none, 0 for document, number greater than 0 for respective page. If null, the default value is 0 for PDF/A-3 and -1 otherwise.

afRelationship - The relationship of the embedded file to the object associate. (Ignored, if associate is -1.) If null, the default value is AFRelationship.UNSPECIFIED.

Throws:

IllegalArgumentException - The associated file stream could not be opened for reading.

IllegalArgumentException - The associate argument is invalid.

IOException - Error reading from embeddedFile.

IllegalArgumentException - if embeddedFile is null

IllegalArgumentException - if name is null

addAssociatedFile

public void addAssociatedFile(Stream embeddedFile,
 String name,
 Integer associate,
 AFRelationship afRelationship,
 String mimeType)
                       throws IOException

Prepares the associated file for embedding.

Add a file to the document’s embedded files. For PDF/A-3, the embedded file is associated with an object of the document, i.e. it is an associated file. The file is embedded as-is. Embedding files is not allowed for PDF/A-1 and restricted to PDF/A conforming files for PDF/A-2.

Parameters:

embeddedFile - The stream of the embedded file.

name - The name used for the embedded file. This name is presented to the user when viewing the list of embedded files.

associate - The object to associate the embedded file with, -1 for none, 0 for document, number greater than 0 for respective page. If null, the default value is 0 for PDF/A-3 and -1 otherwise.

afRelationship - The relationship of the embedded file to the object associate. (Ignored, if associate is -1.) If null, the default value is AFRelationship.UNSPECIFIED.

mimeType - MIME ­Type of the embedded file. Common values other than the default are "application/pdf", "application/xml" or "application/msword". If null, the default value is "application/octet-stream".

Throws:

IllegalArgumentException - The associated file stream could not be opened for reading.

IllegalArgumentException - The associate argument is invalid.

IOException - Error reading from embeddedFile.

IllegalArgumentException - if embeddedFile is null

IllegalArgumentException - if name is null

addAssociatedFile

public void addAssociatedFile(Stream embeddedFile,
 String name,
 Integer associate,
 AFRelationship afRelationship,
 String mimeType,
 String description)
                       throws IOException

Prepares the associated file for embedding.

Add a file to the document’s embedded files. For PDF/A-3, the embedded file is associated with an object of the document, i.e. it is an associated file. The file is embedded as-is. Embedding files is not allowed for PDF/A-1 and restricted to PDF/A conforming files for PDF/A-2.

Parameters:

embeddedFile - The stream of the embedded file.

name - The name used for the embedded file. This name is presented to the user when viewing the list of embedded files.

associate - The object to associate the embedded file with, -1 for none, 0 for document, number greater than 0 for respective page. If null, the default value is 0 for PDF/A-3 and -1 otherwise.

afRelationship - The relationship of the embedded file to the object associate. (Ignored, if associate is -1.) If null, the default value is AFRelationship.UNSPECIFIED.

mimeType - MIME ­Type of the embedded file. Common values other than the default are "application/pdf", "application/xml" or "application/msword". If null, the default value is "application/octet-stream".

description - A description of the embedded file. This is presented to the user when viewing the list of embedded files. If null, the default value is "".

Throws:

IllegalArgumentException - The associated file stream could not be opened for reading.

IllegalArgumentException - The associate argument is invalid.

IOException - Error reading from embeddedFile.

IllegalArgumentException - if embeddedFile is null

IllegalArgumentException - if name is null

addAssociatedFile

public void addAssociatedFile(Stream embeddedFile,
 String name,
 Integer associate,
 AFRelationship afRelationship,
 String mimeType,
 String description,
 OffsetDateTime modificationDate)
                       throws IOException

Prepares the associated file for embedding.

Add a file to the document’s embedded files. For PDF/A-3, the embedded file is associated with an object of the document, i.e. it is an associated file. The file is embedded as-is. Embedding files is not allowed for PDF/A-1 and restricted to PDF/A conforming files for PDF/A-2.

Parameters:

embeddedFile - The stream of the embedded file.

name - The name used for the embedded file. This name is presented to the user when viewing the list of embedded files.

associate - The object to associate the embedded file with, -1 for none, 0 for document, number greater than 0 for respective page. If null, the default value is 0 for PDF/A-3 and -1 otherwise.

afRelationship - The relationship of the embedded file to the object associate. (Ignored, if associate is -1.) If null, the default value is AFRelationship.UNSPECIFIED.

mimeType - MIME ­Type of the embedded file. Common values other than the default are "application/pdf", "application/xml" or "application/msword". If null, the default value is "application/octet-stream".

description - A description of the embedded file. This is presented to the user when viewing the list of embedded files. If null, the default value is "".

modificationDate - The modify date of the file. If null, the default value is modification date of the file on the file system or current time, if not available.

Throws:

IllegalArgumentException - The associated file stream could not be opened for reading.

IllegalArgumentException - The associate argument is invalid.

IOException - Error reading from embeddedFile.

IllegalArgumentException - if embeddedFile is null

IllegalArgumentException - if name is null

convert

public Document convert(AnalysisResult analysis,
 Document document,
 Stream outStream)
                 throws IOException,
NotFoundException,
GenericException,
LicenseException,
CorruptException,
ConformanceException,
UnsupportedFeatureException,
ProcessingException

Convert a document to PDF/A.

Note that it is highly recommended to use Converter.ConversionEventListener to detect critical conversion events.

Parameters:

analysis - The result of the document's analysis using pdftools.pdfa.validation.Validator.analyze.

document - The document to convert

outStream - The stream where the converted document is written

Returns:

The result of the conversion

Throws:

LicenseException - The license check has failed.

IllegalArgumentException - The outOptions argument is invalid.

IllegalArgumentException - The output stream could not be opened for writing.

IllegalStateException - The document has already been closed.

IllegalArgumentException - The analysis has already been closed, e.g. due to a previous conversion.

IllegalArgumentException - The PDF/A version of the analysis and the conversion options do not match.

IllegalArgumentException - The analysis is not the analysis result of document.

IOException - Error reading from or writing to the outStream.

ConformanceException - The conformance required by options cannot be achieved.

• PDF/A level U: All text of the input document must be extractable.
• PDF/A level A: In addition to the requirements of level U, the input document must be tagged.

ConformanceException - The PDF/A version of the conformances of analysis and options differ. The same PDF/A version must be used for the analysis and conversion.

IllegalArgumentException - The outOptions specifies document encryption, which is not allowed in PDF/A documents.

GenericException - The document cannot be converted to PDF/A.

CorruptException - The analysis has been stopped.

ProcessingException - Failed to add the invoice file. Possible reasons include an invalid XML format, or that the invoice type conflicts with the content of the XML file.

UnsupportedFeatureException - The document is not a PDF, but an XFA document. See pdftools.pdf.Document.getXfa for more information on how to detect and handle XFA documents.

NotFoundException - A required font is missing from the installed font directories.

IllegalStateException - Invalid associate value for an embedded file.

IllegalArgumentException - if analysis is null

IllegalArgumentException - if document is null

IllegalArgumentException - if outStream is null

convert

public Document convert(AnalysisResult analysis,
 Document document,
 Stream outStream,
 ConversionOptions options)
                 throws IOException,
NotFoundException,
GenericException,
LicenseException,
CorruptException,
ConformanceException,
UnsupportedFeatureException,
ProcessingException

Convert a document to PDF/A.

Note that it is highly recommended to use Converter.ConversionEventListener to detect critical conversion events.

Parameters:

analysis - The result of the document's analysis using pdftools.pdfa.validation.Validator.analyze.

document - The document to convert

outStream - The stream where the converted document is written

options - The conversion options

Returns:

The result of the conversion

Throws:

LicenseException - The license check has failed.

IllegalArgumentException - The outOptions argument is invalid.

IllegalArgumentException - The output stream could not be opened for writing.

IllegalStateException - The document has already been closed.

IllegalArgumentException - The analysis has already been closed, e.g. due to a previous conversion.

IllegalArgumentException - The PDF/A version of the analysis and the conversion options do not match.

IllegalArgumentException - The analysis is not the analysis result of document.

IOException - Error reading from or writing to the outStream.

ConformanceException - The conformance required by options cannot be achieved.

• PDF/A level U: All text of the input document must be extractable.
• PDF/A level A: In addition to the requirements of level U, the input document must be tagged.

ConformanceException - The PDF/A version of the conformances of analysis and options differ. The same PDF/A version must be used for the analysis and conversion.

IllegalArgumentException - The outOptions specifies document encryption, which is not allowed in PDF/A documents.

GenericException - The document cannot be converted to PDF/A.

CorruptException - The analysis has been stopped.

ProcessingException - Failed to add the invoice file. Possible reasons include an invalid XML format, or that the invoice type conflicts with the content of the XML file.

UnsupportedFeatureException - The document is not a PDF, but an XFA document. See pdftools.pdf.Document.getXfa for more information on how to detect and handle XFA documents.

NotFoundException - A required font is missing from the installed font directories.

IllegalStateException - Invalid associate value for an embedded file.

IllegalArgumentException - if analysis is null

IllegalArgumentException - if document is null

IllegalArgumentException - if outStream is null

convert

public Document convert(AnalysisResult analysis,
 Document document,
 Stream outStream,
 ConversionOptions options,
 OutputOptions outOptions)
                 throws IOException,
NotFoundException,
GenericException,
LicenseException,
CorruptException,
ConformanceException,
UnsupportedFeatureException,
ProcessingException

Convert a document to PDF/A.

Note that it is highly recommended to use Converter.ConversionEventListener to detect critical conversion events.

Parameters:

analysis - The result of the document's analysis using pdftools.pdfa.validation.Validator.analyze.

document - The document to convert

outStream - The stream where the converted document is written

options - The conversion options

outOptions - The output options object

Returns:

The result of the conversion

Throws:

LicenseException - The license check has failed.

IllegalArgumentException - The outOptions argument is invalid.

IllegalArgumentException - The output stream could not be opened for writing.

IllegalStateException - The document has already been closed.

IllegalArgumentException - The analysis has already been closed, e.g. due to a previous conversion.

IllegalArgumentException - The PDF/A version of the analysis and the conversion options do not match.

IllegalArgumentException - The analysis is not the analysis result of document.

IOException - Error reading from or writing to the outStream.

ConformanceException - The conformance required by options cannot be achieved.

• PDF/A level U: All text of the input document must be extractable.
• PDF/A level A: In addition to the requirements of level U, the input document must be tagged.

ConformanceException - The PDF/A version of the conformances of analysis and options differ. The same PDF/A version must be used for the analysis and conversion.

IllegalArgumentException - The outOptions specifies document encryption, which is not allowed in PDF/A documents.

GenericException - The document cannot be converted to PDF/A.

CorruptException - The analysis has been stopped.

ProcessingException - Failed to add the invoice file. Possible reasons include an invalid XML format, or that the invoice type conflicts with the content of the XML file.

UnsupportedFeatureException - The document is not a PDF, but an XFA document. See pdftools.pdf.Document.getXfa for more information on how to detect and handle XFA documents.

NotFoundException - A required font is missing from the installed font directories.

IllegalStateException - Invalid associate value for an embedded file.

IllegalArgumentException - if analysis is null

IllegalArgumentException - if document is null

IllegalArgumentException - if outStream is null