如何從 FTP 突顯 PDF（Java） – 在 Java 中從 FTP 為 PDF 添加註釋

當你需要對位於 FTP 伺服器上的 highlight PDF Java 檔案進行突顯時，先下載文件往往會浪費資源。在本教學中，你將看到如何直接從 FTP 串流 PDF、套用突顯註釋，並儲存結果——全部不產生中間的本機檔案。我們會逐步說明所需的函式庫、展示精確的 API 呼叫（保留佔位碼程式區塊不變），並提供在生產環境中擴展此模式的實用技巧。

快速解答

  • 我可以在不先下載 PDF 的情況下進行註釋嗎？ 是——直接從 FTP 串流檔案並在記憶體中註釋。
  • 哪個函式庫負責註釋？ GroupDocs.Annotation for Java 提供流暢的 API 以進行突顯、註記與圖形。
  • 生產環境需要授權嗎？ 需要完整的 GroupDocs 授權才能在生產部署中使用。
  • 需要哪個 Java 版本？ 支援 JDK 8 或更新版本。
  • FTP 是唯一的儲存選項嗎？ 不是——相同的串流方式也適用於 S3、Azure Blob 或本機檔案系統。

在 PDF 的情境下，「如何添加註釋」是什麼意思？

添加註釋指的是以程式方式在 PDF 文件中插入視覺標記——例如突顯、註記或圖形。使用 GroupDocs.Annotation 可直接在輸入串流上完成，這對於 FTP 伺服器等遠端來源而言非常理想。

為何選擇此方式進行 PDF FTP 註釋？

從 FTP 載入 PDF、套用突顯，並在單一管線中寫回。此方式可消除本機磁碟 I/O、減少網路流量，並讓版本控制保持簡單。在大規模環境中，此模式每分鐘可處理數百份文件，同時將每檔案的記憶體使用量控制在 100 MB 以下。

前置條件與環境設定

  • 已安裝 JDK 8 或更新版本。
  • Apache Commons Net 函式庫（提供 FTPClient 類別）。
  • GroupDocs.Annotation for Java 函式庫（建議使用最新版本）。
  • 用於相依管理的 Maven 或 Gradle。
  • 具備讀寫權限的有效 FTP 憑證。

設定 GroupDocs.Annotation for Java

Maven 設定

將儲存庫與相依項目加入你的 pom.xml 檔案：

<repositories>
   <repository>
      <id>repository.groupdocs.com</id>
      <name>GroupDocs Repository</name>
      <url>https://releases.groupdocs.com/annotation/java/</url>
   </repository>
</repositories>
<dependencies>
   <dependency>
      <groupId>com.groupdocs</groupId>
      <artifactId>groupdocs-annotation</artifactId>
      <version>25.2</version>
   </dependency>
</dependencies>

授權設定選項

GroupDocs 提供三種授權模式：

  1. Free Trial – 非常適合概念驗證工作。
  2. Temporary License – 在評估期間移除試用限制。
  3. Full License – 任何生產部署皆需此授權。

專業提示： 先使用免費試用版，確認工作流程符合效能目標後再升級。

完整實作指南

以下是逐步說明，展示 how to add annotation（如何添加註釋）到從 FTP 伺服器取得的 PDF。

步驟 1：從 FTP 伺服器載入文件

FTPClient 是 Apache Commons Net 用於處理 FTP 連線的類別。它抽象化低層協定，讓你以串流方式取得檔案。

import org.apache.commons.net.ftp.FTPClient;
import java.io.IOException;
import java.io.InputStream;

public static InputStream getFileFromFtp(String server, String filePath) throws IOException {
    // Initialize FTP client
    FTPClient client = new FTPClient();
    
    // Connect to the FTP server
    client.connect(server);
    
    // Retrieve the specified file as an input stream
    InputStream inputStream = client.retrieveFileStream(filePath);
    
    // Disconnect from the FTP server
    client.disconnect();
    
    return inputStream;
}

發生了什麼？

  • FTPClient 開啟連線、登入，並串流遠端 PDF。
  • 回傳的 InputStream 可避免在磁碟上產生暫存檔。
  • 在安全環境下，請將 FTPClient 換成 FTPSClient 以啟用 TLS 加密。

FTPSClient 繼承自 FTPClient，提供 FTP over TLS 的安全傳輸。

步驟 2：為 PDF 添加註釋

