App42 Cloud API

Windows Phone Cloud SDK

Session Management

The Session Manager manages user sessions on the server side. It is a persistent Session Manager. It allows to save attributes in the session and retrieve them. This Session Manager is especially useful for Mobile/Device Apps which want to do session management.

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 SessionService, BuildSessionService() method needs to be called.

SessionService sessionService = api.BuildSessionService();

Once the API instance has been retrieved, You are ready to use the functions available for that particular API.

The Windows Phone API's work in an asynchronous mode that means the response will not be available immediately and all the API methods would not return any value and have return type as void. The response will be returned in callback methods which the caller will provide to the calling method.
As mentioned above that the response will be returned in callback methods, every API method is taking instance of App42Callback (as the last parameter) which will have the implementation of 2 methods: OnSuccess & OnException.(as shown below)

public class CallBack : App42Callback
{
public override void OnSuccess(Object obj)
{
Session session = (Session) obj;
//Do whatever you want with the user object
}
public override void OnException(App42Exception e)
{
//Do whatever you want with the exception
}
}

The callback methods will return the response in the form of Object which will have to be type cast to the object domain object (e.g. App42Response / Session in this case) The Domain object 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.

public override void OnSuccess(Object obj)
{
Session session = (Session) obj;  
Console.WriteLine("User Name is" + session.GetUserName());
Console.WriteLine("sessionId is" + session.GetSessionId());
String jsonResponse = session.ToString(); /* returns the response in JSON format. */
}

The functions available under Session Management API can throw some exceptions in abnormal conditions. Example of the same has been given below.

E.g. If App developer is trying to invalidate a Session which is already in invalidated, the function will throw the App42Exception (as shown below) with message as "NOT FOUND" and the appErrorCode as "2202" and the details as "Session with the id '<sessionId>' does not exist.".

public override void OnException(App42Exception ex)
{
int appErrorCode = ex.GetAppErrorCode();
int httpErrorCode = ex.GetHttpErrorCode();
String jsonText = ex.GetMessage(); /* returns the Exception text in JSON format. (as shown below)*/	
} 
{
"app42Fault": {
"httpErrorCode": 400,
"appErrorCode": 2202,
"message": "Bad Request",
"details": "Session with the id '48dacb76-7f5e-4011-ac24-e09623bdc70f' does not exist"
}
}

Below are the HTTP Error Codes and their description, the function under the Session Management 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 Session Management API can throw.

/*
2200 - NOT FOUND - User by the name '<userName>' does not exist.
2201 - NOT FOUND - Session for the user '<userName>' does not exist.
2202 - NOT FOUND - Session with the id '<sessionId>' does not exist.
2203 - BAD REQUEST - The request parameters are invalid. Session with the Id '<sessionId>' is already invalidated.
2204 - NOT FOUND - Attribute with the name '<name>' for session id '<sessionId>' does not exist.
2205 - NOT FOUND - There are no attributes for session id '<sessionId>'.
2206 - NOT FOUND - Attributes for session id '<sessionId>' do not exist.
*/

Various functions available under Session Management API has been explained below.

public void GetSession(String uName, App42Callback requestCallback)

Create Session for the User. If the session does not exist it will create a new session

Parameters:

uName - Username for which the session has to be created
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Session object containing the session id of the created session. This id has to be used for storing or retrieving attributes.

Response: Session Object

For more details click Exception
String userName = "Nick";

sessionService.GetSession(userName,requestCallback);  /* returns the Session object. */  
OnSuccess(Object obj)
{
Session session = (Session) obj;
Console.WriteLine("User Name is" + session.GetUserName());
Console.WriteLine("sessionId is" + session.GetSessionId());
Console.WriteLine("createdOn is" +  session.GetCreatedOn());
String jsonResponse = session.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "session": {
                "userName": "Nick",
                "sessionId": "74f9b379-60f7-4d93-89f2-4aca536ba407",
                "createdOn": "2012-05-09T05:34:55.000Z"
            }
        }
    }
}
public void GetSession(String uName, Boolean isCreate, App42Callback requestCallback)

Create User Session based on the isCreate boolean parameter. If isCreate is true and there is an existing session for the user, the existing session is returned. If there is no existing session for the user a new one is created. If isCreate is false and there is an existing session, the existing session is returned if there is no existing session new one is not created.

Parameters:

uName - Username for which the session has to be created
isCreate - A boolean value for specifying if an existing session is not there, should a new one is to be created or not
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Session object containing the session id of the created session. This id has to be used for storing or retrieving attributes.

Response: Session Object

Exception:

