MongoDB  2.7.0
document.h
1 /* Copyright 2013 10gen Inc.
2  *
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  * http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 #pragma once
17 
18 #include <boost/scoped_ptr.hpp>
19 
20 #include "mongo/base/disallow_copying.h"
21 #include "mongo/base/string_data.h"
22 #include "mongo/bson/mutable/const_element.h"
23 #include "mongo/bson/mutable/damage_vector.h"
24 #include "mongo/bson/mutable/element.h"
25 #include "mongo/db/jsobj.h"
26 #include "mongo/platform/cstdint.h"
27 #include "mongo/util/safe_num.h"
28 
29 namespace mongo {
30 namespace mutablebson {
31 
221  class Document {
222 
223  // TODO: In principle there is nothing that prevents implementing a deep copy for
224  // Document, but for now it is not permitted.
225  MONGO_DISALLOW_COPYING(Document);
226 
227  public:
228 
229  //
230  // Lifecycle
231  //
232 
234  Document();
235 
236  enum InPlaceMode {
237  kInPlaceDisabled = 0,
238  kInPlaceEnabled = 1,
239  };
240 
245  explicit Document(const BSONObj& value, InPlaceMode inPlaceMode = kInPlaceEnabled);
246 
255  void reset();
256 
260  void reset(const BSONObj& value, InPlaceMode inPlaceMode = kInPlaceEnabled);
261 
263  ~Document();
264 
265 
266  //
267  // Comparison API
268  //
269 
271  inline int compareWith(const Document& other, bool considerFieldName = true) const;
272 
274  inline int compareWithBSONObj(const BSONObj& other, bool considerFieldName = true) const;
275 
276 
277  //
278  // Serialization API
279  //
280 
284  inline void writeTo(BSONObjBuilder* builder) const;
285 
289  inline BSONObj getObject() const;
290 
291 
292  //
293  // Element creation API.
294  //
295  // Newly created elements are not attached to the tree (effectively, they are
296  // 'roots'). You must call one of the topology management methods in 'Element' to
297  // connect the newly created Element to another Element in the Document, possibly the
298  // Element referenced by Document::root. Elements do not outlive the Document.
299  //
300 
302  Element makeElementDouble(const StringData& fieldName, double value);
303 
305  Element makeElementString(const StringData& fieldName, const StringData& value);
306 
308  Element makeElementObject(const StringData& fieldName);
309 
313  Element makeElementObject(const StringData& fieldName, const BSONObj& value);
314 
316  Element makeElementArray(const StringData& fieldName);
317 
321  Element makeElementArray(const StringData& fieldName, const BSONObj& value);
322 
325  const StringData& fieldName, uint32_t len, BinDataType binType, const void* data);
326 
328  Element makeElementUndefined(const StringData& fieldName);
329 
331  Element makeElementNewOID(const StringData& fieldName);
332 
334  Element makeElementOID(const StringData& fieldName, mongo::OID value);
335 
337  Element makeElementBool(const StringData& fieldName, bool value);
338 
340  Element makeElementDate(const StringData& fieldName, Date_t value);
341 
343  Element makeElementNull(const StringData& fieldName);
344 
347  const StringData& fieldName, const StringData& regex, const StringData& flags);
348 
351  const StringData& fieldName, const StringData& ns, mongo::OID oid);
352 
354  Element makeElementCode(const StringData& fieldName, const StringData& value);
355 
357  Element makeElementSymbol(const StringData& fieldName, const StringData& value);
358 
361  const StringData& fieldName, const StringData& code, const BSONObj& scope);
362 
364  Element makeElementInt(const StringData& fieldName, int32_t value);
365 
367  Element makeElementTimestamp(const StringData& fieldName, OpTime value);
368 
370  Element makeElementLong(const StringData& fieldName, int64_t value);
371 
373  Element makeElementMinKey(const StringData& fieldName);
374 
376  Element makeElementMaxKey(const StringData& fieldName);
377 
378 
379  //
380  // Element creation methods from variant types
381  //
382 
386  Element makeElement(const BSONElement& elt);
387 
391  Element makeElementWithNewFieldName(const StringData& fieldName, const BSONElement& elt);
392 
396  Element makeElementSafeNum(const StringData& fieldName, SafeNum value);
397 
403 
409  Element makeElementWithNewFieldName(const StringData& fieldName, ConstElement elt);
410 
411  //
412  // Accessors
413  //
414 
416  inline Element root();
417 
419  inline ConstElement root() const;
420 
422  inline Element end();
423 
425  inline ConstElement end() const;
426 
427  inline std::string toString() const;
428 
429  //
430  // In-place API.
431  //
432 
436  void reserveDamageEvents(size_t expectedEvents);
437 
462  bool getInPlaceUpdates(DamageVector* damages,
463  const char** source,
464  size_t* size = NULL);
465 
473  void disableInPlaceUpdates();
474 
481  InPlaceMode getCurrentInPlaceMode() const;
482 
486  inline bool isInPlaceModeEnabled() const;
487 
488  private:
489  friend class Element;
490 
491  // For now, the implementation of Document is firewalled.
492  class Impl;
493  inline Impl& getImpl();
494  inline const Impl& getImpl() const;
495 
496  Element makeRootElement();
497  Element makeRootElement(const BSONObj& value);
498  Element makeElement(ConstElement element, const StringData* fieldName);
499 
500  const boost::scoped_ptr<Impl> _impl;
501 
502  // The root element of this document.
503  const Element _root;
504  };
505 
506 } // namespace mutablebson
507 } // namespace mongo
508 
509 #include "mongo/bson/mutable/document-inl.h"
Element makeElementWithNewFieldName(const StringData &fieldName, const BSONElement &elt)
Construct a new Element with the same type and value as the provided BSONElement, but with a new name...
Definition: document.cpp:2521
Element makeElementMinKey(const StringData &fieldName)
Create a new min key Element with the given field name.
Definition: document.cpp:2479
Element makeElementCodeWithScope(const StringData &fieldName, const StringData &code, const BSONObj &scope)
Create a new scoped code Element with the given data and field name.
Definition: document.cpp:2436
Utility for creating a BSONObj.
Definition: bsonobjbuilder.h:52
Element makeElementRegex(const StringData &fieldName, const StringData &regex, const StringData &flags)
Create a new regex Element with the given data and field name.
Definition: document.cpp:2390
Element makeElementCode(const StringData &fieldName, const StringData &value)
Create a new code Element with the given value and field name.
Definition: document.cpp:2414
void writeTo(BSONObjBuilder *builder) const
Serialize the Elements reachable from the root Element of this Document to the provided builder...
Definition: document-inl.h:32
Element makeElementObject(const StringData &fieldName)
Create a new empty object Element with the given field name.
Definition: document.cpp:2265
Element makeElementBool(const StringData &fieldName, bool value)
Create a new bool Element with the given value and field name.
Definition: document.cpp:2360
Element makeElementArray(const StringData &fieldName)
Create a new empty array Element with the given field name.
Definition: document.cpp:2293
BSON classes.
Element makeElementMaxKey(const StringData &fieldName)
Create a new max key Element with the given field name.
Definition: document.cpp:2489
~Document()
Destroy this document permanently.
Definition: document.cpp:2225
Element makeElementDouble(const StringData &fieldName, double value)
Create a new double Element with the given value and field name.
Definition: document.cpp:2244
Element root()
Returns the root element for this document.
Definition: document-inl.h:42
Definition: time_support.h:35
Element makeElementInt(const StringData &fieldName, int32_t value)
Create a new integer Element with the given value and field name.
Definition: document.cpp:2449
int compareWithBSONObj(const BSONObj &other, bool considerFieldName=true) const
Compare this Document to 'other' with the semantics of BSONObj::woCompare.
Definition: document-inl.h:28
Element makeElementTimestamp(const StringData &fieldName, OpTime value)
Create a new timetamp Element with the given value and field name.
Definition: document.cpp:2459
Element end()
Returns an element that will compare equal to a non-ok element.
Definition: document-inl.h:50
Element makeElementNull(const StringData &fieldName)
Create a new null Element with the given field name.
Definition: document.cpp:2380
Element makeElementDBRef(const StringData &fieldName, const StringData &ns, mongo::OID oid)
Create a new DBRef Element with the given data and field name.
Definition: document.cpp:2404
Element makeElementUndefined(const StringData &fieldName)
Create a new undefined Element with the given field name.
Definition: document.cpp:2334
bool isInPlaceModeEnabled() const
A convenience routine, this returns true if the current in-place mode is kInPlaceEnabled, and false otherwise.
Definition: document-inl.h:62
Element makeElementLong(const StringData &fieldName, int64_t value)
Create a new long integer Element with the given value and field name.
Definition: document.cpp:2469
SafeNum holds and does arithmetic on a number in a safe way, handling overflow and casting for the us...
Definition: safe_num.h:56
Element makeElementDate(const StringData &fieldName, Date_t value)
Create a new date Element with the given value and field name.
Definition: document.cpp:2370
void reserveDamageEvents(size_t expectedEvents)
Ensure that at least 'expectedEvents' damage events can be recorded for in-place mutations without re...
Definition: document.cpp:2227
Definition: optime.h:41
InPlaceMode getCurrentInPlaceMode() const
Returns the current in-place mode for the document.
Definition: document.cpp:2240
Element represents a BSON value or object in a mutable BSON Document.
Definition: element.h:99
BSONElement represents an "element" in a BSONObj.
Definition: bsonelement.h:62
Element makeElementSymbol(const StringData &fieldName, const StringData &value)
Create a new symbol Element with the given value and field name.
Definition: document.cpp:2425
C++ representation of a "BSON" object – that is, an extended JSON-style object in a binary representa...
Definition: bsonobj.h:77
Element makeElementString(const StringData &fieldName, const StringData &value)
Create a new string Element with the given value and field name.
Definition: document.cpp:2254
Element makeElementBinary(const StringData &fieldName, uint32_t len, BinDataType binType, const void *data)
Create a new binary Element with the given data and field name.
Definition: document.cpp:2320
Element makeElement(const BSONElement &elt)
Construct a new Element with the same name, type, and value as the provided BSONElement.
Definition: document.cpp:2499
void reset()
Abandon all internal state associated with this Document, and return to a state semantically equivale...
Definition: document.cpp:2211
void disableInPlaceUpdates()
Drop the queue of in-place update damage events, and do not queue new operations that would otherwise...
Definition: document.cpp:2236
For an overview of mutable BSON, please see the file document.h in this directory.
Definition: const_element.h:36
int compareWith(const Document &other, bool considerFieldName=true) const
Compare this Document to 'other' with the semantics of BSONObj::woCompare.
Definition: document-inl.h:21
Element makeElementNewOID(const StringData &fieldName)
Create a new OID + Element with the given field name.
Definition: document.cpp:2344
Object ID type.
Definition: oid.h:42
Element makeElementOID(const StringData &fieldName, mongo::OID value)
Create a new OID Element with the given value and field name.
Definition: document.cpp:2350
bool getInPlaceUpdates(DamageVector *damages, const char **source, size_t *size=NULL)
Request a vector of damage events describing in-place updates to this Document.
Definition: document.cpp:2231
Mutable BSON Overview.
Definition: document.h:221
Element makeElementSafeNum(const StringData &fieldName, SafeNum value)
Create a new element of the appopriate type to hold the given value, with the given field name...
Definition: document.cpp:2542
Document()
Construct a new empty document.
Definition: document.cpp:2199
BSONObj getObject() const
Serialize the Elements reachable from the root Element of this Document and return the result as a BS...
Definition: document-inl.h:36