드라이버 버전 업그레이드

버전 5.0 주요 변경 사항

이 드라이버 버전에는 다음과 같은 호환성이 손상되는 변경이 도입되었습니다.

• ConnectionId 클래스에 다음과 같은 변경 사항을 도입합니다.

  • ConnectionId 생성자는 이제 두 번째 매개 변수로 int 유형 대신 long 유형의 값을 허용합니다. 마찬가지로, 생성자는 이제 세 번째 매개 변수로 Integer 유형 대신 Long 유형의 값을 허용합니다. 이 변경으로 인해 바이너리 호환성이 중단되므로 ConnectionId 생성자를 호출하는 모든 기존 코드를 다시 컴파일합니다.

  • withServerValue() 메서드는 이제 int 유형이 아닌 long 유형의 매개변수를 허용합니다. 이 변경으로 인해 바이너리 호환성이 중단되므로 withServerValue() 메서드를 호출하는 모든 코드를 다시 컴파일해야 합니다.

  • getServerValue() 메서드는 이제 Integer 유형 대신 Long 유형의 값을 반환합니다. 마찬가지로 getLocalValue() 메서드는 int 유형 대신 long 유형의 값을 반환합니다. 이 변경으로 인해 바이너리 및 소스 호환성이 모두 중단되므로 이러한 메서드를 사용하는 모든 소스 코드를 업데이트하고 바이너리를 다시 빌드하세요.

• org.bson.codecs.record.annotations 패키지의 다음 레코드 주석을 org.bson.codecs.pojo.annotations 패키지의 동일한 이름의 주석으로 대체합니다.

  • BsonId

  • BsonProperty

  • BsonRepresentation

• SocketSettings.Builder.connectTimeout() 및 SocketSettings.Builder.readTimeout() 메서드에서 시간 초과 기간 매개변수의 데이터 유형을 변경합니다. 이 매개변수의 데이터 유형은 이제 long int 입니다.

  이전 버전에서 이 매개변수는 두 메서드 모두에서 int 유형입니다. 이 변경으로 인해 바이너리 호환성이 중단되어 다시 컴파일해야 하지만 코드를 변경할 필요는 없습니다. SocketSettings 메서드를 호출하는 방법을 보여주는 예제를 보려면 MongoClient 설정 지정 가이드의 SocketSettings 예제 를 참조하세요.

• 벡터 검색을 수행할 때 동일성 필터를 구성할 수 있도록 하는 Beta 독점으로 릴리스된 Filters.eqFull() 메서드를 제거합니다. 다음 코드와 같이 VectorSearchOptions 유형을 인스턴스화할 때 Filters.eq() 메서드를 사용할 수 있습니다.

  VectorSearchOptions opts = vectorSearchOptions().filter(eq("x", 8));

• org.mongodb.scala.ObservableImplicits.ToSingleObservableVoid 암시적 클래스를 제거합니다. 이는 org.reactivestreams.Publisher[Void] 유형이 더 이상 org.mongodb.scala.SingleObservable[Void] 로 자동으로 변환되지 않음을 의미합니다. 또한 API는 org.mongodb.scala.Observable[Void] org.mongodb.scala.Observable[Unit] 을(를) 노출합니다.

  자세한 내용은 Scala API 문서의 관찰 가능 특성을 참조하세요.

• ClusterSettings 가 ClusterConnectionMode 을 계산하는 방식을 변경하여, 구성 방식에 관계없이 지정된 복제본 세트 이름을 사용하여 더 일관성을 유지합니다. 이전에는 복제본 세트 이름이 연결 문자열로 설정된 경우에만 고려되었습니다.

  예를 들어 다음 두 코드 샘플은 모두 ClusterConnectionMode.MULTIPLE 값을 반환하지만, 이전에는 두 번째 샘플은 ClusterConnectionMode.SINGLE 을 반환했습니다.

  ClusterSettings.builder()
      .applyConnectionString(new ConnectionString("mongodb://127.0.0.1:27017/?replicaSet=replset"))
      .build()
      .getMode()

  ClusterSettings.builder()
      .hosts(Collections.singletonList(
              new ServerAddress("127.0.0.1", 27017)
      ))
      .requiredReplicaSetName("replset")
      .build()
      .getMode()

