Migrating from iText

<properties>
  <itext.version>9.8.0</itext.version>
</properties>

<dependencies>
  <dependency>
    <groupId>com.itextpdf</groupId>
    <artifactId>itext-core</artifactId>
    <version>${itext.version}</version>
    <type>pom</type>
  </dependency>
  <dependency>
    <groupId>com.itextpdf</groupId>
    <artifactId>bouncy-castle-adapter</artifactId>
    <version>${itext.version}</version>
  </dependency>
</dependencies>

// Before the first iText call.
LicenseKey.loadLicenseFile(new File("path/to/itextkey.json"));

@sdk-pdf:registry=https://registry.sdk.pdf.net
//registry.sdk.pdf.net/:_authToken=${PDF_NET_REGISTRY_TOKEN}

npm install @sdk-pdf/react

import { useMemo } from 'react'
import { CONTENT_POLICY_PRESET, PdfProviders } from '@sdk-pdf/react'
import '@sdk-pdf/react/style.css'

export function ContractPage({
  contractId,
  canEdit,
}: {
  contractId: string
  canEdit: boolean
}) {
  const config = useMemo(
    () => ({
      // PDF_VIEWER: fillable widgets and clickable links, read-only text and annotations.
      // Applied when the viewport first mounts; switch later with useSetInteractionMode.
      initialContentPolicy: canEdit
        ? CONTENT_POLICY_PRESET.PDF_EDITOR
        : CONTENT_POLICY_PRESET.PDF_VIEWER,
    }),
    [canEdit]
  )

  return (
    <PdfProviders {...config}>
      <DocumentLoader url={`/api/contracts/${contractId}/file`} />
    </PdfProviders>
  )
}

byte[] stored = storage.read(documentId);
ReaderProperties properties = new ReaderProperties();
if (password != null) {
    properties.setPassword(password.getBytes(StandardCharsets.UTF_8));
}

try (PdfDocument pdfDoc = new PdfDocument(
        new PdfReader(new ByteArrayInputStream(stored), properties))) {
    int pageCount = pdfDoc.getNumberOfPages();
} catch (BadPasswordException e) {
    // The password is missing or wrong: ask for it, then open the file again.
} catch (IOException e) {
    // Reading the bytes failed.
}

import { useRef, useState } from 'react'
import { InvalidPasswordError, useLoadPdf, useResetPdf } from '@sdk-pdf/react'

function DocumentLoader({ url }: { url: string }) {
  const [loadState, loadPdf] = useLoadPdf()
  const resetPdf = useResetPdf()
  // The bytes and the URL they came from, kept for a password retry.
  const bytesRef = useRef<{ url: string; data: Uint8Array } | null>(null)
  const [loadedUrl, setLoadedUrl] = useState<string>()
  const [needsPassword, setNeedsPassword] = useState(false)
  const [errorMessage, setErrorMessage] = useState<string>()

  async function open(password?: string) {
    setErrorMessage(undefined)
    try {
      let data = bytesRef.current?.url === url ? bytesRef.current.data : undefined
      if (!data) {
        // The endpoint that used to stream iText output now returns the stored file.
        const response = await fetch(url, { credentials: 'include' })
        if (!response.ok) {
          setErrorMessage(`Loading the document failed with ${response.status}`)
          return
        }
        data = new Uint8Array(await response.arrayBuffer())
        bytesRef.current = { url, data }
      }

      // A document from another URL may still be loaded: unload it, which invalidates its
      // ids.
      if (loadState.status !== 'initial') resetPdf()
      setLoadedUrl(undefined)

      // loadPdf reads from the buffer it receives for the document's lifetime,
      // so keep the original for a retry and pass a copy.
      await loadPdf(data.slice(), { password })
      setLoadedUrl(url)
      setNeedsPassword(false)
    } catch (error) {
      // Replaces catching BadPasswordException.
      if (error instanceof InvalidPasswordError) setNeedsPassword(true)
      else setErrorMessage('The document could not be opened')
    }
  }

  if (needsPassword)
    return <PasswordPrompt onSubmit={(password) => void open(password)} />
  if (loadState.status === 'loading') return <p>Loading the document…</p>
  // Render the application only for the document loaded from the current URL.
  if (loadState.status === 'ready' && loadedUrl === url) return <PdfApplication />

  return (
    <>
      {errorMessage && <p role="alert">{errorMessage}</p>}
      <button onClick={() => void open()}>Open</button>
    </>
  )
}

