Java 클라이언트 라이브러리 설정

Java 클라이언트 라이브러리 설정 (Java client setup)

Java 클라이언트 라이브러리를 설치하고 Pulsar 클러스터에 연결하는 방법을 정리해볼게요. Maven 또는 Gradle로 pulsar-client 아티팩트를 추가하면 되고, 의존성 충돌을 피하고 싶다면 Pulsar BOM을 함께 쓰는 걸 권장해요. 마지막에는 프로토콜 URL로 클러스터를 지정하는 법까지 확인할 수 있어요.

출처: 문서

본문

Pulsar에서 Java 클라이언트를 설정하려면 다음 단계를 완료하세요.

1단계: Java 클라이언트 라이브러리 설치 (Step 1: Install Java client library)

Pulsar Java 클라이언트는 Maven Central에 두 가지 라인으로 게시돼요: LTS 버전(4.0.13)과 최신 버전(5.0.0-M2)이에요. 최근에 추가된 기능이 필요하지 않다면 LTS 버전을 사용하세요 — 장기 지원과 버그 수정을 받을 수 있어요.

아래처럼 빌드 구성에 pulsar-client 아티팩트를 추가해요. 게시된 아티팩트는 Maven Central에서 확인할 수 있어요(LTS, latest).

Pulsar는 shade된 클라이언트와 shade되지 않은 클라이언트 아티팩트를 모두 게시해요.

  • Shade됨 (pulsar-client, pulsar-client-admin) — 의존성(예: Netty)이 maven-shade-plugin으로 재배치(relocate)되어 충돌을 피해요. 의존성 충돌을 직접 관리하고 싶지 않다면 권장돼요.
  • Shade되지 않음 (pulsar-client-original, pulsar-client-admin-original) — 의존성이 재배치되지 않아요. 의존성을 직접 관리하고 싶다면 사용하되, 이 경우 pulsar-bom을 가져오고 netty-bom으로 Netty 버전을 맞춰야 해요.

Maven

Maven을 사용한다면 pom.xml 파일에 다음 정보를 추가해요.

<!-- in your <properties> block -->
<!-- LTS: 4.0.13, latest: 5.0.0-M2, milestone: 5.0.0-M2 -->
<pulsar.version>4.0.13</pulsar.version>

<!-- in your <dependencies> block -->
<dependency>
  <groupId>org.apache.pulsar</groupId>
  <artifactId>pulsar-client</artifactId>
  <version>${pulsar.version}</version>
</dependency>

Gradle

Gradle을 사용한다면 build.gradle 파일에 다음 정보를 추가해요.

// LTS: 4.0.13, latest: 5.0.0-M2, milestone: 5.0.0-M2
def pulsarVersion = '4.0.13'

dependencies {
    implementation "org.apache.pulsar:pulsar-client:${pulsarVersion}"
}

Pulsar BOM

위 의존성만으로도 Pulsar Java 클라이언트를 얻기에 충분하지만, 모든 Pulsar 의존성이 같은 예상 버전에 있도록 Pulsar BOM을 함께 사용하는 것을 권장해요. BOM을 사용하려면 이전 지침을 약간 수정하면 돼요.

Maven

Spring Boot와 기본 Maven 빌드를 사용할 때는 Spring Boot Maven 플러그인 기능으로 Pulsar 버전을 구성해야 한다는 점을 주의하세요. 자세한 내용은 Spring Boot using Maven 섹션을 참고해요.

Maven을 사용한다면 pom.xml 파일에 다음 정보를 추가해요.

<!-- in your <properties> block -->
<!-- LTS: 4.0.13, latest: 5.0.0-M2, milestone: 5.0.0-M2 -->
<pulsar.version>4.0.13</pulsar.version>

<!-- in your <dependencyManagement>/<dependencies> block -->
<dependency>
  <groupId>org.apache.pulsar</groupId>
  <artifactId>pulsar-bom</artifactId>
  <version>${pulsar.version}</version>
  <type>pom</type>
  <scope>import</scope>
</dependency>

<!-- in your <dependencies> block -->
<dependency>
  <groupId>org.apache.pulsar</groupId>
  <artifactId>pulsar-client</artifactId>
</dependency>

Gradle

Gradle을 사용한다면 build.gradle 파일에 다음 정보를 추가해요. Spring Boot와 기본 Gradle 빌드에서 Spring Dependency Management 플러그인(io.spring.dependency-management)을 사용할 때는, Spring Dependency Management 플러그인 기능으로 Pulsar 버전을 구성해야 한다는 점을 주의하세요. 자세한 내용은 Spring Boot using Gradle 섹션을 참고해요.

// LTS: 4.0.13, latest: 5.0.0-M2, milestone: 5.0.0-M2
def pulsarVersion = '4.0.13'

dependencies {
  implementation enforcedPlatform("org.apache.pulsar:pulsar-bom:${pulsarVersion}")
  implementation 'org.apache.pulsar:pulsar-client'
}

이제 pulsar-client 의존성의 버전 번호는 Pulsar BOM이 어떤 버전을 사용할지 결정하므로 생략된다는 점을 참고하세요.

Spring Boot

Pulsar를 Spring Boot와 함께 사용하는 방법에 대한 자세한 내용은 Spring Boot 문서를 참고하세요.

Spring Boot using Maven

Spring Boot 의존성 버전 속성은 pulsar.version과 pulsar-reactive.version을 정의해 Pulsar Java 클라이언트 버전과 Pulsar Reactive 클라이언트 버전을 제어해요.

<!-- in your <properties> block -->
<!-- LTS: 4.0.13, latest: 5.0.0-M2, milestone: 5.0.0-M2 -->
<pulsar.version>4.0.13</pulsar.version>

