title: 자바 클라이언트

자바에서 바른 사용하기

자바 클라이언트 bareun-client 로 형태소 분석·맞춤법 교정·동형이의어 의미 구분· 우리말샘 음소 검색을 씁니다.

저장소: bareun-java
현재 버전: 2.0.0
자바 17 이상

2.0.0 은 배포 준비 중입니다

Maven Central 에 아직 올라가지 않았습니다. 그전까지는 저장소를 받아 mvn install 로 로컬에 설치해 쓰세요.

이미 배포된 1.4.3(ai.bareun.tagger:bareun)은 형태소 분석과 사용자 사전만 지원합니다. 맞춤법 교정·의미 구분·음소 검색은 2.0.0 부터입니다.

설치

<dependency>
  <groupId>ai.bareun</groupId>
  <artifactId>bareun-client</artifactId>
  <version>2.0.0</version>
</dependency>

implementation 'ai.bareun:bareun-client:2.0.0'

런타임 의존은 protobuf-java 하나뿐입니다.

준비물

실행 중인 바른 서버. 로컬 설치본은 5658, 도커는 5656 이 기본 포트입니다.
API 키. koba- 로 시작합니다. 발급 방법

맞춤법 교정과 우리말샘 음소 검색은 맞춤법 교정 기능이 포함된 서버에서만 됩니다.

형태소 분석

import ai.bareun.client.BareunClient;
import ai.bareun.tagger.Tagger;
import ai.bareun.tagger.Tagged;

BareunClient client = BareunClient.builder()
        .host("localhost").port(5656)
        .apiKey("koba-...")
        .build();

Tagger tagger = new Tagger(client);
Tagged t = tagger.tag("아버지가 방에 들어가신다.");

t.pos();     // [아버지/NNG, 가/JKS, 방/NNG, 에/JKB, 들어가/VV, 시/EP, ㄴ다/EF, ./SF]
t.morphs();  // [아버지, 가, 방, 에, 들어가, 시, ㄴ다, .]
t.nouns();   // [아버지, 방]
t.verbs();   // [들어가]

클라우드에 붙을 때는 주소를 통째로 줍니다.

BareunClient.builder().baseUrl("https://api.bareun.ai").apiKey("koba-...").build();

BareunClient 는 스레드 안전합니다. 하나 만들어 두고 공유하세요.

위치 정보

요청은 UTF-16 오프셋으로 보냅니다. 자바 문자열이 UTF-16 이라, 서버가 준 위치를 substring 에 그대로 넣을 수 있습니다.

var span = t.sentences().get(0).getTokens(0).getText();
text.substring(span.getBeginOffset(), span.getBeginOffset() + span.getLength());
// "아버지가"

여러 문장 한 번에

문장 경계가 이미 정해져 있으면 왕복을 줄일 수 있습니다.

List<Tagged> results = tagger.tagAll(List.of("첫 문장입니다.", "둘째 문장입니다."), false);

사용자 사전

Tagger tagger = new Tagger(client, List.of("mydict"));

사전은 client.customDictionary() 로 만들고 지웁니다. 여럿을 주면 앞에 온 것이 우선합니다. 사용자 사전 API 참고.

맞춤법 교정

import ai.bareun.tagger.Corrector;

Corrector c = new Corrector(client);

c.correct("이거 안되요. 학교에 갔읍니다.");
// "이거 안되요. 학교에 갔습니다."

for (Corrector.Change ch : c.changes("이거 안되요. 학교에 갔읍니다.")) {
    System.out.println(ch.origin() + " → " + ch.revised() + " (" + ch.category() + ")");
}
// 갔읍니다. → 갔습니다. (STANDARD)

Change 의 beginOffset·length 도 자바 문자열 기준이라 substring 에 바로 씁니다. 중첩 교정이나 도움말까지 보려면 c.raw(text) 로 서버 응답을 그대로 받습니다.

자세한 내용은 맞춤법 검사 API 를 보세요.

동형이의어 의미 구분

같은 글자가 여러 뜻을 가질 때 어느 뜻인지 골라 줍니다.

