J2ME Convertor Application

It has only occured to me recently that the Sony Ericsson 750i does not seem to include a weight/distance/volume convertor utility. Nokia had such an utility on their phones for a while now -- even though it looked a bit, well, rubbish really :-). And even with the new models of Sony Ericsson mobile phones you seem to actually get such an utility nowadays. However, there are still a lot of users of the Sony Ericsson 750i it seems as they were a major hit, and I'm sure that certain other models -- not just Sony Ericsson -- lack of such an utility. So if you're like me, and never made too much sense of the imperial units, then you might find an utility like this one, that you can take on your mobile phone everywhere quite handy.

Note for the impatient users: Click here to scroll down to the download link.

For the not-so-impatient ones, there are a couple of things you might want to know before downloading the application and starting to customize it:

• First and foremost, the application has been compiled using Wireless Toolkit 2.1 and uses CLDC-1.1 and MIDP-2.0 profiles. If you are going to target a more recent phone you could change this and compile it specifically for your platform.
• Also note that due to the fact that it targets MIDP-2.0, if planning to deploy this on an older phone (for instance, one that only supports MIDP-1.0), the application will not work out-of-the-box. It is likely that you can adapt the code to work on this platform but I am not willing to provide such backward compatibility as most of the phones that I have encountered in the last couple of years support MIDP-2.0.
• I have tried this application on a Nokia 6600 series and on Sony Ericsson 750i and W900i and it worked fine. Due to the fact that it doesn't use any Nokia or Sony Ericsson specific libraries/calls/etc, it should work fine on all the other devices that support J2ME. However, if you find it to have problems running on your phone, please let me know by using the Support Page. Please make sure that you select Report Mobile Application Problem from the dropdown menu when sending such a message.
• If you think the application is lacking certain facilities (quite likely) and/or you have extended it to include such facilities, please feel free again to use the Support Page to send me a message and I will get back to you and find a way to incorporate such changes in the application.

Installing the Application

There are a few ways you can install this application on your phone. I would strongly recommend that you download the jar file and then install it to your mobile via Bluetooth, as the cost is zero doing it this way, however, feel free to use over-the-air installation as well, but be aware that your network operator might charge you for the transfer.

• Installing via Bluetooth -- If your mobile supports Bluetooth connections and if you have a way to connect your computer to your mobile via Bluetooth (e.g. a Bluetooth USB dongle), then you can use this method. The advantage of this method is that there is that there will be no charge on your mobile for installing the application. Simply download the application binaries, which are packaged in a jar file, to your computer. (To download the binaries, go to the downloads section at the bottom of the page.) Save the file on your hard disk as j2me_convertor.jar. After the file has finished downloading, using your Bluetooth software tools (normally these come with either the USB Bluetooth dongle, the operating system or with the phone) copy this jar file onto your phone. At this step your mobile phone will prompt you whether you want to install this application or not. Simply accept the installation and allow for the software to be installed. Once installed, the stopwatch application will be stored on your phone and you can use it any time you want.
  Please note that certain phones might take you through a few confirmation steps during the installation process. Such steps are not described here and you should consult your mobile phone manual for this. Also note that certain mobiles that have a memory card/stick/etc will probably prompt you whether you want the application to be saved onto your mobile memory or the memory card/stick. It is irrelevant from the application's point of view where you install it and the application will work the same whether saved onto your mobile memory or on the memory card.
• Over-the-air Installation -- If you do not have Bluetooth support in your mobile (unlikely!) or you do not have a way to connect your PC to your mobile via Bluetooth, and you have internet access on your mobile phone, you can use this method to install the application. Be aware that this method involves accessing the internet from your mobile phone and your network operator will more than likely charge you for that. However, if you have a certain download limit included in your contract, or the cost of such download is rather negligeable, than you can proceed using this method. To use over-the-air installation, using your mobile, navigate to the link (provided below) to download the application descriptor. The application descriptor is a file in a certain format that "describes" the application to the mobile, in order to allow the user to see certain details and make up his/her mind whether s/he should continue with installing the application. This descriptor file also contains the URL where the actual application binaries (the jar file) can be downloaded from, should the user chose to continue with the installation. So when entering the link in your mobile and navigating to it, your mobile phone will download this file and it will prompt you with details about the application and whether you want to continue with the installation. If you decide that you want to continue, then the mobile phone will download the jar file that contains the application and then take you through all the confirmation screens necessary when installing a Java application.
  Please note that the size of the jar file is about 91K, so the download shouldn't take that long -- but then again, this depends on your connection speed.
  To download the application descriptor the link is: http://www.liviutudor.com/tech/downloads/j2me_convertor.jad (note that this link is also given below in the Downloads section.)

