Balia is not like another swing based widgets suite. A window built with baila maps data to widget and automatically shows the right data in the right widget. Baila also contains a user input checker, showing appropriate error message to the application user if needed. Using Baila for UI development reduces twice the "Hand Written" code! Baila does not map the database, Baila is a full 3-Tier complient (persistance layer independence).

Screenshots

Baila beans

Baila beans customizer used for UI mapping settings

Widgets hierarchy for a frame using Baila

Baila User's Guide

Packages

Class diagram

For more information, read hereafter and consult the generated javadoc documentation.

Files

Baila is a single JAR file named "Baila.jar".

Requirements

Baila run on JRE 1.1.5 and upper.
For earlier version than JRE 1.2, Swing 1.0.3 (also known as JFC 1.1) is required.
For development, a java beans capable IDE is required.

Adding Baila to an IDE

Each java beans capable Integrated Development Environment can import JAR files to it’s own java beans library. Each imported java beans can be shown in the java beans palette of the user interface IDE.

For example, with Visual Café, the menu "File – Add component to the library" let the user choose the "Baila.jar" file. The IDE usualy shows the new added java beans as described below.

Visual Café component library with Baila widgets

From this window, the user can add all the Baila java beans in the IDE’s widgets palette. This makes available Baila widgets as all other already available widgets.

Visual Café component palette with Baila widgets

Now, your IDE is ready for building applications using Baila.

Building an application with Baila

Most IDE uses projects for building applications. The project defines source code files, archive files used, the "public static void main(String args)" start class (or HTML start page for applets) and application parameters if needed.

Creating a project using Baila

As all archive used in an application, the "Baila.jar" file must be declared in the application project at design time (most IDE add it automaticaly if needed).

A Baila application must starts with the Baila Application Starter, it’s full class name is " com.activebean.baila.ABBailaApplicationStarter". An Application Starter requires two parameters :
- the first window to show (full class name)
- the path for the property file of parameters (usualy "parameters.properties"). This path can be an URL pointing to a remote and shared parameters file on a web site. If the parameter file is local, it must be deployed with each client application.

For example, the command line for the Baila sample application is :

java com.activebean.baila.ABBailaApplicationStarter com.activebean.samples.crm.SearchPersonFrame parameters.properties

Note : In the example above, there is no carriage return but only a space after "ApplicationStarter".

Building windows with Baila widgets

Baila are used as standard Swing widgets. The developper can mix Baila widget and non Baila widgets with only one restriction : for automatic data mapping, a Baila widget must be added into a Baila container widget (ABFrame, ABPanel, etc.). Baila container widget can contain non Baila widgets.

Mapping setting

Instance mapping

The very first widget who have to map a value is usualy an ABFrame. The mapped value to show is usualy created or selected from a database or a file. When this value is in memory, the developer can use a code who looks like the example below for enabling automatic data mapping.

Person p = getPerson(sId); // gets data from a persistance server// "this" is a ABFrame (who can be without any mapped value)this.showAsChild(new CustomerFrame(),p);

Here a CustomerFrame automaticaly shows the person "p", "p" fields are automaticaly mapped with the CustomerFrame Baila widgets.

The following code works outside an ABFrame.

Person p = getPerson(sId); // gets data from a persistance server
CustomerFrame f = new CustomerFrame();
f.setMappedValue(p);
f.setVisible(true);

Field mapping

The MappedName property let the developper chose which business instance field have to map with the currently selected widget.

Visual Café property list for a widget named “ABTextField1”

In the example above, the widget ABTextField1 will map with a field named “name” (property “MappedName”).

Mapping Customizer

Each ABFieldMapper widget (ABTextField, ABCheckBox, etc.) can be can be easily customized from the Baila Mapping Customizer available when the user select the "customize" property from the property list.

Baila Mapping Customizer

Recursive Mapping

Mapping is automaticaly recursive between "ABInstanceMapper" widgets using the "this" MappedName. The recursive mapping is broken if one of the widget container is not a Baila widget container (a standard Swing Jpanel for example).

For example, the following "CustomerFrame" makes recursive data mapping :

CustomerFrame widgets hierarchy

In this example, "tabCustomer" and "pnlCivilStatus"  widgets MappedName are both set to "this", "address" widget MappedName is "address", etc.

Recursive mapping is broken when a non Baila widget container (a java.awt.Container not implementing " com.activebean.baila.ABInstanceMapper") contains a Baila widget. The developer can use a code who looks like the example below for linking an isolated Baila widget with a Baila widget container.

BailaContainer.addABFieldMapper(isolatedBailaWidget);

Updating memory value with UI value

The developer get an automaticaly updated instance from an ABInstanceMapper (ABFrame, ABPanel, etc.) with a code similar to the sample below :

