service/simulator/java/sdk/src/org/oic/simulator/client/SimulatorRemoteResource.java

   1 /*
   2  * Copyright 2015 Samsung Electronics All Rights Reserved.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package org.oic.simulator.client;
  18
  19 import java.util.Map;
  20 import java.util.Vector;
  21
  22 import org.oic.simulator.InvalidArgsException;
  23 import org.oic.simulator.NoSupportException;
  24 import org.oic.simulator.OperationInProgressException;
  25 import org.oic.simulator.SimulatorException;
  26 import org.oic.simulator.SimulatorResourceModel;
  27 import org.oic.simulator.SimulatorResult;
  28
  29 /**
  30  * SimulatorRemoteResource represents a Resource running in the remote Simulator
  31  * Server. It comes with a well-defined contract or interface onto which you can
  32  * perform different operations or subscribe for event notifications.
  33  */
  34 public final class SimulatorRemoteResource {
  35     private long           mNativeHandle;
  36     private String         mUri;
  37     private int            mConnType;
  38     private String         mHost;
  39     private String         mId;
  40     private Vector<String> mResTypes;
  41     private Vector<String> mResInterfaces;
  42     private boolean        mIsObservable;
  43
  44     @Override
  45     protected void finalize() throws Throwable {
  46         try {
  47             nativeDispose();
  48         } catch (Throwable t) {
  49             throw t;
  50         } finally {
  51             super.finalize();
  52         }
  53     }
  54
  55     /**
  56      * Enum to represent the verification types which can be used by the client
  57      * to verify the resource model of the remote resource.
  58      */
  59     public enum RequestType {
  60         UKNOWN, GET, PUT, POST, DELETE;
  61     }
  62
  63     /**
  64      * API to get the URI for this resource.
  65      *
  66      * @return Resource URI.
  67      */
  68     public String getURI() {
  69         return mUri;
  70     }
  71
  72     /**
  73      * API to get the address detail of the resource.
  74      *
  75      * @return Host address.
  76      */
  77     public String getHost() {
  78         return mHost;
  79     }
  80
  81     /**
  82      * API to get a unique Id of the resource.
  83      *
  84      * @return Unique ID.
  85      */
  86     public String getId() {
  87         return mId;
  88     }
  89
  90     /**
  91      * API to get the connectivity type for this resource.
  92      *
  93      * @return Connectivity type.
  94      */
  95     public SimulatorConnectivityType getConnectivityType() {
  96         return SimulatorConnectivityType.getConnectivityType(mConnType);
  97     }
  98
  99     /**
 100      * API to get the list of resource types.
 101      *
 102      * @return Resource types.
 103      */
 104     public Vector<String> getResourceTypes() {
 105         return mResTypes;
 106     }
 107
 108     /**
 109      * API to get the list of resource interfaces.
 110      *
 111      * @return Resource interfaces.
 112      */
 113     public Vector<String> getResourceInterfaces() {
 114         return mResInterfaces;
 115     }
 116
 117     /**
 118      * API to get the observe policy of this resource.
 119      *
 120      * @return True if the resource is observable, otherwise false.
 121      */
 122     public boolean isObservable() {
 123         return mIsObservable;
 124     }
 125
 126     /**
 127      * API to send GET request to the resource. Response will be notified
 128      * asynchronously via callback set for {@link GetResponseListener}.
 129      *
 130      * @param queryParams
 131      *            Map which can have the query parameter name and value.
 132      * @param onGetListener
 133      *            Event handler which will be invoked with the response for GET
 134      *            request with a map of attribute name and values.
 135      *
 136      * @throws InvalidArgsException
 137      *             This exception will be thrown if any parameter has invalid
 138      *             values.
 139      * @throws SimulatorException
 140      *             This exception will be thrown for other errors.
 141      */
 142     public void get(Map<String, String> queryParams,
 143             GetResponseListener onGetListener) throws InvalidArgsException,
 144             SimulatorException {
 145         nativeGet(null, queryParams, onGetListener);
 146     }
 147
 148     /**
 149      * API to send GET request to the resource. Response will be notified
 150      * asynchronously via callback set for {@link GetResponseListener}.
 151      *
 152      * @param resourceInterface
 153      *            Interface type of the resource to operate on.
 154      * @param queryParams
 155      *            Map which can have the query parameter name and value.
 156      * @param onGetListener
 157      *            Event handler which will be invoked with the response for GET
 158      *            request with a map of attribute name and values.
 159      *
 160      * @throws InvalidArgsException
 161      *             This exception will be thrown if any parameter has invalid
 162      *             values.
 163      * @throws SimulatorException
 164      *             This exception will be thrown for other errors.
 165      */
 166     public void get(String resourceInterface, Map<String, String> queryParams,
 167             GetResponseListener onGetListener) throws InvalidArgsException,
 168             SimulatorException {
 169         if (null == resourceInterface || resourceInterface.isEmpty())
 170             throw new InvalidArgsException(
 171                     SimulatorResult.SIMULATOR_INVALID_PARAM,
 172                     "Invalid resource interface!");
 173         nativeGet(resourceInterface, queryParams, onGetListener);
 174     }
 175
 176     /**
 177      * API to send PUT request to the resource. Response will be notified
 178      * asynchronously via callback set for {@link PutResponseListener}.
 179      *
 180      * @param queryParams
 181      *            Map which can have the query parameter name and value.
 182      * @param representation
 183      *            {@link SimulatorResourceModel} holding the representation of
 184      *            the resource.
 185      * @param onPutListener
 186      *            Event handler which will be invoked with the response for PUT
 187      *            request with a map of attribute name and values.
 188      *
 189      * @throws InvalidArgsException
 190      *             This exception will be thrown if any parameter has invalid
 191      *             value.
 192      * @throws SimulatorException
 193      *             This exception will be thrown for other errors.
 194      */
 195     public void put(Map<String, String> queryParams,
 196             SimulatorResourceModel representation,
 197             PutResponseListener onPutListener) throws InvalidArgsException,
 198             SimulatorException {
 199         nativePut(null, queryParams, representation, onPutListener);
 200     }
 201
 202     /**
 203      * API to send PUT request to the resource. Response will be notified
 204      * asynchronously via callback set for {@link PutResponseListener}.
 205      *
 206      * @param resourceInterface
 207      *            Interface type of the resource to operate on.
 208      * @param queryParams
 209      *            Map which can have the query parameter name and value.
 210      * @param representation
 211      *            {@link SimulatorResourceModel} holding the representation of
 212      *            the resource.
 213      * @param onPutListener
 214      *            Event handler which will be invoked with the response for PUT
 215      *            request with a map of attribute name and values.
 216      *
 217      * @throws InvalidArgsException
 218      *             This exception will be thrown if any parameter has invalid
 219      *             value.
 220      * @throws SimulatorException
 221      *             This exception will be thrown for other errors.
 222      */
 223     public void put(String resourceInterface, Map<String, String> queryParams,
 224             SimulatorResourceModel representation,
 225             PutResponseListener onPutListener) throws InvalidArgsException,
 226             SimulatorException {
 227         if (null == resourceInterface || resourceInterface.isEmpty())
 228             throw new InvalidArgsException(
 229                     SimulatorResult.SIMULATOR_INVALID_PARAM,
 230                     "Invalid resource interface!");
 231         nativePut(resourceInterface, queryParams, representation, onPutListener);
 232     }
 233
 234     /**
 235      * API to send POST request to the resource. Response will be notified
 236      * asynchronously via callback set for {@link PostResponseListener}.
 237      *
 238      * @param queryParams
 239      *            Map which can have the query parameter name and value.
 240      * @param representation
 241      *            {@link SimulatorResourceModel} holding the representation of
 242      *            the resource.
 243      * @param onPostListener
 244      *            Event handler which will be invoked with the response for POST
 245      *            request with a map of attribute name and values.
 246      *
 247      * @throws InvalidArgsException
 248      *             This exception will be thrown if any parameter has invalid
 249      *             value.
 250      * @throws SimulatorException
 251      *             This exception will be thrown for other errors.
 252      */
 253     public void post(Map<String, String> queryParams,
 254             SimulatorResourceModel representation,
 255             PostResponseListener onPostListener) throws InvalidArgsException,
 256             SimulatorException {
 257         nativePost(null, queryParams, representation, onPostListener);
 258     }
 259
 260     /**
 261      * API to send POST request to the resource. Response will be notified
 262      * asynchronously via callback set for {@link PostResponseListener}.
 263      *
 264      * @param resourceInterface
 265      *            Interface type of the resource to operate on.
 266      * @param queryParams
 267      *            Map which can have the query parameter name and value.
 268      * @param representation
 269      *            {@link SimulatorResourceModel} holding the representation of
 270      *            the resource.
 271      * @param onPostListener
 272      *            Event handler which will be invoked with the response for POST
 273      *            request with a map of attribute name and values.
 274      *
 275      * @throws InvalidArgsException
 276      *             This exception will be thrown if any parameter has invalid
 277      *             value.
 278      * @throws SimulatorException
 279      *             This exception will be thrown for other errors.
 280      */
 281     public void post(String resourceInterface, Map<String, String> queryParams,
 282             SimulatorResourceModel representation,
 283             PostResponseListener onPostListener) throws InvalidArgsException,
 284             SimulatorException {
 285         if (null == resourceInterface || resourceInterface.isEmpty())
 286             throw new InvalidArgsException(
 287                     SimulatorResult.SIMULATOR_INVALID_PARAM,
 288                     "Invalid resource interface!");
 289         nativePost(resourceInterface, queryParams, representation,
 290                 onPostListener);
 291     }
 292
 293     /**
 294      * API to start observing the resource.
 295      *
 296      * @param onObserveListener
 297      *            The handler method which will be invoked with a map of
 298      *            attribute names and values whenever there is a change in
 299      *            resource model of the remote resource.
 300      *
 301      * @throws InvalidArgsException
 302      *             This exception will be thrown if any parameter has invalid
 303      *             values.
 304      * @throws SimulatorException
 305      *             This exception will be thrown for other errors.
 306      */
 307     public void observe(ObserveNotificationListener onObserveListener)
 308             throws InvalidArgsException, SimulatorException {
 309         nativeStartObserve(null, onObserveListener);
 310     }
 311
 312     /**
 313      * API to start observing the resource.
 314      *
 315      * @param queryParams
 316      *            Map which can have the query parameter names and values.
 317      * @param onObserveListener
 318      *            The handler method which will be invoked with a map of
 319      *            attribute names and values whenever there is a change in
 320      *            resource model of the remote resource.
 321      *
 322      * @throws InvalidArgsException
 323      *             This exception will be thrown if any parameter has invalid
 324      *             values.
 325      * @throws SimulatorException
 326      *             This exception will be thrown for other errors.
 327      */
 328     public void observe(Map<String, String> queryParams,
 329             ObserveNotificationListener onObserveListener)
 330             throws InvalidArgsException, SimulatorException {
 331         if (null == queryParams)
 332             throw new InvalidArgsException(
 333                     SimulatorResult.SIMULATOR_INVALID_PARAM,
 334                     "Invalid Query Parameters!");
 335         nativeStartObserve(queryParams, onObserveListener);
 336     }
 337
 338     /**
 339      * API to stop observing the resource.
 340      *
 341      * @throws InvalidArgsException
 342      *             This exception will be thrown if the native remote resource
 343      *             object is unavailable.
 344      * @throws SimulatorException
 345      *             This exception will be thrown for other errors.
 346      */
 347     public void stopObserve() throws InvalidArgsException, SimulatorException {
 348         nativeStopObserve();
 349     }
 350
 351     /**
 352      * API to provide remote resource configure information, which is required
 353      * for using automation feature.
 354      *
 355      * @param path
 356      *            Path to RAML file.
 357      *
 358      * @return Representation {@link SimulatorResourceModel} holding the
 359      *         representation of the remote resource.
 360      *
 361      * @throws InvalidArgsException
 362      *             Thrown if the RAML configuration file path is invalid.
 363      * @throws SimulatorException
 364      *             Thrown for other errors.
 365      */
 366     public Map<RequestType, SimulatorRequestModel> setConfigInfo(String path)
 367             throws InvalidArgsException, SimulatorException {
 368         return nativeSetConfigInfo(path);
 369     }
 370
 371     /**
 372      * API to send multiple requests for the resource, based on the configure
 373      * file provided from {@link setConfigInfo}. This verifies response received
 374      * as well.
 375      *
 376      * @param type
 377      *            Request type to verify.
 378      * @param onVerifyListener
 379      *            This event handler will be invoked with the current status of
 380      *            the automation.
 381      *
 382      * @return Automation ID.
 383      *
 384      * @throws InvalidArgsException
 385      *             This exception will be thrown if any parameter has invalid
 386      *             value.
 387      * @throws NoSupportException
 388      *             Thrown either if the resource does not support the request
 389      *             type or the resource is not configured with RAML.
 390      * @throws OperationInProgressException
 391      *             Thrown if another request generation session is already in
 392      *             progress.
 393      * @throws SimulatorException
 394      *             This exception will be thrown for other errors.
 395      */
 396     public int startVerification(RequestType type,
 397             VerificationListener onVerifyListener) throws InvalidArgsException,
 398             NoSupportException, OperationInProgressException,
 399             SimulatorException {
 400         return nativeStartAutoRequesting(type, onVerifyListener);
 401     }
 402
 403     /**
 404      * API to stop sending requests which has been started using
 405      * {@link startVerification}.
 406      *
 407      * @param id
 408      *            Automation ID.
 409      *
 410      * @throws InvalidArgsException
 411      *             Thrown if the automation ID is invalid.
 412      * @throws SimulatorException
 413      *             Thrown for other errors.
 414      */
 415     public void stopVerification(int id) throws InvalidArgsException,
 416             SimulatorException {
 417         nativeStopAutoRequesting(id);
 418     }
 419
 420     /**
 421      * Listener for receiving asynchronous response for GET request.
 422      */
 423     public interface GetResponseListener {
 424         /**
 425          * Method will be called when response for GET request arrives.
 426          *
 427          * @param uid
 428          *            Unique Id of the resource.
 429          * @param result
 430          *            Error code {@link SimulatorResult}.
 431          * @param resourceModel
 432          *            {@link SimulatorResourceModel}.
 433          */
 434         public void onGetResponse(String uid, SimulatorResult result,
 435                 SimulatorResourceModel resourceModel);
 436     }
 437
 438     /**
 439      * Listener for receiving asynchronous response for PUT request.
 440      */
 441     public interface PutResponseListener {
 442         /**
 443          * Method will be called when response for PUT request arrives.
 444          *
 445          * @param uid
 446          *            Unique Id of the resource.
 447          * @param result
 448          *            Error code {@link SimulatorResult}.
 449          * @param resourceModel
 450          *            {@link SimulatorResourceModel}.
 451          */
 452         public void onPutResponse(String uid, SimulatorResult result,
 453                 SimulatorResourceModel resourceModel);
 454     }
 455
 456     /**
 457      * Listener for receiving asynchronous response for POST request.
 458      */
 459     public interface PostResponseListener {
 460         /**
 461          * Method will be called when response for POST request arrives.
 462          *
 463          * @param uid
 464          *            Unique Id of the resource.
 465          * @param result
 466          *            Error code {@link SimulatorResult}.
 467          * @param resourceModel
 468          *            {@link SimulatorResourceModel}.
 469          */
 470         public void onPostResponse(String uid, SimulatorResult result,
 471                 SimulatorResourceModel resourceModel);
 472     }
 473
 474     /**
 475      * Listener for getting asynchronous notification whenever remote resource's
 476      * representation gets changed.
 477      */
 478     public interface ObserveNotificationListener {
 479         /**
 480          * This method will be called when there is a change in the resource
 481          * model of the remote resource.
 482          *
 483          * @param uid
 484          *            Unique Id of the resource.
 485          * @param resourceModel
 486          *            {@link SimulatorResourceModel}.
 487          * @param sequenceNumber
 488          *            Sequential number for ordering the model change
 489          *            notifications.
 490          */
 491         public void onObserveNotification(String uid,
 492                 SimulatorResourceModel resourceModel, int sequenceNumber);
 493     }
 494
 495     /**
 496      * Listener for receiving the verification session status.
 497      */
 498     public interface VerificationListener {
 499         /**
 500          * Called when the verification request is accepted and started.
 501          *
 502          * @param uid
 503          *            Unique Id of the resource.
 504          * @param id
 505          *            Verification Id.
 506          */
 507         public void onVerificationStarted(String uid, int id);
 508
 509         /**
 510          * Called when the verification is stopped before its completion.
 511          *
 512          * @param uid
 513          *            Unique Id of the resource.
 514          * @param id
 515          *            Verification Id.
 516          */
 517         public void onVerificationAborted(String uid, int id);
 518
 519         /**
 520          * Called when the verification is done.
 521          *
 522          * @param uid
 523          *            Unique Id of the resource.
 524          * @param id
 525          *            Verification Id.
 526          */
 527         public void onVerificationCompleted(String uid, int id);
 528     }
 529
 530     private SimulatorRemoteResource(long nativeHandle) {
 531         mNativeHandle = nativeHandle;
 532     }
 533
 534     private native void nativeGet(String resourceInterface,
 535             Map<String, String> queryParamsMap,
 536             GetResponseListener onGetListener);
 537
 538     private native void nativePut(String resourceInterface,
 539             Map<String, String> queryParams,
 540             SimulatorResourceModel representation,
 541             PutResponseListener onPutListener);
 542
 543     private native void nativePost(String resourceInterface,
 544             Map<String, String> queryParams,
 545             SimulatorResourceModel representation,
 546             PostResponseListener onPostListener);
 547
 548     private native void nativeStartObserve(Map<String, String> queryParams,
 549             ObserveNotificationListener onObserveListener);
 550
 551     private native void nativeStopObserve();
 552
 553     private native Map<RequestType, SimulatorRequestModel> nativeSetConfigInfo(
 554             String path);
 555
 556     private native int nativeStartAutoRequesting(RequestType type,
 557             VerificationListener onVerifyListener);
 558
 559     private native void nativeStopAutoRequesting(int id);
 560
 561     private native void nativeDispose();
 562 }