Compiling the Application

If you decide that you want to modify the application, you will need to download the sources. These are provided in the Downloads section below, packaged in a zip file that contains the whole application project. I personally use Eclipse (link will open in a new window) and EclipseME (link will open in a new window) plugin to edit the file and compile them. Obviously, these still rely on the presence of Sun's Wireless Toolkit (WTK) (link will open in a new window) so you will need to have this installed as well. (As stated above, this project relies on WTK 1.1 and above, so if you have WTK 2.0 or a more recent version, that will work just as well.) Due to my using Eclipse, the project included in the zip file is an Eclipse project, however, I am sure it's easy to create a project file for any other IDE that uses WTK.
To edit/change/compile the application simply download the zip file provided below, then unzip it in a folder (keeping the directory structure) and then point Eclipse to that directory when creating a new project in Eclipse. Building the sources should be done automatically every time you change the file (well, at least that's the way I've set up my Eclipse instance). Once you are happy with your application, simply right-click on the project itself in Eclipse and select J2ME --> Create Package -- this will create a jar and a jad file in the deployed directory which then you can upload on your mobile.
Important note regarding compiling the sources: Please make sure that when you compile the sources, the .class files are generating using compliance level 1.1, as J2ME is still JDK 1.1 compatible! Setting your compliance level to a higher value (e.g. 1.5) will create code that your mobile cannot run.

Customizing the Application

If you have already run the application, you have noticed that at startup it presents a menu with all the conversions it offers -- each such menu item has an image shown on the left. These images are stored in the source directory under res/img/ folder. The images' names are self-explanatory (e.g. thermometer.png is the image for temperature conversion, speed.png is the image for speed conversion and so on. Simply replace the images with some others that you find more suggestive, recompile the application and deploy (see above) and you're done.
In terms of GUI that's the basic customization you can do with this application.
Of course, you can change the Form that shows the main menu and make it show larger images or add some cool effects if you want -- but for that you will need to actually change the code.Personally, I prefer relying on the J2ME standards, which offers compatibility with a wide range of devices -- but if you do go down that route and manage to change it, feel free to contact me about it with the list of devices you have tested it on and your changes and I'll be glad to incorporate those changes in the app.
One last thing: at the moment, the application limits the maximum number of characters per field to 20 and maximum number of decimals shown to 10. You can change these values though by changing the constants MAX_CHARS and MAX_DECIMALS defined in the class ProviderInput.

Expanding the Application

If you are seriously thinking about getting your hands dirty with this application code, then there are some other "customizations" you can do -- like expanding the application with your own convertor. Here is how:
If you look in the source directory of the application, you will find out that the app is split (as much as possible) in 2 layers: business logic (all the classes under liviu.tudor.convertor.provider package) and GUI/user interaction (all the classes under liviu.tudor.convertor). The ConvertorMidlet is the main midlet application which invokes at startup ConvertorDisplayable. This is the main menu screen, which shows a list of all the convertors in the system. At the moment, this list is hardcoded into PROVIDERS array, member of the ConvertorDisplayable, and it contains all the convertors in the system.
A more elegant solution would have been indeed for the system to actually detect dynamically at startup all the providers in the system, but unfortunatelly, J2ME doesn't offer yet a reflection and introspection mechanism so this was the only way I could think of to do this.
You will notice that that all of the convertor classes are instances of the ConvertProvider interface. The GUI only communicates with the business logic layer via this interface (remember the GOF rule that says "always work at interface level"? :-)
So if you want to implement your own convertor and add it to the application, you will have to write a class that implements this interface. If you look at the code, you will find that the JavaDoc comments explain the meaning and use of each such function in the interface.
However, your average conversion follows typically this rule:

U1 = K * U2

where :

• U1 is the unit measure we convert to
• U2 is the unit measure we convert from and
• K is a constant

In other words, your typical conversion is simply multiplying an unit with a constant. For example, to convert from miles to kilometers, we simply multiply the number of kilometers by 1.60934, so in this case, the formula becomes:

U1 [km] = U2 [miles] * 1.60934

i.e to find how many kilometers is 10 miles (U2), we multiply them by 1.60934 (K) and find our answer: 16.0934 (U1).
In such cases, it doesn't make sense to keep implementing the conversions function defined in ConvertProvider all the time, as we will have to keep an array of all the K values etc. For this purpose, the ConvertProviderAdapter class is provided, which makes it easier to implement a class with such functionality.
So if you want to implement a class that follows the above formula of conversion, here is how:

1. Chose a name for your conversion class -- say, for the above example, if we want to convert miles to kilometers (distances), let's call it DistanceConvertor.
2. Declare your class to extend the class ConvertProviderAdapter
3. Chose a reference unit -- say kilometer. We will express now all the other units in reference to this one. In the constructor of this class, use the addField function to add this as a reference field (note that a reference field will always have the value of 1!):
   addField( "Km", 1, true );
4. Still in the constructor, add all the other units you want to convert to/from, and their corresponding value in Km (since this is the reference unit we have chosen above). For example, a mile is 1.60934 Km, so we would add this line:
   addField( "Miles", 1.60934 );
   Note that by default, unless adding the third parameter and setting it to true, the function will consider that the unit just added is not a reference unit.
