[JAVA-2521] Repackage the driver so that packages are no longer divided Created: 26/May/17  Updated: 29/Oct/23  Resolved: 26/Jan/18

Status: Closed
Project: Java Driver
Component/s: Packaging
Affects Version/s: None
Fix Version/s: 3.7.0

Type: New Feature Priority: Major - P3
Reporter: Jeffrey Yemin Assignee: Jeffrey Yemin
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Depends
depends on JAVA-2705 Move MongoDriverInformation class fro... Closed
Epic Link: Java9

 Description   
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.


 Comments   
Comment by Githook User [ 26/Jan/18 ]

Author:

{'name': 'Jeff Yemin', 'email': 'jeff.yemin@10gen.com', 'username': 'jyemin'}

Message: JAVA-2521: Remove Automatic-Module-Name from mongo-java-driver jar
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/b7ff3c75b87403e18ec206061e250a22f769b99f

Comment by Githook User [ 23/Jan/18 ]

Author:

{'name': 'Jeff Yemin', 'email': 'jeff.yemin@10gen.com', 'username': 'jyemin'}

Message: JAVA-2521: Add mongodb-driver uber-jar containing driver-sync and driver-legacy.

Note: this can not be a Java module due to the split of the com.mongodb package between driver-legacy and driver-core.
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/dced1698eda4aa892af0098e87c492e7dbc4bad9

Comment by Githook User [ 23/Jan/18 ]

Author:

{'name': 'Jeff Yemin', 'email': 'jeff.yemin@10gen.com', 'username': 'jyemin'}

Message: JAVA-2521: Rename driver directory to driver-sync
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/8a25c0722f36dd8e2b3d83dc07c1f89823b1b095

Comment by Githook User [ 23/Jan/18 ]

Author:

{'name': 'Jeff Yemin', 'email': 'jeff.yemin@10gen.com', 'username': 'jyemin'}

Message: JAVA-2521: Move DBObject-related classes from driver-legacy to driver-core

This makes it possible to use DBObject using the new CRUD API without pulling in the whole legacy driver API
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/66531c9601f622711e4190a8358275611e395801

Comment by Githook User [ 23/Jan/18 ]

Author:

{'name': 'Jeff Yemin', 'email': 'jeff.yemin@10gen.com', 'username': 'jyemin'}

Message: JAVA-2521: Move org.bson package in driver-legacy into the bson module

This avoids package-splitting issue that make it impossible to modularize the artifacts for Java 9.
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/517b70f0130248fcb9d0b83963fc4760adadb523

Comment by Githook User [ 11/Jan/18 ]

Author:

{'email': 'jeff.yemin@10gen.com', 'name': 'Jeff Yemin', 'username': 'jyemin'}

Message: JAVA-2521: Document public classes in com.mongodb.client.internal as not part of the public API
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/ab6828082e901a9188a19469157e4b6ec31649bf

Comment by Githook User [ 09/Jan/18 ]

Author:

{'email': 'jeff.yemin@10gen.com', 'name': 'Jeff Yemin', 'username': 'jyemin'}

Message: JAVA-2521: Replace use of org.mongodb.assertions with com.mongodb.assertions in driver-async
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/3d5e177ccca52459a6ac747d7a30a60cab1a4817

Comment by Githook User [ 09/Jan/18 ]

Author:

{'email': 'jeff.yemin@10gen.com', 'name': 'Jeff Yemin', 'username': 'jyemin'}

Message: JAVA-2521: Modularize the driver sub-project by splitting the legacy API from the standard CRUD API
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/ce655bb474b224c971ae43db4c30131692fe8db8

Comment by Jeffrey Yemin [ 08/Dec/17 ]

aharris yes, they should be. Note that currently the mongodb-driver module is not OSGI-compatibile due to the fact that it contains classes from both the org.bson package and the com.mongodb package. This new structure would rectify that situation by avoiding all package splitting across modules.

Comment by Andrew Harris [ 08/Dec/17 ]

Would these changes still be compatible with OSGi?

Generated at Thu Feb 08 08:57:25 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.