GroupDocs.Annotation for Java를 사용하여 주석이 달린 PDF 저장 방법

이 튜토리얼에서는 GroupDocs.Annotation for Java를 사용하여 프로그래밍 방식으로 주석이 달린 PDF 문서를 저장하는 방법을 알아봅니다. 법률 조항을 강조하거나 검토 의견을 추가하거나 엔지니어링 도면에 도형을 삽입해야 할 경우, 아래 단계는 Maven 설정부터 배치로 주석을 추가하고 최종 파일을 저장하는 전체 과정을 안내합니다. 끝까지 진행하면 모든 Java 애플리케이션에 강력한 PDF 주석 기능을 통합할 수 있게 됩니다.

빠른 답변

  • GroupDocs.Annotation의 주요 목적은 무엇입니까?
    Java 애플리케이션에서 프로그래밍 방식으로 주석이 달린 PDF 문서를 생성, 편집 및 주석이 달린 PDF 저장합니다.
  • 필요한 Maven 아티팩트는 무엇입니까?
    com.groupdocs:groupdocs-annotation (see the Maven 의존성 section).
  • 한 번에 여러 주석을 추가할 수 있나요?
    예 – 단일 작업에서 여러 주석 추가가 가능하여 I/O 오버헤드를 줄입니다.
  • Annotator를 어떻게 초기화합니까?
    튜토리얼에 표시된 Annotator 초기화 패턴을 사용하십시오; PDF를 로드하고 주석 작업을 위한 API를 준비합니다.
  • 핵심 모범 사례 팁은 무엇입니까?
    주석 모범 사례 체크리스트를 따라 메모리 관리, 배치 처리 및 최적 파일 크기를 유지하십시오.

“PDF에 주석을 다는 방법”이란?

GroupDocs.Annotation은 PDF 파일에 직접 시각적 메모(하이라이트, 댓글, 도형, 스탬프)를 삽입할 수 있는 Java 라이브러리입니다. 이 라이브러리는 저수준 PDF 조작을 추상화하여 PDF 내부보다 비즈니스 로직에 집중할 수 있게 합니다. 다양한 주석 유형을 지원하고 대용량 문서를 위한 스트리밍 API를 제공하며 기존 Java 프로젝트와 쉽게 통합되어 모든 PDF 기반 워크플로에 다재다능한 솔루션이 됩니다.

Java용 GroupDocs.Annotation를 사용하는 이유

GroupDocs.Annotation은 PDF 주석 작업을 단순화하면서 높은 성능과 확장성을 제공하는 포괄적인 기능 세트를 제공합니다. 이 라이브러리는 Java를 지원하는 모든 운영 체제에서 실행되며 전체 파일을 메모리에 로드하지 않고도 500 MB까지의 문서를 처리하고 15가지 이상의 내장 주석 유형을 포함합니다. API는 개발자를 위해 설계되어 몇 줄의 코드만으로 주석을 추가, 편집 및 제거할 수 있으며, 평가판과 프로덕션 모두에 적합한 강력한 라이선스 옵션을 제공합니다.

  • Cross‑platform support – Windows, Linux, macOS에서 실행되며 Java 호환 환경의 100 %를 커버합니다.
  • Rich annotation types – 텍스트, 영역, 타원, 사용자 정의 스탬프 등 15가지 이상의 내장 유형을 지원합니다.
  • No external PDF editors required – 모든 작업이 Java 코드 내부에서 이루어져 서드파티 의존성을 제거합니다.
  • Enterprise‑grade scalability – 스트리밍 API 덕분에 전체 파일을 메모리에 로드하지 않고도 500 MB까지의 PDF와 수백 페이지 문서를 처리할 수 있습니다.

사전 요구 사항

  • Java 8 또는 그 이상 (JDK 11 이상 권장).
  • Maven을 통한 의존성 관리.
  • IntelliJ IDEA 또는 Eclipse와 같은 IDE.
  • Java 컬렉션 및 예외 처리에 대한 기본 지식.

Maven 의존성 GroupDocs

Add the GroupDocs repository and the annotation library to your 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>

라이선스 획득

  1. Free trial – API 평가를 위해 30일 무료 체험판을 다운로드합니다.
  2. Temporary license – 전체 기능 접근을 위한 7일 평가 키를 요청합니다.
  3. Production license – 무제한 배포를 위한 영구 라이선스를 구매합니다.

