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,
 146             GetResponseListener onGetListener) throws InvalidArgsException,
 147             SimulatorException {
 148         nativeGet(null, queryParams, onGetListener);
 149     }
 150
 151     /**
 152      * API to send GET request to the resource. Response will be notified
 153      * asynchronously via callback set for {@link IGetListener}.
 154      *
 155      * @param resourceInterface
 156      *            Interface type of the resource to operate on.
 157      * @param queryParams
 158      *            Map which can have the query parameter name and value.
 159      * @param onGetListener
 160      *            Event handler which will be invoked with the response for GET
 161      *            request with a map of attribute name and values.
 162      *
 163      * @throws InvalidArgsException
 164      *             This exception will be thrown if any parameter has invalid
 165      *             values.
 166      * @throws SimulatorException
 167      *             This exception will be thrown for other errors.
 168      */
 169     public void get(String resourceInterface, Map<String, String> queryParams,
 170             GetResponseListener onGetListener) throws InvalidArgsException,
 171             SimulatorException {
 172         if (null == resourceInterface || resourceInterface.isEmpty())
 173             throw new InvalidArgsException(
 174                     SimulatorResult.SIMULATOR_INVALID_PARAM,
 175                     "Invalid resource interface!");
 176         nativeGet(resourceInterface, queryParams, onGetListener);
 177     }
 178
 179     /**
 180      * API to send PUT request to the resource. Response will be notified
 181      * asynchronously via callback set for {@link IPutListener}.
 182      *
 183      * @param queryParams
 184      *            Map which can have the query parameter name and value.
 185      * @param representation
 186      *            {@link SimulatorResourceModel} holding the representation of
 187      *            the resource.
 188      * @param onPutListener
 189      *            Event handler which will be invoked with the response for PUT
 190      *            request with a map of attribute name and values.
 191      *
 192      * @throws InvalidArgsException
 193      *             This exception will be thrown if any parameter has invalid
 194      *             value.
 195      * @throws SimulatorException
 196      *             This exception will be thrown for other errors.
 197      */
 198     public void put(Map<String, String> queryParams,
 199             SimulatorResourceModel representation,
 200             PutResponseListener onPutListener) throws InvalidArgsException,
 201             SimulatorException {
 202         nativePut(null, queryParams, representation, onPutListener);
 203     }
 204
 205     /**
 206      * API to send PUT request to the resource. Response will be notified
 207      * asynchronously via callback set for {@link IPutListener}.
 208      *
 209      * @param resourceInterface
 210      *            Interface type of the resource to operate on.
 211      * @param queryParams
 212      *            Map which can have the query parameter name and value.
 213      * @param representation
 214      *            {@link SimulatorResourceModel} holding the representation of
 215      *            the resource.
 216      * @param onPutListener
 217      *            Event handler which will be invoked with the response for PUT
 218      *            request with a map of attribute name and values.
 219      *
 220      * @throws InvalidArgsException
 221      *             This exception will be thrown if any parameter has invalid
 222      *             value.
 223      * @throws SimulatorException
 224      *             This exception will be thrown for other errors.
 225      */
 226     public void put(String resourceInterface, Map<String, String> queryParams,
 227             SimulatorResourceModel representation,
 228             PutResponseListener onPutListener) throws InvalidArgsException,
 229             SimulatorException {
 230         if (null == resourceInterface || resourceInterface.isEmpty())
 231             throw new InvalidArgsException(
 232                     SimulatorResult.SIMULATOR_INVALID_PARAM,
 233                     "Invalid resource interface!");
 234         nativePut(resourceInterface, queryParams, representation, onPutListener);
 235     }
 236
 237     /**
 238      * API to send POST request to the resource. Response will be notified
 239      * asynchronously via callback set for {@link IPostListener}.
 240      *
 241      * @param queryParams
 242      *            Map which can have the query parameter name and value.
 243      * @param representation
 244      *            {@link SimulatorResourceModel} holding the representation of
 245      *            the resource.
 246      * @param onPostListener
 247      *            Event handler which will be invoked with the response for POST
 248      *            request with a map of attribute name and values.
 249      *
 250      * @throws InvalidArgsException
 251      *             This exception will be thrown if any parameter has invalid
 252      *             value.
 253      * @throws SimulatorException
 254      *             This exception will be thrown for other errors.
 255      */
 256     public void post(Map<String, String> queryParams,
 257             SimulatorResourceModel representation,
 258             PostResponseListener onPostListener) throws InvalidArgsException,
 259             SimulatorException {
 260         nativePost(null, queryParams, representation, onPostListener);
 261     }
 262
 263     /**
 264      * API to send POST request to the resource. Response will be notified
 265      * asynchronously via callback set for {@link IPostListener}.
 266      *
 267      * @param resourceInterface
 268      *            Interface type of the resource to operate on.
 269      * @param queryParams
 270      *            Map which can have the query parameter name and value.
 271      * @param representation
 272      *            {@link SimulatorResourceModel} holding the representation of
 273      *            the resource.
 274      * @param onPostListener
 275      *            Event handler which will be invoked with the response for POST
 276      *            request with a map of attribute name and values.
 277      *
 278      * @throws InvalidArgsException
 279      *             This exception will be thrown if any parameter has invalid
 280      *             value.
 281      * @throws SimulatorException
 282      *             This exception will be thrown for other errors.
 283      */
 284     public void post(String resourceInterface, Map<String, String> queryParams,
 285             SimulatorResourceModel representation,
 286             PostResponseListener onPostListener) throws InvalidArgsException,
 287             SimulatorException {
 288         if (null == resourceInterface || resourceInterface.isEmpty())
 289             throw new InvalidArgsException(
 290                     SimulatorResult.SIMULATOR_INVALID_PARAM,
 291                     "Invalid resource interface!");
 292         nativePost(resourceInterface, queryParams, representation,
 293                 onPostListener);
 294     }
 295
 296     /**
 297      * API to start observing the resource.
 298      *
 299      * @param queryParams
 300      *            Map which can have the query parameter names and values.
 301      * @param onObserveListener
 302      *            The handler method which will be invoked with a map of
 303      *            attribute names and values whenever there is a change in
 304      *            resource model of the remote resource.
 305      *
 306      * @throws InvalidArgsException
 307      *             This exception will be thrown if any parameter has invalid
 308      *             values.
 309      * @throws SimulatorException
 310      *             This exception will be thrown for other errors.
 311      */
 312     public native void startObserve(Map<String, String> queryParams,
 313             ObserveNotificationListener onObserveListener)
 314             throws InvalidArgsException, SimulatorException;
 315
 316     /**
 317      * API to stop observing the resource.
 318      *
 319      * @throws InvalidArgsException
 320      *             This exception will be thrown if the native remote resource
 321      *             object is unavailable.
 322      * @throws SimulatorException
 323      *             This exception will be thrown for other errors.
 324      */
 325     public native void stopObserve() throws InvalidArgsException,
 326             SimulatorException;
 327
 328     /**
 329      * API to provide remote resource configure information, which is required
 330      * for using automation feature.
 331      *
 332      * @param path
 333      *            Path to RAML file.
 334      *
 335      * @return representation {@link SimulatorResourceModel} holding the
 336      *         representation of the remote resource.
 337      *
 338      * @throws InvalidArgsException
 339      *             Thrown if the RAML configuration file path is invalid.
 340      * @throws SimulatorException
 341      *             Thrown for other errors.
 342      */
 343     public native SimulatorResourceModel setConfigInfo(String path)
 344             throws InvalidArgsException, SimulatorException;
 345
 346     /**
 347      * API to send multiple requests for the resource, based on the configure
 348      * file provided from {@link setConfigInfo}. This verifies response received
 349      * as well.
 350      *
 351      * @param type
 352      *            Request type to verify.
 353      * @param onVerifyListener
 354      *            This event handler will be invoked with the current status of
 355      *            the automation.
 356      *
 357      * @return Automation ID.
 358      *
 359      * @throws InvalidArgsException
 360      *             This exception will be thrown if any parameter has invalid
 361      *             value.
 362      * @throws NoSupportException
 363      *             Thrown either if the resource does not support the request
 364      *             type or the resource is not configured with RAML.
 365      * @throws OperationInProgressException
 366      *             Thrown if another request generation session is already in
 367      *             progress.
 368      * @throws SimulatorException
 369      *             This exception will be thrown for other errors.
 370      */
 371     public int startVerification(VerificationType type,
 372             VerificationListener onVerifyListener) throws InvalidArgsException,
 373             NoSupportException, OperationInProgressException,
 374             SimulatorException {
 375         return startVerification(type.ordinal(), onVerifyListener);
 376     }
 377
 378     /**
 379      * API to stop sending requests which has been started using
 380      * {@link setConfigInfo}.
 381      *
 382      * @param id
 383      *            Automation ID.
 384      *
 385      * @throws InvalidArgsException
 386      *             Thrown if the automation ID is invalid.
 387      * @throws SimulatorException
 388      *             Thrown for other errors.
 389      */
 390     public native void stopVerification(int id) throws InvalidArgsException,
 391             SimulatorException;
 392
 393     /**
 394      * Listener for receiving asynchronous response for GET request.
 395      */
 396     public interface GetResponseListener {
 397         /**
 398          * Method will be called when response for GET request arrives.
 399          *
 400          * @param uid
 401          *            Unique Id of the resource.
 402          * @param result
 403          *            Error code {@link SimulatorResult}.
 404          * @param resourceModel
 405          *            {@link SimulatorResourceModel}.
 406          */
 407         public void onGetResponse(String uid, SimulatorResult result,
 408                 SimulatorResourceModel resourceModel);
 409     }
 410
 411     /**
 412      * Listener for receiving asynchronous response for PUT request.
 413      */
 414     public interface PutResponseListener {
 415         /**
 416          * Method will be called when response for PUT request arrives.
 417          *
 418          * @param uid
 419          *            Unique Id of the resource.
 420          * @param result
 421          *            Error code {@link SimulatorResult}.
 422          * @param resourceModel
 423          *            {@link SimulatorResourceModel}.
 424          */
 425         public void onPutResponse(String uid, SimulatorResult result,
 426                 SimulatorResourceModel resourceModel);
 427     }
 428
 429     /**
 430      * Listener for receiving asynchronous response for POST request.
 431      */
 432     public interface PostResponseListener {
 433         /**
 434          * Method will be called when response for POST request arrives.
 435          *
 436          * @param uid
 437          *            Unique Id of the resource.
 438          * @param result
 439          *            Error code {@link SimulatorResult}.
 440          * @param resourceModel
 441          *            {@link SimulatorResourceModel}.
 442          */
 443         public void onPostResponse(String uid, SimulatorResult result,
 444                 SimulatorResourceModel resourceModel);
 445     }
 446
 447     /**
 448      * Listener for getting asynchronous notification whenever remote resource's
 449      * representation gets changed.
 450      */
 451     public interface ObserveNotificationListener {
 452         /**
 453          * This method will be called when there is a change in the resource
 454          * model of the remote resource.
 455          *
 456          * @param uid
 457          *            Unique Id of the resource.
 458          * @param resourceModel
 459          *            {@link SimulatorResourceModel}.
 460          * @param sequenceNumber
 461          *            Sequential number for ordering the model change
 462          *            notifications.
 463          */
 464         public void onObserveNotification(String uid,
 465                 SimulatorResourceModel resourceModel, int sequenceNumber);
 466     }
 467
 468     /**
 469      * Listener for receiving the verification session status.
 470      */
 471     public interface VerificationListener {
 472         /**
 473          * Called when the verification request is accepted and started.
 474          *
 475          * @param uid
 476          *            Unique Id of the resource.
 477          * @param id
 478          *            Verification Id.
 479          */
 480         public void onVerificationStarted(String uid, int id);
 481
 482         /**
 483          * Called when the verification is stopped before its completion.
 484          *
 485          * @param uid
 486          *            Unique Id of the resource.
 487          * @param id
 488          *            Verification Id.
 489          */
 490         public void onVerificationAborted(String uid, int id);
 491
 492         /**
 493          * Called when the verification is done.
 494          *
 495          * @param uid
 496          *            Unique Id of the resource.
 497          * @param id
 498          *            Verification Id.
 499          */
 500         public void onVerificationCompleted(String uid, int id);
 501     }
 502
 503     private native void nativeGet(String resourceInterface,
 504             Map<String, String> queryParamsMap,
 505             GetResponseListener onGetListener);
 506
 507     private native void nativePut(String resourceInterface,
 508             Map<String, String> queryParams,
 509             SimulatorResourceModel representation,
 510             PutResponseListener onPutListener);
 511
 512     private native void nativePost(String resourceInterface,
 513             Map<String, String> queryParams,
 514             SimulatorResourceModel representation,
 515             PostResponseListener onPostListener);
 516
 517     private native int startVerification(int type,
 518             VerificationListener onVerifyListener);
 519 }