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