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 type
 297      *            Type of observation.
 298      * @param onObserveListener
 299      *            The handler method which will be invoked with a map of
 300      *            attribute names and values whenever there is a change in
 301      *            resource model of the remote resource.
 302      *
 303      * @throws InvalidArgsException
 304      *             This exception will be thrown if any parameter has invalid
 305      *             values.
 306      * @throws SimulatorException
 307      *             This exception will be thrown for other errors.
 308      */
 309     public void observe(ObserveNotificationListener onObserveListener)
 310             throws InvalidArgsException, SimulatorException {
 311         nativeStartObserve(null, onObserveListener);
 312     }
 313
 314     /**
 315      * API to start observing the resource.
 316      *
 317      * @param type
 318      *            Type of observation.
 319      * @param queryParams
 320      *            Map which can have the query parameter names and values.
 321      * @param onObserveListener
 322      *            The handler method which will be invoked with a map of
 323      *            attribute names and values whenever there is a change in
 324      *            resource model of the remote resource.
 325      *
 326      * @throws InvalidArgsException
 327      *             This exception will be thrown if any parameter has invalid
 328      *             values.
 329      * @throws SimulatorException
 330      *             This exception will be thrown for other errors.
 331      */
 332     public void observe(Map<String, String> queryParams,
 333             ObserveNotificationListener onObserveListener)
 334             throws InvalidArgsException, SimulatorException {
 335         if (null == queryParams)
 336             throw new InvalidArgsException(
 337                     SimulatorResult.SIMULATOR_INVALID_PARAM,
 338                     "Invalid Query Parameters!");
 339         nativeStartObserve(queryParams, onObserveListener);
 340     }
 341
 342     /**
 343      * API to stop observing the resource.
 344      *
 345      * @throws InvalidArgsException
 346      *             This exception will be thrown if the native remote resource
 347      *             object is unavailable.
 348      * @throws SimulatorException
 349      *             This exception will be thrown for other errors.
 350      */
 351     public void stopObserve() throws InvalidArgsException, SimulatorException {
 352         nativeStopObserve();
 353     }
 354
 355     /**
 356      * API to provide remote resource configure information, which is required
 357      * for using automation feature.
 358      *
 359      * @param path
 360      *            Path to RAML file.
 361      *
 362      * @return Representation {@link SimulatorResourceModel} holding the
 363      *         representation of the remote resource.
 364      *
 365      * @throws InvalidArgsException
 366      *             Thrown if the RAML configuration file path is invalid.
 367      * @throws SimulatorException
 368      *             Thrown for other errors.
 369      */
 370     public Map<RequestType, SimulatorRequestModel> setConfigInfo(String path)
 371             throws InvalidArgsException, SimulatorException {
 372         return nativeSetConfigInfo(path);
 373     }
 374
 375     /**
 376      * API to send multiple requests for the resource, based on the configure
 377      * file provided from {@link setConfigInfo}. This verifies response received
 378      * as well.
 379      *
 380      * @param type
 381      *            Request type to verify.
 382      * @param onVerifyListener
 383      *            This event handler will be invoked with the current status of
 384      *            the automation.
 385      *
 386      * @return Automation ID.
 387      *
 388      * @throws InvalidArgsException
 389      *             This exception will be thrown if any parameter has invalid
 390      *             value.
 391      * @throws NoSupportException
 392      *             Thrown either if the resource does not support the request
 393      *             type or the resource is not configured with RAML.
 394      * @throws OperationInProgressException
 395      *             Thrown if another request generation session is already in
 396      *             progress.
 397      * @throws SimulatorException
 398      *             This exception will be thrown for other errors.
 399      */
 400     public int startVerification(RequestType type,
 401             VerificationListener onVerifyListener) throws InvalidArgsException,
 402             NoSupportException, OperationInProgressException,
 403             SimulatorException {
 404         return nativeStartAutoRequesting(type, onVerifyListener);
 405     }
 406
 407     /**
 408      * API to stop sending requests which has been started using
 409      * {@link startVerification}.
 410      *
 411      * @param id
 412      *            Automation ID.
 413      *
 414      * @throws InvalidArgsException
 415      *             Thrown if the automation ID is invalid.
 416      * @throws SimulatorException
 417      *             Thrown for other errors.
 418      */
 419     public void stopVerification(int id) throws InvalidArgsException,
 420             SimulatorException {
 421         nativeStopAutoRequesting(id);
 422     }
 423
 424     /**
 425      * Listener for receiving asynchronous response for GET request.
 426      */
 427     public interface GetResponseListener {
 428         /**
 429          * Method will be called when response for GET request arrives.
 430          *
 431          * @param uid
 432          *            Unique Id of the resource.
 433          * @param result
 434          *            Error code {@link SimulatorResult}.
 435          * @param resourceModel
 436          *            {@link SimulatorResourceModel}.
 437          */
 438         public void onGetResponse(String uid, SimulatorResult result,
 439                 SimulatorResourceModel resourceModel);
 440     }
 441
 442     /**
 443      * Listener for receiving asynchronous response for PUT request.
 444      */
 445     public interface PutResponseListener {
 446         /**
 447          * Method will be called when response for PUT request arrives.
 448          *
 449          * @param uid
 450          *            Unique Id of the resource.
 451          * @param result
 452          *            Error code {@link SimulatorResult}.
 453          * @param resourceModel
 454          *            {@link SimulatorResourceModel}.
 455          */
 456         public void onPutResponse(String uid, SimulatorResult result,
 457                 SimulatorResourceModel resourceModel);
 458     }
 459
 460     /**
 461      * Listener for receiving asynchronous response for POST request.
 462      */
 463     public interface PostResponseListener {
 464         /**
 465          * Method will be called when response for POST request arrives.
 466          *
 467          * @param uid
 468          *            Unique Id of the resource.
 469          * @param result
 470          *            Error code {@link SimulatorResult}.
 471          * @param resourceModel
 472          *            {@link SimulatorResourceModel}.
 473          */
 474         public void onPostResponse(String uid, SimulatorResult result,
 475                 SimulatorResourceModel resourceModel);
 476     }
 477
 478     /**
 479      * Listener for getting asynchronous notification whenever remote resource's
 480      * representation gets changed.
 481      */
 482     public interface ObserveNotificationListener {
 483         /**
 484          * This method will be called when there is a change in the resource
 485          * model of the remote resource.
 486          *
 487          * @param uid
 488          *            Unique Id of the resource.
 489          * @param resourceModel
 490          *            {@link SimulatorResourceModel}.
 491          * @param sequenceNumber
 492          *            Sequential number for ordering the model change
 493          *            notifications.
 494          */
 495         public void onObserveNotification(String uid,
 496                 SimulatorResourceModel resourceModel, int sequenceNumber);
 497     }
 498
 499     /**
 500      * Listener for receiving the verification session status.
 501      */
 502     public interface VerificationListener {
 503         /**
 504          * Called when the verification request is accepted and started.
 505          *
 506          * @param uid
 507          *            Unique Id of the resource.
 508          * @param id
 509          *            Verification Id.
 510          */
 511         public void onVerificationStarted(String uid, int id);
 512
 513         /**
 514          * Called when the verification is stopped before its completion.
 515          *
 516          * @param uid
 517          *            Unique Id of the resource.
 518          * @param id
 519          *            Verification Id.
 520          */
 521         public void onVerificationAborted(String uid, int id);
 522
 523         /**
 524          * Called when the verification is done.
 525          *
 526          * @param uid
 527          *            Unique Id of the resource.
 528          * @param id
 529          *            Verification Id.
 530          */
 531         public void onVerificationCompleted(String uid, int id);
 532     }
 533
 534     private SimulatorRemoteResource(long nativeHandle) {
 535         mNativeHandle = nativeHandle;
 536     }
 537
 538     private native void nativeGet(String resourceInterface,
 539             Map<String, String> queryParamsMap,
 540             GetResponseListener onGetListener);
 541
 542     private native void nativePut(String resourceInterface,
 543             Map<String, String> queryParams,
 544             SimulatorResourceModel representation,
 545             PutResponseListener onPutListener);
 546
 547     private native void nativePost(String resourceInterface,
 548             Map<String, String> queryParams,
 549             SimulatorResourceModel representation,
 550             PostResponseListener onPostListener);
 551
 552     private native void nativeStartObserve(Map<String, String> queryParams,
 553             ObserveNotificationListener onObserveListener);
 554
 555     private native void nativeStopObserve();
 556
 557     private native Map<RequestType, SimulatorRequestModel> nativeSetConfigInfo(
 558             String path);
 559
 560     private native int nativeStartAutoRequesting(RequestType type,
 561             VerificationListener onVerifyListener);
 562
 563     private native void nativeStopAutoRequesting(int id);
 564
 565     private native void nativeDispose();
 566 }