From: Minji Park Date: Thu, 1 Oct 2015 01:09:08 +0000 (+0900) Subject: Refine comments for android apis of resource-encapsulation. X-Git-Tag: 1.0.0-RC2~1 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=529d886aba18d95f1e983c63a0cbf9d960513832;p=contrib%2Fiotivity.git Refine comments for android apis of resource-encapsulation. Incorrect tags are fixed. Links for types and methods in comments are added for convenience. Change-Id: I8f4bbc31dfb4ead6b4b5fd0f80046002f8e80589 Signed-off-by: coderhyme Reviewed-on: https://gerrit.iotivity.org/gerrit/3189 Tested-by: jenkins-iotivity Reviewed-by: Madan Lanka Signed-off-by: Minji Park Reviewed-on: https://gerrit.iotivity.org/gerrit/3337 Reviewed-by: Uze Choi --- diff --git a/service/resource-encapsulation/android/SConscript b/service/resource-encapsulation/android/SConscript index 23a3951..689eec9 100644 --- a/service/resource-encapsulation/android/SConscript +++ b/service/resource-encapsulation/android/SConscript @@ -45,8 +45,7 @@ if not os.path.exists(android_home + '/platforms/android-21') or not os.path.exi def ensure_libs(target, source, env): return target, [source, env.get('BUILD_DIR') + 'librcs_server.so', - env.get('BUILD_DIR') + 'librcs_client.so', - env.get('BUILD_DIR') + 'librcs_container.so'] + env.get('BUILD_DIR') + 'librcs_client.so'] jdk_env = Environment(ENV=os.environ) jdk_env['BUILDERS']['Gradle'] = Builder(action = env.get('ANDROID_GRADLE') + diff --git a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/RcsResourceAttributes.java b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/RcsResourceAttributes.java index 41849a9..8151102 100644 --- a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/RcsResourceAttributes.java +++ b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/RcsResourceAttributes.java @@ -26,9 +26,11 @@ import java.util.HashSet; import java.util.Map; import java.util.Set; +import org.iotivity.service.server.RcsLockedAttributes; + /** * - * RCSResourceAttributes represents the attributes for a resource. + * This class represents the attributes for a resource. * * @see RcsValue */ @@ -55,6 +57,13 @@ public final class RcsResourceAttributes extends RcsObject { public RcsResourceAttributes() { } + public RcsResourceAttributes(RcsLockedAttributes lockedAttrs) + throws RcsException { + for (final String key : lockedAttrs.keySet()) { + mCache.put(key, lockedAttrs.get(key)); + } + } + /** * Returns a unmodifiable Set view of the keys contained in this attributes. * @@ -99,13 +108,15 @@ public final class RcsResourceAttributes extends RcsObject { * If the object previously contained a mapping for the key, the old value * is replaced by the specified value. * - * * @param key * key with which the specified value is to be associated * * @param value * value to be associated with the specified key * + * @throws NullPointerException + * if key or value is null + * */ public void put(String key, RcsValue value) { if (key == null) throw new NullPointerException("key is null"); @@ -115,7 +126,25 @@ public final class RcsResourceAttributes extends RcsObject { if (hasHandle()) nativeRemove(key); } + /** + * Sets the specified value with the specified key. + * If the object previously contained a mapping for the key, the old value + * is replaced by the specified value. + * + * @param key + * key with which the specified value is to be associated + * + * @param value + * value to be associated with the specified key + * + * @throws NullPointerException + * if key or value is null + * @throws IllegalArgumentException + * if object is not supported type by {@link RcsValue} + */ public void put(String key, Object object) { + if (key == null) throw new NullPointerException("key is null"); + put(key, new RcsValue(object)); } @@ -171,6 +200,9 @@ public final class RcsResourceAttributes extends RcsObject { * key whose presence is to be tested * * @return true if this contains a mapping for the specified key. + * + * @throws NullPointerException + * if key is null */ public boolean contains(String key) { if (key == null) throw new NullPointerException("key is null"); diff --git a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/RcsValue.java b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/RcsValue.java index 7e916fe..e1fd331 100644 --- a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/RcsValue.java +++ b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/RcsValue.java @@ -29,7 +29,7 @@ import java.util.Map; * * Type helps identify type information of Value. * - * @see RCSResourceAttributes + * @see RcsResourceAttributes * @see Type */ public final class RcsValue { @@ -53,8 +53,8 @@ public final class RcsValue { /** * A Helper class to identify types of Value. * - * @see RCSResourceAttributes - * @see Value + * @see RcsResourceAttributes + * @see RcsValue * @see TypeId */ public static class Type { @@ -69,9 +69,9 @@ public final class RcsValue { * * @return Identifier of type * - * @see getBaseTypeId + * @see #getBaseTypeId(RcsValue.Type) */ - public final TypeId getTypeId() { + public final TypeId getId() { return mTypeId; } @@ -86,7 +86,7 @@ public final class RcsValue { /** * Returns the type identifier of a base type of sequence. * - * For non sequence types, it is equivalent to calling getId. + * For non sequence types, it is equivalent to calling {@link #getId()}. * * @return identifier of type * @@ -110,11 +110,10 @@ public final class RcsValue { /** * Factory method to create Type instance from an object. + * Note that object must be a supported type by RcsValue. * * @return An instance that has TypeId for obj. * - * @note object must be a supported type by Value. - * * @throws NullPointerException * if obj is null. * @throws IllegalArgumentException @@ -130,12 +129,11 @@ public final class RcsValue { } /** - * Factory method to create Type instance from a clss. + * Factory method to create Type instance from a class. + * Note that class must be a supported type by RcsValue. * * @return An instance that has TypeId for class. * - * @note class must be a supported type by Value. - * * @throws NullPointerException * if cls is null. * @throws IllegalArgumentException @@ -257,7 +255,7 @@ public final class RcsValue { } /** - * Constructs a new value that holds null value. + * Constructs a new value that holds a boolean value. * * @param value * a boolean @@ -510,7 +508,7 @@ public final class RcsValue { } /** - * Returns the value it represents is null. + * Returns whether the value is null. * * @return true if the value is null. */ @@ -519,7 +517,7 @@ public final class RcsValue { } /** - * Returns the object represents null for RcsValue. + * Returns whether the object represents null for RcsValue. * * @param o * an object to be tested diff --git a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/client/RcsAddress.java b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/client/RcsAddress.java index 4864b81..af6faee 100644 --- a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/client/RcsAddress.java +++ b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/client/RcsAddress.java @@ -21,13 +21,9 @@ package org.iotivity.service.client; /** - * This class provides a set of APIs for constructing RCSAddress object. - * - *

