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