This method throws following exception.
/*
2201 - NOT FOUND - Session for the user '<userName>' does not exist.
*/        
For more details click Exception
String userName = "Nick";

bool isCreate = true;
sessionService.GetSession(uName, isCreate,requestCallback);  /* returns the Session object. */  
Onsuccess(Object obj)
{
Session session = (Session) obj;
Console.WriteLine("User Name is" + session.GetUserName());
Console.WriteLine("sessionId is" + session.GetSessionId());
Console.WriteLine("createdOn is" +  session.GetCreatedOn());
String jsonResponse = session.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "session": {
                "userName": "Nick",
                "sessionId": "48dacb76-7f5e-4011-ac24-e09623bdc70f",
                "createdOn": "2012-05-09T05:38:43.000Z"
            }
        }
    }
}

public void Invalidate(String sessionId, App42Callback requestCallback)

Invalidate a session based on the session id. All the attributes store in the session will be lost.

Parameters:

sessionId - The session id for which the session has to be invalidated
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

App42Response if invalidated successfully

Response: App42Response Object

Exception:

This method throws following exception.
/*
2202 - NOT FOUND - Session with the id '<sessionId>' does not exist.
2203 - BAD REQUEST - The request parameters are invalid. Session with the Id '<sessionId>' is already invalidated.
*/  	        
For more details click Exception
String sessionId = "48dacb76-7f5e-4011-ac24-e09623bdc70f";
						
sessionService.Invalidate(sessionId,requestCallback); /* returns the App42Response object. */
OnSuccess(Object obj)
{
App42Response response = (App42Response) obj;
Boolean success = response.IsResponseSuccess();
String jsonResponse = response.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "session": {
                "userName": "Nick",
                "sessionId": "74f9b379-60f7-4d93-89f2-4aca536ba407",
                "createdOn": "2012-05-09T05:34:55.000Z",
                "invalidatedOn": "2012-05-09T05:38:42.000Z"
            }
        }
    }
}
public void SetAttribute(String sessionId, String attributeName, String attributeValue, App42Callback requestCallback)

Sets attribute in a session whose session id is provided. Attributes are stored in a key value pair.

Parameters:

sessionId - Session id for which the attribute has to be saved
attributeName - The attribute key that needs to be stored
attributeValue - The attribute value that needs to be stored
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Session object containing the attribute and value which is stored

Response: Session Object

Exception:

This method throws following exception.
/*
2202 - NOT FOUND - Session with the id '<sessionId>' does not exist.
2203 - BAD REQUEST - The request parameters are invalid. Session with the Id '<sessionId>' is already invalidated.
*/
For more details click Exception
String sessionId = "48dacb76-7f5e-4011-ac24-e09623bdc70f";
String attributeName = "attributeName01";
String attributeValue =	"attributeValue01";	
		
sessionService.SetAttribute(sessionId, attributeName, attributeValue,requestCallback);  /* returns the Session object. */  
Console.WriteLine("sessionId is" +  session.GetSessionId());
OnSuccess(Object obj)
{
Session session = (Session) obj;
Console.WriteLine("sessionId is" +  session.GetSessionId()); 
IList<Session.Attribute> attributeList = session.GetAttributeList();  
for (int i = 0; i < attributeList.Count; i++)  
{  
Console.WriteLine("sessionId is" + attributeList[i].GetName());
Console.WriteLine("createdOn is" +  attributeList[i].GetValue());
}  
String jsonResponse = session.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "session": {
                "sessionId": "48dacb76-7f5e-4011-ac24-e09623bdc70f",
                "attributes": {
                    "attribute": {
                        "name": "attributeName01",
                        "value": "attributeValue01"
                    }
                }
            }
        }
    }
}
public void GetAttribute(String sessionId, String attributeName, App42Callback requestCallback)

Gets the attribute value in a session whose session id is provided.

Parameters:

sessionId - The session id for which the attribute has to be fetched
attributeName - The attribute key that has to be fetched
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Session object containing the attribute and value which is stored for the session id and attribute name

Response: Session Object

Exception:

This method throws following exception.
/*
2202 - NOT FOUND - Session with the id '<sessionId>' does not exist.
2203 - BAD REQUEST - The request parameters are invalid. Session with the Id '<sessionId>' is already invalidated.
2204 - NOT FOUND - Attribute with the name '<name>' for session id '<sessionId>' does not exist.
*/  	        
For more details click Exception
String sessionId = "48dacb76-7f5e-4011-ac24-e09623bdc70f";
String attributeName = "attributeName01";

