org.apache.pdfbox.pdfwriter

## Class COSWriter

- java.lang.Object
- - org.apache.pdfbox.pdfwriter.COSWriter

All Implemented Interfaces:
  ICOSVisitor

    public class COSWriter
    extends Object
    implements ICOSVisitor

This class acts on a in-memory representation of a PDF document.

Author:
  Michael Traut, Ben Litchfield

### Field Summary

Fields
`static byte[]` `ARRAY_CLOSE` The array close token.
`static byte[]` `ARRAY_OPEN` The array open token.
`static byte[]` `COMMENT` The start to a PDF comment.
`static byte[]` `DICT_CLOSE` The dictionary close token.
`static byte[]` `DICT_OPEN` The dictionary open token.
`static byte[]` `ENDOBJ` The end object token.
`static byte[]` `ENDSTREAM` The close stream token.
`static byte[]` `EOF` The EOF constant.
`static byte[]` `GARBAGE` Garbage bytes used to create the PDF header.
`static byte[]` `OBJ` The starting object token.
`static byte[]` `REFERENCE` The reference token.
`static byte[]` `SPACE` space character.
`static byte[]` `STARTXREF` The start xref token.
`static byte[]` `STREAM` The open stream token.
`static byte[]` `TRAILER` The trailer token.
`static byte[]` `VERSION` The output version of the PDF.
`static byte[]` `XREF` The XREF token.
`static byte[]` `XREF_FREE` The xref free token.
`static byte[]` `XREF_USED` The xref used token.

### Constructor Summary

Constructors
Constructor and Description
`COSWriter(OutputStream outputStream)` COSWriter constructor.
`COSWriter(OutputStream outputStream, CompressParameters compressParameters)` COSWriter constructor.
`COSWriter(OutputStream outputStream, org.apache.pdfbox.io.RandomAccessRead inputData)` COSWriter constructor for incremental updates.
`COSWriter(OutputStream outputStream, org.apache.pdfbox.io.RandomAccessRead inputData, Set<COSDictionary> objectsToWrite)` Constructor for incremental updates with a list of objects to write.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`protected void` `addXRefEntry(XReferenceEntry entry)` add an entry in the x ref table for later dump.
`protected void` `doWriteBody(COSDocument doc)` This will write the body of the document.
`protected void` `doWriteHeader(COSDocument doc)` This will write the header to the PDF document.
`void` `doWriteObject(COSBase obj)` This will write a COS object.
`void` `doWriteObject(COSObjectKey key, COSBase obj)` This will write a COS object for a predefined key.
`protected void` `doWriteTrailer(COSDocument doc)` This will write the trailer to the PDF document.
`InputStream` `getDataToSign()` Return the stream of PDF data to be signed.
`protected OutputStream` `getOutput()` This will get the output stream.
`protected COSStandardOutputStream` `getStandardOutput()` This will get the standard output stream.
`protected long` `getStartxref()` This will get the current start xref.
`protected List<XReferenceEntry>` `getXRefEntries()` This will get the xref entries.
`protected Long[]` `getXRefRanges(List<XReferenceEntry> xRefEntriesList)` check the xref entries and write out the ranges.
`boolean` `isCompress()` Returns true, if the resulting document shall be compressed.
`protected void` `setStartxref(long newStartxref)` This will set the start xref.
`void` `visitFromArray(COSArray array)` Notification of visit to Array object.
`void` `visitFromBoolean(COSBoolean obj)` Notification of visit to boolean object.
`void` `visitFromDictionary(COSDictionary obj)` Notification of visit to dictionary object.
`void` `visitFromDocument(COSDocument doc)` Notification of visit to document object.
`void` `visitFromFloat(COSFloat obj)` Notification of visit to float object.
`void` `visitFromInt(COSInteger obj)` Notification of visit to integer object.
`void` `visitFromName(COSName obj)` Notification of visit to name object.
`void` `visitFromNull(COSNull obj)` Notification of visit to null object.
`void` `visitFromStream(COSStream obj)` Notification of visit to stream object.
`void` `visitFromString(COSString obj)` Notification of visit to string object.
`void` `write(COSDocument doc)` This will write the pdf document.
`void` `write(FDFDocument doc)` This will write the fdf document.
`void` `write(PDDocument doc)` This will write the pdf document.
`void` `write(PDDocument doc, SignatureInterface signInterface)` This will write the pdf document.
`void` `writeExternalSignature(byte[] cmsSignature)` Write externally created signature of PDF data obtained via `getDataToSign()` method.
`void` `writeReference(COSBase obj)` visitFromObjRef method comment.
`static void` `writeString(byte[] bytes, OutputStream output)` This will output the given text/byte getString as a PDF object.
`static void` `writeString(COSString string, OutputStream output)` This will output the given byte getString as a PDF object.

