Java에서 Apache POI 및 POI-TL을 활용한 Word 문서 템플릿 기반 생성

Java 애플리케이션에서 Word 문서를 템플릿 기반으로 자동 생성하고 내보내는 작업은 Apache POI와 POI-TL(POI Template Language) 라이브러리를 통해 효율적으로 구현할 수 있습니다. Apache POI는 Microsoft Office 문서를 다루기 위한 강력한 Java API이며, POI-TL은 이 POI 위에 구축되어 Word 문서 생성을 위한 직관적인 템플릿 엔진을 제공합니다. 이 두 라이브러리를 함께 사용하면 정형화된 Word 문서를 동적으로 생성하는 과정을 간소화할 수 있습니다.

다음은 POI와 POI-TL을 사용하여 Word 템플릿에서 문서를 생성하는 구체적인 절차입니다.

준비 단계

  1. 프로젝트에 필요한 의존성을 추가합니다. Maven 또는 Gradle을 사용하여 POI 및 POI-TL 라이브러리를 포함시킬 수 있습니다. Maven을 사용하는 경우, pom.xml 파일에 아래와 같은 의존성을 추가합니다.

    <!-- Apache POI 핵심 라이브러리 -->
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi</artifactId>
    <version>X.Y.Z</version>
</dependency>
<!-- OOXML 형식 (docx, xlsx 등) 지원 라이브러리 -->
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>X.Y.Z</version>
</dependency>

<!-- POI-TL 템플릿 엔진 라이브러리 -->
<dependency>
    <groupId>com.deepoove</groupId>
    <artifactId>poi-tl</artifactId>
    <version>A.B.C</version>
</dependency>

    (참고: X.Y.Z와 A.B.C는 현재 사용 가능한 최신 버전으로 대체해야 합니다.)

  2. Word 템플릿 파일 (예: my_report_template.docx)을 생성합니다. 이 템플릿 문서에는 동적으로 채워질 내용을 표시하기 위한 특별한 플레이스홀더를 포함할 수 있습니다. POI-TL은 기본적으로 {{key}} 형태의 플레이스홀더를 사용하여 데이터가 삽입될 위치를 지정합니다.

    예시 템플릿 내용:

    보고서 제목: {{reportTitle}}
작성자: {{authorName}}

주요 내용:
{{mainContent}}

날짜: {{generationDate}}

Java 코드 구현을 통한 문서 생성

  1. Java 클래스에서 먼저 Word 템플릿 파일을 로드합니다.

    import com.deepoove.poi.XWPFTemplate;
import java.io.IOException;

// ...

public class WordDocumentGenerator {

    public static void main(String[] args) {
        String templatePath = "src/main/resources/my_report_template.docx";
        XWPFTemplate docTemplate = null;
        try {
            docTemplate = XWPFTemplate.compile(templatePath);
        } catch (IOException e) {
            System.err.println("템플릿 파일을 불러오는 중 오류가 발생했습니다: " + e.getMessage());
            // 예외 처리 로직 추가 (예: 프로그램 종료, 기본 템플릿 사용 등)
            return;
        }

        // ... 다음 단계로 이동 ...
    }
}

  2. 템플릿 내의 플레이스홀더를 채울 데이터를 담는 데이터 모델을 생성합니다. 이 모델은 일반적으로 Map 형태를 사용하여 키-값 쌍으로 데이터를 관리하며, 키는 템플릿의 플레이스홀더 이름과 일치해야 합니다.

    import java.util.HashMap;
import java.util.Map;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;

// ... (main 메서드 내부 또는 별도 메서드) ...

Map<String, Object> renderingData = new HashMap<>();
renderingData.put("reportTitle", "월간 프로젝트 진행 보고서");
renderingData.put("authorName", "김철수");
renderingData.put("mainContent", "이번 달에는 신규 기능 개발을 성공적으로 완료하였으며, 다음 달에는 사용자 테스트 단계에 진입할 예정입니다.");
renderingData.put("generationDate", LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy년 MM월 dd일")));

// ...

  3. POI-TL을 사용하여 템플릿의 플레이스홀더를 데이터로 대체하고, 최종 Word 문서를 지정된 경로에 저장합니다.

    import java.io.FileOutputStream;
import java.io.IOException;

// ... (main 메서드 내부 또는 별도 메서드) ...

if (docTemplate != null) {
    // 데이터로 문서 렌더링
    docTemplate.render(renderingData);

    // 결과 문서를 파일로 저장
    String outputFilePath = "output/generated_monthly_report.docx";
    try (FileOutputStream out = new FileOutputStream(outputFilePath)) {
        docTemplate.write(out);
        System.out.println("Word 문서가 성공적으로 생성되었습니다: " + outputFilePath);
    } catch (IOException e) {
        System.err.println("문서 저장 중 오류가 발생했습니다: " + e.getMessage());
        // 예외 처리 로직 추가
    } finally {
        // 템플릿 리소스 닫기
        try {
            docTemplate.close();
        } catch (IOException e) {
            System.err.println("템플릿 리소스 닫는 중 오류 발생: " + e.getMessage());
        }
    }
}

위 단계를 거치면 지정된 Word 템플릿과 제공된 데이터를 기반으로 완전히 새로운 Word 문서가 생성됩니다. 이 과정에서 핵심은 코드의 논리적 정확성을 확보하고, 템플릿 내 플레이스홀더 이름이 데이터 모델의 키와 정확히 일치하는지 확인하는 것입니다. POI-TL은 단순 텍스트 대체 기능을 넘어 이미지, 표, 목록 등 복잡한 문서 요소를 처리하는 기능을 제공하여 문서 생성의 유연성을 크게 높여줍니다. 이러한 접근 방식은 보고서, 송장, 계약서 등 반복적으로 생성되는 다양한 Word 문서를 자동화하고, 일관되고 정확한 문서를 대량으로 만들어야 하는 시나리오에 특히 유용합니다.

태그: java Apache POI POI-TL Word 문서 자동화 템플릿 엔진

7월 26일 02:07에 게시됨

인기 태그

©2026 괴물 클럽