1. JavaRosa Team Dimagi Avatar JavaRosa Team Dimagi
  2. javarosa
  3. javarosa

Wiki

Clone wiki

javarosa / ReliableHttp

View History

Table of Contents

  • [#UsingReliableHttpTransportMethod Using RHTM]
  • [#CommunicatingwithaRegularHTTPServer Communicating with a Regular HTTP Server]
  • [#SettinguptheRHTMServer Setting up the RHTM Server]
  • [#Preferences My Preferences]
  • [#Rationale Rationale]
  • [#MessageSequence Message Sequence]
  • [#Layout Layout]
  • [#ProtocolExample Protocol Example]
  • [#ExpectedBehaviour Expected Behaviour]

Using ReliableHttpTransportMethod

ReliableHttpTransportMethod (RHTM) is designed to be a drop-in replacement for the HttpTransportMethod (HTM). To start using it, first make sure org.javarosa.communication module is part of your build. Then simply call 

new ReliableHttpTransportModule().registerModule(context);

instead of

new HttpTransportModule().registerModule(context);

at the start of your application.

Consecutive uploads are queued, much like in the regular http. Concurrent uploads are no longer supported since they bring the user interface to a grinding halt when the network conditions are poor.

Communicating with a Regular HTTP Server

RHTM can communicate with a regular HTTP server. In this case, it simply attempts to send data just HTM. If there is a problem in transmitting, it will automatically retry sending until it reaches the user-configured maximum number of retry attempts.

Setting up the RHTM Server

To make full use of RHTM, you can set up the RHTM server located in ‘serverrosa’ in the svn repository. The main file of interest is JavaRosaTestServlet.java, although there are various project settings in that directory as well. To setup the RHTM Server for development: 1. Install the latest version of Eclipse with support for Java Enterprise Edition. (Currently we have only tested with Eclipse 3.4.1). 2. Install the latest version of Tomcat. (Currently we have only tested with Tomcat 5.5). 3. Check out the serverrosa directory from the svn repository. 4. Open Eclipse. 5. Select File -> Import -> General -> Existing Projects into Workspace. 6. Click ‘Browse’ next to ‘Select root directory’ and browse to your local copy of serverrosa. You should find and be able to load an eclipse project definition. 7. Right-click on the whitespace in Project Explorer and select New -> Other->Server->Server. 8. Select the appropriate server (in my case, Apache -> Tomcat V5.5) and click “Finish”. 9. Right-click org.javarosa.server in your Package Explorer and select “Run as”/“Debug as” -> “Run on Server”/“Debug on Server” 10. Select the server you configured in Step 8. Click “Finish”. 11. In the server panel, you should see the Tomcat server “Starting” and then “Running”. The Eclipse ‘Web Browser’ window should open and display the status page from JavaRosaTestServlet.

Note: If you’re installing Java EE on Ubuntu, you may need to manually specify the location of your latest jvm while executing the installer. For example, instead of running

sudo ./java_ee_sdk-5_03-linux-nojdk.bin

as per the installation instructions, you would run: 

sudo ./java_ee_sdk-5_03-linux-nojdk.bin -javahome /usr/lib/jvm/java-6-sun-1.6.0.03

Preferences

There are a certain number of user-configurable parameters. On the phone/client, these can be modified through the javarosa 'settings' menu item. Parameters include:

  • Maximum number of retransmission attempts
  • Time to wait between retransmission attempts (should be longer than 1 s, even in the best environments, to account for transient delays) The server currently assumes the existence of a writable directory at /usr/share/tomcat5.5/webapps/jrtest/store/. In the final release, this will be a reconfigurable parameter in a text file.

Rationale

This module is designed to support a big form submission over a poor network connection.

Message Sequence

1. Client POSTs big form with Etag set to file’s unique ID (md5 of file) to ReliableHttp server (port 80). 2. Big form is interrupted. 3. Client sends empty HEAD with same ETag to test whether the server supports reliable HTTP. 4. Server responds with same E-Tag and byte range in HTTP’s ‘Range’ field 5. Client POSTs bytes not yet received by server (bytes specified in Content-Range) 6. As file is being received, server copies data to local file system identifying each file by its unique ID. (Buffer filewriting manually to ensure optimal robustness to power outages). 7. After file completely sent, server issues confirmation of bytes received. 8. reliableHttpServer submits data to the local web server.

  • Multiple form submissions are placed in a FIFO queue
  • If the server does not support reliable http, then it will not provide the correct E-Tag in its response to the client in step 4. Then the client will proceed with regular http re-submission to the given IP/URL at port 80 until it reaches the maximum retransmission timeout.
  • If the client is powered down during transmission, transmission resumes upon startup of javarosa, assuming maximum retransmission time has not passed. This occurs in ReliableHttpTransportMethod’s initialization.
  • If the server is powered down during transmission, transmission resumes when the server becomes available, assuming maximum retransmission time has not passed.

Layout

Client functionality implemented in package: javarosa.communication.reliablehttp Inherits from javarosa.communication.http ReliableHttpTransportMethod’s Worker Thread – one spawned for each download Server’s JavaRosaTestServlet (extends HttpServlet)

Protocol Example

Client initiates upload: 

POST /upload HTTP/1.1
If-Match: "MD5"
[other HTTP headers]

[data]

The request is terminated prior to receiving a response from the server. Client polls the server to determine which bytes it has received: 

HEAD /upload HTTP/1.1
If-Match: "vEpr6barcD"
[other HTTP headers]

Server responds with the current byte range: 

HTTP/1.1 308 Resume Incomplete
ETag: "vEpr6barcD"
Content-Length: 0
Range: 0-42
[other HTTP headers]

Client resumes where the server left off:

POST /upload HTTP/1.1
If-Match: "vEpr6barcD"
[other HTTP headers]

[remaining data]

This time the server receives everything and sends its response:

HTTP/1.1 200 OK
ETag: "vEpr6barcD"
[other HTTP headers]

[response]

Expected Behaviour

  • If you try to transmit to a non-existent URL, it will re-try several times (very slow). This is because there is no good way to differentiate non-existent URLs vs servers that are just really slow to access. So don’t do this.
  • Occasionally, over poor network conditions, the server will throw a ReadTimedOutException. This is fine and nothing to worry about. The server will recover and reliableHttp will resend.

Updated