The MoCA CIS LIS WSDL Network SOAP/WS

Full text

(1)

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 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

(2)

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.

(3)

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.

(4)

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:

(5)

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].

(6)

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

(7)

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()); ...

(8)

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.

(9)

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/moca-ws

Figure

Updating...

References

Updating...