|
1 | | -+++ |
2 | | -date = "2016-08-15T16:11:58+05:30" |
3 | | -title = "Breaking changes from 26compat" |
4 | | -[menu.main] |
5 | | - weight = 25 |
6 | | - parent="legacy" |
7 | | -+++ |
8 | | - |
9 | | -The 26compat release series tracks the server 2.6 releases one-to-one. As a |
10 | | -result, it receives only bugfixes and small updates necessary to keep it |
11 | | -building in isolation. |
12 | | - |
13 | | -The legacy release series, on the other hand, is a permanent and diverging |
14 | | -fork. Our philosophy is to keep the legacy branch as close to the 26compat |
15 | | -branch as is reasonable, but that when weighing new features against |
16 | | -compatibility, we will choose new features. As a result the legacy branch |
17 | | -is not 100% source compatible with the 26compat branch. |
18 | | - |
19 | | -This page attempts to serve as a transition guide for those users looking |
20 | | -to migrate from the 26compat branch to the legacy branch. Note that it does |
21 | | -*not* discuss new features in detail and simply points to the per-release |
22 | | -notes. |
23 | | - |
24 | | -# Breaking Changes |
25 | | - |
26 | | -## Changes to the build system |
27 | | - |
28 | | -Scons targets have been renamed to more 'obvious' names, and some unused or |
29 | | -unneeded targets have been removed. |
30 | | - |
31 | | -### cheat sheet |
32 | | - |
33 | | -Task | Scons Target |
34 | | ---------------------------------------|----------------- |
35 | | -compile driver |`driver` |
36 | | -install driver |`install` |
37 | | -check driver install (used internally)|`check-install` |
38 | | -build unit tests |`build-unit` |
39 | | -run unit tests |`unit` |
40 | | -build integration tests |`build-integration` |
41 | | -run integration tests |`integration` |
42 | | -build client examples |`build-examples` |
43 | | -run client examples |`examples` |
44 | | -build everything (driver, unit tests, integration tests, examples|`all` |
45 | | -run all tests and client examples |`test` |
46 | | - |
47 | | -### Details |
48 | | - |
49 | | -* [`mongo-orchestration`](https://github.com/10gen/mongo-orchestration) is now required to run the driver's test suite. Please see the repository for instructions how to install and run `mongo-orchestration`. If you are not running tests, simply allow scons to time out when it looks for an instance of `mongo-orchestration` at the start of a build. |
50 | | -* The `driver` target has been created to built the client library without installing it |
51 | | -* The `install-mongoclient` target has been renamed to `install` |
52 | | -* Unit tests are now built with `build-unit`, and run with `unit` |
53 | | -* Integration tests are now built with `build-integration`, and run with `integration` |
54 | | -* Examples are now built with `build-examples`, and run with `examples` |
55 | | -* On OSX the `--osx-version-min` flag will now default to the current OSX version |
56 | | -* The `--full` flag is no longer required, and it is an error to specify it. |
57 | | -* The `--d` and `--dd` flags have been removed. Use the `--opt` and `--dbg` flags instead. |
58 | | -* The `--use-system-boost` flag is no longer required, and it is an error to specify it. |
59 | | -* All ABI affecting macros are now defined in a generated `config.h` header that is automatically included from `dbclient.h` and `bson.h`. |
60 | | -* Many server specific build options (that were unlikely to have been used when building the driver) have been removed. |
61 | | -* The default installation prefix is now `build/install`, rather than `/usr/local`. |
62 | | -* All build artifacts are now captured under the `build` directory. |
63 | | - |
64 | | -## Changes to APIs |
65 | | -* The `mongo::be`, `mongo::bo`, and `mongo::bob` typedefs for `mongo::BSONElement`, `mongo::BSONObj` and `mongo::BSONObjBuilder` have been removed. We recommend using the fully qualified names in new code. |
66 | | -* The `mongo::BSONBuilderBase` class has been removed and is no longer a base class of `mongo::BSONObjBuilder` or `mongo::BSONArrayBuilder` |
67 | | -* The `OpTime` class has been completely removed. It has been replaced by the simplified `Timestamp_t` class. |
68 | | -* The `globalServerOptions` and `globalSSLOptions` objects and their classes have been removed. All driver configuration should be done through the new `mongo::client::Options` object. |
69 | | -* The `RamLog`, `RotatableFileAppender`, and `Console` classes have been removed from the logging subsystem. |
70 | | -* In addition, many auxiliary types, functions, and headers that were either unused, or minimally used, have been removed from the distribution. |
71 | | -* The `ensureIndex` and related methods have been removed. The replacement is the new `createIndex` method. |
72 | | -* `IndexSpec::dropDuplicates()` is now deprecated as it is a no-op in MongoDB 3.0. |
73 | | -* The `QUERY` macro has been replaced by `MONGO_QUERY`. |
74 | | -* The `ConnectionString::parse` method now requires it's argument to be in the MongoDB URL ("mongodb://...") format. To use the old format, use the new `ConnectionString::parseDeprecated` method. |
75 | | -* The `ConnectionPool` and `ScopedDbConnection` classes have been removed. |
76 | | - |
77 | | -## Behavior Changes |
78 | | -* The driver will not function correctly unless `mongo::client::initialize` is invoked before using the driver APIs. The mongo::client::shutdown method should also be called at application termination (if options.callShutdownAtExit() is not set) so the driver can cleanly terminate. As a convenience, we have added [`mongo::GlobalInstance`](https://github.com/mongodb/mongo-cxx-driver/blob/legacy/src/mongo/client/init.h#L69) as an RAII wrapper to automatically call these methods. |
79 | | -* options.callShutdownAtExit() is a no-op on non-static builds on Windows due to issues around sudden thread termination. |
80 | | -* The driver no longer logs any output by default. You may configure and inject a logger to re-enable logging. See `src/mongo/client/examples/clientTest.cpp` for an example of how to enable logging. |
81 | | -* Writes are now "[acknowledged](http://docs.mongodb.org/manual/core/write-concern/#write-concern-acknowledged)" by default. In all previous releases the default write concern was “[unacknowledged](http://docs.mongodb.org/manual/core/write-concern/#unacknowledged)”. This change may have performance and behavior implications for existing applications that did not confirm writes. You can read more about the change [here](http://docs.mongodb.org/manual/release-notes/drivers-write-concern/#driver-write-concern-change). |
82 | | -* The driver now throws a mongo::OperationException when write concern is greater than Acknowledged for errors that occur when running operations against a MongoDB database. |
83 | | -* The default shutdown grace period is now zero which means the driver may block forever until a successful shutdown occurs. |
84 | | - |
85 | | -# Improvements |
86 | | - |
87 | | -Please see the [release |
88 | | -notes](https://github.com/mongodb/mongo-cxx-driver/releases) for the |
89 | | -individual legacy branch releases for details on improvements in each |
90 | | -release. |
| 1 | ++++ |
| 2 | +date = "2016-08-15T16:11:58+05:30" |
| 3 | +title = "Breaking changes from 26compat" |
| 4 | +[menu.main] |
| 5 | + weight = 25 |
| 6 | + parent="legacy" |
| 7 | ++++ |
| 8 | + |
| 9 | +The 26compat release series tracks the server 2.6 releases one-to-one. As a |
| 10 | +result, it receives only bugfixes and small updates necessary to keep it |
| 11 | +building in isolation. |
| 12 | + |
| 13 | +The legacy release series, on the other hand, is a permanent and diverging |
| 14 | +fork. Our philosophy is to keep the legacy branch as close to the 26compat |
| 15 | +branch as is reasonable, but that when weighing new features against |
| 16 | +compatibility, we will choose new features. As a result the legacy branch |
| 17 | +is not 100% source compatible with the 26compat branch. |
| 18 | + |
| 19 | +This page attempts to serve as a transition guide for those users looking |
| 20 | +to migrate from the 26compat branch to the legacy branch. Note that it does |
| 21 | +*not* discuss new features in detail and simply points to the per-release |
| 22 | +notes. |
| 23 | + |
| 24 | +# Breaking Changes |
| 25 | + |
| 26 | +## Changes to the build system |
| 27 | + |
| 28 | +Scons targets have been renamed to more 'obvious' names, and some unused or |
| 29 | +unneeded targets have been removed. |
| 30 | + |
| 31 | +### cheat sheet |
| 32 | + |
| 33 | +Task | Scons Target |
| 34 | +--------------------------------------|----------------- |
| 35 | +compile driver |`driver` |
| 36 | +install driver |`install` |
| 37 | +check driver install (used internally)|`check-install` |
| 38 | +build unit tests |`build-unit` |
| 39 | +run unit tests |`unit` |
| 40 | +build integration tests |`build-integration` |
| 41 | +run integration tests |`integration` |
| 42 | +build client examples |`build-examples` |
| 43 | +run client examples |`examples` |
| 44 | +build everything (driver, unit tests, integration tests, examples|`all` |
| 45 | +run all tests and client examples |`test` |
| 46 | + |
| 47 | +### Details |
| 48 | + |
| 49 | +* [`mongo-orchestration`](https://github.com/10gen/mongo-orchestration) is now required to run the driver's test suite. Please see the repository for instructions how to install and run `mongo-orchestration`. If you are not running tests, simply allow scons to time out when it looks for an instance of `mongo-orchestration` at the start of a build. |
| 50 | +* The `driver` target has been created to built the client library without installing it |
| 51 | +* The `install-mongoclient` target has been renamed to `install` |
| 52 | +* Unit tests are now built with `build-unit`, and run with `unit` |
| 53 | +* Integration tests are now built with `build-integration`, and run with `integration` |
| 54 | +* Examples are now built with `build-examples`, and run with `examples` |
| 55 | +* On OSX the `--osx-version-min` flag will now default to the current OSX version |
| 56 | +* The `--full` flag is no longer required, and it is an error to specify it. |
| 57 | +* The `--d` and `--dd` flags have been removed. Use the `--opt` and `--dbg` flags instead. |
| 58 | +* The `--use-system-boost` flag is no longer required, and it is an error to specify it. |
| 59 | +* All ABI affecting macros are now defined in a generated `config.h` header that is automatically included from `dbclient.h` and `bson.h`. |
| 60 | +* Many server specific build options (that were unlikely to have been used when building the driver) have been removed. |
| 61 | +* The default installation prefix is now `build/install`, rather than `/usr/local`. |
| 62 | +* All build artifacts are now captured under the `build` directory. |
| 63 | + |
| 64 | +## Changes to APIs |
| 65 | +* The `mongo::be`, `mongo::bo`, and `mongo::bob` typedefs for `mongo::BSONElement`, `mongo::BSONObj` and `mongo::BSONObjBuilder` have been removed. We recommend using the fully qualified names in new code. |
| 66 | +* The `mongo::BSONBuilderBase` class has been removed and is no longer a base class of `mongo::BSONObjBuilder` or `mongo::BSONArrayBuilder` |
| 67 | +* The `OpTime` class has been completely removed. It has been replaced by the simplified `Timestamp_t` class. |
| 68 | +* The `globalServerOptions` and `globalSSLOptions` objects and their classes have been removed. All driver configuration should be done through the new `mongo::client::Options` object. |
| 69 | +* The `RamLog`, `RotatableFileAppender`, and `Console` classes have been removed from the logging subsystem. |
| 70 | +* In addition, many auxiliary types, functions, and headers that were either unused, or minimally used, have been removed from the distribution. |
| 71 | +* The `ensureIndex` and related methods have been removed. The replacement is the new `createIndex` method. |
| 72 | +* `IndexSpec::dropDuplicates()` is now deprecated as it is a no-op in MongoDB 3.0. |
| 73 | +* The `QUERY` macro has been replaced by `MONGO_QUERY`. |
| 74 | +* The `ConnectionString::parse` method now requires it's argument to be in the MongoDB URL ("mongodb://...") format. To use the old format, use the new `ConnectionString::parseDeprecated` method. |
| 75 | +* The `ConnectionPool` and `ScopedDbConnection` classes have been removed. |
| 76 | + |
| 77 | +## Behavior Changes |
| 78 | +* The driver will not function correctly unless `mongo::client::initialize` is invoked before using the driver APIs. The mongo::client::shutdown method should also be called at application termination (if options.callShutdownAtExit() is not set) so the driver can cleanly terminate. As a convenience, we have added [`mongo::GlobalInstance`](https://github.com/mongodb/mongo-cxx-driver/blob/legacy/src/mongo/client/init.h#L69) as an RAII wrapper to automatically call these methods. |
| 79 | +* options.callShutdownAtExit() is a no-op on non-static builds on Windows due to issues around sudden thread termination. |
| 80 | +* The driver no longer logs any output by default. You may configure and inject a logger to re-enable logging. See `src/mongo/client/examples/clientTest.cpp` for an example of how to enable logging. |
| 81 | +* Writes are now "[acknowledged](http://docs.mongodb.org/manual/core/write-concern/#write-concern-acknowledged)" by default. In all previous releases the default write concern was “[unacknowledged](http://docs.mongodb.org/manual/core/write-concern/#unacknowledged)”. This change may have performance and behavior implications for existing applications that did not confirm writes. You can read more about the change [here](http://docs.mongodb.org/manual/release-notes/drivers-write-concern/#driver-write-concern-change). |
| 82 | +* The driver now throws a mongo::OperationException when write concern is greater than Acknowledged for errors that occur when running operations against a MongoDB database. |
| 83 | +* The default shutdown grace period is now zero which means the driver may block forever until a successful shutdown occurs. |
| 84 | + |
| 85 | +# Improvements |
| 86 | + |
| 87 | +Please see the [release |
| 88 | +notes](https://github.com/mongodb/mongo-cxx-driver/releases) for the |
| 89 | +individual legacy branch releases for details on improvements in each |
| 90 | +release. |
0 commit comments