Service Layer API

HTTP Service

HTTP service facilitates the execution of network requests of varying types. User can execute HTTP requests of type GET, POST, PUT, DELETE. Additionally, this service also provides the facility to save the response of network request in a file specified by the user.

HTTP request without Save Data

Executes the network HTTP request according to the details provided by the user and returns the response from the server converted in the JSON form to the web layer. Also, the response sent to the web layer provides the response headers along with the server response.

Request Parameters:

Helper Method:

appit.mmi.executeHttpRequest(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)

Response Format:

{‘httpResponseHeaders’:[<JSON array containing list of headers received in response>], ‘httpResponse’ : ‘<HTTP response>’}

Example:

Refer to the following snippet for executing HTTP request in your application.

Request:

var HTTP_REQUEST = {

'requestMethod':'GET',

'requestUrl': 'http://ip-api.com/json',

'requestContentType':'application/json'

};

appit.mmi.executeHttpRequest(HTTP_REQUEST,scope.onClickHttpReqCallback,scope);

Response:

{"httpResponseHeaders":[{"headerName":"Content-Type","headerValue":"application/json; charset=utf-8"},{"headerName":"Access-Control-Allow-Origin","headerValue":"*"},{"headerName":"Transfer-Encoding","headerValue":"chunked"},{"headerName":"Date","headerValue":"Mon, 02 Jun 2014 10:56:58 GMT"},{"headerName":"Server","headerValue":"secure"}],"httpResponse":"{"status":"success","country":"India","countryCode":"IN","region":"","regionName":"","city":"","zip":"","lat":"20","lon":"77","timezone":"Asia\\/Kolkata","isp":"Bharti Broadband","org":"BHARTI Airtel","as":"AS45609 Bharti Airtel Ltd. AS for GPRS Service","query":"171.61.33.157"}"}

HTTP request with Save Data

Performs the same operation as the HTTP request without save data, except the fact that it saves the response in a file whose name is specified by the user and returns the absolute location of the file to the web layer rather than the server response. Although, this operation returns the file location where the response was written, it still sends the response headers along with the response.

Request Parameters:

Helper Method:

appit.mmi.executeHttpRequest(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)

Response Format:

{‘httpResponseHeaders’:[<JSON array containing list of headers received in response>], ‘httpResponse’ : ‘<HTTP response>’}

Example:

Refer to the following snippet for executing HTTP request and save its data in a dump file in your application.

Request:

var HTTP_REQUEST_SAVE_DATA = {

'requestMethod':'GET',

'requestUrl':'http://ip-api.com/json',

'requestContentType':'application/json',

'requestFileNameToSave': 'testFile'

};

appit.mmi.executeHttpRequestWithSaveData(HTTP_REQUEST_SAVE_DATA,scope.onClickHttpReqWithSaveDataCallback,scope);

Response:

{"httpResponseHeaders":[{"headerName":"Content-Type","headerValue":"application/json; charset=utf-8"},{"headerName":"Access-Control-Allow-Origin","headerValue":"*"},{"headerName":"Transfer-Encoding","headerValue":"chunked"},{"headerName":"Date","headerValue":"Mon, 02 Jun 2014 10:57:16 GMT"},{"headerName":"Server","headerValue":"secure"}],"httpResponse":"/storage/emulated/0/Android/data/com.appit.appit_revamp/files/testFile"}

Persistence Service

The purpose of this service is to provide the user with an option to save the data in the persistence store of the application. This data will be preserved across sessions of the application. This means if the user closes/ quits/ force quits the application and then reopens the application, then the same set of data is maintained in the application memory. However, if the user deliberately clears the application data or uninstalls the application, then the data would get lost. This service provides operations to save, retrieve or delete data in key-value format in the store
.

NOTE: Make sure that you do not save very large amount of data in the persistence store as it might lead to performance degradation of the application while retrieving data. This medium of information preservation is meant for storing small amount of data that can be operated upon easily and quickly. For storing large amounts of data, using Database service is the suggested approach.

Save Data in Persistence Store

This operation is used to save the information in the form of key-value pair in the persistence store of the application.

Request Parameters:

Helper Method:

appit.mmi.saveData(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)

Response Format:

{‘storeName’:‘<Name of persistence store>’,’storeReturnData’:[]}

Here, parameter ‘storeReturnData’ will be blank JSON array for SAVE operation.

Example:

Refer to the following snippet for saving data in persistence store in your application.

Request:

var PERSIST_SAVE_REQ = {

'storeName':'appit_persist_store',

'requestData':[

{

'key':'key 1',

'value':'value 1'

},

{

'key':'key 2',

'value':'value 2'

}

]

};

appit.mmi.saveData(PERSIST_SAVE_REQ,scope.onClickPersistSaveDataCallback,scope);

Response:

{"storeReturnData":"","storeName":"appit_persist_store"}

Retrieve Data from Persistence Store