// p is initialized with the Person mapped in the CustomerFrame
Person p = aCustomerFrame.getMappedValue();

Checking UI value

The property "Requirement" let define if this widget must be filled or not, if it had to contain a number, a date, a boolean, etc. For requirement setting, use the "Mapping Customizer" described below.

The "NullWhenEmpty" property let the developper choose if the mapped instance field should be set to null when the widget is empty.

If the requirement isn’t satisfied when the ABInstanceMapper (the widget container) gets the mapped instance value, an error message box is automaticalty shown to the user. This message box shows the message identified by the "ErrorMessageCode" property.

Baila parameters properties file

The parameters properties file is given to the Baila Application Starter at application starting as a command line parameter or as an applet parameter, depending on the running mode.

The parameter file is defined by a full or relative local file or by an URL pointing to a remote and shared parameters file like in a web site for example.

Note : If the parameter file is local, it must be deployed with each client application.

Requirement error messages are defined in the "parameters.properties" file like in the sample below :

#
# Message catalog
# (use the ErrorMessageCode property of Baila widgets)
#
msg.-1=bad value
#msg.0=message 0
msg.1=required value
msg.2=bad number format
msg.3=bad date format

The date format used for date checking in Baila widgets is defined in the "parameters.properties" file like in the sample below :

#
# Date format
# for more information, see java.text.SimpleDateFormat
#
DateFormat=MM/dd/yyyy

For work group, ActiveBean advise to share this file with a version control tool like CVS. For localisation, ActiveBean advise to use another parameters properties file with all needed converted values (messages, date format, etc.). This means that a part of the localisation is managed at deployment time.

Child window closing event notification

The user can detect a child frame closing event overriding the childClose method on the parent ABFrame calling the child ABFrame.

public void childClosed(Frame child)
{
    // the child frame (a CustomerFrame) is closed
    Person p = child.getMappedValue() ;
}

Customizing mapping code

To customize memory data update, the developper can override the "getMappedValue()" method on the needed ABFrame subclass like in the example below.

public Object getMappedValue()
{
    // super method callbefore
    Object uiData = super.getMappedValue(); 
    … // developper specialization code goes here
    return retData; // retData is the developer customizing result
}

To customize UI update, the developper can override the "setMappedValue()" method on the needed ABFrame subclass like in the example below.

public void setMappedValue(Object data)
{
    … // developper specialization code goes here

    // custData is the developer customizing result
    super.setMappedValue(custData); // super method call after
}

Managing data mapping in ABCombBox widgets

Like all Baila widgets ABCombox can map every "java.lang" class type. It had to be filled before any mapping with all possibles "toString()" resulting values.

For example, if an ABComboBox had to map with a "java.lang.Integer" field, it must be filled before with "1", "2", "3" items. If the mapped field contains an Integer value that didn’t match (with a "toString()" ) with any ABComboBox items, the data mapping will not work.

Note on using ActiveBean Tool Library with Baila

The ActiveBean Tool library ("com.activebean.tool" package) is used by Baila, check the Tool library documentation, lots of functionnalities are assumed by the Tool library.

Do not use Baila with a different version than the one already included with Baila archive. For more information on ActiveBean Tool library.

Managing arrays

Automatic Array mapping are managed in the Baila v1.1.0 version. For older versions, ActiveBean advise to use a Swing JTable to select an array element like in the "SearchPersonFrame" from the "Crm" sample application. The selected element can then be shown and modified alone with Baila single element automatic mapping.

Baila v1.1.0 manage automatic array mapping with the "ABArrayPanel" widget. This widget contain a control bar, an optional list, and an optional custom panel.

In the example above a ABArrayPannel widget is showing the second of the two contracts contained in the array of contracts. The ABArrayPanel is set to show the optional list (with contract label, type, state and state date), the optional zoom button and a custom panel showing the current contract n°, type and creation date.

Array Element Class

An array can contains differents type of elements (for example a contract array can contain an insurrance contract and a subscription contract defined in differents sub-classes of contract).

For this reason the ABArrayPanel contains the "ArrayElementClass" property. This property defines wich elements of the aray are allowed to be mapped in the ABArrayPanel.

The "ArrayElementClass" property is usefull to filter elements to show in a ABArrayPanel. For example it is possible to map the same a contract array with two ABArrayPanel widgets in the same window. One ABArrayPanel widget will show, add, delete and update insurrance contracts and the other ABArrayPanel widget will do the same thing for the subscriptions contracts on the same array of contract.

If no class are defined in this property, the ABArrayPanel will not show any array element and consider the mapped instance as a simple business object.

Control Bar

The ABArrayPanel widget contains a control bar with :

• a title, defined in the "Title" property, to describe what is shown in this ABArrayPanel

• an index, to describe the current element and how many element are managed in this widget

