Skip navigation links

oracle.xdo.common.pdf.util
Class PDFDocMerger

java.lang.Object
oracle.xdo.common.pdf.util.PDFDocMerger

public class PDFDocMerger

extends java.lang.Object

This class merges multiple PDF documents into one single document.

Basic usage

Here is a basic example on how to use it.

 // PDF documents to be merged.
 InputStream[] inStreams;
 
 // Output destination of the merged PDF document.
 OutputStream outStream;
  :
  :
  :
 // Create PDFDocMerger instance.
 PDFDocMerger pdfMerger = new PDFDocMerger(inStreams, outStream);
 
 // Run the merging process.
 pdfMerger.mergePDFDocs();
 

Please note that you cannot call mergePDFDocs() twice in this version. If you try to call the method twice, then it throws "NullPointerException". Please re-initialize PDFDocMerger and call mergePDFDocs().

Page numbering

This class also provides the page numbering functionality that allows you to put page numbering against the merged document. There are 2 ways to put page numbering. One is to use a background PDF document, the other is to use APIs.

Using background PDF

You can use a background PDF document to put page numbering in the merged PDF document. You can include a PDF form field as a placeholder for the page numbers. The field name should be @pagenum@. You can also set the default value of the start page number in the field. For example, if you put 2 in the field, the page numbers starts from 2 like 2, 3, 4 ... Here is a coding example.

 // Create PDFDocMerger instance.
 PDFDocMerger pdfMerger = new PDFDocMerger(inStreams, outStream);
 
 // Set the background PDF
 pdfMerger.setBackground(inStream);
 
 // Run the merging process.
 pdfMerger.mergePDFDocs();
 

Using APIs

You can also put page numbering in the merged document by calling a set of APIs. In this case, you don't have to create a background PDF document. You need to call the following methods.

• setPageNumberCoordinates(): Sets the absolute position of the page number in the document.
• setPageNumberFontInfo(): Sets the font information of the page numbers. (optional)
• setPageNumberValue(): Sets the numbering rules. (optional)

For example, if you would like to put the page nubmers in the bottom center of the merged document with the size 10 of Helvetica font, the page number starts from 2, the page numbering starts from the second page, the code is as follows.

 // Create PDFDocMerger instance.
 PDFDocMerger pdfMerger = new PDFDocMerger(inStreams, outStream);
 
 // Set the position of the page number
 pdfMerger.setPageNumberCoordinates(300, 20);
 
 // Set the font info of the page number
 pdfMerger.setPageNumberFontInfo("Helvetica", 10);
 
 // Set the numbering rules
 pdfMerger.setPageNumberValue(2, 2);
 
 // Run the merging process.
 pdfMerger.mergePDFDocs();
 

Version:

4.0

Author:

Incheol Kang.

Field Summary

static java.lang.String	RCS_ID
static java.lang.String	WATERMARK_ANGLE
static java.lang.String	WATERMARK_COLOR
static java.lang.String	WATERMARK_FONT
static java.lang.String	WATERMARK_FONT_SIZE
static java.lang.String	WATERMARK_POSITION
static java.lang.String	WATERMARK_TEXT
static java.lang.String	WATERMARK_TEXT_DEFAULT
static java.lang.String	WATERMARK_TO

Constructor Summary

PDFDocMerger(java.io.File[] inputFiles, java.io.File outputFile)
Accepts the array of multiple documents' File instance and Output File instance.

PDFDocMerger(java.io.InputStream[] inputStreams, java.io.OutputStream outputStream)
Accepts the array of multiple documents' InputStream and OutputStream.

PDFDocMerger(java.lang.Object[] inputObjs)
Accepts the array of Objects Added for #8506761

PDFDocMerger(java.lang.Object[] inputObjs, java.io.OutputStream outputStream)
Accepts the array of multiple documents' input Object (File or URL) and OutputStream.

PDFDocMerger(PDFParser[] inputPDFParsers)
Accepts the array of PDFParser.

Method Summary

