• 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 forums or the Contact page.
• 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 our forums to let us know

Installation

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. 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://3bsoft.net/download/j2me_convertor.jad

Compiling the Application

If you decide that you want to modify the application, you will need to download the sources. These are provided in packaged in a zip file that contains the whole application project. I personally use Eclipse and EclipseMTJ  plugin to edit the file and compile them. Obviously, these still rely on the presence of Sun’s Wireless Toolkit (WTK)  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 Java Mobile–> 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 net.freebiesoft.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:

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

• Declare your class to extend the class ConvertProviderAdapter

• 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 );

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

• 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!)

• 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).

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

In  the forums section I have added a little thread which goes through the history of this application prior to having it moved to 3bsoft.net: http://forums.3bsoft.net/viewtopic.php?f=17&t=5&start=0

Finally the J2ME Convertor app which used to be hosted under www.liviutudor.com has been moved onto the 3B Software servers and it is from now on available for download from this page. The original page on the old www.liviutudor.com server has been set to perform a redirect to our servers so please update your bookmarks to reflect this change.

The application has started when it occured to some of us (a while back!) that the Sony Ericsson 750i does not seem to include a weight/distance/volume convertor utility. At the time Nokia had such an utility on their phones (and still does!) — 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.In time this has changed and most of the modern mobiles do include a measurement convertor however quite often it does not include a lot of units — which makes them a bit superfluous really

Either way, whether you don’t have a convertor unit for your mobile handset or you need one that supports more units than the one you already have, this application might come in handy.

The application is available for anonymous SVN checkout here: https://forge.3bsoft.net/j2me_convertor/

Or you can download the binaries  here:

• JAd file (for over-the-air installation): J2ME Convertor JAD - JAD file for over-the-air installation of the convertor app
• JAR file: J2ME Convertor JAR - The actual convertor app

or complete with sources here: J2ME Convertor Sources & Binaries - Complete sources for the J2ME convertor and binaries

You will notice that the mobile section and the hotel section of our website are currently offline.This is due to our staged migration of our sourcecode to SVN which is currently in progress, with the software utilities section being the first to be migrated — once this is sorted out and made available to the public, then we move onto the mobile section and finally onto the hotel software. During the migration we expect to occasionally experience SVN/forge downtime — please bear with us throughout this process. An announcement will be made on our website once the full migration is finished — however, expect to see some intermediary updates as we make progress on each section.