Welcome!

Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Java Development

Sample "Please Wait" Screen - part 3

by Developer on ‎06-30-2010 03:25 PM - edited on ‎09-20-2010 04:27 PM by BlackBerry Development Advisor (14,160 Views)

If you have reviewed the previous two articles, you will see that there is still two things missing:

  1. Status updates from the Background Thread
  2. "Time to go" indication

 

This article addresses both these points, though not completely.  For the sake of simplicity, this article just adds a "percentage complete" progress bar to the display.  The approach used to do this can be extended to provide 'status updates' and 'time to go' indications. 

 

Also for simplicity, the enhancements added in part 2, using the Stoppable Interface, are not included in the part 3 sample.  These can easily be incorporated, but that would make this sample code larger and more complex, and hide the lessons to be learned from adding the percentage complete Field.

 

For those of you interested in patterns, this sample is really an implementation of the Observer and Observable Interfaces.  These are not defined in Java® ME, but are easy to add.  In this case, we have used Observer and Observable Interface definitions that are specific to this requirement. 

 

To provide a percentage complete Display Field, in a generic way that can be used by many processes, we must:

  1. Define a way so that the background processing can update an Observer as it progresses — the PercentageCompleteObserver Interface
  2. Define a way to tell the PleaseWaitScreen that the background processing may supply the percentage complete figures — the PercentageCompleteObservable interface.
  3. Add a Field to the PleaseWaitScreen that will display the percentage complete — a GaugeField.

If you have reviewed Part 1 and Part 2, you will see that we are getting a simple HTML file from the Web, and this process takes such a short time we have actually had to artificially slow it down. 

 

In this case we want a more reasonable demonstration, so we need a larger file to download.  The sample code defaults to downloading the current UI Guidelines — which is currently a 7 MB .pdf (and a very good read!). 

 

You will no doubt be aware that downloading a large file in one go will typically result in a 413 response code.  To overcome this, we download the file in chunks, using the code from the following KB article:

 

Download large files using the BlackBerry Mobile Data System

 

This also gives us an easy place to update the Observer. We can do it for every chunk! Note that the sample now requires a microSD card because it saves the chunks of the file to it.  Refer to the following article for the steps to configure a microSD card in the BlackBerry® Smartphone Simulator.

 

Use a computer file system as a microSD card

 

So our Background processing is a variation on the DownloadCombiner code supplied in this article. Now on to the code.

 

1) Update the background processing to provide the figures we want to an Observer

 

We must first  be able to tell our Background Processing (DownloadCombiner)  that something wants to see it progressing.  In this case, we want to tell DownloadCombiner that the PleaseWaitScreen would like to be advised of percentage changes.  As is standard in Java®, we use a 'listener', though in this case it is more normally called an Observer.  We need the background processing to know that there is an Observer, so we define a method in our background processing that allow an Observer to register for updates.  In this case, we use the method setPercentageCompleteObserver(..). Note that our background processing (DownloadCombiner) supports only one Observer at a time.

 

So we have an Observer, but how do we provide Observations to it?  In this case, we want to provide percent complete figures, so we need our Observer to implement a method the background procesising can invokel to supply an integer value between 0 and 100.  Normally Observers are called using an update method, so the method our background processing will use is update(int percentComplete).

 

Now, to make sure that our Observer has this method, we require the Observer to implement the PercentageCompleteObserver interface, as follows:

 

/**
* A class can implement this interface when it wants to know the
* completion percentage of an Observed process.
*/
public interface PercentageCompleteObserver {
/**
* This method is called whenever the percentage completion of an
* observed process changes.
* This is a simple implementatin of the 'Observer' interface
* designed to demonstrate the functionality.
* @param perdentComplete - the current percentage completed.
* Note the following special values:
* 0 - is used when the processing is first started
* 100 - will only be supplied when the processing is about to terminate
* -1 - is supplied if there is an error.
*/
public void update(int percentComplete);
}

 

 

2) Defining background Processing that can supply a percentage Complete

 

As noted in Part 2, we have not told the PleaseWaitScreen anything about the processing it is running.  All we have told it, is that the processing is Runnable.  This makes the PleaseWaitScreen very general - it is not tied to one particular Object.  We want to do the same for this.  So we use the same Java concept. 

 

We create an interface, called PercentageCompleteObservable.  This interface has one method, setPercentageCompleteObserver() as shown:

 

/**
* A class can implement this interface when it supports providing
* PercentageCompleteObserver observervations.
*/
public interface PercentageCompleteObservable {

/**
* This method is called to set a
* PercentageCompleteObserver observer for the implementing Object.
*/
public void setPercentageCompleteObserver(PercentageCompleteObserver observer);

}

 

Any Object can implement this interface, in our case, our Background processing (DownloadCombiner) already has implemented this, so to complete this step, we just need to update the source for DownloadCombiner to indicate that it has implemented PercentageCompleteObservable, as well as Runnable. 

 

 

3) Adding the GaugeField (only when it is going to be useful)

 

We want to extend the PleaseWaitScreen, so that it will continue to work our existing Runnable Objects and also support Runnable processing that is PercentageCompleteObservable.  To achieve this, the constructor checks to see if the Runnable process being executed is, in fact, PercentageCompleteObservable.  If it is, the constructor add a GaugeField, and adds itself as a PercentageCompleteObserver.  The public void update(final int percentComplete) method in the PleaseWaitScreen updates the GaugeField. 

 

As noted at the start of this article, most implementations will also want to be able to cancel  the background processing, which requires combining this and the changes made in Part 2.  Good luck with this.

 

Sample code is attached. 

 

One final thing.  When I run this code on one of my devices, the LabelField on the PleaseWaitScreen occasionally says something like the following:

 

Error reported: -13

 

I can't see how we ever get a negative number.  If you could sort this out, that would be great!

 

Additional Links

Sample "Please Wait" screen - part 1

Sample "Please Wait" screen - part 2

Contributors
Comments
by BlackBerry Development Advisor on ‎06-11-2010 09:52 AM

Ready for publication.

Users Online
Currently online: 4 members 1,687 guests
Please welcome our newest community members: