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