Top Description Fields Constructors Methods
org.apache.pdfbox.contentstream

public abstract Class PDFStreamEngine

extends Object
Class Inheritance
Known Direct Subclasses
org.apache.pdfbox.text.LegacyPDFStreamEngine, org.apache.pdfbox.contentstream.PDFGraphicsStreamEngine
Imports
java.awt.geom.GeneralPath, .Point2D, .Rectangle2D, java.io.ByteArrayInputStream, .IOException, .InputStream, java.util.ArrayDeque, .ArrayList, .Deque, .HashMap, .List, .Map, java.util.zip.DataFormatException, org.apache.commons.logging.Log, .LogFactory, org.apache.pdfbox.contentstream.operator.MissingOperandException, .Operator, .OperatorName, .OperatorProcessor, org.apache.pdfbox.contentstream.operator.state.EmptyGraphicsStackException, org.apache.pdfbox.cos.COSArray, .COSBase, .COSDictionary, .COSName, .COSNumber, .COSString, org.apache.pdfbox.filter.MissingImageReaderException, org.apache.pdfbox.pdfparser.PDFStreamParser, org.apache.pdfbox.pdmodel.MissingResourceException, .PDPage, .PDResources, org.apache.pdfbox.pdmodel.common.PDRectangle, org.apache.pdfbox.pdmodel.font.PDFont, .PDType1Font, .PDType3CharProc, .PDType3Font, .Standard14Fonts.FontName, org.apache.pdfbox.pdmodel.graphics.PDLineDashPattern, org.apache.pdfbox.pdmodel.graphics.color.PDColor, .PDColorSpace, org.apache.pdfbox.pdmodel.graphics.form.PDFormXObject, .PDTransparencyGroup, org.apache.pdfbox.pdmodel.graphics.pattern.PDTilingPattern, org.apache.pdfbox.pdmodel.graphics.state.PDGraphicsState, .PDTextState, org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotation, .PDAppearanceStream, org.apache.pdfbox.util.Matrix, .Vector, org.apache.pdfbox.pdmodel.graphics.blend.BlendMode

Processes a PDF content stream and executes certain operations. Provides a callback interface for clients that want to do things with the stream.
Author
Ben Litchfield

Field Summary

Modifier and TypeField and Description
private PDPage
private PDFont
private Deque<PDGraphicsState>
private Matrix
private boolean
private int
private static final Log
private final Map<String, OperatorProcessor>
private PDResources
private boolean

Constructor Summary

AccessConstructor and Description
protected
PDFStreamEngine()

Creates a new PDFStreamEngine.

Method Summary

Modifier and TypeMethod and Description
public final void
addOperator(OperatorProcessor
operator processor
op
)

Adds an operator processor to the engine.

protected void
applyTextAdjustment(float
x-translation
tx
,
float
y-translation
ty
)

Applies a text position adjustment from the TJ operator.

public void
beginMarkedContentSequence(COSName
indicates the role or significance of the sequence
tag
,
COSDictionary
optional properties
properties
)

Called when a marked content group begins

public void
beginText()

Called when the BT operator is encountered.

private void
clipToRect(PDRectangle rectangle)

Transforms the given rectangle using the CTM and then intersects it with the current clipping area.

public void
decreaseLevel()

Decrease the level.

public void
endMarkedContentSequence()

Called when a marked content group ends

public void
endText()

Called when the ET operator is encountered.

public PDAppearanceStream

Returns:

The stream to process.
getAppearance
(PDAnnotation
The current annotation.
annotation
)

Returns the appearance stream to process for the given annotation.

public PDPage

Returns:

the current page
getCurrentPage
()

Returns the current page.

private PDFont

Returns:

the default font
getDefaultFont
()

Provide standard 14 Helvetica font as default if there isn't any font available.

public int

Returns:

Returns the size of the graphicsStack.
getGraphicsStackSize
()

public PDGraphicsState

Returns:

Returns the graphicsState.
getGraphicsState
()

public Matrix

Returns:

the initial matrix
getInitialMatrix
()

