MoCA/WS: A Web Service Personality of MoCA (Mobile Collaboration Architecture) Marcelo Malcher and Markus Endler Overview 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 Service (CIS) and Location Inference Service (LIS), as these are the main context provisioning services of MoCA. MoCA CIS LIS WEB MoCA/WS WSDL Network SOAP/ HTTP SOAP/ HTTP SOAP/ HTTP Cliente 1 Cliente 2 Cliente N
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.
Request Ticket Listener Client MoCA/WS MoCA Ticket TKT1 MoCA/WS Event Fired MoCA TKT1 TKT2... TKTN Save Get info with ticket Client MoCA/WS TKT1 Return Info Get TKT1 TKT2... TKTN 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. cis.sleep.content.table=30000 #[CIS] Time that the garbage collector is activated. 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: Accessing the WSDL file:
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]. - Requesting a device s context information from CIS:
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 out (SyncTimeOut) approach
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 Requesting Saved Events Result: Events saved 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. Download Download de ZIP containing the WAR (Web Archive File) and a configuration file mocaws.properties Project Dependencies Jax-ws 2.0 CIS APIs LIS APIs SRM APIs References: [1] MoCA/WS Web Site http://www.lac.inf.puc-rio.br/mocaws