Java에서 Annotator 초기화 방법

Annotator는 GroupDocs.Annotation의 핵심 클래스이며 PDF를 로드하고 주석을 생성, 편집 및 저장하는 메서드를 제공합니다. 올바르게 초기화하는 것이 안정적인 워크플로의 첫 단계이며, try‑with‑resources를 사용하면 네이티브 리소스가 자동으로 해제됩니다. 파일 경로(보호된 PDF인 경우 선택적으로 비밀번호)를 생성자에 전달하여 인스턴스를 만들면 이후 작업을 수행할 준비가 됩니다.

import com.groupdocs.annotation.Annotator;

public class Feature1 {
    public void loadAnnotator(String fileName) {
        try (final Annotator annotator = new Annotator(fileName)) {
            // Ready to use!
        }
    }
}

기능 1: 로드 및 Annotator 초기화

이 기능은 파일 경로와 선택적으로 보호된 PDF의 비밀번호를 전달하여 Annotator 인스턴스를 생성하는 방법을 보여줍니다.

import com.groupdocs.annotation.Annotator;

public class Feature1 {
    public void loadAnnotator(String fileName) {
        try (final Annotator annotator = new Annotator(fileName)) {
            // Annotator initialized and ready.
        }
    }
}

주석 생성 방법

주석을 생성하려면 특정 주석 모델을 인스턴스화하고 속성을 구성한 뒤 annotator의 컬렉션에 추가합니다.

기능 2: 영역 주석 생성

AreaAnnotation은 PDF 페이지에 사각형 하이라이트 영역을 나타냅니다. 텍스트나 이미지 중 주목이 필요한 부분을 표시하는 데 유용합니다.

import com.groupdocs.annotation.models.Rectangle;
import com.groupdocs.annotation.models.annotationmodels.AreaAnnotation;

public class Feature2 {
    public AreaAnnotation createAreaAnnotation() {
        AreaAnnotation area = new AreaAnnotation();
        area.setBox(new Rectangle(100, 100, 100, 100));
        area.setBackgroundColor(65535);
        area.setPageNumber(1);

        return area;
    }
}

기능 3: 타원 주석 생성

EllipseAnnotation은 페이지에 원형 또는 타원형 도형을 배치하여 로고, 다이어그램 또는 기타 시각 요소를 강조할 수 있게 합니다.

import com.groupdocs.annotation.models.Rectangle;
import com.groupdocs.annotation.models.annotationmodels.EllipseAnnotation;

public class Feature3 {
    public EllipseAnnotation createEllipseAnnotation() {
        EllipseAnnotation ellipse = new EllipseAnnotation();
        ellipse.setBox(new Rectangle(100, 100, 100, 100));
        ellipse.setBackgroundColor(123456);
        ellipse.setPageNumber(2);

        return ellipse;
    }
}

여러 주석 추가 방법

addAnnotations 메서드를 사용하면 문서에 주석 객체 컬렉션을 한 번에 추가할 수 있어 파일 시스템 쓰기와 메모리 사용을 줄여 성능을 향상시킵니다. 배치 주석을 사용하면 I/O 작업을 최소화하고 특히 대용량 PDF 작업 시 JVM 힙 사용량을 낮게 유지할 수 있습니다.

import com.groupdocs.annotation.Annotator;
import java.util.ArrayList;
import java.util.List;
import com.groupdocs.annotation.models.AnnotationBase;
import com.groupdocs.annotation.models.annotationmodels.AreaAnnotation;
import com.groupdocs.annotation.models.annotationmodels.EllipseAnnotation;

public class Feature4 {
    public void addAnnotations(Annotator annotator) {
        AreaAnnotation area = new AreaAnnotation();
        area.setBox(new Rectangle(100, 100, 100, 100));
        area.setBackgroundColor(65535);
        area.setPageNumber(1);

        EllipseAnnotation ellipse = new EllipseAnnotation();
        ellipse.setBox(new Rectangle(100, 100, 100, 100));
        ellipse.setBackgroundColor(123456);
        ellipse.setPageNumber(2);

        List<AnnotationBase> annotations = new ArrayList<>();
        annotations.add(area);
        annotations.add(ellipse);

        annotator.add(annotations);
    }
}

