Storage service on cloud provides the way to store the JSON document in NoSQL database running on cloud. One can store the JSON document, update it , search it and can apply the map-reduce search on stored documents. Example : If one will store JSON doc {"employeeName":"Nick"} it will be stored with unique Object Id and stored JSON object will loook like { "employeeName" : "Nick" , "_id" : { "$oid" : "4f423dcce1603b3f0bd560cf"}}. This oid can further be used to access/search the document.
In order to use the various functions available under a particular API, a developer will have to create an instance of ServiceAPI by passing the apiKey and the secretKey which has been received while creating an app.
ServiceAPI api = new ServiceAPI("<API_KEY>","<SECRET_KEY>");
After initialization, developer needs to call the buildXXXService method on ServiceAPI instance to get the instance of the particular API that you wish to build. For example, To build an instance of StorageService, buildStorageService() method needs to be called.
StorageService storageService = api.buildStorageService();;
Once the API instance has been retrieved, You are ready to use the functions available for that particular API.
The methods available under a particular API will return the domain object (like Storage in this case) as a response which will have the accessor / mutator to access the available properties for that object. You can get the response in the form of JSON as well. We have provided the JSON response with every function detail which can be retrieved by calling the toString() on the returned object.
String dbName = "test";
String collectionName = "foo";
String json = "{\"employeeName \":\"Nick\"}";
Storage storage = storageService.insertJSONDocument(dbName,collectionName,json); /* returns the Storage object. */
System.out.println("dbName is " + storage.getDbName());
System.out.println("Collection Name is " + storage.getCollectionName());
ArrayList<Storage.JSONDocument>jsonDocList = storage.getJsonDocList();
for(Storage.JSONDocument jsonDoc : jsonDocList)
{
System.out.println("docId is " + jsonDoc.getDocId());
System.out.println("JsonDoc is " + jsonDoc.getJsonDoc());
}
String jsonResponse = storage.toString(); /* returns the response in JSON format. */
The functions available under Storage API can throw some exceptions in abnormal conditions. Example of the same has been given below.
E.g. If App developer is requesting for the document that does not exist, the function will throw the App42Exception (as shown below) with message as "Not Found" and the appErrorCode as "2600" and the details as "Document by the Id '<docId>' does not exist".
String dbName = "test";
String collectionName = "foo";
String docId = "4faa3f1ac68df147a51f8bd7";
try
{
Storage storage = storageService.findDocumentById(dbName, collectionName, docId);
}
catch(App42Exception ex)
{
int appErrorCode = ex.getAppErrorCode();
int httpErrorCode = ex.getHttpErrorCode();
if(appErrorCode == 2600)
{
// Handle here for Not Found (Document by the Id '<docId>' does not exist.)
}
else if(appErrorCode == 2606)
{
// Handle here for Bad Request (Document Id '<docId>' is not valid.)
}
else if(appErrorCode == 1401)
{
// handle here for Client is not authorized
}
else if(appErrorCode == 1500)
{
// handle here for Internal Server Error
}
String jsonText = ex.getMessage(); /* returns the Exception text in JSON format. (as shown below)*/
}
{
"app42Fault": {
"httpErrorCode": 404,
"appErrorCode": 2600,
"message": "Not Found",
"details": "Document by the Id '4faa3f1ac68df147a51f8bd7' does not Exist"
}
}
Below are the HTTP Error Codes and their description, the function under the Storage API can throw.
/* 1400 - BAD REQUEST - The Request parameters are invalid 1401 - UNAUTHORIZED - Client is not authorized 1500 - INTERNAL SERVER ERROR - Internal Server Error. Please try again */
Below are the Application Error Codes and their description, the function under the Storage API can throw.
/* 2600 - NOT FOUND - Document by the Id '<docId>' does not exist. 2601 - NOT FOUND - Document by key '<key>' and value '<value>' does not exist. 2602 - NOT FOUND - No document in the collection '<collectionName>' exists. 2603 - BAD REQUEST - The request parameters are invalid. Make Sure DB and collection name exists and functions are syntactically correct. 2604 - NOT FOUND - No storage exist with the name '<storageName>'. 2605 - BAD REQUEST - Passed JSON string '<newjsonDoc>' is not valid. 2606 - BAD REQUEST - Document Id '<docId>' is not valid. 2607 - NOT FOUND - The number of documents in the collection '<collectionName>' are less than the specified offset : <offset>. 2606 - BAD REQUEST - Document Id '<docId>' is not valid. */
Various functions available under Storage API has been explained below.
Save the JSON document in given database name and collection name.
Parameters:
Returns:
Response: Storage Object
Exception:
/* 2605 - BAD REQUEST - Passed JSON string '<newjsonDoc>' is not valid. */
String dbName = "test";
String collectionName = "foo";
String json = "{\"employeeName \":\"Nick\"}";
Storage storage = storageService.insertJSONDocument(dbName,collectionName,json); /* returns the Storage object. */
System.out.println("dbName is " + storage.getDbName());
System.out.println("Collection Name is " + storage.getCollectionName());
ArrayList<Storage.JSONDocument>jsonDocList = storage.getJsonDocList();
for(Storage.JSONDocument jsonDoc : jsonDocList)
{
System.out.println("docId is " + jsonDoc.getDocId());
System.out.println("JsonDoc is " + jsonDoc.getJsonDoc());
}
String jsonResponse = storage.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"storage": {
"dbName": "test",
"collectionName": "foo",
"jsonDoc": {
"employeeName": "Nick",
"_id": {
"$oid": "4faa3f1ac68df147a51f8bd7"
}
}
}
}
}
}
Find all documents stored in given database and collection.
Parameters:
Returns:
Response: Storage Object
Exception:
/* 2602 - NOT FOUND - No document in the collection '<collectionName>' exists. */
String dbName = "test";
String collectionName = "foo";
Storage storage = storageService.findAllDocuments(dbName,collectionName); /* returns the Storage object. */
System.out.println("dbName is " + storage.getDbName());
System.out.println("Collection Name is " + storage.getCollectionName());
ArrayList<Storage.JSONDocument>jsonDocList = storage.getJsonDocList();
for(Storage.JSONDocument jsonDoc : jsonDocList)
{
System.out.println("docId is " + jsonDoc.getDocId());
System.out.println("JsonDoc is " + jsonDoc.getJsonDoc());
}
String jsonResponse = storage.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"storage": {
"dbName": "test",
"collectionName": "foo",
"jsonDoc": [
{
"_id": {
"$oid": "50470db9c68d8e2fae75653e"
},
"employeeName": "Nick"
},
{
"_id": {
"$oid": "50470dccc68d8e2fae75653f"
},
"employeeName": "Nick"
},
{
"_id": {
"$oid": "50470e8fc68d8e2fae756540"
},
"employeeName": "Gill"
}
]
}
}
}
}
Find all documents stored in given database and collection.
Parameters:
Returns:
Response: App42Response Object
String dbName = "test"; String collectionName = "foo"; App42Response response = storage.findAllDocumentsCount(dbName,collectionName); /* returns the App42Response objects. */ boolean success = response.isResponseSuccess(); int totalRecords = response.getTotalRecords(); String jsonResponse = response.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"totalRecords": 96
}
}
}
Find all documents stored in given database and collection.
Parameters:
Returns:
Response: Storage Object
Exception:
/* 2607 - NOT FOUND - The number of documents in the collection '<collectionName>' are less than the specified offset : <offset>. */
String dbName = "test";
String collectionName = "foo";
int max = 1;
int offset = 0;
Storage storage = storageService.findAllDocuments(dbName,collectionName,max,offset); /* returns the Storage object. */
System.out.println("dbName is " + storage.getDbName());
System.out.println("Collection Name is " + storage.getCollectionName());
ArrayList<Storage.JSONDocument>jsonDocList = storage.getJsonDocList();
for(Storage.JSONDocument jsonDoc : jsonDocList)
{
System.out.println("docId is " + jsonDoc.getDocId());
System.out.println("JsonDoc is " + jsonDoc.getJsonDoc());
}
String jsonResponse = storage.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"storage": {
"dbName": "test",
"collectionName": "foo",
"jsonDoc": [
{
"_id": {
"$oid": "4faa3f1ac68df147a51f8bd7"
},
"employeeName": "Nick"
}
]
}
}
}
}
Find target document by given unique object id.
Parameters:
Returns:
Response: Storage Object
Exception:
/* 2600 - NOT FOUND - Document by the Id '<docId>' does not exist. 2606 - BAD REQUEST - Document Id '<docId>' is not valid. */
String dbName = "test";
String collectionName = "foo";
String docId = "4faa3f1ac68df147a51f8bd7";
Storage storage = storageService.findDocumentById(dbName,collectionName,docId); /* returns the Storage object. */
System.out.println("dbName is " + storage.getDbName());
System.out.println("Collection Name is " + storage.getCollectionName());
ArrayList<Storage.JSONDocument>jsonDocList = storage.getJsonDocList();
for(Storage.JSONDocument jsonDoc : jsonDocList)
{
System.out.println("docId is " + jsonDoc.getDocId());
System.out.println("JsonDoc is " + jsonDoc.getJsonDoc());
}
String jsonResponse = storage.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"storage": {
"dbName": "test",
"collectionName": "foo",
"jsonDoc": {
"_id": {
"$oid": "50471017c68d8e2fae756545"
},
"employeeName": "Nick"
}
}
}
}
}
Find target document using key value search parameter. This key value pair will be searched in the JSON doc stored on the cloud and matching Doc will be returned as a result of this method.
Parameters:
Returns:
Response: Storage Object
Exception:
/* 2601 - NOT FOUND - Document by key '<key>' and value '<value>' does not exist. */
String dbName = "test";
String collectionName = "foo";
String key = "employeeName";
String value = "Nick";
Storage storage = storageService.findDocumentByKeyValue(dbName,collectionName,key,value); /* returns the Storage object. */
System.out.println("dbName is " + storage.getDbName());
System.out.println("Collection Name is " + storage.getCollectionName());
ArrayList<Storage.JSONDocument>jsonDocList = storage.getJsonDocList();
for(Storage.JSONDocument jsonDoc : jsonDocList)
{
System.out.println("docId is " + jsonDoc.getDocId());
System.out.println("JsonDoc is " + jsonDoc.getJsonDoc());
}
String jsonResponse = storage.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"storage": {
"dbName": "test",
"collectionName": "foo",
"jsonDoc": {
"employeeName": "Nick",
"_id": {
"$oid": "50470f5fc68d8e2fae756544"
}
}
}
}
}
}
Find target document using Single Query and operator.
Parameters:
Returns:
Response: Storage Object
Exception:
/* 2605 - BAD REQUEST - Invalid Storage Query. 2608 - NOT FOUND - No document in the collection '<collectionName>' exists for given query. */
String dbName = "test";
String collectionName = "foo";
Query q1 = QueryBuilder.build("NickScore", 300, Operator.LESS_THAN_EQUALTO);
Storage storage = storageService.findDocumentsByQuery(dbName,collectionName,q1); /* returns the Storage object. */
System.out.println("dbName is " + storage.getDbName());
System.out.println("Collection Name is " + storage.getCollectionName());
ArrayList<Storage.JSONDocument>jsonDocList = storage.getJsonDocList();
for(Storage.JSONDocument jsonDoc : jsonDocList)
{
System.out.println("docId is " + jsonDoc.getDocId());
System.out.println("JsonDoc is " + jsonDoc.getJsonDoc());
}
String jsonResponse = storage.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"storage": {
"dbName": "test",
"collectionName": "foo",
"jsonDoc": [
{
"_id": {
"$oid": "507bq526c68d198fe882d0d4"
},
"name": "shephertz",
"NickScore": 300
}
]
}
}
}
}
Find target document using Custom Query .
Parameters:
Returns:
Response: Storage Object
Exception:
/* 2605 - BAD REQUEST - Invalid Storage Query. 2608 - NOT FOUND - No document in the collection '<collectionName>' exists for given query. */
String dbName = "test";
String collectionName = "foo";
Query q1 = QueryBuilder.build("NickScore", 300, Operator.LESS_THAN_EQUALTO);
Query q2 = QueryBuilder.build("name", "shephertz", Operator.LIKE);
Query q3 = QueryBuilder.compoundOperator(q1, Operator.AND, q2);
Storage storage = storageService.findDocumentsByQuery(dbName,collectionName,q3); /* returns the Storage object. */
System.out.println("dbName is " + storage.getDbName());
System.out.println("Collection Name is " + storage.getCollectionName());
ArrayList<Storage.JSONDocument>jsonDocList = storage.getJsonDocList();
for(Storage.JSONDocument jsonDoc : jsonDocList)
{
System.out.println("docId is " + jsonDoc.getDocId());
System.out.println("JsonDoc is " + jsonDoc.getJsonDoc());
}
String jsonResponse = storage.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"storage": {
"dbName": "test",
"collectionName": "foo",
"jsonDoc": [
{
"_id": {
"$oid": "507bq526c68d198fe882d0d4"
},
"name": "shephertz",
"NickScore": 300
}
]
}
}
}
}
Find target document using Custom Query.
Parameters:
Returns:
Response: Storage Object
Exception:
/* 2605 - BAD REQUEST - Invalid Storage Query. 2608 - NOT FOUND - No document in the collection '<collectionName>' exists for given query. */
String dbName = "test";
String collectionName = "foo";
Query q1 = QueryBuilder.build("NickScore", 300, Operator.LESS_THAN_EQUALTO);
Query q2 = QueryBuilder.build("name", "", Operator.LIKE);
Query q3 = QueryBuilder.compoundOperator(q1, Operator.AND, q2);
Storage storage = storageService.findDocumentsByQuery(dbName,collectionName,q3); /* returns the Storage object. */
System.out.println("dbName is " + storage.getDbName());
System.out.println("Collection Name is " + storage.getCollectionName());
ArrayList<Storage.JSONDocument>jsonDocList = storage.getJsonDocList();
for(Storage.JSONDocument jsonDoc : jsonDocList)
{
System.out.println("docId is " + jsonDoc.getDocId());
System.out.println("JsonDoc is " + jsonDoc.getJsonDoc());
}
String jsonResponse = storage.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"storage": {
"dbName": "test",
"collectionName": "foo",
"jsonDoc": [
{
"_id": {
"$oid": "507bq526c68d198fe882d0d4"
},
"name": "shephertz",
"NickScore": 300
}
]
}
}
}
}
Find target document using Custom Query with paging.
Parameters:
Returns:
Response: Storage Object
Exception:
/* 2605 - BAD REQUEST - Invalid Storage Query. 2608 - NOT FOUND - No document in the collection '<collectionName>' exists for given query. */
String dbName = "test";
String collectionName = "foo";
Query q1 = QueryBuilder.build("NickScore", 500, Operator.LESS_THAN_EQUALTO);
Query q2 = QueryBuilder.build("name", "Ni", Operator.LIKE);
Query q3 = QueryBuilder.compoundOperator(q1, Operator.AND, q2);
int max = 1;
int offset = 0;
Storage storage = storageService.findDocumentsByQueryWithPaging(dbName,collectionName,q3,max,offset); /* returns the Storage object. */
System.out.println("dbName is " + storage.getDbName());
System.out.println("Collection Name is " + storage.getCollectionName());
ArrayList<Storage.JSONDocument>jsonDocList = storage.getJsonDocList();
for(Storage.JSONDocument jsonDoc : jsonDocList)
{
System.out.println("docId is " + jsonDoc.getDocId());
System.out.println("JsonDoc is " + jsonDoc.getJsonDoc());
}
String jsonResponse = storage.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"storage": {
"dbName": "test",
"collectionName": "foo",
"jsonDoc": [
{
"_id": {
"$oid": "507bc528e68d198fe882d0d4"
},
"name": "Nick",
"NickScore": 400
}
]
}
}
}
}
Find target document using Custom Query with paging and orderby.
Parameters:
Returns:
Response: Storage Object
Exception:
/* 2605 - BAD REQUEST - Invalid Storage Query. 2608 - NOT FOUND - No document in the collection '<collectionName>' exists for given query. */
String dbName = "test";
String collectionName = "foo";
Query q1 = QueryBuilder.build("name", "Nick", Operator.EQUALS);
Query q2 = QueryBuilder.build("company", "shep", Operator.LIKE);
Query q3 = QueryBuilder.compoundOperator(q1, Operator.AND, q2);
int max = 1;
int offset = 0;
Storage storage = storageService.findDocsWithQueryPagingOrderBy(dbName,collectionName,q3,max,offset,"_id",OrderByType.ASCENDING); /* returns the Storage object. */
System.out.println("dbName is " + storage.getDbName());
System.out.println("Collection Name is " + storage.getCollectionName());
ArrayList<Storage.JSONDocument>jsonDocList = storage.getJsonDocList();
for(Storage.JSONDocument jsonDoc : jsonDocList)
{
System.out.println("docId is " + jsonDoc.getDocId());
System.out.println("JsonDoc is " + jsonDoc.getJsonDoc());
}
String jsonResponse = storage.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"storage": {
"dbName": "test",
"collectionName": "foo",
"jsonDoc": [
{
"_id": {
"$oid": "507bj236c68d2b42bc4f23db"
},
"name": "Nick",
"company": "shephertz"
}
]
}
}
}
}
Update target document using the document id.
Parameters:
Returns:
Response: Storage Object
Exception:
/* 2605 - BAD REQUEST - Passed JSON string '<newjsonDoc>' is not valid. */
String dbName = "test";
String collectionName = "foo";
String docId = "4faa4707c68df147a51f8be1";
String newJsonDoc = "{\"employeeName \":\"Gill\"}";
Storage storage = storageService.updateDocumentByDocId(dbName,collectionName,docId,newJsonDoc); /* returns the Storage object. */
System.out.println("dbName is " + storage.getDbName());
System.out.println("Collection Name is " + storage.getCollectionName());
ArrayList<Storage.JSONDocument>jsonDocList = storage.getJsonDocList();
for(Storage.JSONDocument jsonDoc : jsonDocList)
{
System.out.println("JsonDoc is " + jsonDoc.getJsonDoc());
}
String jsonResponse = storage.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"storage": {
"dbName": "test",
"collectionName": "foo",
"jsonDoc": {
"employeeName": "Gill"
}
}
}
}
}
Update target document using key value search parameter. This key value pair will be searched in the JSON doc stored in the cloud and matching Doc will be updated with new value passed.
Parameters:
Returns:
Response: Storage Object
Exception:
/* 2601 - NOT FOUND - Document by key '<key>' and value '<value>' does not exist. 2605 - BAD REQUEST - Passed JSON string '<newjsonDoc>' is not valid. */
String dbName = "test";
String collectionName = "foo";
String key = "employeeName";
String value = "Nick";
String newJsonDoc = "{\"employeeName \":\"Gill\"}";
Storage storage = storageService.updateDocumentByKeyValue(dbName,collectionName,key,value,newJsonDoc); /* returns the Storage object. */
System.out.println("dbName is " + storage.getDbName());
System.out.println("Collection Name is " + storage.getCollectionName());
ArrayList<Storage.JSONDocument>jsonDocList = storage.getJsonDocList();
for(Storage.JSONDocument jsonDoc : jsonDocList)
{
System.out.println("docId is " + jsonDoc.getDocId());
System.out.println("JsonDoc is " + jsonDoc.getJsonDoc());
}
String jsonResponse = storage.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"storage": {
"dbName": "test",
"collectionName": "foo",
"jsonDoc": [
{
"_id": {
"$oid": "4fb0dc0bc68d13dfac87d37a"
},
"employeeName": "Gill"
}
]
}
}
}
}
Delete target document using Object Id from given db and collection. The Object Id will be searched in the JSON doc stored on the cloud and matching Doc will be deleted.
Parameters:
Returns:
Response: App42Response Object
Exception:
/* 2600 - NOT FOUND - Document by the Id '<docId>' does not exist. */
String dbName = "test"; String collectionName = "foo"; String docId = "4faa3f1ac68df147a51f8bd7"; App42Response response = storageService.deleteDocumentById(dbName, collectionName, docId); /* returns the App42Response object. */ boolean success = response.isResponseSuccess(); String jsonResponse = response.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"storage": {
"dbName": "test",
"collectionName": "foo",
"jsonDoc": {
"_id": {
"$oid": "4faa3f1ac68df147a51f8bd7"
},
"employeeName": "Nick"
}
}
}
}
}
Map reduce function to search the target document. Please see detail information on map-reduce http://en.wikipedia.org/wiki/MapReduce .
Parameters:
Returns:
Response: String Object
Exception:
/* 2603 - BAD REQUEST - The request parameters are invalid. Make Sure DB and collection name exists and functions are syntactically correct. */
String dbName = "test";
String collectionName = "foo";
String mapFunction = "function map(){ emit(this.user,1);}";
String reduceFunction = "function reduce(key, val){var sum = 0; for(var n=0;n< val.length;n++){ sum = sum + val[n]; } return sum;}";
String response = storageService.mapReduce(dbName, collectionName, mapFunction, reduceFunction); /* returns the Storage object. */
{
"app42": {
"response": {
"success": true,
"storage": {
"dbName": "test",
"collectionName": "foo",
"jsonDoc": [
{
"_id": null,
"value": 2
}
]
}
}
}
}
Save the JSON document in given database name and collection name. It accepts the HashMap containing key-value and convert it into JSON. Converted JSON doc further saved on the cloud using given db name and collection name.
Parameters:
Returns:
Response: Storage Object
String dbName = "test";
String collectionName = "foo";
HashMap< String, String > map = new HashMap< String, String >();
map.put("name", "nick");
map.put("age", "28");
Storage storage = storageService.insertJsonDocUsingMap(dbName,collectionName,map); /* returns the Storage object. */
System.out.println("dbName is " + storage.getDbName());
System.out.println("Collection Name is " + storage.getCollectionName());
String jsonResponse = storage.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"storage": {
"dbName": "test",
"collectionName": "foo",
"jsonDoc": {
"name": "nick",
"age": "28",
"_id": {
"$oid": "50471983c68d8e2fae756551"
}
}
}
}
}
}