inc/FWebJsonJsonObject.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                FWebJsonJsonObject.h
  20  * @brief               This is the header file for the %JsonObject class.
  21  *
  22  * This header file contains the declarations of the %JsonObject class.
  23  * This class represents the JSON value of type object.
  24  */
  25 #ifndef _FWEB_JSON_JSON_OBJECT_H_
  26 #define _FWEB_JSON_JSON_OBJECT_H_
  27
  28 #include <FBaseColHashMapT.h>
  29 #include <FBaseString.h>
  30 #include <FWebJsonIJsonValue.h>
  31
  32 #ifdef __clang__
  33 #pragma clang diagnostic push
  34 #pragma clang diagnostic ignored "-Woverloaded-virtual"
  35 #endif
  36
  37 namespace Tizen { namespace Web { namespace Json
  38 {
  39 class _JsonObjectImpl;
  40 class _JsonObjectComparer;
  41 class _JsonObjectHashCodeProvider;
  42 }}} // Tizen::Web::Json
  43
  44 namespace Tizen { namespace Web { namespace Json
  45 {
  46
  47 /**
  48  * @class       JsonObject
  49  * @brief       This class represents the JSON value of type object.
  50  *
  51  * @since       2.0
  52  *
  53  * @final       This class is not intended for extension.
  54  *
  55  * The %JsonObject class represents the JSON value of type object.
  56  *
  57  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/web/json_namespace.htm">JSON Guide</a>.
  58  *
  59  * The following example demonstrates how to create and initialize a %JsonObject instance and how to use its methods.
  60  *
  61  * @code
  62  *      #include <FWebJson.h>
  63  *
  64  *      using namespace Tizen::Base;
  65  *      using namespace Tizen::Base::Collection;
  66  *      using namespace Tizen::Web::Json;
  67  *
  68  *      void
  69  *      MyClass::JsonObjectSample(void)
  70  *      {
  71  *              //Creates an instance of JsonObject
  72  *              JsonObject *pJsonObj = new JsonObject();
  73  *
  74  *              //Construct() must be called for JsonObject
  75  *              pJsonObj->Construct();
  76  *
  77  *              //Creates keys, the pointer to string is the key for the element of the JsonObject
  78  *              String  *pStrFNKey      = new String(L"firstName");
  79  *              String  *pStrAgeKey             = new String(L"age");
  80  *
  81  *              //Creates values, the pointer to any JsonValue is the value for the element of the JsonObject
  82  *              JsonString  *pStrFNVal      = new JsonString(L"John");
  83  *              JsonNumber      *pNumAge                = new JsonNumber(25);
  84  *
  85  *              //Adds key-value pairs to object
  86  *              pJsonObj->Add(pStrFNKey, pStrFNVal);
  87  *              pJsonObj->Add(pStrAgeKey, pNumAge);
  88  *
  89  *              // Gets the value with the specified key
  90  *              IJsonValue* pValue = null;
  91  *              pJsonObj->GetValue(pStrFNKey, pValue);
  92  *
  93  *              // Uses enumerator to access elements in the map
  94  *              const String* pKey = null;
  95  *              IMapEnumeratorT<const String*, IJsonValue*>*  pMapEnum = null;
  96  *              pMapEnum = pJsonObj->GetMapEnumeratorN();
  97  *              if( pMapEnum )
  98  *              {
  99  *                      while (pMapEnum->MoveNext() == E_SUCCESS)
 100  *                      {
 101  *                              pMapEnum->GetKey(pKey);
 102  *                              pMapEnum->GetValue(pValue);
 103  *                      }
 104  *                      delete pMapEnum;
 105  *              }
 106  *
 107  *              // Removes a key-value pair with memory deallocation
 108  *              pJsonObj->Remove(pStrAgeKey, true);
 109  *
 110  *              // Removes all remaining key-value pairs with memory deallocation
 111  *              pJsonObj->RemoveAll(true);
 112  *              delete pJsonObj;
 113  *      }
 114  * @endcode
 115  */
 116 class _OSP_EXPORT_ JsonObject
 117         : public IJsonValue
 118         , public Tizen::Base::Collection::HashMapT<const Tizen::Base::String*, IJsonValue*>
 119 {
 120 public:
 121         /**
 122          * The object is not fully constructed after this constructor is called. @n
 123          * For full construction, the Construct() method must be called right after calling this constructor.
 124          *
 125          * @since       2.0
 126          */
 127         JsonObject(void);
 128
 129         /**
 130          * This destructor overrides Tizen::Base::Object::~Object().
 131          *
 132          * @since       2.0
 133          */
 134         virtual ~JsonObject(void);
 135
 136         /**
 137          * Initializes this instance of %JsonObject.
 138          *
 139          * @since                       2.0
 140          *
 141          * @return      An error code
 142          * @exception   E_SUCCESS                       The method is successful.
 143          * @exception   E_SYSTEM                This exception exists only for historical reasons.
 144          */
 145         result Construct(void);
 146
 147         /**
 148          * Gets the type of the JSON object.
 149          *
 150          * @since               2.0
 151          *
 152          * @return      The type of the JSON object
 153          */
 154         JsonType GetType(void) const;
 155
 156         /**
 157          * Adds the specified key-value pair to a JSON object.
 158          *
 159          * @since           2.0
 160          *
 161          * @return              An error code
 162          * @param[in]   pKey                            A pointer to the key-value to add
 163          * @param[in]   pJsonValue                      A pointer to the value to add
 164          * @exception   E_SUCCESS                       The method is successful.
 165          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or the key comparison has failed.
 166          * @exception   E_OBJ_ALREADY_EXIST     The specified @c pKey already exists.
 167          * @see Remove()
 168          */
 169         virtual result Add(const Tizen::Base::String* const& pKey, Tizen::Web::Json::IJsonValue* const& pJsonValue);
 170
 171
 172         /**
 173          * Gets the value associated with a specified key.
 174          *
 175          * @since           2.0
 176          *
 177          * @return              The value associated with the key, @n
 178          *                              else @c null if an exception occurs
 179          * @param[in]   pKey                            A pointer to the key to locate
 180          * @param[out]  pJsonValue                      A pointer to the value associated with the key
 181          * @exception   E_SUCCESS                       The method is successful.
 182          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or the key comparison has failed.
 183          * @exception   E_OBJ_NOT_FOUND         The specified @c pKey is not found.
 184          * @see                 SetValue()
 185          */
 186         virtual result GetValue(const Tizen::Base::String* const& pKey, Tizen::Web::Json::IJsonValue*& pJsonValue) const;
 187
 188         /**
 189          * Checks whether a JSON object contains the specified value.
 190          *
 191          * @since           2.0
 192          *
 193          * @return              @c true if the JSON object contains the specified value, @n
 194          *                              else @c false
 195          * @param[in]   pJsonValue A pointer to the value to locate
 196          */
 197         virtual bool ContainsValue(IJsonValue* const& pJsonValue) const;
 198
 199         /**
 200          *      Checks whether the value of the specified instance equals the value of the current instance of %JsonObject.
 201          *
 202          *      @since          2.0
 203          *
 204          *      @return         @c true if the value of the current instance equals the value of the specified instance, @n
 205          *               else @c false
 206          *      @param[in]      obj     The object to compare @n
 207          *                  This object is compared with the current instance of %JsonObject.
 208          *      @remarks    This method returns @c false if the specified object is not of type JSON object.
 209          *  @see                Tizen::Base::Object::Equals()
 210          */
 211         virtual bool Equals(const Object& obj) const;
 212
 213         /**
 214          * Gets the hash value of the current instance.
 215          *
 216          * @since 2.0
 217          *
 218          * @return      An integer value indicating the hash value of the current instance
 219          * @remarks     The two equal instances must return the same hash value. For better performance,
 220          *              the used hash function must generate a random distribution for all inputs. @n
 221          *              The default implementation of this method returns the address of the current instance.
 222          */
 223         virtual int GetHashCode(void) const;
 224
 225         /**
 226          * Removes the value associated with a specified key.
 227          *
 228          * @since           2.0
 229          *
 230          * @return              An error code
 231          * @param[in]   pKey                A pointer to the key to remove
 232          * @exception   E_SUCCESS                       The method is successful.
 233          * @exception   E_INVALID_ARG           The specified input parameter is invalid, or the key comparison has failed.
 234          * @exception   E_OBJ_NOT_FOUND         The specified @c pKey is not found.
 235          */
 236         virtual result Remove(const Tizen::Base::String* const& pKey);
 237
 238         /**
 239          * Removes the value associated with a specified key.
 240          *
 241          * @since           2.0
 242          *
 243          * @return              An error code
 244          * @param[in]   pKey                A pointer to the key to remove
 245          * @param[in]   deallocate                      Set to @c true to deallocate the JSON value, @n
 246          *                                  else @c false
 247          * @exception   E_SUCCESS                       The method is successful.
 248          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or the key comparison has failed.
 249          * @exception   E_OBJ_NOT_FOUND         The specified @c pKey is not found.
 250          */
 251         virtual result Remove(const Tizen::Base::String* const& pKey, bool deallocate);
 252
 253         /**
 254          * Removes all the key-value pairs in %JsonObject.
 255          *
 256          * @since        2.0
 257          *
 258          * @param[in]   deallocate                      Set to @c true to deallocate the JSON value, @n
 259          *                                  else @c false
 260          */
 261         virtual void RemoveAll(bool deallocate = false);
 262
 263         /**
 264          * Sets a new value to a specified key.
 265          *
 266          * @since           2.0
 267          *
 268          * @return              An error code
 269          * @param[in]   pKey                            A pointer to the key for which the value is to replace
 270          * @param[in]   pJsonValue                      A pointer to the new value to set
 271          * @exception   E_SUCCESS                       The method is successful.
 272          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or the key comparison has failed.
 273          * @exception   E_OBJ_NOT_FOUND         The specified @c pKey is not found.
 274          * @remarks             Use the Add() method to add a new key-value pair.
 275          */
 276         virtual result SetValue(const Tizen::Base::String* const& pKey, Tizen::Web::Json::IJsonValue* const& pJsonValue);
 277
 278         /**
 279          * Sets a new value to a specified key.
 280          *
 281          * @since           2.0
 282          *
 283          * @return              An error code
 284          * @param[in]   pKey                            A pointer to the key for which the value is to replace
 285          * @param[in]   pJsonValue                      A pointer to the new value to set
 286          * @param[in]   deallocate                      Set to @c true to deallocate the JSON value, @n
 287          *                                  else @c false
 288          * @exception   E_SUCCESS                       The method is successful.
 289          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or the key comparison has failed.
 290          * @exception   E_OBJ_NOT_FOUND         The specified @c pKey is not found.
 291          * @remarks             Use the Add() method to add a new key-value pair.
 292          */
 293         virtual result SetValue(const Tizen::Base::String* const& pKey, Tizen::Web::Json::IJsonValue* const& pJsonValue, bool deallocate);
 294
 295         /**
 296          * Checks whether a JSON object contains the specified key.
 297          *
 298          * @since               2.0
 299          *
 300          * @return              An error code
 301          * @param[in]   pKey    The key to locate
 302          * @param[out]  out     @c true if the JSON object contains the specified key, @n
 303          *                                              else @c false
 304          * @exception   E_SUCCESS                       The method is successful.
 305          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or the key comparison has failed.
 306          */
 307         virtual result ContainsKey(const Tizen::Base::String* const& pKey, bool& out) const;
 308
 309         /**
 310          * Returns a new cloned %JsonObject instance.
 311          *
 312          * @since 2.0
 313          *
 314          * @return              A  new cloned %JsonObject or @c null if it fails to allocate the instance
 315          * @exception   E_SUCCESS                       The method is successful.
 316          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 317          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 318          */
 319         JsonObject* CloneN(void) const;
 320
 321 private:
 322         //
 323         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 324         //
 325         // @param[in]   item            The instance of the %JsonObject class to copy from
 326         // @remarks             This constructor is hidden.
 327         //
 328         JsonObject(const JsonObject& item);
 329
 330         //
 331         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 332         //
 333         // @param[in]   item            The instance of the %JsonObject class to assign from
 334         // @remarks             This operator is hidden.
 335         //
 336         JsonObject& operator =(const JsonObject& item);
 337
 338 private:
 339         _JsonObjectImpl* __pJsonObjectImpl;
 340         _JsonObjectComparer* __pJsonObjectComparer;
 341         _JsonObjectHashCodeProvider* __pJsonObjectHashCodeProvider;
 342         friend class _JsonObjectImpl;
 343 }; // JsonObject
 344
 345 }}} // Tizen::Web::Json
 346 #endif // _FWEB_JSON_JSON_OBJECT_H_
 347
 348 #ifdef __clang__
 349 #pragma clang diagnostic pop
 350 #endif