Gets the stream's initial matrix.

public int

Returns:

the current level.
getLevel
()

Get the current level.

public PDResources

Returns:

the stream' resources. This is mainly to be used by the OperatorProcessor classes.
getResources
()

public Matrix

Returns:

Returns the textLineMatrix.
getTextLineMatrix
()

public Matrix

Returns:

Returns the textMatrix.
getTextMatrix
()

public void
increaseLevel()

Increase the level.

private void
initPage(PDPage page)

Initializes the stream engine for the given page.

public boolean

Returns:

true if color operators should be processed, false if not, e.g. in type3 charprocs with d1 or in uncolored tiling patterns.
isShouldProcessColorOperators
()

Tells whether color operators should be processed.

protected void
operatorException(Operator
The unknown operator.
operator
,
List<COSBase>
The list of operands.
operands
,
IOException
the excpetion which occured when processing the operator
exception
)

Called when an exception is thrown by an operator.

private void
popResources(PDResources parentResources)

Pops the current resources, replacing them with the given resources.

protected void
processAnnotation(PDAnnotation
The annotation containing the appearance stream to process.
annotation
,
PDAppearanceStream
The appearance stream to process.
appearance
)

Process the given annotation with the specified appearance stream.

protected void
processChildStream(PDContentStream
the child content stream
contentStream
,
PDPage
the page to be used for processing
page
)

Process a child stream of the given page.

public void
processOperator(String
The operation to perform.
operation
,
List<COSBase>
The list of arguments.
arguments
)

This is used to handle an operation.

protected void
processOperator(Operator
The operation to perform.
operator
,
List<COSBase>
The list of arguments.
operands
)

This is used to handle an operation.

public void
processPage(PDPage
the page to process
page
)

This will initialize and process the contents of the stream.

protected void
processSoftMask(PDTransparencyGroup
transparency group used for the soft mask
group
)

Processes a soft mask transparency group stream.

private void
processStream(PDContentStream
the content stream
contentStream
)

Process a content stream.

private void
processStreamOperators(PDContentStream
to content stream to parse.
contentStream
)

Processes the operators of the given content stream.

protected final void
processTilingPattern(PDTilingPattern
the tiling pattern
tilingPattern
,
PDColor
color to use, if this is an uncoloured pattern, otherwise null.
color
,
PDColorSpace
color space to use, if this is an uncoloured pattern, otherwise null.
colorSpace
)

Process the given tiling pattern.

protected final void
processTilingPattern(PDTilingPattern
the tiling pattern
tilingPattern
,
PDColor
color to use, if this is an uncoloured pattern, otherwise null.
color
,
PDColorSpace
color space to use, if this is an uncoloured pattern, otherwise null.
colorSpace
,
Matrix
the pattern matrix, may be overridden for custom rendering.
patternMatrix
)

Process the given tiling pattern.

protected void
processTransparencyGroup(PDTransparencyGroup
transparency group to be processed
group
)

Processes a transparency group stream.

protected void
processType3Stream(PDType3CharProc
Type 3 character procedure
charProc
,
Matrix
the Text Rendering Matrix
textRenderingMatrix
)

Processes a Type 3 character stream.

private PDResources
pushResources(PDContentStream contentStream)

Pushes the given stream's resources, returning the previous resources.

protected final void
restoreGraphicsStack(Deque<PDGraphicsState>
the graphics state to be restored
snapshot
)

Restores the entire graphics stack.

public void
restoreGraphicsState()

Pops the current graphics state from the stack.

protected final Deque<PDGraphicsState>

Returns:

the saved graphics state stack.
saveGraphicsStack
()

Saves the entire graphics stack.

public void
saveGraphicsState()

Pushes the current graphics state to the stack.

public void
setLineDashPattern(COSArray
dash array
array
,
int
dash phase
phase
)

public void
setTextLineMatrix(Matrix
The textLineMatrix to set.
value
)

public void
setTextMatrix(Matrix
The textMatrix to set.
value
)

public void
showAnnotation(PDAnnotation
An annotation on the current page.
annotation
)

Shows the given annotation.

protected void
showFontGlyph(Matrix
the current text rendering matrix, Trm
textRenderingMatrix
,
PDFont
the current font
font
,
int
internal PDF character code for the glyph
code
,
Vector
the displacement (i.e. advance) of the glyph in text space
displacement
)

Called when a glyph is to be processed.

public void
showForm(PDFormXObject
form XObject
form
)

Shows a form from the content stream.

protected void
showGlyph(Matrix
the current text rendering matrix, Trm
textRenderingMatrix
,
PDFont
the current font
font
,
int
internal PDF character code for the glyph
code
,
Vector
the displacement (i.e. advance) of the glyph in text space
displacement
)

Called when a glyph is to be processed.

protected void
showText(byte[]
the encoded text
string
)

Process text from the PDF Stream.

public void
showTextString(byte[]
the encoded text
string
)

Called when a string of text is to be shown.

public void
showTextStrings(COSArray
array of encoded text strings and adjustments
array
)

Called when a string of text with spacing adjustments is to be shown.

public void
showTransparencyGroup(PDTransparencyGroup
transparency group (form) XObject
form
)

Shows a transparency group from the content stream.

protected void
showType3Glyph(Matrix
the current text rendering matrix, Trm
textRenderingMatrix
,
PDType3Font
the current font
font
,
int
internal PDF character code for the glyph
code
,
Vector
the displacement (i.e. advance) of the glyph in text space
displacement
)

Called when a glyph is to be processed.

public Point2D.Float

Returns:

the transformed point
transformedPoint
(float
the x-coordinate of the point to be transformed
x
,
float
the y-coordinate of the point to be transformed
y
)

Transforms a point using the CTM.

protected float

Returns:

the transformed width
transformWidth
(float
the width to be transformed
width
)

Transforms a width using the CTM.

protected void
unsupportedOperator(Operator
The unknown operator.
operator
,
List<COSBase>
The list of operands.
operands
)

Called when an unsupported operator is encountered.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

currentPageback to summary
private PDPage currentPage
defaultFontback to summary
private PDFont defaultFont
graphicsStackback to summary
private Deque<PDGraphicsState> graphicsStack
initialMatrixback to summary
private Matrix initialMatrix
isProcessingPageback to summary
private boolean isProcessingPage
levelback to summary
private int level
LOGback to summary
private static final Log LOG
operatorsback to summary
private final Map<String, OperatorProcessor> operators
resourcesback to summary
private PDResources resources
shouldProcessColorOperatorsback to summary
private boolean shouldProcessColorOperators

Constructor Detail

PDFStreamEngineback to summary
protected PDFStreamEngine()

Creates a new PDFStreamEngine.

Method Detail

addOperatorback to summary
public final void addOperator(OperatorProcessor op)

Adds an operator processor to the engine.

Parameters
op:OperatorProcessor

operator processor

applyTextAdjustmentback to summary
protected void applyTextAdjustment(float tx, float ty)

Applies a text position adjustment from the TJ operator. May be overridden in subclasses.

Parameters
tx:float

x-translation

ty:float

y-translation

beginMarkedContentSequenceback to summary
public void beginMarkedContentSequence(COSName tag, COSDictionary properties)

Called when a marked content group begins

Parameters
tag:COSName

indicates the role or significance of the sequence

properties:COSDictionary

optional properties

beginTextback to summary
public void beginText() throws IOException

Called when the BT operator is encountered. This method is for overriding in subclasses, the default implementation does nothing.

Exceptions
IOException:
if there was an error processing the text
clipToRectback to summary
private void clipToRect(PDRectangle rectangle)

Transforms the given rectangle using the CTM and then intersects it with the current clipping area.

decreaseLevelback to summary
public void decreaseLevel()

Decrease the level. Call this after running a potentially recursive operation. A log message is shown if the level is below 0. This can happen if the level is not decreased after an operation is done, e.g. by using a "finally" block.

endMarkedContentSequenceback to summary
public void endMarkedContentSequence()

Called when a marked content group ends

endTextback to summary
public void endText() throws IOException

Called when the ET operator is encountered. This method is for overriding in subclasses, the default implementation does nothing.

Exceptions
IOException:
if there was an error processing the text
getAppearanceback to summary
public PDAppearanceStream getAppearance(PDAnnotation annotation)

Returns the appearance stream to process for the given annotation. May be used to render a specific appearance such as "hover".

Parameters
annotation:PDAnnotation

The current annotation.

Returns:PDAppearanceStream

The stream to process.

getCurrentPageback to summary
public PDPage getCurrentPage()

Returns the current page.

Returns:PDPage

the current page

getDefaultFontback to summary
private PDFont getDefaultFont()

Provide standard 14 Helvetica font as default if there isn't any font available.

Returns:PDFont

the default font

getGraphicsStackSizeback to summary
public int getGraphicsStackSize()
Returns:int

Returns the size of the graphicsStack.

getGraphicsStateback to summary
public PDGraphicsState getGraphicsState()
Returns:PDGraphicsState

Returns the graphicsState.

getInitialMatrixback to summary
public Matrix getInitialMatrix()

Gets the stream's initial matrix.

Returns:Matrix

the initial matrix

getLevelback to summary
public int getLevel()

Get the current level. This can be used to decide whether a recursion has done too deep and an operation should be skipped to avoid a stack overflow.

Returns:int

the current level.

getResourcesback to summary
public PDResources getResources()
Returns:PDResources

the stream' resources. This is mainly to be used by the OperatorProcessor classes.

getTextLineMatrixback to summary
public Matrix getTextLineMatrix()
Returns:Matrix

Returns the textLineMatrix.

getTextMatrixback to summary
public Matrix getTextMatrix()
Returns:Matrix

Returns the textMatrix.

increaseLevelback to summary
public void increaseLevel()

Increase the level. Call this before running a potentially recursive operation.

initPageback to summary
private void initPage(PDPage page)

Initializes the stream engine for the given page.

isShouldProcessColorOperatorsback to summary
public boolean isShouldProcessColorOperators()

Tells whether color operators should be processed. To be used in some OperatorProcessor classes.

Returns:boolean

true if color operators should be processed, false if not, e.g. in type3 charprocs with d1 or in uncolored tiling patterns.

operatorExceptionback to summary
protected void operatorException(Operator operator, List<COSBase> operands, IOException exception) throws IOException

Called when an exception is thrown by an operator.

Parameters
operator:Operator

The unknown operator.

operands:List<COSBase>

The list of operands.

exception:IOException

the excpetion which occured when processing the operator

Exceptions
IOException:
if there is an error processing the operator exception
popResourcesback to summary
private void popResources(PDResources parentResources)

Pops the current resources, replacing them with the given resources.

processAnnotationback to summary
protected void processAnnotation(PDAnnotation annotation, PDAppearanceStream appearance) throws IOException

Process the given annotation with the specified appearance stream.

Parameters
annotation:PDAnnotation

The annotation containing the appearance stream to process.

appearance:PDAppearanceStream

The appearance stream to process.

Exceptions
IOException:
If there is an error reading or parsing the appearance content stream.
processChildStreamback to summary
protected void processChildStream(PDContentStream contentStream, PDPage page) throws IOException

Process a child stream of the given page. Cannot be used with processPage(PDPage).

Parameters
contentStream:PDContentStream

the child content stream

page:PDPage

the page to be used for processing

Exceptions
IOException:
if there is an exception while processing the stream
processOperatorback to summary
public void processOperator(String operation, List<COSBase> arguments) throws IOException

This is used to handle an operation.

Parameters
operation:String

The operation to perform.

arguments:List<COSBase>

The list of arguments.

Exceptions
IOException:
If there is an error processing the operation.
processOperatorback to summary
protected void processOperator(Operator operator, List<COSBase> operands) throws IOException

This is used to handle an operation.

Parameters
operator:Operator