• Decimal128 값과 동일한 방식으로 응답하여 BsonDecimal128 값이 메서드 호출에 응답하는 방식을 변경합니다. 특히 BsonDecimal128.isNumber() 는 이제 true 을 반환하고 BsonDecimal128.asNumber() 는 이에 상응하는 BsonNumber 를 반환합니다.

• ServerAddress 메서드 getSocketAddress() 및 getSocketAddresses()(을)를 제거합니다.

  getSocketAddress() 대신 java.net.InetAddress의 getByName() 인스턴스 메서드를 사용합니다.

  getSocketAddresses() 대신 java.net.InetAddress의 getAllByName() 인스턴스 메서드를 사용합니다.

• UnixServerAddress 메서드 getSocketAddress() 및 getUnixSocketAddress()를 제거합니다.

  getUnixSocketAddress() 대신 jnr.unixsocket.UnixSocketAddress의 인스턴스를 구성합니다. 생성자에 UNIX 소켓 파일의 전체 경로를 전달합니다. 기본적으로 MongoDB는 "/tmp/mongodb-27017.sock"에 UNIX 소켓 파일을 생성합니다. UnixSocketAddress에 대한 자세한 내용은 UnixSocketAddress API 문서에서 확인하세요.

• Parameterizable 인터페이스를 제거합니다. 사용자 지정 Codec 유형에서 이 인터페이스를 구현하는 대신 코덱이 매개변수화된 유형에 대해 의도된 경우 코덱의 CodecProvider 에서 CodecProvider.get() 메서드를 재정의합니다.

• ReadPreference 및 TaggableReadPreference 클래스에서 isSlaveOk() 메서드를 제거합니다. 읽기 설정 (read preference)이 복제본 세트의 세컨더리 멤버에서 읽기를 허용하는지 확인하려면 이러한 클래스의 isSecondaryOk() 메서드를 대신 사용합니다.

• collStats 명령에 대한 DBCollection.getStats() 및 DBCollection.isCapped() 헬퍼 메서드를 제거합니다. 이러한 메서드 대신 $collStats 집계 파이프라인 단계를 사용할 수 있습니다. 이 파이프라인 단계를 사용하는 방법에 대한 예는 4 내 새로운 기능을 참조하십시오.Java 드라이버용 11.

• MapCodec 및 IterableCodec 클래스를 제거합니다. MapCodec 대신 MapCodecProvider 을 사용합니다. IterableCodec 대신 Collection Iterable 유형의 경우 CollectionCodecProvider 또는 IterableCodecProvider 를 사용합니다.

• MapReducePublisher 및 MapReduceIterable 클래스에서 sharded() 및 nonAtomic() 메서드를 제거합니다.

• geoHaystack 인덱스와 함께 사용할 수 있도록 다음 메서드를 제거합니다.

  • Indexes.geoHaystack()

  • IndexOptions.getBucketSize()

  • IndexOptions.bucketSize()

  대신 2d 인덱스에서 $geoNear 집계 파이프라인 단계 또는 지리 공간적 쿼리 연산자를 사용할 수 있습니다. 자세한 내용은 MongoDB Server 매뉴얼의 지리 공간적 쿼리 페이지를 참조하세요.

• 찾기 작업에서 oplogReplay 옵션을 제거합니다. 여기에는 다음 메서드가 포함됩니다:

  • DBCursor.oplogReplay()

  • DBCollectionFindOptions.isOplogReplay()

  • DBCollectionFindOptions.oplogReplay()

  • FindPublisher.oplogReplay()

  • FindIterable.oplogReplay()

