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