com.itextpdf.kernel.pdf

Class MemoryLimitsAwareHandler

java.lang.Object

com.itextpdf.kernel.pdf.MemoryLimitsAwareHandler

public class MemoryLimitsAwareHandler
extends Object

Enforces configurable limits intended to protect PDF reading/parsing against excessive memory consumption.

The handler is primarily used during decoding (decompression) of PDF streams, but also guards against other potentially unbounded structures during reading, e.g. cross-reference (xref) table growth and per-page XObject usage.

How it is configured

A configured handler can be set on ReaderProperties and will be used by PdfReader when opening a document.

See Also:

ReaderProperties.setMemoryLimitsAwareHandler(MemoryLimitsAwareHandler), MemoryLimitsAwareException

Constructor Summary

Constructors

Constructor and Description
MemoryLimitsAwareHandler() Creates a MemoryLimitsAwareHandler to handle decompression of PDF streams and other memory-related limits during reading.
MemoryLimitsAwareHandler(long documentSize) Creates a MemoryLimitsAwareHandler with calculated memory limits for decompression and xref structures based on the provided document size.

Method Summary

Modifier and Type	Method and Description
protected static int	calculateMaxElementsInXref(long documentSizeInBytes) Calculate max number of elements allowed in xref table based on the size of the document, achieving max limit at 100MB.
void	checkIfPageSizeExceedsTheLimit(long totalXObjectsSize)
void	checkIfXrefStructureExceedsTheLimit(int requestedCapacity) Performs a check of possible extension of xref structure.
MemoryLimitsAwareHandler	createNewInstance() Creates a new instance of MemoryLimitsAwareHandler by copying settings from this instance of MemoryLimitsAwareHandler.
int	getMaxNumberOfElementsInXrefStructure() Gets maximum number of elements in xref structure.
long	getMaxSizeOfDecompressedPdfStreamsSum() Gets the maximum allowed size which can be occupied by all decompressed pdf streams.
int	getMaxSizeOfSingleDecompressedPdfStream() Returns the maximum allowed size (in bytes) of a single decompressed PDF stream.
long	getMaxXObjectsSizePerPage() Gets maximum page size.
boolean	isMemoryLimitsAwarenessRequiredOnDecompression(PdfArray filters) Performs a check if the PdfStream with provided setup of the filters requires memory limits awareness during decompression.
void	setMaxNumberOfElementsInXrefStructure(int maxNumberOfElementsInXrefStructure) Sets maximum number of elements in xref structure.
MemoryLimitsAwareHandler	setMaxSizeOfDecompressedPdfStreamsSum(long maxSizeOfDecompressedPdfStreamsSum) Sets the maximum allowed size which can be occupied by all decompressed pdf streams.
MemoryLimitsAwareHandler	setMaxSizeOfSingleDecompressedPdfStream(int maxSizeOfSingleDecompressedPdfStream) Sets the maximum allowed size which can be occupied by a single decompressed pdf stream.
void	setMaxXObjectsSizePerPage(long maxPageSize) Sets maximum page size.

Methods inherited from class java.lang.Object

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

Constructor Detail

MemoryLimitsAwareHandler

public MemoryLimitsAwareHandler()

Creates a MemoryLimitsAwareHandler to handle decompression of PDF streams and other memory-related limits during reading.

MemoryLimitsAwareHandler

public MemoryLimitsAwareHandler(long documentSize)

Creates a MemoryLimitsAwareHandler with calculated memory limits for decompression and xref structures based on the provided document size.

Parameters:

documentSize - the size of the document (in bytes).

Method Detail

createNewInstance

public MemoryLimitsAwareHandler createNewInstance()

Creates a new instance of MemoryLimitsAwareHandler by copying settings from this instance of MemoryLimitsAwareHandler.

Returns:

a new instance of MemoryLimitsAwareHandler.

getMaxSizeOfSingleDecompressedPdfStream