void	clean()
static void	main(java.lang.String[] args) Main method for the command line mode.
void	mergePDFDocs() Deprecated. since 5.0
void	process() Merges multiple PDF documents into one single PDF document.
PDFParser	processAndGetPDFParser() This merges multiple PDF documents into one single PDF document and returns PDFParser which contains the generated PDF document.
void	setBackground(java.io.InputStream inStream) Sets the background PDF document.
void	setConfig(java.util.Hashtable properties) Deprecated. since 4.5
void	setConfig(java.util.Properties properties) Sets properties such as security and temporary directory information.
void	setConfig(java.lang.String propName, java.lang.String propValue) Sets properties such as security and temporary directory information.
void	setImageWatermark(java.io.InputStream imageStream, float[] rectangleCoords) Sets WaterMark with image.
void	setLocale(java.util.Locale locale) Sets the locale.
void	setLocale(java.lang.String locale) Sets locale information for text WaterMark.
void	setPageNumberCoordinates(float posX, float posY) Sets the coordination information on the page numbering.
void	setPageNumberFontInfo(java.lang.String adobeType1FontName, float fontSize) Sets the font information on the page numbering.
void	setPageNumberValue(int initialValue) Sets an initial number from which the page numbering starts.
void	setPageNumberValue(int initialValue, int startPageIndex) Sets an initial number from which the page numbering starts from and the page index from which you want to start the page numbering.
void	setTextDefaultWatermark(java.lang.String watermarkText) Sets WaterMark text with specific behavior.
void	setTextWatermark(java.lang.String watermarkText, float startX, float startY) Sets WaterMark text with default attributes.
void	setTextWatermarkAngle(int angDeg) Sets an angle measured in degree.
void	setTextWatermarkColor(float red, float green, float blue) Sets color with r,g,b.
void	setTextWatermarkFont(java.lang.String fontName, int fontSize) Sets font face name with font size.
void	setWatermarks(java.util.Hashtable[] watermarks) Sets multiple watermarks at once.
void	setWatermarkTo(int pageIndex) Sets the page index in which the watermark is specified.

Methods inherited from class java.lang.Object

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

Field Detail

RCS_ID

public static final java.lang.String RCS_ID

See Also:

Constant Field Values

WATERMARK_TEXT_DEFAULT

public static java.lang.String WATERMARK_TEXT_DEFAULT

WATERMARK_TEXT

public static java.lang.String WATERMARK_TEXT

WATERMARK_POSITION

public static java.lang.String WATERMARK_POSITION

WATERMARK_ANGLE

public static java.lang.String WATERMARK_ANGLE

WATERMARK_COLOR

public static java.lang.String WATERMARK_COLOR

WATERMARK_TO

public static java.lang.String WATERMARK_TO

WATERMARK_FONT

public static java.lang.String WATERMARK_FONT

WATERMARK_FONT_SIZE

public static java.lang.String WATERMARK_FONT_SIZE

Constructor Detail

PDFDocMerger

public PDFDocMerger(java.io.InputStream[] inputStreams,
                    java.io.OutputStream outputStream)
             throws java.lang.NullPointerException

Accepts the array of multiple documents' InputStream and OutputStream.

Parameters:

inputStreams - PDF documents' InputStream array. The output will be generated in the order of this array.

outputStream - Output destination of the generated PDF document.

Throws:

java.lang.NullPointerException - If either the InputStream array or OutputStream is null.

See Also:

PDFDocMerger(File[] inputFiles, File outputFile)

PDFDocMerger

public PDFDocMerger(java.io.File[] inputFiles,
                    java.io.File outputFile)
             throws java.lang.NullPointerException

Accepts the array of multiple documents' File instance and Output File instance.
Please use this constructor if you can make File[] instance for inputs and File instance for output.
This method uses less file I/O in O/S level.

Parameters:

inputFiles - PDF documents' File array. The output will be generated in the order of this array.

outputFile - Output destination of the generated PDF document.

Throws:

java.lang.NullPointerException - If either the inputFiles array or outputFile is null.

Since:

4.5

See Also:

PDFDocMerger(InputStream[] inputStreams, OutputStream outputStream)

PDFDocMerger

public PDFDocMerger(java.lang.Object[] inputObjs,
                    java.io.OutputStream outputStream)
             throws java.lang.NullPointerException

Accepts the array of multiple documents' input Object (File or URL) and OutputStream.

Parameters:

inputObject - PDF documents' input Object (File or URL) array. The output will be generated in the order of this array.

outputStream - Output destination of the generated PDF document.

Throws:

java.lang.NullPointerException - If either the InputStream array or OutputStream is null.

See Also:

PDFDocMerger(File[] inputFiles, File outputFile)

PDFDocMerger

