MoCA/WS: A Web Service Personality of MoCA (Mobile
Collaboration Architecture)
Marcelo Malcher and Markus EndlerOverview
The main purpose of MoCA/WS is to allow non-Java client programs to access and use the context services provided by the MoCA architecture. MoCA/WS acts as a proxy and offers a similar interface to its clients that the MoCA’s own APIs for Java applications. Now, any language that offers support to web services, such as .NET, Delphi, and C++, can be used to implement clients of MoCA.
When a client application sends a request to the MoCA/WS (through a SOAP
message over HTTP), it forwards this request to a MoCA service and returns a SOAP reply. The illustration below shows how the communication between a client, the MoCA/WS and MoCA is made.
Hence, MoCA/WS and MoCA establish a CLIENT-SERVER relationship, and now MoCA/WS is responsible for handling clients, while the MoCA service(s) now have only one client,
MoCA/WS. One should remark that there may exists other Java clients (or MoCA/WS instances in another web container) concurrently accessing the services of MoCA.
The figure below illustrates the communication between the participants. MoCA/WS offers methods to access only the Context Information Service (CIS) and Location Inference Service (LIS), as these are the main context provisioning services of MoCA.
MoCA WEB CIS LIS MoCA/WS Cliente 1 Cliente 2 Cliente N SOAP/ HTTP WSDL Network SOAP/ HTTP SOAP/ HTTP
There is a major difference between accessing the MoCA APIs directly through a Java application and accessing it through MoCA/WS. Because it is a web service and its communication it is over HTTP (stateless), the MoCA/WS doesn’t know who its clients are. Requesting synchronous methods it is exactly equal like any other Java application that uses MoCA APIs. This is because the request-response approach of HTTP fits with these synchronous methods. However, requesting asynchronous methods of CIS and LIS is different. Using CIS and LIS services in the regular way, a client subscribes a request and the middleware publishes the events when they occur. Like MoCA/WS doesn’t know its clients, two other ways to use these kind of methods were developed.
The first way, called SyncTimeOut way, offers access to the asynchronous methods with a condition. A client can requests the MoCA/WS passing as argument a time out, that it is checked and the response is sent back when an event meeting the conditions occurs, or the time out occurs . There is a chance that the client receives null as answer. With LIS services, there is another argument passed, the number of events desired, that is, if the number of desired events happens before the time out explodes it is returned the events to the client. If the time out explodes before, it is returned all the events that were received (even if is still not happened the exactly number of desired events). The illustration bellow shows how this approach works.
The other way is called Async. It uses the concept of tickets, where a ticket holds the response of an asynchronous requests. When the MoCA/WS creates a ticket and sends it back to its clients, it associates that ticket with the events received by the MoCA services, and saves these events in a virtual table, like a buffer. Holding a ticket, a client can requests all events associated with it, and may decide if the MoCA/WS should continue to receive events associated with the ticket, or not. Periodically, a garbage collector is executed on the virtual table, in order to remove events that are older than some specific, pre-configured time. The figure below illustrates the interactions using tickets.
Client MoCA/WS MoCA Request Ticket Listener
Ticket
MoCA/WS Event Fired MoCA
TKT1 .. . TKT1 TKT2 TKTN Context Information Context Information Context Information Context Information Context Information Save Client MoCA/WS
Get info with ticket
Return Info TKT1 .. . TKT1 TKT2 TKTN Context Information Context Information Context Information Context Information Context Information Get
For more information on getting started with MoCA/WS, see the following documents:
• User Guide – Using MoCA/WS • MoCA/WS’ Java Doc
Deploying & Configuring
First, download the MoCA/WS ZIP file (containing the WAR file and the properties file). A web container like Tomcat it is needed to deploy the MoCA/WS. There are only three steps to start to use:
1. Copy all JAR files from the project dependencies to the LIB folder of the web container (in use of Tomcat, [TOMCAT_DIRECTORY//shared//lib]);
2. Copy the properties file to the lib directory of the Java Virtual Machine used by the web container (like [JAVA_HOME]//jre/lib) and configure it;
3. Deploy the WAR file in the web container. How to configure:
In order to ensure that MoCA/WS connects correctly to CIS and LIS, the
MoCAWS.properties file that comes in the MoCA/WS ZIP file has to be configured following these rules:
local.address=192.168.0.145 #IP of MoCA/WS's machine
cis.address=192.168.0.145 #CIS address, same of cis.server.address of cis.properties file lis.address=192.168.0.145 #LIS address, same of lis.server.host of lis.properties file srm.address=192.168.0.145 #SRM address, same of srm.server.host of srm.properties file protocol=TCP #protocol of communication, TCP or UDP
cis.time.out=3000 #time out of CIS connection
cis.async.server.port=55000 #Async Event port, same of cis.event_server.port of cis.properties file cis.sync.server.port=55001 #Sync port, same of cis.server.port of cis.properties file
cis.subscriber.local.port=55903 #Subscriber local port, can be any port that is not used
cis.time.out.content.table=600000 #[CIS] Time that the garbage collector considers that an saved #event is old. In miliseconds.
lis.server.port=55021 #LIS server port, same of lis.server.port of lis.properties file lis.publisher.port=55020 #LIS publisher port, same of lis.publisher.port of lis.properties file lis.client.port=55301 #LIS client port, can be any port that is not used
srm.server.sync.port=55030 #SRM Sync port, same of srm.query.port of srm.properties file srm.server.async.port=55031 #SRM Async port, same of srm.event.port of srm.properties file lis.time.out.content.table=600000 #[LIS] Time that the garbage collector considers that an saved event #is old. In miliseconds.
lis.sleep.content.table=30000 #[LIS] Time that the garbage collector is activated. In miliseconds.
Using MoCA/WS
After having deployed MoCA/WS, it can be used. Accessing the methods offered by the WSDL (Document description of the web service) is simple and like any object use. The examples showed in the following were developed using Microsoft Visual C# 2005.
A developer just needs to add a web reference and create an object to the MoCA/WS. After that, he/she can use its methods like any other object. The illustrations bellows shows the sequence of creating a web reference at Visual C# 2005.
Adding the web reference:
The new object in the tools:
Visual C# 2005 offers great support for web services creating the stub classes automatically.
Calling the methods:
The application used as example access all methods of the web service and can be downloaded from [1].
Code: ...
WS.deviceContextWS context = mocaWS.askCIS(txtCISSyncMacAddress.Text); lstCISSyncResult.Items.Clear();
//Advertisement Periodicity
lstCISSyncResult.Items.Add("> Advertisement Periodicity = " + context.advertisementPeriodicity.ToString());
//Ap Change
lstCISSyncResult.Items.Add("> Ap Change = " + context.apChange.ToString()); //Cpu Usage
lstCISSyncResult.Items.Add("> CPU Usage = " + context.cpuUsage.ToString()); ...
- Requesting a device’s context under a certain condition with time
Code: ... WS.deviceContextWS context = mocaWS.requestCIS(txtCISSyncTimeOutMacAddress.Text, txtCISSyncTimeOutSQL.Text, Convert.ToInt64(txtCISSyncTimeOutTimeOut.Text)); if (context == null) return; lstCISSyncTimeOutResults.Items.Clear(); //Advertisement Periodicity
lstCISSyncTimeOutResults.Items.Add("> Advertisement Periodicity = " + context.advertisementPeriodicity.ToString());
//Ap Change
lstCISSyncTimeOutResults.Items.Add("> Ap Change = " + context.apChange.ToString());
//Cpu Usage
lstCISSyncTimeOutResults.Items.Add("> CPU Usage = " + context.cpuUsage.ToString());
...
- Requesting a CIS ticket and using this ticket to request saved
events:
Code for requesting tickets: ...
WS.ticketWS ticket = mocaWS.requestTicketCIS(txtCISAsyncMacAddress.Text, txtCISAsyncSQL.Text);
if (ticket == null) return;
lstCISAsyncTickets.Items.Add(ticket.id.ToString()); ...
MAC Address SQL Condition
Tickets recebidos
Result: Events saved
Requesting Saved Events
Code for requesting the saved events with a ticket: ...
//delete is boolean
listDvcCtxWS = mocaWS.getTicketCISInfo(ticket, delete); //for each saved event
foreach (WS.deviceContextWS dvcCtxWS in listDvcCtxWS)
{
lstCISAsyncResults.Items.Add("Fired event for: " + dvcCtxWS.mobileHostMacAddress);
} ...
To view the LIS methods see the source of this client example or check the official document of MoCA/WS (in portuguese).
Using Mobile Applications Example
We have implemented a simple Pocket PC application that connects with MoCA/WS and receives context information about devices. This example was developed with Visual Basic .NET 2005. The figure bellow shows the PDA connecting to the
MoCA/WS and receiving this information. The code used for this application is exactly the one showed above.
The examples showed here were executed under .NET Framework 2.0 and .NET Compact Framework 2.0.
Samples:
- Link to the client example
- Link to the PDA’s client example.
