Jak podświetlić PDF w Javie z FTP – Dodaj adnotację do PDF z FTP w Javie

Kiedy potrzebujesz highlight PDF Java plików znajdujących się na serwerze FTP, pobieranie dokumentu najpierw jest często nieefektywne. W tym samouczku zobaczysz, jak strumieniować PDF bezpośrednio z FTP, zastosować adnotację podświetlenia i zapisać wynik — wszystko bez tworzenia pośrednich plików lokalnych. Przejdziemy przez wymagane biblioteki, pokażemy dokładne wywołania API (bloki kodu zastępcze pozostają niezmienione) i podamy praktyczne wskazówki dotyczące skalowania tego wzorca w środowiskach produkcyjnych.

Szybkie odpowiedzi

• Czy mogę adnotować PDF bez jego pobierania? Tak – strumieniuj plik bezpośrednio z FTP i adnotuj w pamięci.
• Która biblioteka obsługuje adnotacje? GroupDocs.Annotation for Java zapewnia płynne API dla podświetleń, notatek i kształtów.
• Czy potrzebuję licencji do produkcji? Pełna licencja GroupDocs jest wymagana do wdrożeń produkcyjnych.
• Jaka wersja Javy jest wymagana? Obsługiwany jest JDK 8 lub nowszy.
• Czy FTP jest jedyną opcją przechowywania? Nie – to samo podejście strumieniowe działa z S3, Azure Blob lub lokalnymi systemami plików.

Co oznacza „jak dodać adnotację” w kontekście PDF‑ów?

Dodawanie adnotacji oznacza programowe wstawianie wizualnych znaków — takich jak podświetlenia, notatki czy kształty — do dokumentu PDF. Dzięki GroupDocs.Annotation można to zrobić bezpośrednio na strumieniu wejściowym, co jest idealne dla zdalnych źródeł, takich jak serwery FTP.

Dlaczego wybrać to podejście do adnotacji PDF z FTP?

Załaduj PDF z FTP, zastosuj podświetlenie i zapisz go z powrotem w jednym potoku. To eliminuje operacje I/O na dysku lokalnym, zmniejsza ruch sieciowy i upraszcza kontrolę wersji. W środowiskach dużej skali wzorzec może przetwarzać setki dokumentów na minutę, utrzymując zużycie pamięci poniżej 100 MB na plik.

Wymagania wstępne i konfiguracja środowiska

Zanim rozpoczniesz, upewnij się, że masz:

• Zainstalowany JDK 8 lub nowszy.
• Bibliotekę Apache Commons Net (udostępnia klasę FTPClient).
• Bibliotekę GroupDocs.Annotation for Java (zalecana najnowsza wersja).
• Maven lub Gradle do zarządzania zależnościami.
• Ważne dane uwierzytelniające FTP z uprawnieniami odczytu/zapisu.

Konfiguracja GroupDocs.Annotation dla Javy

Konfiguracja Maven

Add the repository and dependency to your pom.xml file:

<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>

Opcje konfiguracji licencji

GroupDocs offers three licensing models:

1. Free Trial – Idealny do prac proof‑of‑concept.
2. Temporary License – Usuwa ograniczenia wersji próbnej podczas oceny.
3. Full License – Wymagana do wszelkich wdrożeń produkcyjnych.

Pro tip: Rozpocznij od wersji próbnej, a następnie przejdź na płatną, gdy potwierdzisz, że przepływ pracy spełnia Twoje cele wydajnościowe.

Kompletny przewodnik implementacji

Poniżej znajduje się krok po kroku przewodnik, który pokazuje jak dodać adnotację do PDF pobranego z serwera FTP.

Krok 1: Ładowanie dokumentów z serwera FTP

FTPClient to klasa Apache Commons Net służąca do obsługi połączeń FTP. Abstrahuje protokół niskiego poziomu i umożliwia pobieranie plików jako strumienie.

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;
}

Co się dzieje?

• FTPClient otwiera połączenie, loguje się i strumieniuje zdalny PDF.
• Zwrócony InputStream zapobiega tworzeniu tymczasowego pliku na dysku.
• W środowiskach zabezpieczonych zamień FTPClient na FTPSClient, aby włączyć szyfrowanie TLS.

FTPSClient rozszerza FTPClient, zapewniając FTP over TLS dla bezpiecznych transferów.

Krok 2: Dodawanie adnotacji do PDF

Annotator to podstawowa klasa w GroupDocs.Annotation, która działa bezpośrednio z InputStream. Tworzy, modyfikuje i zapisuje adnotacje bez ładowania całego dokumentu do pamięci.

PdfLoadOptions konfiguruje sposób ładowania PDF, np. obsługę hasła i zakres stron.
Rectangle określa pozycję i rozmiar adnotacji na stronie.

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();
}

Kluczowe punkty

• Annotator przyjmuje strumień PDF oraz obiekt PdfLoadOptions.
• Rectangle definiuje pozycję i rozmiar podświetlenia na stronie.
• Kolory są wyrażane jako liczby całkowite ARGB; 65535 odpowiada jasnemu żółtemu.

Krok 3: Łączenie wszystkiego razem

Metoda main demonstruje pełny przepływ pracy — od pobrania z FTP po zapisanie podświetlonego 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());
        }
    }
}

Uruchomienie tego programu generuje annotated_report.pdf z żółtym podświetleniem umieszczonym w określonych przez Ciebie współrzędnych.

Zaawansowane techniki adnotacji

Poza prostymi podświetleniami obszarów, GroupDocs.Annotation obsługuje szeroką gamę typów adnotacji, przydatnych w różnych scenariuszach biznesowych.