public int getMaxSizeOfSingleDecompressedPdfStream()

Returns the maximum allowed size (in bytes) of a single decompressed PDF stream.

Returns:

maximum allowed size of a single decompressed stream in bytes.

setMaxSizeOfSingleDecompressedPdfStream

public MemoryLimitsAwareHandler setMaxSizeOfSingleDecompressedPdfStream(int maxSizeOfSingleDecompressedPdfStream)

Sets the maximum allowed size which can be occupied by a single decompressed pdf stream. This value correlates with maximum heap size. This value should not exceed limit of the heap size.

iText will throw an exception if during decompression a pdf stream which was identified as requiring memory limits awareness occupies more memory than allowed.

Parameters:

maxSizeOfSingleDecompressedPdfStream - the maximum allowed size which can be occupied by a single decompressed pdf stream.

Returns:

this MemoryLimitsAwareHandler instance.

See Also:

isMemoryLimitsAwarenessRequiredOnDecompression(PdfArray)

getMaxSizeOfDecompressedPdfStreamsSum

public long getMaxSizeOfDecompressedPdfStreamsSum()

Gets the maximum allowed size which can be occupied by all decompressed pdf streams.

Returns:

the maximum allowed size value which streams may occupy

setMaxSizeOfDecompressedPdfStreamsSum

public MemoryLimitsAwareHandler setMaxSizeOfDecompressedPdfStreamsSum(long maxSizeOfDecompressedPdfStreamsSum)

Sets the maximum allowed size which can be occupied by all decompressed pdf streams. This value can be limited by the maximum expected PDF file size when it's completely decompressed. Setting this value correlates with the maximum processing time spent on document reading

iText will throw an exception if during decompression pdf streams which were identified as requiring memory limits awareness occupy more memory than allowed.

Parameters:

maxSizeOfDecompressedPdfStreamsSum - he maximum allowed size which can be occupied by all decompressed pdf streams.

Returns:

this MemoryLimitsAwareHandler instance.

See Also:

isMemoryLimitsAwarenessRequiredOnDecompression(PdfArray)

isMemoryLimitsAwarenessRequiredOnDecompression

public boolean isMemoryLimitsAwarenessRequiredOnDecompression(PdfArray filters)

Performs a check if the PdfStream with provided setup of the filters requires memory limits awareness during decompression.

Parameters:

filters - is an PdfArray of names of filters

Returns:

true if PDF stream is suspicious and false otherwise

getMaxNumberOfElementsInXrefStructure

public int getMaxNumberOfElementsInXrefStructure()

Gets maximum number of elements in xref structure.

Returns:

maximum number of elements in xref structure.

getMaxXObjectsSizePerPage

public long getMaxXObjectsSizePerPage()

Gets maximum page size.

Returns:

maximum page size.

setMaxXObjectsSizePerPage

public void setMaxXObjectsSizePerPage(long maxPageSize)

Sets maximum page size.

Parameters:

maxPageSize - maximum page size.

setMaxNumberOfElementsInXrefStructure

public void setMaxNumberOfElementsInXrefStructure(int maxNumberOfElementsInXrefStructure)

Sets maximum number of elements in xref structure.

Parameters:

maxNumberOfElementsInXrefStructure - maximum number of elements in xref structure.

checkIfXrefStructureExceedsTheLimit

public void checkIfXrefStructureExceedsTheLimit(int requestedCapacity)

Performs a check of possible extension of xref structure.

Parameters:

requestedCapacity - capacity to which we need to expand xref array.

checkIfPageSizeExceedsTheLimit

public void checkIfPageSizeExceedsTheLimit(long totalXObjectsSize)

calculateMaxElementsInXref

protected static int calculateMaxElementsInXref(long documentSizeInBytes)

Calculate max number of elements allowed in xref table based on the size of the document, achieving max limit at 100MB.

Parameters:

documentSizeInBytes - document size in bytes.

Returns:

calculated limit.