• add element and delete element buttons, to add or delete elements in the mapped array. Before deleting the current element, an optional user confirmation can be done. The message displayed to the user for this purpose is defined in the "ConfirmDeleteMessageCode" property.

• next element and previous element buttons, to select the current element or to show each element one by one in the inner custom panel

• zoom button, to show the current element in another window defined by the "ZoomWindow" property. If no zoom window is defined, this button does not appear.

Array element updates are performed automatically when :

• the ABArrayPanel show another element instance (previous, next, add or delete button click)

• the program call the "getMappedvalue()" method (usualy in response of a user save request)

Inner customizing panel

ABArrayPanel widget can be customized with an inner custom panel as in the example above. To specialize this widget add a ABPanel with a MappedName set to "this" and the "Placement" property set to "Center" (layout is forced to BorderLayout).

The widget hierarchy below shows the "contracList" widget (the ABArrayPanel widget) containing a contractDetail (the custom ABPanel with the "MappedName" property set to "this" and a "Placement" property set to "Center").

Optional list widget

The optional list is available if the "ListMode" property is set to "True". This list is not editable and unsorted.
The optional list widget is customized by the following properties :

• ListColumnsMappedName : fields of array elements to show in the list

• ListColumnsTitle : title for each column of the list

• ListColumnsWidth : width for each column of the list

• ListRowCount : the number of rows to show in the list

• ListRowHeight : the heigth of each row in the list

• ListColumnFormat : the format used in each column to display associated array element field.
  This format depend of the field type mapped in the column. For a enumeration value, it can be the enumeration format (see "Managing enumeration values") or a java.lang.MessageFormat pattern.

In the example above, the first and third columns have no format, second column use the "short" format defined for contract type enumeration, and the fourth column use a "MM/dd/yyyy" date pattern.

For more information, read the generated javadoc documentation.

Managing Enumerations Values

Approximately 50% of business object fields are enumeration values (contract type, person gender). Considering this, Baila v1.1.0 and newer versions includes an enumeration manager engine. Baila also contains widgets with automatic enumeration values filling.

For example Baila combobox and list widgets (ABComboBox and ABList) will automaticaly be filled with all values available for the enumeration type of their mapped field.

In Baila, an enumeration instance is a subclass of the "com.activebean.enumeration.ABEnumeration" class. Each enumeration instance contains a type (the business class name) with a limited list of valid string values. Each string value is associated with an integer code. This enumeration code is used for comparison and persistance purpose.

Enumeration Properties File

Enumeration values are stored in a enumeration properties file (usualy named "enumerations.properties") defined by the "EnumerationFile" parameter of the Baila Application Starter "paramater.properties" file.

You can see an example of Enumeration File declaration in the parameter properties file below :

#
# Enumeration properties file (full or relative local file, or full URL)
# (usualy named "enumerations.properties")
#
EnumerationsFile=enumerations.properties

Note: For work group, ActiveBean advise to share this file with a version control tool like CVS. For localisation, ActiveBean advise to keep the same enumeration properties file and use the "#format" tag for enumeration values. If enumeration file is local, it must be deployed with each client application using Baila.

Creating a new enumeration

The creation of a new enumeration needs two steps :

1. create a business class for the enumeration (make an ABEnumeration sub-class)

2. define associated enumeration values (add a property in the enumeration properties file)

To create a ABEnumeration sub-class, copy an paste the following code and replace text in bold with the new enumeration name and/or package :

package business.package;

/** ABC Enumeration */
public class ABC extends ABEnumeration
{
    /** @return ABC enumeration name "business.package.ABC") */
    public static String getEnumerationName()
    {
        // defines enumeration name stored in enumeration file
        return "business.package.ABC";
    }

    public ABC() throws ABUnknownEnumerationException
    {
        super(getEnumerationName()); // default enumeration value
     ^}

    /** build a "ABC" ABEnumeration with a given value
        * @param pValue the required value
    */
    public ABC(String pValue) throws            ABUnknownEnumerationException,
ABUnknownEnumerationValueException
    {
        super(getEnumerationName(),pValue);
    }
}

ActiveBean advise to store enumeration classes in the same package of the business object(s) declaring it.

To add a property in the enumeration properties file, add a new line in the file as in the example below :

# ABC enumeration values (A is the default value)
business.package.ABC=A;B;C;D;E;F

In this example, each enumeration value is separated by a semi-colon ";". Each value is associated with a code value : the first value is for the code 0 (the default value), the 2^nd value is for the code 1, etc.

For no default value, leave blank the first value item like in the example below :

# ABC enumeration values without default value
business.package.ABC=;A;B;C;D;E;F

Each enumeration can have a format tag ("#format" at the end of the enumeration name), allowing to display differents values for the same code. The format tag is usefull for localisation.

You can see an example below :

