android/android_api/base/src/main/java/org/iotivity/base/OcResource.java

   1 /*
   2  * //******************************************************************
   3  * //
   4  * // Copyright 2015 Intel Corporation.
   5  * //
   6  * //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   7  * //
   8  * // Licensed under the Apache License, Version 2.0 (the "License");
   9  * // you may not use this file except in compliance with the License.
  10  * // You may obtain a copy of the License at
  11  * //
  12  * //      http://www.apache.org/licenses/LICENSE-2.0
  13  * //
  14  * // Unless required by applicable law or agreed to in writing, software
  15  * // distributed under the License is distributed on an "AS IS" BASIS,
  16  * // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * // See the License for the specific language governing permissions and
  18  * // limitations under the License.
  19  * //
  20  * //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  21  */
  22
  23 package org.iotivity.base;
  24
  25 import java.util.EnumSet;
  26 import java.util.List;
  27 import java.util.Map;
  28
  29 /**
  30  * OcResource represents an OC resource. A resource could be a light controller, temperature sensor,
  31  * smoke detector, etc. A resource comes with a well-defined contract or interface onto which you
  32  * can perform different operations, such as turning on the light, getting the current temperature
  33  * or subscribing for event notifications from the smoke detector. A resource can be composed of
  34  * one or more resources.
  35  */
  36 public class OcResource {
  37     public static final String CREATED_URI_KEY = "createduri";
  38
  39     private OcResource(long nativeHandle) {
  40         this.mNativeHandle = nativeHandle;
  41     }
  42
  43     /**
  44      * Method to get the attributes of a resource.
  45      *
  46      * @param queryParamsMap map which can have the query parameter name and value
  47      * @param onGetListener  The event handler will be invoked with a map of attribute name and
  48      *                       values. The event handler will also have the result from this Get
  49      *                       operation This will have error codes
  50      * @throws OcException if failure
  51      */
  52     public native void get(Map<String, String> queryParamsMap,
  53                            OnGetListener onGetListener) throws OcException;
  54
  55     /**
  56      * Method to get the attributes of a resource.
  57      *
  58      * @param queryParamsMap   map which can have the query parameter name and value
  59      * @param onGetListener    The event handler will be invoked with a map of attribute name and
  60      *                         values. The event handler will also have the result from this Get
  61      *                         operation This will have error codes
  62      * @param qualityOfService the quality of communication
  63      * @throws OcException if failure
  64      */
  65     public void get(Map<String, String> queryParamsMap,
  66                     OnGetListener onGetListener,
  67                     QualityOfService qualityOfService) throws OcException {
  68         this.get1(queryParamsMap, onGetListener, qualityOfService.getValue());
  69     }
  70
  71     private native void get1(Map<String, String> queryParamsMap,
  72                              OnGetListener onGetListener,
  73                              int qualityOfService) throws OcException;
  74
  75     /**
  76      * Method to get the attributes of a resource.
  77      *
  78      * @param resourceType      resourceType of the resource to operate on
  79      * @param resourceInterface interface type of the resource to operate on
  80      * @param queryParamsMap    map which can have the query parameter name and value
  81      * @param onGetListener     The event handler will be invoked with a map of attribute name and
  82      *                          values. The event handler will also have the result from this Get
  83      *                          operation This will have error codes
  84      * @throws OcException if failure
  85      */
  86     public void get(String resourceType,
  87                     String resourceInterface,
  88                     Map<String, String> queryParamsMap,
  89                     OnGetListener onGetListener) throws OcException {
  90         this.get2(
  91                 resourceType,
  92                 resourceInterface,
  93                 queryParamsMap,
  94                 onGetListener);
  95     }
  96
  97     private native void get2(String resourceType,
  98                              String resourceInterface,
  99                              Map<String, String> queryParamsMap,
 100                              OnGetListener onGetListener) throws OcException;
 101
 102     /**
 103      * Method to get the attributes of a resource.
 104      *
 105      * @param resourceType      resourceType of the resource to operate on
 106      * @param resourceInterface interface type of the resource to operate on
 107      * @param queryParamsMap    map which can have the query parameter name and value
 108      * @param onGetListener     The event handler will be invoked with a map of attribute name and
 109      *                          values. The event handler will also have the result from this Get
 110      *                          operation This will have error codes
 111      * @param qualityOfService  the quality of communication
 112      * @throws OcException if failure
 113      */
 114     public void get(String resourceType,
 115                     String resourceInterface,
 116                     Map<String, String> queryParamsMap,
 117                     OnGetListener onGetListener,
 118                     QualityOfService qualityOfService) throws OcException {
 119         this.get3(
 120                 resourceType,
 121                 resourceInterface,
 122                 queryParamsMap,
 123                 onGetListener,
 124                 qualityOfService.getValue());
 125     }
 126
 127     private native void get3(String resourceType,
 128                              String resourceInterface,
 129                              Map<String, String> queryParamsMap,
 130                              OnGetListener onGetListener,
 131                              int qualityOfService) throws OcException;
 132
 133     /**
 134      * Method to set the representation of a resource (via PUT)
 135      *
 136      * @param representation representation of the resource
 137      * @param queryParamsMap Map which can have the query parameter name and value
 138      * @param onPutListener  event handler The event handler will be invoked with a map of attribute
 139      *                       name and values.
 140      * @throws OcException if failure
 141      */
 142     public native void put(OcRepresentation representation,
 143                            Map<String, String> queryParamsMap,
 144                            OnPutListener onPutListener) throws OcException;
 145
 146     /**
 147      * Method to set the representation of a resource (via PUT)
 148      *
 149      * @param ocRepresentation representation of the resource
 150      * @param queryParamsMap   Map which can have the query parameter name and value
 151      * @param onPutListener    event handler The event handler will be invoked with a map of
 152      *                         attribute name and values.
 153      * @param qualityOfService the quality of communication
 154      * @throws OcException if failure
 155      */
 156     public void put(OcRepresentation ocRepresentation,
 157                     Map<String, String> queryParamsMap,
 158                     OnPutListener onPutListener,
 159                     QualityOfService qualityOfService) throws OcException {
 160         this.put1(
 161                 ocRepresentation,
 162                 queryParamsMap,
 163                 onPutListener,
 164                 qualityOfService.getValue());
 165     }
 166
 167     private native void put1(OcRepresentation ocRepresentation,
 168                              Map<String, String> queryParamsMap,
 169                              OnPutListener onPutListener,
 170                              int qualityOfService) throws OcException;
 171
 172     /**
 173      * Method to set the representation of a resource (via PUT)
 174      *
 175      * @param resourceType      resource type of the resource to operate on
 176      * @param resourceInterface interface type of the resource to operate on
 177      * @param ocRepresentation  representation of the resource
 178      * @param queryParamsMap    Map which can have the query parameter name and value
 179      * @param onPutListener     event handler The event handler will be invoked with a map of
 180      *                          attribute name and values.
 181      * @throws OcException if failure
 182      */
 183     public void put(String resourceType,
 184                     String resourceInterface,
 185                     OcRepresentation ocRepresentation,
 186                     Map<String, String> queryParamsMap,
 187                     OnPutListener onPutListener) throws OcException {
 188         this.put2(
 189                 resourceType,
 190                 resourceInterface,
 191                 ocRepresentation,
 192                 queryParamsMap,
 193                 onPutListener);
 194     }
 195
 196     private native void put2(String resourceType,
 197                              String resourceInterface,
 198                              OcRepresentation ocRepresentation,
 199                              Map<String, String> queryParamsMap,
 200                              OnPutListener onPutListener) throws OcException;
 201
 202     /**
 203      * Method to set the representation of a resource (via PUT)
 204      *
 205      * @param resourceType      resource type of the resource to operate on
 206      * @param resourceInterface interface type of the resource to operate on
 207      * @param ocRepresentation  representation of the resource
 208      * @param queryParamsMap    Map which can have the query parameter name and value
 209      * @param onPutListener     event handler The event handler will be invoked with a map of
 210      *                          attribute name and values.
 211      * @param qualityOfService  the quality of communication
 212      * @throws OcException if failure
 213      */
 214     public void put(String resourceType,
 215                     String resourceInterface,
 216                     OcRepresentation ocRepresentation,
 217                     Map<String, String> queryParamsMap,
 218                     OnPutListener onPutListener,
 219                     QualityOfService qualityOfService) throws OcException {
 220         this.put3(
 221                 resourceType,
 222                 resourceInterface,
 223                 ocRepresentation,
 224                 queryParamsMap,
 225                 onPutListener,
 226                 qualityOfService.getValue());
 227     }
 228
 229     private native void put3(String resourceType,
 230                              String resourceInterface,
 231                              OcRepresentation ocRepresentation,
 232                              Map<String, String> queryParamsMap,
 233                              OnPutListener onPutListener,
 234                              int qualityOfService) throws OcException;
 235
 236     /**
 237      * Method to POST on a resource
 238      *
 239      * @param ocRepresentation representation of the resource
 240      * @param queryParamsMap   Map which can have the query parameter name and value
 241      * @param onPostListener   event handler The event handler will be invoked with a map of
 242      *                         attribute name and values.
 243      * @throws OcException if failure
 244      */
 245     public native void post(OcRepresentation ocRepresentation,
 246                             Map<String, String> queryParamsMap,
 247                             OnPostListener onPostListener) throws OcException;
 248
 249     /**
 250      * Method to POST on a resource
 251      *
 252      * @param ocRepresentation representation of the resource
 253      * @param queryParamsMap   Map which can have the query parameter name and value
 254      * @param onPostListener   event handler The event handler will be invoked with a map of
 255      *                         attribute name and values.
 256      * @param qualityOfService the quality of communication
 257      * @throws OcException if failure
 258      */
 259     public void post(OcRepresentation ocRepresentation,
 260                      Map<String, String> queryParamsMap,
 261                      OnPostListener onPostListener,
 262                      QualityOfService qualityOfService) throws OcException {
 263         this.post1(
 264                 ocRepresentation,
 265                 queryParamsMap,
 266                 onPostListener,
 267                 qualityOfService.getValue());
 268     }
 269
 270     private native void post1(OcRepresentation ocRepresentation,
 271                               Map<String, String> queryParamsMap,
 272                               OnPostListener onPostListener,
 273                               int qualityOfService) throws OcException;
 274
 275     /**
 276      * Method to POST on a resource
 277      *
 278      * @param resourceType      resource type of the resource to operate on
 279      * @param resourceInterface interface type of the resource to operate on
 280      * @param ocRepresentation  representation of the resource
 281      * @param queryParamsMap    Map which can have the query parameter name and value
 282      * @param onPostListener    event handler The event handler will be invoked with a map of
 283      *                          attribute name and values.
 284      * @throws OcException if failure
 285      */
 286     public void post(String resourceType,
 287                      String resourceInterface,
 288                      OcRepresentation ocRepresentation,
 289                      Map<String, String> queryParamsMap,
 290                      OnPostListener onPostListener) throws OcException {
 291         this.post2(
 292                 resourceType,
 293                 resourceInterface,
 294                 ocRepresentation,
 295                 queryParamsMap,
 296                 onPostListener);
 297     }
 298
 299     private native void post2(String resourceType,
 300                               String resourceInterface,
 301                               OcRepresentation ocRepresentation,
 302                               Map<String, String> queryParamsMap,
 303                               OnPostListener onPostListener) throws OcException;
 304
 305     /**
 306      * Method to POST on a resource
 307      *
 308      * @param resourceType      resource type of the resource to operate on
 309      * @param resourceInterface interface type of the resource to operate on
 310      * @param ocRepresentation  representation of the resource
 311      * @param queryParamsMap    Map which can have the query parameter name and value
 312      * @param onPostListener    event handler The event handler will be invoked with a map of
 313      *                          attribute name and values.
 314      * @param qualityOfService  the quality of communication
 315      * @throws OcException
 316      */
 317     public void post(String resourceType,
 318                      String resourceInterface,
 319                      OcRepresentation ocRepresentation,
 320                      Map<String, String> queryParamsMap,
 321                      OnPostListener onPostListener,
 322                      QualityOfService qualityOfService) throws OcException {
 323         this.post3(
 324                 resourceType,
 325                 resourceInterface,
 326                 ocRepresentation,
 327                 queryParamsMap,
 328                 onPostListener,
 329                 qualityOfService.getValue());
 330     }
 331
 332     private native void post3(String resourceType,
 333                               String resourceInterface,
 334                               OcRepresentation ocRepresentation,
 335                               Map<String, String> queryParamsMap,
 336                               OnPostListener onPostListener,
 337                               int qualityOfService) throws OcException;
 338
 339     /**
 340      * Method to perform DELETE operation
 341      *
 342      * @param onDeleteListener event handler The event handler will have headerOptionList
 343      */
 344     public native void deleteResource(OnDeleteListener onDeleteListener) throws OcException;
 345
 346     /**
 347      * Method to perform DELETE operation
 348      *
 349      * @param onDeleteListener event handler The event handler will have headerOptionList
 350      * @param qualityOfService the quality of communication
 351      */
 352     public void deleteResource(OnDeleteListener onDeleteListener,
 353                                QualityOfService qualityOfService) throws OcException {
 354         this.deleteResource1(onDeleteListener,
 355                 qualityOfService.getValue());
 356     }
 357
 358     private native void deleteResource1(OnDeleteListener onDeleteListener,
 359                                         int qualityOfService) throws OcException;
 360
 361     /**
 362      * Method to set observation on the resource
 363      *
 364      * @param observeType       allows the client to specify how it wants to observe
 365      * @param queryParamsMap    map which can have the query parameter name and value
 366      * @param onObserveListener event handler The handler method will be invoked with a map
 367      *                          of attribute name and values.
 368      * @throws OcException
 369      */
 370     public void observe(ObserveType observeType,
 371                         Map<String, String> queryParamsMap,
 372                         OnObserveListener onObserveListener) throws OcException {
 373         this.observe(
 374                 observeType.getValue(),
 375                 queryParamsMap,
 376                 onObserveListener);
 377     }
 378
 379     private synchronized native void observe(int observeType,
 380                                              Map<String, String> queryParamsMap,
 381                                              OnObserveListener onObserveListener) throws OcException;
 382
 383     /**
 384      * Method to set observation on the resource
 385      *
 386      * @param observeType       allows the client to specify how it wants to observe
 387      * @param queryParamsMap    map which can have the query parameter name and value
 388      * @param onObserveListener event handler The handler method will be invoked with a map
 389      *                          of attribute name and values.
 390      * @param qualityOfService  the quality of communication
 391      * @throws OcException
 392      */
 393     public void observe(ObserveType observeType,
 394                         Map<String, String> queryParamsMap,
 395                         OnObserveListener onObserveListener,
 396                         QualityOfService qualityOfService) throws OcException {
 397         this.observe1(
 398                 observeType.getValue(),
 399                 queryParamsMap,
 400                 onObserveListener,
 401                 qualityOfService.getValue());
 402     }
 403
 404     private synchronized native void observe1(int observeType,
 405                                               Map<String, String> queryParamsMap,
 406                                               OnObserveListener onObserveListener,
 407                                               int qualityOfService) throws OcException;
 408
 409     /**
 410      * Method to cancel the observation on the resource
 411      *
 412      * @throws OcException
 413      */
 414     public native void cancelObserve() throws OcException;
 415
 416     /**
 417      * Method to cancel the observation on the resource
 418      *
 419      * @param qualityOfService the quality of communication
 420      * @throws OcException
 421      */
 422     public void cancelObserve(QualityOfService qualityOfService) throws OcException {
 423         this.cancelObserve1(qualityOfService.getValue());
 424     }
 425
 426     private native void cancelObserve1(int qualityOfService) throws OcException;
 427
 428     /**
 429      * Method to set header options
 430      *
 431      * @param headerOptionList List<OcHeaderOption> where header information(header optionID and
 432      *                         optionData is passed
 433      */
 434     public void setHeaderOptions(List<OcHeaderOption> headerOptionList) {
 435         this.setHeaderOptions(headerOptionList.toArray(
 436                         new OcHeaderOption[headerOptionList.size()])
 437         );
 438     }
 439
 440     private native void setHeaderOptions(OcHeaderOption[] headerOptionList);
 441
 442     /**
 443      * Method to unset header options
 444      */
 445     public native void unsetHeaderOptions();
 446
 447     /**
 448      * Method to get the host address of this resource
 449      *
 450      * @return host address NOTE: This might or might not be exposed in future due to
 451      * security concerns
 452      */
 453     public native String getHost();
 454
 455     /**
 456      * Method to get the URI for this resource
 457      *
 458      * @return resource URI
 459      */
 460     public native String getUri();
 461
 462     /**
 463      * Method to get the connectivity type of this resource
 464      *
 465      * @return EnumSet<OcConnectivityType></OcConnectivityType> connectivity type set
 466      */
 467     public EnumSet<OcConnectivityType> getConnectivityTypeSet() {
 468         return OcConnectivityType.convertToEnumSet(
 469                 this.getConnectivityTypeN()
 470         );
 471     }
 472
 473     private native int getConnectivityTypeN();
 474
 475     /**
 476      * Method to provide ability to check if this resource is observable or not
 477      *
 478      * @return true indicates resource is observable; false indicates resource is not observable
 479      */
 480     public native boolean isObservable();
 481
 482     /**
 483      * Method to get the list of resource types
 484      *
 485      * @return List of resource types
 486      */
 487     public native List<String> getResourceTypes();
 488
 489     /**
 490      * Method to get the list of resource interfaces
 491      *
 492      * @return List of resource interface
 493      */
 494     public native List<String> getResourceInterfaces();
 495
 496     /**
 497      * Method to get a unique identifier for this resource across network interfaces.  This will
 498      * be guaranteed unique for every resource-per-server independent of how this was discovered.
 499      *
 500      * @return OcResourceIdentifier object, which can be used for all comparison and hashing
 501      */
 502     public native OcResourceIdentifier getUniqueIdentifier();
 503
 504     /**
 505      * Method to get a string representation of the resource's server ID.
 506      * <p>
 507      * This is unique per- server independent on how it was discovered.
 508      * </p>
 509      *
 510      * @return server ID
 511      */
 512     public native String getServerId();
 513
 514     /**
 515      * An OnGetListener can be registered via the resource get call.
 516      * Event listeners are notified asynchronously
 517      */
 518     public interface OnGetListener {
 519         public void onGetCompleted(List<OcHeaderOption> headerOptionList,
 520                                    OcRepresentation ocRepresentation);
 521
 522         public void onGetFailed(Throwable ex);
 523     }
 524
 525     /**
 526      * An OnPutListener can be registered via the resource put call.
 527      * Event listeners are notified asynchronously
 528      */
 529     public interface OnPutListener {
 530         public void onPutCompleted(List<OcHeaderOption> headerOptionList,
 531                                    OcRepresentation ocRepresentation);
 532
 533         public void onPutFailed(Throwable ex);
 534     }
 535
 536     /**
 537      * An OnPostListener can be registered via the resource post call.
 538      * Event listeners are notified asynchronously
 539      */
 540     public interface OnPostListener {
 541         public void onPostCompleted(List<OcHeaderOption> headerOptionList,
 542                                     OcRepresentation ocRepresentation);
 543
 544         public void onPostFailed(Throwable ex);
 545     }
 546
 547     /**
 548      * An OnDeleteListener can be registered via the resource delete call.
 549      * Event listeners are notified asynchronously
 550      */
 551     public interface OnDeleteListener {
 552         public void onDeleteCompleted(List<OcHeaderOption> headerOptionList);
 553
 554         public void onDeleteFailed(Throwable ex);
 555     }
 556
 557     /**
 558      * An OnObserveListener can be registered via the resource observe call.
 559      * Event listeners are notified asynchronously
 560      */
 561     public interface OnObserveListener {
 562         /**
 563          * To Register.
 564          */
 565         public static final int REGISTER = 0;
 566         /**
 567          * To Deregister.
 568          */
 569         public static final int DEREGISTER = 1;
 570         /**
 571          * Others.
 572          */
 573         public static final int NO_OPTION = 2;
 574
 575         public void onObserveCompleted(List<OcHeaderOption> headerOptionList,
 576                                        OcRepresentation ocRepresentation,
 577                                        int sequenceNumber);
 578
 579         public void onObserveFailed(Throwable ex);
 580     }
 581
 582     @Override
 583     protected void finalize() throws Throwable {
 584         super.finalize();
 585
 586         dispose();
 587     }
 588
 589     private native void dispose();
 590
 591     private long mNativeHandle;
 592 }