sessionService.GetAttribute(sessionId, attributeName,requestCallback);  /* returns the Session object. */  
OnSuccess(Object obj)
{
Session session = (Session) obj;
String sessionId =  session.GetSessionId();  
IList<Session.Attribute> attributeList = session.GetAttributeList();  
for (int i = 0; i < attributeList.Count; i++)  
{  
Console.WriteLine("sessionId is" + attributeList[i].GetName());
Console.WriteLine("createdOn is" +  attributeList[i].GetValue());
}  
String jsonResponse = session.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "session": {
                "sessionId": "48dacb76-7f5e-4011-ac24-e09623bdc70f",
                "attributes": {
                    "attribute": {
                        "name": "attributeName01",
                        "value": "attributeValue01"
                    }
                }
            }
        }
    }
}
public void GetAllAttributes(String sessionId, App42Callback requestCallback)

Gets all the attributes for a given session id.

Parameters:

sessionId - The session id for which the attribute has to be fetched
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Session object containing all the attributes and values which are stored for the session id

Response: Session Object

Exception:

This method throws following exception.
/*
2202 - NOT FOUND - Session with the id '<sessionId>' does not exist.
2203 - BAD REQUEST - The request parameters are invalid. Session with the Id '<sessionId>' is already invalidated.
2205 - NOT FOUND - There are no attributes for session id '<sessionId>'.
*/ 	        
For more details click Exception
String sessionId = "48dacb76-7f5e-4011-ac24-e09623bdc70f";

sessionService.GetAllAttributes(sessionId,requestCallback);  /* returns the Session object. */  
OnSuccess(Object obj){
Session session = (Session) obj;
IList<Session.Attribute> attributeList = session.GetAttributeList();
for (int i = 0; i < attributeList.Count; i++)
{
Console.WriteLine("sessionId is" + attributeList[i].GetName());
Console.WriteLine("createdOn is" +  attributeList[i].GetValue());
}
String jsonResponse = session.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "session": {
                "sessionId": "48dacb76-7f5e-4011-ac24-e09623bdc70f",
                "attributes": {
                    "attribute": [
                        {
                            "name": "attributeName01",
                            "value": "attributeValue01"
                        },
                        {
                            "name": "attributeName02",
                            "value": "attributeValue02"
                        }
                    ]
                }
            }
        }
    }
}
public void RemoveAttribute(String sessionId, String attributeName, App42Callback requestCallback)

Removes the attribute from a session whose session id is provided.

Parameters:

sessionId - The session id for which the attribute has to be removed
attributeName - The attribute key that has to be removed
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

App42Response if removed successfully

Response: App42Response Object

Exception:

This method throws following exception.
/*
2202 - NOT FOUND - Session with the id '<sessionId>' does not exist.
2203 - BAD REQUEST - The request parameters are invalid. Session with the Id '<sessionId>' is already invalidated.
*/	        
String sessionId = "48dacb76-7f5e-4011-ac24-e09623bdc70f";
String attributeName = "attributeName01";

sessionService.RemoveAttribute(sessionId, attributeName,requestCallback); /* returns the App42Response object. */
OnSuccess(Object obj)
{
App42Response response = (App42Response) obj;
Boolean success = response.IsResponseSuccess();
String jsonResponse = response.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "session": {
                "sessionId": "48dacb76-7f5e-4011-ac24-e09623bdc70f",
                "attributes": {
                    "attribute": {
                        "name": "attributeName01"
                    }
                }
            }
        }
    }
}
public void RemoveAllAttributes(String sessionId, App42Callback requestCallback)

Removes all the attributes for a given session id

Parameters:

sessionId - The session id for which the attributes has to be removed
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

App42Response if removed successfully

Response: App42Response Object

Exception:

This method throws following exception.
/*
2202 - NOT FOUND - Session with the id '<sessionId>' does not exist.
2203 - BAD REQUEST - The request parameters are invalid. Session with the Id '<sessionId>' is already invalidated.
2206 - NOT FOUND - Attributes for session id '<sessionId>' do not exist.
*/ 		        
For more details click Exception
String sessionId = "48dacb76-7f5e-4011-ac24-e09623bdc70f";

sessionService.RemoveAllAttributes(sessionId,requestCallback); /* returns the App42Response object. */
OnSuccess(Object obj)
{
App42Response response = (App42Response) obj;
Boolean success = response.IsResponseSuccess();
String jsonResponse = response.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "session": {
                "sessionId": "48dacb76-7f5e-4011-ac24-e09623bdc70f",
                "attributes": {
                    "attribute": [
                        {
                            "name": "attributeName01"
                        },
                        {
                            "name": "attributeName02"
                        }
                    ]
                }
            }
        }
    }
}