public PDFDocMerger(java.lang.Object[] inputObjs)
             throws java.lang.NullPointerException

Accepts the array of Objects Added for #8506761

Parameters:

inputObjs - Input object array. The output will be generated in the order of this array.

Throws:

java.lang.NullPointerException

PDFDocMerger

public PDFDocMerger(PDFParser[] inputPDFParsers)
             throws java.lang.NullPointerException

Accepts the array of PDFParser. Added for #8506761

Parameters:

inputPDFParsers - Input PDFParser array. The output will be generated in the order of this array.

Throws:

java.lang.NullPointerException

Method Detail

processAndGetPDFParser

public PDFParser processAndGetPDFParser()
                                 throws XDOException

This merges multiple PDF documents into one single PDF document and returns PDFParser which contains the generated PDF document. Added for #8506761.

Throws:

XDOException

process

public void process()
             throws XDOException

Merges multiple PDF documents into one single PDF document. This method should be called only once after setting proper arguments. This method replaces the mergePDFDocs().

Throws:

XDOException

Since:

5.0

mergePDFDocs

public void mergePDFDocs()
                  throws java.lang.NullPointerException

Deprecated. since 5.0

Merges multiple PDF documents into one single PDF document. This method should be called only once after setting proper arguments.

Throws:

java.lang.NullPointerException

clean

public void clean()

setPageNumberCoordinates

public void setPageNumberCoordinates(float posX,
                                     float posY)

Sets the coordination information on the page numbering.

You can specify the location of the page numbers by a pair of x and y positions in pixel from the bottom left of the page. In case of portrait orientation, the A4 page size is (x=595, y=845) and the letter size is (x=612, y=792). If you want to put page numbers on the center-bottom of the page, please try (x=300, y=20). The page numbering does not work properly if you merge documents that have different page sizes.

Parameters:

posX - x position

posY - y position

See Also:

setPageNumberFontInfo(String, float), setPageNumberValue(int), setPageNumberValue(int, int), setBackground(InputStream)

setPageNumberFontInfo

public void setPageNumberFontInfo(java.lang.String adobeType1FontName,
                                  float fontSize)

Sets the font information on the page numbering. You have to specify the font name defined in the Adobe Type1 Font list. Following 14 font names are available.

 Times-Roman      Helvetica             Courier             Symbol
 Times-Bold       Helvetica-Bold        Courier-Bold        ZapfDingbats
 Times-Italic     Helvetica-Oblique     Courier-Oblique
 Times-BoldItalic Helvetica-BoldOblique Courier-BoldOblique 
 

If you specify the font name that doesn't listed above, the default font name will be used. The default font name is "Helvetica". The default font size is "8".

Parameters:

adobeType1FontName - the Adobe Type1 font name

fontSize - the font size

See Also:

setPageNumberCoordinates(float, float), setPageNumberValue(int), setPageNumberValue(int, int), setBackground(InputStream)

setPageNumberValue

public void setPageNumberValue(int initialValue)
                        throws java.lang.IllegalArgumentException

Sets an initial number from which the page numbering starts. The default number is 1.

Parameters:

initialValue - the page number initial value

Throws:

java.lang.IllegalArgumentException - if the argument is invalid.

See Also:

setPageNumberCoordinates(float, float), setPageNumberFontInfo(String, float), setPageNumberValue(int, int), setBackground(InputStream)

setPageNumberValue

public void setPageNumberValue(int initialValue,
                               int startPageIndex)
                        throws java.lang.IllegalArgumentException

Sets an initial number from which the page numbering starts from and the page index from which you want to start the page numbering.

For example, if you have a PDF document which has 2 cover pages and you want to put the page numbers from the 3rd page with the numbers starting from 1, you can call this method like setPageNumberValue(1, 3).

Parameters:

initialValue - start number of the page numbering.

startPageIndex - start page index from which you want to start the page numbering.

Throws:

java.lang.IllegalArgumentException - if the argument is invalid.

See Also:

setPageNumberCoordinates(float, float), setPageNumberFontInfo(String, float), setPageNumberValue(int), setBackground(InputStream)

setBackground

public void setBackground(java.io.InputStream inStream)
                   throws java.lang.NullPointerException

Sets the background PDF document.

This method is used with the background PDF document that includes a placeholder for the page numbering. The page size of the background PDF must be the same as the target PDF document, otherwise the page numbering doesn't work properly.

