개요
이 섹션에서는 운전자 를 새 버전으로 업그레이드 하기 위해 애플리케이션 에 적용해야 하는 변경 사항을 확인할 수 있습니다.
업그레이드하기 전에 다음 작업을 수행하세요:
새 운전자 버전이 애플리케이션 연결되는 MongoDB Server 버전 및 애플리케이션 실행되는 Java 런타임 환경(JRE)과 호환되는지 확인하세요. 호환성 정보를 보려면 호환성 페이지를 참조하세요.
애플리케이션 에서 사용 중인 운전자 의 현재 버전과 업그레이드 예정 버전 간의 호환성이 손상되는 변경은 호환성이 손상되는 변경 섹션에서 확인하세요. MongoDB Server 출시하다 호환성 변경 사항에 대해 자세히 학습 서버 릴리스 호환성 변경 사항 섹션을 참조하세요.
팁
향후 운전자 버전을 업그레이드 때 애플리케이션 필요한 변경 사항을 최소화하려면 Stable API 사용하세요.
호환성이 손상되는 변경
호환성이 손상되는 변경은 업그레이드하기 전에 해결하지 않으면 애플리케이션이 제대로 작동하지 않을 수 있는 특정 버전의 드라이버 규칙이나 동작의 수정입니다.
이 섹션의 호환성이 손상되는 변경은 이를 도입한 운전자 버전별로 분류됩니다. 운전자 버전을 업그레이드할 때 현재 버전과 업그레이드 버전 간의 호환성이 손상되는 변경을 모두 주소 . 예시 를 들어 운전자 v4.0 에서 v4.7로 업그레이드하는 경우 v4.0 이후 버전의 모든 호환성이 손상되는 변경을 주소 . v4.7에 나열된 모든 항목을 포함합니다.
버전 5.5 호환성이 손상되는 변경
운전자 더 이상 MongoDB Server 버전 4.0과 호환되지 않습니다. 이 변경 사항에 대해 자세히 학습하려면 드라이버 버전 5.5 서버 지원 변경 섹션을 참조하세요.
버전 5.2 호환성이 손상되는 변경
이 드라이버 버전에는 다음과 같은 호환성이 손상되는 변경이 도입되었습니다.
MongoDB Server v3.6에 대한 지원 중단합니다. 이 변경 사항에 대해 자세히 학습 5.2 드라이버 버전 서버 지원 변경 섹션을 참조하세요.
JVM 드라이버의 버전 관리와 일치하도록 mongodb-crypt 종속성 버전 관리를 수정합니다.
mongodb-crypt
의 향후 버전은 운전자 와 함께 출시될 예정이며 동일한 버전 번호를 주식 합니다.mongodb-crypt
종속성을 v5로 업그레이드 해야 합니다.2.0 이 출시하다 의 운전자 업그레이드할 때 .
버전 5.1 호환성이 손상되는 변경
이 드라이버 버전에는 다음과 같은 호환성이 손상되는 변경이 도입되었습니다.
MONGODB-OIDC
인증 메커니즘 을 사용하는 경우authMechanismProperties
연결 string 값에 쉼표 문자를 포함하지 않아야 합니다.
버전 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()
메서드에 대한connectTimeout
시간 초과 기간 매개변수의 데이터 유형 변경합니다. 이 매개변수의 데이터 유형 이제int
대신long
입니다.이전 버전에서 이 매개변수는 두 메서드 모두에서
int
유형입니다. 이 변경은 바이너리 호환성을 깨고 다시 컴파일해야 하지만 코드를 변경할 필요는 없습니다.벡터 검색 수행할 때 동일성 필터하다 구성할 수 있도록
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() BsonDecimal128
값은Decimal128
값과 동일한 방식으로 메서드 호출에 응답합니다. 이제BsonDecimal128.isNumber()
는true
를 반환하고BsonDecimal128.asNumber()
는 이에 상응하는BsonNumber
를 반환합니다.ServerAddress 메서드
getSocketAddress()
및getSocketAddresses()
(을)를 제거합니다.getSocketAddress()
대신java.net.InetAddress
의getByName()
인스턴스 메서드를 사용합니다.getSocketAddresses()
대신java.net.InetAddress
의getAllByName()
인스턴스 메서드를 사용합니다.UnixServerAddress 메서드
getSocketAddress()
및getUnixSocketAddress()
를 제거합니다.getSocketAddress()
대신java.net.InetAddress
의getByName()
인스턴스 메서드를 사용합니다.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
집계 파이프라인 단계를 사용할 수 있습니다.MapCodec
및IterableCodec
클래스를 제거합니다.MapCodec
대신MapCodecProvider
을 사용합니다.IterableCodec
대신Collection
Iterable
유형의 경우CollectionCodecProvider
또는IterableCodecProvider
를 사용합니다.MapReducePublisher
및MapReduceIterable
클래스에서sharded()
및nonAtomic()
메서드를 제거합니다.geoHaystack
인덱스와 함께 사용할 수 있도록 다음 메서드를 제거합니다.Indexes.geoHaystack()
IndexOptions.getBucketSize()
IndexOptions.bucketSize()
대신 2d 인덱스에서
$geoNear
집계 파이프라인 단계 또는 지리 공간적 쿼리 작업자를 사용할 수 있습니다. 자세한 내용은 MongoDB Server 매뉴얼의 Geospatial Queries(지리 공간적 쿼리) 페이지를 참조하세요.찾기 작업에서
oplogReplay
옵션을 제거합니다. 다음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
내용은 API 설명서를 참조하세요.
listCollections
명령에authorizedCollection
옵션을 추가합니다. 이로 인해MongoDatabase.listCollectionNames()
메서드에 호환성이 손상되는 바이너리 변경이 도입됩니다. 이 변경으로 인해 소스 코드 변경할 필요는 없지만 이 메서드를 사용하는 모든 코드를 다시 컴파일해야 합니다.스트림 인터페이스와 관련된 다음 메서드 및 유형을 제거합니다.
MongoClientSettings.Builder.streamFactoryFactory()
메서드. 대신MongoClientSettings.Builder.transportSettings()
메서드를 사용합니다.MongoClientSettings.getStreamFactoryFactory()
메서드. 대신MongoClientSettings.getTransportSettings()
메서드를 사용합니다.NettyStreamFactoryFactory
클래스. 대신TransportSettings.nettyBuilder()
메서드를 호출하여NettyTransportSettings
객체 만듭니다. 그런 다음MongoClientSettings.Builder.transportSettings()
메서드를 호출하여 설정을 적용 .NettyStreamFactory
클래스.AsynchronousSocketChannelStreamFactory
클래스.AsynchronousSocketChannelStreamFactoryFactory
클래스.BufferProvider
인터페이스.SocketStreamFactory
클래스.Stream
인터페이스.StreamFactory
인터페이스.StreamFactoryFactory
인터페이스.TlsChannelStreamFactoryFactory
클래스.
버전 4.8 호환성이 손상되는 변경
이 드라이버 버전에는 다음과 같은 호환성이 손상되는 변경이 도입되었습니다.
MongoDB Server 버전 v3.4 및 이전 버전에 대한 연결 지원 종료합니다. 이 변경 사항에 대해 자세히 학습 4.8 드라이버 버전 서버 지원 변경 섹션을 참조하세요.
애플리케이션 이 OSGi 컨테이너 에 운전자 배포하고 Java 레코드의 인코딩 및 디코딩을 위해 운전자 사용하는 경우
org.bson.codecs.record
모듈에 대한 명시적 종속성을 추가해야 합니다.RecordCodec
List
또는Map
필드의 유형 매개변수로 지정된 POJO 및 기록 클래스를 적절한 기록 및 POJO 유형으로 역직렬화합니다. 이전에는 이 코덱이 이를Document
값으로 역직렬화했습니다.예를 들어, 다음 레코드 클래스 정의는
Chapter
유형 매개 변수를 받는List
가 포함된Book
레코드를 보여줍니다.public record Book(String title, List<Chapter> chapters) {} public record Chapter(Integer number, String text) {} 이 버전부터 코덱은
List
의 데이터를Document
값 대신Chapter
레코드 클래스로 역직렬화합니다.
버전 4.7 호환성이 손상되는 변경
이 드라이버 버전에는 다음과 같은 호환성이 손상되는 변경이 도입되었습니다.
버전 4.2 호환성이 손상되는 변경
이 드라이버 버전에는 다음과 같은 호환성이 손상되는 변경이 도입되었습니다.
다양한 버전의 운전자 에서 직렬화 호환성 문제를 최소화하는 새로운 형식을 사용하도록
ObjectId
클래스와 해당serialVersionUID
필드 업데이트합니다.운전자 버전 4.2 이상을 사용하는 애플리케이션
ObjectId
포함되어 있고 이전 버전의 운전자 에 의해 직렬화된 객체에 대해 Java 객체 직렬화 수행하려고 하면 JavaInvalidClassException
을 발생시킵니다.Java 객체 직렬화 에 대해 자세히 학습 Java 문서에서 직렬화 가능한 객체를 참조하세요.
버전 4.0 호환성이 손상되는 변경
이 드라이버 버전에는 다음과 같은 호환성이 손상되는 변경이 도입되었습니다.
3.12 출시하다 에서 더 이상 사용되지 않는 것으로 표시된 여러 클래스와 메서드를 제거합니다.
삽입 헬퍼 메서드를 수정하여
void
대신InsertOneResult
또는InsertManyResult
객체 반환합니다.BsonDocument
,Document
및DbObject
클래스의toJson()
메서드를 수정하여 엄격한 JSON 형식 대신 완화된 JSON 형식을 반환합니다. 이렇게 하면 JSON 문서의 가독성이 높아지지만 32비트와 64비트 정수의 차이와 같은 BSON 유형 정보를 식별하기가 더 어려워질 수 있습니다. 애플리케이션 엄격한 JSON 형식을 사용하는 경우 데이터를 읽거나 쓸 때 엄격 모드 사용하세요.java.util.UUID
값의 기본값 BSON 표현을JAVA_LEGACY
에서UNSPECIFIED
로 변경합니다. UUID 값을 저장 하거나 조회 하는 애플리케이션은 사용할 표현을 명시적으로 지정해야 합니다.MongoClientSettings
객체 의uuidRepresentation
속성 에서 표현을 지정할 수 있습니다.지정하는 UUID 표현은 운전자 UUID를 디코딩하는 방법을 엄격하게 제어합니다. 버전 4.0에서
JAVA_LEGACY
표현은 하위 유형 3에서만 작동합니다. 이전 버전의 운전자 에서는JAVA_LEGACY
표현을 지정한 경우 운전자 하위 유형 3 및 4 의 바이너리 객체를 UUID로 디코딩했습니다.UuidRepresentation
열거형 노드 목록은 v4.0 API 문서를 참조하세요.연결 풀 더 이상 MongoDB 에 대한 연결이 필요한 대기열 스레드 또는 비동기 작업 수를 제한하지 않습니다. 애플리케이션 운전자 에 의존하여
MongoWaitQueueFullException
을 발생시키는 대신 필요에 따라 요청을 제한합니다.운전자 더 이상
java.util.logging
패키지 사용하여 로깅하지 않으며 SLF4J 로깅 프레임워크 만 지원합니다.내장된 드라이버와 Android 드라이버가 제거되었습니다. 애플리케이션에서 이러한 드라이버를 사용하는 경우 3.x Java 드라이버 버전을 계속 사용해야 합니다.
Java 운전자
mongo-java-driver
및mongodb-driver
에 대한 uber JAR은 더 이상 게시되지 않습니다. 애플리케이션 이러한 uber JAR을 사용하는 경우 종속성을 제거 하고 다음 패키지 중 하나를 대신 사용하세요.애플리케이션 현재 API 사용하는 경우
mongodb-driver-sync
패키지 종속성으로 추가합니다.애플리케이션 레거시 API 사용하는 경우
mongodb-driver-legacy
패키지 종속성으로 추가합니다.
여러 클래스에서 삽입 헬퍼 메서드에 대한 메서드 시그니처 변경과 같은 이진 호환성 문제가 발생합니다. 이 버전 이상에 대해 운전자 에 연결되는 모든 클래스를 다시 컴파일하여 계속 작동하는지 확인합니다.
서버 릴리스 호환성 변경 사항
서버 출시하다 호환성 변경은 MongoDB Server 버전 설정하다 에 대한 지원 중단하는 스칼라 운전자 의 수정 사항입니다.
드라이버는 MongoDB 서버 버전이 수명 종료(EOL) 시점에 도달하면 해당 버전에 대한 지원을 중단합니다.
EOL 제품에 대한 MongoDB 지원에 대해 자세히 알아보려면 레거시 지원 정책을 참조하세요.
드라이버 버전 5.5 서버 지원 변경 사항
v5.5 운전자 MongoDB Server 4.0에 대한 지원 중단합니다. v5.5 을 사용하려면 운전자 사용하려면 MongoDB Server 4.2 이상에 연결해야 합니다. MongoDB Server 배포서버 업그레이드 방법을 학습하려면 MongoDB Server 매뉴얼의 릴리스 노트 참조하세요.
서버 버전 8.1 지원 변경 사항
3.x 버전의 스칼라 운전자 사용하여 MongoDB Server v8.1를 실행 MongoDB deployment 에 연결할 수 없습니다. MongoDB Server v8.1부터 buildinfo
명령에는 인증 필요하므로 v3.x와 호환되지 않습니다. 운전자.
드라이버 버전 5.2 서버 지원 변경 사항
v5.2 운전자 MongoDB Server 3.6에 대한 지원 중단합니다. v5.2 을 사용하려면 운전자 사용하려면 MongoDB Server 4.0 이상에 연결해야 합니다. MongoDB Server 배포서버 업그레이드 방법을 학습하려면 MongoDB Server 매뉴얼의 릴리스 노트 참조하세요.
드라이버 버전 4.8 서버 지원 변경 사항
v4.8 운전자 MongoDB Server 3.4 및 이전 버전에 대한 지원 중단합니다. v4.8 을 사용하려면 운전자 사용하려면 MongoDB Server 3.6 이상에 연결해야 합니다. MongoDB Server 배포서버 업그레이드 방법을 학습하려면 MongoDB Server 매뉴얼의 릴리스 노트 참조하세요.