<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
<document> 
  <header> 
    <title>PDFBox - PDF File References</title> 
  </header> 
  <body> 
    <section>
      <title>File Specification</title>
      <p>
      See package:<a href="../javadoc/org/pdfbox/pdmodel/common/filespecification/package-summary.html">org.pdfbox.pdmodel.common.filespecification</a> <br/>
      See example:<a href="../javadoc/org/pdfbox/examples/pdmodel/EmbeddedFiles.html">EmbeddedFiles</a>
      </p>
      <p>
      	A PDF can contain references to external files via the file system or a URL to a remote location.
      	It is also possible to embed a binary file into a PDF document.
      </p>
      <p>
      There are two classes that can be used when referencing a file.  
      <a href="../javadoc/org/pdfbox/examples/pdmodel/common/filespecification/PDSimpleFileSpecification.html">PDSimpleFileSpecification</a> 
      is a simple string reference to a file(e.g. "./movies/BigMovie.avi").  The simple file specification does not allow for any parameters to be
      set.  The <a href="../javadoc/org/pdfbox/examples/pdmodel/common/filespecification/PDComplexFileSpecification.html">PDComplexFileSpecification</a> 
      is more feature rich and allows for advanced settings on the file reference.
      </p>
      
      <p>
      It is also possible to embed a file directly into a PDF.  Instead of setting the file attribute of the PDComplexFileSpecification, the 
      EmbeddedFile attribute can be used instead.
      </p>
    </section>
    <section>
      <title>File Attachments</title>
      <p>
      PDF documents can contain file attachments that are accessed from the Document->File Attachments menu.  PDFBox allows attachments
      to be added and extracted to PDF documents.  Attachments are part of the named tree that is attached to the document catalog.
      </p>
      <source>
        PDEmbeddedFilesNameTreeNode efTree = new PDEmbeddedFilesNameTreeNode();
        
        //first create the file specification, which holds the embedded file
        PDComplexFileSpecification fs = new PDComplexFileSpecification();
        fs.setFile( "Test.txt" );
        InputStream is = ...;
        PDEmbeddedFile ef = new PDEmbeddedFile(doc, is );
        //set some of the attributes of the embedded file
        ef.setSubtype( "test/plain" );
        ef.setSize( data.length );
        ef.setCreationDate( new GregorianCalendar() );
        fs.setEmbeddedFile( ef );
        
        //now add the entry to the embedded file tree and set in the document.
        Map efMap = new HashMap();
        efMap.put( "My first attachment", fs );
        efTree.setNames( efMap );
        //attachments are stored as part of the "names" dictionary in the document catalog
        PDDocumentNameDictionary names = new PDDocumentNameDictionary( doc.getDocumentCatalog() );
        names.setEmbeddedFiles( efTree );
        doc.getDocumentCatalog().setNames( names );
  </source>
    </section>
  </body>
</document>