Annotator 是 GroupDocs.Annotation 的核心類別，可直接使用 InputStream。它能建立、修改並儲存註釋，而不必將整份文件載入記憶體。

PdfLoadOptions 設定 PDF 的載入方式，例如密碼處理與頁面範圍。
Rectangle 定義註釋在頁面上的位置與大小。

import com.groupdocs.annotation.Annotator;
import com.groupdocs.annotation.models.Rectangle;
import com.groupdocs.annotation.models.annotationmodels.AreaAnnotation;
import java.io.InputStream;

public static void addAnnotationAndSave(InputStream inputStream, String outputPath) {
    // Initialize Annotator with the provided InputStream
    final Annotator annotator = new Annotator(inputStream);
    
    // Create a new Area Annotation
    AreaAnnotation area = new AreaAnnotation();
    
    // Set the position and size of the annotation (100x100 at coordinates 100,100)
    area.setBox(new Rectangle(100, 100, 100, 100));
    
    // Set a background color for the annotation
    area.setBackgroundColor(65535); // Yellow color in ARGB format
    
    // Add the annotation to the document
    annotator.add(area);
    
    // Save the annotated document to the specified output path
    annotator.save(outputPath);
    
    // Dispose of resources used by Annotator
    annotator.dispose();
}

重點

  • Annotator 接受 PDF 串流與 PdfLoadOptions 物件。
  • Rectangle 定義突顯在頁面上的位置與尺寸。
  • 顏色以 ARGB 整數表示；65535 代表亮黃色。

步驟 3：整合所有步驟

main 方法示範完整工作流程——從 FTP 取得檔案到儲存已突顯的 PDF。

public class PDFAnnotationFromFTP {
    public static void main(String[] args) {
        try {
            // Load PDF from FTP server
            InputStream pdfStream = getFileFromFtp("ftp.example.com", "/documents/report.pdf");
            
            // Add annotations and save
            addAnnotationAndSave(pdfStream, "annotated_report.pdf");
            
            System.out.println("PDF successfully annotated from FTP!");
            
        } catch (IOException e) {
            System.err.println("Error processing PDF: " + e.getMessage());
        }
    }
}

執行此程式會產生 annotated_report.pdf，其中的黃色突顯位於你指定的座標。

進階註釋技巧

除了簡單的區域突顯外，GroupDocs.Annotation 支援多種註釋類型，適用於不同的商業情境。

文字註釋 – 詳細說明

TextAnnotation 讓你在任意頁面區域附加自由形式的註記。

TextAnnotation textAnnotation = new TextAnnotation();
textAnnotation.setBox(new Rectangle(200, 200, 100, 50));
textAnnotation.setText("Important: Review this section carefully");
textAnnotation.setFontColor(16711680); // Red text
annotator.add(textAnnotation);

點註釋 – 快速備註

PointAnnotation 會建立一個指標標記，可用於清單項目或錯誤標示。

PointAnnotation pointAnnotation = new PointAnnotation();
pointAnnotation.setBox(new Rectangle(300, 150, 0, 0));
pointAnnotation.setText("Check this calculation");
annotator.add(pointAnnotation);

真實案例與應用

了解 highlight pdf java 能帶來的價值，有助於決定何時採用此模式。

情境註釋如何協助
Legal Document Review突顯條款、添加旁註，且無需在本機複製檔案即可保留完整稽核紀錄。
Engineering Report Processing標記關鍵測量值、附加安全警告，並即時與遠端團隊分享註釋過的 PDF。
Educational Content Management教師可對儲存在 FTP 的學生提交檔案進行註釋，於數秒內提供回饋。
Business Intelligence在財務 PDF 中標記關鍵績效指標，然後自動產生執行摘要。

效能最佳化與最佳實踐

記憶體管理技巧

try‑with‑resources 可確保即時關閉串流與 Annotator，防止記憶體洩漏。

try (Annotator annotator = new Annotator(inputStream)) {
    // Your annotation code here
    annotator.add(annotation);
    annotator.save(outputPath);
} // Automatic resource cleanup
  • 完成使用後立即釋放每個串流。
  • 若 PDF 超過 200 頁，請增加 JVM 堆疊大小（-Xmx2g）或使用 Annotator 的頁面級 API 分批處理。

網路最佳化策略

FTP 連線池

在多個檔案間重複使用單一 FTPClient 實例，可減少握手開銷並提升吞吐量。

FTPClient client = new FTPClient();
client.connect(server);
client.login(username, password);