com.activebean.samples.business.ContractType=Unknown;Sales;Rental
com.activebean.samples.business.ContractType#short=?;Sls;Rent
com.activebean.samples.business.ContractType#fr_FR=Inconnu;Vente;Location

Most IDE contains a localisation tool allowing developper to choose any property value for any widget. To localize UI with Baila enumeration mapper widgets, use the format property.

Using enumeration values in code

Enumeration values can be used in business method code to create or compare an instance of enumeration with a given value. You can used the sample code below as an example :

try {
    // creation example of a "Sex" enumeration with the value "FEMALE"
    aPerson.sex = new Sex("FEMALE");
    // comparison example (is this person a male ?)
    if(aPerson.sex.equals(new Sex("MALE")) { ... }
} catch(Exception e) { e.printStackTrace(); ... }

Note: ActiveBean strongly advise to not refer to formatted values in business code method, this will cause problem for further localisation purpose. Use only default format values or manually defined "public static final" values.

Business objects are usually stored by a persistance layer like a database, ActiveBean advise to store enumeration values using the associated code. You can used the sample code below as an example for a JDBC layer :

// database examples (table "Person" contain a "sex" column of type "number")
aSQLStatement.executeUpdate("update Person set sex=" + aPerson.sex.getCode + ";");
aPerson.sex.setCode(aSQLResultset.getInt("sex"));

Mapping enumeration with Baila widgets

Baila widgets enabled to map with enumeration values (widgets implementing the ABEnumerationMapper) are ABComboBox and ABList.

An ABEnumerationMapper widget will automaticaly be filled with all values available for the enumeration type of the mapped field. This means that the mapped field can not be null.

For this reason all enumeration values have an "unknown value code" (-1) and a "default value code". Depending on business object with enumeration field needs, the business object constructor must set all it's enumeration fields with at least a unknown value code like in the example below :

aEnumeration.setCode(ABEnumeration.UNKNOWN_VALUE_CODE);

When a widget map an enumeration with a unknown value code, it display the ENUMERATION_UNKNOWN_VALUE defined in the enumeration properties file as in the example below :

#
# unknown enumeration value
#
ENUMERATION_UNKNOWN_VALUE=<unknown>

ABList widget is a Swing JList sub-class, this means that it must be in a ScrollPane to show a vertical scroll bar if needed. A ScrollPane is not a Baila widget container and this breaks recursive mapping for ABList widgets. To resolve this problem, bind the isolated ABList widget with a call of addABFieldMapper() from the associated Baila widget container. You can use the following code as an example :

/* manually bind the ABList contractType
 * with the ABFrame "this" because ScrollPane
 * break the recursive mapping
  */
this.addABFieldMapper(contractType);

For more information, read the generated javadoc documentation.

Enabling Baila Traces for Debug

Baila traces can be set to help developper to resolve problems like unmapped widgets.

To enable Baila trace in standard output (Java console), add a property named "DebugBailaMapping" and set it to "True" in the Baila parameters properties file, like in the example below :

#
# Baila mapping debug traces flag
#
DebugBailaMapping=True

A log file can be created to store all Baila traces. To define this log file, add add a property named "LogFile" and set it with a full or relative local file in the Baila parameters properties file, like in the example below :

#
# log file use to save
# ABTracer traces and exceptions
#
LogFile=crm.log

The created log file will contains information like this one :

LogFile created at 27/10/00 17:41.

- com.activebean.baila.ABSimpleInstanceMapper.setMappedValue : field 'name2' not found in class com.activebean.samples.business.Customer, no mapping made for this field (tflt=10880) (date=27/10/00 17:41)

Those traces are managed by the ABTracer tool from the ActiveBean Tool Library and it's subclass ABBailaTracer from the Baila class package. For more information in traces read the generated javadoc documentation.

Deploying an Application using Baila

In a stand alone application the Baila archive must be declared in the "CLASSPATH". For example, in Windows, use the DOS command :

set CLASSPATH=.\Baila.jar;%CLASSPATH%

For applets, the "Baila.jar" file must be declared in the "ARCHIVE" parameter of the "<APPLET>" tag. For example in this HTML sample :

<applet archive="Baila.jar,App.jar" code="com.activebean.baila.BailaApplicationStarter">…</applet>

If parameter properties file is not shared by all client programs (in a web server for example), it must be deployed in all client program hosting machines. The parameter properties file is defined in the program command line or in the "<applet>" html tag as an applet parameter.

If enumeration properties file is not shared by all client programs (in a web server for example), it must be deployed in all client program hosting machines. The enumeration properties file is defined in the parameter properties file, in the "EnumerationFile" property.

If application manage localization, please check that :

• there is parameter properties for each locale version

• the same enumeration properties file is used, and contains, for each locale, the associated formatted values list ("#format" tag).