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
    Modifier and Type | Field and Description
    --- | ---
    `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
    Modifier and Type | Method and Description
    --- | ---
    `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.