import { useResetPdf } from '@sdk-pdf/react'

function CloseDocumentButton() {
  const resetPdf = useResetPdf()

  // The load state returns to 'initial'.
  return <button onClick={() => resetPdf()}>Close</button>
}

@Override
protected void doGet(HttpServletRequest request, HttpServletResponse response)
        throws IOException {
    byte[] stored = storage.read(request.getParameter("id"));

    ByteArrayOutputStream output = new ByteArrayOutputStream();
    try (PdfDocument pdfDoc = new PdfDocument(
            new PdfReader(new ByteArrayInputStream(stored)), new PdfWriter(output))) {
        // Per-request changes go here: filled fields, stamps, page operations.
    }

    response.setContentType("application/pdf");
    response.setContentLength(output.size());
    output.writeTo(response.getOutputStream());
}

<iframe src="/documents?id=42" title="Contract"></iframe>

import { useViewportAutoFitScale, Viewport } from '@sdk-pdf/react'

function PdfApplication() {
  // Fit the page width once per loaded document.
  useViewportAutoFitScale('width')

  return (
    <div style={{ display: 'grid', gridTemplateRows: 'auto 1fr', height: '100vh' }}>
      {/* Your toolbar: the page, form, and save controls from this guide. */}
      <Toolbar />
      {/* The viewport fills its parent, so the parent needs an explicit size. */}
      <div style={{ minHeight: 0 }}>
        <Viewport />
      </div>
    </div>
  )
}

try (PdfDocument pdfDoc = new PdfDocument(
        new PdfReader(new ByteArrayInputStream(stored)), new PdfWriter(output))) {
    // getPageSize() ignores the rotation; getPageSizeWithRotation() applies it.
    Rectangle firstPageSize = pdfDoc.getPage(1).getPageSizeWithRotation();

    // Insert a blank A4 page at position 2: the pages after it shift by one.
    pdfDoc.addNewPage(2, PageSize.A4);
    // Move the last page to the front.
    pdfDoc.movePage(pdfDoc.getNumberOfPages(), 1);
    // The rotation is absolute: read the current angle to turn the page a quarter
    // clockwise.
    PdfPage firstPage = pdfDoc.getPage(1);
    firstPage.setRotation((firstPage.getRotation() + 90) % 360);
    // Remove page 3.
    pdfDoc.removePage(3);
}

import {
  usePageCreate,
  usePageDelete,
  usePageMove,
  usePages,
  useSetPageRotation,
} from '@sdk-pdf/react'

function PageActions({ pageId }: { pageId: string }) {
  const pages = usePages()
  const createPage = usePageCreate()
  const deletePages = usePageDelete()
  const { moveBefore } = usePageMove()
  const setPageRotation = useSetPageRotation()

  const index = pages.findIndex((page) => page.id === pageId)
  if (index === -1) return null
  const page = pages[index]

  return (
    <div role="toolbar" aria-label={`Page ${index + 1} of ${pages.length}`}>
      {/* User-space units with the rotation applied, like getPageSizeWithRotation(). */}
      <span>
        {Math.round(page.width)} × {Math.round(page.height)}
      </span>
      {/* A4 is roughly 595 × 842; the new page goes after this one. */}
      <button onClick={() => createPage(595, 842, pageId)}>
        Insert blank page after
      </button>
      {/* Without a target page, moveBefore inserts at the start of the document. */}
      <button onClick={() => moveBefore(pageId)}>Move to start</button>
      {/* Absolute, as with setRotation: add to the current angle yourself. */}
      <button onClick={() => setPageRotation(pageId, page.rotation + 90)}>
        Rotate clockwise
      </button>
      <button disabled={pages.length <= 1} onClick={() => deletePages(pageId)}>
        Delete
      </button>
    </div>
  )
}