The operation to perform.

operands:List<COSBase>

The list of arguments.

Exceptions
IOException:
If there is an error processing the operation.
processPageback to summary
public void processPage(PDPage page) throws IOException

This will initialize and process the contents of the stream.

Parameters
page:PDPage

the page to process

Exceptions
IOException:
if there is an error accessing the stream
processSoftMaskback to summary
protected void processSoftMask(PDTransparencyGroup group) throws IOException

Processes a soft mask transparency group stream.

Parameters
group:PDTransparencyGroup

transparency group used for the soft mask

Exceptions
IOException:
if the transparency group cannot be processed
processStreamback to summary
private void processStream(PDContentStream contentStream) throws IOException

Process a content stream.

Parameters
contentStream:PDContentStream

the content stream

Exceptions
IOException:
if there is an exception while processing the stream
processStreamOperatorsback to summary
private void processStreamOperators(PDContentStream contentStream) throws IOException

Processes the operators of the given content stream.

Parameters
contentStream:PDContentStream

to content stream to parse.

Exceptions
IOException:
if there is an error reading or parsing the content stream.
processTilingPatternback to summary
protected final void processTilingPattern(PDTilingPattern tilingPattern, PDColor color, PDColorSpace colorSpace) throws IOException

Process the given tiling pattern.

Parameters
tilingPattern:PDTilingPattern

the tiling pattern

color:PDColor

color to use, if this is an uncoloured pattern, otherwise null.

colorSpace:PDColorSpace

color space to use, if this is an uncoloured pattern, otherwise null.

Exceptions
IOException:
if there is an error reading or parsing the tiling pattern content stream.
processTilingPatternback to summary
protected final void processTilingPattern(PDTilingPattern tilingPattern, PDColor color, PDColorSpace colorSpace, Matrix patternMatrix) throws IOException

Process the given tiling pattern. Allows the pattern matrix to be overridden for custom rendering.

Parameters
tilingPattern:PDTilingPattern

the tiling pattern

color:PDColor

color to use, if this is an uncoloured pattern, otherwise null.

colorSpace:PDColorSpace

color space to use, if this is an uncoloured pattern, otherwise null.

patternMatrix:Matrix

the pattern matrix, may be overridden for custom rendering.

Exceptions
IOException:
if there is an error reading or parsing the tiling pattern content stream.
processTransparencyGroupback to summary
protected void processTransparencyGroup(PDTransparencyGroup group) throws IOException

Processes a transparency group stream.

Parameters
group:PDTransparencyGroup

transparency group to be processed

Exceptions
IOException:
if the transparency group cannot be processed
processType3Streamback to summary
protected void processType3Stream(PDType3CharProc charProc, Matrix textRenderingMatrix) throws IOException

Processes a Type 3 character stream.

Parameters
charProc:PDType3CharProc

Type 3 character procedure

textRenderingMatrix:Matrix

the Text Rendering Matrix

Exceptions
IOException:
if there is an error reading or parsing the character content stream.
pushResourcesback to summary
private PDResources pushResources(PDContentStream contentStream)

Pushes the given stream's resources, returning the previous resources.

restoreGraphicsStackback to summary
protected final void restoreGraphicsStack(Deque<PDGraphicsState> snapshot)

Restores the entire graphics stack.

Parameters
snapshot:Deque<PDGraphicsState>

the graphics state to be restored

restoreGraphicsStateback to summary
public void restoreGraphicsState()

Pops the current graphics state from the stack.

saveGraphicsStackback to summary
protected final Deque<PDGraphicsState> saveGraphicsStack()

Saves the entire graphics stack.

Returns:Deque<PDGraphicsState>

the saved graphics state stack.

saveGraphicsStateback to summary
public void saveGraphicsState()

Pushes the current graphics state to the stack.

setLineDashPatternback to summary
public void setLineDashPattern(COSArray array, int phase)
Parameters
array:COSArray

dash array

phase:int

dash phase

setTextLineMatrixback to summary
public void setTextLineMatrix(Matrix value)
Parameters
value:Matrix