주석이 달린 PDF 저장 방법

SaveOptions를 사용하면 PDF를 영구 저장할 때 적용할 주석 유형 및 출력 설정을 지정할 수 있습니다. PDF를 로드하고 원하는 주석을 추가한 뒤, 어떤 주석 유형을 유지할지 지정한 SaveOptions 객체와 함께 save 메서드를 호출하면 변경 사항이 원본 구조를 보존하면서 디스크에 기록됩니다.

public class Feature5 {
    public String getOutputPath(String fileName) {
        return "YOUR_OUTPUT_DIRECTORY" + "/filtered_output.pdf";
    public void saveAnnotatedDocument(Annotator annotator, String outputPath) {
        SaveOptions saveOptions = new SaveOptions();
        saveOptions.setAnnotationTypes(AnnotationType.ELLIPSE);

        annotator.save(outputPath, saveOptions);
    }
}

Java용 주석 모범 사례

  • try‑with‑resources를 사용하여 Annotator를 자동으로 닫고 네이티브 리소스를 해제합니다.
  • Batch add annotations(Feature 4)처럼 주석을 일괄 추가하여 I/O 오버헤드를 최소화합니다.
  • SaveOptions에 필요한 주석 유형만 지정하여 출력 파일 크기를 제어합니다.
  • 저장 후 큰 문서를 메모리에서 해제하고 annotator.dispose()를 호출하여 누수를 방지합니다.

실용적인 적용 사례

  • Legal document review – 조항을 강조하고 댓글을 첨부하며 검토자 변경 사항을 추적합니다.
  • Educational resources – 교과서나 강의 슬라이드에 주석을 달아 협업 학습 그룹에 활용합니다.
  • Technical manuals – 엔지니어링 도면에 직접 메모, 경고 및 개정 표시를 삽입합니다.

성능 고려 사항

  • 300 MB 이상 대용량 PDF에 대한 동시 주석 작업을 제한하여 힙 압력을 방지합니다.
  • 일반적인 엔터프라이즈 워크로드에서 메모리 사용량을 200 MB 이하로 유지하려면 주석 모범 사례를 따르세요.
  • 지연 시간이 급증하면 Java Flight Recorder 또는 VisualVM으로 애플리케이션을 프로파일링합니다.

일반적인 문제 및 해결책

문제해결책
OutOfMemoryError 발생 시 대용량 PDF 로드문서를 스트리밍 모드(new Annotator(stream))로 로드하거나 JVM 힙(-Xmx2g)을 늘립니다.
저장 후 주석이 표시되지 않음SaveOptions에 올바른 AnnotationType 열거형 값이 포함되어 있는지 확인합니다.
라이선스 오류라이선스 파일 경로가 올바른지, 라이선스 버전이 라이브러리 버전과 일치하는지 확인합니다.

자주 묻는 질문

Q: 텍스트 주석을 도형 외에 추가할 수 있나요?
A: 예, GroupDocs.Annotation은 TextAnnotation 및 CommentAnnotation 유형을 지원합니다—적절한 모델을 인스턴스화하고 annotator 컬렉션에 추가하십시오.

Q: 기존 주석을 편집할 수 있나요?
A: 물론입니다. ID로 주석을 조회하고 속성을 수정한 뒤 annotator.update(updatedAnnotation)을 호출합니다.

Q: 더 이상 필요 없는 주석을 어떻게 제거하나요?
A: annotator.delete(annotationId)를 사용해 특정 주석을 삭제하거나 annotator.clear(pageNumber)로 페이지의 모든 주석을 삭제합니다.

Q: 라이브러리가 비밀번호로 보호된 PDF에서도 작동하나요?
A: 예. Annotator 인스턴스를 생성할 때 비밀번호를 제공하면 됩니다: new Annotator(filePath, password).

Q: 필요한 Java 버전은 무엇인가요?
A: 라이브러리는 Java 8 및 그 이후 버전과 호환됩니다; 최적의 성능과 보안을 위해 최신 LTS 릴리스(Java 17)를 권장합니다.


마지막 업데이트: 2026-10-11
테스트 환경: GroupDocs.Annotation 25.2
작성자: GroupDocs


관련 튜토리얼