This operation is meant to retrieve all the information stored in the persistence store of the application or even selective retrieval of the information.

Request Parameters:

Helper Method:

appit.mmi.retrieveData(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)

Response Format:

{‘storeName’:‘<Name of persistence store>’,’storeReturnData’:[<JSON array containing the records read from the store>]}

Here, parameter ‘storeReturnData’ would contain a value in this case of READ operation from the Persistence service. This will be JSON array containing the key-value pairs read from the store.

Example:

Refer to the following snippet for retrieving data from persistence store in your application.

Request:

var PERSIST_RETRIEVE_REQ = {

'storeName':'appit_persist_store',

'requestData':[

{

'key':'key 1'

},

{

'key':'key 2'

}

]

};

appit.mmi.retrieveData(PERSIST_RETRIEVE_REQ,scope.onClickPersistRetrieveDataCallback,scope);

Response:

{"storeReturnData":[{"value":"value 2","key":"data 2"}],"storeName":"appit_persist_store"}

Delete Data from Persistence Store

To delete the information stored in the persistence store of the application, this operation is used. User needs to provide the key(s) to be deleted from the store.

Request Parameters:

Helper Method:

appit.mmi.deleteData(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)

Response Format:

{‘storeName’:‘<Name of persistence store>’,’storeReturnData’:[]}

Here, parameter ‘storeReturnData’ will be blank JSON array for DELETE operation.

Example:

Refer to the following snippet for retrieving data from persistence store in your application.

Request:

var PERSIST_DELETE_REQ = {

'storeName':'appit_persist_store',

'requestData':[

{

'key':'key 1'

}

]

};

appit.mmi.deleteData(PERSIST_DELETE_REQ,scope.onClickPersistDeleteDataCallback,scope);

Response:

{"storeReturnData":"","storeName":"appit_persist_store"}

Device Database Service

For storing the application information in a more structured format, Device Database service can be used. This service makes use of the SQLite databases which are supported by all the major platforms such as Android, iOS and Windows Phone. This service thus supports CRUD operations as well complex queries as supported by SQLite standard. Using this service user can maintain relational databases in their application in a secure manner.

Open Database

This operation opens the connection to the specified database whose name is provided by the user.

Request Parameters:

Helper Method:

appit.mmi.openDatabase(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)

Response Format:

{‘appDB’:’<Name of the DB being accessed>’ }

Example:

Refer to the following snippet for opening database in your application.

Request:

var DB_OPEN_REQ = {

'appDB':'appit_db',

'shouldEncrypt':false

};

appit.mmi.openDatabase(DB_OPEN_REQ,scope.onClickDbOpenCallback,scope);

Response:

{"appDB":"appit_db"}

Execute Database Query

This operation is responsible for executing SQLite queries as they are provided by the user.

Request Parameters:

Helper Method:

appit.mmi.executeDbQuery(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)

Response Format:

{‘appDB’:’<Name of the DB being accessed>’ }

Example:

Refer to the following snippet for executing query in your application.

Request:

Here the developer has the liberty to execute all the SQL queries. But for the sake of example, we are considering an INSERT query

var DB_INSERT_RECORD_REQ = {

'appDB':'appit_db',

'queryRequest':'insert into category(name,description) values("Sample Key","Sample Value");'

};

appit.mmi.executeDbQuery(DB_INSERT_RECORD_REQ,scope.onClickDbInsertRecordCallback,scope);

Response:

{"appDB":"appit_db"}

Execute Database Read Query

This operation is meant for executing read table related queries on application database tables. This operation returns the rows of table elements that match according to the query.

NOTE: Make sure that you run your read database queries i.e. SELECT queries using this operation only otherwise you will not get any table rows in the callback function.

Request Parameters:

Helper Method:

appit.mmi.executeReadDbQuery(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)

Response Format:

{‘appDB’:’<Name of the DB being accessed>’, ’dbRecords’:[<JSON array containing the results of the read query> }

Example:

Refer to the following snippet for executing query in your application.

Request:

var DB_READ_RECORD_REQ = {

'appDB':'appit_db',

'queryRequest' : 'select * from category'

};

appit.mmi.executeReadDbQuery(DB_READ_RECORD_REQ,scope.onClickDbReadRecordCallback,scope);

Response:

{"appDB":"appit_Revamp_db","dbRecords":[{"id":"1","description":"value 1","name":"key 1"},{"id":"2","description":"value 2","name":"key 2"}]}

Close Database

Close the opened connection of the specified database.

Request Parameters:

Helper Method:

appit.mmi.closeDatabase(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)

Response Format:

{‘appDB’:’<Name of the DB being closed>’ }

Example:

Refer to the following snippet for closing database connection in your application.

Request:

var DB_CLOSE_REQ = {

'appDB':'appit_db'

};

appit.mmi.closeDatabase(DB_CLOSE_REQ,scope.onClickDbCloseCallback,scope);

Response:

{"appDB":"appit_db"}

Maps Service

Maps are an important part of any enterprise application and can be used for variety of purposes from user location tracking to depicting user’s Points of Interests (PoIs) etc. The map service in the appIt MMI layer tries to address this requirement of a typical enterprise application. Given the points that need to be plotted, the Map service shows the map to the user. Additionally the user has the option to get directions to a specific point from the current location of the user. This service makes use of platform specific map services i.e. Google Maps for Android and Apple Maps for iOS.

NOTE: When using Maps, do not forget to add the following entries in AndroidManifest.xml for Android projects

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES" />

<uses-permission android:name="<YOUR-APPLICATION-PACKAGE-NAME>.permission.MAPS_RECEIVE" />

<permission android:name="<YOUR-APPLICATION-PACKAGE>.permission.MAPS_RECEIVE"

android:protectionLevel="signature" />

<uses-feature

android:glEsVersion="0x00020000"

android:required="true" />

Also, add the following entries within the application node in AndroidManifest.xml.

<meta-data

android:name="com.google.android.maps.v2.API_KEY"

android:value="<YOUR-GOOGLE-MAPS-API-KEY-HERE>" />

<activity
android:name="com.emobilizer.utility.SmartDirectionActivity"
android:label="@string/app_name"
android:screenOrientation="portrait" >
</activity>
<activity
android:name="com.emobilizer.utility.SmartMapHandlerActivity"
android:label="@string/app_name"
android:screenOrientation="portrait" >
</activity>

Show Map

This operation takes the set of points to be shown on the map, from the user and plots them on the map. It also shows the user’s current location on the map.

Request Parameters:

Helper Method:

appit.mmi.showMap(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)

Response Format:

Here the service response would just be a blank JSON as the map operation completion has no completion arguments associated with it. In this case, the success of the operation will be determined by checking getOperationComplete().

Example:

Refer to the following snippet for showing map in your application.

Request:

var SHOW_MAP_REQ = {

'locations' : [

{

'locLatitude': '22.6160',

'locLongitude':'78.110',

'locMarkerPin': '#ff0000',

'locTitle':'Location 1',

'locDescription': 'Description 1'

},

{

'locLatitude': '22.6170',

'locLongitude':'78.120',

'locMarkerPin': '#00ff00',

'locTitle':'Location 2',

'locDescription': 'Description 2'

}

]

};

appit.mmi.showMap(SHOW_MAP_REQ,scope.onClickMapShowCallback,scope);

Response:

{"response":"OK"}

Show Map with Directions

This operation is similar to the Show Map operation except for the fact that it also provides the option to show the direction to a particular location from the user current location.

Request Parameters:

Helper Method:

appit.mmi.showMapWithDirections(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)

Here the service response would just be a blank JSON as the map operation completion has no completion arguments associated with it. In this case, the success of the operation will be determined by checking getOperationComplete().

Example:

Refer to the following snippet for showing map with directions in your application.

Request:

var SHOW_MAP_WITH_DIR_REQ = {

'locations' : [

{

'locLatitude': '22.6160',

'locLongitude':'78.110',

'locMarkerPin': '#ff0000',

'locTitle':'Location 1',

'locDescription': 'Description 1'

},

{

'locLatitude': '22.6170',

'locLongitude':'78.120',

'locMarkerPin': '#00ff00',

'locTitle':'Location 2',

'locDescription': 'Description 2'

}

]

};

appit.mmi.showMapWithDirections(SHOW_MAP_WITH_DIR_REQ,scope.onClickMapShowWithDirCallback,scope);

Response:

{"response":"OK"}

Show Map with Animations

This operation is specific to iOS devices only. Using map with animations, the map is shown with animation. Currently 2 animation types are supported Curl and Flip. On Android and Windows Phone, this operation will show map without any animation just like the Show Map operation.

Request Parameters:

Helper Method:

appit.mmi.showMapWithAnimation(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)

Response Format:

Here the service response would just be a blank JSON as the map operation completion has no completion arguments associated with it. In this case, the success of the operation will be determined by checking getOperationComplete().

Example:

Refer to the following snippet for showing map with animation in your application.

Request:

var SHOW_MAP_WITH_ANIM_REQ = {

'locations' : [

{

'locLatitude': '22.6160',

'locLongitude':'78.110',

'locMarkerPin': '#ff0000',

'locTitle':'Location 1',

'locDescription': 'Description 1'

},

{

'locLatitude': '22.6170',

'locLongitude':'78.120',

'locMarkerPin': '#00ff00',

'locTitle':'Location 2',

'locDescription': 'Description 2'

}

]

};

appit.mmi.showMapWithAnimation(SHOW_MAP_WITH_ANIM_REQ,scope.onClickMapShowWithAnimCallback,scope);

Response:

{"response":"OK"}