Package org.faceless.pdf2

Class Portfolio

  • public class Portfolio
extends Object

    A "Portfolio PDF" is a PDF that primarily exists as a container for other documents, which are included as EmbeddedFile objects in the PDF.getEmbeddedFiles() map. Even then, the majority of PDFs with embedded files are not Portfolios - if that's the case, the isValid() method on this class will return false.

    The main advantage of a Portfolio PDF is the ability to structure the files within it, and to control which fields on each EmbeddedFile are displayed to the user to allow the appropriate file to be selected. For example, an entire directory tree could be archived into a single PDF, or a hierarchical email folder could be stored, with appropriate metadata for each email. This sort of structure requires a Portfolio.

    The PDF.getEmbeddedFiles() method returns the map of embedded files that make up the PDF, and therefore the Portfolio. It's still possible to add files to the PDF by adding them to that Map, but with a Portfolio you also hae the option of building up a tree of EmbeddedFile objects, by retrieving the root from getRoot() and adding descendents to its EmbeddedFile.getChildren() list. The result is ultimately the same; the two views of the same datastructure are reconciled in PDF.render(java.io.OutputStream).

    Here's how you might recursively attach an entire directory tree to a PDF 

      PDF pdf = new PDF();
  Portfolio portfolio = pdf.getPortfolio();
  add(portfolio.getRoot(), file);

  void add(EmbeddedFile dir, File f) {
    EmbeddedFile ef = new EmbeddedFile(f);
    dir.getChildren().add(ef2);
    if (f.isDirectory()) {
      for (File f2 : f.listFiles()) {
        add(ef, f2);
      }
    }
  }
    Since:
    2.26

    • Method Detail

      • isValid

        public boolean isValid()
        Return true if this Portfolio exists on the PDF, false if it's just a placeholder

      • getRoot

        public EmbeddedFile getRoot()
        Return the root folder of this Portfolio, creating it if necessary

      • reset

        public void reset​(boolean full)
        Clear this Portfolio. All folders will be removed and any EmbeddedFiles in this PDF reduced to a flat structure.
        Parameters:
        full - if true, the entire Portfolio is cleared. If false, only the folder structure is removed.

      • getSchema

        public Map<String,​Portfolio.FieldType> getSchema()
        Return the Schema to be used when displaying this Portfolio. A schema describes the collection of properties that the user will be shown for each embedded file. For example, when displaying a collection of emails, rather than files, it may be more appropriate to show From, To, Subject and so on rather than file size and so on. Here's an example of how to do that. 
         PDF pdf = new PDF();
 Portfolio portfolio = pdf.getPortfolio();
 Map<String,PortFolio.FieldType> schema = portfolio.getSchema();
 schema.put("from", new Portfolio.FieldType("From", "text"));
 schema.put("to", new Portfolio.FieldType("To", "text"));
 schema.put("date", new Portfolio.FieldType("To", "date"));
 schema.put("size", new Portfolio.FieldType("To", "size"));

 EmbedddedFile email1 = new EmbeddedFile(new File("email1.pdf"));
 email1.putProperty("from", "test@test.com");
 email1.putProperty("to", "other@test.com");
 email1.putProperty("date", new Date());
 portfolio.getRoot().getChildren().add(email1);
 // repeat with remaining emails
        Keys in this map should match the property names set in the EmbeddedFile.getProperties() map, at least for Portfolio.FieldType objects where the type is "text", "number" or "date". If the schema is empty (the default), the list of columns is chosen by the PDF viewer.
        Returns:
        the Schema
        See Also:
        Portfolio.FieldType, EmbeddedFile.getProperties()

      • setSchema

        public void setSchema​(String schema)

        Set the Schema based on the supplied Json string. This method is a convenient way of populating the Schema map returned by getSchema(). Here's an example: 

         {"From":{}, "To":{"name":"Recipient","hidden":true}, "Size":{"type":"size"}}
        Properties are type (defaults to "text"), name (defaults to property name), hidden and editable, which both default to false. All are optional.
        Parameters:
        schema - the schema as a Json string
        Throws:
        IllegalArgumentException - if the argument is invalid

      • setPresentation

        public void setPresentation​(String view)
        Set the presentation for this Portfolio. Currently supported values are "detail", "tile", hidden", "filmstrip", "freeform", "linear" or "tree", but any value can be set. How well these are supported, or whether others are supported, depends on the viewer.
        Parameters:
        view - the view, or null to not define a view

      • getPresentation

        public String getPresentation()
        Return the currently defined presentation for this Portfolio, as set by setPresentation(java.lang.String), or null if none is defined.
        Returns:
        the presentation type

      • apply

        public void apply()
        Apply the Portfolio to the PDF. This may rebuild the Map returned from PDF.getEmbeddedFiles(). It will be called automatically before the PDF is rendered
        Since:
        2.26.3