### Methods inherited from class java.lang.Object

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

### Methods inherited from interface org.apache.pdfbox.cos.ICOSVisitor

`visitFromObject`

### Field Detail

#### DICT_OPEN

    public static final byte[] DICT_OPEN

The dictionary open token.

#### DICT_CLOSE

    public static final byte[] DICT_CLOSE

The dictionary close token.

#### SPACE

    public static final byte[] SPACE

space character.

#### COMMENT

    public static final byte[] COMMENT

The start to a PDF comment.

#### VERSION

    public static final byte[] VERSION

The output version of the PDF.

#### GARBAGE

    public static final byte[] GARBAGE

Garbage bytes used to create the PDF header.

#### EOF

    public static final byte[] EOF

The EOF constant.

#### REFERENCE

    public static final byte[] REFERENCE

The reference token.

#### XREF

    public static final byte[] XREF

The XREF token.

#### XREF_FREE

    public static final byte[] XREF_FREE

The xref free token.

#### XREF_USED

    public static final byte[] XREF_USED

The xref used token.

#### TRAILER

    public static final byte[] TRAILER

The trailer token.

#### STARTXREF

    public static final byte[] STARTXREF

The start xref token.

#### OBJ

    public static final byte[] OBJ

The starting object token.

#### ENDOBJ

    public static final byte[] ENDOBJ

The end object token.

#### ARRAY_OPEN

    public static final byte[] ARRAY_OPEN

The array open token.

#### ARRAY_CLOSE

    public static final byte[] ARRAY_CLOSE

The array close token.

#### STREAM

    public static final byte[] STREAM

The open stream token.

#### ENDSTREAM

    public static final byte[] ENDSTREAM

The close stream token.

### Constructor Detail

#### COSWriter

    public COSWriter(OutputStream outputStream)

COSWriter constructor.

Parameters:
  `outputStream` - The output stream to write the PDF.

#### COSWriter

    public COSWriter(OutputStream outputStream,
                     CompressParameters compressParameters)

COSWriter constructor.

Parameters:
  `outputStream` - The output stream to write the PDF.
  `compressParameters` - The configuration for the document's compression.

#### COSWriter

    public COSWriter(OutputStream outputStream,
                     org.apache.pdfbox.io.RandomAccessRead inputData)
              throws IOException

COSWriter constructor for incremental updates. There must be a path of objects that have `COSUpdateInfo.isNeedToBeUpdated()` set, starting from the document catalog. For signatures this is taken care by PDFBox itself.

Parameters:
  `outputStream` - output stream where the new PDF data will be written.
  `inputData` - random access read containing source PDF data
Throws:
  `IOException` - if something went wrong

#### COSWriter

    public COSWriter(OutputStream outputStream,
                     org.apache.pdfbox.io.RandomAccessRead inputData,
                     Set<COSDictionary> objectsToWrite)
              throws IOException

Constructor for incremental updates with a list of objects to write. This allows to include objects even if there is no path of objects that have `COSUpdateInfo.isNeedToBeUpdated()` set so the incremental update gets smaller. Only dictionaries are supported; if you need to update other objects classes, then add their parent dictionary.

Parameters:
  `outputStream` - output stream where the new PDF data will be written.
  `inputData` - random access read containing source PDF data.
  `objectsToWrite` - objects that must be part of the incremental saving.
Throws:
  `IOException` - if something went wrong

### Method Detail

#### isCompress

    public boolean isCompress()

Returns true, if the resulting document shall be compressed.

Returns:
  True, if the resulting document shall be compressed.

#### addXRefEntry

    protected void addXRefEntry(XReferenceEntry entry)

add an entry in the x ref table for later dump.

Parameters:
  `entry` - The new entry to add.

#### getOutput

    protected OutputStream getOutput()

This will get the output stream.

Returns:
  The output stream.

#### getStandardOutput

    protected COSStandardOutputStream getStandardOutput()

This will get the standard output stream.

Returns:
  The standard output stream.

