service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/SSMInterface.java

   1 /******************************************************************
   2  *
   3  * Copyright 2015 Samsung Electronics All Rights Reserved.
   4  *
   5  *
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  *      http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  ******************************************************************/
  20 /**
  21  * @file    SSMInterface.java
  22  *
  23  * @brief    This file gives description of SSMInterface class and its utility functions.
  24  *         This is the interface between an application and the query engine.
  25  *         SSMinterface makes desired queries in form of CQL(Context Query Language)
  26  *         to the query engine and passes the returned result obtained in form of callback
  27  *         back to the application.
  28  */
  29
  30 package org.iotivity.service.ssm;
  31
  32 import java.util.ArrayList;
  33 import java.util.HashMap;
  34 import java.util.List;
  35 import java.util.Map;
  36 import java.util.concurrent.locks.Lock;
  37 import java.util.concurrent.locks.ReentrantLock;
  38
  39 /**
  40  * @class SSMInterface
  41  * @brief This class provides a set of APIs to manage the SSM framework
  42  *      This class sits in between the application and query engine and acts
  43  *      as an interface between them. SSMinterface makes desired queries in form of CQL(Context Query Language)
  44  *      to the query engine and passes the returned result obtained in form of callback
  45  *      back to the application
  46  */
  47 public class SSMInterface
  48 {
  49
  50         /**
  51          * @class QueryEngineEventReceiver
  52          * @brief This class provides a set of APIs to handle query engine events
  53          *          related to soft sensor Interface framework.
  54          *
  55          *
  56          */
  57         private class QueryEngineEventReceiver extends IQueryEngineEvent
  58         {
  59                 private Lock mMtxListener = new ReentrantLock();
  60                 private Map<Integer, IQueryEngineEvent> mMapListener = new HashMap<Integer, IQueryEngineEvent>();
  61
  62                 /**
  63                  * Transmits result of SSMCore to Application layer
  64                  *     This abstract method needs to be implemeted by application
  65                  *     as a precondition for query engine implementation.
  66                  *
  67                  * @param cqid
  68                  *              - ContextQuery ID of the registered query
  69                  *
  70                  * @param result
  71                  *              - data received from SSMCore
  72                  *
  73                  * @return void
  74                  *
  75                  */
  76                 public void onQueryEngineEvent(int cqid, DataReader result)
  77                 {
  78                     mMtxListener.lock();
  79
  80                     mMapListener.get(cqid).onQueryEngineEvent(cqid, result);
  81
  82                     mMtxListener.unlock();
  83                 }
  84
  85                 /**
  86                  * To lock QueryEngineEventReceiver object to execute a query atomically,
  87                  *         this is done to provide synchronization in case of multiple queries.
  88                  *
  89                  * @return void
  90                  *
  91                  */
  92                 void lockListener()
  93                 {
  94                     mMtxListener.lock();
  95                 }
  96
  97                 /**
  98                  * release the QueryEngineEventReceiver object
  99                  *
 100                  * @return void
 101                  *
 102                  */
 103                 void unlockListener()
 104                 {
 105                     mMtxListener.unlock();
 106                 }
 107
 108                 /**
 109                  * add listener to receive response for the registered query with SSMCore.
 110                  *     Listen for callbacks from SSMCore.
 111                  *     This is also a precondition for implementing query engine object.
 112                  *
 113                  * @param cqid
 114                  *              - ContextQuery ID of the registered query
 115                  *
 116                  * @param engineEvent
 117                  *              - query engine's event that contains the results
 118                  *
 119                  * @return void
 120                  */
 121                 void addListener(int cqid, IQueryEngineEvent engineEvent)
 122                 {
 123                     mMapListener.put(cqid, engineEvent);
 124                 }
 125
 126                 /**
 127                  * Remove listener for a query on unregistering it
 128                  *
 129                  * @param cqid
 130                  *              - ContextQuery ID of the registered query
 131                  *
 132                  * @return void
 133                  *
 134                  */
 135                 void removeListener(int cqid)
 136                 {
 137                     mMapListener.remove(cqid);
 138                 }
 139         };
 140
 141         private CoreController mSSMCore = null;
 142         private QueryEngine mQueryEngine = null;
 143         private QueryEngineEventReceiver mQueryEngineEventListenerReceiver = new QueryEngineEventReceiver();
 144         private List<Integer> mRunningCQLs = new ArrayList<Integer>();
 145
 146         public SSMInterface()
 147         {
 148         }
 149
 150         /**
 151          * Starts the framework that allows other devices to discover and communicate
 152          *     with the SSMCore and underlying query engine.
 153          *
 154          * @param initConfig
 155          *              - initial framework specifications
 156          *
 157          * @return void
 158          *
 159          */
 160         public void startSSMCore(String initConfig) throws Exception
 161         {
 162             mSSMCore = CoreController.getInstance();
 163             mSSMCore.initializeSSMCore(initConfig);
 164             mSSMCore.startSSMCore();
 165
 166             mQueryEngine = mSSMCore.createQueryEngine();
 167
 168             mQueryEngine.registerQueryEvent(mQueryEngineEventListenerReceiver);
 169         }
 170
 171         /**
 172          * Stops the framework and terminate all communications.
 173          *
 174          * @return void
 175          *
 176          */
 177         public void stopSSMCore() throws Exception
 178         {
 179             mQueryEngine.registerQueryEvent(null);
 180             mSSMCore.releaseQueryEngine(mQueryEngine);
 181             mQueryEngineEventListenerReceiver = null;
 182             mQueryEngine = null;
 183             mSSMCore.stopSSMCore();
 184             mSSMCore.terminateSSMCore();
 185         }
 186
 187         /**
 188          * Register the query and execute statement with the query engine
 189          *     and add listener for the registered query so as to get response data.
 190          *     After success response message for registration, SSMCore sends an
 191          *     event to the client, if the specified condtions in the query is satisfied.
 192          *
 193          * @param contextQuery
 194          *             - query for requesting data
 195          *
 196          * @param listener
 197          *             - listener for receiving response data of the query
 198          *
 199          * @return int - ContextQuery ID
 200          *
 201          */
 202         public int registerQuery(String contextQuery, IQueryEngineEvent listener)
 203         throws Exception
 204         {
 205             int cqid = 0;
 206
 207             try {
 208                 mQueryEngineEventListenerReceiver.lockListener();
 209                 cqid = mQueryEngine.executeContextQuery(contextQuery);
 210                 mQueryEngineEventListenerReceiver.addListener(cqid, listener);
 211                 mRunningCQLs.add(cqid);
 212             }
 213             catch (Exception e)
 214             {
 215                 throw e;
 216             } finally {
 217                 mQueryEngineEventListenerReceiver.unlockListener();
 218             }
 219
 220             return cqid;
 221         }
 222
 223         /**
 224          * unregister a registered query using its query ID. The query corresponding
 225          *      to the cqid will be terminated and removes listener for the given query
 226          *      The SSMCore will not send any callbacks after successful unregistration.
 227          *
 228          *
 229          * @param cqid - ContextQuery ID of the query to be unregistered
 230          *
 231          * @return void
 232          *
 233          */
 234         public void unregisterQuery(int cqid) throws Exception
 235         {
 236             try {
 237                 mQueryEngineEventListenerReceiver.lockListener();
 238                 mQueryEngine.killContextQuery(cqid);
 239                 mQueryEngineEventListenerReceiver.removeListener(cqid);
 240                 mRunningCQLs.remove((Object) cqid);
 241             }
 242             catch (Exception e)
 243             {
 244                 throw e;
 245             } finally {
 246                 mQueryEngineEventListenerReceiver.unlockListener();
 247             }
 248         }
 249 }