title: Java MongoDB/BSON class confusion
body: <p>I'm trying to understand the BSON implementation used by the Java MongoDB driver (the official async one, in case that is important).</p>
  
  <p>However, I'm totally stuck on the classes representing BSON documents. I'm concentrating on the "normal" ones, ignoring features like lazy construction for now. So far, I have found:</p>
  
  <ul>
  <li>BasicBSONObject</li>
  <li>BsonDocument</li>
  <li>Document</li>
  <li>BSONObject, an interface implemented by BasicBSONObject but not the others</li>
  </ul>
  
  <p>I've also found that the MongoDB driver returns its results as Document instances by default, and can be changed to return BsonDocument. OTOH, the JSON class wants to return a DBObject, which is implemented by BasicDBObject extends BasicBSONObject.</p>
  
  <p>How are these classes related? Which one should be used in which case?</p>
  
  <p>When writing code that accepts a BSON document as a parameter, or returns it, which type should I use? This is actually the question I'm most interested in, but the above restrictions seem to contradict.</p>