java/common/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 void cancelObserve() throws OcException{
 415         this.cancelObserve(OcPlatform.getPlatformQualityOfService());
 416     }
 417
 418     /**
 419      * Method to cancel the observation on the resource
 420      *
 421      * @param qualityOfService the quality of communication
 422      * @throws OcException
 423      */
 424     public void cancelObserve(QualityOfService qualityOfService) throws OcException {
 425         this.cancelObserve1(qualityOfService.getValue());
 426     }
 427
 428     private native void cancelObserve1(int qualityOfService) throws OcException;
 429
 430     /**
 431      * Method to set header options
 432      *
 433      * @param headerOptionList List<OcHeaderOption> where header information(header optionID and
 434      *                         optionData is passed
 435      */
 436     public void setHeaderOptions(List<OcHeaderOption> headerOptionList) {
 437         this.setHeaderOptions(headerOptionList.toArray(
 438                         new OcHeaderOption[headerOptionList.size()])
 439         );
 440     }
 441
 442     private native void setHeaderOptions(OcHeaderOption[] headerOptionList);
 443
 444     /**
 445      * Method to unset header options
 446      */
 447     public native void unsetHeaderOptions();
 448
 449     /**
 450      * Method to get the host address of this resource
 451      *
 452      * @return host address NOTE: This might or might not be exposed in future due to
 453      * security concerns
 454      */
 455     public native String getHost();
 456
 457     /**
 458      * Method to get the URI for this resource
 459      *
 460      * @return resource URI
 461      */
 462     public native String getUri();
 463
 464     /**
 465      * Method to get the connectivity type of this resource
 466      *
 467      * @return EnumSet<OcConnectivityType></OcConnectivityType> connectivity type set
 468      */
 469     public EnumSet<OcConnectivityType> getConnectivityTypeSet() {
 470         return OcConnectivityType.convertToEnumSet(
 471                 this.getConnectivityTypeN()
 472         );
 473     }
 474
 475     private native int getConnectivityTypeN();
 476
 477     /**
 478      * Method to provide ability to check if this resource is observable or not
 479      *
 480      * @return true indicates resource is observable; false indicates resource is not observable
 481      */
 482     public native boolean isObservable();
 483
 484     /**
 485      * Method to get the list of resource types
 486      *
 487      * @return List of resource types
 488      */
 489     public native List<String> getResourceTypes();
 490
 491     /**
 492      * Method to get the list of resource interfaces
 493      *
 494      * @return List of resource interface
 495      */
 496     public native List<String> getResourceInterfaces();
 497
 498     /**
 499      * Method to get a unique identifier for this resource across network interfaces.  This will
 500      * be guaranteed unique for every resource-per-server independent of how this was discovered.
 501      *
 502      * @return OcResourceIdentifier object, which can be used for all comparison and hashing
 503      */
 504     public native OcResourceIdentifier getUniqueIdentifier();
 505
 506     /**
 507      * Method to get a string representation of the resource's server ID.
 508      * <p>
 509      * This is unique per- server independent on how it was discovered.
 510      * </p>
 511      *
 512      * @return server ID
 513      */
 514     public native String getServerId();
 515
 516     /**
 517      * An OnGetListener can be registered via the resource get call.
 518      * Event listeners are notified asynchronously
 519      */
 520     public interface OnGetListener {
 521         public void onGetCompleted(List<OcHeaderOption> headerOptionList,
 522                                    OcRepresentation ocRepresentation);
 523
 524         public void onGetFailed(Throwable ex);
 525     }
 526
 527     /**
 528      * An OnPutListener can be registered via the resource put call.
 529      * Event listeners are notified asynchronously
 530      */
 531     public interface OnPutListener {
 532         public void onPutCompleted(List<OcHeaderOption> headerOptionList,
 533                                    OcRepresentation ocRepresentation);
 534
 535         public void onPutFailed(Throwable ex);
 536     }
 537
 538     /**
 539      * An OnPostListener can be registered via the resource post call.
 540      * Event listeners are notified asynchronously
 541      */
 542     public interface OnPostListener {
 543         public void onPostCompleted(List<OcHeaderOption> headerOptionList,
 544                                     OcRepresentation ocRepresentation);
 545
 546         public void onPostFailed(Throwable ex);
 547     }
 548
 549     /**
 550      * An OnDeleteListener can be registered via the resource delete call.
 551      * Event listeners are notified asynchronously
 552      */
 553     public interface OnDeleteListener {
 554         public void onDeleteCompleted(List<OcHeaderOption> headerOptionList);
 555
 556         public void onDeleteFailed(Throwable ex);
 557     }
 558
 559     /**
 560      * An OnObserveListener can be registered via the resource observe call.
 561      * Event listeners are notified asynchronously
 562      */
 563     public interface OnObserveListener {
 564         /**
 565          * To Register.
 566          */
 567         public static final int REGISTER = 0;
 568         /**
 569          * To Deregister.
 570          */
 571         public static final int DEREGISTER = 1;
 572         /**
 573          * Others.
 574          */
 575         public static final int NO_OPTION = 2;
 576
 577         public void onObserveCompleted(List<OcHeaderOption> headerOptionList,
 578                                        OcRepresentation ocRepresentation,
 579                                        int sequenceNumber);
 580
 581         public void onObserveFailed(Throwable ex);
 582     }
 583
 584     @Override
 585     protected void finalize() throws Throwable {
 586         super.finalize();
 587
 588         dispose();
 589     }
 590
 591     private native void dispose();
 592
 593     private long mNativeHandle;
 594 }