<!-- in your <dependencies> block -->
<!-- The Pulsar Java client will be automatically added to dependencies as a transitive dependency of the spring-boot-starter-pulsar dependency -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-pulsar</artifactId>
</dependency>

Spring Boot using Gradle

Gradle에서 Spring Dependency Management 플러그인(io.spring.dependency-management)을 사용할 때는 Spring Dependency Management 플러그인 기능으로 Pulsar 버전을 구성해야 한다는 점을 주의하세요.

Spring Boot 의존성 버전 속성은 pulsar.version과 pulsar-reactive.version을 정의해 Pulsar Java 클라이언트 버전과 Pulsar Reactive 클라이언트 버전을 제어해요. Gradle을 사용하는 Spring Boot 애플리케이션에서 Pulsar Java 클라이언트의 특정 Pulsar 버전을 사용하려면 Spring Boot 프로젝트의 build.gradle 파일에 다음을 추가해요.

// Alternatively, you can set the `pulsar.version` property in the `gradle.properties` file.

// LTS: 4.0.13, latest: 5.0.0-M2, milestone: 5.0.0-M2
ext['pulsar.version'] = '4.0.13'

// The Pulsar Java client will be automatically added to dependencies as a transitive dependency of the spring-boot-starter-pulsar dependency
dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-pulsar'
}

2단계: Pulsar 클러스터에 연결 (Step 2: Connect to Pulsar cluster)

클라이언트 라이브러리로 Pulsar에 연결하려면 Pulsar 프로토콜 URL을 지정해야 해요. 특정 클러스터에 Pulsar 프로토콜 URL을 할당하고 pulsar 체계를 사용할 수 있어요. 기본 포트 6650을 사용하는 localhost의 예시는 다음과 같아요.

pulsar://localhost:6650

여러 브로커가 있다면 IP:port를 쉼표로 구분해요.

pulsar://localhost:6550,localhost:6651,localhost:6652

mTLS 인증을 사용한다면 체계에 +ssl을 추가해요.

pulsar+ssl://pulsar.us-west.example.com:6651

Java 클라이언트 성능 고려사항 (Java client Performance considerations)

메모리 제한 늘리기 (Increasing the memory limit)

고처리량 애플리케이션의 경우, Java 클라이언트 빌더의 memoryLimit 구성 옵션으로 메모리 양을 늘릴 수 있어요. 기본 제한은 64MB인데, 고처리량 애플리케이션에는 보통 너무 적어요.

기본적으로 Java 애플리케이션은 다이렉트 메모리(direct memory) 할당에 제한이 있어요. 할당은 -XX:MaxDirectMemorySize JVM 옵션에 의해 제한돼요. 많은 JVM 구현에서, 명시적으로 설정하지 않으면 최대 힙 크기로 기본 설정돼요. 할당은 Java 힙 밖에서 일어나요.

최적화된 Netty 다이렉트 메모리 버퍼 접근 활성화 (Enabling optimized Netty direct memory buffer access)

Pulsar Java 클라이언트는 내부적으로 Netty를 사용하고, 데이터 전송에 Netty 다이렉트 버퍼를 사용해요. Netty에는 최적화된 다이렉트 메모리 버퍼 접근을 허용하는 기능이 있어요. 이 기능은 Netty가 다이렉트 메모리 연산에 sun.misc.Unsafe 같은 저수준 API를 사용하게 해, 다이렉트 버퍼의 할당과 해제를 더 빠르게 해줘요.

더 빠른 해제는 다이렉트 메모리 고갈과 java.lang.OutOfMemoryError: Direct buffer memory 에러를 피하는 데 도움이 돼요. 이런 에러는 Netty 메모리 풀과 메모리 할당자가 메모리를 운영체제로 충분히 빨리 반환하지 못할 때 발생할 수 있어요.

Java 11 이후 Java 클라이언트에서 이 기능을 활성화하려면 Java 클라이언트를 사용하는 애플리케이션에 다음 JVM 옵션을 추가해야 해요.

  • --add-opens java.base/java.nio=ALL-UNNAMED
  • --add-opens java.base/jdk.internal.misc=ALL-UNNAMED

또한 다음 JVM 옵션 중 하나를 추가해야 해요.

  • 기본 shade된 Pulsar 클라이언트의 경우 -Dorg.apache.pulsar.shade.io.netty.tryReflectionSetAccessible=true
  • shade되지 않은 "original" Pulsar 클라이언트의 경우 -Dio.netty.tryReflectionSetAccessible=true

네이티브 라이브러리 로딩 실패 시 최적화된 체크섬 계산 활성화 (Enabling optimized checksum calculation when native library loading fails)

Pulsar Java 클라이언트는 체크섬 계산에 BookKeeper 클라이언트의 com.scurrilous.circe.checksum.Crc32cIntChecksum 클래스를 사용해요. 최적화된 체크섬 계산을 위해 Pulsar는 libcirce-checksum 네이티브 라이브러리 로딩을 시도해요. 그 라이브러리를 사용할 수 없을 때는 com.scurrilous.circe.checksum.Java9IntHash 클래스가 사용돼요.

이것은 JVM 옵션에 --add-opens java.base/java.util.zip=ALL-UNNAMED가 전달될 때만 동작해요. 필요한 JVM 옵션이 없을 때 에러 메시지는 Unable to use reflected methods: java.lang.reflect.InaccessibleObjectException: Unable to make private static int java.util.zip.CRC32C.updateBytes(int,byte[],int,int) accessible: module java.base does not "opens java.util.zip" to unnamed module가 될 거예요.

더 알아보기 (Learn more)