• 다음 Exception 생성자를 제거합니다.

  • MongoBulkWriteException(BulkWriteResult, List<BulkWriteError>, WriteConcernError, ServerAddress)

  • MongoCursorNotFoundException(long, ServerAddress)

  • MongoQueryException(ServerAddress, int, String)

  • MongoQueryException(ServerAddress, int, String, String)

  • MongoQueryException(MongoCommandException)

• BulkWriteResult.acknowledged() 메서드에 대한 다음 오버로드를 제거합니다:

  • acknowledged(Type, int, List<BulkWriteUpsert>)

  • acknowledged(Type, int, Integer, List<BulkWriteUpsert>)

  • acknowledged(int, int, int, Integer, List<BulkWriteUpsert>)

• 다음 ChangeStreamDocument 생성자를 제거합니다.

  • ChangeStreamDocument(String, BsonDocument, BsonDocument, BsonDocument, TDocument, TDocument, BsonDocument, ...)

  • ChangeStreamDocument(String, BsonDocument, BsonDocument, BsonDocument, TDocument, BsonDocument, BsonTimestamp, ...)

  • ChangeStreamDocument(OperationType, BsonDocument, BsonDocument, BsonDocument, TDocument, BsonDocument, BsonTimestamp, ...)

• 이벤트에 대한 다음 생성자를 제거합니다:

  • CommandEvent(RequestContext, int, ConnectionDescription, String)

  • CommandEvent(int, ConnectionDescription, String)

  • CommandEvent(RequestContext, long, int, ConnectionDescription, String)

  • CommandFailedEvent(RequestContext, int, ConnectionDescription, String, long, Throwable)

  • CommandFailedEvent(int, ConnectionDescription, String, long, Throwable)

  • CommandStartedEvent(RequestContext, int, ConnectionDescription, String, String, BsonDocument)

  • CommandStartedEvent(int, ConnectionDescription, String, String, BsonDocument)

  • CommandSucceededEvent(RequestContext, int, ConnectionDescription, String, BsonDocument, long)

  • CommandSucceededEvent(int, ConnectionDescription, String, BsonDocument, long)

  • ConnectionCheckedInEvent(ConnectionId)

  • ConnectionCheckedOutEvent(ConnectionId, long)

  • ConnectionCheckedOutEvent(ConnectionId)

  • ConnectionCheckOutFailedEvent(ServerId, long, Reason)

  • ConnectionCheckOutFailedEvent(ServerId, Reason)

  • ConnectionCheckOutStartedEvent(ServerId)

  • ConnectionReadyEvent(ConnectionId)

  • ServerHeartbeatFailedEvent(ConnectionId, long, Throwable)

  • ServerHeartbeatSucceededEvent(ConnectionId, BsonDocument, long)

• WriteConcernError 클래스에서 errorLabels 옵션을 제거합니다. 여기에는 addLabel() 및 getErrorLabels() 메서드와 errorLabels 매개 변수를 포함하는 생성자가 포함됩니다. 대신 WriteConcernError 이 포함된 MongoException 객체에 포함된 오류 레이블을 사용할 수 있습니다.

• com.mongodb.event 패키지에서 다음 클래스를 제거합니다.

  • ConnectionAddedEvent

  • ConnectionPoolOpenedEvent

  • ConnectionRemovedEvent

  • ClusterListenerAdapter

  • ConnectionPoolListenerAdapter

  • ServerListenerAdapter

  • ServerMonitorListenerAdapter

  이러한 제거로 인해 다음 메서드도 ConnectionPoolListener 인터페이스에서 제거되었습니다.

  • connectionAdded

  • connectionPoolOpened

  • connectionRemoved

  이벤트 패키지에 대한 자세한 내용은 com.mongodb.event 패키지 문서를 참조하세요.

• listCollections 명령의 새로운 authorizedCollection 옵션에 대한 지원을 추가합니다. 이로 인해 MongoDatabase.listCollectionNames() 메서드에 호환성이 손상되는 바이너리 변경이 도입되며, 이는 이러한 메서드를 사용하는 모든 코드를 다시 컴파일해야 함을 의미합니다. 이 변경으로 인해 소스 코드를 변경할 필요는 없습니다.

