com.lowagie.text.pdf

## Class PdfFileSpecification

- java.lang.Object
- - com.lowagie.text.pdf.PdfObject
  - - com.lowagie.text.pdf.PdfDictionary
    - - com.lowagie.text.pdf.PdfFileSpecification

    public class PdfFileSpecification
    extends PdfDictionary

Specifies a file or an URL. The file can be extern or embedded.

Author:
  Paulo Soares (psoares@consiste.pt)

### Field Summary

Fields
`protected PdfIndirectReference` `ref`
`protected PdfWriter` `writer`

### Fields inherited from class com.lowagie.text.pdf.PdfDictionary

`CATALOG, FONT, hashMap, OUTLINES, PAGE, PAGES`

### Fields inherited from class com.lowagie.text.pdf.PdfObject

`ARRAY, BOOLEAN, bytes, DICTIONARY, INDIRECT, indRef, NAME, NOTHING, NULL, NUMBER, STREAM, STRING, TEXT_PDFDOCENCODING, TEXT_UNICODE, type`

### Constructor Summary

Constructors
Constructor and Description
`PdfFileSpecification()` Creates a new instance of PdfFileSpecification.

### Method Summary

Methods
`void` `addCollectionItem(PdfCollectionItem ci)` Adds the Collection item dictionary.
`void` `addDescription(java.lang.String description, boolean unicode)` Adds a description for the file that is specified here.
`static PdfFileSpecification` `fileEmbedded(PdfWriter writer, java.lang.String filePath, java.lang.String fileDisplay, byte[] fileStore)` Creates a file specification with the file embedded.
`static PdfFileSpecification` `fileEmbedded(PdfWriter writer, java.lang.String filePath, java.lang.String fileDisplay, byte[] fileStore, boolean compress)` Creates a file specification with the file embedded.
`static PdfFileSpecification` `fileEmbedded(PdfWriter writer, java.lang.String filePath, java.lang.String fileDisplay, byte[] fileStore, boolean compress, java.lang.String mimeType, PdfDictionary fileParameter)` Creates a file specification with the file embedded.
`static PdfFileSpecification` `fileEmbedded(PdfWriter writer, java.lang.String filePath, java.lang.String fileDisplay, byte[] fileStore, int compressionLevel)` Creates a file specification with the file embedded.
`static PdfFileSpecification` `fileEmbedded(PdfWriter writer, java.lang.String filePath, java.lang.String fileDisplay, byte[] fileStore, java.lang.String mimeType, PdfDictionary fileParameter, int compressionLevel)` Creates a file specification with the file embedded.
`static PdfFileSpecification` `fileExtern(PdfWriter writer, java.lang.String filePath)` Creates a file specification for an external file.
`PdfIndirectReference` `getReference()` Gets the indirect reference to this file specification.
`void` `setMultiByteFileName(byte[] fileName)` Sets the file name (the key /F) string as an hex representation to support multi byte file names.
`void` `setUnicodeFileName(java.lang.String filename, boolean unicode)` Adds the unicode file name (the key /UF).
`void` `setVolatile(boolean volatile_file)` Sets a flag that indicates whether an external file referenced by the file specification is volatile.
`static PdfFileSpecification` `url(PdfWriter writer, java.lang.String url)` Creates a file specification of type URL.

### Methods inherited from class com.lowagie.text.pdf.PdfDictionary

`contains, get, getAsArray, getAsBoolean, getAsDict, getAsIndirectObject, getAsName, getAsNumber, getAsStream, getAsString, getDirectObject, getKeys, isCatalog, isFont, isOutlineTree, isPage, isPages, merge, mergeDifferent, put, putAll, putEx, remove, size, toPdf, toString`

### Methods inherited from class com.lowagie.text.pdf.PdfObject

`canBeInObjStm, getBytes, getIndRef, isArray, isBoolean, isDictionary, isIndirect, isName, isNull, isNumber, isStream, isString, length, setContent, setIndRef, type`

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

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

### Field Detail

#### writer

    protected PdfWriter writer

#### ref

    protected PdfIndirectReference ref

### Constructor Detail

#### PdfFileSpecification

    public PdfFileSpecification()

Creates a new instance of PdfFileSpecification. The static methods are preferred.

### Method Detail

#### url

    public static PdfFileSpecification url(PdfWriter writer,
                           java.lang.String url)

Creates a file specification of type URL.

Parameters:
  `writer` - the `PdfWriter`
  `url` - the URL
Returns:
  the file specification

#### fileEmbedded

    public static PdfFileSpecification fileEmbedded(PdfWriter writer,
                                    java.lang.String filePath,
                                    java.lang.String fileDisplay,
                                    byte[] fileStore)
                                             throws java.io.IOException

Creates a file specification with the file embedded. The file may come from the file system or from a byte array. The data is flate compressed.

Parameters:
  `writer` - the `PdfWriter`
  `filePath` - the file path
  `fileDisplay` - the file information that is presented to the user
  `fileStore` - the byte array with the file. If it is not `null` it takes precedence over `filePath`
Returns:
  the file specification
Throws:
  `java.io.IOException` - on error

