DOC: Separate ConnectionFactoryBuilder and Transcoder docs by f1v3-dev · Pull Request #1052 · naver/arcus-java-client

f1v3-dev · 2026-02-26T08:52:22Z

🔗 Related Issue

https://github.com/jam2in/arcus-works/issues/695#issuecomment-3931062402

⌨️ What I did

ConnectionFactoryBuilder 항목에 대한 문서를 개선합니다.
02-arcus-java-client.md 에서는 ConnectionFactoryBuilder 옵션에 대한 표를 제공합니다.
- ConnectionFactoryBuilder 옵션에 대한 구체적인 설명은 별도의 페이지에서 소개합니다.
- Transcoder 또한, 구체적인 설명은 별도의 페이지에서 소개합니다.

수정 내용 미리보기 링크

02-arcus-java-client.md - ConnectionFactoryBuilder

13-connection-factory.md

14-transcoder.md

oliviarla

리뷰 완료입니다. @jhpark816 방향성만 한번 미리 확인해주시면 좋겠습니다.

oliviarla · 2026-02-26T12:29:42Z

docs/user-guide/13-connection-factory.md

+cfb.setAPIReadPriority(APIType.GET, ReadPriority.MASTER); // GET만 Master로 읽기
+```
+
+## 주의사항


변경 불가 설정 같은 단어를 사용하면 좋을 것 같은데 고민해보시고 괜찮은거로 변경해주세요.

고민을 해봤는데 아래와 같은 형식은 어떨까요?

## ARCUS 환경 제약사항 > 아래의 옵션은 spymemcached 호환을 위해 존재하며, ARCUS 환경에서 변경해도 효과가 없거나 정상 동작을 보장하지 않습니다.

괜찮아보입니다.

oliviarla · 2026-02-26T12:32:01Z

docs/user-guide/13-connection-factory.md

+**Queue**
+
+| Method                                          | Description                                | Default                      | Unit | Note       |
+|:------------------------------------------------|:-------------------------------------------|:-----------------------------|:-----|:-----------|
+| `setOpQueueFactory(OperationQueueFactory)`      | Input Queue의 팩토리 객체 설정                     | `ArrayOperationQueueFactory` |      | 크기: 16,384 |
+| `setWriteOpQueueFactory(OperationQueueFactory)` | Write Queue의 팩토리 객체 설정                     | `ArrayOperationQueueFactory` |      | 크기: 16,384 |
+| `setReadOpQueueFactory(OperationQueueFactory)`  | Read Queue의 팩토리 객체 설정                      | `ArrayOperationQueueFactory` |      | 크기: 16,384 |
+| `setOpQueueMaxBlockTime(long)`                  | Input Queue가 가득 찬 상태일 때 유저 스레드가 대기하는 최대 시간 | 10,000                       | ms   |            |
+
+**타임아웃 및 재연결**
+
+| Method                              | Description                              | Default | Unit  | Note                        |
+|:------------------------------------|:-----------------------------------------|:--------|:------|:----------------------------|
+| `setOpTimeout(long)`                | `Future.get()` 호출 시 캐시 서버 응답을 대기하는 최대 시간 | 700     | ms    |                             |
+| `setMaxReconnectDelay(long)`        | 캐시 서버 연결 문제 발생 시 재연결 전 대기 시간             | 1       | s     |                             |
+| `setTimeoutExceptionThreshold(int)` | 재연결 조건 판단 시 연속 Timeout 발생 횟수 임계값         | 10      | count | 최솟값: 2                      |
+| `setTimeoutDurationThreshold(int)`  | 재연결 조건 판단 시 첫 Timeout부터 현재까지의 지속 시간 임계값  | 1,600   | ms    | 0: 비활성화, 제한 범위: 1,000~5,000 |
+| `setKeepAlive(boolean)`             | 캐시 서버와의 TCP KeepAlive 설정                 | false   |       |                             |
+
+**직렬화**
+
+| Method                                        | Description                                        | Default               | Unit | Note |
+|:----------------------------------------------|:---------------------------------------------------|:----------------------|:-----|:-----|
+| `setTranscoder(Transcoder<Object>)`           | Key-Value 타입 캐시 데이터와 Java 객체 간 변환에 사용할 Transcoder  | SerializingTranscoder |      |      |
+| `setCollectionTranscoder(Transcoder<Object>)` | Collection 타입 캐시 데이터와 Java 객체 간 변환에 사용할 Transcoder | SerializingTranscoder |      |      |
+
+**네트워크 및 연결**
+
+| Method                              | Description                                  | Default | Unit  | Note                          |
+|:------------------------------------|:---------------------------------------------|:--------|:------|:------------------------------|
+| `setReadBufferSize(int)`            | 캐시 서버와 소켓 통신 시 사용되는 전역 ByteBuffer 크기         | 16,384  | bytes | 읽기/쓰기 버퍼 모두 이 값을 기준으로 생성됨     |
+| `setDaemon(boolean)`                | Memcached I/O 스레드를 데몬 스레드로 설정                | true    |       | 기본값(true) 유지 권장               |
+| `setUseNagleAlgorithm(boolean)`     | Nagle 알고리즘 사용 여부 (TCP NoDelay 옵션)            | false   |       |                               |
+| `setDelimiter(byte)`                | 캐시 서버 `-D <char>` 옵션으로 지정된 Prefix/Subkey 구분자 | `:`     |       | 서버 옵션과 반드시 일치해야 함             |
+| `setDnsCacheTtlCheck(boolean)`      | 구동 시 DNS 캐시 TTL 검증 활성화 여부                    | true    |       | ZooKeeper를 도메인 주소로 관리하는 경우 유효 |
+| `enableShardKey(boolean)`           | 키의 `{`, `}` 로 감싸진 부분만을 해싱 대상으로 사용            | false   |       |                               |
+| `setAuthDescriptor(AuthDescriptor)` | 캐시 서버 연결 시 SASL 인증을 위한 AuthDescriptor        | null    |       | 현재 `scramSha256` 만 지원         |
+
+**최적화**
+
+| Method                       | Description                                                | Default | Unit | Note   |
+|:-----------------------------|:-----------------------------------------------------------|:--------|:-----|:-------|
+| `setShouldOptimize(boolean)` | Operation Queue 내 연속된 GET 요청을 최대 100개 단위로 조합하여 하나의 요청으로 처리 | false   |      | 사용 비권장 |
+
+**Front Cache**
+
+| Method                          | Description                    | Default | Unit  | Note    |
+|:--------------------------------|:-------------------------------|:--------|:------|:--------|
+| `setMaxFrontCacheElements(int)` | Front Cache에 저장할 수 있는 최대 아이템 수 | 0       | items | 0: 비활성화 |
+| `setFrontCacheExpireTime(int)`  | Front Cache 아이템 만료 시간          | 5       | s     |         |
+
+**Replication (Enterprise Only)**
+
+| Method                                      | Description                         | Default | Unit | Note                       |
+|:--------------------------------------------|:------------------------------------|:--------|:-----|:---------------------------|
+| `setReadPriority(ReadPriority)`             | Replication 환경에서 읽기 요청의 우선순위 설정     | MASTER  |      |                            |
+| `setAPIReadPriority(APIType, ReadPriority)` | Replication 환경에서 API 타입별 읽기 우선순위 설정 | 없음      |      | `setReadPriority`보다 우선 적용됨 |


이미 02 문서에 표가 있는데, 그 표랑 여기 표랑 어떤 차이가 있는건가요?

02-arcus-java-client.md 에 존재하는 표는 "퀵 스타트/한눈에 보기" 목적이라 ArcusClient를 구성할 때 ConnectionFactoryBuilder를 통해 어떤 옵션을 설정할 수 있는지 빠르게 스캔하는 용도의 표입니다.

반면, 13-connection-factory.md 문서에서의 표는 해당 문서로 바로 진입하는 독자들을 대비한 "옵션 요약본" 입니다.
아래에서 옵션별로 상세 설명이 길게 이어지기 때문에, 상단에 목록이 필요하다고 판단했습니다.

자세한 사항은 별도 chapter or section으로 정리할 것이므로, 여기서는 중요 설정만 알려하는 것이 어떤 지 ?

jhpark816 · 2026-02-26T13:01:44Z

방향성만 한번 미리 확인해주시면 좋겠습니다.

방향성 관점은 괜찮은 것 같습니다.
대신, chapter or section 중 어떤 형태가 좋을 지와 어떤 위치가 좋을 지 등이 논의 사항인 것 같고,
검토 후에 의견을 전달하겠습니다.
따라서, 내용 자체에 대해서는 리뷰 진행하면 됩니다.

f1v3-dev · 2026-02-27T09:19:30Z

@jhpark816 @oliviarla

1. ConnectionFactoryBuilder 문서 이동 위치

02-arcus-java-client 문서 내의 ArcusClient 생성 파트에서 ConnectionFactoryBuilder(cfb) 에 대해 아래와 같이 언급하고 있습니다.

### ARCUS Client 생성
// ...
먼저, 단일 ARCUS Client 객체를 생성하기 위한 메소드는 아래와 같다.

ArcusClient.createArcusClient(String arcusAdminAddress, String serviceCode, ConnectionFactoryBuilder cfb)

- arcusAdminAddress: 접근할 cache cloud를 관리하는 ARCUS zookeeper ensemble 주소
  - IP:port 리스트인 "ip1:port,ip2:port,ip3:port" 형태로 지정하거나
  - "FQDN:port" 형태로 지정할 수 있다. (zookeeper IP list에 대한 domain name을 DNS에 등록한 경우)
- serviceCode: 접속할 cache cloud의 식별자
- cfb: ARCUS client의 동작 설정을 위한 ConnectionFactoryBuilder 객체

이 마지막 부분에 아래와 같이 ConnectionFactoryBuilder에 대해 자세히 보고싶은 경우 별도의 문서로 이동시키는 형태는 어떠한가요?

### ARCUS Client 생성
...
- cfb: ARCUS client의 동작 설정을 위한 ConnectionFactoryBuilder 객체

> ConnectionFactoryBuilder에 대한 더 자세한 내용은 해당 문서를 참고한다.

이렇게 작성한 후 02-arcus-java-client.md 문서에서 최하단에 ConnectionFactoryBuilder에 대한 설명은 따로 존재하지 않게 하는게 어떤가 싶습니다.

중요 설정들에 대한 요약들만 별도로 제공하는 경우 중복된 내용이 두 문서(02-arcus-java-client, 13-connection-factory)에 존재하게 되므로 추후 문서에 대한 수정이 필요한 경우 실수로 인해 서로 다른 내용을 포함하게 될 가능성이 존재하다고 보입니다.

2. 설정에 대한 표 형태

현재 임시로 만들어둔 두 가지 표 형태도 생각하는 것 만큼 깔끔하게 보이지 않아 모든 문서에서 없애는 방향이 맞다고 보여집니다.

전체 옵션을 한눈에 보기 위한 것은 존재하지 않게 되지만, 13-connection-factory.md 문서의 목적에 따라 접근할 수 있는 형태이기 때문에 이 부분은 문제 없을 것이라고 보입니다.

DOC: Separate ConnectionFactoryBuilder and Transcoder docs

ad367e5

f1v3-dev requested a review from oliviarla February 26, 2026 12:22

oliviarla reviewed Feb 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Separate ConnectionFactoryBuilder and Transcoder docs#1052

DOC: Separate ConnectionFactoryBuilder and Transcoder docs#1052
f1v3-dev wants to merge 1 commit intonaver:developfrom
f1v3-dev:docs/connection-factory

f1v3-dev commented Feb 26, 2026

Uh oh!

oliviarla left a comment

Uh oh!

oliviarla Feb 26, 2026

Uh oh!

f1v3-dev Feb 27, 2026

Uh oh!

oliviarla Feb 27, 2026

Uh oh!

oliviarla Feb 26, 2026

Uh oh!

f1v3-dev Feb 27, 2026

Uh oh!

jhpark816 Feb 27, 2026 •

edited

Loading

Uh oh!

jhpark816 commented Feb 26, 2026

Uh oh!

f1v3-dev commented Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

f1v3-dev commented Feb 26, 2026

🔗 Related Issue

⌨️ What I did

Uh oh!

oliviarla left a comment

Choose a reason for hiding this comment

Uh oh!

oliviarla Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

f1v3-dev Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

oliviarla Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

oliviarla Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

f1v3-dev Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

jhpark816 Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jhpark816 commented Feb 26, 2026

Uh oh!

f1v3-dev commented Feb 27, 2026

1. ConnectionFactoryBuilder 문서 이동 위치

2. 설정에 대한 표 형태

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jhpark816 Feb 27, 2026 •

edited

Loading