- * RCSAddress object is the first parameter for Discover Resource APIs of - * RCSDiscoveryManager Class. - *

- * {@link RcsDiscoveryManager} + * This is to specify a target address to discover. + * + * @see RcsDiscoveryManager */ public final class RcsAddress { private final String mAddress; diff --git a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/client/RcsDiscoveryManager.java b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/client/RcsDiscoveryManager.java index 6e6e934..7e8c44f 100644 --- a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/client/RcsDiscoveryManager.java +++ b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/client/RcsDiscoveryManager.java @@ -45,6 +45,12 @@ public final class RcsDiscoveryManager { System.loadLibrary("rcs_jni"); } + /** + * This represents a task for discovery. + * + * The task must be canceled if no longer needed. + * + */ public static class DiscoveryTask extends RcsObject { private DiscoveryTask() { } @@ -92,6 +98,8 @@ public final class RcsDiscoveryManager { * * @param address * the target address + * @param listener + * the listener to be invoked when a resource is discovered * * @return a task object indicating this request. * @@ -114,7 +122,9 @@ public final class RcsDiscoveryManager { * the target address * @param uri * the relative uri of resource to be searched - * + * @param listener + * the listener to be invoked when a resource is discovered + * * @return a task object indicating this request. * * @throws RcsPlatformException @@ -135,6 +145,8 @@ public final class RcsDiscoveryManager { * the target address * @param resourceType * the resource type + * @param listener + * the listener to be invoked when a resource is discovered * * @return a task object indicating this request. * @@ -161,6 +173,8 @@ public final class RcsDiscoveryManager { * the relative uri of resource to be searched * @param resourceType * the resource type + * @param listener + * the listener to be invoked when a resource is discovered * * @return a task object indicating this request. * diff --git a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/client/RcsRemoteResourceObject.java b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/client/RcsRemoteResourceObject.java index 0577dab..df13696 100644 --- a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/client/RcsRemoteResourceObject.java +++ b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/client/RcsRemoteResourceObject.java @@ -27,7 +27,6 @@ import org.iotivity.service.RcsObject; import org.iotivity.service.RcsPlatformException; import org.iotivity.service.RcsResourceAttributes; import org.iotivity.service.RcsValue; -import org.iotivity.service.server.RcsResourceObject; /** * @@ -86,21 +85,29 @@ public final class RcsRemoteResourceObject extends RcsObject { /** * This represents states of monitoring. * - * @see #startMonitoring() + * @see #startMonitoring(OnStateChangedListener) * @see #getState() * @see OnStateChangedListener * */ public enum ResourceState { + /** Monitoring is not started. */ + NONE, + + /** + * Monitoring is started and checking state is in progress. + * This is the default state after startMonitoring. + */ + REQUESTED, + + /** The resource is alive. */ + ALIVE, - NONE, /** < Monitoring is not started. */ - REQUESTED, /** - * < Monitoring is started and checking state is in progress. - * This is the default state after startMonitoring. - */ - ALIVE, /** < The resource is alive. */ - LOST_SIGNAL, /** < Failed to reach the resource. */ - DESTROYED /** < The resource is deleted. */ + /** Failed to reach the resource. */ + LOST_SIGNAL, + + /** The resource is deleted. */ + DESTROYED } /** @@ -110,14 +117,20 @@ public final class RcsRemoteResourceObject extends RcsObject { * @see #getCacheState() */ public enum CacheState { + /** Caching is not started. */ + NONE, + + /** + * Caching is started, but the data is not ready yet. This is + * the default state after startCaching. + */ + UNREADY, - NONE, /** < Caching is not started. */ - UNREADY, /** - * < Caching is started, but the data is not ready yet. This is - * the default state after startCaching. - */ - READY, /** < The data is ready. */ - LOST_SIGNAL /** < Failed to reach the resource. */ + /** The data is ready. */ + READY, + + /** Failed to reach the resource. */ + LOST_SIGNAL } /** @@ -227,7 +240,7 @@ public final class RcsRemoteResourceObject extends RcsObject { * @throws RcsDestroyedObjectException * if the object is already destroyed * - * @see RcsResourceObject.Builder#setObservable(boolean) + * @see org.iotivity.service.server.RcsResourceObject.Builder#setObservable(boolean) */ public boolean isObservable() throws RcsException { assertAlive(); @@ -303,8 +316,9 @@ public final class RcsRemoteResourceObject extends RcsObject { * This will start data caching for the resource. Once caching started it * will look for the data updation on the resource and updates the cache * data accordingly. - * - * It is equivalent to calling startCaching(CacheUpdatedCallback) with null. + *

+ * It is equivalent to calling {@link #startCaching(OnCacheUpdatedListener)} + * with null. * * @throws RcsDestroyedObjectException * if the object is already destroyed @@ -386,8 +400,9 @@ public final class RcsRemoteResourceObject extends RcsObject { /** * Returns whether cached data is available. * - * Cache will be available always once cache state had been READY even if - * current state is LOST_SIGNAL. + * Cache will be available always once cache state had been + * {@link CacheState#READY} even if current state is + * {@link CacheState#LOST_SIGNAL} until stopped. * * @return true if cache data is available. * @@ -407,7 +422,8 @@ public final class RcsRemoteResourceObject extends RcsObject { /** * Returns the cached attributes. - * This works only when cache is available. + *

+ * Note that this works only when cache is available. * * @return the cached attributes. * @@ -431,9 +447,9 @@ public final class RcsRemoteResourceObject extends RcsObject { /** * Returns the cached value to which the specified key is mapped, or null if - * RcsResourceAttributes contains no mapping for the key. - * - * This works only when cache is available. + * no mapping for the key. + *

+ * Note that this works only when cache is available. * * @param key * the key whose associated value is to be returned @@ -466,7 +482,7 @@ public final class RcsRemoteResourceObject extends RcsObject { } /** - * Sends a request for the resource attributes directly to the server. + * Sends a request for the resource attributes directly to the resource. * * @param listener * the listener to receive the response @@ -491,8 +507,8 @@ public final class RcsRemoteResourceObject extends RcsObject { } /** - * Sends a set request with resource attributes to the server. - * + * Sends a set request with resource attributes to the resource. + *

* The SetRequest behavior depends on the server, whether updating its * attributes or not. * diff --git a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsGetResponse.java b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsGetResponse.java index 7809275..96dcd24 100644 --- a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsGetResponse.java +++ b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsGetResponse.java @@ -23,8 +23,7 @@ package org.iotivity.service.server; import org.iotivity.service.RcsResourceAttributes; /** - * This class provides methods to create the response for a received get - * request. + * This class provides methods to create the response for a get request. * * @see RcsResourceObject * @see RcsSetResponse @@ -32,9 +31,9 @@ import org.iotivity.service.RcsResourceAttributes; public class RcsGetResponse extends RcsResponse { /** - * Creates a default RcsResourceObject. The response will have - * RCSResponse.DEFAULT_ERROR_CODE for the errorCode. The attributes of - * RCSResourceObject will be set as the result attributes. + * Creates a default RCcsGetResponse. The response will have + * {@link #DEFAULT_ERROR_CODE} for the errorCode. The attributes of + * {@link RcsResourceObject} will be set as the result attributes. * */ public static RcsGetResponse defaultAction() { @@ -42,11 +41,12 @@ public class RcsGetResponse extends RcsResponse { } /** - * Creates a RcsResourceObject with error code passed. The - * attributes of the RCSResourceObject will be set as the result attributes. + * Creates a RcsGetResponse with error code passed. The + * attributes of the {@link RcsResourceObject} will be set as the result + * attributes. * * @param errorCode - * The error code to set in response. + * error code to be set in response * */ public static RcsGetResponse create(int errorCode) { @@ -55,12 +55,13 @@ public class RcsGetResponse extends RcsResponse { } /** - * Creates a RcsResourceObject with custom attributes. This sends the passed + * Creates a RcsGetResponse with custom attributes and + * {@link #DEFAULT_ERROR_CODE} for the errorCode. This sends the passed * attributes as the result attributes instead of the one the - * RCSResourceObject holds. + * {@link RcsResourceObject} holds. * * @param attributes - * The attributes to send in response. + * attributes to be sent as the result * */ public static RcsGetResponse create(RcsResourceAttributes attributes) { @@ -68,14 +69,14 @@ public class RcsGetResponse extends RcsResponse { } /** - * Creates a RcsResourceObject with error code passed. This sends + * Creates a RcsGetResponse with error code passed. This sends * the passed attributes as the result attributes instead of one the - * RCSResourceObject holds. + * {@link RcsResourceObject} holds. * * @param attributes - * The attributes to send in response. + * attributes to be sent as the result * @param errorCode - * The error code for response. + * error code for response * */ public static RcsGetResponse create(RcsResourceAttributes attributes, diff --git a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsLockedAttributes.java b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsLockedAttributes.java index 13381d2..67651ce 100644 --- a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsLockedAttributes.java +++ b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsLockedAttributes.java @@ -92,6 +92,15 @@ public final class RcsLockedAttributes extends RcsObject { } } + /** + * Returns a unmodifiable Set view of the keys contained in this attributes. + * + * @return an unmodifiable set view of the keys in this attributes + * + * @throws RcsUnlockedException + * if the {@link RcsResourceObject.AttributesLock} for this + * object is unlocked + */ public Set keySet() throws RcsException { ensureLocked(); @@ -102,6 +111,22 @@ public final class RcsLockedAttributes extends RcsObject { return Collections.unmodifiableSet(keySet); } + /** + * Returns the value to which the specified key is mapped, or null if this + * contains no mapping for the key. + * + * @param key + * the key whose associated value is to be returned + * + * @return the value to which the specified key is mapped, or null if this + * contains no mapping for the key + * + * @throws NullPointerException + * if key is null + * @throws RcsUnlockedException + * if the {@link RcsResourceObject.AttributesLock} for this + * object is unlocked + */ public RcsValue get(String key) throws RcsException { ensureLocked(); @@ -113,7 +138,21 @@ public final class RcsLockedAttributes extends RcsObject { return mCache.get(key); } - public RcsLockedAttributes putAll(RcsResourceAttributes attributes) { + /** + * Copies all of the mappings from the specified to this + * + * @param attributes + * attributes to be copied + * + * @throws RcsUnlockedException + * if the {@link RcsResourceObject.AttributesLock} for this + * object is unlocked + * + */ + public RcsLockedAttributes putAll(RcsResourceAttributes attributes) + throws RcsException { + ensureLocked(); + final Set keys = attributes.keySet(); for (final String k : keys) { @@ -123,13 +162,21 @@ public final class RcsLockedAttributes extends RcsObject { } /** - * set a attribute value. + * Sets the specified value with the specified key. + * If the object previously contained a mapping for the key, the old value + * is replaced by the specified value. * * @param key - * - Key of the element to be added. + * key with which the specified value is to be associated * * @param value - * - value to be set. + * value to be associated with the specified key + * + * @throws NullPointerException + * if key or value is null + * @throws RcsUnlockedException + * if the {@link RcsResourceObject.AttributesLock} for this + * object is unlocked * */ public RcsLockedAttributes put(String key, RcsValue value) @@ -145,9 +192,36 @@ public final class RcsLockedAttributes extends RcsObject { } /** + * Sets the specified value with the specified key. + * If the object previously contained a mapping for the key, the old value + * is replaced by the specified value. + * + * @param key + * key with which the specified value is to be associated + * + * @param value + * value to be associated with the specified key + * + * @throws NullPointerException + * if key or value is null + * @throws IllegalArgumentException + * if object is not supported type by {@link RcsValue} + * @throws RcsUnlockedException + * if the {@link RcsResourceObject.AttributesLock} for this + * object is unlocked + */ + public void put(String key, Object value) throws RcsException { + if (key == null) throw new NullPointerException("key is null"); + + put(key, new RcsValue(value)); + } + + /** * Returns whether attribute is empty. * - * @return boolean + * @throws RcsUnlockedException + * if the {@link RcsResourceObject.AttributesLock} for this + * object is unlocked */ public boolean isEmpty() throws RcsException { ensureLocked(); @@ -156,8 +230,11 @@ public final class RcsLockedAttributes extends RcsObject { } /** - * Returns the number of elements. + * Returns the number of key-value mappings. * + * @throws RcsUnlockedException + * if the {@link RcsResourceObject.AttributesLock} for this + * object is unlocked */ public int size() throws RcsException { ensureLocked(); @@ -166,12 +243,16 @@ public final class RcsLockedAttributes extends RcsObject { } /** - * Removes a single attribute + * Removes the mapping for a key from this attributes if it is present. * * @param key - * Key to be removed. + * key whose mapping is to be removed + * + * @return true if the key is present and the the value mapped is removed. * - * @return true if an attribute is removed, false otherwise. + * @throws RcsUnlockedException + * if the {@link RcsResourceObject.AttributesLock} for this + * object is unlocked */ public boolean remove(String key) throws RcsException { ensureLocked(); @@ -185,18 +266,32 @@ public final class RcsLockedAttributes extends RcsObject { return cacheRemove || nativeRemove; } - public void clear() { + /** + * Removes all elements. + * + * @throws RcsUnlockedException + * if the {@link RcsResourceObject.AttributesLock} for this + * object is unlocked + */ + public void clear() throws RcsException { + ensureLocked(); + nativeClear(mResourceObject); } /** - * Checks the container has an attribute with a Key equivalent to the - * provided key. + * Returns true if this contains a mapping for the specified key. * * @param key - * Key to check. + * key whose presence is to be tested + * + * @return true if this contains a mapping for the specified key. * - * @return true if an attribute with requests key exists, false otherwise. + * @throws NullPointerException + * if key is null + * @throws RcsUnlockedException + * if the {@link RcsResourceObject.AttributesLock} for this + * object is unlocked */ public boolean contains(String key) throws RcsException { ensureLocked(); diff --git a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsResponse.java b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsResponse.java index 0311553..73e876f 100644 --- a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsResponse.java +++ b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsResponse.java @@ -22,7 +22,7 @@ package org.iotivity.service.server; import org.iotivity.service.RcsResourceAttributes; -public class RcsResponse { +class RcsResponse { private native static int nativeGetDefaultErrorCode(); public static final int DEFAULT_ERROR_CODE; diff --git a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsSetResponse.java b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsSetResponse.java index 95fbd2e..266501d 100644 --- a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsSetResponse.java +++ b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsSetResponse.java @@ -33,14 +33,12 @@ public final class RcsSetResponse extends RcsResponse { /** * Options for handling a set request. * - * This overrides RcsResourceObject#SetRequestHandlerPolicy. - * - * @see RcsResourceObject#SetRequestHandlerPolicy + * This overrides {@link RcsResourceObject.SetRequestHandlerPolicy}. * */ public enum AcceptanceMethod { /** - * Follow RcsResourceObject#SetRequestHandlerPolicy. + * Follow {@link RcsResourceObject.SetRequestHandlerPolicy}. */ DEFAULT, @@ -59,9 +57,10 @@ public final class RcsSetResponse extends RcsResponse { private AcceptanceMethod mAcceptanceMethod = AcceptanceMethod.DEFAULT; /** - * Creates a default RCSSetResponse with DEFAULT acceptance method. The - * response will have RCSResponse.DEFAULT_ERROR_CODE for the errorCode. The - * attributes of RCSResourceObject will be set as the result attributes. + * Creates a default RcsSetResponse with {@link AcceptanceMethod#DEFAULT}. + * The response will have {@link #DEFAULT_ERROR_CODE} for the errorCode. The + * attributes of {@link RcsResourceObject} will be set as the result + * attributes. * */ public static RcsSetResponse defaultAction() { @@ -69,9 +68,10 @@ public final class RcsSetResponse extends RcsResponse { } /** - * Creates a default RCSSetResponse with ACCEPT acceptance method. The - * response will have RCSResponse.DEFAULT_ERROR_CODE for the errorCode. The - * attributes of RCSResourceObject will be set as the result attributes. + * Creates a default RcsSetResponse with {@link AcceptanceMethod#ACCEPT} + * The response will have {@link #DEFAULT_ERROR_CODE} for the errorCode. The + * attributes of {@link RcsResourceObject} will be set as the result + * attributes. * */ public static RcsSetResponse accept() { @@ -80,13 +80,13 @@ public final class RcsSetResponse extends RcsResponse { } /** - * Creates a RCSSetResponse with ACCEPT acceptance method and error code - * passed. - * The attributes of the RCSResourceObject will be set as the result + * Creates a RcsSetResponse with {@link AcceptanceMethod#ACCEPT} and error + * code passed. + * The attributes of the {@link RcsResourceObject} will be set as the result * attributes. * * @param errorCode - * The error code to set in response. + * error code to be set in response * */ public static RcsSetResponse accept(int errorCode) { @@ -95,9 +95,10 @@ public final class RcsSetResponse extends RcsResponse { } /** - * Creates a default RCSSetResponse with IGNORE acceptance method. The - * response will have RCSResponse.DEFAULT_ERROR_CODE for the errorCode. The - * attributes of RCSResourceObject will be set as the result attributes. + * Creates a default RcsSetResponse with {@link AcceptanceMethod#IGNORE}. + * The response will have {@link #DEFAULT_ERROR_CODE} for the errorCode. The + * attributes of {@link RcsResourceObject} will be set as the result + * attributes. * */ public static RcsSetResponse ignore() { @@ -106,12 +107,12 @@ public final class RcsSetResponse extends RcsResponse { } /** - * Creates a RCSSetResponse with IGNORE acceptance method and - * error code passed. The attributes of the RCSResourceObject will be set as - * the result attributes. + * Creates a RcsSetResponse with {@link AcceptanceMethod#IGNORE} and error + * code passed. The attributes of the {@link RcsResourceObject} will be set + * as the result attributes. * * @param errorCode - * The error code to set in response. + * error code to be set in response * */ public static RcsSetResponse ignore(int errorCode) { @@ -120,12 +121,12 @@ public final class RcsSetResponse extends RcsResponse { } /** - * Creates a RCSSetResponse with error code passed and has - * DEFAULT acceptance method. The attributes of the RCSResourceObject will - * be set as the result attributes. + * Creates a RcsSetResponse with error code passed and + * {@link AcceptanceMethod#DEFAULT}. The attributes of the + * {@link RcsResourceObject} will be set as the result attributes. * * @param errorCode - * The error code to set in response. + * error code to be set in response * */ public static RcsSetResponse create(int errorCode) { @@ -133,12 +134,12 @@ public final class RcsSetResponse extends RcsResponse { } /** - * Creates a RCSSetResponse with custom attributes and has DEFAULT - * acceptance method. This sends the passed attributes as the result - * attributes instead of one the RCSResourceObject holds. + * Creates a RcsSetResponse with custom attributes and + * {@link AcceptanceMethod#DEFAULT}. This sends the passed attributes as the + * result attributes instead of one the {@link RcsResourceObject} holds. * * @param attributes - * The attributes to send in response. + * attributes to be sent as the result * */ public static RcsSetResponse create(RcsResourceAttributes attributes) { @@ -146,6 +147,22 @@ public final class RcsSetResponse extends RcsResponse { } /** + * Creates a RcsSetResponse with error code passed and + * {@link AcceptanceMethod#DEFAULT}. This sends the passed attributes as the + * result attributes instead of one the {@link RcsResourceObject} holds. + * + * @param attributes + * attributes to be sent as the result + * @param errorCode + * error code for response + * + */ + public static RcsSetResponse create(RcsResourceAttributes attributes, + int errorCode) { + return new RcsSetResponse(attributes, errorCode); + } + + /** * Returns the acceptance method. * */ @@ -154,12 +171,12 @@ public final class RcsSetResponse extends RcsResponse { } /** - * Sets the acceptance method for the RCSSetResponse. + * Sets the acceptance method. * * @param method - * AcceptanceMethod value to set + * method to be set * - * @return The reference to this RCSSetResponse + * @return The reference to this RcsSetResponse * */ public RcsSetResponse setAcceptanceMethod(AcceptanceMethod method) { @@ -167,22 +184,6 @@ public final class RcsSetResponse extends RcsResponse { return this; } - /** - * Creates a RCSSetResponse with error code passed. This sends - * the passed attributes as the result attributes instead of one the - * RCSResourceObject holds. - * - * @param attributes - * The attributes to send in response. - * @param errorCode - * The error code for response. - * - */ - public static RcsSetResponse create(RcsResourceAttributes attributes, - int errorCode) { - return new RcsSetResponse(attributes, errorCode); - } - private RcsSetResponse() { super(); } diff --git a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsUnlockedException.java b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsUnlockedException.java index 143ac35..d23975e 100644 --- a/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsUnlockedException.java +++ b/service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/server/RcsUnlockedException.java @@ -3,7 +3,7 @@ package org.iotivity.service.server; import org.iotivity.service.RcsException; /** - * Thrown when trying to access a unlocked RcsLockedAttributes. + * Thrown when trying to access a unlocked {@link RcsLockedAttributes}. * */ public class RcsUnlockedException extends RcsException { diff --git a/service/resource-encapsulation/android/service/src/main/jni/JniRcsResourceAttributes.cpp b/service/resource-encapsulation/android/service/src/main/jni/JniRcsResourceAttributes.cpp index 405468d..4e02d77 100644 --- a/service/resource-encapsulation/android/service/src/main/jni/JniRcsResourceAttributes.cpp +++ b/service/resource-encapsulation/android/service/src/main/jni/JniRcsResourceAttributes.cpp @@ -224,7 +224,7 @@ JNIEXPORT void JNICALL Java_org_iotivity_service_RcsResourceAttributes_nativeAdd JNIEXPORT jobject JNICALL Java_org_iotivity_service_RcsResourceAttributes_nativeExtract (JNIEnv* env, jobject obj, jstring keyObj) { - LOGD("extractAsJavaObject"); + LOGD("extract"); EXPECT_RET_DEF(keyObj, "Key is null."); EXPECT_RET_DEF(hasNativeHandle(env, obj), "no native handle."); @@ -240,6 +240,7 @@ JNIEXPORT jobject JNICALL Java_org_iotivity_service_RcsResourceAttributes_native VERIFY_NO_EXC_RET_DEF(env); attrs.erase(key); + if (attrs.empty()) releaseNativeHandle(env, obj); return valueObj; } diff --git a/service/resource-encapsulation/include/RCSResourceAttributes.h b/service/resource-encapsulation/include/RCSResourceAttributes.h index 7ebbc4d..d20985e 100644 --- a/service/resource-encapsulation/include/RCSResourceAttributes.h +++ b/service/resource-encapsulation/include/RCSResourceAttributes.h @@ -523,7 +523,7 @@ namespace OIC bool erase(const std::string& key); /** - * Checks the container has an element with a Key equivalent to key. + * Checks this contains an element for the specified key. * * @param key Key to check. * diff --git a/service/resource-encapsulation/include/RCSResourceObject.h b/service/resource-encapsulation/include/RCSResourceObject.h index b5e6a51..40044c6 100644 --- a/service/resource-encapsulation/include/RCSResourceObject.h +++ b/service/resource-encapsulation/include/RCSResourceObject.h @@ -113,7 +113,7 @@ namespace OIC NEVER, /**< Requests will be ignored if attributes of the request contain a new key or a value that has different type from the current value of the key. */ - ACCEPTANCE /**< The whole attributes of the request will be applied + ACCEPTANCE /**< The attributes of the request will be applied unconditionally even if there are new name or type conflicts. */ }; @@ -143,7 +143,7 @@ namespace OIC /** * Sets whether the resource is discoverable. * - * @param discoverable whether to be discovered. + * @param discoverable whether to be discoverable. * */ Builder& setDiscoverable(bool discoverable); @@ -151,13 +151,13 @@ namespace OIC /** * Sets the observable property of the resource. * - * @param observable whether to be observed. + * @param observable whether to be observable. * */ Builder& setObservable(bool observable); /** - * Sets attribute of the resource. + * Sets attributes for the resource. * * @param attributes attributes to set * @@ -344,12 +344,12 @@ namespace OIC const RCSResourceAttributes& getAttributes() const; /** - * Checks whether the particular resource is observable or not. + * Checks whether the resource is observable or not. */ virtual bool isObservable() const; /** - * Checks whether the particular resource is discoverable or not. + * Checks whether the resource is discoverable or not. */ virtual bool isDiscoverable() const; @@ -357,7 +357,7 @@ namespace OIC * Sets the get request handler. * To remove handler, pass empty handler or nullptr. * - * Default behavior is RCSGetResponse::defaultAction() + * Default behavior is RCSGetResponse::defaultAction(). * * @param handler a get request handler * @@ -370,7 +370,7 @@ namespace OIC * Sets the set request handler. * To remove handler, pass empty handler or nullptr. * - * Default behavior is RCSGetResponse::defaultAction() + * Default behavior is RCSSetResponse::defaultAction(). * * @param handler a set request handler * @@ -380,7 +380,7 @@ namespace OIC virtual void setSetRequestHandler(SetRequestHandler handler); /** - * Adds a listener for a particular attribute update. + * Adds a listener for a particular attribute updated. * * @param key the interested attribute's key * @param listener listener to be invoked @@ -396,9 +396,11 @@ namespace OIC AttributeUpdatedListener listener); /** - * Removes a listener for a particular attribute update. + * Removes a listener for a particular attribute updated. * - * @param key the key to be removed + * @param key the key associated with the listener to be removed + * + * @return True if the listener added with same key exists and is removed. * */ virtual bool removeAttributeUpdatedListener(const std::string& key); @@ -488,7 +490,7 @@ namespace OIC }; /** - * The class provides a convinent RAII-style mechanism for the attributes of a + * The class provides a convenient RAII-style mechanism for the attributes of a * RCSResourceObject. When a LockGuard is created, it attempts to lock the attributes of * the RCSResourceObject it is given. When control leaves the scope in which the LockGuard * object was created, the LockGuard is destructed and the attributes is unlocked.