try (PdfDocument pdfDoc = new PdfDocument(
        new PdfReader(new ByteArrayInputStream(stored)), new PdfWriter(output))) {
    PdfAcroForm form = PdfFormCreator.getAcroForm(pdfDoc, true);

    form.getField("customer.name").setValue("Jane Doe");
    form.getField("terms").setValue("Yes");

    PdfTextFormField notes = new TextFormFieldBuilder(pdfDoc, "notes")
            .setWidgetRectangle(new Rectangle(72, 600, 300, 24))
            .createText();
    notes.setMultiline(true);
    form.addField(notes, pdfDoc.getPage(1));

    // Lock a field, or turn every field into page content with form.flattenFields().
    form.getField("customer.name").setReadOnly(true);
}

import {
  CheckboxWidget,
  useDocumentSaving,
  useSetWidgetProps,
  useWidgets,
  useWidgetsCreate,
  useWidgetsGetter,
  useWidgetValue,
  Widget,
} from '@sdk-pdf/react'

function isCheckboxWidget(widget: Widget): widget is CheckboxWidget {
  return widget.widgetType === 'checkbox'
}

// The counterpart of getField("terms"): the value is a boolean, not an appearance state
// name.
function TermsCheckbox() {
  const { widgets } = useWidgets()
  const widget = widgets
    .filter(isCheckboxWidget)
    .find((widget) => widget.fieldName === 'terms')

  return widget ? <CheckboxField widget={widget} /> : null
}

function CheckboxField({ widget }: { widget: CheckboxWidget }) {
  const [isChecked, setIsChecked] = useWidgetValue(widget)

  return (
    <label>
      <input
        type="checkbox"
        checked={isChecked}
        onChange={(event) => setIsChecked(event.currentTarget.checked)}
      />
      I accept the terms
    </label>
  )
}

// The counterpart of TextFormFieldBuilder and addField(field, page).
function useAddNotesField() {
  const createWidgets = useWidgetsCreate()

  return async (pageId: string) => {
    const [widget] = await createWidgets({
      pageId,
      widgetType: 'text',
      // User-space units: the origin is at the bottom-left corner of the page.
      x: 72,
      y: 600,
      width: 300,
      height: 24,
      fieldName: 'notes',
      isMultiline: true,
    })
    return widget
  }
}

// Upload the filled form, then lock it: the counterpart of setReadOnly(true) on every
// field.
function useSubmitForm() {
  const getWidgets = useWidgetsGetter()
  const setWidgetProps = useSetWidgetProps()
  const { prepareDocument } = useDocumentSaving()

  return async (url: string) => {
    const bytes = await prepareDocument({ returnOriginalIfUnchanged: false })
    const response = await fetch(url, { method: 'POST', body: bytes as BodyInit })
    // A failed upload leaves the form editable, so the user can try again.
    if (!response.ok)
      throw new Error(`Submitting the form failed with ${response.status}`)

    const widgets = await getWidgets()
    // excludeFromHistory keeps undo from unlocking the submitted form.
    await setWidgetProps(
      widgets.map((widget) => widget.id),
      { isReadOnly: true },
      { excludeFromHistory: true }
    )
  }
}

PdfDocument pdfDoc = new PdfDocument(
        new PdfReader(new ByteArrayInputStream(stored)), new PdfWriter(output));
try (Document document = new Document(pdfDoc)) {
    PdfPage page = pdfDoc.getPage(1);
    Rectangle pageSize = page.getPageSize();

    // A text object at an absolute position.
    PdfCanvas canvas = new PdfCanvas(page);
    canvas.beginText()
            .setFontAndSize(PdfFontFactory.createFont(StandardFonts.HELVETICA), 12)
            .moveText(72, pageSize.getTop() - 72)
            .showText("Reviewed by the legal team")
            .endText();

    // An image fitted into a rectangle given by its lower-left corner, width, and height.
    ImageData logo = ImageDataFactory.create(logoBytes);
    canvas.addImageFittedIntoRectangle(logo, new Rectangle(72, 72, 150, 50), false);

    // A layout paragraph, centered on page 1.
    document.showTextAligned(new Paragraph("DRAFT").setFontSize(48),
            pageSize.getX() + pageSize.getWidth() / 2,
            pageSize.getY() + pageSize.getHeight() / 2, 1,
            TextAlignment.CENTER, VerticalAlignment.MIDDLE, 0);
}

import {
  CONTENT_POLICY_PRESET,
  InteractionTool,
  stageImage,
  useInteractionTool,
  useParagraphCreate,
  useProgrammaticEditor,
  useSetInteractionMode,
  useStampAnnotationCreate,
} from '@sdk-pdf/react'