• 스트림 인터페이스와 관련된 다음 메서드 및 유형을 제거합니다.

  • streamFactoryFactory() MongoClientSettings.Builder 의 메서드. 대신 MongoClientSettings.Builder.transportSettings() 메서드를 사용합니다.

  • getStreamFactoryFactory() MongoClientSettings 의 메서드. 대신 MongoClientSettings.getTransportSettings() 메서드를 사용합니다.

  • NettyStreamFactoryFactory 클래스입니다. TransportSettings.nettyBuilder() 로 생성 가능하고 MongoClientSettings.Builder.transportSettings() 를 통해 적용되는 NettyTransportSettings 을 사용합니다.

  • NettyStreamFactory 클래스

  • AsynchronousSocketChannelStreamFactory 클래스

  • AsynchronousSocketChannelStreamFactoryFactory 클래스

  • BufferProvider 인터페이스

  • SocketStreamFactory 클래스

  • Stream 인터페이스

  • StreamFactory 인터페이스

  • StreamFactoryFactory 인터페이스

  • TlsChannelStreamFactoryFactory 클래스

버전 4.8 긴급 변경 사항

• 드라이버는 MongoDB Server 버전 v3.4 및 이전 버전에 대한 연결 지원을 종료합니다. 이 변경 사항에 대해 자세히 알아보려면 드라이버 버전 4.8 서버 지원 변경 섹션을 참조하세요.

• 애플리케이션이 OSGi 컨테이너에 드라이버를 배포하고 Java 레코드의 인코딩 및 디코딩을 위해 드라이버를 사용하는 경우 org.bson.codecs.record 모듈에 대한 명시적 종속성을 추가해야 합니다.

• v4.6에서 구현된 RecordCodec은 레코드의 List 또는 Map 필드의 유형 매개 변수로 지정된 POJO 및 레코드 클래스를 해당 클래스 대신 Document 값으로 역직렬화했습니다. 이 버전에서는 이제 적절한 레코드 및 POJO 유형으로 역직렬화합니다.

  예를 들어, 다음 레코드 클래스 정의는 Chapter 유형 매개 변수를 받는 List가 포함된 Book 레코드를 보여줍니다.

  public record Book(String title, List<Chapter> chapters) {}
  public record Chapter(Integer number, String text) {}

  이 버전부터 코덱은 List의 데이터를 Document 값 대신 Chapter 레코드 클래스로 역직렬화합니다.

버전 4.7 주요 변경 사항

• setWindowFields 빌더 API는 더 이상 베타 버전이 아닙니다. 새 빌더는 바이너리 및 소스 호환성을 손상시킵니다. Aggregates API 문서에서 새로운 setWindowFields() 메서드 시그니처 정보를 확인하세요.

  애플리케이션이 v4.7 이전 버전에서 이 빌더를 사용하는 경우 새 메서드 서명을 사용하도록 소스 코드를 업데이트하고 바이너리를 다시 빌드하세요.

버전 4.2 주요 변경 사항

• 다양한 버전의 드라이버에서 직렬화 호환성 문제를 최소화하는 새 형식을 사용하도록 ObjectId 클래스와 해당 serialVersionUID 필드가 업데이트됐습니다.

  이 버전 이상의 드라이버를 사용하는 애플리케이션에서 ObjectId가 포함되어 있고 이전 버전의 드라이버에서 직렬화된 객체에 대해 Java 객체 직렬화를 수행하려고 하면 Java에서 InvalidClassException을 발생시킵니다.

  Java 객체 직렬화에 대해 자세히 알아보려면 직렬화 가능한 객체에 대한 Java 문서를 참조하세요.

버전 4.0 주요 변경 사항

• 3.12 릴리스에서 더 이상 사용되지 않는 것으로 표시된 여러 클래스와 메서드가 이 버전에서 제거됐습니다.