#### fileEmbedded

    public static PdfFileSpecification fileEmbedded(PdfWriter writer,
                                    java.lang.String filePath,
                                    java.lang.String fileDisplay,
                                    byte[] fileStore,
                                    int compressionLevel)
                                             throws java.io.IOException

Creates a file specification with the file embedded. The file may come from the file system or from a byte array. The data is flate compressed.

Parameters:
  `writer` - the `PdfWriter`
  `filePath` - the file path
  `fileDisplay` - the file information that is presented to the user
  `fileStore` - the byte array with the file. If it is not `null` it takes precedence over `filePath`
  `compressionLevel` - the compression level to be used for compressing the file it takes precedence over `filePath`
Returns:
  the file specification
Throws:
  `java.io.IOException` - on error
Since:
  2.1.3

#### fileEmbedded

    public static PdfFileSpecification fileEmbedded(PdfWriter writer,
                                    java.lang.String filePath,
                                    java.lang.String fileDisplay,
                                    byte[] fileStore,
                                    boolean compress)
                                             throws java.io.IOException

Creates a file specification with the file embedded. The file may come from the file system or from a byte array.

Parameters:
  `writer` - the `PdfWriter`
  `filePath` - the file path
  `fileDisplay` - the file information that is presented to the user
  `fileStore` - the byte array with the file. If it is not `null` it takes precedence over `filePath`
  `compress` - sets the compression on the data. Multimedia content will benefit little from compression
Returns:
  the file specification
Throws:
  `java.io.IOException` - on error

#### fileEmbedded

    public static PdfFileSpecification fileEmbedded(PdfWriter writer,
                                    java.lang.String filePath,
                                    java.lang.String fileDisplay,
                                    byte[] fileStore,
                                    boolean compress,
                                    java.lang.String mimeType,
                                    PdfDictionary fileParameter)
                                             throws java.io.IOException

Creates a file specification with the file embedded. The file may come from the file system or from a byte array.

Parameters:
  `writer` - the `PdfWriter`
  `filePath` - the file path
  `fileDisplay` - the file information that is presented to the user
  `fileStore` - the byte array with the file. If it is not `null` it takes precedence over `filePath`
  `compress` - sets the compression on the data. Multimedia content will benefit little from compression
  `mimeType` - the optional mimeType
  `fileParameter` - the optional extra file parameters such as the creation or modification date
Returns:
  the file specification
Throws:
  `java.io.IOException` - on error

#### fileEmbedded

    public static PdfFileSpecification fileEmbedded(PdfWriter writer,
                                    java.lang.String filePath,
                                    java.lang.String fileDisplay,
                                    byte[] fileStore,
                                    java.lang.String mimeType,
                                    PdfDictionary fileParameter,
                                    int compressionLevel)
                                             throws java.io.IOException

Creates a file specification with the file embedded. The file may come from the file system or from a byte array.

Parameters:
  `writer` - the `PdfWriter`
  `filePath` - the file path
  `fileDisplay` - the file information that is presented to the user
  `fileStore` - the byte array with the file. If it is not `null` it takes precedence over `filePath`
  `mimeType` - the optional mimeType
  `fileParameter` - the optional extra file parameters such as the creation or modification date
  `compressionLevel` - the level of compression
Returns:
  the file specification
Throws:
  `java.io.IOException` - on error
Since:
  2.1.3

#### fileExtern

    public static PdfFileSpecification fileExtern(PdfWriter writer,
                                  java.lang.String filePath)

Creates a file specification for an external file.

Parameters:
  `writer` - the `PdfWriter`
  `filePath` - the file path
Returns:
  the file specification

#### getReference

    public PdfIndirectReference getReference()
                                      throws java.io.IOException

Gets the indirect reference to this file specification. Multiple invocations will retrieve the same value.

Returns:
  the indirect reference
Throws:
  `java.io.IOException` - on error

#### setMultiByteFileName

    public void setMultiByteFileName(byte[] fileName)

Sets the file name (the key /F) string as an hex representation to support multi byte file names. The name must have the slash and backslash escaped according to the file specification rules

Parameters:
  `fileName` - the file name as a byte array

#### setUnicodeFileName

    public void setUnicodeFileName(java.lang.String filename,
                          boolean unicode)

Adds the unicode file name (the key /UF). This entry was introduced in PDF 1.7. The filename must have the slash and backslash escaped according to the file specification rules.

Parameters:
  `filename` - the filename
  `unicode` - if true, the filename is UTF-16BE encoded; otherwise PDFDocEncoding is used;

#### setVolatile

    public void setVolatile(boolean volatile_file)

Sets a flag that indicates whether an external file referenced by the file specification is volatile. If the value is true, applications should never cache a copy of the file.

Parameters:
  `volatile_file` - if true, the external file should not be cached

#### addDescription

    public void addDescription(java.lang.String description,
                      boolean unicode)

Adds a description for the file that is specified here.

Parameters:
  `description` - some text
  `unicode` - if true, the text is added as a unicode string

#### addCollectionItem

    public void addCollectionItem(PdfCollectionItem ci)

Adds the Collection item dictionary.