Incorrect tags are fixed.
Links for types and methods in comments are added for convenience.
Change-Id: I8f4bbc31dfb4ead6b4b5fd0f80046002f8e80589
Signed-off-by: coderhyme <jhyo.kim@samsung.com>
Reviewed-on: https://gerrit.iotivity.org/gerrit/3189
Tested-by: jenkins-iotivity <jenkins-iotivity@opendaylight.org>
Reviewed-by: Madan Lanka <lanka.madan@samsung.com>
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') +
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
*/
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.
*
* 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");
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));
}
* 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");
*
* Type helps identify type information of Value.
*
- * @see RCSResourceAttributes
+ * @see RcsResourceAttributes
* @see Type
*/
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 {
*
* @return Identifier of type
*
- * @see getBaseTypeId
+ * @see #getBaseTypeId(RcsValue.Type)
*/
- public final TypeId getTypeId() {
+ public final TypeId getId() {
return mTypeId;
}
/**
* 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
*
/**
* 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
}
/**
- * 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
}
/**
- * Constructs a new value that holds null value.
+ * Constructs a new value that holds a boolean value.
*
* @param value
* a boolean
}
/**
- * Returns the value it represents is null.
+ * Returns whether the value is null.
*
* @return true if the value is null.
*/
}
/**
- * Returns the object represents null for RcsValue.
+ * Returns whether the object represents null for RcsValue.
*
* @param o
* an object to be tested
package org.iotivity.service.client;
/**
- * This class provides a set of APIs for constructing RCSAddress object.
- *
- * <p>
- * RCSAddress object is the first parameter for Discover Resource APIs of
- * RCSDiscoveryManager Class.
- * <p>
- * {@link RcsDiscoveryManager}
+ * This is to specify a target address to discover.
+ *
+ * @see RcsDiscoveryManager
*/
public final class RcsAddress {
private final String mAddress;
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() {
}
*
* @param address
* the target address
+ * @param listener
+ * the listener to be invoked when a resource is discovered
*
* @return a task object indicating this request.
*
* 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
* 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.
*
* 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.
*
import org.iotivity.service.RcsPlatformException;
import org.iotivity.service.RcsResourceAttributes;
import org.iotivity.service.RcsValue;
-import org.iotivity.service.server.RcsResourceObject;
/**
*
/**
* 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
}
/**
* @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
}
/**
* @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();
* 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.
+ * <p>
+ * It is equivalent to calling {@link #startCaching(OnCacheUpdatedListener)}
+ * with null.
*
* @throws RcsDestroyedObjectException
* if the object is already destroyed
/**
* 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.
*
/**
* Returns the cached attributes.
- * This works only when cache is available.
+ * <p>
+ * Note that this works only when cache is available.
*
* @return the cached attributes.
*
/**
* 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.
+ * <p>
+ * Note that this works only when cache is available.
*
* @param key
* the key whose associated value is to be returned
}
/**
- * 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
}
/**
- * Sends a set request with resource attributes to the server.
- *
+ * Sends a set request with resource attributes to the resource.
+ * <p>
* The SetRequest behavior depends on the server, whether updating its
* attributes or not.
*
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
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() {
}
/**
- * 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) {
}
/**
- * 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) {
}
/**
- * 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,
}
}
+ /**
+ * 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<String> keySet() throws RcsException {
ensureLocked();
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();
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<String> keys = attributes.keySet();
for (final String k : keys) {
}
/**
- * 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)
}
/**
+ * 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();
}
/**
- * 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();
}
/**
- * 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();
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();
* <p>
* It also provides an auto notification mechanism that notifies to the
* observers. Requests are handled automatically by defaultAction of
- * RCSGetResponse and RCSSetResponse. Developer can override them and send your
- * own response.
+ * {@link RcsGetResponse} and {@link RcsSetResponse}. You can override them and
+ * send your own response with {@link GetRequestHandler} and
+ * {@link SetRequestHandler}.
* <p>
- * For simple resources, developer may want to know whenever attributes are
- * changed by a set request. In this case, add an AttributeUpdatedListener with
- * a key interested in instead of overriding SetRequestHandler.
+ * For simple resources, they are simply required to notify whenever attributes
+ * are changed by a set request. In this case, add an
+ * {@link OnAttributeUpdatedListener} with a key interested in instead of
+ * overriding {@link SetRequestHandler}.
*
* @see Builder
*/
public final class RcsResourceObject extends RcsObject {
/**
- * This class provides APIs for resource creation, setting properties and
- * attributes for the constructed resource. It provides the build() API
- * which
- * builds a resource and returns RCSResourceObject.
+ * This is a builder to create resource with properties and attributes.
+ *
+ * The resource will be observable and discoverable by default, to make them
+ * disable
+ * set these properties explicitly with setDiscoverable and setObservable.
*
- * {@link RcsResourceObject}
*/
public static class Builder {
private final String mUri;
private RcsResourceAttributes mAttributes;
/**
- * Constructor
+ * Constructs a Builder.
*
* @param uri
- * Resource URI value to be set
+ * resource uri
* @param resourceType
- * Resource type value to be set
+ * resource type
* @param resourceInterface
- * Interface value to be set
+ * resource interface
*
* @throws NullPointerException
- * If any parameter is null.
+ * if any parameter is null
*/
public Builder(String uri, String resourceType,
String resourceInterface) {
-
if (uri == null) {
throw new NullPointerException("uri is null.");
}
}
/**
- * Sets the discoverable(OC_DISCOVERABLE) property for the resource.
+ * Sets whether the resource is discoverable.
*
* @param isDiscoverable
- * Whether to be discovered or not
+ * whether to be discoverable or not
*
*/
public Builder setDiscoverable(boolean isDiscoverable) {
* Sets the observable(OC_OBSERVABLE) property of the resource.
*
* @param isObservable
- * Whether to be observed or not
+ * whether to be observable or not
*
*/
public Builder setObservable(boolean isObservable) {
}
/**
- * API for setting attributes of the resource.
- *
- * @param attributes
- * Attributes to set
+ * Sets attributes foe the resource.
*
*/
public Builder setAttributes(RcsResourceAttributes attributes) {
}
/**
- * Creates a RCSResourceObject.
+ * Register a resource and returns a RCSResourceObject.
*
* @throws RcsPlatformException
* If registering a resource is failed.
* {@code
* AttributesLock lock = rcsResourceObject.getAttributesLock();
*
- * try
- * {
+ * try {
* lock.lock();
*
* ....
* } finally {
* lock.unlock();
* }
+ * }
* </pre>
*/
public static class AttributesLock {
}
private RcsResourceObject ensureResourceObject() throws RcsException {
-
final RcsResourceObject object = mResourceObjectRef.get();
+
if (object == null || object.isDestroyed()) {
throw new RcsDestroyedObjectException(
"The object is already destroyed!");
* @return Locked attributes.
*
* @throws RcsException
- * If the RcsResourceObject is destroyed.
+ * if the RcsResourceObject is destroyed
*/
public RcsLockedAttributes lock() throws RcsException {
return mCurrentAttributes = new RcsLockedAttributes(
* Applies the modified attributes to the RcsResourceObject.
*
* @throws RcsIllegalStateException
- * If not in locked state.
+ * if not in locked state
*/
public void apply() throws RcsIllegalStateException {
if (mCurrentAttributes == null) {
/**
* Represents the policy of AutoNotify function of RCSResourceObject class
- * In accord with this policy, observers are notified of attributes that are
+ * In accord with this, observers are notified of attributes that are
* changed or updated.
*
* <p>
* Attributes are changed or updated according to execution of some
- * functions or receipt of 'set-request'.
+ * functions which modify attributes or receipt of set requests.
+ *
+ * @see setAttribute
+ * @see removeAttribute
+ * @see getAttributesLock
*
- * {@link RcsResourceObject}
*/
public enum AutoNotifyPolicy {
- NEVER, /** < Never notify. */
- ALWAYS, /** < Always notify. */
- UPDATED;
- /** < When attributes are changed, notify. */
+ /** Never */
+ NEVER,
+
+ /** Always */
+ ALWAYS,
+
+ /** When attributes are changed */
+ UPDATED
}
+ /**
+ * Represents the policy of set-request handler.
+ * In accord with this, the RCSResourceObject decides whether a set-request
+ * is
+ * acceptable or not.
+ */
public enum SetRequestHandlerPolicy {
+ /**
+ * 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.
+ */
+ NEVER,
- NEVER, /**
- * < Server ignore when server is received set-request of
- * attributes of the new key.
- */
- ACCEPT;
/**
- * < Server creates attributes of the new key When server is received
- * set-request of attributes of the new key.
+ * The attributes of the request will be applied unconditionally
+ * even if there are new name or type conflicts.
*/
+ ACCEPT
}
/**
* Interface definition for a handler to be invoked when a get request is
* received.
+ * <p>
+ * The handler will be called first when a get request is received, before
+ * the RCSResourceObject handles.
+ *
+ * @see setGetRequestHandler
*/
public interface GetRequestHandler {
/**
* Interface definition for a handler to be invoked when a set request is
* received.
+ * <p>
+ * The handler will be called first when a get request is received, before
+ * the RCSResourceObject handles. If the attributes are modified in the
+ * callback, the modified attributes will be set in the RCSResourceObject if
+ * the request is not ignored.
+ *
+ * @see setGetRequestHandler
*/
public interface SetRequestHandler {
* Called when received a set request from the client.
*
* @param request
- * Request information.
+ * request information
* @param attributes
- * The attributes of the request.
- * It will be applied to the RcsResourceObject.
+ * the attributes of the request.
+ * it will be applied to the RcsResourceObject
*
* @return A response indicating how to handle this request.
*
* Called when an attribute value is updated.
*
* @param oldValue
- * The attribute value before updated.
+ * the attribute value before updated
* @param newValue
- * The current resource attribute value.
+ * the current resource attribute value
*/
void onAttributeUpdated(RcsValue oldValue, RcsValue newValue);
}
}
/**
- * Sets a particular attribute value as a integer.
- * The thread-safety for attributes is taken care internally.
+ * Sets a particular attribute value.
*
* @param key
- * name of attribute(used to map the attribute value).
+ * key with which the specified value is to be associated
* @param value
- * value to be mapped against the key.
+ * value to be associated with the specified key
*
- * @throws RcsException
- * If the object is destroyed.
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
* @throws NullPointerException
- * If key or value is null.
+ * if key or value is null
*
*/
public void setAttribute(String key, RcsValue value) throws RcsException {
/**
* Returns a copied attribute value associated with the supplied key.
- * The thread-safety for attributes is taken care internally.
*
* @param key
- * key of an attribute.
+ * the key whose associated value is to be returned
*
- * @return An attributes value.
+ * @return the value to which the specified key is mapped, or null if no
+ * attribute for the key
*
- * @throws RcsException
- * If the object is destroyed.
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
* @throws NullPointerException
- * If key is null.
+ * if key is null
*/
public RcsValue getAttributeValue(String key) throws RcsException {
assertAlive();
}
/**
- * API for removing a particular attribute of the resource.
- * The thread-safety for attributes is taken care internally.
+ * Removes the mapping for a key from the attributes if it is present.
*
* @param key
- * Name of the attribute.
+ * key whose mapping is to be removed
*
- * @return If the key exist and matched attribute is deleted, return true.
+ * @return true if the key is present and the the value mapped is removed.
*
- * @throws RcsException
- * If the object is destroyed.
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
* @throws NullPointerException
- * If key is null.
+ * if key is null
*/
public boolean removeAttribute(String key) throws RcsException {
assertAlive();
}
/**
- * API for checking whether a particular attribute is there for a resource
- * or not.
- * The thread-safety for attributes is taken care internally.
+ * Returns true if the attributes contains a mapping for the specified key.
*
* @param key
- * Name of the attribute.
+ * key whose presence is to be tested
*
- * @return If the key exist, return true.
+ * @return true if the attributes contains a mapping for the specified key.
*
- * @throws RcsException
- * If the object is destroyed.
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
* @throws NullPointerException
- * If key is null.
+ * if key is null
*/
public boolean containsAttribute(String key) throws RcsException {
assertAlive();
/**
* Returns a copied attributes of the RCSResourceObject.
- * To modify the attributes, use AttrbutesLock.
+ * To modify the attributes, use {@link AttributesLock}.
*
- * @throws RcsException
- * If the object is destroyed.
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
*
* @see getAttributesLock
*/
}
/**
- * Returns the AttributesLock for this RcsResourceObject.
+ * Returns an AttributesLock for this RcsResourceObject.
*
- * @throws RcsException
- * If the object is destroyed.
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
*/
public AttributesLock getAttributesLock() throws RcsException {
assertAlive();
}
/**
- * API for checking whether the particular resource is observable or not.
- *
- * @return true if this is observable. Otherwise false.
+ * Checks whether the resource is observable or not.
*
- * @throws RcsException
- * If the object is destroyed.
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
*/
public boolean isObservable() throws RcsException {
assertAlive();
}
/**
- * API for checking whether the particular resource is discoverable or not.
+ * Checks whether the resource is discoverable or not.
*
- * @return true if this is discoverable. Otherwise false.
- *
- * @throws RcsException
- * If the object is destroyed.
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
*/
public boolean isDiscoverable() throws RcsException {
assertAlive();
}
/**
- * API for setting the resource's get request handler by the
- * developer/application. If developer set this handler then all get request
- * will come to the application and developer can send the response to the
- * client using APIs of RCSGetResponse class.
+ * Sets the get request handler. To remove handler, pass null.
+ *
+ * Default behavior is {@link RcsGetResponse#defaultAction()}.
*
- * @throws RcsException
- * If the object is destroyed.
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
*/
public void setGetRequestHandler(GetRequestHandler handler)
throws RcsException {
}
/**
- * API for setting the resource's set request handler by the
- * developer/application. If developer set this handler then all set request
- * will come to the application and developer can send the response to the
- * client using APIs of RCSSetResponse class.
+ * Sets the set request handler. To remove handler, pass null.
*
- * @throws RcsException
- * If the object is destroyed.
+ * Default behavior is {@link RcsSetResponse#defaultAction()}.
+ *
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
*
*/
public void setSetRequestHandler(SetRequestHandler handler)
}
/**
- * API for setting the Listener for a particular attribute update.
+ * Adds a listener for a particular attribute updated.
*
* @param key
- * The interested attribute's key
+ * the interested attribute's key
+ * @param listener
+ * listener to be invoked
*
* @throws NullPointerException
- * If key or listener is null.
- *
- * @throws RcsException
- * If the object is destroyed.
+ * if key or listener is null
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
*/
public void addAttributeUpdatedListener(String key,
OnAttributeUpdatedListener listener) throws RcsException {
}
/**
- * API for removing the handler for a particular attribute update.
+ * Removes a listener for a particular attribute updated.
*
* @param key
- * The interested attribute's key
+ * key the key associated with the listener to be removed
*
- * @return true if the requested attribute is removed successfully.
- * Otherwise false.
+ * @return true if the listener added with same key exists and is removed.
*
- * @throws RcsException
- * If the object is destroyed.
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
* @throws NullPointerException
- * If key is null.
+ * if key is null
*/
public boolean removeAttributeUpdatedListener(String key)
throws RcsException {
}
/**
- * API for notifying all observers of the RCSResourceObject with the updated
- * attributes value
+ * Notifies all observers of the current attributes.
*
- * @throws RcsException
- * If the object is destroyed.
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
* @throws RcsPlatformException
- * If the operation failed.
+ * if the operation failed
*/
public void notifyObservers() throws RcsException {
assertAlive();
}
/**
- * API for setting Auto notify policy
+ * Sets auto notify policy
*
* @param policy
* policy to be set
*
- * @throws RcsException
- * If the object is destroyed.
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
*
*/
public void setAutoNotifyPolicy(AutoNotifyPolicy policy)
}
/**
- * API for getting auto notify policy
+ * Returns the current policy
*
- * @return AntoNotify policy
- *
- * @throws RcsException
- * If the object is destroyed.
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
*
*/
public AutoNotifyPolicy getAutoNotifyPolicy() throws RcsException {
}
/**
- * API for setting the policy for a setRequestHandler.
+ * Sets the policy for handling a set request.
*
* @param policy
* policy to be set
*
- * @throws RcsException
- * If the object is destroyed.
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
*
*/
public void setSetRequestHandlerPolicy(SetRequestHandlerPolicy policy)
}
/**
- * API for getting the SetRequestHandler Policy.
- *
- * @return Property of setRequesthandler
- *
- * @throws RcsException
- * If the object is destroyed.
+ * Returns the current policy.
*
+ * @throws RcsDestroyedObjectException
+ * if the object is destroyed
*/
public SetRequestHandlerPolicy getSetRequestHandlerPolicy()
throws RcsException {
import org.iotivity.service.RcsResourceAttributes;
-public class RcsResponse {
+class RcsResponse {
private native static int nativeGetDefaultErrorCode();
public static final int DEFAULT_ERROR_CODE;
/**
* 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,
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() {
}
/**
- * 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() {
}
/**
- * 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) {
}
/**
- * 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() {
}
/**
- * 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) {
}
/**
- * 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) {
}
/**
- * 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) {
}
/**
+ * 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.
*
*/
}
/**
- * 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) {
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();
}
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 {
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.");
VERIFY_NO_EXC_RET_DEF(env);
attrs.erase(key);
+ if (attrs.empty()) releaseNativeHandle(env, obj);
return valueObj;
}
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.
*
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. */
};
/**
* Sets whether the resource is discoverable.
*
- * @param discoverable whether to be discovered.
+ * @param discoverable whether to be discoverable.
*
*/
Builder& setDiscoverable(bool discoverable);
/**
* 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
*
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;
* 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
*
* 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
*
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
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);
};
/**
- * 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.
projects / platform / upstream / iotivity.git / commitdiff