If you use the background PDF for the page numbering, it always does the page numbering from the first page. If you want to start the page numbering in the middle of the document, you need to call the APIs (setPageNumberCoordinates(), setPageNumberFontInfo(), setPageNumberValue()) instead.

Parameters:

inStream - the background PDF document which includes "Page Number Field".

Throws:

java.lang.NullPointerException - if the InputStream is null.

See Also:

setPageNumberCoordinates(float, float), setPageNumberFontInfo(String, float), setPageNumberValue(int), setPageNumberValue(int, int)

setImageWatermark

public void setImageWatermark(java.io.InputStream imageStream,
                              float[] rectangleCoords)

Sets WaterMark with image.
Image can be added for several purposes.

1. BackGround : the image can cover all page area as to be the BackGround.
2. Logo : the image can be placed at the specific area as to be the Logo.

The rectangleCoords can be set as follows.

 1. Specify all of coordination information [LowerLeft X, LowerLeft Y, UpperRight X, UpperRight Y].
 float[] rectangleCoords = {100f, 100f, 200f, 200f};
 2. Specify coords as below to use image's size.
 float[] rectangleCoords = {100f, 100f, -1f, -1f};
 

Parameters:

imageStream - the Image InputStream

rectangleCoords - the float[] which includes image area.

Since:

4.0

setTextDefaultWatermark

public void setTextDefaultWatermark(java.lang.String watermarkText)

Sets WaterMark text with specific behavior.
The WaterMark text is laid with forward slash type.
If this method is called, then calling other methods doesn't affect to draw the WaterMark anymore.
Here are default values for other attributes.

• the Angle in degree : 55
• the Color : light gray(0.9, 0.9, 0.9)
• the FontName : "Helvetica"
• the FontSize : "100"
• the Start Pos : It will be changed depending on the length of WaterMark text.

If the WaterMark text contains multibyte, then one of unicode fonts may be used according to locale.

 [For Example] 
 "Helvetica" is used if the locale is one of Latin1.
 Albany unicode font is used if the locale is in non-Latin1.
 

Please refer to Oracle XML Publisher Developer's Guide for more I18N support information.

Parameters:

watermarkText - the WaterMark text

Since:

4.0

setTextWatermark

public void setTextWatermark(java.lang.String watermarkText,
                             float startX,
                             float startY)

Sets WaterMark text with default attributes.
Here are default values for other attributes if this method is only called.

• the Angle in degree : 0
• the Color : light gray(0.9, 0.9, 0.9)
• the FontName : "Helvetica"
• the FontSize : "100"

If the WaterMark text contains multibyte, then one of unicode fonts may be used according to locale.

 [For Example] 
 "Helvetica" is used if the locale is one of Latin1.
 Albany unicode font is used of the locale is non-Latin1.
 

Please refer to Oracle XML Publisher Developer's Guide for more I18N support information.

Parameters:

watermarkText - the WaterMark text

Since:

4.0

setTextWatermarkFont

public void setTextWatermarkFont(java.lang.String fontName,
                                 int fontSize)

Sets font face name with font size.

Parameters:

fontName - the font name like "Helvetica".

fontSize - the font size like 100.

Since:

4.0

setWatermarkTo

public void setWatermarkTo(int pageIndex)
                    throws java.lang.IllegalArgumentException

Sets the page index in which the watermark is specified.
The pageIdx starts at 1.
If the value is 0, then watermark is set to all of pages.
If this method is not called, then watermark is set to all of pages.

Parameters:

pageIndex - the page index in which the watermark is set.

Throws:

java.lang.IllegalArgumentException

Since:

5.0

setWatermarks

public void setWatermarks(java.util.Hashtable[] watermarks)

