JsonCppData Class Reference

Base class for data objects using JsonCpp for underlying state. More...

#include "client/data/jsoncpp_data.h"

Inheritance diagram for JsonCppData:

List of all members.

Public Member Functions
	JsonCppData (const Json::Value &value)
	Standard constructor for an immutable instances.
	JsonCppData (Json::Value *value)
	Standard constructor for mutable instances.
virtual	~JsonCppData ()
	Standard destructor.
virtual util::Status	LoadFromJsonStream (std::istream *stream)
	Restores the state of this object from the JSON in the given std::istream.
virtual util::Status	StoreToJsonStream (std::ostream *stream) const
	Stores the state of this object as JSON in the given std::ostream.
virtual void	Clear ()
	Clears this instance state to an empty object.
virtual util::Status	LoadFromJsonReader (DataReader *reader)
	Restores the state of this object from the JSON in the given reader.
virtual DataReader *	MakeJsonReader () const
	Serializes the object into a JSON byte stream.
void	CopyFrom (const JsonCppData &from)
	Copies state from another instance into this one.
bool	IsMutable () const
	Determines if this instance is mutable or not.
bool	IsNull () const
	Determines if the represented JSON value is NULL.
void	CheckIsMutable () const
	Ensures the instance is mutable or terminate if not.
const Json::Value &	Storage () const
	Returns reference to the Json::Value instance used for storage.
const Json::Value &	Storage (const char *key) const
	Returns reference to the Json::Value instance used for storage.
Json::Value *	MutableStorage ()
	Returns a pointer to the storage bound in the constructor.
Json::Value *	MutableStorage (const char *key)
	Returns a pointer to the storage for the named subcomponent.
bool	operator== (const JsonCppData &other) const
	Determines if the object instances are equivalent.

---

Detailed Description

Base class for data objects using JsonCpp for underlying state.

Class instances are either const or mutable depending on how they are constructed. If constructed with a const reference, the instance will not allow direct mutation. If constructed with a pointer, the instance will allow mutation. It doesnt necessarily have to be like this, just seems like a reasonable safety mechanism given the wrapper ipmlementation strategy.

The objects are intended to be used in a call-by-value / value-result syntax however the "values" are actually references so semantics are actually call-by-reference. Admitedly this is unfortunate (i.e. weird) but it is to allow object wrappers to be used in a complete and uniform way when accessing and modifying complex composite objects through their various parts. Since the wrapper object state is just a pointer (and a bool) the copying syntax should not add much runtime overhead.

Keeping all the state in the Json::Value object will likely add runtime overhead however. Rather than attributes (of derived classes) being inlined member variables, they will be [] operator lookups on string names. The tradeoff here is for completeness, correctness, and internal implementation convienence in the short term to get things up and running more quickly to play with and understand strategic issues beyond performance.

Keeping all the state together allows unknown attributes to be first-class citizens along with known ones. Serialization, iteration, and so forth are already handled (and in an open soure library) by jsoncpp. Presumably since this is cheap to implement, it will be cheap to throw away and replace, investing the effort for runtime efficiency (or finding another package) at some future point down the road when it is a more pressing impedement.

This class is not thread-safe.

---

Constructor & Destructor Documentation

JsonCppData

(

const Json::Value &

value

)

[explicit]

Standard constructor for an immutable instances.

Parameters:

[in]

value

Provides the underlying JsonCpp storage. The lifetime of 'value' must be retained over the lifetime of this instance, however the state can change internally.

JsonCppData

(

Json::Value *

value

)

[explicit]

Standard constructor for mutable instances.

Parameters:

[in]

value

Provides the underlying JsonCpp storage. Ownership of 'value' is retained by the caller and must live beyond the lifecycle of this instance.

virtual ~JsonCppData

(

)

[virtual]

Standard destructor.

---

Member Function Documentation

void CheckIsMutable

(

)

const [inline]

Ensures the instance is mutable or terminate if not.

If the instance is not mutable this call will CHECK-fail and terminate the program. It is only intended to make assertions that indicate programming errors.

virtual void Clear

(

)

[virtual]

Clears this instance state to an empty object.

Implements SerializableJson.

void CopyFrom

(

const JsonCppData &

from

)

[inline]

Copies state from another instance into this one.

This will preserve the existing IsMutable-ness of this instance.

Parameters:

[in]

from

The state to copy from.

bool IsMutable

(

)

const [inline]

Determines if this instance is mutable or not.

Mutability is determined by which constructor was used.

Returns:

true if the instance is mutable.

bool IsNull

(

)

const [inline]

Determines if the represented JSON value is NULL.

Returns:

true if the underlying Json::Value denotes a null value.

virtual util::Status LoadFromJsonReader

(

DataReader *

reader

)

[virtual]

Restores the state of this object from the JSON in the given reader.

Parameters:

[in]

reader

The byte-sequence to read from.

Returns:

ok or explaination of failure.

Implements SerializableJson.

virtual util::Status LoadFromJsonStream

(

std::istream *

stream

)

[virtual]

Restores the state of this object from the JSON in the given std::istream.

Parameters:

[in]

stream

The stream to read from.

Returns:

ok or explaination of failure.

See also:

LoadFromJsonReader

Reimplemented from SerializableJson.

virtual DataReader* MakeJsonReader

(

)

const [virtual]

Serializes the object into a JSON byte stream.

Returns:

A standard reader interface around the JSON encoded object.

Implements SerializableJson.

Json::Value* MutableStorage

(

)

[inline]

Returns a pointer to the storage bound in the constructor.

This method will CHECK fail if the instance is immutable.

Json::Value* MutableStorage

(

const char *

key

)

[inline]

Returns a pointer to the storage for the named subcomponent.

This method will CHECK fail if the instance is immutable.

bool operator==

(

const JsonCppData &

other

)

const [inline]

Determines if the object instances are equivalent.

const Json::Value& Storage

(

)

const [inline]

Returns reference to the Json::Value instance used for storage.

Returns:

The instance bound in the constructor.

const Json::Value& Storage

(

const char *

key

)

const [inline]

Returns reference to the Json::Value instance used for storage.

This will create a new subcomponent if one did not already exist.

Parameters:

[in]

key

The JSON name of the desired subcomponent.

Returns:

The instance might be Json::Value::isNull but will be valid.

virtual util::Status StoreToJsonStream

(

std::ostream *

stream

)

const [virtual]

Stores the state of this object as JSON in the given std::ostream.

Parameters:

[in]

stream

The stream to write to.

Returns:

ok or explaination of failure.

See also:

MakeJsonReader

Reimplemented from SerializableJson.

---

The documentation for this class was generated from the following file:

• googleapis/client/data/jsoncpp_data.h