• 삽입 헬퍼 메서드는 void 대신 삽입 결과 객체를 반환합니다.

• BsonDocument, Document 및 DbObject의 toJson() 메소드는 엄격한(strict) JSON 형식 대신 완화된(relaxed) JSON 형식을 반환합니다. 이렇게 하면 JSON 문서의 가독성이 높아지지만 32비트와 64비트 정수의 차이와 같이 BSON 유형 정보를 식별하기가 더 어려워질 수 있습니다. 애플리케이션이 엄격한 JSON 형식을 사용하는 경우 데이터를 읽거나 쓸 때 엄격(strict) 모드를 사용하세요. 문서 데이터 형식: 확장 JSON 가이드를 참조해 현재 API에서 JSON 형식을 지정하는 방법을 알아보세요.

• java.util.UUID 값의 기본 BSON 표현이 JAVA_LEGACY에서 UNSPECIFIED로 변경되었습니다. UUID 값을 저장하거나 검색하는 애플리케이션은 사용할 표현을 명시적으로 지정해야 합니다. MongoClientSettings의 uuidRepresentation 속성에서 표현을 지정할 수 있습니다.

  지정하는 UUID 표현은 드라이버가 UUID를 디코딩하는 방법을 엄격하게 제어합니다. 이전 버전의 드라이버에서는 JAVA_LEGACY 표현을 지정한 경우 드라이버가 하위 유형 3 및 4의 바이너리 객체를 UUID로 디코딩했습니다. 버전 4.0에서 JAVA_LEGACY 표현은 하위 유형 3에서만 작동합니다.

  UuidRepresentation 열거형 노드 목록은 v4.0 API 문서를 참조하세요.

• 연결 풀은 더 이상 MongoDB에 연결해야 하는 대기 큐 스레드 또는 비동기 작업의 수를 제한하지 않습니다. 애플리케이션은 드라이버에 의존하여 MongoWaitQueueFullException을 발생시키는 대신 필요에 따라 요청을 제한해야 합니다.

• 드라이버는 더 이상 java.util.logging(JUL) 패키지를 사용하여 로깅하지 않으며 SLF4J 로깅 프레임워크만 지원합니다.

• 내장된 드라이버와 Android 드라이버가 제거되었습니다. 애플리케이션에서 이러한 드라이버를 사용하는 경우 3.x Java 드라이버 버전을 계속 사용해야 합니다.

• Uber JAR인 mongo-java-driver 및 mongodb-driver는 더 이상 출시되지 않습니다. 애플리케이션이 이들 중 하나를 사용하는 경우 애플리케이션에서 사용하는 API에 따라 mongodb-driver-sync 또는 mongodb-driver-legacy 중 하나로 전환해야 합니다. 종속 항목에서 uber JAR을 제거해야 합니다.

• 여러 클래스를 업데이트하면서 삽입 헬퍼 메서드에 대한 메서드 시그니처 변경과 같은 이진 호환성 문제가 발생했습니다. 이 버전 이상에 대해 드라이버에 연결되는 모든 클래스를 다시 컴파일하여 계속 작동하는지 확인하세요.

서버 버전 8.1 지원 변경 사항

3.x 버전의 Java 드라이버를 사용하여 MongoDB Server v8.1 을 실행하는 배포에 연결할 수 없습니다. MongoDB Server v8.1 부터 buildinfo 명령에 인증이 필요하여 v3.x 드라이버와 호환되지 않습니다.

드라이버 버전 4.8 서버 지원 변경 사항

v4.8 드라이버는 MongoDB Server v3.4 및 이전 버전에 대한 지원을 중단합니다. v4.8 드라이버를 사용하려면 MongoDB Server는 v3.6 및 이후 버전이어야 합니다. MongoDB Server 배포를 업그레이드하는 방법을 알아보려면 MongoDB Server 매뉴얼의 릴리스 노트를 참조합니다.