service/simulator/java/sdk/src/org/oic/simulator/server/SimulatorResource.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.server;
  18
  19 import java.util.Vector;
  20
  21 import org.oic.simulator.InvalidArgsException;
  22 import org.oic.simulator.SimulatorException;
  23 import org.oic.simulator.SimulatorResourceModel;
  24
  25 /**
  26  * This class serves as a base class type for all the resources in the
  27  * simulator. It provides APIs to get and update the resource details, and
  28  * register listeners to get notifications for resource model changes and
  29  * observe requests from clients, and APIs to register/ unregister the resource
  30  * with the platform.
  31  */
  32 public class SimulatorResource {
  33
  34     private native void dispose();
  35
  36     protected long mNativeHandle;
  37
  38     protected SimulatorResource() {
  39     }
  40
  41     @Override
  42     protected void finalize() throws Throwable {
  43         try {
  44             dispose();
  45         } catch (Throwable t) {
  46             throw t;
  47         } finally {
  48             super.finalize();
  49         }
  50     }
  51
  52     /**
  53      * Enum to represent the type of resource.
  54      */
  55     public enum Type {
  56         SINGLE, COLLECTION
  57     }
  58
  59     /**
  60      * Enum to represent the update type of automation.
  61      */
  62     public enum AutoUpdateType {
  63         ONE_TIME, REPEAT
  64     }
  65
  66     /**
  67      * API to get the name of the resource.
  68      *
  69      * @return Name of the resource.
  70      *
  71      * @throws SimulatorException
  72      *             This exception will be thrown if the native resource object
  73      *             does not exist or for some general errors.
  74      */
  75     public native String getName() throws SimulatorException;
  76
  77     /**
  78      * API to get the type which indicates whether resource is single or
  79      * collection resource.
  80      *
  81      * @return Type of resource.
  82      *
  83      * @throws SimulatorException
  84      *             This exception will be thrown if the native resource object
  85      *             does not exist or for some general errors.
  86      */
  87     public native Type getType() throws SimulatorException;
  88
  89     /**
  90      * API to get the resource URI.
  91      *
  92      * @return Resource URI.
  93      *
  94      * @throws SimulatorException
  95      *             This exception will be thrown if the native resource object
  96      *             does not exist or for some general errors.
  97      */
  98     public native String getURI() throws SimulatorException;
  99
 100     /**
 101      * API to get the resource type.
 102      *
 103      * @return Resource type.
 104      *
 105      * @throws SimulatorException
 106      *             This exception will be thrown if the native resource object
 107      *             does not exist or for some general errors.
 108      */
 109     public native String getResourceType() throws SimulatorException;
 110
 111     /**
 112      * API to get the interfaces resource is bound with.
 113      *
 114      * @return Interface types.
 115      *
 116      * @throws SimulatorException
 117      *             This exception will be thrown if the native resource object
 118      *             does not exist or for some general errors.
 119      */
 120     public native Vector<String> getInterface() throws SimulatorException;
 121
 122     /**
 123      * API to get the observable state of resource.
 124      *
 125      * @return Observable state - true if resource is observable, otherwise
 126      *         false.
 127      *
 128      * @throws SimulatorException
 129      *             This exception will be thrown if the native resource object
 130      *             does not exist or for some general errors.
 131      */
 132     public native boolean isObservable() throws SimulatorException;
 133
 134     /**
 135      * API to get the start state of resource.
 136      *
 137      * @return Start state - true if resource is started, otherwise false.
 138      *
 139      * @throws SimulatorException
 140      *             This exception will be thrown if the native resource object
 141      *             does not exist or for some general errors.
 142      */
 143     public native boolean isStarted() throws SimulatorException;
 144
 145     /**
 146      * API to get the {@link SimulatorResourceModel} of the simulated resource.
 147      *
 148      * @return {@link SimulatorResourceModel} object on success, otherwise null.
 149      *
 150      * @throws SimulatorException
 151      *             This exception will be thrown if simulated resource is not
 152      *             proper.
 153      */
 154     public native SimulatorResourceModel getResourceModel()
 155             throws SimulatorException;
 156
 157     /**
 158      * API to set the name of the resource.
 159      *
 160      * @param name
 161      *            Name to be set.
 162      *
 163      * @throws InvalidArgsException
 164      *             This exception will be thrown if the resource name is
 165      *             invalid.
 166      * @throws SimulatorException
 167      *             This exception will be thrown if the native resource object
 168      *             does not exist or for some general errors.
 169      */
 170     public native void setName(String name) throws InvalidArgsException,
 171             SimulatorException;
 172
 173     /**
 174      * API to set the resource URI.
 175      *
 176      * @param uri
 177      *            URI to be set.
 178      *
 179      * @throws InvalidArgsException
 180      *             This exception will be thrown if the resource URI is invalid.
 181      * @throws SimulatorException
 182      *             A resource needs to be stopped by calling the stop() before
 183      *             calling this API. This exception will be thrown if the native
 184      *             resource object has not yet been stopped.
 185      */
 186     public native void setURI(String uri) throws InvalidArgsException,
 187             SimulatorException;
 188
 189     /**
 190      * API to set the resource type.
 191      *
 192      * @param resourceType
 193      *            Resource type string.
 194      *
 195      * @throws InvalidArgsException
 196      *             This exception will be thrown if the resource type is
 197      *             invalid.
 198      * @throws SimulatorException
 199      *             This exception will be thrown if the native resource object
 200      *             does not exist or for some general errors.
 201      */
 202     public native void setResourceType(String resourceType)
 203             throws InvalidArgsException, SimulatorException;
 204
 205     /**
 206      * API to add interface type for resource.
 207      *
 208      * @param interfaceType
 209      *            Interface to be added for resource.
 210      *
 211      * @throws InvalidArgsException
 212      *             This exception will be thrown if the interface type is
 213      *             invalid.
 214      * @throws SimulatorException
 215      *             This exception will be thrown if the native resource object
 216      *             does not exist or for some general errors.
 217      */
 218     public native void addInterface(String interfaceType)
 219             throws InvalidArgsException, SimulatorException;
 220
 221     /**
 222      * API to remove interface type for resource.
 223      *
 224      * @param interfaceType
 225      *            Interface to be remove for resource.
 226      * @throws InvalidArgsException
 227      *             This exception will be thrown if the interface type is
 228      *             invalid.
 229      * @throws SimulatorException
 230      *             This exception will be thrown if the native resource object
 231      *             does not exist or for some general errors.
 232      */
 233     public native void removeInterface(String interfaceType)
 234             throws InvalidArgsException, SimulatorException;
 235
 236     /**
 237      * API to add a list of interfaces for resource.
 238      *
 239      * @param interfaceType
 240      *            List of interfaces to be added to the resource.
 241      *
 242      * @throws InvalidArgsException
 243      *             This exception will be thrown if the interface type is
 244      *             invalid.
 245      * @throws SimulatorException
 246      *             This exception will be thrown if the native resource object
 247      *             does not exist or for some general errors.
 248      */
 249     public native void addInterfaces(Vector<String> interfaceType)
 250             throws InvalidArgsException, SimulatorException;
 251
 252     /**
 253      * API to remove interface type for resource.
 254      *
 255      * @param interfaceType
 256      *            List of interfaces to be removed from the resource.
 257      * @throws InvalidArgsException
 258      *             This exception will be thrown if the interface type is
 259      *             invalid.
 260      * @throws SimulatorException
 261      *             This exception will be thrown if the native resource object
 262      *             does not exist or for some general errors.
 263      */
 264     public native void removeInterfaces(Vector<String> interfaceType)
 265             throws InvalidArgsException, SimulatorException;
 266
 267     /**
 268      * API to make the resource observable or not.
 269      *
 270      * @param state
 271      *            True makes the resource observable, otherwise non-observable.
 272      *
 273      * @throws SimulatorException
 274      *             This exception will be thrown if the native resource object
 275      *             does not exist or for some general errors.
 276      */
 277     public native void setObservable(boolean state) throws SimulatorException;
 278
 279     /**
 280      * API to set the listener for receiving the notifications when observer is
 281      * registered or unregistered with resource.
 282      *
 283      * @param listener
 284      *            Callback to be set for receiving the notifications.
 285      *
 286      * @throws InvalidArgsException
 287      *             This exception will be thrown if the listener is invalid.
 288      * @throws SimulatorException
 289      *             This exception will be thrown if the native resource object
 290      *             does not exist or for some general errors.
 291      */
 292     public native void setObserverListener(ObserverListener listener)
 293             throws InvalidArgsException, SimulatorException;
 294
 295     /**
 296      * API to set listener for receiving notifications when resource's model
 297      * gets changed.
 298      *
 299      * @param listener
 300      *            {@link ResourceModelChangeListener}.
 301      *
 302      * @throws InvalidArgsException
 303      *             This exception will be thrown on invalid input.
 304      * @throws SimulatorException
 305      *             This exception will be thrown for other errors.
 306      */
 307     public native void setResourceModelChangeListener(
 308             ResourceModelChangeListener listener) throws InvalidArgsException,
 309             SimulatorException;
 310
 311     /**
 312      * API to start(register) the resource.
 313      *
 314      * @throws SimulatorException
 315      *             This exception will be thrown if the native resource object
 316      *             does not exist or for some general errors.
 317      */
 318     public native void start() throws SimulatorException;
 319
 320     /**
 321      * API to stop(unregister) the resource.
 322      *
 323      * @throws SimulatorException
 324      *             This exception will be thrown if the native resource object
 325      *             does not exist or for some general errors.
 326      */
 327     public native void stop() throws SimulatorException;
 328
 329     /**
 330      * API to get observers which are registered with resource.
 331      *
 332      * @return observers as an array of {@link Observer}.
 333      *
 334      * @throws SimulatorException
 335      *             This exception will be thrown if the native resource object
 336      *             does not exist or for some general errors.
 337      */
 338     public native Vector<Observer> getObservers() throws SimulatorException;
 339
 340     /**
 341      * API to notify current resource model to a specific observer.
 342      *
 343      * @param observerId
 344      *            Observer ID to notify.
 345      *
 346      * @throws SimulatorException
 347      *             This exception will be thrown if the native resource object
 348      *             does not exist or for some general errors.
 349      */
 350     public native void notifyObserver(int observerId) throws SimulatorException;
 351
 352     /**
 353      * API to notify current resource model to all registered observers.
 354      *
 355      * @throws SimulatorException
 356      *             This exception will be thrown if the native resource object
 357      *             does not exist or for some general errors.
 358      */
 359     public native void notifyAllObservers() throws SimulatorException;
 360
 361     /**
 362      * Listener for receiving notification when observer is registered or
 363      * unregistered with the resource.
 364      */
 365     public interface ObserverListener {
 366         /**
 367          * Method will be invoked when an observer is registered with resource.
 368          *
 369          * @param resourceURI
 370          *            URI of the resource.
 371          * @param observer
 372          *            {@link Observer} object containing the details of
 373          *            observer.
 374          */
 375         public void onObserverAdded(String resourceURI, Observer observer);
 376
 377         /**
 378          * Method will be invoked when an observer is unregistered from the
 379          * resource.
 380          *
 381          * @param resourceURI
 382          *            URI of the resource.
 383          * @param observer
 384          *            {@link Observer} object containing the details of
 385          *            observer.
 386          */
 387         public void onObserverRemoved(String resourceURI, Observer observer);
 388     }
 389
 390     /**
 391      * Listener for receiving notification on completion of automatically
 392      * updating attribute value from its range or value set property.
 393      */
 394     public interface AutoUpdateListener {
 395         /**
 396          * Method for receiving automation complete notifications.
 397          *
 398          * @param uri
 399          *            URI of resource.
 400          * @param id
 401          *            Identifier for auto resource/attribute update session.
 402          */
 403         public void onUpdateComplete(String uri, int id);
 404     }
 405
 406     /**
 407      * Listener for receiving notifications whenever there is a change in the
 408      * resource model.
 409      */
 410     public interface ResourceModelChangeListener {
 411         /**
 412          * Method will be invoked to notify about the changes in the resource
 413          * model.
 414          *
 415          * @param uri
 416          *            URI of resource.
 417          * @param resourceModel
 418          *            {@link SimulatorResourceModel} of the resource.
 419          */
 420         public void onResourceModelChanged(String uri,
 421                 SimulatorResourceModel resourceModel);
 422     }
 423 }