#### getStartxref

    protected long getStartxref()

This will get the current start xref.

Returns:
  The current start xref.

#### getXRefEntries

    protected List<XReferenceEntry> getXRefEntries()

This will get the xref entries.

Returns:
  All available xref entries.

#### setStartxref

    protected void setStartxref(long newStartxref)

This will set the start xref.

Parameters:
  `newStartxref` - The new start xref attribute.

#### doWriteBody

    protected void doWriteBody(COSDocument doc)
                        throws IOException

This will write the body of the document.

Parameters:
  `doc` - The document to write the body for.
Throws:
  `IOException` - If there is an error writing the data.

#### doWriteObject

    public void doWriteObject(COSObjectKey key,
                              COSBase obj)
                       throws IOException

This will write a COS object for a predefined key.

Parameters:
  `key` - The key of the object to write.
  `obj` - The object to write.
Throws:
  `IOException` - if the output cannot be written

#### doWriteObject

    public void doWriteObject(COSBase obj)
                       throws IOException

This will write a COS object.

Parameters:
  `obj` - The object to write.
Throws:
  `IOException` - if the output cannot be written

#### doWriteHeader

    protected void doWriteHeader(COSDocument doc)
                          throws IOException

This will write the header to the PDF document.

Parameters:
  `doc` - The document to get the data from.
Throws:
  `IOException` - If there is an error writing to the stream.

#### doWriteTrailer

    protected void doWriteTrailer(COSDocument doc)
                           throws IOException

This will write the trailer to the PDF document.

Parameters:
  `doc` - The document to create the trailer for.
Throws:
  `IOException` - If there is an IOError while writing the document.

#### getDataToSign

    public InputStream getDataToSign()
                              throws IOException

Return the stream of PDF data to be signed. Clients should use this method only to create signatures externally. `write(PDDocument)` method should have been called prior. The created signature should be set using `writeExternalSignature(byte[])`.

When `SignatureInterface` instance is used, COSWriter obtains and writes the signature itself.

Returns:
  data stream to be signed
Throws:
  `IllegalStateException` - if PDF is not prepared for external signing
  `IOException` - if input data is closed

#### writeExternalSignature

    public void writeExternalSignature(byte[] cmsSignature)
                                throws IOException

Write externally created signature of PDF data obtained via `getDataToSign()` method.

Parameters:
  `cmsSignature` - CMS signature byte array
Throws:
  `IllegalStateException` - if PDF is not prepared for external signing
  `IOException` - if source data stream is closed

#### getXRefRanges

    protected Long[] getXRefRanges(List<XReferenceEntry> xRefEntriesList)

check the xref entries and write out the ranges. The format of the returned array is exactly the same as the pdf specification. See section 7.5.4 of ISO32000-1:2008, example 1 (page 40) for reference.

example: 0 1 2 5 6 7 8 10

will create a array with follow ranges

0 3 5 4 10 1

this mean that the element 0 is followed by two other related numbers that represent a cluster of the size 3. 5 is follow by three other related numbers and create a cluster of size 4. etc.

Parameters:
  `xRefEntriesList` - list with the xRef entries that was written
Returns:
  a integer array with the ranges

#### visitFromArray

    public void visitFromArray(COSArray array)
                        throws IOException

Description copied from interface: `ICOSVisitor`
Notification of visit to Array object.

Specified by:
  `visitFromArray` in interface `ICOSVisitor`
Parameters:
  `array` - The Object that is being visited.
Throws:
  `IOException` - If there is an error while visiting this object.

#### visitFromBoolean

    public void visitFromBoolean(COSBoolean obj)
                          throws IOException

Description copied from interface: `ICOSVisitor`
Notification of visit to boolean object.

Specified by:
  `visitFromBoolean` in interface `ICOSVisitor`
Parameters:
  `obj` - The Object that is being visited.
Throws:
  `IOException` - If there is an error while visiting this object.

#### visitFromDictionary

    public void visitFromDictionary(COSDictionary obj)
                             throws IOException

Description copied from interface: `ICOSVisitor`
Notification of visit to dictionary object.

Specified by:
  `visitFromDictionary` in interface `ICOSVisitor`
Parameters:
  `obj` - The Object that is being visited.
Throws:
  `IOException` - If there is an error while visiting this object.

#### visitFromDocument

    public void visitFromDocument(COSDocument doc)
                           throws IOException