// The counterpart of beginText(), moveText(x, y), and showText(text).
function useStampText() {
  const createParagraph = useParagraphCreate()
  const { getParagraphEditor } = useProgrammaticEditor()

  return async (pageId: string, x: number, y: number, text: string) => {
    const paragraphId = await createParagraph(pageId, x, y)
    const editor = getParagraphEditor(paragraphId)
    // The paragraph may be gone already: deleted by an undo.
    if (!editor) return

    editor.selectAll()
    editor.deleteAll()
    editor.insertText(text)
  }
}

// The counterpart of addImageFittedIntoRectangle(logo, new Rectangle(72, 72, 150, 50),
// false).
function useStampLogo() {
  const createStamp = useStampAnnotationCreate()

  return async (pageId: string, logo: Blob) => {
    const image = await stageImage(logo)
    // x and y are the bottom-left corner in user space; with only a width, the height
    // follows the aspect ratio.
    return createStamp({ pageId, image, x: 72, y: 72, width: 150 })
  }
}

const addTextTool: InteractionTool = { type: 'addText' }

function StampToolbar({ logo }: { logo: Blob }) {
  const interactionTool = useInteractionTool()
  const setInteractionMode = useSetInteractionMode()

  async function placeLogo() {
    const image = await stageImage(logo)
    // The next click on a page places the image, 150 user-space units wide.
    setInteractionMode(
      { type: 'addImage', image, width: 150 },
      CONTENT_POLICY_PRESET.PDF_EDITOR
    )
  }

  return (
    <div role="toolbar">
      {/* The next click creates a paragraph and focuses it. */}
      <button
        aria-pressed={interactionTool.type === 'addText'}
        onClick={() => setInteractionMode(addTextTool, CONTENT_POLICY_PRESET.PDF_EDITOR)}
      >
        Add text
      </button>
      <button
        aria-pressed={interactionTool.type === 'addImage'}
        onClick={() => placeLogo().catch(showError)}
      >
        Place logo
      </button>
    </div>
  )
}

ByteArrayOutputStream merged = new ByteArrayOutputStream();
try (PdfDocument result = new PdfDocument(new PdfWriter(merged));
     PdfDocument cover = new PdfDocument(
             new PdfReader(new ByteArrayInputStream(coverBytes)));
     PdfDocument contract = new PdfDocument(
             new PdfReader(new ByteArrayInputStream(contractBytes)))) {
    PdfMerger merger = new PdfMerger(result);
    merger.merge(cover, 1, 1);
    merger.merge(contract, 1, contract.getNumberOfPages());
}

ByteArrayOutputStream excerpt = new ByteArrayOutputStream();
try (PdfDocument source = new PdfDocument(
        new PdfReader(new ByteArrayInputStream(contractBytes)));
     PdfDocument part = new PdfDocument(new PdfWriter(excerpt))) {
    // Pages 2 to 4, inclusive.
    source.copyPagesTo(2, 4, part);
}

import { useDocumentSaving, usePages } from '@sdk-pdf/react'

// The browser-side counterpart of copyPagesTo(from, to, part): 1-based and inclusive.
function useSavePageRange() {
  const pages = usePages()
  const { prepareDocument } = useDocumentSaving()

  return async (from: number, to: number) => {
    if (from < 1 || to > pages.length || from > to)
      throw new RangeError('The page range is outside the document')

    const pageIds = pages.slice(from - 1, to).map((page) => page.id)
    return prepareDocument({ pageIds })
  }
}

try (PdfDocument pdfDoc = new PdfDocument(
        new PdfReader(new ByteArrayInputStream(stored)))) {
    StringBuilder text = new StringBuilder();
    for (int i = 1; i <= pdfDoc.getNumberOfPages(); i++) {
        text.append(PdfTextExtractor.getTextFromPage(
                pdfDoc.getPage(i), new LocationTextExtractionStrategy()));
        text.append('\n');
    }
}

import { useProgrammaticEditor } from '@sdk-pdf/react'

