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