Diamond Powder for NetBeans

Last year, i have created a NetBeans plugin to an interesting framework, called Diamond Powder, it was developed by a friend of mine, Renato Bellia .
To explain what Diamond Powder is, i´ve extracted a briefly introduction from his blog,

What is it ?

It's a Java ME framework to quickly build data collector forms. Further, it is able to manage the persistence of collected data into RMS records.

Data Collector ?

It is about user input.

Suppose you develop a MIDP application that helps car drivers to maintain records about fuel consume in his/her car: The driver stops by at the gas station and gets his mobile device to take note about odometer value, supplied fuel amount , price of fuel, gas station name, and the current date. Later on the driver needs to recover such data. This is a data collector, and Diamond Powder can help you to do so.

Your MIDP application could go further, doing some math with such data, plotting charts, sending it over the internet and the like, but this is up to you.

How does it work ?

Read this step-by-step and the glossary bellow:

1. Define a Schema
2. Create a Collector suppling with a display, a schema and a flow name
3. Add regular LCDUI commands to the collector
1. at least an OK Command, and a BACK Command
2. other Commands can be provided
   
4. Swicht the MIDlet display to the Collector
5. At the end of Colletor´s job you may persist collected data with a StorageManager.
   

Glossary:

term	definition
Schema	A Hashtable that describes the data collector fields, and its organization. A schema contains a name, a version number, and at least one Flow.
Flow	A sequence pages that the application user can browse through.
Page	A top level field container, to display to the user, as a data collector step. Can be reused among flows. Can be associated with a help screen.
Field	Regular LCDUI items: StringItem, TextField, DateField, ChoiceGroup + Filter : a special component to deal with huge ChoiceGroups
Collector	A collector manages the display of a Flow of Pages, and gathers all user input. It extends LCDUI Form.
StorageManager	It is the Diamond Powder persistence component. It helps to preserve user input data gathered by a Collector into RMS records. It also helps to restore a Collector with previously saved RMS records.

NetBeans Plugin

Now, it´s time to talk about my collaboration in this project, if you get a look at this framework, you will realize that it simplifies a lot the development of a data collector on java me.

On the other hand, the heart of the framework, the "Schema", as stated in the glossary, it is a Hashtable that describes the data collector fields, flow, name and version of your application. Let´s see on listing 1, a snippet of the schema code from the hello world example, extracted from diamond powder blog.

public Hashtable getSchema() {
Hashtable schema = new Hashtable();

//schema declaration: name;version
schema.put("schema", "fuelControl;2");
//flow declaration: page1;page2;...
schema.put("flow.basicRecord", "numbers;extra");
//page declaration: title;field1;field2;...
schema.put("page.numbers", "The Numbers;date;odometer;fuelAmount;fuelPrice");
schema.put("page.extra", "Gas Station;gasStationName;gasStationBrand");
//help for page: help text
schema.put("help.numbers", "Enter the odometer mark, the supplied fuel amount and the fuel price");
schema.put("help.extra", "Enter the gas station name and brand");

//text field declaration: field type;label;size;mask
schema.put("field.odometer","textfield;odometer;6;numeric");
schema.put("field.fuelAmount","textfield;fuel amount;5;decimal");
schema.put("field.fuelPrice","textfield;fuel price;5;decimal");
// dateField;label;{date|time|date_time}"
schema.put("field.date","datefield;when;date_time");
schema.put("field.gasStationName","textfield;gas station;40;initial_caps_word");

//choice gorup declaration: field type;label;list model;mode
schema.put("field.gasStationBrand",
"choicegroup;brand;allBrands;exclusive");
//list model declaration: value1;label1;value2;label2;...
schema.put("listmodel.allBrands",
"999;undefined;1;Atlantic;2;Chevron;3;Esso;4;Texaco");

return schema;
}

Listing 1: Schema method example.

As you can see in the example, it can be a problem if you want a more complex application, as your schema evolves it can became inconvenient and error-prone, as you add more fields, or even new pages.
Diamond Powder for NetBeans it´s a plugin, that comes to fill this gap, and helps to create a Schema code, avoiding spelling error in variable names. Now let´s see how to install it.

Download and Installation
To install Diamond Powder for NetBeans, you can visit plugin Portal on NetBeans website, or you can download it directly from java.net site project. The easiest way to download it, is directly from NetBeans,
To install DP from NetBeans, select "Tools > Plugins", open the Setting category and click Add button, in Name field enter "Diamond Powder", and URL enter "https://diamond-powder.dev.java.net/files/documents/9072/108868/updates.xml", and click OK to create a new Update Center source.

Figure 1: Configuration of Update Centers.

Now, to install the plugin, select "Available Plugins" category and install the Diamond Powder plugin, during instalation it will generate a warning, stating that the module is not signed, but it´s ok..

Generating the Schema
There are two ways to create a schema, creating a new file, selecting "New File > MIDP > Diamond Powder - Schema Generator" from a Java ME Project, or you can invoke Diamond Powder wizard from the source code editor, selecting menu popup "Refactor > Diamond Powder - Schema Generator"..

Figure 2: Creating a new Schema file

Start by creating a Diamond Powder Schema file, as shown in Figure 3. Let´s create the schema defined in listing 1, so name the schema "fuelControl", set version 2 and click next to go the panel shown in Figure 4:

Figure 3: Naming the Schema file.

Here we can define our application fields, , let´s define the odometer, fuelAmount, fuelPrice, date, gasStationName and gasStationBrand. Note, that for gastStationBrand is a choicegroup field, to define our list values, click the Editor button, and create the list model defined in Figure 5.

Figure 4: Fields Configuration

Enter "allBrands" to List Model and click New Button, to include a value to the allBrands list model, select it in the list and click Add button, to cancel an item just click cancel, and to finish it, close the window.

Figure 5: List Model editor.

In the Pages Configuration step, let´s create our pages number and extra adding the related fields and entering the properly information like page name, title and help, like Figure 6.

Figure 6: Pages Configuration.

Click Next to our final step, now we going to define the sequence pages that our application will browse through. Enter basicRecord for Flow Name, and add the two pages created earlier (Figure 7).
Check the "Save to File?" option and click browser, this option will persist all fields created to an user defined file.

Figure 7: Flow Definition.

Note: You can retrieve these values, loading the file in the Fields Configuration step (see Figure 4).

Click Finish to generate the schema class. After generation, you should see the Java class, Schema, in the hello.schema package.

References:
Diamond Powder (java.net): https://diamond-powder.dev.java.net/
Diamond Powder Blog: http://diamond-powder.blogspot.com/
NetBeans Plugin: http://plugins.netbeans.org/PluginPortal/faces/PluginDetailPage.jsp?pluginid=17094
NetBeans: http://www.netbeans.org/

Try it !!