[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
| |
| 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:
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:
The forthcoming PojoCodec in the 3.1 release ( I hope this answers your questions. Ross |