for (Tagged.SenseEntry s : tagger.tag("나는 밤에 밤을 먹었다.", true).senses()) {
    System.out.println(s.morph() + "/" + s.tag() + " " + s.senseNo() + " " + s.meaning());
}
// 밤/NNG 2 밤나무의 열매. ...
// 먹/VV 2 음식 따위를 입을 통하여 뱃속에 들여보내다.

조사·어미처럼 의미를 갖지 않는 형태소에는 원래 붙지 않으므로, 대부분의 형태소는 결과에 나오지 않습니다. 동형이의어 의미 구분 API 참고.

우리말샘 음소 검색

완성형 한글로는 "초성이 ㅅ 이고 종성이 ㄴ 인 음절" 같은 조건을 쓸 수 없습니다.

import ai.bareun.protos.DictSearchAnchor;

client.dictSearch().words("{ㅅ//ㄴ}다", DictSearchAnchor.DICT_SEARCH_ANCHOR_WORD, 10);
// [신다]

client.dictSearch().words("아지", DictSearchAnchor.DICT_SEARCH_ANCHOR_SUFFIX, 5);
// [아지, 가아지, 강아지, 개아지, 갱아지]

패턴 문법은 우리말샘 음소 검색 API 를 보세요.

오류 처리

호출이 실패하면 BareunException 이 나오고, 종류는 ConnectCode 로 가릅니다.

try {
    tagger.tag("문장");
} catch (BareunException e) {
    switch (e.getCode()) {
        case PERMISSION_DENIED -> System.err.println("API 키를 확인하세요");
        case UNAVAILABLE       -> System.err.println("서버 주소·기동 상태를 확인하세요");
        case UNIMPLEMENTED     -> System.err.println("이 서버는 그 기능을 제공하지 않습니다");
        default                -> System.err.println(e.getMessage());
    }
}

코드	언제
`UNAVAILABLE`	서버에 닿지 못함. 주소 오타·미기동·방화벽·시간 초과
`PERMISSION_DENIED`	API 키가 유효하지 않거나 라이선스 만료
`UNIMPLEMENTED`	그 서버가 제공하지 않는 기능. 교정 기능이 없는 서버에 교정을 요청한 경우
`INTERNAL`	서버 내부 오류, 또는 응답을 해석하지 못함

1.x 에서 옮겨오기

2.0.0 은 1.x 와 호환되지 않습니다.

1.x	2.0.0
`ai.bareun.tagger:bareun`	`ai.bareun:bareun-client`
gRPC (`io.grpc` 1.21.0)	Connect (JDK `HttpClient`)
자바 8	자바 17
의존 20여 개	`protobuf-java` 하나
형태소 분석·사용자 사전	+ 교정·의미 구분·음소 검색

LanguageServiceClient 를 직접 만들던 코드는 BareunClient.builder() 로 바꿉니다.

이 라이브러리가 감싸지 않은 기능

client.connect().call(...) 로 서버의 모든 메서드를 직접 부를 수 있습니다.

client.connect().call("bareun.LanguageService", "AnalyzeSyntax", request,
        AnalyzeSyntaxResponse.parser());

스트리밍 교정(StreamCorrectError)은 아직 지원하지 않습니다.

자주 묻는 질문

Q. 자바 8 이나 11 에서 쓸 수 있나요? A. 2.0.0 은 자바 17 이상이 필요합니다. 그보다 낮은 환경에서는 1.4.3 을 쓰되, 맞춤법 교정과 의미 구분은 REST API 로 직접 호출하세요.

Q. 왜 gRPC 를 걷어냈나요? A. Connect 의 단항 호출은 평범한 HTTP POST 라 JDK 의 HttpClient 만으로 됩니다. gRPC 스택은 grpc-netty-shaded·guava 등 20여 개를 함께 들여왔고, 그 버전이 애플리케이션의 다른 라이브러리와 충돌하는 일이 잦았습니다.

Q. 하나의 클라이언트를 여러 스레드가 써도 되나요? A. 됩니다. BareunClient 와 Tagger·Corrector 모두 스레드 안전합니다. 내부 HttpClient 가 연결을 재사용하므로 오히려 하나를 공유하는 편이 낫습니다.