The textLineMatrix to set.

setTextMatrixback to summary
public void setTextMatrix(Matrix value)
Parameters
value:Matrix

The textMatrix to set.

showAnnotationback to summary
public void showAnnotation(PDAnnotation annotation) throws IOException

Shows the given annotation.

Parameters
annotation:PDAnnotation

An annotation on the current page.

Exceptions
IOException:
If an error occurred reading the annotation
showFontGlyphback to summary
protected void showFontGlyph(Matrix textRenderingMatrix, PDFont font, int code, Vector displacement) throws IOException

Called when a glyph is to be processed. This method is intended for overriding in subclasses, the default implementation does nothing.

Parameters
textRenderingMatrix:Matrix

the current text rendering matrix, Trm

font:PDFont

the current font

code:int

internal PDF character code for the glyph

displacement:Vector

the displacement (i.e. advance) of the glyph in text space

Exceptions
IOException:
if the glyph cannot be processed
showFormback to summary
public void showForm(PDFormXObject form) throws IOException

Shows a form from the content stream.

Parameters
form:PDFormXObject

form XObject

Exceptions
IOException:
if the form cannot be processed
showGlyphback to summary
protected void showGlyph(Matrix textRenderingMatrix, PDFont font, int code, Vector displacement) throws IOException

Called when a glyph is to be processed. This method is intended for overriding in subclasses, the default implementation does nothing.

Parameters
textRenderingMatrix:Matrix

the current text rendering matrix, Trm

font:PDFont

the current font

code:int

internal PDF character code for the glyph

displacement:Vector

the displacement (i.e. advance) of the glyph in text space

Exceptions
IOException:
if the glyph cannot be processed
showTextback to summary
protected void showText(byte[] string) throws IOException

Process text from the PDF Stream. You should override this method if you want to perform an action when encoded text is being processed.

Parameters
string:byte[]

the encoded text

Exceptions
IOException:
if there is an error processing the string
showTextStringback to summary
public void showTextString(byte[] string) throws IOException

Called when a string of text is to be shown.

Parameters
string:byte[]

the encoded text

Exceptions
IOException:
if there was an error showing the text
showTextStringsback to summary
public void showTextStrings(COSArray array) throws IOException

Called when a string of text with spacing adjustments is to be shown.

Parameters
array:COSArray

array of encoded text strings and adjustments

Exceptions
IOException:
if there was an error showing the text
showTransparencyGroupback to summary
public void showTransparencyGroup(PDTransparencyGroup form) throws IOException

Shows a transparency group from the content stream.

Parameters
form:PDTransparencyGroup

transparency group (form) XObject

Exceptions
IOException:
if the transparency group cannot be processed
showType3Glyphback to summary
protected void showType3Glyph(Matrix textRenderingMatrix, PDType3Font font, int code, Vector displacement) throws IOException

Called when a glyph is to be processed. This method is intended for overriding in subclasses, the default implementation does nothing.

Parameters
textRenderingMatrix:Matrix

the current text rendering matrix, Trm

font:PDType3Font

the current font

code:int

internal PDF character code for the glyph

displacement:Vector

the displacement (i.e. advance) of the glyph in text space

Exceptions
IOException:
if the glyph cannot be processed
transformedPointback to summary
public Point2D.Float transformedPoint(float x, float y)

Transforms a point using the CTM.

Parameters
x:float

the x-coordinate of the point to be transformed

y:float

the y-coordinate of the point to be transformed

Returns:Point2D.Float

the transformed point

transformWidthback to summary
protected float transformWidth(float width)

Transforms a width using the CTM.

Parameters
width:float

the width to be transformed

Returns:float

the transformed width

unsupportedOperatorback to summary
protected void unsupportedOperator(Operator operator, List<COSBase> operands) throws IOException

Called when an unsupported operator is encountered.

Parameters
operator:Operator

The unknown operator.

operands:List<COSBase>

The list of operands.

Exceptions
IOException:
if there is an error processing the unsupported operator