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