Class PageAnchoring

java.lang.Object
org.apache.tika.metadata.PageAnchoring
public final class PageAnchoring extends Object
Helpers for tagging an embedded resource's metadata with the pages or sheets of its parent document on which it appears. Centralised so every paginated/sheeted parser (HSLF/XSLF for PowerPoint, OpenDocumentParser for ODP, HSSF/XSSF for Excel, PDF, ...) encodes the same convention identically.

Convention:

  • indices == null: caller does not know the resource's anchoring — both single- and sequence-valued properties are left unset.
  • indices.isEmpty(): the resource is known to be present in the container but referenced from no page/sheet — the sequence property is set to a single-element array containing the sentinel value (see TikaPagedText.UNLINKED_PAGE and Office.UNLINKED_SHEET).
  • indices.size() == 1: both the single-valued and the sequence-valued property are set, the sequence carrying the one index as its only element. Consumers that only inspect the single-valued property still see the right answer.
  • indices.size() > 1: only the sequence-valued property is set; the single-valued property is cleared, because no single index would be meaningful.

This class only mutates the metadata it is handed — it is the caller's job to compute the index set (e.g. by pre-scanning a slide file for picture references before the embedded-resource emission).

  • Method Details

    • applyPageMetadata

      public static void applyPageMetadata(Metadata target, Collection<Integer> pages)
      Apply TikaPagedText.PAGE_NUMBER / TikaPagedText.PAGE_NUMBERS to target, per the page-anchoring convention. Used by presentation parsers (PPT, PPTX, ODP), and by PDF parsers when tagging per-page embedded resources.
      Parameters:
      target - metadata to write to
      pages - 1-based page numbers, an empty collection for "known unlinked", or null for unknown

    • applySheetMetadata

      public static void applySheetMetadata(Metadata target, Collection<Integer> sheets)
      Apply Office.SHEET_NUMBER / Office.SHEET_NUMBERS to target, per the same convention as applyPageMetadata(Metadata, Collection). Used by spreadsheet parsers (HSSF, XSSF) when tagging an embedded resource with the sheets it appears on.
      Parameters:
      target - metadata to write to
      sheets - 1-based sheet numbers, an empty collection for "known unlinked", or null for unknown

    • applyAnchorMetadata

      public static void applyAnchorMetadata(Metadata target, Collection<Integer> indices, Property singleProperty, Property sequenceProperty, int unlinkedSentinel)
      Shared core for applyPageMetadata(Metadata, Collection) and applySheetMetadata(Metadata, Collection). Exposed so future paginated-resource conventions (e.g. arbitrary index spaces other than pages/sheets) can reuse the same logic without copying it.
      Parameters:
      target - metadata to write to (no-op if null)
      indices - the anchor indices, or null for "unknown"
      singleProperty - internalInteger property set when there is exactly one anchor index
      sequenceProperty - internalIntegerSequence property populated with all anchor indices
      unlinkedSentinel - value used as the sole element of sequenceProperty when indices is empty (known unlinked)