[JAVA-1859] Improve explanation of MongoCollection type parameter Created: 11/Jun/15  Updated: 07/Oct/15  Resolved: 04/Sep/15

Status: Closed
Project: Java Driver
Component/s: API, Documentation
Affects Version/s: None
Fix Version/s: 3.1.0

Type: Improvement Priority: Minor - P4
Reporter: Ben McCann Assignee: Ross Lawley
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

MongoCollection<Document> doesn't make sense to me. This is much harder to use in code than just MongoCollection. Why was it genericized? What else can you have a collection of besides documents? This seems like potentially it wasn't the best way to design this. Or maybe it's just that the documentation needs to be improved to make it clearer what the purpose of this is.



 Comments   
Comment by Jeffrey Yemin [ 07/Oct/15 ]

Released in 3.1.0

Comment by Ross Lawley [ 04/Sep/15 ]

Updated the API docs for MongoCollection - thanks to Ben for the impetus.

Comment by Githook User [ 04/Sep/15 ]

Author:

{u'username': u'rozza', u'name': u'Ross Lawley', u'email': u'ross.lawley@gmail.com'}

Message: Api Docs clarify the connection between MongoCollection and the CodecRegistry

JAVA-1859
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/a92afc8eae8a476516ea659aaa59ecd5a0c1064d

Comment by Ben McCann [ 11/Jun/15 ]

Thanks. That's very helpful.

I'll leave this open for now with a couple suggestions of changes I think could be helpful newbies to the API like me to navigate the docs and figure this out.

It'd be helpful to expand the documentation TDocument from "The type that this collection will encode documents from and decode documents to." to something more like "The type that this collection will encode documents from and decode documents to. These must first be registered with a CodecRegistry. The default CodecRegistry includes built-in support for types like Document, DBObject, POJO. See http://mongodb.github.io/mongo-java-driver/3.0/bson/codecs/ for details"

The CodecRegistry docs show you how to create a registry, but not how you can use it for anything. I see now that there's a section in the CRUD docs for that explains it. However, when I wanted to see what CodecRegistry did I went to the CodecRegistry docs and so I never saw that. These need to be linked somehow. My suggestion would be to move most of that documentation from CRUD to CodecRegistry and then in CRUD say something like "An overload of the getCollection method allows clients to specify a different class for representing BSON documents. For example, users of the legacy CRUD API from the 2.x driver series may wish to continue using BasicDBObject in order to ease the transition to the new CRUD API. For more details see the <a href="...">Codec documentation</a>."

(btw, the blog post you linked me to suggests leaving feedback in the bug tracker. if you prefer the mailing list for this sort of feedback it might be worth updating that)

thanks!

Comment by Ross Lawley [ 11/Jun/15 ]

Hi chengas123,

This might have been better posted on the mailing list as the JAVA project is specifically for driver based bugs or issues.

I'm interested in why you find it much harder to use - can you provide an example? We've kept with a default Document type via the API, so it shouldn't be intrusive but we have allowed users who want to use their own domain objects the ability to do so directly, which wasn't possible in 2.0.

There is a blog post about some of the specific design decisions in the 3.0 driver on the MongoDB blog: Introducing the 3.0 Java Driver which talks briefly about the new codecs and generics features:

A popular feature request has been to provide an easier way to convert the results from the database straight into domain objects. With the introduction of a Codec registry and the use of generics in the API, working directly with domain objects is now possible. So if the new Document class isn't to your taste, then register a custom codec for your domain object and simply use the API and pass in the class of the domain object you want to use.

This is also mentioned in the driver documentation in the CRUD operations guide. This is particularly helpful when migrating legacy DBObject code to the new API as you can simply do:

MongoCollection<DBObject> collection = client.getDatabase("myDatabase").getCollection("collectionName", DBObject.class);

The forthcoming PojoCodec in the 3.1 release (JAVA-1833) will help with the usability of Codecs and using custom Domain Objects to represent data from MongoDB. Of course examples of using this feature will be added to the documentation as well.

I hope this answers your questions.

Ross

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