5. If your application has to do any checks on values entered by the user, then implement the function checkValue(int,double) -- where you should do your check and throw an IllegalArgumentException if the entered data is wrong. (For instance, we might decide that we can only convert positive values etc.) If you do not need to perform any checks in your code, simply add this function with an empty body. (Note that you will have to implement the function anyway, since it's declared as abstract in the base class!)
6. In terms of functionality, really, that's it -- the base class will handle the rest for you. However, you will need to implement a few other functions meant for the presentation layer (GUI) -- such as: getName (to define the text that will be shown in the menu next to your conversion class), getImageName (to define the image to be shown in the menu next to your conversion class) and getInfo (to show some information about the conversion class when the user choses Info from the menu -- such information can contain the author, version, measure units it provides etc).
7. Having implemented all this, do not forget to add an instance of your class to the PROVIDERS member of the ConvertDisplayable class and that's it!

When you recompile the application and run it, you will notice that your conversion will appear in the list with the name and the image you have specified and selecting Info from the menu will bring up the information you have defined about it!
For more details about this method of extend the application, have a look at some of the classes provided in the package, like DistanceConvertor and AreaConvertor.

Implementing Advanced Formulas

The above scenario works fine for linear formulas of type:

U2 = K * U1

as described before. However, when implementing more complex formulas, this approach is not going to work. For instance, consider the conversion from Fahrenheit to Celsius:

Celsius = (5/9) * (Fahrenheit - 32)

You can scratch your head as much as you want, you won't be able to fit it in using the ConvertProviderAdapter class and the method shown above. In such cases, we have to simply implement a class that just implements the ConvertProvider interface and for each type of conversion implement a function that does the conversion and returns the value and then store these values and return them to the caller. In other words, we have to implement the whole internal stuff that is handled for us in the ConvertProviderAdapter class. There are numerous ways of doing it, but for a quickstart, look at the implementation of the TemperatureConvertor class which does exactly that.
You will notice that we use an internal interface (Computor) which provides just one simple function to convert from an unit to another -- so it takes a double and it returns a (converted) double. Having defined functions for each type of conversion, we then store them in a 2D array, such as position (i,j) stores an instance to Computor that will convert from unit i to j.
Having set up this infrastracture, simply all we have to do when setFieldValue() is called is to call all the function on row index, where index is the index of the field passed in setFieldValue().
Again, the JavaDoc comments in this class are self-explanatory and will help you understand what's what inside it, but pretty much that's it. I might get around to actually implement an adapter class for this method to make it as generic as ConvertProviderAdapter but do not hold your breath for it just yet!
Now, if you follow this method or the one above and add an extension to this application which you want added to the main package, use the contact page and let me know and I'll be glad to add it and give you credit for it.

History

The current version of this application is 1.1.1 and as it stands at the moment I am not tracking previous versions to that. It's very likely that if I decide to maintain this project in the future I will only keep the latest version, however, if at some point I will provide downloads for previous versions as well then the Downloads section below will contain links to all the previous versions of the project.

• Version 1.1.2 NO_IMAGE (released 13/Feb/2007) is the same a version 1.1.2 except that it doesn't include any of the images in the jar file. This is due to the fact that a few of you have signalled the fact that on non-Sony and non-Nokia mobiles (Simenes CX65 seems to be on top of the list definitely -- thanks, Francesco!) the icons appear too big and mess up the whole display. So from now on, I will be releasing 2 versions each time: one which contains the image (the standard release) and one with no images. You can find the links for both versions below.
• Version 1.1.2 (released 09/Jan/2007) is exactly the same version as the previous one (1.1.2) but it fixes the problem with the icon for the application and for Distances being too big and causing displaying problems on some phones. This is something that I noticed for a while but I just needed someone to signal it -- thanks, Mark Naudi!)
• Version 1.1.1 (released 12/Nov/2006) is pretty much the same as version 1.0.3 as it turns out that I cannot downgrade this application actually to CLDC 1.0 as this API does not support floating point operations! Due to this, it is not possible to provide precise conversions from one unit to another -- which is the whole purpose of the application. I will be updating the entries on getjar.com to reflect this problem such that users of the likes of Motorola RAZR will be informed they can't use this application on older models which only support CLDC 1.0. Many thanks go again to Michael Pienaar for his feedback throughout these few releases when I was trying to figure out why it wouldn't work on his mobile!
• Version 1.1.0 (released 11/Nov/2006) is just a recompile of the application using the CLDC 1.0 API this time, as it was signalled by some users (thanks, Michael Pienaar!) that this application was not working on Motorola RAZR (which still uses the CLDC 1.0 API). Hopefully this should fix it and all the Motorola users should now be able to run this app.
• Version 1.0.3 (released 23/Sep/2006) is just an update to the Volume Convertor section, after I have received a couple of emails informing me that the conversion to and from barrels (US) was wrong. Having done some reasearch about this, it turns out that indeed there are different values for US barrels and the one I was using was what is known as federal US barrel. So having found that, I have added the other values as well. Thanks, Kumoro!
• Version 1.0.2 (released 26/Aug/2006) fixes a bug with formatting the values, where the number resulted from a conversion was too big to fit in the field and the JVM was throwing an error thus preventing the application from working correctly. Now, each value shown is truncated to the correct number of characters if too long.
• Version 1.0.1 (released on 15/Aug/2006) is basically the same as Version 1.0.0 but this time I had compiled it with Sun's (previous) WTK 2.1 -- rather than WTK 2.2 which I use normally. This is due to a few messages that signalled the fact that it didn't work on their (fairly recent, MIDP-2.0 and CLDC-1.1 compatible) handsets. Fingers crossed, this might make a difference.

Download the application (jar).
Download the application descriptor (jad) -- please note that this usually will also kick off the process of downloading the actual application if you access this link from your mobile.
Download the application project (binaries and source code).
Read our download disclaimer.

Download the NO_IMAGE version (jar).
Download the NO_IMAGE version application descriptor (jad) -- please note that this usually will also kick off the process of downloading the actual application if you access this link from your mobile.

Note that this application is also hosted on getjar.com, so if you prefer you can download it from there, by using this link (link will open in a new window).

Go back to the J2ME page.

Go back to the Technical page.

Go back to the main page.