Adnotacje tekstowe dla szczegółowych komentarzy

TextAnnotation pozwala dołączyć notatki w dowolnej formie do dowolnego regionu strony.

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);

Adnotacje punktowe dla szybkich notatek

PointAnnotation tworzy znacznik punktowy, który może być używany do elementów list kontrolnych lub flag błędów.

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

Praktyczne przypadki użycia i zastosowania

Zrozumienie, gdzie highlight pdf java przynosi wartość, pomaga zdecydować, kiedy przyjąć ten wzorzec.

Optymalizacja wydajności i najlepsze praktyki

Wskazówki dotyczące zarządzania pamięcią

try‑with‑resources zapewnia, że strumienie i Annotator są zamykane niezwłocznie, zapobiegając wyciekom pamięci.

try (Annotator annotator = new Annotator(inputStream)) {
    // Your annotation code here
    annotator.add(annotation);
    annotator.save(outputPath);
} // Automatic resource cleanup

• Zwolnij każdy strumień, gdy tylko skończysz go używać.
• Dla PDF‑ów przekraczających 200 stron zwiększ pamięć JVM (-Xmx2g) lub przetwarzaj strony w partiach, używając API na poziomie stron Annotator.

Strategie optymalizacji sieci

Puli połączeń FTP

Ponowne użycie jednej instancji FTPClient dla wielu plików zmniejsza narzut na nawiązywanie połączeń i zwiększa przepustowość.

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

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

client.disconnect();

• Włącz tryb pasywny (client.enterLocalPassiveMode()), aby ominąć zapory.
• Zaimplementuj ponowne próby z wykładniczym opóźnieniem, aby łagodnie obsługiwać przejściowe problemy sieciowe.

Solidna obsługa błędów

Przewiduj awarie I/O i zapewnij jasne ścieżki odzyskiwania.

IOException to wyjątek sygnalizujący awarię podczas operacji wejścia lub wyjścia.

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;
}

• Przechwytuj IOException i ponawiaj do trzech razy.
• Loguj nazwę pliku, kod odpowiedzi FTP oraz stack trace w celach audytowych.

Rozwiązywanie typowych problemów

PdfInfo dostarcza metadane o PDF, w tym rozmiary stron i ich liczbę.

Zagadnienia bezpieczeństwa przy użyciu w produkcji

• Nigdy nie koduj na stałe poświadczeń – przechowuj je w zmiennych środowiskowych lub menedżerze tajemnic.
• Preferuj FTPS (FTP over TLS), aby szyfrować dane w tranzycie.
• Waliduj typ i rozmiar pliku przed przetwarzaniem, aby chronić przed złośliwymi ładunkami.
• Loguj każdy dostęp – utrzymuj ślad audytu dla zgodności i analizy forensic.

Często zadawane pytania

Q: Czy mogę używać tego podejścia z usługami przechowywania w chmurze, takimi jak AWS S3 lub Google Drive?
A: Absolutnie. Zamień kod pobierania z FTP na odpowiednie wywołanie SDK; logika adnotacji pozostaje dokładnie taka sama.

Q: Jakie formaty plików obsługuje GroupDocs.Annotation oprócz PDF?
A: GroupDocs.Annotation obsługuje ponad 50 formatów, w tym DOCX, XLSX, PPTX, JPEG, PNG i pliki CAD.

Q: Jak obsłużyć bardzo duże PDF‑y bez wyczerpania pamięci?
A: Stream the file, increase the JVM heap if needed, and use the page‑level API to process one page at a time.

Q: Czy można odczytać istniejące adnotacje z PDF‑a załadowanego z FTP?
A: Tak. Wywołaj annotator.get() po załadowaniu strumienia, aby pobrać wszystkie bieżące adnotacje przed dodaniem nowych.

Q: Jaki jest najlepszy sposób na efektywne przetwarzanie setek dokumentów?
A: Połącz pooling połączeń FTP, CompletableFuture Javy do asynchronicznego, nieblokującego wykonywania oraz kolejkę wiadomości (np. RabbitMQ), aby rozłożyć pracę na wiele węzłów roboczych.

CompletableFuture umożliwia asynchroniczne, nieblokujące wykonywanie zadań w Javie.

Co dalej?

Rozpocznij od zintegrowania strumieniowego przepływu adnotacji z istniejącą usługą zarządzania dokumentami. Następnie eksperymentuj z dodatkowymi typami adnotacji — pieczątki, znaki wodne i niestandardowe kształty — aby wzbogacić doświadczenie użytkownika. Na koniec udostępnij prosty endpoint REST, który przyjmuje ścieżkę FTP, stosuje podświetlenie i zwraca adnotowany PDF w treści odpowiedzi. Ten end‑to‑end pipeline zapewni skalowalny, działający w czasie rzeczywistym silnik przetwarzania PDF.

Zasoby i dalsza nauka

• Documentation - Kompleksowa dokumentacja API i przewodniki
• API Reference - Szczegółowa dokumentacja metod
• Download Latest Version - Zawsze używaj najnowszej wersji
• Purchase License - Opcje wdrożenia produkcyjnego
• Free Trial - Wypróbuj wszystkie funkcje
• Temporary License - Usuń ograniczenia wersji próbnej
• Community Support - Uzyskaj pomoc od ekspertów i społeczności

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

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

Powiązane samouczki

• Jak adnotować PDF – Ładowanie PDF z URL w Javie – Kompletny przewodnik
• Jak adnotować PDF z Amazon S3 przy użyciu Javy – Kompletny przewodnik
• Java PDF Text Annotation: Dodaj wyszukiwalne podświetlenia z GroupDocs