From d22d10cd70e50a0f900583ee54f8e18a9ba3bc4a Mon Sep 17 00:00:00 2001 From: jk13 Date: Fri, 20 Mar 2015 11:14:58 +0900 Subject: [PATCH] [SSM] Add Java SDK comments and fix formatting 1. Add Java SDK description 2. Fix existing comments format Change-Id: I6d02e63a0c1afc9cab30d8103bc240bb4b890898 Signed-off-by: jk13 Reviewed-on: https://gerrit.iotivity.org/gerrit/521 Reviewed-by: Uze Choi Tested-by: Uze Choi --- .../SDK/cpp/include/SSMInterface.h | 67 +++-- .../SDK/cpp/src/InprocSSMCore.cpp | 19 ++ .../org/iotivity/service/ssm/CoreController.java | 318 +++++++++++++++++---- .../java/org/iotivity/service/ssm/DataReader.java | 101 +++++-- .../iotivity/service/ssm/IQueryEngineEvent.java | 82 +++++- .../org/iotivity/service/ssm/IReportReceiver.java | 52 +++- .../java/org/iotivity/service/ssm/ModelData.java | 110 +++++-- .../java/org/iotivity/service/ssm/QueryEngine.java | 113 ++++++-- .../org/iotivity/service/ssm/SSMInterface.java | 317 ++++++++++++++------ 9 files changed, 952 insertions(+), 227 deletions(-) diff --git a/service/soft-sensor-manager/SDK/cpp/include/SSMInterface.h b/service/soft-sensor-manager/SDK/cpp/include/SSMInterface.h index 50ab302..eab4948 100644 --- a/service/soft-sensor-manager/SDK/cpp/include/SSMInterface.h +++ b/service/soft-sensor-manager/SDK/cpp/include/SSMInterface.h @@ -1,3 +1,29 @@ +/****************************************************************** + * + * Copyright 2015 Samsung Electronics All Rights Reserved. + * + * + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ******************************************************************/ + /** + * @file SSMInterface.h + * + * @brief This file provides a set of classes for DataReader, QueryEngine and SSM utility functions + * + */ + #ifndef _SSMInterface_H_ #define _SSMInterface_H_ @@ -34,7 +60,6 @@ namespace OIC * @brief Get affected DataId. ContextModel has plenty of data so \n * returned data is matched from given condition * - * @param None * * @return int * @warning @@ -44,11 +69,10 @@ namespace OIC virtual int getDataId() = 0; /** - * @fn GetPropertyCount + * @fn getPropertyCount * @brief ContextModel has at least one property that contains data \n - * property is described from its specification. + * property as described from its specification. * - * @param None * * @return int * @warning @@ -61,7 +85,7 @@ namespace OIC * @fn getPropertyName * @brief Retrieve propertyName * - * @param [in] int propertyIndex - index of property to read + * @param [in] propertyIndex - index of property to read * * @return std::string * @warning @@ -74,7 +98,7 @@ namespace OIC * @fn getPropertyValue * @brief Retrieve propertyValue * - * @param [in] int propertyIndex - index of property to read + * @param [in] propertyIndex - index of property to read * * @return std::string * @warning @@ -87,7 +111,7 @@ namespace OIC * @fn getPropertyValueByName * @brief Retrieve propertyValue using given name * - * @param [in] std::string propertyName - property name looking for + * @param [in] propertyName - property name to look for * * @return std::string * @warning @@ -112,7 +136,7 @@ namespace OIC * @fn getAffectedModels * @brief Get affected ContextModels. The CQL can specify multiple ContextModels for retrieving data. * - * @param [in, out] std::vector *pAffectedModels - affected ContextModel list + * @param [in, out] pAffectedModels - affected ContextModel list * * @return SSMRESULT * @warning @@ -123,11 +147,11 @@ namespace OIC /** * @fn getModelDataCount - * @brief Get affected data count. There are multiple data can exist from given condition. + * @brief Get affected data count. There are multiple data that can exist from given condition. * - * @param [in] std::string modelName - affected ContextModel name + * @param [in] modelName - affected ContextModel name * - * @param [in, out] int *pDataCount - affected dataId count + * @param [in, out] pDataCount - affected dataId count * * @return SSMRESULT * @warning @@ -140,13 +164,13 @@ namespace OIC * @fn getModelData * @brief Get actual Context Model data * - * @param [in] std::string modelName - affected ContextModel name + * @param [in] modelName - affected ContextModel name * * - * @param [in] int dataIndex - affected dataId index + * @param [in] dataIndex - affected dataId index * * - * @param [out] IModelData **ppModelData - affected ContextModel data reader + * @param [out] ppModelData - affected ContextModel data reader * * @return SSMRESULT * @warning @@ -171,9 +195,9 @@ namespace OIC * @fn onQueryEngineEvent * @brief Transmit result of SSMCore to Application layer * - * @param [in] int cqid - entered ContextQuery ID + * @param [in] cqid - entered ContextQuery ID * - * @param [in] IDataReader *pResult - result of SSMCore + * @param [in] pResult - result of SSMCore * * @return SSMRESULT * @warning @@ -189,7 +213,7 @@ namespace OIC * @fn InitializeSSM * @brief Initialize Soft sensor manager using given configuration information. * - * @param [in] std::string xmlDescription - specification described in XML + * @param [in] xmlDescription - specification described in XML * * @return SSMRESULT * @warning @@ -202,7 +226,6 @@ namespace OIC * @fn TerminateSSM * @brief Terminates Soft sensor manager * - * @param None * * @return SSMRESULT * @warning @@ -215,11 +238,11 @@ namespace OIC * @fn RegisterQuery * @brief Execute ContextQuery and return ContextQuery ID * - * @param [in] std::string queryString - query for requesting data + * @param [in] queryString - query for requesting data * - * @param [in] IQueryEngineEvent listener - listener for receiving data related to query + * @param [in] listener - listener for receiving data related to query * - * @param [in, out] int &cqid - ID of ContextQuery + * @param [in, out] cqid - ID of ContextQuery * * @return SSMRESULT * @warning @@ -232,7 +255,7 @@ namespace OIC * @fn UnregisterQuery * @brief unregister registered ContextQuery according to cqid * - * @param [in] int cqid - Context query corresponding to the cqid will be terminated + * @param [in] cqid - Context query corresponding to the cqid to be unregistered * * @return SSMRESULT * @warning diff --git a/service/soft-sensor-manager/SDK/cpp/src/InprocSSMCore.cpp b/service/soft-sensor-manager/SDK/cpp/src/InprocSSMCore.cpp index 82d2c6f..6e06e07 100644 --- a/service/soft-sensor-manager/SDK/cpp/src/InprocSSMCore.cpp +++ b/service/soft-sensor-manager/SDK/cpp/src/InprocSSMCore.cpp @@ -1,3 +1,22 @@ +/****************************************************************** + * + * Copyright 2015 Samsung Electronics All Rights Reserved. + * + * + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ******************************************************************/ #include "SSMInterface.h" #include "SSMInterface/SSMCore.h" #include "Common/PlatformLayer.h" diff --git a/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/CoreController.java b/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/CoreController.java index 35ad502..cbbd2bb 100644 --- a/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/CoreController.java +++ b/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/CoreController.java @@ -1,83 +1,289 @@ +/****************************************************************** + * + * Copyright 2015 Samsung Electronics All Rights Reserved. + * + * + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ******************************************************************/ + +/** + * @file CoreController.java + * + * @brief This file provides a class containing a set of APIs for soft sensor manager + * application. + * + */ + package org.iotivity.service.ssm; import java.util.List; -public class CoreController { - static { - try { - String workingPath = System.getProperty("user.dir"); +/** + * @class CoreController + * @brief This class provides a set of APIs relating to soft sensor manager + * It contains utility API's for DataReader, QueryEngine and SSMInterface classes. + * + * + */ +public class CoreController +{ + static + { + try { + String workingPath = System.getProperty("user.dir"); + + // for android: not complete method + if (System.getProperty("os.name").toLowerCase().equals("linux")) + { + // System.out.println("System load Android library"); + System.loadLibrary("oc_logger"); + System.loadLibrary("coap"); + System.loadLibrary("octbstack"); + System.loadLibrary("oc"); + System.loadLibrary("SSMCore"); + } + else { + // System.out.println("System load 32bit library"); + System.load(workingPath + "SSMCore_Windows.dll"); + } + } + catch (UnsatisfiedLinkError e) + { + System.out.println(e.getMessage()); + } + } - // for android: not complete method - if (System.getProperty("os.name").toLowerCase().equals("linux")) { - // System.out.println("System load Android library"); - System.loadLibrary("oc_logger"); - System.loadLibrary("coap"); - System.loadLibrary("octbstack"); - System.loadLibrary("oc"); - System.loadLibrary("SSMCore"); - } else { - // System.out.println("System load 32bit library"); - System.load(workingPath + "SSMCore_Windows.dll"); - } - } catch (UnsatisfiedLinkError e) { - System.out.println(e.getMessage()); - } - } + static private CoreController coreController; - static private CoreController coreController; + public static CoreController getInstance() + { + if (coreController == null) + coreController = new CoreController(); - public static CoreController getInstance() { - if (coreController == null) - coreController = new CoreController(); + return coreController; + } - return coreController; - } + /** + * @fn InitializeSSMCore + * @brief Initialize a framework using the given configuration + * + * @param [in] xmlDescription - Framework specifications described in XML format + * + * + * @return void + */ + public native void InitializeSSMCore(String xmlDescription) + throws Exception; - public native void InitializeSSMCore(String xmlDescription) - throws Exception; + /** + * @fn StartSSMCore + * @brief Starts the framework that allows other devices to discover and communicate + * with the SSMCore and underlying query engine. + * + * @return void + */ + public native void StartSSMCore() throws Exception; - public native void StartSSMCore() throws Exception; + /** + * @fn StopSSMCore + * @brief Stops the framework and terminate all communications. + * + * @return void + */ + public native void StopSSMCore() throws Exception; - public native void StopSSMCore() throws Exception; + /** + * @fn TerminateSSMCore + * @brief Terminate the framework, return all allocated resources + * + * @return void + */ + public native void TerminateSSMCore() throws Exception; - public native void TerminateSSMCore() throws Exception; + /** + * @fn CreateQueryEngine + * @brief Creates an instance of the Query Engine + * + * @return QueryEngine - QueryEngine object created + */ + public native QueryEngine CreateQueryEngine() throws Exception; - public native QueryEngine CreateQueryEngine() throws Exception; + /** + * @fn ReleaseQueryEngine + * @brief Release the QueryEngine object. + * + * @param [in] queryEngine - QueryEngine instance to be released + * + * @return int - success or failure result + */ + public native int ReleaseQueryEngine(QueryEngine queryEngine); - public native int ReleaseQueryEngine(QueryEngine queryEngine); + // QueryEngine + /** + * @fn ExecuteContextQuery + * @brief Execute the query with the QueryEngine and return ContextQuery ID + * for the query + * + * @param [in] pQueryEngineInstance - instance(created on creation of the QueryEngine) + * of the query engine with which the query is to be executed + * + * @param [in] contextQuery - query string to be executed + * + * @return int - ID of context query executed + */ + public native int ExecuteContextQuery(int pQueryEngineInstance, + String contextQuery) throws Exception; - // QueryEngine - public native int ExecuteContextQuery(int pQueryEngineInstance, - String contextQuery) throws Exception; + /** + * @fn RegisterQueryEvent + * @brief Register QueryEngineEvent to QueryEngine. + * + * @param [in] pQueryEngineInstance - instance(created on creation of the QueryEngine) + * of the query engine with which the query is to be registered + * + * @param [in] queryEngineEvent - the event to register with QueryEngine + * + * @return void + */ + public native void RegisterQueryEvent(int pQueryEngineInstance, + IQueryEngineEvent queryEngineEvent); - public native void RegisterQueryEvent(int pQueryEngineInstance, - IQueryEngineEvent queryEngineEvent); - public native void KillContextQuery(int pQueryEngineInstance, int cqid) - throws Exception; + /** + * @fn KillContextQuery + * @brief Kill the registered ContextQuery corresponding to the to cqid + * + * @param [in] pQueryEngineInstance - instance(created on creation of the QueryEngine) + * of the query engine with which the query is to be terminated + * + * @param [in] cqid - ContextQuery ID of the query to be terminated + * + * @return void + */ + public native void KillContextQuery(int pQueryEngineInstance, int cqid) + throws Exception; - // public native void UnregiterQueryEvent(int pQueryEngineInstance, - // IQueryEngineEvent queryEngineEvent); + // public native void UnregiterQueryEvent(int pQueryEngineInstance, + // IQueryEngineEvent queryEngineEvent); - // IModelData - public native int GetDataId(int pIModelDataInstance); + // IModelData + /** + * @fn GetDataId + * @brief Get the affected DataId - ContextModel has plenty of data so + * returned data is matched from given condition which in this case is the model + * data object instance + * + *@param [in] pIModelDataInstance - instance(created on creation of the ModelData) + * of the model data for which Data ID is to be returned + * + * @return int - the affected DataId + */ + public native int GetDataId(int pIModelDataInstance); - public native int GetPropertyCount(int pIModelDataInstance); + /** + * @fn GetPropertyCount + * @brief ContextModel has at least one property that contains data \n + * property is described from its specification. + * + *@param [in] pIModelDataInstance - instance(created on creation of the ModelData) + * of the model data for which propertycount is to be returned + * + * @return int + */ + public native int GetPropertyCount(int pIModelDataInstance); - public native String GetPropertyName(int pIModelDataInstance, - int propertyIndex); + /** + * @fn GetPropertyName + * @brief Retrieve the name of the property using the given index + * + * @param [in] pIModelDataInstance - instance(created on creation of the ModelData) + * of the model data for which property name is to be returned + * + * @param [in] propertyIndex - index of property to read + * + * @return String - property name + */ + public native String GetPropertyName(int pIModelDataInstance, + int propertyIndex); - public native String GetPropertyValue(int pIModelDataInstance, - int propertyIndex); + /** + * @fn GetPropertyValue + * @brief Retrieve the value of the property using the given index + * + * @param [in] pIModelDataInstance - instance(created on creation of the ModelData) + * of the model data for which property value is to be returned + * + * @param [in] propertyIndex - index of property to read + * + * @return String - property value + */ + public native String GetPropertyValue(int pIModelDataInstance, + int propertyIndex); - // IDataReader - public native List GetAffectedModels(int pDataReaderInstance); + // IDataReader + /** + * @fn GetAffectedModels + * @brief Get affected context models. The CQL(context query language) can specify + * multiple ContextModels for retrieving data so a list of string of affected + * dacontext models is returned + * + * @param [in] pDataReaderInstance - instance(created on creation of the DataReader) + * of the data reader class object + * + * @return List - affected ContextModel list + */ + public native List GetAffectedModels(int pDataReaderInstance); - public native int GetModelDataCount(int pDataReaderInstance, - String modelName) throws Exception; + /** + * @fn GetModelDataCount + * @brief Get affected model data count. There can be multiple data models existing + * from the given condition, return the count. + * + * @param [in] pDataReaderInstance - instance(created on creation of the DataReader) + * of the data reader class object + * + * @param [in] modelName - affected ContextModel name + * + * @return int - affected dataId count + */ + public native int GetModelDataCount(int pDataReaderInstance, + String modelName) throws Exception; - public native ModelData GetModelData(int pDataReaderInstance, - String modelName, int dataIndex) throws Exception; + /** + * @fn GetModelData + * @brief Get actual Context Model data + * + * @param [in] pDataReaderInstance - instance(created on creation of the DataReader) + * of the data reader class object + * + * @param [in] modelName - affected ContextModel name + * + * @param [in] dataIndex - affected dataId index + * + * @return ModelData - affected ContextModel data reader + */ + public native ModelData GetModelData(int pDataReaderInstance, + String modelName, int dataIndex) throws Exception; - public native void RegisterReportReceiver(IReportReceiver reportReceiver); + /** + * @fn RegisterReportReceiver + * @brief To register the report receiver to receive messages + * + * @param [in] reportReceiver - report receiver instance + * + * @return void + */ + public native void RegisterReportReceiver(IReportReceiver reportReceiver); } \ No newline at end of file diff --git a/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/DataReader.java b/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/DataReader.java index 5d552b2..5e83566 100644 --- a/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/DataReader.java +++ b/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/DataReader.java @@ -1,28 +1,93 @@ +/****************************************************************** + * + * Copyright 2015 Samsung Electronics All Rights Reserved. + * + * + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ******************************************************************/ +/** + * @file DataReader.java + * + * @brief This file provides a class that represents context model data package's reader + * + */ + package org.iotivity.service.ssm; import java.util.List; -public class DataReader { +/** +* @class DataReader +* @brief This class represents context model data package's reader and contains +* API's to be used by IQueryEngineEvent listeners to handle the model data. +* +*/ +public class DataReader +{ - private int pDataReaderInstance; + private int pDataReaderInstance; - public DataReader(int dataReaderInstance) { - pDataReaderInstance = dataReaderInstance; - } + public DataReader(int dataReaderInstance) + { + pDataReaderInstance = dataReaderInstance; + } - public List GetAffectedModels() { - return CoreController.getInstance().GetAffectedModels( - pDataReaderInstance); - } + /** + * @fn GetAffectedModels + * @brief Get affected context models. The CQL(context query language) can specify + * multiple ContextModels for retrieving data, so a list of strings of affected + * context models is returned. + * + * @return List - affected ContextModel list + */ + public List GetAffectedModels() + { + return CoreController.getInstance().GetAffectedModels( + pDataReaderInstance); + } - public int GetModelDataCount(String modelName) throws Exception { - return CoreController.getInstance().GetModelDataCount( - pDataReaderInstance, modelName); - } + /** + * @fn GetModelDataCount + * @brief Get affected model data count. There can be multiple data models existing + * from the given condition, return the count matching the condition. + * + * @param [in] modelName - affected ContextModel name + * + * @return int - affected dataId count + */ + public int GetModelDataCount(String modelName) throws Exception + { + return CoreController.getInstance().GetModelDataCount( + pDataReaderInstance, modelName); + } - public ModelData GetModelData(String modelName, int dataIndex) - throws Exception { - return CoreController.getInstance().GetModelData(pDataReaderInstance, - modelName, dataIndex); - } + /** + * @fn GetModelData + * @brief Get actual Context Model data + * + * @param [in] modelName - affected ContextModel name + * + * + * @param [in] dataIndex - affected dataId index + * + * @return ModelData - affected ContextModel data reader + */ + public ModelData GetModelData(String modelName, int dataIndex) + throws Exception + { + return CoreController.getInstance().GetModelData(pDataReaderInstance, + modelName, dataIndex); + } } diff --git a/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/IQueryEngineEvent.java b/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/IQueryEngineEvent.java index 1f3c601..92eb67f 100644 --- a/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/IQueryEngineEvent.java +++ b/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/IQueryEngineEvent.java @@ -1,5 +1,83 @@ +/****************************************************************** + * + * Copyright 2015 Samsung Electronics All Rights Reserved. + * + * + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ******************************************************************/ +/** + * @file IQueryEngineEvent.java + * + * @brief This file provides a class that represents Query Engine's event that contains results + * + */ package org.iotivity.service.ssm; -public abstract class IQueryEngineEvent { - public abstract void OnQueryEngineEvent(int cqid, DataReader result); +/** + * @class IQueryEngineEvent + * @brief This is an interface class for sample applications.It handles the response from + * SSMCore received asynchronously on making a query with the SSMCore. + * Application should implement the pure virtual function OnQueryEngineEvent. + * The Application should call registerQuery() and add a listener. + * + * + *
+    *Sample code :
+
+        int cqid = SoftSensorManager.registerQuery(edtQuery.getText().toString(), mQueryEngineEventListener);
+        mRunningQueries.add(cqid);
+
+        private IQueryEngineEvent mQueryEngineEventListener = new IQueryEngineEvent()
+        {
+        @Override
+        public void OnQueryEngineEvent(int cqid, DataReader result)
+        {
+                List models = result.GetAffectedModels();
+
+                for(String modelName : models)
+                {
+                    int dataCount = result.GetModelDataCount(modelName);
+                    for(int i=0; i < dataCount; i++)
+                    {
+                        ModelData modelData = result.GetModelData(modelName, i);
+                        for(int j=0; j < modelData.GetPropertyCount(); j++)
+                        {
+                            PrintLog("Name: " + modelData.GetPropertyName(j) +
+                                " Value: " + modelData.GetPropertyValue(j));
+                        }
+                    }
+                }
+        }
+        };
+
+ */ +public abstract class IQueryEngineEvent +{ + + /** + * @fn OnQueryEngineEvent + * @brief Transmits result of SSMCore to Application layer + * This abstract method needs to be implemeted by application + * as a precondition for query engine implementation. + * + * @param [in] cqid - ContextQuery ID of the registered query + * + * @param [in] result - data received from SSMCore + * + * @return void + * + */ + public abstract void OnQueryEngineEvent(int cqid, DataReader result); } \ No newline at end of file diff --git a/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/IReportReceiver.java b/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/IReportReceiver.java index 9fc66c8..a2c88da 100644 --- a/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/IReportReceiver.java +++ b/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/IReportReceiver.java @@ -1,5 +1,53 @@ +/****************************************************************** + * + * Copyright 2015 Samsung Electronics All Rights Reserved. + * + * + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ******************************************************************/ +/** + * @file IReportReceiver.java + * + * @brief This file provides a class for a set of APIs to handle response on receiving + * message + * + */ + package org.iotivity.service.ssm; -public abstract class IReportReceiver { - public abstract void OnMessageReceived(String tag, String msg); +/** + * @class IReportReceiver + * @brief This class provides an API to handle the report Message. + * The application should implement the pure virtual function OnMessageReceived. + * + */ +public abstract class IReportReceiver +{ + + /** + * @fn OnMessageReceived + * @brief Handle response on receiving message + * This abstract method needs to be implemeted by application + * as a precondition for query engine implementation. + * + * @param [in] tag + * + * @param [in] msg - received message + * + * + * @return void + */ + public abstract void OnMessageReceived(String tag, String msg); } \ No newline at end of file diff --git a/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/ModelData.java b/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/ModelData.java index 885d797..e7ae3f9 100644 --- a/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/ModelData.java +++ b/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/ModelData.java @@ -1,29 +1,99 @@ +/****************************************************************** + * + * Copyright 2015 Samsung Electronics All Rights Reserved. + * + * + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ******************************************************************/ +/** + * @file ModelData.java + * + * @brief This file provides a class for Model data operations + * message + * + */ + package org.iotivity.service.ssm; -public class ModelData { +/** + * @class ModelData + * @brief This class provides a set of API for DataReader class to handle the data + * received by IQueryEngineEvent listeners from SSMCore + * + */ +public class ModelData +{ - private int pIModelDataInstance; + private int pIModelDataInstance; - public ModelData(int iModelDataInstance) { - pIModelDataInstance = iModelDataInstance; - } + public ModelData(int iModelDataInstance) + { + pIModelDataInstance = iModelDataInstance; + } - public int GetDataId() { - return CoreController.getInstance().GetDataId(pIModelDataInstance); - } + /** + * @fn GetDataId + * @brief Get the affected DataId - ContextModel has plenty of data so the + * returned data is matched fom given condition and returned, + * which in this case is the model data object instance + * + * @return int - the affected DataId + */ + public int GetDataId() + { + return CoreController.getInstance().GetDataId(pIModelDataInstance); + } - public int GetPropertyCount() { - return CoreController.getInstance().GetPropertyCount( - pIModelDataInstance); - } + /** + * @fn GetPropertyCount + * @brief ContextModel has at least one property that contains data \n + * the property is described from its specification. + * + * @return int -the property count + */ + public int GetPropertyCount() + { + return CoreController.getInstance().GetPropertyCount( + pIModelDataInstance); + } - public String GetPropertyName(int propertyIndex) { - return CoreController.getInstance().GetPropertyName( - pIModelDataInstance, propertyIndex); - } + /** + * @fn GetPropertyName + * @brief Retrieve the name of the property using the given index value + * + * @param [in] propertyIndex - index of property to read + * + * @return String - the property name + */ + public String GetPropertyName(int propertyIndex) + { + return CoreController.getInstance().GetPropertyName( + pIModelDataInstance, propertyIndex); + } - public String GetPropertyValue(int propertyIndex) { - return CoreController.getInstance().GetPropertyValue( - pIModelDataInstance, propertyIndex); - } + /** + * @fn GetPropertyValue + * @brief Retrieve the value of the property using the given index value + * + * @param [in] propertyIndex - index of property to read + * + * @return String - the property value + */ + public String GetPropertyValue(int propertyIndex) + { + return CoreController.getInstance().GetPropertyValue( + pIModelDataInstance, propertyIndex); + } } \ No newline at end of file diff --git a/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/QueryEngine.java b/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/QueryEngine.java index 050f99d..71c1540 100644 --- a/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/QueryEngine.java +++ b/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/QueryEngine.java @@ -1,28 +1,101 @@ +/****************************************************************** + * + * Copyright 2015 Samsung Electronics All Rights Reserved. + * + * + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ******************************************************************/ +/** + * @file QueryEngine.java + * + * @brief This file provides a class that represents main interface of Query Engine + * + */ + package org.iotivity.service.ssm; -public class QueryEngine { - private int pQueryEngineInstance; +/** +* @class QueryEngine +* @brief This class represents main interface of Query Engine to interact with +* SSMCore with in turn interacts with the application. +* QueryEninge class forms the database from the base to respond to +* queries from SSMCore. +* +*/ +public class QueryEngine +{ + private int pQueryEngineInstance; - public QueryEngine(int queryEngineInstance) { - pQueryEngineInstance = queryEngineInstance; - } + public QueryEngine(int queryEngineInstance) + { + pQueryEngineInstance = queryEngineInstance; + } - public int GetQueryEngineInstance() { - return pQueryEngineInstance; - } + /** + * @fn GetQueryEngineInstance + * @brief Obtain the instance value of the called query engine object, + * this value is set on creation of the QueryEngine object + * + * @return int - Instance of the query engine object, set on object's creation + */ + public int GetQueryEngineInstance() + { + return pQueryEngineInstance; + } - public int ExecuteContextQuery(String contextQuery) throws Exception { - return CoreController.getInstance().ExecuteContextQuery( - pQueryEngineInstance, contextQuery); - } + /** + * @fn ExecuteContextQuery + * @brief Execute the query with the QueryEngine and return the generated ContextQuery ID + * for the query string. + * + * @param [in] contextQuery - query string to execute + * + * @return int - generated ID for the ContextQuery string + */ + public int ExecuteContextQuery(String contextQuery) throws Exception + { + return CoreController.getInstance().ExecuteContextQuery( + pQueryEngineInstance, contextQuery); + } - public void RegisterQueryEvent(IQueryEngineEvent queryEngineEvent) { - CoreController.getInstance().RegisterQueryEvent(pQueryEngineInstance, - queryEngineEvent); - } + /** + * @fn RegisterQueryEvent + * @brief Register QueryEngineEvent to the QueryEngine. + * + * @param [in] queryEngineEvent - the event to register with QueryEngine + * + * @return void + */ + public void RegisterQueryEvent(IQueryEngineEvent queryEngineEvent) + { + CoreController.getInstance().RegisterQueryEvent(pQueryEngineInstance, + queryEngineEvent); + } - public void KillContextQuery(int cqid) throws Exception { - CoreController.getInstance().KillContextQuery(pQueryEngineInstance, - cqid); - } + /** + * @fn KillContextQuery + * @brief Kill the registered ContextQuery corresponding to the to cqid + * + * @param [in] cqid - ContextQuery ID of the query to be terminated. + * This ID was generated on execution of the query + * + * @return void + */ + public void KillContextQuery(int cqid) throws Exception + { + CoreController.getInstance().KillContextQuery(pQueryEngineInstance, + cqid); + } } \ No newline at end of file diff --git a/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/SSMInterface.java b/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/SSMInterface.java index 904febc..7370ec2 100644 --- a/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/SSMInterface.java +++ b/service/soft-sensor-manager/SDK/java/org/iotivity/service/ssm/SSMInterface.java @@ -1,3 +1,32 @@ +/****************************************************************** + * + * Copyright 2015 Samsung Electronics All Rights Reserved. + * + * + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + ******************************************************************/ +/** + * @file SSMInterface.java + * + * @brief This file gives description of SSMInterface class and its utility functions. + * This is the interface between an application and the query engine. + * SSMinterface makes desired querries in form of CQL(Context Query Language) + * to the query engine and passes the returned result obtained in form of callback + * back to the application. + */ + package org.iotivity.service.ssm; import java.util.ArrayList; @@ -7,91 +36,205 @@ import java.util.Map; import java.util.concurrent.locks.Lock; import java.util.concurrent.locks.ReentrantLock; -public class SSMInterface { - private class QueryEngineEventReceiver extends IQueryEngineEvent { - private Lock mMtxListener = new ReentrantLock(); - private Map mMapListener = new HashMap(); - - public void OnQueryEngineEvent(int cqid, DataReader result) { - mMtxListener.lock(); - - mMapListener.get(cqid).OnQueryEngineEvent(cqid, result); - - mMtxListener.unlock(); - } - - void lockListener() { - mMtxListener.lock(); - } - - void unlockListener() { - mMtxListener.unlock(); - } - - void addListener(int cqid, IQueryEngineEvent engineEvent) { - mMapListener.put(cqid, engineEvent); - } - - void removeListener(int cqid) { - mMapListener.remove(cqid); - } - }; - - private CoreController mSSMCore = null; - private QueryEngine mQueryEngine = null; - private QueryEngineEventReceiver mQueryEngineEventListenerReceiver = new QueryEngineEventReceiver(); - private List mRunningCQLs = new ArrayList(); - - public SSMInterface() { - } - - public void startSSMCore(String initConfig) throws Exception { - mSSMCore = CoreController.getInstance(); - mSSMCore.InitializeSSMCore(initConfig); - mSSMCore.StartSSMCore(); - - mQueryEngine = mSSMCore.CreateQueryEngine(); - - mQueryEngine.RegisterQueryEvent(mQueryEngineEventListenerReceiver); - } - - public void stopSSMCore() throws Exception { - mQueryEngine.RegisterQueryEvent(null); - mSSMCore.ReleaseQueryEngine(mQueryEngine); - mQueryEngineEventListenerReceiver = null; - mQueryEngine = null; - mSSMCore.StopSSMCore(); - mSSMCore.TerminateSSMCore(); - } - - public int registerQuery(String contextQuery, IQueryEngineEvent listener) - throws Exception { - int cqid = 0; - - try { - mQueryEngineEventListenerReceiver.lockListener(); - cqid = mQueryEngine.ExecuteContextQuery(contextQuery); - mQueryEngineEventListenerReceiver.addListener(cqid, listener); - mRunningCQLs.add(cqid); - } catch (Exception e) { - throw e; - } finally { - mQueryEngineEventListenerReceiver.unlockListener(); - } - - return cqid; - } - - public void unregisterQuery(int cqid) throws Exception { - try { - mQueryEngineEventListenerReceiver.lockListener(); - mQueryEngine.KillContextQuery(cqid); - mQueryEngineEventListenerReceiver.removeListener(cqid); - mRunningCQLs.remove((Object) cqid); - } catch (Exception e) { - throw e; - } finally { - mQueryEngineEventListenerReceiver.unlockListener(); - } - } +/** + * @class SSMInterface + * @brief This class provides a set of APIs to manage the SSM framework + * This class sits in between the application and query engine and acts + * as an interface between them. SSMinterface makes desired querries in form of CQL(Context Query Language) + * to the query engine and passes the returned result obtained in form of callback + * back to the application + */ +public class SSMInterface +{ + + /** + * @class QueryEngineEventReceiver + * @brief This class provides a set of APIs to handle query engine events + * related to soft sensor Interface framework. + * + * + */ + private class QueryEngineEventReceiver extends IQueryEngineEvent + { + private Lock mMtxListener = new ReentrantLock(); + private Map mMapListener = new HashMap(); + + /** + * @fn OnQueryEngineEvent + * @brief Transmits result of SSMCore to Application layer + * + * @param [in] cqid - ContextQuery ID of the registered query + * + * @param [in] result - data received from SSMCore + * + * @return void + */ + public void OnQueryEngineEvent(int cqid, DataReader result) + { + mMtxListener.lock(); + + mMapListener.get(cqid).OnQueryEngineEvent(cqid, result); + + mMtxListener.unlock(); + } + + /** + * @fn lockListener + * @brief To lock QueryEngineEventReceiver object to execute a query atomicaly, + * this is done to provide synchronization in case of multiple queries. + * + * @return void + */ + void lockListener() + { + mMtxListener.lock(); + } + + /** + * @fn unlockListener + * @brief release the QueryEngineEventReceiver object + * + * @return void + */ + void unlockListener() + { + mMtxListener.unlock(); + } + + /** + * @fn addListener + * @brief add listener to receive response for the registered query with SSMCore. + * Listen for callbacks from SSMCore. + * This is also a precondition for implementing query engine object. + * + * @param [in] cqid - ContextQuery ID of the registered query + * + * @param [in] engineEvent - query engine's event that contains the results + * + * @return void + */ + void addListener(int cqid, IQueryEngineEvent engineEvent) + { + mMapListener.put(cqid, engineEvent); + } + + /** + * @fn removeListener + * @brief Remove listener for a query on unregistering it + * + * @param [in] cqid - ContextQuery ID of the registered query + * + * @return void + */ + void removeListener(int cqid) + { + mMapListener.remove(cqid); + } + }; + + private CoreController mSSMCore = null; + private QueryEngine mQueryEngine = null; + private QueryEngineEventReceiver mQueryEngineEventListenerReceiver = new QueryEngineEventReceiver(); + private List mRunningCQLs = new ArrayList(); + + public SSMInterface() + { + } + + /** + * @fn startSSMCore + * @brief Starts the framework that allows other devices to discover and communicate + * with the SSMCore and underlying query engine. + * + * @param [in] initConfig - initial framework specifications + * + * @return void + */ + public void startSSMCore(String initConfig) throws Exception + { + mSSMCore = CoreController.getInstance(); + mSSMCore.InitializeSSMCore(initConfig); + mSSMCore.StartSSMCore(); + + mQueryEngine = mSSMCore.CreateQueryEngine(); + + mQueryEngine.RegisterQueryEvent(mQueryEngineEventListenerReceiver); + } + + /** + * @fn stopSSMCore + * @brief Stops the framework and terminate all communications. + * + * @return void + */ + public void stopSSMCore() throws Exception + { + mQueryEngine.RegisterQueryEvent(null); + mSSMCore.ReleaseQueryEngine(mQueryEngine); + mQueryEngineEventListenerReceiver = null; + mQueryEngine = null; + mSSMCore.StopSSMCore(); + mSSMCore.TerminateSSMCore(); + } + + /** + * @fn registerQuery + * @brief Register the query and execute statement with the query engine + * and add listener for the registered query so as to get response data. + * After success response message for registration, SSMCore sends an + * event to the client, if the specified condtions in the query is satisfied. + * + * @param [in] contextQuery - query for requesting data + * + * @param [in] listener - listener for receiving response data of the query + * + * @return int - ContextQuery ID + */ + public int registerQuery(String contextQuery, IQueryEngineEvent listener) + throws Exception + { + int cqid = 0; + + try { + mQueryEngineEventListenerReceiver.lockListener(); + cqid = mQueryEngine.ExecuteContextQuery(contextQuery); + mQueryEngineEventListenerReceiver.addListener(cqid, listener); + mRunningCQLs.add(cqid); + } + catch (Exception e) + { + throw e; + } finally { + mQueryEngineEventListenerReceiver.unlockListener(); + } + + return cqid; + } + + /** + * @fn unregisterQuery + * @brief unregister a registered query using its query ID the query corresponding + * to the cqid will be terminated and removes listener for the given query + * The SSMCore will not send any callbacks after successful unregistration. + * + * + * @param [in] cqid - ContextQuery ID of the query to be unregistered + * + * @return void + */ + public void unregisterQuery(int cqid) throws Exception + { + try { + mQueryEngineEventListenerReceiver.lockListener(); + mQueryEngine.KillContextQuery(cqid); + mQueryEngineEventListenerReceiver.removeListener(cqid); + mRunningCQLs.remove((Object) cqid); + } + catch (Exception e) + { + throw e; + } finally { + mQueryEngineEventListenerReceiver.unlockListener(); + } + } } \ No newline at end of file -- 2.7.4