SDMConnectivity

The SDMConnectivity layer hides the complexity of network communication and provides easy to use APIs to the applications.

List of Features

  • Provides interfaces for request handling
  • Handles the requests asynchronously
  • Can handle the requests by multiple number of threads (configurable)

SDMConnectivity Public APIs

Note: The SUP APIs and their descriptions are available after the installation of Sybase Unwired Platform at the following location within your installation folder: ...\UnwiredPlatform\ClientAPI\apidoc.

The SDMRequestManager class implements the ISDMRequestManager interface, which provides the following methods:

ISDMRequestManager

	void makeRequest(final ISDMRequest aRequest); 
	void makeRequest(final ISDMBundleRequest aRequest); 
	ConnectivityParameters getConnectivityParameter();
	int getQueueSize();
	Vector getAllRequests();
 Object getRequest();
 void setMainHandlerClassName(final String classname);
 void terminate();
 boolean hasRequests();
 void sendOnSuccess(final ISDMNetListener listener, final ISDMRequest request, finral HttpResponse response);

The number of working threads in the RequestManager class is configurable via the constructor. The number of threads is maximized by the connectivity layer because of performance related issues. If the client initializes the layer with more than the allowed threads, the implementation of the connectivity layer will decrease the thread number to the max allowed number (4).

Methods defined by the ISDMConnectivityParameters interface: 

SDMConnectivityParameters

	void setUserName(final String aUserName);
	String getUserName(); 
	void setUserPassword(final String aPassword); 
	String getUserPassword();
	void setBaseUrl(final String url);
	String getBaseUrl();

		String getLanguage();
	void setLanguage(final String language); 
	void setServerCertificate(Certificate certificate) throws KeyStoreException;
	final TrustManager[] getTrustManagers();
Sending requests with the connectivity layer consists of the following steps:
  1. Create the RequestManager class and initialize it with the required parameters.
  2. Create the request object. This can be done in the following ways:
    • Implement the ISDMRequest interface.
    • Extend the BaseRequest class, which is the base implementation of the ISDMRequest interface.
    • When the requests’ execution order is important, implement the ISDMBundleRequest, add the ISDMRequest instances into it, then pass this bundle to the request manager. Both of them are provided by the connectivity layer.
  3. Use the request / request bundle object when making a request to the RequestManager.

SDMBundleRequest is a special set of SDMRequest objects. It provides serial processing of the requests when the SDMRequestManager is in multithreaded mode. Because the single SDMRequest objects are processed by multiple threads, the timing of the responses are not consistent. With SDMBundleRequest, one thread processes the bundled requests, guaranteeing that the responses are arriving in the same order as the requests are added to the bundle.

Example

//create and fill parameters for Connectivity library
SDMConnectivityParameters params = new SDMConnectivityParameters();
params.setUserName("test");
params.setUserPassword("testpwd");
mLogger = (ISDMLogger) new SDMLogger();
mPreferences = new SDMPreferences(getApplicationContext(), mLogger);
//create the RequestManager
mRequestManager = new SDMRequestManager(mLogger, mPreferences, params, 2);
ISDMRequest testRequest = new SDMBaseRequest();
testRequest.setRequestUrl("http://test.de:8080/testpath");
testRequest.setRequestMethod(ISDMRequest.REQUEST_METHOD_GET);
testRequest.setPriority(ISDMRequest.PRIORITY_NORMAL);
//add the request to the connectivity layer
mRequestManager.makeRequest(testRequest);

Technical Details

The tasks of the connectivity library have been divided into three main categories:
  • Manage the request queues
  • Manage the reading writing to the input/output streams
  • Manage the platform specific connection creation
The Connectivity component always performs the requests in asynchronous mode. The application’s role is to handle the requests in sync mode. The component is able to perform HTTP and HTTPS requests, which you can use for developing and testing purposes, but the default is SUP Request. The threads in the connectivity library are responsible for taking the requests from the queue (FIFO - First in first out - algorithm) and performing the requests. The number of working threads in the connection pool can be configured in the connectivity layer. The queue is handled by the SDMRequestManager, and the working threads take the requests from this queue. Applications are interacting only with the SDMRequestManager class; the other components of the connectivity library are not visible to them. The network component consists of three main parts:
  • SDMRequestManager: responsible for queuing the requests, managing the threads and keeping the connection with applications
  • AbstractConnectionHandler: responsible for performing the request
  • ConnectionFactory: responsible for creating and managing platform dependent connections to the server

An application can have more than one SDMRequestManager instances, for example, when connecting to two different servers at the same time. To support this scenario, SDMRequestManager handles ConnectionHandler as a plugin. This kind of plugin needs to implement the ISDMConnectionHandler and implement a constructor taking three parameters: SDMRequestManager, ISDMLogger implementation and ISDMPreferences implementation.

The class name with package is set by SDMRequestManager.setMainHandlerClassName(String), or in SDMPreferences by the ISDMPreferences.SDM_CONNECTIVITY_HANDLER_CLASS_NAME preference key. The default plugin is "com.sybase.mobile.lib.client.IMOConnectionHandler", which handles connections through SUP.

There is built-in support for setting the timeout for the socket connection: the application can use the SDMPreferences object to modify the value, using the following keys:
  • ISDMPreferences.SDM_CONNECTIVITY_CONNTIMEOUT for connection timeout, and
  • ISDMPreferences.SDM_CONNECTIVITY_SCONNTIMEOUT for socket connection timeout.

SDMRequest Object

An SDMRequest object wraps all the information needed by the connectivity library to be able to perform the requests. The connectivity library interacts with the request object to query the necessary information about the headers, the post data, and so on. The connectivity layer also uses the request object to notify the application about the result of the request by using the ISDMNetListener interface. The connectivity component provides an interface called ISDMRequest and a base implementation of it, called SDMBaseRequest. The applications have to extend this interface when creating new application specific requests. 

ISDMRequest

o		void setRequestUrl(String url); 
o		String getRequestUrl(); 
o		void setRequestMethod(final int reqType); 
o		int getRequestMethod();
o		byte[] getData();
o		Hashtable getHeaders();
o		void setPriority(final int value);
o		int getPriority();
o		boolean useCookies();
o		ISDMNetListener getListener();
o		void setListener(ISDMNetListener listener);
The connectivity layer notifies the client about the result of a request by the ISDMNetListener interface. Usage of this feature is not mandatory, but it is recommended to be able to handle incidental errors. Methods available in the ISDMNetListener interface: 
ISDMNetListener

	void onSuccess(ISDMRequest  aRequest, HttpResponse aResponse);
	void onError(ISDMRequest aRequest, HttpResponse aResponse, SDMRequestStateElement 	   aRequestStateElement);
The role of the SDMRequestStateElement object used by the connectivity library is to provide the application with more detail on the occurred error. Methods available in ISDMRequestStateElement interface: 
ISDMRequestStateElement

	int getHttpStatusCode();
	int getErrorCode();
	Exception getException();	void setHttpStatusCode(final int httpStatus);
	void setErrorCode(final int code);
	void setException(final Exception aException);

Example

public void onSuccess(ISDMRequest  aRequest, SDMHttpResponse aResponse) {
	System.out.println("Http response status code:" + aResponse.getStatusCode());
	System.out.println("Cookie string:" + aResponse.getCookieString());
	byte[] content = aResponse.getContent();
	String response = new String(content);
	System.out.println("Received content:" + response);
	//get the headers
	Hashtable headers = aResponse.getHeaders();
}
Parent topic: OData SDK Components and APIs