Updated api description for the client side of RE. 45/5245/4
authorcoderhyme <jhyo.kim@samsung.com>
Mon, 29 Feb 2016 00:30:29 +0000 (16:30 -0800)
committerJungHo Kim <jhyo.kim@samsung.com>
Mon, 29 Feb 2016 07:39:55 +0000 (07:39 +0000)
Change-Id: I52babb04f0568dfcac22f176774111dc5033284a
Signed-off-by: coderhyme <jhyo.kim@samsung.com>
Reviewed-on: https://gerrit.iotivity.org/gerrit/5245
Tested-by: jenkins-iotivity <jenkins-iotivity@opendaylight.org>
Reviewed-by: Uze Choi <uzchoi@samsung.com>
service/resource-encapsulation/include/RCSDiscoveryManager.h
service/resource-encapsulation/include/RCSRemoteResourceObject.h
service/resource-encapsulation/src/resourceClient/RCSRemoteResourceObject.cpp
service/resource-encapsulation/unittests/ResourceClientTest.cpp

index 18572b5..71b260a 100644 (file)
@@ -102,7 +102,7 @@ namespace OIC
 
             /**
              * Discovers resources of interest, regardless of uri and resource type.
-             * It is Consistently discovering resources until the discovery task is canceled.
+             * It will consistently discover resources until the discovery task is canceled.
              *
              * @param address         A RCSAddress object
              * @param cb              A callback to obtain discovered resource
@@ -117,7 +117,7 @@ namespace OIC
 
             /**
              * Discovers resources of interest, regardless of resource type.
-             * It is Consistently discovering resources until the discovery task is canceled.
+             * It will consistently discover resources until the discovery task is canceled.
              *
              * @param address          A RCSAddress object
              * @param relativeUri      The relative uri of resource to be searched
@@ -133,7 +133,7 @@ namespace OIC
 
             /**
              * Discovers resources of interest by resource type.
-             * It is Consistently discovering resources until the discovery task is canceled.
+             * It will consistently discover resources until the discovery task is canceled.
              *
              * @param address          A RCSAddress object
              * @param resourceType     Resource Type
@@ -148,16 +148,16 @@ namespace OIC
                     const std::string& resourceType, ResourceDiscoveredCallback cb);
 
             /**
-             * Discovers resources of interest by resource type.
-             * It is Consistently discovering resources until the discovery task is canceled.
+             * Discovers resources of interest by resource types.
+             * It will consistently discover resources until the discovery task is canceled.
              *
              * @param address          A RCSAddress object
              * @param resourceTypes    List of Resource Types
              * @param cb               A callback to obtain discovered resource
              *
              * @throws InvalidParameterException If cb is empty.
-             * @throws InvalidParameterException If resourceType's size is than 2,
-             * at least one of resource type is empty.
+             * @throws RCSBadRequestException If resourceTypes contain more than one element and
+             * any of them is empty.
              *
              * @note The callback will be invoked in an internal thread.
              * @note If resourceTypes is empty, discovers resource by all resource types.
@@ -168,8 +168,8 @@ namespace OIC
                     ResourceDiscoveredCallback cb);
 
             /**
-             * Discovers resources of interest by resource types with provided relativeUri.
-             * It is Consistently discovering resources until the discovery task is canceled.
+             * Discovers resources of interest by a resource type with provided relativeUri.
+             * It will consistently discover resources until the discovery task is canceled.
              *
              * @param address          A RCSAddress object
              * @param relativeUri      The relative uri of resource to be searched
@@ -187,7 +187,7 @@ namespace OIC
 
             /**
              * Discovers resources of interest by resource types with provided relativeUri.
-             * It is Consistently discovering resources until the discovery task is canceled.
+             * It will consistently discover resources until the discovery task is canceled.
              *
              * @param address          A RCSAddress object
              * @param relativeUri      The relative uri of resource to be searched
@@ -195,8 +195,8 @@ namespace OIC
              * @param cb               A callback to obtain discovered resource
              *
              * @throws InvalidParameterException If cb is empty.
-             * @throws InvalidParameterException If resourceType's size is than 2,
-             * at least one of resource type is empty.
+             * @throws RCSBadRequestException If resourceTypes contain more than one element and
+             * any of them is empty.
              *
              * @note The callback will be invoked in an internal thread.
              * @note If resourceTypes is empty, discovers resource by all resource types.
index 5960766..5a27f0a 100644 (file)
@@ -83,27 +83,65 @@ namespace OIC
 
         class PrimitiveResource;
 
+        /**
+         * This is to specify query parameters for requests to the server.
+         *
+         * @see RCSRemoteResourceObject
+         */
         class RCSQueryParams
         {
         public:
             typedef std::unordered_map< std::string, std::string > Map;
 
         public:
-            RCSQueryParams& setResourceInterface(const std::string&);
-            RCSQueryParams& setResourceInterface(std::string&&);
 
-            RCSQueryParams& setResuorceType(const std::string&);
-            RCSQueryParams& setResuorceType(std::string&&);
+            /**
+             * Sets an interface of the resource to operate on
+             *
+             * @param interface interface
+             */
+            RCSQueryParams& setResourceInterface(std::string interface);
+
+            /**
+             * Sets a resource type of the resource to operate on
+             *
+             * @param type resource type
+             */
+            RCSQueryParams& setResourceType(std::string type);
 
-            RCSQueryParams& put(const std::string&, const std::string&);
-            RCSQueryParams& put(std::string&&, std::string&&);
-            RCSQueryParams& put(const std::string&, std::string&&);
-            RCSQueryParams& put(std::string&&, const std::string&);
+            /**
+             * Sets a resource type of the resource to operate on
+             *
+             * @param key key to be inserted
+             * @param value value to be inserted
+             *
+             * @note "rt" and "if" are reserved, so you should avoid them as a key.
+             *
+             */
+            RCSQueryParams& put(std::string key, std::string value);
 
+            /**
+             * Returns the resource interface.
+             */
             std::string getResourceInterface() const;
+
+            /**
+             * Returns the resource type.
+             */
             std::string getResourceType() const;
-            std::string get(const std::string&) const;
 
+            /**
+             * Returns a value.
+             *
+             * @param key key of the element whose mapped value is accessed.
+             *
+             * @throws InvalidKeyException If @a key doesn't match the key of any value.
+             */
+            std::string get(const std::string& key) const;
+
+            /**
+             * Returns all params.
+             */
             const Map& getAll() const;
 
         private:
@@ -156,8 +194,17 @@ namespace OIC
             typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
                 RemoteAttributesGetCallback;
 
-            typedef std::function< void(const HeaderOpts&, const RCSRepresentation& rep, int eCode) >
-                GetCallback;
+            /**
+             * Callback definition to be invoked when the response of get is received.
+             *
+             * @param HeaderOpts
+             * @param rep the result representation
+             * @param eCode the error code received from the resource
+             *
+             * @see get
+             */
+            typedef std::function< void(const HeaderOpts& headerOpts,
+                    const RCSRepresentation& rep, int eCode) > GetCallback;
 
             /**
              * Callback definition to be invoked when the response of setRemoteAttributes is
@@ -168,11 +215,20 @@ namespace OIC
              *
              * @see setRemoteAttributes
              */
-            typedef std::function< void(const RCSResourceAttributes&, int) >
+            typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
                 RemoteAttributesSetCallback;
 
-            typedef std::function< void(const HeaderOpts&, const RCSRepresentation& rep, int eCode) >
-                SetCallback;
+            /**
+             * Callback definition to be invoked when the response of set is received.
+             *
+             * @param HeaderOpts
+             * @param rep the result representation
+             * @param eCode the error code received from the resource
+             *
+             * @see set
+             */
+            typedef std::function< void(const HeaderOpts& headerOpts,
+                    const RCSRepresentation& rep, int eCode) > SetCallback;
 
         private:
             typedef int CacheID;
@@ -185,7 +241,13 @@ namespace OIC
 
             ~RCSRemoteResourceObject();
 
-            static RCSRemoteResourceObject::Ptr fromOCResource(std::shared_ptr< OC::OCResource >);
+            /**
+             * Creates an instance from an OCResource instance.
+             *
+             * @throw RCSInvalidParameterException If ocResource is nullptr.
+             */
+            static RCSRemoteResourceObject::Ptr fromOCResource(
+                    std::shared_ptr< OC::OCResource > ocResource);
 
             /**
              * Returns whether monitoring is enabled.
@@ -351,19 +413,41 @@ namespace OIC
              * Gets resource attributes directly from the server.
              *
              * This API send a get request to the resource of interest and provides
-             * the attributes to the caller in the RemoteAttributesReceivedCallback.
+             * the attributes to the caller in the RemoteAttributesGetCallback.
              *
              * @throws PlatformException If the operation failed
              * @throws InvalidParameterException If cb is an empty function or null.
              *
-             * @see RCSResourceAttributes::Value
-             *
              * @note The callback will be invoked in an internal thread.
              */
             void getRemoteAttributes(RemoteAttributesGetCallback cb);
 
+            /**
+             * Gets resource representation with empty query parameters directly from the server.
+             *
+             * @param cb A callback to receive the response.
+             *
+             * @throws PlatformException If the operation failed
+             * @throws InvalidParameterException If cb is an empty function or null.
+             *
+             * @note The callback will be invoked in an internal thread.
+             */
             void get(GetCallback cb);
-            void get(const RCSQueryParams&, GetCallback cb);
+
+            /**
+             * Gets resource representation directly from the server.
+             *
+             * The response could be different by the query parameters, it depends on server.
+             *
+             * @param queryParams Query parameters
+             * @param cb A callback to receive the response.
+             *
+             * @throws PlatformException If the operation failed
+             * @throws InvalidParameterException If cb is an empty function or null.
+             *
+             * @note The callback will be invoked in an internal thread.
+             */
+            void get(const RCSQueryParams& queryParams, GetCallback cb);
 
             /**
              * Sends a set request with resource attributes to the server.
@@ -384,8 +468,43 @@ namespace OIC
             void setRemoteAttributes(const RCSResourceAttributes& attributes,
                     RemoteAttributesSetCallback cb);
 
+            /**
+             * Sends a set request with resource attributes to the server.
+             *
+             * The SetRequest behavior depends on query parameters and the server.
+             *
+             * @param attributes Attributes to set
+             * @param cb A callback to receive the response.
+             *
+             * @throws PlatformException If the operation failed
+             * @throws InvalidParameterException If cb is an empty function or null.
+             *
+             * @see RCSResourceObject
+             * @see RCSResourceObject::SetRequestHandlerPolicy
+             *
+             * @note The callback will be invoked in an internal thread.
+             */
             void set(const RCSResourceAttributes& attributes, SetCallback cb);
-            void set(const RCSQueryParams&, const RCSResourceAttributes& attributes,  SetCallback cb);
+
+            /**
+             * Sends a set request with resource attributes to the server.
+             *
+             * The SetRequest behavior depends on query parameters and the server.
+             *
+             * @param queryParams Query parameters
+             * @param attributes Attributes to set
+             * @param cb A callback to receive the response.
+             *
+             * @throws PlatformException If the operation failed
+             * @throws InvalidParameterException If cb is an empty function or null.
+             *
+             * @see RCSResourceObject
+             * @see RCSResourceObject::SetRequestHandlerPolicy
+             *
+             * @note The callback will be invoked in an internal thread.
+             */
+            void set(const RCSQueryParams& queryParams, const RCSResourceAttributes& attributes,
+                    SetCallback cb);
 
             /**
              * Returns the uri of the resource.
index f87bce5..54e7ce8 100644 (file)
@@ -121,54 +121,24 @@ namespace OIC
     namespace Service
     {
 
-        RCSQueryParams& RCSQueryParams::setResourceInterface(const std::string& resourceInterface)
-        {
-            m_resourceInterface = resourceInterface;
-            return *this;
-        }
-
-        RCSQueryParams& RCSQueryParams::setResourceInterface(std::string&& resourceInterface)
+        RCSQueryParams& RCSQueryParams::setResourceInterface(std::string resourceInterface)
         {
             m_resourceInterface = std::move(resourceInterface);
             return *this;
         }
 
-        RCSQueryParams& RCSQueryParams::setResuorceType(const std::string& resourceType)
-        {
-            m_resourceType = resourceType;
-            return *this;
-        }
-
-        RCSQueryParams& RCSQueryParams::setResuorceType(std::string&& resourceType)
+        RCSQueryParams& RCSQueryParams::setResourceType(std::string resourceType)
         {
             m_resourceType = std::move(resourceType);
             return *this;
         }
 
-        RCSQueryParams& RCSQueryParams::put(const std::string& key, const std::string& value)
-        {
-            m_map[key] = value;
-            return *this;
-        }
-
-        RCSQueryParams& RCSQueryParams::put(std::string&& key, std::string&& value)
+        RCSQueryParams& RCSQueryParams::put(std::string key, std::string value)
         {
             m_map[std::move(key)] = std::move(value);
             return *this;
         }
 
-        RCSQueryParams& RCSQueryParams::put(const std::string& key, std::string&& value)
-        {
-            m_map[key] = std::move(value);
-            return *this;
-        }
-
-        RCSQueryParams& RCSQueryParams::put(std::string&& key, const std::string& value)
-        {
-            m_map[std::move(key)] = value;
-            return *this;
-        }
-
         std::string RCSQueryParams::getResourceInterface() const
         {
             return m_resourceInterface;
@@ -181,7 +151,14 @@ namespace OIC
 
         std::string RCSQueryParams::get(const std::string& key) const
         {
-            return m_map.at(key);
+            try
+            {
+                return m_map.at(key);
+            }
+            catch (const std::out_of_range&)
+            {
+                throw RCSInvalidKeyException(key + " is an invalid key");
+            }
         }
 
         const RCSQueryParams::Map& RCSQueryParams::getAll() const
@@ -191,8 +168,8 @@ namespace OIC
 
 
         RCSRemoteResourceObject::RCSRemoteResourceObject(
-                std::shared_ptr< PrimitiveResource > pResource) :
-                m_primitiveResource{ pResource },
+                std::shared_ptr< PrimitiveResource > primtiveResource) :
+                m_primitiveResource{ primtiveResource },
                 m_cacheId{ },
                 m_brokerId{ }
         {
@@ -435,8 +412,6 @@ namespace OIC
 
             const auto& paramMap = queryParams.getAll();
 
-            std::cout << queryParams.getResourceInterface() << "??\n";
-
             m_primitiveResource->requestGetWith(
                     queryParams.getResourceType(), queryParams.getResourceInterface(),
                     OC::QueryParamsMap{ paramMap.begin(), paramMap.end() },
index 5c47717..341d365 100644 (file)
@@ -177,7 +177,7 @@ TEST_F(RemoteResourceObjectTest, QueryParamsForGetWillBePassedToBase)
     constexpr char PARAM_KEY[] { "aKey" };
     constexpr char VALUE[] { "value" };
 
-    object->get(RCSQueryParams().setResourceInterface(RESOURCEINTERFACE).setResuorceType(RESOURCETYPE).
+    object->get(RCSQueryParams().setResourceInterface(RESOURCEINTERFACE).setResourceType(RESOURCETYPE).
             put(PARAM_KEY, VALUE),
             [](const HeaderOpts&, const RCSRepresentation&, int){});