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

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