for (String filePath : filePaths) {
    InputStream stream = client.retrieveFileStream(filePath);
    processAndAnnotate(stream);
}

client.disconnect();
  • 啟用被動模式（client.enterLocalPassiveMode()）以穿越防火牆。
  • 實作指數退避重試，以優雅處理暫時的網路故障。

完整錯誤處理

預測 I/O 失敗並提供明確的復原路徑。

IOException 是在輸入或輸出操作期間發生失敗時拋出的例外。

public static InputStream getFileFromFtpWithRetry(String server, String filePath, int maxRetries) {
    for (int attempt = 1; attempt <= maxRetries; attempt++) {
        try {
            return getFileFromFtp(server, filePath);
        } catch (IOException e) {
            if (attempt == maxRetries) {
                throw new RuntimeException("Failed to retrieve file after " + maxRetries + " attempts", e);
            }
            // Wait before retry
            try {
                Thread.sleep(1000 * attempt); // Exponential backoff
            } catch (InterruptedException ie) {
                Thread.currentThread().interrupt();
                throw new RuntimeException("Interrupted during retry", ie);
            }
        }
    }
    return null;
}
  • 捕捉 IOException，最多重試三次。
  • 記錄檔案名稱、FTP 回應碼與堆疊追蹤，以供稽核使用。

常見問題排除

問題可能原因解決方案
Connection timed out伺服器/埠號錯誤或防火牆阻擋核對 FTP 位址、開啟埠號 21，並啟用被動模式。
Authentication failure憑證錯誤或權限不足再次確認使用者名稱/密碼，並確保帳號具備讀取目標目錄的權限。
“Document format not supported”檔案損毀或非 PDF 內容確認檔案為有效 PDF，並設定 FTP 二進位模式（FTP.BINARY_FILE_TYPE）。
Annotations not appearing座標超出頁面範圍或安全限制使用 PdfInfo 取得頁面尺寸以計算有效矩形；在註釋前移除密碼保護。
Color not showingARGB 值不正確使用已知值：Red = 0xFFFF0000、Green = 0xFF00FF00、Blue = 0xFF0000FF、Yellow = 0xFFFFFF00。

PdfInfo 提供 PDF 的中繼資料，包括頁面尺寸與頁數。

生產環境安全考量

  • 絕不要硬編碼憑證——請將其存放於環境變數或機密管理服務中。
  • 優先使用 FTPS（FTP over TLS）以加密傳輸中的資料。
  • 在處理前驗證檔案類型與大小，以防惡意負載。
  • 記錄每一次存取——保留稽核追蹤以符合法規與鑑識分析需求。

常見問答

Q: 我可以將此方式與雲端儲存服務（如 AWS S3 或 Google Drive）一起使用嗎？
A: 當然可以。將 FTP 取得程式碼替換為相應的 SDK 呼叫，註釋邏輯保持不變。

Q: 除了 PDF，GroupDocs.Annotation 支援哪些檔案格式？
A: GroupDocs.Annotation 支援 50+ 種格式，包括 DOCX、XLSX、PPTX、JPEG、PNG 與 CAD 檔案等。

Q: 如何在不耗盡記憶體的情況下處理非常大的 PDF？
A: 以串流方式處理檔案，必要時增加 JVM 堆疊，並使用頁面級 API 逐頁處理。

Q: 能否從從 FTP 載入的 PDF 中讀取現有的註釋？
A: 可以。載入串流後呼叫 annotator.get() 以取得所有現有註釋，再進行新增。

Q: 有效處理數百份文件的最佳方法是什麼？
A: 結合 FTP 連線池、Java 的 CompletableFuture 進行非阻塞非同步執行，以及使用訊息佇列（如 RabbitMQ）將工作分散至多個工作節點。

CompletableFuture 讓 Java 任務以非同步、非阻塞方式執行。

下一步？

首先將串流註釋流程整合至現有的文件管理服務。接著嘗試其他註釋類型——印章、浮水印與自訂圖形，以提升使用者體驗。最後，提供一個簡易的 REST 端點，接受 FTP 路徑、套用突顯，並在回應主體中回傳註釋過的 PDF。此端對端管線將為你提供可擴充、即時的 PDF 處理引擎。

資源與進一步學習

Last Updated: 2026-06-26
Tested With: GroupDocs.Annotation 25.2 for Java
Author: GroupDocs

{< blocks/products/products-backtop-button >}

相關教學