Sets multiple watermarks at once.
Once this is called, other watermark related method calling is ignored. All value should be String even though the meaning of each value can be referred from each watermark related method. For example, "0.9, 0.9, 0.9" is required for watermark color and you can get the color information from setTextWatermarkColor(float red, float green, float blue) Please refer to following example on how to call it.

 Hashtable[] watermarks = new Hashtable[2];
 watermarks[0] = new Hashtable();
 // Sets default watermark text
 watermarks[0].put(PDFDocMerger.WATERMARK_TEXT_DEFAULT, "DRAFT");
 watermarks[1] = new Hashtable();
 // Sets watermark text
 watermarks[1].put(PDFDocMerger.WATERMARK_TEXT, "CONFIDENTIAL");
 // Sets watermark starting position. If this value is not properly specified, "0,0" will be used, instead.
 watermarks[1].put(PDFDocMerger.WATERMARK_POSITION, "100, 100");
 // Sets watermark angle degree. The default value is "0" which means no rotation.
 watermarks[1].put(PDFDocMerger.WATERMARK_ANGLE, "90");
 // Sets watermark color with light gray.
 watermarks[1].put(PDFDocMerger.WATERMARK_COLOR, "0.9, 0.9, 0.9");
 // Sets watermark to all pages.
 watermarks[1].put(PDFDocMerger.WATERMARK_TO, "0");
 // Sets font name for watermark text
 watermarks[1].put(PDFDocMerger.WATERMARK_FONT, "Courier");
 // Sets font size
 watermarks[1].put(PDFDocMerger.WATERMARK_FONT_SIZE, "10");
 

Parameters:

watermarks - a set of watermarks with array of Hashtable.

Since:

5.0

setTextWatermarkAngle

public void setTextWatermarkAngle(int angDeg)

Sets an angle measured in degree.

Parameters:

angDeg - the angle measured in degree. e.g : 55.

Since:

4.0

setTextWatermarkColor

public void setTextWatermarkColor(float red,
                                  float green,
                                  float blue)

Sets color with r,g,b.
The value ranges from 0.0 to 1.0.

• black : 0.0 , 0.0 , 0.0
• red : 1.0 , 0.0 , 0.0
• green : 0.0 , 1.0 , 0.0
• blue : 0.0 , 0.0 , 1.0
• light gray : 0.9 , 0.9 , 0.9

Parameters:

red - the value for red.

green - the value for red.

blue - the value for red.

Since:

4.0

setLocale

public void setLocale(java.lang.String locale)

Sets locale information for text WaterMark.
If the WaterMark text is non-latin1, then customers need to specify proper locale information to support multibyte.

Parameters:

locale - ISOLanguage(lowercase 2 letters) + [ "-" + ISOCountry(uppercase 2 letters)]

setLocale

public void setLocale(java.util.Locale locale)

Sets the locale.

Parameters:

locale - java locale

setConfig

public void setConfig(java.lang.String propName,
                      java.lang.String propValue)

Sets properties such as security and temporary directory information.

  [example]
  pdfDocMerger.setConfig("system-temp-dir", "/tmp");
  pdfDocMerger.setConfig("pdf-security", "true");
  pdfDocMerger.setConfig("pdf-open-password", "");
  pdfDocMerger.setConfig("pdf-permissions-password", "xxxxxx");
  pdfDocMerger.mergePDFDocs();
  

Parameters:

Properties - the document configuration properties.

Since:

4.3

setConfig

public void setConfig(java.util.Hashtable properties)

Deprecated. since 4.5

Sets properties such as security and temporary directory information.

  [example]
  Hashtable configTable = new Hashtable();
  configTable.put("system-temp-dir", "/tmp");
  configTable.put("pdf-security", "true");
  configTable.put("pdf-open-password", "");
  configTable.put("pdf-permissions-password", "xxxxxx");
  pdfDocMerger.setConfig(configTable);
  pdfDocMerger.mergePDFDocs();
  

Parameters:

Properties - the document configuration properties.

Since:

4.3

setConfig

public void setConfig(java.util.Properties properties)

Sets properties such as security and temporary directory information.

  [example]
  Properties configTable = new Properties();
  configTable.put("system-temp-dir", "/tmp");
  configTable.put("pdf-security", "true");
  configTable.put("pdf-open-password", "");
  configTable.put("pdf-permissions-password", "xxxxxx");
  pdfDocMerger.setConfig(configTable);
  pdfDocMerger.mergePDFDocs();
  

Parameters:

Properties - the document configuration properties.

Since:

4.5

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

Main method for the command line mode. You can merge as many PDF files as you want into one single PDF file. You can pass PDF files you want to merge followed by the final output PDF file to this method as follows.

 java oracle.xdo.common.pdf.util.PDFDocMerger -tmp <tempDir> <inputPDF> <inputPDF> .... <outputPDF>
 

Note that you have to pass the absolute file name for each input/output PDF file.

Throws:

java.lang.Exception

Skip navigation links