function useReadDocumentText() {
  const { getAllParagraphIds, getPlainTextParagraphs } = useProgrammaticEditor()

  return async () => {
    // Loads every page in turn, which takes a while on a large document.
    const paragraphIds = await getAllParagraphIds()
    const paragraphs = await getPlainTextParagraphs(paragraphIds)

    return paragraphs
      .map((paragraph) => `[page ${paragraph.pageNumber}] ${paragraph.content}`)
      .join('\n\n')
  }
}

ByteArrayOutputStream output = new ByteArrayOutputStream();
try (PdfDocument pdfDoc = new PdfDocument(
        new PdfReader(new ByteArrayInputStream(stored)), new PdfWriter(output),
        new StampingProperties().useAppendMode())) {
    PdfFormCreator.getAcroForm(pdfDoc, true).getField("status").setValue("Approved");
}
storage.save(documentId, output.toByteArray());

response.setContentType("application/pdf");
response.setHeader("Content-Disposition", "attachment; filename=\"contract.pdf\"");
output.writeTo(response.getOutputStream());

import { useRef, useState } from 'react'
import {
  useDocumentRevision,
  useDocumentRevisionGetter,
  useDocumentSaving,
} from '@sdk-pdf/react'

function SaveControls({ url }: { url: string }) {
  const revision = useDocumentRevision()
  const getRevision = useDocumentRevisionGetter()
  // The revision on the server: the loaded document's revision until the first save.
  const [savedRevision, setSavedRevision] = useState(revision)
  // One save at a time, so an overlapping save can't mark a failed upload as saved.
  const isSavingRef = useRef(false)
  const { prepareDocument, downloadDocument } = useDocumentSaving()

  // Undoing back to the saved state clears it too.
  const hasUnsavedChanges = revision !== savedRevision

  async function save() {
    if (isSavingRef.current) return
    isSavingRef.current = true
    try {
      // Edits made after the save starts may be missing from the saved bytes, so only
      // this revision becomes saved.
      const startRevision = getRevision()
      // The buffer goes to fetch, so don't hand out the loaded document's original
      // buffer.
      const bytes = await prepareDocument({ returnOriginalIfUnchanged: false })
      const response = await fetch(url, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/pdf' },
        body: bytes as BodyInit,
      })
      // Keep the unsaved state when the server rejects the file.
      if (!response.ok) throw new Error(`Saving failed with ${response.status}`)

      setSavedRevision(startRevision)
    } finally {
      isSavingRef.current = false
    }
  }

  return (
    <div role="toolbar">
      <button disabled={!hasUnsavedChanges} onClick={() => save().catch(showError)}>
        Save
      </button>
      <button onClick={() => void downloadDocument()}>Download</button>
      {hasUnsavedChanges && <span>Unsaved changes</span>}
    </div>
  )
}

try (PdfDocument pdfDoc = new PdfDocument(
        new PdfReader(new ByteArrayInputStream(stored)))) {
    if (pdfDoc.getReader().hasRebuiltXref()) {
        metrics.increment("pdf.repaired");
    }
} catch (BadPasswordException e) {
    // A missing or wrong password.
} catch (PdfException e) {
    // A file iText can't process.
} catch (IOException e) {
    // Reading the bytes failed.
}

<!-- logback.xml: iText's loggers are named after its classes, under com.itextpdf. -->
<logger name="com.itextpdf" level="WARN" />

import { useEffect } from 'react'
import { logMessages, LogLevel } from '@sdk-pdf/react'

function useForwardSdkLogs(url: string) {
  useEffect(() => {
    // The SDK never prints to the console: subscribe, and unsubscribe on unmount.
    const unsubscribe = logMessages.on('message', (logMessage) => {
      if (logMessage.level < LogLevel.Warning) return

      // The message is static, so it groups cleanly in the server's logs.
      navigator.sendBeacon(
        url,
        JSON.stringify({
          level: logMessage.level,
          reason: logMessage.reason,
          message: logMessage.message,
        })
      )
    })
    return () => {
      unsubscribe()
    }
  }, [url])
}

PdfDocument pdfDoc = new PdfDocument(new PdfReader(input), new PdfWriter(output));
// Keep the caller's output stream open after close().
pdfDoc.setCloseWriter(false);
try {
    // Work with the document.
} finally {
    // Writes the file; later calls on pdfDoc throw PdfException.
    pdfDoc.close();
}