Problem statement

The 3.x driver releases have a number of problems when considered in relation to Jigsaw modules:

• The same packages are included in multiple jar files. The mongo-java-driver is an "uber" jar that includes all classes from bson, driver-core, and driver. If anyone tried to put both the regular and uber jars in the module path it would result in a failure, as only one module can contain a given package.
• Packages are split across jar files, and for the same reason as above those jars can not be made into modules. In particular:
  • com.mongodb is split across driver-core and driver
  • org.bson is split across bson and driver

Java 9 Module structure

• bson
  • Include all classes in the bson source module
• mongodb-driver-core
  • Include all classes in the driver-core source module
  • Move com.mongodb.connection.netty from driver-core to driver-async or to driver-async-netty. The latter has advantages because then Netty doesn't have to be an optional module dependency but a true dependency, and users can just decide whether to depend on the driver-async-netty module explicitly.
• mongodb-driver-async
  • Include all classes in the driver-async source module
• mongodb-driver
  • Include the following packages from the driver source module
    • com.mongodb.client
      • Add a new entry point into the CRUD API that doesn't include the legacy API. It includes a com.mongodb.client.MongoClients factory and a com.mongodb.client.MongoClient interface, mirroring the async version
    • com.mongodb.client.gridfs
• mongo-java-driver
  • Includes the following packages from the current driver source module
    • com.mongodb
    • com.mongodb.client.jndi
    • com.mongodb.client.model
    • com.mongodb.gridfs
    • com.mongodb.util
    • org.bson
    • org.bson.io
    • org.bson.types
    • org.bson.util
  • Packaged only as an uber jar including all classes in bson, driver-core, and driver, and mongo-java-driver
    • Perhaps exclude the new com.mongodb.client.MongoClients and com.mongodb.client.MongoClient classes to avoid having multiple MongoClient classes in the uber jar
  • Perhaps deprecate com.mongodb.MongoClient

Advantages

• The module structure is nice and clean for those using the standard API, with no need for an uber jar or inclusion of packages that are unnecessary.
• No need to include the legacy driver API when pulling in driver-async, as was required by the original proposal
• No need to include the legacy bson API (the part that's in the driver source module) when using the non-legacy API
• Only users of the legacy API have to use the uber-jar

Disadvantages

• It's sort of a breaking change for anyone currently relying on mongodb-driver, as it will no longer contain the legacy API. If that's too onerous, we could instead choose a new module name for the non-legacy API, e.g. mongodb-driver-sync, and continue to publish mongodb-driver as is, though it can't be a Java 9 module due to the package splitting.
• Any application that uses just the CRUD API but also needs DBObject will have to depend on the entire mongo-java-driver uber jar (driver-async users have the same problem now).
• It will not be possible to mix use of the legacy API and the async API on the module path. The problem is that module dependencies are based on module names rather than packages, so mongodb-driver-async has to depend on either mongodb-driver-core or mongo-java-driver, but can't depend on both.

Original proposal

• Move org.bson.* classes currently included in the driver module into the bson module. Consider a separate source root for them like bson/legacy/main
• Move com.mongodb.connection.netty from driver-core to driver-async or to driver-async-netty. The latter has advantages because then Netty doesn't have to be an optional module dependency but a true dependency, and users can just decide whether to depend on the driver-async-netty module explicitly.
• Combine driver and driver-core into a single module so that com.mongodb is no longer split. It will depend on the bson module
• The driver-async module will depend on this combined module. The downside is that users of driver-async have a dependency, though unused, on the high level sync CRUD API as well as the high level legacy API. Without breaking binary compatibility in a major way by moving classes to different packages, there may be nothing we can do about this.