FEATURE: Add CompletableFuture BTree position APIs

[f1v3-dev]

🔗 Related Issue

• https://github.com/jam2in/arcus-works/issues/832#event-23130177064

⌨️ What I did

BTree Position 조회 API 추가

• 특정 element의 위치(position)을 조회하거나, position을 기반으로 element를 조회하는 3가지 API를 구현하였습니다.
  1. bopGetPosition: bKey가 일치하는 element의 position 반환
  2. bopGetByPosition (gbp): 단건 - position에 맞는 element 반환 / 범위 - 범위 내의 Map<position, BTreeElement> 반환
  3. bopPositionWithGet (pwg): 주어진 bKey의 position을 찾고, 해당 position 양쪽으로 count 개씩 인접 element를 함께 반환

작업 특이사항

as-is

• BTreeFindPosition, BTreeFindPositionWithGet은 bKey를 long 또는 byte[] 형태로만 받는 생성자만 존재

to-be

• v2 레이어의 BKey VO를 기존 legacy 클래스에 연결하기 위해 각각 생성자를 추가
  • BTreeFindPosition: String 생성자 추가 → bopGetPosition에서 bKey.toString() 값을 그대로 전달
  • BTreeFindPositionWithGet: BKeyObject를 받는 생성자 추가 + 기존 long/byte[] 생성자는 이를 위임하도록 체이닝
  • BKey: toBKeyObject() 변환 메서드 추가

[oliviarla]

리뷰 완료입니다.

[jhpark816]

리뷰 완료

[jhpark816]

질문입니다.
아래 결과를 리턴하는 것을 어떻게 생각하나요?

• List<BTreeElement<T>>

아래와 같이 처리할 수 있는 데요.

• from ~ to 범위의 elements가 모두 있으면 이를 그대로 리턴
• from에서 to 이전의 elements만 있으면 이를 그대로 리턴
  • 1 ~ 5 까지의 요청인데, 4까지 elements만 있다면 4개만 리턴
• from에 해당하는 elements가 없다면 오류 리턴

어떤 응답 결과가 응용에 유용하고 처리가 간단한 지 검토 바랍니다.
참고로, Map으로 리턴하면, 위의 3번째 경우에도 응답을 줄 수 있습니다.

[f1v3-dev]

제 생각에는 Map을 유지하여 키 값에 담기는 position 정보가 있어야한다고 보여집니다.

API의 네이밍부터 bopGetByPosition 처럼 position을 통해 데이터를 가져오는 형태인데, 결과에서 position 정보가 사라지는 형태는 맞지 않다고 보여집니다.

또한 아래와 같은 상황에서 혼란을 방지해야한다고 생각합니다.

// from: 100, to: 200 인 상황
// 150번 째 값을 찾길 원하는 상황인 경우
async.bopGetByPosition(key, 100, 200, BTreeOrder.ASC);

// 1. List 형태
list.get(50); // <- 50번 째 값 = 150번 째 (?)

// 2. Map 형태
map.get(150); // <- 150번 쨰 값

위와 같이 명확하게 몇 번째 값을 원하는지 표시하는 것이 사용자 입장에서 더 직관적으로 보일 것이라고 생각합니다.

[jhpark816]

B+Tree elements 조회하기 위해, bkey range 조건 or position range 조건을 줄 수 있습니다.
각 경우의 기존 API를 확인해 보니, 리턴 타입이 아래와 같네요.

• bkey range 조건
  • Map<Long, Element<Object>
  • Map<ByteArrayBKey, Element<Object>>
• position range 조건
  • Map<Integer, Element<Object>>

v2에서도 위와 동일하게 리턴하는 거죠?

[f1v3-dev]

v2도 동일한 데이터를 반환하지만, 데이터를 담는 클래스가 다릅니다.

BKey 범위 조건

• v1: Map<Long / ByteArrayBKey, Element<Object>>
• v2: BTreeElements<T> (List 기반 wrapper, 각 BTreeElement가 bKey, value, eFlag 보유)

Position 범위 조건

• v1: Map<Integer, Element<Object>>
• v2: Map<Integer, BTreeElement<T>> (Map 구조 유지, value 타입만 변경)

[jhpark816]

B+Tree elements 조회하기 위해, bkey range 조건 or position range 조건을 줄 수 있습니다.
단지 조회 조건만 다른 것이며, 서버에서 조회한 결과는 동일하게 응답합니다.

따라서, 클라이언트에서도 동일하게 맞추면 좋겠습니다.
v2에서 두 경우 동일하게 BTreeElements<T> 리턴하도록 맞추는 것이 좋겠습니다.

[jhpark816]

여기도 질문입니다.

• 주어진 bKey에 대한 position은 Map 결과에서 어떻게 확인할 수 있나요?
• 해당 position의 앞뒤에 몇 개의 elements가 있는 지를 어떻게 확인하나요?

[f1v3-dev]

주어진 bKey에 대한 position은 Map 결과에서 어떻게 확인할 수 있나요?

현재는 요청한 bKey에 대한 position을 확인할 수 있는 방법이 존재하지 않습니다.

해당 position의 앞 뒤에 몇 개의 elements..

현재는 따로 제공해주지 않지만, 반환하는 Map의 size를 통해 앞뒤 elements의 합산 개수는 파악할 수 있습니다. 다만 앞에 몇 개, 뒤에 몇 개인지는 확인할 수 없습니다

---

말씀해주신 두 가지에 대한 정보가 필요하다면, 아래와 같은 vo로 설계하여 제공할 수 있을 것 같습니다.

public class BopPositionWithGetResult<T> {
    private final int position;  // 조회한 bKey의 position
    private final Map<Integer, BTreeElement<T>> elements;  // 주변 elements
}

// Callback ...
BTreeFindPositionWithGetOperation.Callback cb 
    = new BTreeFindPositionWithGetOperation.Callback() {

   @Override
    public void gotData(int pos, int flags, BKeyObject bKeyObj, byte[] eFlag, byte[] data) {
      result.get().getElements().put(pos, buildBTreeElement(flags, bKeyObj, eFlag, data));
      if (BKey.of(bKeyObj).equals(bKey)) {
        result.get().setPosition(pos);  // 조회한 bKey의 position 기록
      }
    }

  //...

}

[jhpark816]

기존 API를 보니 아래 타입을 리턴하고 있고, v2에서도 동일하게 맞추려는 것이네요.

• Map<Integer, Element<Object>>

@oliviarla
어떤 타입의 리턴 값을 리턴하는 것이 좋은 지 의견 주세요.

[oliviarla]

의견입니다.

• 캐시 서버 응답에서는 bkey 위치의 position, index과 element 목록을 반환함
• 클라이언트 응답에서는 position을 계산하여 포함한 element 목록을 반환함
• 위에서 제안한 VO와 같이 bkey 위치의 position을 함께 반환하면 충분할 것으로 보임
• Map을 LinkedHashMap으로 반환하여 position 순서대로 조회할 수 있게 하면 좋을 것 같음