Description copied from interface: `ICOSVisitor`
Notification of visit to document object.

Specified by:
  `visitFromDocument` in interface `ICOSVisitor`
Parameters:
  `doc` - The Object that is being visited.
Throws:
  `IOException` - If there is an error while visiting this object.

#### visitFromFloat

    public void visitFromFloat(COSFloat obj)
                        throws IOException

Description copied from interface: `ICOSVisitor`
Notification of visit to float object.

Specified by:
  `visitFromFloat` in interface `ICOSVisitor`
Parameters:
  `obj` - The Object that is being visited.
Throws:
  `IOException` - If there is an error while visiting this object.

#### visitFromInt

    public void visitFromInt(COSInteger obj)
                      throws IOException

Description copied from interface: `ICOSVisitor`
Notification of visit to integer object.

Specified by:
  `visitFromInt` in interface `ICOSVisitor`
Parameters:
  `obj` - The Object that is being visited.
Throws:
  `IOException` - If there is an error while visiting this object.

#### visitFromName

    public void visitFromName(COSName obj)
                       throws IOException

Description copied from interface: `ICOSVisitor`
Notification of visit to name object.

Specified by:
  `visitFromName` in interface `ICOSVisitor`
Parameters:
  `obj` - The Object that is being visited.
Throws:
  `IOException` - If there is an error while visiting this object.

#### visitFromNull

    public void visitFromNull(COSNull obj)
                       throws IOException

Description copied from interface: `ICOSVisitor`
Notification of visit to null object.

Specified by:
  `visitFromNull` in interface `ICOSVisitor`
Parameters:
  `obj` - The Object that is being visited.
Throws:
  `IOException` - If there is an error while visiting this object.

#### writeReference

    public void writeReference(COSBase obj)
                        throws IOException

visitFromObjRef method comment.

Parameters:
  `obj` - The object that is being visited.
Throws:
  `IOException` - If there is an exception while visiting this object.

#### visitFromStream

    public void visitFromStream(COSStream obj)
                         throws IOException

Description copied from interface: `ICOSVisitor`
Notification of visit to stream object.

Specified by:
  `visitFromStream` in interface `ICOSVisitor`
Parameters:
  `obj` - The Object that is being visited.
Throws:
  `IOException` - If there is an error while visiting this object.

#### visitFromString

    public void visitFromString(COSString obj)
                         throws IOException

Description copied from interface: `ICOSVisitor`
Notification of visit to string object.

Specified by:
  `visitFromString` in interface `ICOSVisitor`
Parameters:
  `obj` - The Object that is being visited.
Throws:
  `IOException` - If there is an error while visiting this object.

#### write

    public void write(COSDocument doc)
               throws IOException

This will write the pdf document.

Parameters:
  `doc` - The document to write.
Throws:
  `IOException` - If an error occurs while generating the data.

#### write

    public void write(PDDocument doc)
               throws IOException

This will write the pdf document. If signature should be created externally, `writeExternalSignature(byte[])` should be invoked to set signature after calling this method.

Parameters:
  `doc` - The document to write.
Throws:
  `IOException` - If an error occurs while generating the data.

#### write

    public void write(PDDocument doc,
                      SignatureInterface signInterface)
               throws IOException

This will write the pdf document. If signature should be created externally, `writeExternalSignature(byte[])` should be invoked to set signature after calling this method.

Parameters:
  `doc` - The document to write.
  `signInterface` - class to be used for signing; `null` if external signing would be performed or there will be no signing at all
Throws:
  `IOException` - If an error occurs while generating the data.
  `IllegalStateException` - If the document has an encryption dictionary but no protection policy.

#### write

    public void write(FDFDocument doc)
               throws IOException

This will write the fdf document.

Parameters:
  `doc` - The document to write.
Throws:
  `IOException` - If an error occurs while generating the data.

#### writeString

    public static void writeString(COSString string,
                                   OutputStream output)
                            throws IOException

This will output the given byte getString as a PDF object.

Parameters:
  `string` - COSString to be written
  `output` - The stream to write to.
Throws:
  `IOException` - If there is an error writing to the stream.

#### writeString

    public static void writeString(byte[] bytes,
                                   OutputStream output)
                            throws IOException

This will output the given text/byte getString as a PDF object.

Parameters:
  `bytes` - byte array representation of a string to be written
  `output` - The stream to write to.
Throws:
  `IOException` - If there is an error writing to the stream.