service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/client/RcsRemoteResourceObject.java

   1 /******************************************************************
   2  *
   3  * Copyright 2015 Samsung Electronics All Rights Reserved.
   4  *
   5  *
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  *      http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  ******************************************************************/
  20
  21 package org.iotivity.service.client;
  22
  23 import org.iotivity.service.RcsDestroyedObjectException;
  24 import org.iotivity.service.RcsException;
  25 import org.iotivity.service.RcsIllegalStateException;
  26 import org.iotivity.service.RcsObject;
  27 import org.iotivity.service.RcsPlatformException;
  28 import org.iotivity.service.RcsResourceAttributes;
  29 import org.iotivity.service.RcsValue;
  30 import org.iotivity.service.server.RcsResourceObject;
  31
  32 /**
  33  *
  34  * This represents a remote resource and provides simple ways to interact with
  35  * it.
  36  * Basically this is a client of a remote resource that runs on other device.
  37  *
  38  * The class supports features to help get information of a remote resource
  39  * such as monitoring and caching.
  40  *
  41  * @see RcsDiscoveryManager
  42  *
  43  */
  44 public final class RcsRemoteResourceObject extends RcsObject {
  45
  46     private native boolean nativeIsMonitoring();
  47
  48     private native boolean nativeIsCaching();
  49
  50     private native boolean nativeIsObservable();
  51
  52     private native void nativeStartMonitoring(OnStateChangedListener listener);
  53
  54     private native void nativeStopMonitoring();
  55
  56     private native ResourceState nativeGetState();
  57
  58     private native void nativeStartCaching(OnCacheUpdatedListener listener);
  59
  60     private native void nativeStopCaching();
  61
  62     private native CacheState nativeGetCacheState();
  63
  64     private native boolean nativeIsCachedAvailable();
  65
  66     private native RcsResourceAttributes nativeGetCachedAttributes();
  67
  68     private native void nativeGetRemoteAttributes(
  69             OnRemoteAttributesReceivedListener listener);
  70
  71     private native void nativeSetRemoteAttributes(
  72             RcsResourceAttributes attributes,
  73             OnRemoteAttributesReceivedListener listener);
  74
  75     private native String nativeGetUri();
  76
  77     private native String nativeGetAddress();
  78
  79     private native String[] nativeGetTypes();
  80
  81     private native String[] nativeGetInterfaces();
  82
  83     private RcsRemoteResourceObject() {
  84     }
  85
  86     /**
  87      * This represents states of monitoring.
  88      *
  89      * @see #startMonitoring()
  90      * @see #getState()
  91      * @see OnStateChangedListener
  92      *
  93      */
  94     public enum ResourceState {
  95
  96         NONE, /** < Monitoring is not started. */
  97         REQUESTED, /**
  98                     * < Monitoring is started and checking state is in progress.
  99                     * This is the default state after startMonitoring.
 100                     */
 101         ALIVE, /** < The resource is alive. */
 102         LOST_SIGNAL, /** < Failed to reach the resource. */
 103         DESTROYED /** < The resource is deleted. */
 104     }
 105
 106     /**
 107      * This represents states of caching.
 108      *
 109      * @see #startCaching()
 110      * @see #getCacheState()
 111      */
 112     public enum CacheState {
 113
 114         NONE, /** < Caching is not started. */
 115         UNREADY, /**
 116                   * < Caching is started, but the data is not ready yet. This is
 117                   * the default state after startCaching.
 118                   */
 119         READY, /** < The data is ready. */
 120         LOST_SIGNAL /** < Failed to reach the resource. */
 121     }
 122
 123     /**
 124      * Interface definition for a callback to be invoked when the cache is
 125      * updated.
 126      *
 127      * @see #startCaching(OnCacheUpdatedListener)
 128      */
 129     public interface OnCacheUpdatedListener {
 130
 131         /**
 132          * Called when the cache is updated.
 133          *
 134          * @param attributes
 135          *            the updated attributes
 136          *
 137          */
 138         public void onCacheUpdated(RcsResourceAttributes attributes);
 139
 140     }
 141
 142     /**
 143      * Interface definition for a callback to be invoked when the response of
 144      * getRemoteAttributes and setRemoteAttributes is received.
 145      *
 146      * @see #getRemoteAttributes(OnRemoteAttributesReceivedListener)
 147      * @see #setRemoteAttributes(RcsResourceAttributes,
 148      *      OnRemoteAttributesReceivedListener)
 149      */
 150     public interface OnRemoteAttributesReceivedListener {
 151
 152         /**
 153          * Called when a response for the getRemoteAttributes request or
 154          * setRemoteAttributes request is received.
 155          *
 156          * @param attributes
 157          *            the resource attributes received from the remote resource
 158          *
 159          */
 160         public void onAttributesReceived(RcsResourceAttributes attributes,
 161                 int errorCode);
 162
 163     }
 164
 165     /**
 166      * Interface definition for a callback to be invoked when the monitoring
 167      * state is changed.
 168      *
 169      * @see #startMonitoring(OnStateChangedListener)
 170      */
 171     public interface OnStateChangedListener {
 172
 173         /**
 174          * Called when the monitoring state is changed.
 175          *
 176          * @param resourceState
 177          *            updated state
 178          *
 179          */
 180         public void onStateChanged(ResourceState resourceState);
 181     }
 182
 183     private void assertAlive() throws RcsException {
 184         if (!hasHandle()) {
 185             throw new RcsDestroyedObjectException(
 186                     "The object is already destroyed!");
 187         }
 188     }
 189
 190     /**
 191      * Returns whether monitoring is enabled.
 192      *
 193      * @return true if monitoring the resource.
 194      *
 195      * @throws RcsDestroyedObjectException
 196      *             if the object is already destroyed
 197      *
 198      * @see #startMonitoring(OnStateChangedListener)
 199      */
 200     public boolean isMonitoring() throws RcsException {
 201         assertAlive();
 202         return nativeIsMonitoring();
 203     }
 204
 205     /**
 206      * Returns whether caching is enabled.
 207      *
 208      * @return true if caching the resource.
 209      *
 210      * @throws RcsDestroyedObjectException
 211      *             if the object is already destroyed
 212      *
 213      * @see #startCaching()
 214      * @see #startCaching(OnCacheUpdatedListener)
 215      *
 216      */
 217     public boolean isCaching() throws RcsException {
 218         assertAlive();
 219         return nativeIsCaching();
 220     }
 221
 222     /**
 223      * Returns whether resource is observable.
 224      *
 225      * @return true if resource is observable.
 226      *
 227      * @throws RcsDestroyedObjectException
 228      *             if the object is already destroyed
 229      *
 230      * @see RcsResourceObject.Builder#setObservable(boolean)
 231      */
 232     public boolean isObservable() throws RcsException {
 233         assertAlive();
 234         return nativeIsObservable();
 235     }
 236
 237     /**
 238      * Starts monitoring the resource.
 239      * <p>
 240      * Monitoring provides a feature to check the presence of a resource, even
 241      * when the server is not announcing Presence using startPresnece.
 242      *
 243      * @param listener
 244      *            the listener to receive new state.
 245      *
 246      * @throws NullPointerException
 247      *             if listener is null
 248      * @throws RcsIllegalStateException
 249      *             if monitoring is already started
 250      * @throws RcsDestroyedObjectException
 251      *             if the object is already destroyed
 252      *
 253      * @see ResourceState
 254      * @see #isMonitoring()
 255      * @see #stopMonitoring()
 256      */
 257     public void startMonitoring(OnStateChangedListener listener)
 258             throws RcsException {
 259         assertAlive();
 260         if (listener == null) {
 261             throw new NullPointerException("listener is null.");
 262         }
 263
 264         nativeStartMonitoring(listener);
 265     }
 266
 267     /**
 268      * Stops monitoring the resource.
 269      * <p>
 270      * It does nothing if monitoring is not started.
 271      *
 272      * @throws RcsDestroyedObjectException
 273      *             if the object is already destroyed
 274      *
 275      * @see #startMonitoring(OnStateChangedListener)
 276      * @see #isMonitoring()
 277      */
 278     public void stopMonitoring() throws RcsException {
 279         assertAlive();
 280         nativeStopMonitoring();
 281     }
 282
 283     /**
 284      * Returns the current state of the resource.
 285      *
 286      * @return ResourceState - current resource state
 287      *
 288      * @throws RcsDestroyedObjectException
 289      *             if the object is already destroyed
 290      *
 291      * @see #startMonitoring(OnStateChangedListener)
 292      * @see #isMonitoring()
 293      * @see OnStateChangedListener
 294      */
 295     public ResourceState getState() throws RcsException {
 296         assertAlive();
 297         return nativeGetState();
 298     }
 299
 300     /**
 301      * Starts caching attributes of the resource.
 302      *
 303      * This will start data caching for the resource. Once caching started it
 304      * will look for the data updation on the resource and updates the cache
 305      * data accordingly.
 306      *
 307      * It is equivalent to calling startCaching(CacheUpdatedCallback) with null.
 308      *
 309      * @throws RcsDestroyedObjectException
 310      *             if the object is already destroyed
 311      *
 312      * @see #startCaching(OnCacheUpdatedListener)
 313      * @see #isCaching()
 314      * @see #getCacheState()
 315      * @see #getCachedAttribute(String)
 316      * @see #getCachedAttributes()
 317      * @see OnCacheUpdatedListener
 318      */
 319     public void startCaching() throws RcsException {
 320         assertAlive();
 321         startCaching(null);
 322     }
 323
 324     /**
 325      * Starts caching attributes of the resource.
 326      *
 327      * This will start data caching for the resource. Once caching started it
 328      * will look for the data updation on the resource and updates the cache
 329      * data accordingly.
 330      *
 331      * @param listener
 332      *            the listener to be notified when attributes are updated or
 333      *            null if no need
 334      *
 335      * @throws RcsDestroyedObjectException
 336      *             if the object is already destroyed
 337      *
 338      * @see #startCaching()
 339      * @see #isCaching()
 340      * @see #getCacheState()
 341      * @see #getCachedAttribute(String)
 342      * @see #getCachedAttributes()
 343      * @see OnCacheUpdatedListener
 344      */
 345     public void startCaching(OnCacheUpdatedListener listener)
 346             throws RcsException {
 347         assertAlive();
 348         nativeStartCaching(listener);
 349     }
 350
 351     /**
 352      * Stops caching.
 353      *
 354      * It does nothing if caching is not started.
 355      *
 356      * @throws RcsDestroyedObjectException
 357      *             if the object is already destroyed
 358      *
 359      * @see #startCaching()
 360      * @see #startCaching(OnCacheUpdatedListener)
 361      * @see #isCaching()
 362      *
 363      */
 364     public void stopCaching() throws RcsException {
 365         assertAlive();
 366         nativeStopCaching();
 367     }
 368
 369     /**
 370      * Returns the current cache state.
 371      *
 372      * @return current cache state.
 373      *
 374      * @throws RcsDestroyedObjectException
 375      *             if the object is already destroyed
 376      *
 377      * @see #startCaching()
 378      * @see #startCaching(OnCacheUpdatedListener)
 379      * @see #isCaching()
 380      */
 381     public CacheState getCacheState() throws RcsException {
 382         assertAlive();
 383         return nativeGetCacheState();
 384     }
 385
 386     /**
 387      * Returns whether cached data is available.
 388      *
 389      * Cache will be available always once cache state had been READY even if
 390      * current state is LOST_SIGNAL.
 391      *
 392      * @return true if cache data is available.
 393      *
 394      * @throws RcsDestroyedObjectException
 395      *             if the object is already destroyed
 396      *
 397      * @see #startCaching()
 398      * @see #startCaching(OnCacheUpdatedListener)
 399      * @see #isCaching()
 400      * @see #getCacheState()
 401      *
 402      */
 403     public boolean isCachedAvailable() throws RcsException {
 404         assertAlive();
 405         return nativeIsCachedAvailable();
 406     }
 407
 408     /**
 409      * Returns the cached attributes.
 410      * This works only when cache is available.
 411      *
 412      * @return the cached attributes.
 413      *
 414      * @throws RcsIllegalStateException
 415      *             if cache is not available
 416      * @throws RcsDestroyedObjectException
 417      *             if the object is already destroyed
 418      *
 419      * @see #startCaching()
 420      * @see #startCaching(OnCacheUpdatedListener)
 421      * @see #isCaching()
 422      * @see #getCacheState()
 423      * @see #isCachedAvailable()
 424      * @see #getCachedAttribute(String)
 425      *
 426      */
 427     public RcsResourceAttributes getCachedAttributes() throws RcsException {
 428         assertAlive();
 429         return nativeGetCachedAttributes();
 430     }
 431
 432     /**
 433      * Returns the cached value to which the specified key is mapped, or null if
 434      * RcsResourceAttributes contains no mapping for the key.
 435      *
 436      * This works only when cache is available.
 437      *
 438      * @param key
 439      *            the key whose associated value is to be returned
 440      *
 441      * @return the value to which the specified key is mapped, or null if no
 442      *         mapping for the key
 443      *
 444      * @throws NullPointerException
 445      *             if key is null
 446      * @throws RcsIllegalStateException
 447      *             if cache is not available
 448      * @throws RcsDestroyedObjectException
 449      *             if the object is already destroyed
 450      *
 451      * @see #startCaching()
 452      * @see #startCaching(OnCacheUpdatedListener)
 453      * @see #isCaching()
 454      * @see #getCacheState()
 455      * @see #isCachedAvailable()
 456      * @see #getCachedAttributes()
 457      *
 458      */
 459     public RcsValue getCachedAttribute(String key) throws RcsException {
 460         assertAlive();
 461         if (key == null) {
 462             throw new NullPointerException("key is null.");
 463         }
 464
 465         return getCachedAttributes().get(key);
 466     }
 467
 468     /**
 469      * Sends a request for the resource attributes directly to the server.
 470      *
 471      * @param listener
 472      *            the listener to receive the response
 473      *
 474      * @throws NullPointerException
 475      *             if listener is null
 476      * @throws RcsDestroyedObjectException
 477      *             if the object is already destroyed
 478      * @throws RcsPlatformException
 479      *             if the operation failed
 480      *
 481      * @see OnRemoteAttributesReceivedListener
 482      */
 483     public void getRemoteAttributes(OnRemoteAttributesReceivedListener listener)
 484             throws RcsException {
 485         assertAlive();
 486         if (listener == null) {
 487             throw new NullPointerException("listener is null.");
 488         }
 489
 490         nativeGetRemoteAttributes(listener);
 491     }
 492
 493     /**
 494      * Sends a set request with resource attributes to the server.
 495      *
 496      * The SetRequest behavior depends on the server, whether updating its
 497      * attributes or not.
 498      *
 499      * @param attributes
 500      *            attributes to set for the remote resource.
 501      *
 502      * @throws NullPointerException
 503      *             if attributes or listener is null
 504      * @throws RcsDestroyedObjectException
 505      *             if the object is already destroyed
 506      * @throws RcsPlatformException
 507      *             if the operation failed
 508      *
 509      * @see OnRemoteAttributesReceivedListener
 510      */
 511     public void setRemoteAttributes(RcsResourceAttributes attributes,
 512             OnRemoteAttributesReceivedListener listener) throws RcsException {
 513         assertAlive();
 514
 515         if (attributes == null) {
 516             throw new NullPointerException("attributes is null.");
 517         }
 518         if (listener == null) {
 519             throw new NullPointerException("listener is null.");
 520         }
 521
 522         nativeSetRemoteAttributes(attributes, listener);
 523     }
 524
 525     /**
 526      * Returns the uri of the resource.
 527      *
 528      * @return uri of the resource
 529      *
 530      * @throws RcsDestroyedObjectException
 531      *             if the object is already destroyed
 532      */
 533     public String getUri() throws RcsException {
 534         assertAlive();
 535         return nativeGetUri();
 536     }
 537
 538     /**
 539      * Returns the address of the resource .
 540      *
 541      * @return address of the resource
 542      *
 543      * @throws RcsDestroyedObjectException
 544      *             if the object is already destroyed
 545      */
 546     public String getAddress() throws RcsException {
 547         assertAlive();
 548         return nativeGetAddress();
 549     }
 550
 551     /**
 552      * Returns the resource types of the resource.
 553      *
 554      * @return resource types
 555      *
 556      * @throws RcsDestroyedObjectException
 557      *             if the object is already destroyed
 558      */
 559     public String[] getTypes() throws RcsException {
 560         assertAlive();
 561         return nativeGetTypes();
 562     }
 563
 564     /**
 565      * Returns the resource interfaces of the resource.
 566      *
 567      * @return resource interfaces
 568      *
 569      * @throws RcsDestroyedObjectException
 570      *             if the object is already destroyed
 571      */
 572     public String[] getInterfaces() throws RcsException {
 573         assertAlive();
 574         return nativeGetInterfaces();
 575     }
 576
 577     /**
 578      * Reclaims all resources used by this object.
 579      * This must be called if the resource is not used any longer.
 580      *
 581      */
 582     public void destroy() {
 583         super.dispose();
 584     }
 585 }