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