DreamBeans® User’s Guide

Copyright © 2002-2007 Konsensys, All Rights Reserved.

DreamBeans® is a US registered trademark of Konsensys

http://www.konsensys.com

Product Version 1.2

Document Version 1.2.4

Chapter 1 Introduction

The DreamBeans® product is a new paradigm of software development.

Traditional Development

Create database Create forms Create code Test

DreamBeans® Development

Create forms Test

As shown in the picture below, DreamBeans® has a "preview" pane allowing you to see changes immediately as you add components to forms and set properties. Next, select the "Run" menu item to test your generated servlet! Unlike other products, DreamBeans® eliminates most of the coding.

Overview

Who really has the RAD (Rapid Application Development)?

Java IDE + Java Server Faces or VB/c# .Net	DreamBeans
Use one tool within an IDE (integrated development environment) to design web forms and another tool to specify database tables.	Automatically creates/imports a database field corresponding to a form field -- saving you time.
Use either a wizard or editor to write a complicated database query. And it is up to you to figure out how optimize the query.	Automatically generates and optimizes database queries for you -- saving you time.
Use an editor to write the "code-behind" that glues multiple web pages into an application and then spend weeks testing and debugging it.	Automatically generates logically correct (first order logic) "code-behind" for you -- saving you weeks of time on larger projects.

Other technology like Java Server Faces, .Net Controls, etc. can not be used to visually construct complete software applications, because those technologies lack the “logic semantics” to express a software application’s behavior in a declarative manner. With other products, you have to write code to “glue” the context of the current data entry form to selections made on previous forms. Further, you still have to use tools to define database tables, indexes, referential constraints, and queries.

In contrast, each DreamBeans® GUI icon corresponding to bean is a syntactic component of a logic programming language. The logic programming provides a fully declarative means of expressing the application logic. Thus, creating a complete software application is as simple as selecting DreamBeans® icons (beans) and setting property values.

The logic programming allows DreamBeans® to automatically generate the application logic (code-behind). This fully visual construction of a program that works right the first time, allows to you focus on "what" you want your application to do, rather than spending time determining "how" to make the application. This visual construction of a program makes DreamBeans® the fastest RAD (rapid application development) and prototyping tool for Java servlets available.

This combined AI + Java development paradigm has several key advantages over the JSP paradigm.

1. Much Faster Development (several times faster development than with JSP/ASP-based tools)

2. Safer (guaranteed logical correctness and guaranteed database referential integrity)

3. Easier Developer Learning/Use (much higher level of abstraction)

4. Easier End-User Learning/Use (generates applications with a more consistent look, feel and behavior)

Warning!!!

DreamBeans® is for “professional” software developers!

If a person clicks on an “Insert” button in your generated application a dialog box will sometimes pop up saying the insert failed because it is a duplicate. Then, you have to determine into which “unique” table field the user attempted the insert and decide if this is a correct guarding condition (e.g., you don’t want duplicate usernames or duplicate product serial numbers) or if your application needs a design change (e.g., remove the “unique” constraint on the table field). On complex applications, an experienced software developer is needed to determine where the problem exists in their design.

Likewise, a “ResultTable” bean may appear to display “wrong” results, when put into a form that contains fields from many database tables. This happens when you have not sufficiently thought through the “relationship” between database tables used in a Form that affects how the database query is generated that populates a displayed table, tree, or chart.

Further, the generated application must run on a Java application server and SQL database. For example, even though DreamBeans® can generate all your database tables, you must first create a SQL database that those generated tables can go into. And you must know how deploy the generated jar file to a Java Application server and also register your application’s “context” with the Java application server.

If you lack the above knowledge and skill, then you should look at other products. For example, FileMaker Pro® and Microsoft Access® come with many template applications that have the “logic” already debugged for you. You can use those template applications as a base that you just customize by adding a field or two, etc. Or you can purchase an off-the-shelf application and customize it.

Picking the right tool for the job

The DreamBeans® product is best for data-intensive, web applications having many data entry forms, tables, trees, graphs, and charts.

Examples of such applications are: customer relationship management applications (e.g., sales tracking, help desk, work order tracking, problem reporting, and defect tracking) and analytic applications (decision support and expert systems).

Chapter 2 Installation

Prerequisites

The following environment must be present to install and use the DreamBeans® technology:

· The generated servlets require Sun Microsystems 1.5 or later JRE (Java Run-time Environment)

· The Windows, Linux x86, and Solaris sparc versions of DreamBeans already contain the 1.5 JRE. However, the MacOS, Solaris x86, or the “Generic” versions require you have version 1.5 or later of Java installed.

· The development environment requires that you have either Microsoft’s Internet Explorer or Mozilla installed, which are used to “preview” your application’s web pages inside the development environment. NOTE: On Linux x86, Solaris x86, and Solaris sparc: you must have the Mozilla browser installed in /usr/local/mozilla. You can NOT use the Firefox browser within the IDE, because the current version of Firefox is not designed to be embedded within another application (Firefox libraries are statically linked).

· Generated servlets are compatible with web browsers that support HTML 4 and CSS 2 (such newer versions Microsoft’s Internet Explorer, FireFox, Mozilla, Netscape, and Opera browsers)

· The DreamBeans IDE requires a minimum of 256MB of memory for itself. Thus, you PC should have at least 512MB of memory.

Download

Download the installer specific to your hardware/OS platform (Windows, Linux x86, Solaris x86, Solaris sparc, Mac, or “Generic” Unix), from http://www.konsensys.com.

Configuration and Setup

The Windows-based installer is an EXE, which means you can just double-click it to start the installer. On Linux and Unix, invoke the installer using the “sh” command. For example:

sh   DreamBeans_Linux_x86.sh

That’s it! You’re now ready to use the DreamBeans® library in your IDE.

Licensing

You are granted a binary license subject to the terms described in the DreamBeans installer. If you have installed DreamBeans, then you have explicitly agreed to the license terms. In essence, you can distribute the DreamBeans IDE and run-time jar file without reverse-engineering or modification.

DreamBeans includes software from Sun Microsystems, the Java.net projects, the Apache Foundation, dom4j.org, mortbay.org, w3c.org, and jfree.org.

Chapter 3 Quick Start

The following example will take about 20 minutes to create an application that would take several hours to a day to create using other tools. This quick start example will teach you about 80% of the DreamBeans® language basics. The section following this example will briefly cover the remaining 20% of the basics.

Application Example: Multi-User Address Book

This example will create an address book, with username/password accounts. Because this example is a little complex, it requires a little explanation: The entry form will contain “Login” and “New Account” tabs. The first form displayed will offer the option to login with a username and password. The second form will offer the ability to create a new user name and password.

n “Contacts” form will contain a scrollable table of people’s names and phone numbers. Selecting a row in the table will display more details about the person. Further, this form will have buttons to enter new people/addresses, change existing entries and remove entries.

The first and last name fields will be “sounds-like” searchable. That is, when click on the search button, it will match the first name that “sounds-like” the name you spelled. This feature is useful when you don’t remember the exact spelling of a person’s name.

Okay, let’s get started!

Step 1) Create a new project:  Create a project called “MyContacts”, by selecting the “Project | New…” menu item, as shown in the picture below:

Fill in just the wizard fields specifying the name of your project, “MyContacts” and where you want your project located. You will next see a dialog box displayed with a number of fields defining the application to be created.

Step 2) Create a reusable application object: Use the “New…” button in the project tree pane to display a gallery of components that can be added to a project. Select a “BaseForm” from the gallery, as shown in the picture below:

A BaseForm is a “business object” defining both a data entry form in an application and a base table in a relational database. Adding a data field to a BaseForm adds a field to both a form and relational database table at the same time.  How can this be reusable? For example, suppose you only wanted to display some fields from a table?  DreamBeans® has two unique features that will be shown in the next two steps that make this possible.

Selecting the “BaseForm” will bring up a wizard, where you can type in a name like, “AccountInfo”. The only required fields in the form are “Form name” and “Table Name”. By default, the Table Name is set to the Form Name with any white space characters removed (because some SQL databases don’t like table names that contain white spaces).

When the “AccountInfo” form you just created is displayed in the component pane, set its cascade_delete property to “true”. This tells an application that then when a record is deleted from “AccountInfo” to find all other tables having associated records and delete them as well. That is, if you delete a person’s ID from the database, you also want to remove that person’s phone numbers, addresses, etc. In other words, the deletion of a record “cascades” into deletions of related records in other tables.

Note that this “cascade_delete” property is an ease of use feature that is specified very differently from how cascade delete is specified in SQL databases. In a SQL database, you specify a cascade delete in each dependent (child) table, which can be many child tables. With DreamBeans®, you only specify the cascade delete in one place – the parent table. While the DreamBeans® method isn’t quite as flexible as the SQL method (handle every special cases), it is much easier to use for the common cases. DreamBeans® is designed to make generation of the “typical” application as quick and easy as possible. In contrast, SQL databases have the design goal of handling every special case a business might possibly need, which often makes doing the common things complex and difficult. DreamBeans tries to make the common tasks as simple as possible and

Step 3) Add the fields that define this reusable application object: Click on the “Add…” button in the component pane. This will display a gallery of components which can be added to your BaseForm, as shown in the picture below:

Select a “Text” bean from the bean palette and set the Text field’s property, field_label, to “Username”.

In the property pane, set the Text field’s properties field_value_required to “true” and field_value_unique to “true” (as shown in the picture below): This specifies that each user will have a unique name and that they must enter a name when they use this form.

Using the same method as in the previous step, add a PasswordField from the bean palette to AccountInfo, setting the PasswordField’s field_label to “Password” and field_value_required property to true. Set the maxCharacters properties of the Username and Password to 32 characters. You can also specify the minCharacters for each field also. If a person types in too many or two few characters into the username and password fields, a dialog box will display an error message.

You have finished creating the reusable application object. Now, we’ll revisit the question of, “Suppose we only want to display some fields from a table”?  When you add a re-usable application object (e.g., AccountInfo”) to an application, you can click on the form_field_properties, which will display a table, as shown below. With this table, you can specify all the important display characteristic of each contained field, including visibility. No other JavaBeans (or VB controls) development tool has this form_field_properties feature that allows you to change the properties of a superclass’s (reusable application) components!

The second unique feature that provides re-usability of a form, as will be shown in the next step, where you can add HTML, buttons, etc. to each instance of the reusable application object. The next step will show how your new application object will be reused twice in this application.

Step 4) Create a header to go at the top of each form:  Select “New…” again and then select Box bean (found under the HTML tab), set its name to “My Contacts Header” and set the desired_position property to 0 (puts it at the top of a Form). Then use the “Add…” button in the component pane to add a “HeaderText” bean (found under the “Text” tab) to the Box and set its content property to “My Contacts”. You can experiment setting various properties like color, style, font family (e.g., Arial, Helvetica, Times, etc.) without having to write any HTML code.

Step 5) Create “Login” and “New Account” forms:  Select the application object, “MyContacts” in the project tree and use the “Add…” button to add a “TabbedForm” and give it some name, for example, “Access Forms”.

Use the “Add…” button two times to add two instances of the “AccountInfo” bean to the TabbedForm. Set the form_name properties of the two added AccountInfo forms to “Login” and “New Account” respectively. Set their content_alignment properties to “CENTER”, which will cause all text and fields to be centered on the page.

Next, add a “My Contacts Header” bean (under the “HTML” tab) to your “Login” and “New Account” forms. To each form add a “PageText” bean (under the text tab), and set the text_content property to something like “Enter you user name and password.” Set the desired_position of each PageText bean to 1.

Add a “ButtonPanel” bean to each form. Add a “DbButton” and “Quit” button bean to each ButtonPanel. Select the DbButton button in the “New Account” form, and set the button_label property to “Add” and set the action property to “INSERT”.

NOTE: If the web page does not display elements in proper positions, click on the “Backup” button. After a couple of seconds the backup will complete. Next, select “Revert”. This will force the time stamp on the generated files to change, which will force Java to recompile the web page.

You have now finished creating forms for logging in and creating new accounts, including the database table, SQL code, and “code-behind” – without writing any code! With the Windows, Linux x86, and Solaris versions of DreamBeans, you will see exactly what the Login form will look like in the “Preview” pane (as shown below).

Note: If you don’t like the colors, etc. you can click on the “Style…” button to change them.

Step 6) Create “Contacts” form:  Select “servletapplication.My_Contacts” (the top level component), and add a “GroupForm” bean. Set the form_name of the GroupForm to “Contacts”. Then select the previously added “DbButton” beans. When you select their form_on_success property, a list of available targets appears. Select “Contacts”. This says that if the “Login” find operation or “New Account” insert operation is successful to go to the “Contacts” form.

Add your “My Contacts Header” bean to the “Contacts” bean you added in the previous step. Next add a ResultTable (found under the “Multifield” tab) to the “Contacts” bean..

Note, the group_layout property in the GroupForm, “Contacts”, is set to “COMBINED”. This will cause all the contained forms to be displayed together (laid out) as a single form. If set to “CARD” then each added Form will be displayed separately. This allows you create a tree hierarchy of forms to display.

Add an AccountInfo bean to the Contacts form. Select AccountInfo’s form_field_properties property, which will display a table of AccountInfo’s field properties. Set all the fields to NOT be visible in the form and NOT be visible in a table.

And sest the editing_enabled property to false. This tells DreamBeans that the AccountInfo table is read-only (not modifiable) in the Contacts form.

Note: AccountInfo is added to the Contacts form to inherit the log-in information entered in the previous form (that is, inherit the context). Any time you want to inherit choices made in previous forms, then you must add the same beans (tables) used in the previous forms to the current form.

Add a ResultTable to “Contacts” (found under the Multifield tab). This will create a scrollable table of your contacts.

Now you have a choice. You either use the “New…” button in the project pane to create a reusable BaseForm or use the “Add…” button in the component pane to create a “one-off” BaseForm. If you are 100% certain that you will never use the form/table anywhere else, you can use the “one-off” version.

In this example, we’ll be lazy and just add the BaseForm beans directly to the “Contacts’ form.. Add a BaseForm to “Contacts”. Set the form_name property to “Person.” And set it’s cascade_delete attribute to true, so that if a person is deleted from the database, and associated phone numbers, addresses, etc. will also be deleted.

Add a Link field to “Person”. Click on the linked_table_name property “AccountInfo” from the list of tables. The BaseForms, “Login” and “New Account”, both have “AccountInfo” as their base table. The linked_table_name property says that the “Person” table is linked to the AccountInfo table. Thus, only persons linked to an account will be displayed. VERY IMPORTANT! Set the link field’s field_value_unique to “false.” This allows multiple records (Persons) linked to the same account. In database speak, AccountInfo is a non-unique, foreign key. Otherwise, after you enter the first person’s data, you would not be able to enter any more person records into the database..

It is subtle database design issues such as uniqueness of link fields (foreign keys), that require a professional software developer. In other words, DreamBeans® is a product to improve the productivity of professional developers – not eliminate the need for the professional developer.

Add a GroupField field to “Person” and set the field_label property to “Name”. A GroupField is a container of other fields. The GroupField groups the contained fields into a single field for indexing (sorting done first-to-last contained field) and layout (horizontal or vertical). Set the field_value_unique property to “true” (specifies that the contained fields combined as a single key is unique).

Add three Text fields to “Name”, and set their field_label properties to “Last”, “First”, and “MI” respectively. Set the field_value_required properties to “true” for “Last” and “First” (but not “MI” because not everyone has a middle initial). Sorting will be done by last name, then first name, then middle initial. On “Last” and “First”, set the field_search_constraint property to “sndx”. This will allow successful search on misspellings that still “sound-like” the desired name. Set the maxCharacters property of First and Last to 32. Set the maxCharacters property and field_column_width property of MI to 1.

Add a BaseForm to “Contacts” and set its form_name property to “Street Address”.

Add Text fields to “Street Address”, “Street 1”, “Street 2” and set the field_column_width property of each to 60.

Add a FieldPanel to the BaseForm, “Street”, set the FieldPanel  layout_direction property to “HORIZONATAL”. And to the FieldPanel add the Text fields “City”,  and “State”. You may wish to set the width of “State” to 2 characters and set the property, case_style, to “Uppercase all”. Set the maxCharacters property of Street 1 and Street 2 to 32. Set the maxCharacters property of City to 64. FieldPanels are used to control the horizontal and vertical layout of your fields. You can nest FieldPanels inside each other to create a custom layout.

Add an IntegerField to the FieldPanel and set the IntegerField’s field_max_value to 99999, field_min_value to 0, and field_column_width to 5.

Add a Link field to the “Street Address” Form and set the Link field’s linked_table_name to “Person”. This Link field indicates that street address table references the person table. That is each person has an address.

Important: Set the field_visible_in_result_table of all the address fields to false. You don’t wan the table cluttered up with too much information. When you click on an entry in the displayed table, it will automatically fill in all the form fields with the details.

At this point, you have learned everything you need to complete the application. If you wished, you could add more BaseForms, such as “Email”, “Phone”, “Important Dates”, etc. to make the application as fancy as you wish.

On every field in “Street Address”, set the field properties sorted to “false” and field_visible_in_result_table to “false.” You don’t want the table to have too much information. When you click on a name in the ResultTable, it will automatically fill all the fields in your form with all the details.

You can add a couple more BaseForms for email addresses and phone numbers. We’ll wrap this up by simply adding the buttons required to make to finish off the demo.

Add a ButtonPanel to “Contacts” and set its field_layout_direction property to “VERTICAL.” Add two more ButtonPanels to the first ButtonPanel and name them ButtonPanel1 and 2. The nesting of ButtonPanels is used to organize the layout of the various kinds of buttons. Add two more panels to ButtonPanel1 and name them ButtonPanel3 and 4.

Add a DbButton to ButtonPanel3, and set its label to “Search”.

Set ButtonPanel4’s  field_layout_direction property to “VERTICAL.” Add two more ButtonPanels to ButtonPanel4. Name them ButtonPanel5 and 6.

Add 3 DbButtons to ButtonPanel5 and label them “Add”, “Change”, and “Remove.” Set their action properties to “INSERT”, “UPDATE”, and “ERASE” respectively.

Add a “Clear” button to ButtonPanel6.

Add a Quit button to ButtonPanel2.

Your “Contacts’ form should like something like the following:

Your are done! You are now ready to click on the “Run” button, which will start up a Java webserver and web browser initialized with the URL of the ServletApplication you just created.

When programming using servlets/JSP (or ASP), you have to: create the database tables with separate tool, referential constraints (such as specifying cascade delete on tables depending on the “AccountInfo” table), and indexes; write SQL queries, create the forms, write session-tracking code, write JDBC code to: access the database, write either Javascript or applets to handle client-side constraint checking on fields, make the tabbed panes work, make the buttons work (search, insert, update, etc.), write more Java code to “link” the username/password account in the previous form to the associated names and addresses in the next form, write code for soundex-based searching. And it all has to be tested and debugged!

This will take a minimum of 4 times longer than using DreamBeans® servlet-beans. Even using a Microsoft Access-like project, you still have to define tables, define queries, define forms, and write macros – taking twice as long as DreamBeans® servlet-beans technology.

The remaining 20% of the basics

In the previous section, you have learned 80% of the DreamBeans® basics: How to create a ServletApplication, create a re-usable object, create forms with text, fields and buttons, navigation between forms, etc. This section of this chapter will cover the other 20% of the “basics.”

Button Placement

As you saw in the Address Book demo above, buttons are placed and organized within a ButtonPanel. Normally, a ButtonPanel is placed anywhere in a top-level form.  A top-level form is a form that is displayed as single page. For example, you might enter information into a GroupForm that contains fields from several subforms. An “Enter” button, at the top-level would add the entered information into each of the contained subforms’s associated database tables.

Field Placement

Every BaseForm contains a FieldPanel, which has a “VERTICAL” layout that positions each added field below the prior field. When you add fields to a BaseForm, the BaseForm adds each field to its FieldPanel.

You can also add a FieldPanel to a BaseForm, which will become nested inside the BaseForm’s FieldPanel. And you can add both fields and FieldPanels to other FieldPanels. By setting the layout of each FieldPanel to “HORIZONTAL” or “VERTICAL”, you can create a custom layout of your fields.

CARD layout

If the group_layout property of the GroupForm, “Contacts”, were set to “CARD”, then the forms “Name”, “Address” and “Phone” would each be displayed as individual pages – each would be a “top-level” form and each may contain one or more ButtonPanels filled with Buttons. With CARD layout, the GroupForm, “Contacts”, would never be displayed (only the contained forms are displayed).

You can nest GroupForms with CARD layout to create a tree organization of Forms. This allows you create a very complex application with a large number of forms with a logical grouping and visual organization.

Scope

You will remember in the MyContacts example (in the previous Quick Start section) that DbButtons have the two properties form_on_failure and form_on_success. These specify the next form to call (visit) depending on whether the database action fails or succeeds. The GotoButton also has a form_target property.

When you select one those properties (form_on_failure,  form_on_success, or  form_target), a list of possible destination forms are shown – but not all forms appear there. That is because some forms are out of “scope”.

1) A form has no visibility into the contents of another form. Like most “procedural” programming languages, the calling procedure has no visibility to code inside the called procedure. Likewise, when a Form “calls” a GroupForm that has a CARD layout, the first Form contained within the GroupForm is displayed (like execution of the first statement within a procedure). Technically, each Form is the predicate of a Horn clause. The above explanation is just an analogy to something familiar to the ordinary programmer.

2) A target form is within scope if it is at the same or higher nesting level of Forms, which is analogous to procedure scope rules in languages that support nested procedures like Pascal, Modula, and Ada.

Fortunately, you don’t have to remember the rules. DreamBeans will only display the in-scope Forms in the list of target options.

In the “MyContacts” example, shown in the picture below, “New Account” is within the scope of the “Login” form, because they are both nested at the same level within the GroupForm, “Access Forms”. And both of those forms have “Contacts” within their scope because “Contacts” is nested one level higher in the tree. However, “Person” is not within the scope of “Login” because it is inside another form.

Context

In the MyContacts example above, each user has their own set of names and addresses – their own context. DreamBeans® determines which names and addresses to display for a user based on the previous “context”. The “Login” form sets the context for the “Contacts” form, which the “Contacts” form determines the context via the “Link” field, named “AccountInfo”.

The current context is the form the end user is currently viewing. Previously visited forms are prior contexts. If the target form of a button (or a form’s goto_on_row_selection property) has already been visited, then the context (stack) is unwound back to that previously visited form. In other words, the DreamBeans® language does not allow “recursion.” This makes the generated applications much more intuitive for the user.

For those familiar with logic programming languages like Prolog, each DreamBeans® Form (context) corresponds to a Horn clause, where fields that do not have constant values are logic variables and buttons are operators. The default group_relation property, LinkJoin, is the logical “and” of predicates in a clause.

The Link field is the means by which DreamBeans® automatically detects the primary and foreign key relationships. When you delete a row (and you set the cascade_delete property of a form to true), then DreamBeans® uses the Link field to find all dependent rows in other tables and remove them as well (preventing “orphan” rows). If the cascade_delete property is set to false, then DreamBeans® won’t allow the row to be deleted if dependent rows in other tables exist (preventing “orphan” rows).

A Link field is a little bit similar to a “SEQUENCE” field in Oracle, an “AUTOGENERATE” in IBM’s DB2, an “AUTOINCRMENT” in MySQL, and “AUTONUMBER” in Microsoft Access, etc. The difference is that Link fields are immutable for the life of a row and not displayed in forms or tables. Their purpose is strictly for setting context.

Important note:  Use the Link field to relate one table to another. Never create duplicate fields across tables. This is a cause of database inconsistencies, where a field is updated in one table but not updated to the other tables. If you only use Link fields and display the linked forms together on a GroupForm, then such database inconsistencies will never occur.

Forms containing fields from many database tables

Suppose you purchased a defect tracking tool, and you customize it by entering your company name and product into some configuration tables. When a person uses your defect tracking tool, your company and product name will appear at the top of every form.

However, when a customer selects the “Insert” button to enter a problem report, you don’t want to have your company and product name fields updated! You just want the customer’s problem data to be inserted. You can set the editing_enabled property to “false” on those BaseForms (tables) that you do not want to be affected by a database operation.

Important note: Setting the form_style property to “Display-Only”, does not set the editing_enabled property to “false.” In the defect tracking tool example above, you might set the current date and generate a new defect ID automatically, which is inserted into fields that are “Display-Only.” You might have display-only fields that have values set by assigning a constant value (via the field_constant_value  property of a form field), a default value (via the field_default_value property of a form field), via calculations (via the field_output property of a CalcField), or date/time field being set to the current time, etc.

NULL values not allowed

One reason other products can not generate the “code-behind” from an iconic specification, is that their semantics are not based on formal logic. If you want to translate a “declarative” (high-level) specification into correct code, then there must be some rules based on a formal system of logic to generate the code.

Horn clause logic is a “decideable” (computable) subset of first-order logic, where all assertions are bi-valued (true or false). Relational logic is subset of Horn clause logic. Thus, relational logic is also bi-valued. There is no known tri-valued (true, false, don’t know -- NULL) system of logic that is computable. Therefore, there is no known means to “compute” correct code for a tri-valued system…

And that is why relational tables containing NULL values are a frequent source of logical inconsistencies in a database. There is no way for a database management system to compute a way to prevent or fix problems, when NULL values are allowed. So, if you want to work at higher-level of abstraction, then you have to be a little more disciplined in your “logic.”

There are two cases to deal with:

1) No value is needed. For example, first name and last name might be required, but the middle initial is optional (not everyone has a middle name). For this case, set the field_value_required property of a form field to false and the default will be used. Another example is a retail store might collect customer information during a sale. Some customers may decline to provide information. The default value for a customer name would be set to “Anonymous”.

2) You only know some of the values at this time. This indicates an insufficiently normalized database. Any time, you have some fields with values you don’t know, those fields should be broken out into a separate table (a separate BaseForm). For example, you might know a new employee’s name, but not yet know the assigned department. The department field should be in a separate table, with a “Link” field to link to the employee table. You can then insert a value into the department table when you find out the assigned department.

NULL values were added as a feature to relational databases by ignorant database designers, who lacked a competent understanding of relational logic. The only reason NULL fields exist today, is for backward compatibility for people accustomed to sloppy database design practices. NULL fields should never be used in new applications.

The database management system from Oracle Corporation is particularly bad (non-relational), because it dose not make a distinction between a NULL field and a field having the value of an empty string. That is, you might want the default value stored in a field to be an empty string – not “I don’t know” (NULL).

This position may seem a little extreme. However, consider that a programmer very rarely looks at the machine code generated by a compiler, because 99.9% of the time, the “bug” is in your own software – not the code generated by the compiler. DreamBeans® is a computer language. And you need confidence that the generated application code is correct. That could not be achieved if NULL values were allowed.

Therefore, DreamBeans® language does not allow NULL values in tables. Before a DreamBeans® generated application inserts a row into table, DreamBeans® checks that all values are instantiated to non-NULL values. For databases like Oracle that do not make a distinction between NULL and empty strings, you must assign some non-empty string as a default value (for example, “-----“).

Using external (foreign) tables.

Most “real-world” applications require accessing data in existing database tables. To access an external table:

1. If you have not already done this:

a. Select the “Project | Properties… menu item.

b. Select the “Database” tab in the Properties window and specify the name of the “external” database vendor, database name, port number, user name, and password.

2. Select an “ImportedBaseForm” from the “New” or “Add” buttons.

3. Set the form_name property of the ImportedBaseForm.

4. Set the table_name property of the ImportedBaseForm by selecting a table from the list of tables in the database.

5. Set the form_field_properties property of the ImportedBaseForm.

The example property editor (above) allows customization of how fields from an external database (an ImportedBaseForm) will be displayed.

Note that the form_field_properties property of the ImportedBaseForm has a couple of extra properties for each table field for specifying how each field is displayed. For example, You must specify if a VARCHAR, TEXT, or STRING data type in the database is displayed as either a “Text” or “TextArea” field in an HTML form. And, for each displayed table field, there is a property to specify the display width.

Note #1: You can not add, change, or remove the fields of an ImportedBaseForm from within DreamBeans. This prevents you from accidentally losing all your data or breaking your other existing applications that depend on existing table definitions.

Note #2: You can not use the “LinkField” to reference an external table, because the external table will probably lack a primary key field (column) having the same name as the table name and having the data type of  integer (long or big int). Therefore, to specify the “link” (relationship) to external tables, you must explicitly specify the “common columns”, using the explicit_common_columns property of a GroupForm, which is a comma-separated list of common columns. For example, “Account.PersonID=Salary.PersonID, Account.PersonID=Department.PersonID” says that the “PersonID” in the “Account” table is the same as the “PersonID” table in the “Salary” and “Department” tables.

Note #3: DreamBeans® does not guarantee the relational integrity of those databases not created by DreamBeans®, because imported databases are not as disciplined in their design as those created by DreamBeans®.

Chapter 4 ServletApplications

Your servlet application will extend javarex.beans.servlet.ServletApplication (which implements the javax.servlet.Servlet interface). This special implementation of the Servlet interface also extends java.awt.Container, which allows you to add DreamBeans beans just like you would when constructing an applet. DreamBeans® provides a specialized viewer to preview a form prior to execution.

When you use the ServletApplication wizard to create a new ServletApplication, with <your app name>, several tasks are automated for you:

· A template <your app name>.java file is created

· A <your project name>.css file is created with default styles defined

· The two files mentioned above are added to your project

· The Servlet and DreamBeans® libraries are added to the required library list

· All the servlet context and init parameters are created and set default values

· An images directory is created in your project area containing a few button icons

If you put a check in the “Is a portlet” check box, which is displayed when you create a new ServletApplication, then DreamBeans® generates a special type of ServletApplication, call a PortletApplication. Generated PortletApplications are JSR 168 compliant. See the PortletApplication section of this chapter for a more detailed description of portlets.

Customizing the look and feel

Clicking on the “Style..” button brings up a GUI to change the look and feel of all the components as shown in the picture below:

The GUI modifes a “cascade style sheet”, which is used by the application to provide a consistent look and feel across all applications in the project.

The ServletApplication. property, “style_sheet_inlined” has a default value of “false”, which causes the style sheet to be linked to the generated web page rather than in-lined. This allows you want to experiment with different styles without stopping/restarting your Java web server. NOTE: Remember to put a “/” in front of a relative URL to the style sheet, otherwise, your web server will assume the file is a servlet and generate a ClassNotFound error.

There is a small performance advantage to in-lining the style sheet definitions.  When, in-lined, the ServletApplication holds the style sheet definitions in memory rather than the web server reading in the style sheet from disk for each browser request. Normally, this would only be useful in very high-traffic websites.

If you are not using a version control system, then you should backup the copy of <your app name>.css before modifying it. If you mess up the styles and need to revert back to the original version, it will be much easier if you have a backup copy.

Valid syntax

Only the beans on the “DreamBeansForms” page of your beans palette can be directly added to a ServletApplication. In other words, your ServletApplication is a set of forms. Thus, the only things you can add to a ServletApplication are forms.

You can add as many forms as you wish to a ServletApplication.. DreamBeans® also provides a pseudo-form, HTML_frameset as a convenience to quickly create (you guessed it) an HTML <FRAMESET>.

ServletApplication bean properties

When you pass a cursor over a property, a “hint” pops up that explains the purpose of the property. For most properties the property name and hint are sufficient explanation. The following are additional comments on some properties that require a little more explanation:

The autocommit property has the default value of true. That is, it specifies that any database operation is to be immediately executed. However, if your database supports transactions (COMMIT and ROLLBACK) and you plan to use COMMIT and ROLLBACK in your application, then set autocommit to “false”.

commit_timeout sets the number of seconds to wait before rolling back a transaction. This requires that autocommit property is set to false. For example, a customer is ordering books on-line and you had set the database transaction isolation level to “SERIALIZABLE”, thus no one else can complete their orders until the first customer, who has left for the day, completes his order. This is known as a “live wait”. The DreamBeans® middleware tracks the time each transaction is pending and will tell the database to roll back a pending transaction after a timeout period. The default value of “-1” specifies there is no timeout period.

The debug_depth property is used to specify the amount of debug information to output while your application is running. In most cases you not need this property. However, if you don’t understand the “logic” of why your application is behaving the way it is behaving, then you can turn on debugging. “GUI Forms” and “Logical Table” are useful to you. The other (deeper) levels are primarily for use by Konsensys.

The locale property is used to specify the default language and country, e.g., “en_us”. It is not fully used throughout the DreamBeans product, as DreamBeans in not internationalized. It is here mostly as a place holder.

The max_inactive_period property specifies how long, in minutes, a user’s session lasts with no activity. The default value is 60 (minutes).

The new_window property specifies whether you want your application opened in a new browser window or not. The default value is false.

The SSO_form (Single-Sign-On form) property specifies the name of the “login” form in your application. Leave this property blank if you do not require a person to login or register prior to using your application.

Note #1: The SSO_form property displays a menu list of form names that you have already added to your application. Therefore, you have to add a login form before you can set this property. Single-Sign-On is useful in two circumstances.

1. A user wishes to use an application more than once, without out having to log into the application each time (only requires logging in once).

2. You have a suite of applications in your project, and you only want the user to login once for any or all of the applications in your project.

Note #2: A user is automatically logged out when max_inactive_period expires.

Note #3:  You specify a successful login by setting the login property of DbButton to true. This tells the button, that if the database operation is successful (e.g., matches the entered user name and password to a record in the database) to mark the person a logged in. To complement this, the Quit button has a logout property, which tells the Quit button to both exit the application and also log the person out.

The style_sheet_name property is a URL to the cascade style sheet used for this application.

The version property allows you specify a version number for your application.

Servlet context parameters

All servlet context parameters, specific to DreamBeans®, have the prefix “javarex_”. Servlet context parameters are generally specified in your WEB-INF/web.xml file.

JDBC_database_name,  JDBC_driver, JDBC_URL, JDBC_username, and JDBC_password are used to access a SQL database via JDBC. Note, that there is a minor security issue with storing the username and password to a database in a web.xml or conf file. Be sure to set the directory and file access to restrict readability of that file. You might be asking why not have the ServletApplication prompt for a username and password? A “lights out” (24 by 7) automated environment might automatically restart a crashed server and no one would be around to provide a database username and password. Having the database username and password in a protected web.xml is adequate security for most of the world.

See the chapter on “Databases” for more details specific to choosing and configuring a database with DreamBeans®.

When a servlet starts up and the property, javarex_output_path_HTML, is a non-empty string, then HTML files corresponding to each form is output to the specified directory path.

When a servlet starts up and the property, javarex_output_path_SQL, is a non-empty string, then SQL defining all the tables and views is output to a .sql file in the specified directory path.

javarex_style_sheet_name the URL of the style sheet used by your ServletApplication.  or sent by the web server (linked to the generated web page).

Chapter 5 PortletApplications

PortletApplication is a ServletApplication

A portlet is special type of servlet. A portlet is designed to be displayed in a special type of web page, called a portal. A portal is a container that displays multiple portlets on single web page. That is, a portal is means of gathering multiple sources of data/applications onto a single web page. There is a free, open source portal from Apache.org, called Jetspeed. And there are several commercial versions available, e.g., Plumtree Software’s Portal product.

A portlet does not generate “<HTML>”, “<HEAD>”, nor “<BODY>” tags. The HTML generated by a portlet is captured by a portal “container” and typically displayed within an HTML table. The following describes how to generate JSR 168 compliant portlet using DreamBeans®.

PortletApplication bean properties

Select “New” from the component pane and then select the “ServletApplication” icon. A dialog box with ServletApplication properties will be displayed. If you select the “Is a portlet” check box, then DreamBeans® will generate a special type of ServletApplication called a PortletApplication. You then add forms, etc. to the PortletApplication just as you would a ServletApplication.

Unfortunately, the JSR 168 standard for portlets does not specify how data in form fields is passed in the request to a server. To make this simple for you, DreamBeans® provides an intelligent “StateField” that you can add to your forms.

The “StateFields” you add to your forms are smart. If an HTTP request parameter matching the name of a StateField is not found; the StateField tries to find a matching portlet request “attribute” name; if the StateField finds no match, then it tries to find a matching portlet request “property” name; if the StateField again finds no match, then it tries to find a matching portlet “preference” name.

After you create your portlet, use the “package” menu item under the “Project” menu to create a “.war” file. Copy the war file to your portal and use the portal’s configuration pages to tell the portal about your application, specify the row and column it will appear within the web page, preferences, security constraints, etc.

Chapter 6 Forms

On the bean palette you see the following beans located under the DreamBeansForms page:

BaseForm., GroupForm., TabbedForm, GotoButtonForm, RedirectForm., and HTML_frameset.. The class hierarchy is as follows:

The BaseForm. and GroupForm. are  both of type DataForm. The BaseForm contains data fields (associated with a base table), The GroupForm contains a group other Forms (associated with a derived table).

An ImportedBaseForm is special type of BaseForm that imports its field definitions from an existing database table.

The TabbedForm is a GroupForm with “CARD” layout that displays tabs for each Form added to the TabbedForm. Each tab’s label corresponds to the form_name property of the added Form. At run-time, selecting a tab, displays the corresponding Form.

The GotoButtonForm. contains no data fields. The buttons are used strictly for selecting other form destinations (similar in function to an HTML link).

The RedirectForm is used within a “reusable” GroupForm (a class you make that extends Groupform).

HTML_frameset. is pseudo-form and exists as convenience.

All of these will now be discussed in more detail.

The default value for the form_requst_method property is “POST”, because a “GET” has a limit of 1024 bytes in the URL. If you have a web page that has some large “textarea” fields or a large number of fields, the size of the HTTP query string might be larger than 1024 bytes, which is the maximum size allowed by an HTTP “GET”. The reason this property is made available so that you set it GET, is for case you want skip the default entry form, by passing some parameters specifying the form name and some field values.

BaseForm

A BaseForm. is an object that contains a BaseTable. A BaseTable is persistent database table (either a DreamBeans® object-relational table or an object wrapper around a SQL relational table). When you add fields (beans) to a BaseForm, it implicitly adds fields to the BaseTable. You can also add text, images, calc fields, result tables, etc. to BaseForms. When you create a class that extends BaseForm you have a re-usable object that can be added to your bean palette.

Important Note: You can make your new BaseForm. re-usable by using the BaseForm wizard in the DreamBeans® object gallery (invoked by the “New…” button in project components pane). This will create new class for you extending BaseForm and create an entry in for your new class in the bean palette. After adding your data fields, calc fields, text, etc., you can compile and select your new bean from the palette.

For example, if you create a reusable “AccountInfo”, it will appear in bean gallery as a component that can be added to GroupForm as shown in the picture of the GroupForm’s bean palette below:

When you select your new bean from the bean palette and add it to your application, you will see the bean property, form_field_properties.. When you click on this property, a table will pop-up that allows you to edit various field attributes, e.g., visibility, read-only vs. modifiable, required vs. optional, style, etc. You can even add more text, images, tables, calc fields, etc. to the bean. This allows you customize each instance of your new bean for different contexts.

The example property editor (above) allows customization

of your re-usable object (bean).

Important Note: The BaseForm. listed on the bean palette is for use where you do not plan on re-using the form. Use the object gallery to create a re-usable BaseForm bean. If you do use the bean palette version to define the same table in more than one place and accidentally make two incompatible definitions, you may have trouble tracking down the problem.

Setting the BaseForm.’s form_name property, will automatically set the table_name. property as the default. You should override this by explicitly by either settting the table_name property first or setting the table_name property to a slightly different name.  The reason for creating a unique table name is that you might several instances of this BaseForm, each with a different form_name that all access the same table.

ImportedBaseForm

Using external (foreign) tables.

Most “real-world” applications require accessing data in existing database tables. To access an external table:

6. If you have not already done this:

a. Select the “Project | Properties… menu item.

b. Select the “Database” tab in the Properties window and specify the name of the “external” database vendor, database name, port number, user name, and password.

7. Select an “ImportedBaseForm” from the “New” or “Add” buttons.

8. Set the form_name property of the ImportedBaseForm.

9. Set the table_name property of the ImportedBaseForm by selecting a table from the list of tables in the database.

10. Set the form_field_properties property of the ImportedBaseForm.

The example property editor (above) allows customization of how fields from an external database (an ImportedBaseForm) will be displayed.

Note that the form_field_properties property of the ImportedBaseForm has a couple of extra properties for each table field for specifying how each field is displayed. For example, a VARCHAR, TEXT, or STRING data type in the database can be displayed as either a “Text” field or a “TextArea” field in an HTML form. And, for each displayed table field, there is a property to specify the display width.

Note #1: You can NOT add, change, or remove the fields of an ImportedBaseForm from within DreamBeans. This prevents you from accidentally losing all your data or breaking your other existing applications that depend on existing table definition.

Note #2: To specify a “link” (relationship) to other tables, you can use the form_field_properties to change the “type” of an integer valued field to either a Link field or ChooseOne field.

Note #3: To specify a table in a different database (some database vendors would call it a different catalog or different schema). Prefix the table_name with a name of the database and period (just as you would in a SQL query). For example, “accounts.customer” specifies the “customer” table in the “accounts” database.

GroupForm

A GroupForm. is a form containing other forms. You can add as many forms to a GroupForm as you wish (including other GroupForms – nesting as deeply as you wish). When you add forms to a ServletApplication., you are actually adding the forms to a GroupForm contained within the ServletApplication.

You can make your new GroupForm. re-usable by using the GroupForm wizard in the DreamBeans® object gallery (under the menu item “File | New…”). This will create a new class for you extending GroupForm. After adding your subforms, calc fields, text, etc., you can compile and select your new bean from the palette.

There are two important bean properties for the GroupForm.: group_layout. and group_relation.

group_layout.

The group_layout. property has two values: COMBINED and CARD. When group_layout is COMBINED, then all the subforms are combined and displayed as a single large form in an HTML page. If group_layout is set to CARD, then each subform is displayed on a separate HTML page. The top-level GroupForm. contained within a ServletApplication. has a “CARD” layout.

For example, the “CompanyAndProduct” GroupForm might contain a BaseForm called “Company” and a BaseForm called “Product.” If group_layout is set to COMBINED, you would see an HTML page containing the data fields “Company Name” and “Product Name.”

If the group_layout is set to CARD, then your ServletApplication would first display the Company form. You would have to add a DbButton to the “Company” form to submit the “Company” form. If a row in the Company table is found, then the ServletApplication would display the “Product” form.

Important Note: If a GroupForm has a CARD layout, then you may not add anything but Forms or a TabPanel. If a GroupForm has COMBINED layout, then, you can add buttons, text, images, etc. to the GroupForm. The valid components you can add to GroupForm are automatically selected and displayed when you select the “Add” button. So, there is no need to worry about memorizing that information. However, if you add components to a GroupForm with a COMBINED layout and then change the layout to CARD – then you will have some problems!

To better understand how COMBINED and CARD layouts are used, see the address book example in the “Quick Start” chapter.

group_relation

The group_relation property defines the relational operation across the contained subforms (BaseForms and GroupForms). The group_relation properties allowed are:

LinkJoin, Join, Left Outer Join, Right Outer Join, Difference (SQL92 “EXCEPT), Intersection, Union, Product and Quotient (the division of one table by another).

Note: 99% of the time, the only group_relation you will ever need is “LinkJoin”. A “LinkJoin” is different than the “VIEW” in a SQL database. In a SQL database, a “VIEW” can be any kind of query. In DreamBeans®, a “LinkJoin” operates like the logical “AND” operation in a logic programming language, like Prolog (a natural join using the link fields as named logic variables is done).

The exact type of SQL code generated for SQL databases depends on whether implicit common columns are used. For example, Join generates the SQL, “NATURAL JOIN” when the property “uses_implicit_common_columns” is set to true, and generates “JOIN” when set to false (the default).

Note: A GroupForm must contain at least two data forms, when group_relation is not a LinkJoin. This should be obvious. For example, how could do a join with only one table?

Using external (foreign) tables.

To specify the “link” (relationship) to external tables, you must explicitly specify the “common columns”, using the explicit_common_columns property of a GroupField, which is a comma-separated list of common columns. For example, “Account.PersonID=Salary.PersonID, Account.PersonID=Department.PersonID” says that the “PersonID” in the “Account” table is the same as the “PersonID” table in the “Salaray” and “Department” tables..

GotoButtonForm

The GotoButtonForm bean generates an HTML page with buttons -- but no data fields. This kind of form is useful when you want to offer a list of options that take you other forms. You can add GotoButtons from the DreamBeansButtons page. You can also add PageText, HeaderText, HTML_component, and Box beans (both found on the DreamBeans® Misc page). A Gotobutton has a target destination. Clicking this button causes your ServletApplicaton to go to the target destination web page (similar to clicking on an HTML link).

RedirectForm

The best way to explain the RedirectForm is via an example of how it would be used. An example of its use would be a reusable GroupForm with a CARD layout that contains three “account” forms: an account login form for existing users, a form for new users to create their account username and password, and a form to change their account username and password. After successfully, completing any one of these forms, you want to go to the “next” form outside of this reusable GroupForm. The RedirectForm allows you to create a reusable “account” bean that you can reuse in multiple applications, without having to hard-code the name of the “next” form to display.

You add a RedirectForm as the last form within your reusable GroupForm. The forms within your reusable GroupForm would have buttons specifying the RedirectForm as their target. The RedirectForm automatically redirects to the “next” form following the reusable GroupForm.

HTML_frameset

The only thing you can add to an HTML <FRAMESET> are other <FRAMSET>’s and <FRAME>’s. The same is true here. You can only add an HTML_frameset or HTML_frame beans.

The HTML_framset is a pseudo-form. It’s just a convenience for quickly creating a web page with frames, when you don’t want to take the time to create an HTML page using an HTML editor (it’s a little faster and easier to use DreamBeans® for constructing simple framsets). You can only add a single HTML_framset to a ServletApplication. Further, if you add an HTML_frameset, you may not add anything else to the ServletApplication.

Chapter 7 Form Fields

There are four basic types of fields: data fields for storing various pieces of information, a group field that combines other fields as a single field, the Link field for relating rows in one table to rows in another table, calc fields for computing results from information in tables an inserting calculated results into tables, and finally state fields for providing global state information across forms (within a session). The class hierarchy is outlined in the diagram below:

This diagram shows the class inheritance structure of FormFields.

All form fields inherit from FormField which inherits from HTML_component. Those fields whose values have a textual representation inherit from BasicText. Fields with no textual representation inherit directly from FormField.

A non-data field, Link, inherits from IntegerField, which inherits from BasicText.

Most calc fields inherit from FloatingPoint, which inherits from BasicText.

Data Fields

Text-based

As mentioned previously in this section, data fields that have a textual representation inherit from the class, BasicText. Examples of such classes are:

· Text (a single line of text field),

· TextArea (a multi-line text field),

· IntegerField,

· FloatingPoint,

· Date,

· and Timestamp.

FileField

FileField is special type of data field that displays a file upload field and button. When the file is uploaded to from the browser/PC to the server, the database stores the file as a file. The FileField has a property to specify the mime types (file types) to list for selection.

Link

Link is special type of data field that is “foreign key” referencing a row in another table. It’s value is automatically generated by DreamBeans, and normally not visible in a form. Adding a Link field to BaseForm is your way saying that the BaseForm is “linked” to another BaseForm. If you want to indicate one table uses another table, you simply put a Link field in the BaseForm and give it a field name that is the same as the name of the table you want to “link.”

DreamBeans® uses the Link field to relate one table to another. The DreamBeans®  Link field is a unique feature that eliminates the need to define primary keys, foreign keys and referential constraints on keys. This allows developers to focus on what content and operations they want, without worrying about referential integrity problems.

Non-text-based

Examples of non-text fields that inherit directly from FormField are Checkbox and ChooseOne.

· Checkbox is the visual representation of a Boolean field.

· ChooseOne displays either a list of radio buttons or a menu list depending on whether its field_display_type property is set to “Radio Buttons” or “Menu List” option.

ChooseOne is slightly more complex and powerful field that requires a little further description. You can think of a ChooseOne field as a type of Link field (a foreign key pointing to a row in another table). The referenced row in that other table is identified by choosing from a list values displayed either as radio buttons or menu list. An example, will clarify this.

Suppose, you want to create an application that lets someone assign an employee to a department:

1. Create re-usable BaseForm called “Employees” and add a Text field called “Name”.

2. Create re-usable BaseForm called “Department” containing a Text field called “Department Name” and a ChooseOne field called “Employee Name”.

3. Next, use the “Add” button to add the “Employees” BaseForm, and in the ChooseOne’s choices_field_name property field, select the field “Name”.

When you run your application, a menu list employee names (or set of radio buttons) will be displayed from which a person can select a name to add to a department.

NOTE:

1. You must use the “Add” button to add the BaseForm containing the list of choices to a ChooseOne field.

2. The first field in the added BaseForm is normally the primary key (automatically created there by DreamBeans) and is used as an invisible “value” corresponding to each choice.

3. The ChooseOne field has a choices_field_name property that specifies which field in the added BaseForm contains the list of choices to display. If not specified, then the ChooseOne field assumes the second field (the field following the primary key) in the choices table is the field containing the choices to display.

The selected choice’s corresponding value is an invisible “link” referencing the named employee in the “Employees” table (not the actual name). Thus, an employee can change their name in the “Employees” table (e.g., if getting married), and you won’t have to make any changes in the “Departments” table.

GroupField

The GroupField is a visual means of specifying a composite index. The GroupField contains other FormFields. That is, the purpose of a GroupField is sorting (composite indexing) of a group of fields together. The search order is by the first subfield, then the second subfield, etc.

For example, you could have a GroupField called “Name”, containing the Text fields, “First”, “MI” (middle initial) and “Last”.  If the GroupField’s property, sorted, is “true”, then the GroupField, “Name” would be sorted first by “First”, then by the “MI”, then by “Last” name.

Note: If you are using SQL database, you can only nest subfields one level deep. When the DreamBeans® middleware generates SQL code for your database, it will define a column for each subfield and a composite index key (comprising each of the subfields).

Multidimensional arrays

GroupField is a very easy and powerful means of creating multidimensional arrays. All you have to do is put Link fields into a GroupField with the GroupField’s property, field_value_unique, set to “true”. Each Link field becomes an index for one of the array dimensions.

For example, consider a two dimensional spreadsheet where you wish to itemize quarterly expenses and calculate totals for each quarter. First you would create the classes Expense and Quarter by extending the BaseForm class. The Expense form would contain a list of expenses like electricity, gas, rent, wages, etc. The Quarter form would have three fields: 1) Integer field, named “Quarter”, with field_min_value set to 1 and field_max_value set to 4. 2) Integer field, named “Year”, with field_min_value of 2000 and field_max_value of 3000. 3) FloatingPoint field, named “Total”.

Next create a class called QuarterlyExpense, with a “unique” GroupField containing two Link fields named, “Quarter” and “Expense”. A second field in QuarterlyExpense would be a FloatingPoint field, named “ExpenseItem” with a field_default_value of 0.

A GroupForm, “Expense By Quarter” would contain the subforms Expense, Quarter and  QuarterlyExpense. You would add a ResultTable to this GroupForm as well (setting all of Quarter’s fields to not be visible in the ResultTable). The ResultTable would display a two dimensional array of expense by each quarter.

FieldPanel

FieldPanel

When you add data fields to a BaseForm, they are implicitly added to a FieldPanel contained within that BaseForm. The default FieldPanel has a default layout of “VERTICAL”, which means each data field you add will be added below the previous field.

Sometimes you may want arrange data fields horizontally next to each other. To make this possible, you can add a FieldPanel to a BaseForm and set the FieldPanel’s layout property to “HORIZONTAL”. Then you can add data fields to that panel.

You can nest FieldPanels to create as fancy a layout as you might desire.

Calc Fields

Calc fields have properties that define the operands. If the “operand_type” property is “FIELD”, then the “operand” property is interpreted as the name of the field. Otherwise, “operand_type” is “CONSTANT” and the “operand” property is treated as a constant value to be part of a calculation. If the “field_common_column” property is not blank, then the specified field is set to the calculated value.

The simplest calc field is CopyField. CopyField inherits from BasicText. It copies values from one field to another field (where the two fields are not common columns).

All the other calc fields inherit from FloatingPoint.

The Translation field converts string values to floating point values for use in other calculations. For example, you might want translate “HIGH” to 100, “MEDIUM” to 50, etc. The property “calculation” contains a comma separated list of string:value pairs. For example, “high:100, medium:50, low: 10, none:0”

ArithmeticField has two properties, “operand_one” and “operand_two”. It performs the operation specified in its “calculation” property (“+”, “-“, “*”, “/” or “SQRT”).

StatField has the property, “stat_column_name”, which specifies the column (field) to use in a statistical calculation. The “calculation” property specifies the type of statistical calculation (“SUM”, “MIN”, “MAX”, “COUNT”, “SUM OF PRODUCTS”, “AVG” and “STD”).  “SUM OF PRODUCTS” is a common operation in probability and statistical calculations, where one column in a row is multiplied times another column and the product summed across all rows. This requires two columns, which are specified as comma separated field names in the “stat_column_name” property.

The IfField provides an if-then-else construct. The IfField bean performs a conditional calculation (“=”, “<>”, “<”, “<=”, “>” and “>=”). You can add one or two other calc fields to this field. If the condition evaluates to true, then the first subcalc field is executed. If a second subcalc field is present and the condition evaluated to false, the second subcalc field is executed.

The GroupCalcField is a container of other calc fields.You can add a GroupCalcField to an IfField to conditionally execute a group of calculations.

State Fields

StateFields acquire user input that is not stored in a database. Therefore, StateFields do not correspond to data fields. StateFields and CalcFields are non-persistent logic variables. In contrast, the value of a data field will persist in a database table.

StateFields are used to share “context” across forms. You can think of StateFields as “global” variables. Two StateFields with the same name are references to the same global value.

There are currently six types of StateField provided: Text, IntegerFileld, FloatingPoint, DateField, Checkbox, and ChooseOne. They have the same properties as fields used in tables and can be used the same. The values simply aren’t stored in tables.

Note also that StateFields are global only within a “session” – not across all sessions in the JVM. That is, each user has a set of global variables specific to that user. This makes the StateField useful for maintaining application state for each user context.

The “StateFields” you add to your forms are smart. If an HTTP request parameter matching the name of a StateField is not found; the StateField tries to find a matching session “attribute” name.

If StateField is in a form within a “portlet” application (PortletApplication) and the StateField finds neither matching request parameter nor session attribute, then it tries to find a matching portlet request “property” name; if the StateField finds no match, then it tries to find a matching portlet request “preference” name.

Chapter 8 ButtonPanels & Buttons

Button Panels

Buttons must be placed inside a ButtonPanel A ButtonPanel groups and aligns buttons within a form. You can nest ButtonPanels as deeply as you wish. You may also have more than one ButtonPanel on a form. For example, you might want a set of buttons at both the top and bottom of the same page.

Buttons

All buttons inherit from Button. There are three basic types of button: 1) state setting buttons 2) buttons that unconditionally go to a specified form, 2) buttons that perform some operation on a database table.

Navigation buttons

GoNextButton goes to the next form.

GoBackButton goes to the previous form (causes a stack unwind).

GotoButton goes to the form named in the form_target property. The form_target can be any form at the same nesting level or higher. For a more complete explanation with example, see the section “Scope” in the “Getting Started Quick” chapter. “Next” and “Back” are reserved words used in a form_target property to respectively specify the next and previous forms.

State setting buttons

ResetButton generates a standard HTML reset button (resets all field values).

QuitButton causes the current page to close and stops the current session.

ClearButton clears fields except those fields that were instantiated prior to entry into the form. ClearButton also resets the table cursor. The ClearButton has GotoButton as a parent class, thus after performing a “clear” operation, the ClearButton will “go to” a form specified by the form_target property.

Database buttons

DbButton is the only button that performs an action on a table. The type of action performed on a table is specified by the action property. The following actions are supported:

· FIRST – Finds first row satisfying search constraints

· NEXT – Finds next row satisfying search constraints

· PRIOR – Finds pror row satisfying search constraints

· LAST – Finds last row satisfying search constraints

· INSERT – Inserts the data from the form fields into a row

· UPDATE – Updates a row with data from the form fields

· ENTER – Updates a row if the row already exists else inserts new row

· ERASE – Erases the currently found row

· COMMIT – Commits scheduled changes (if mode is not autocommit)

· ROLLBACK – Rolls back scheduled changes (if mode is not autocommit)

· DUMP – Dumps the contents of the table into UTF-8 formatted “.jrx” file. Currently limited to tables containing only fields which have a character representation. This is useful for backups.

· LOAD – Loads a dump (“.jrx”) file.

Note #1: It is highly recommended that if your form contains a DbButton with an INSERT action, that it also contains a Clear button. The Clear button clears all fields and generates a new primary key. Use of Clear button prevents an error message saying you attempted to insert duplicate primary key.

Note #2: It is recommended that a form has its on_entry_find_first property set, if it contains a DbButton with an action of ENTER or UPDATE and you are getting unwanted error messages about duplicate field on insert or no row selected for update.

The property form_on_success specifies the form to go to if the action succeeds. If no form is specified then the current form is re-displayed.

The property form_on_failure specifies the form to go to if the action fails. If no form is specified then the current form is re-displayed.

The form_on_success and form_on_failure properties can be any form at the same nesting level or higher. For a more complete explanation with example, see the section “Scope” in the “Getting Started Quick” chapter.

Chapter 9 ButtonAction

MailSender (Sending Email)

MailSender is a ButtonAction subclass, which is added to a DbButton. When a DbButton containing a MailSender is selected, the DbButton first performs its database operation and then sends email. MailSender has properties to set the “to”, “cc”, “bcc”, “subject”, and message sources.

The types of sources you can specify for each of the properties: “to”, “cc”, “bcc”, “subject”: are CONSTANT, FORM_FIELD, and TABLE_FIELD. A CONSTANT source type specifies that the property contains the actual value (is constant in value). A FORM_FIELD source type specifies that the property contains the name of an HTML form field to be used as the value (a form field not associated with a database table). A TABLE_FIELD source type specifies that the property contains the name of a database table field from which to obtain its value.

In the message property you can type in whatever text you wish and include data from either a database table field or form field (not associated with a database table field) by using the delimiters, “$$” in the form: “$$source_type:source”. For example:

Dear $$TABLE_FIELD:first_name$$!  You just won a million dollars!

In the example above, “$$TABLE_FIELD:first_name$$”, will be substituted with the current value of the table field, “first_name”.

NOTE #1: The TABLE_FIELD source type will cause the property to display a list of table fields used in the form containing the DbButton.

NOTE #2: MailSender uses “localhost” as the mailserver.

Chapter 10 Multi-Fields

All data-intensive applications need to display information about multiple fields concisely. DreamBeans® provides three beans for presenting information about multiple fields on a web page:

1. ResultTable bean: Displays data in a scrollable table.

2. SimpleTree bean: Displays the data in tree format

3. Chart bean: Displays data in charts (25 chart types available)

4. XY_Table bean: Maps datasets.

NOTE: A current limitation is one ResultTable (or one subclass like a SimpleTree or Chart) per page. However, one type of chart displays a “series” of charts.

ResultTable

When you add a ResultTable to form, it displays all those fields from that form have their field property, field_visibible_in_result_table, set to true.

Context-based Filtering

The rows displayed from the table are automatically filtered by the “context” of the form, which is set via your selections in other forms prior to entering the currently displayed form. You can also, set fields in the current form to a constant value (via the field_constant_value property of a field), to further filter what is displayed.

NOTE #1: You can add a ResultTable to a top-level GroupForm with a COMBINED layout, or to one of the top-level’s subforms. Adding to a subform simply specifies that you want to restrict fields from that subform displayed in the table.

NOTE #2:  Sometimes you want to display all possible rows (ignoring the current context). You can do this by adding the ResultTable to a form (or subform) that has its form_uses_context property set to false.

Scrollable Tables

A ResultTable can display either a plain table or scrollable table of rows. The integer frame_start property has a default value of 8. If the number of rows in a result is greater than frame_start, then the table is displayed as a scrollable table. If frame_start is set to -1, then the table will not be be shown with scrollbars.  Note, that this scrollable table in not supported browser that  do not support the <iframe> tag.

Row Selection Methods

The row_selection_method property of a ResultTable has three possible values: NONE, LINK, and BUTTON. The default is setting is LINK.

· If the row_selection_method set to NONE, then no means is provided for the user to select a row from the displayed table (used when the information in the table is display-only purposes).

· If the row_selection_method property is set to LINK, then each field in the column by the row_selection_field property is displayed as link.

· If the row_selection_method property is set to BUTTON, then a numbered row-select button is displayed to the left of each row in the table. The image_button_select_row_name property specifies the name of the image file to be used for the row-select buttons.

Selecting a row in the ResultTable will cause the containing form’s fields to be instantiated to the values in the selected row. You specify the form to “go to” (display) when a row is selected via the goto_on_row_selection property, which displays a list of possible destination forms. If no destination form is selected, then current form is redisplayed with values set from the selected row in the table.

Selecting Multiple Rows

When the multirow_selections property is set to “true”, the ResultTable displays a checkbox next to each row in the table. Selecting multiple rows from a ResultTable is used in conjunction with DbButtons that have their action property set to either ERASE or UPDATE. That is you can select multiple rows for delete or update.

WARNING: When the “update” button is selected, each selected row is updated with values from the visible fields in the form containing the ResultTable. Make certain that there are no fields visible in the form having their field_value_unique property set to “true”. Otherwise, you will get error messages about trying to insert fields with duplicate values.

Cell Selection (Drill-Down)

Sometimes you want to “drill-down” to get information specific to specific “cell” in a table. For example, you might have a table of departments and employees. If you click on a particular department, then you want to “drill down”  to a form with details about that department. And, if you click on an employee name in that same table, then you want to “drill down” to a form with details about that employee.

This accomplished by setting the drill_down_form property of each form field that you wish to be selectable in a table. The drill_down_form property is displayed when you select the form_field_properties property of a reusable BaseForm.

1. Create the drill-down forms.

2. Create a new, reusable form derived from a BaseForm using the “New” button in the IDE.

3. Next, add your derived (reusable) BaseForm to your application.

4. Select the reusable BaseForm’s form_field_properties property, which pops up a table of all the fields in your reusable BaseForm.

5. For those fields you want displayed in a table, set the field_visible_in_result_table property to true.

6. Of those fields to be visible in a table, select one of the drill-down forms that you created from the menu list. Each of those fields will be displayed as a link.

Display Format

The ResultTable property, display_format, has the two possible values: ROW and COLUMN. The default is ROW, which displays each row of the Form’s table as a row. COLUMN format displays each table ROW as column – however this format is not currently supported (and may be dropped altogether). NOTE: The COLUMN format is experimental. If enough people find it useful, it will be supported.

Sorting Table Results

Initial Sort Order

The property, sort_order property specifies the initial sorting of the rows when the table is displayed. The default is ASCENDING order.

Sorting by a Field (Column)

By default, all fields that have both their sorted and field_visible_in_result_table properties set to true, will have a “sort” button displayed at the top of those fields in the table. Clicking on a sort button will cause the table to be sorted by that field. Click the same field again, and the display order will be reversed. Note: Only fields which had the “sorted” property set to “true” when the table was defined can be used as a sort column.

Locked Sorting

You can restrict sorting to be only by one field by selecting the field in the ResultTable’s sort_only_by property.

SimpleTree

A SimpleTree is a subclass of ResultTable, which displays the query result as a “tree”. No programming is required. Just drop a SimpleTree into a DataForm, and the query result is displayed as a tree. The SimpleTree is most useful when many of the left-most columns have duplicate values. This allows one to display a large number of rows in a smaller amount of space.

The left-most columns in the row are the top-level nodes in the tree. That is, the first field in the form is the left-most field in the tree. And the last field displayed in a form is the right-most field in the tree. The tree is always displayed within a scrollable frame.

Chart

A Chart is also a subclass of ResultTable. As you would expect, the Chart bean displays the data as a chart, e.g., bar char, pie chart, line chart, etc. The chart_type property gives you 25 chart types to choose from. There are also properties on the Chart bean that allow you specify which fields are to be used for labels and which fields contain the numeric data.

XY_Table

An XY_Table is added to a GroupForm containing exactly 3 data forms (either GroupForms or BaseForms). The first form contains data displayed as column headers and second form as the row headers, when the orientation property is set to X_by_Y. And the first form contains data displayed as row headers and second form as the column headers, when the orientation property is set to Y_by_X. The third form contains the data that goes into each XY cell.

NOTE: Often, there will be cases where a column header will not have a piece of data that corresponds to one of the row headers. The XY_Table fills those “empty” cells with the values specified by the null_display_string property.

Chapter 11 Text Elements

HeaderText

The HeaderText bean allows you to add “header” style text to you web page. Like the PageText, bean, the graphical user interface for setting the header properties, like font, font size, color, etc. removes the need to know any HTML.

PageText

The PageText bean allows you to add static text to you web page. The graphical user interface for setting the text properties, like font, font size, color, alignment, etc. removes the need to know any HTML.

TextContainer

The TextContainer bean is an HTML container to which you can PageText and HeaderText. The container_type property displays a menu list: blockquote, divider (div), paragraph, and span. “Divider” (div) is the default container type. A container allows you specify attributes that you can not specify directly to the text, e.g., alignment, borders, etc. The TextContainer bean has properties to set all the commonly used HTML properties (without having to know anything about HTML).

Chapter 12 Other Miscellaneous Form Elements

HTML_component

All DreamBeans® displayed components inherit from HTML_component. This is an easy class for you to extend to create your custom HTML components. The HTML_component displays any HTML (or XML) tag. The tag is automatically lowercased to be XHTML compatible.

The has_end_tag property is set to false for tags that don’t have a matching end tag (e.g., br, img, frame and input tags).

HTML_content is what is placed between the HTML tags.

HTML_tag_modiers are for setting various attributes of the HTML tag. For example, “TYPE=TEXT” or “HREF=image/foo.gif”.

The HTML_style property is for setting a semicolon separated list of style attributes. These style attributes override any style class definitions.

The HTML_style_class property specifies the name of a style class.

HTML_inline

The HTML_inline bean is used when you have a large piece of external HTML that you want to include on a form. For example, you might have a long “license agreement” text that you want to “inline” into a form that has “accept” and “decline” buttons. This allows you to change the license agreement without having to recompile and redistribute your Java code.

An HTML_inline bean, inserts HTML from a file. HTML_inline is the equivalent of a “server-side” include used in “.shtml” files. HTML_inline has the “includeURL” property, which specifies the URL of the file used for the server-side include. The HTML_inline bean encapsulates the inlined HTML with “<div> tags. This allows you to set the alignment of the inlined HTML

Box

Box displays an HTML <TABLE>, which is used for formatting the layout of HTML components. You simply add beans to the Box.

If the HTML_layout_direction is VERTICAL (the default), then the table has a single column and all added components are displayed vertically. As you guessed, when HTML_layout_direction is HORIZONTAL, then the table has a single row and all added components are laid out horizontally.  You can add boxes to boxes to create any layout you desire.

IMPORTANT NOTE:  DO NOT ADD ANY FORMS, FIELDS, PANELS, BUTTONS OR RESULTTABLES TO A BOX. Box is only for formatting the layout of text, images, HTML links, etc. A future version will remove this restriction.

Image

Image is just a convenience (inherits from HTML_component) to quickly add an image to a form.

Chapter 13 Databases

Konsensys provides a built-in database, javarex (Java relational extension), for designing and prototyping. This is a version 1.0 DBMS and should NOT be used to store business or personal information. Use a third party SQL DBMS for your production system.

The built-in DBMS is good for design/prototyping because there is no setup and it uses very little memory and disk space compared to SQL relational databases.

Before using DreamBeans® with a JDBC/SQL database, you must create a database, schema, user, password and access privileges. No two vendors of DBMSes do this the same way. It is assumed you are already familiar with at least one SQL DBMS like MySQL, Oracle, DB2, Sybase, SQL Server, etc.

If you are just using DreamBeans® for prototyping, then you can set the servlet context parameter, javarex_ouput_path_SQL, to specify the directory path where a SQL file will be created containing table and view definitions that you can use as a starting point for your production application.

If you set the ServletApplication property, autocommit, to “false”, then the database must also support transactions (commit/rollback).

This chapter contains a section on using the built-in DreamBeans® database and a section on using the major SQL relational databases for use with DreamBeans® beans.

Using the built-in DreamBeans® DBMS

About the DreamBeans® DBMS

So, why did Konsensys develop yet another DBMS instead of using an existing DBMS? There were two reasons for creating a yet another DBMS. 1) Konsensys needed a completely portable (100% Java), “embeddable” DBMS that did not require any setup or tuning and had a very small footprint on both memory and disk. 2) No distribution fees to keep the price of DreamBeans® as low as possible.

Creating an “embedded” DreamBeans® DBMS

With an embedded DBMS, there is no need for starting up a database server prior to starting your application. An embedded DBMS has little or no setup. If you don’t set the servlet context parameter, javarex_server, then the DreamBeans® DBMS will be automatically embedded into the web server. All servlets on the web server have concurrent access the DreamBeans® database.

If you don’t set the servlet context parameter, javarex_path, then the registry and tables will be created in the current directory of the web server. When a servlet is started via the DreamBeans® IDE, the webapps directory under your project directory is where the embedded database will be created.

Embedded requirements: The embedded configuration requires concurrent access must be from a single JVM on the web server.  And the database must be on a file system mounted to the same computer as the web server. Note, that this is almost always the case when developing in a Java IDE. And this is also the case about 80% of the time for production applications as well.

Creating a “connectable” DreamBeans® DBMS

There are two reasons for creating a connectable DBMS:

· the database tables are located on other computers

· applications on multiple JVMs (e.g., applications on multiple web servers) will access the same tables

For these cases, you must specify the servlet context parameters javarex_server (name of the registry server) and javarex_port (the registry listening port). And prior to running your servlet, you must:

· Put a copy of javarex.jar on the remote server (javarex.jar can be found in the lib subdirectory of your DreamBeans® installation).

· Start the TableServer:  java –jar javarex.jar <dir_path> [port_number]

The required “dir_path” parameter is the directory path to both the “registry” database and default area to create tables. The optional “port_number” parameter is the IP port the TableServer should use (the default port is 1099 – the Java RMI listening port).

Optimizing performance

The best performance is achieved using the “embedded” configuration of the DBMS, because there is no overhead of transferring data over a network connection and no overhead of marshalling and unmarshalling data on each side of the network connection.

However, to handle a very large volume of web server hits, you might have to distribute the hits over multiple web servers running on multiple computers (e.g., a load balanced cluster of computers). That is, the same application is running on multiple web servers accessing the same tables. In that case, you must use a “connectable” configuration of the DBMS. You can maximize performance to a “connectable” DBMS by running a separate a TableServer for each table. If you need even higher performance, then put each table on a different disk spindle.

Using JDBC/SQL Databases

To select the type of SQL database you want to use: select the “Project | Properties…” menu item. This will display a properties wizard. On the properties wizard, select the “Database” panel and select the type of database (DB2, MySQL, Oracle, or PosgreSQL) from the drop-down list. This will automatically set the servlet “resource-ref” and “servlet context parameters” in your web.xml file. The following context parameters are also automatically generated for your application:

· JDBC_database_name

· JDBC_URL

· JDBC_driver

· JDBC_username

· JDBC_password

Using JNDI with JDBC

When starting your DreamBeans®-generated application, your application will first attempt to use JNDI (Java Naming and Directory Interface) using the JDBC_database_name to connect to the database. JNDI is used so that you don’t have to “hard-code” the type of database, hostname, port, etc. Most new versions of Java application servers provide an “admin” web page (after you start up the application server), that you can use to enter the type of database, database name, hostname, port, etc.

For example, you might use DreamBeans® to create an application packaged for sale (using the Project | Package… menu to generate a “.war” file). You don’t know which type of database, database host name, port, etc. that your customer is using. JNDI allows you application to connect to whatever database your customer might have without having to make any changes to your application. Your customer simply copies the .war file to the proper location in your application server, and it works without any extra setup (assuming you application server is configured properly).

Note: The JNDI “<resource-ref>” element in web.xml is not automatically generated because there are no standards across the various application servers. For example, Resin requires different information in the “<resource-ref>” than Tomcat. The application server, JBOSS, requires an added “<context-param>” element in web.xml. And so on. Therefore, if you wish to use the DreamBeans®-generated application with JNDI, you will have to edit the generated web.xml file to add the “<resource-ref>” and any other information required by the application server you are deploying to.

Using a JDBC Driver and URL

If your DreamBeans®-generated application fails to locate a “DataSource” using JNDI and the JDBC_database_name, then your application will next try to use the JDBC driver and URL to connect to the database. If both the JNDI and driver methods fail, then an ERROR message is displayed on the web page when you try to run your application.

Servlet context parameters are also used so that your application is not “hard-coded” to use a specific database and schema. If desired, your customer can edit the generated web.xml file to change any of the context parameters. Sometimes this is easier than using JNDI.

For example, suppose your customer is a very small company that is using an ISP to host their web sight and using a Java application server like Tomcat or Resin. For security and stability reasons (they don’t want to accidentally destabilize other companies on the same computer/application server), they might not be given privileges to configure the application server using JNDI. In this case, they can upack the .war file (using the “jar xf <myApp>.jar” command), edit the web.xml file to use the database on your ISP’s web site (typically MySQL or PostreSQL) with whatever database port number you are assigned.

DreamBeans® comes preconfigured with JDBC drivers for DB2, MySQL, Oracle, and PostgrSQL. You must create a database instance (and if your DBMS has a concept of schema, create a schema) prior to starting your servlet. You must also create a username and password in your SQL database. DreamBeans® will automatically create tables and views in your SQL database.

Note: As you would expect of Microsoft, Microsoft’s JDBC driver is not fully JDBC 2.0 compliant. Specifically, their driver does not support the “addBatch(String)” and “execute(String)” methods, which DreamBeans® requires. Therefore, if you wish to use Microsoft’s SQL Server DBMS, then you will have to install BEA’s Weblogic application server and use its JDBC drivers or use a driver from some other company. Note that the BEA driver license requires that you only use the BEA driver with their Weblogic application server.

You should use the JDBC 2.0 or later drivers. DreamBeans® requires that the SQL DBMS accept the syntax for foreign keys and referential integrity constraints such as “ON DELETE CASCADE”. If you set the ServletApplication property, autocommit, to “false”, then the database must also support transactions (commit/rollback).

DreamBeans® will make an attempt to generate SQL code that works with the major SQL DMBSes. For example:

· Oracle lacks the SQL standard “BIGINT” data type and thus DreamBeans® generates “NUMERIC(19,0)” when it detects Oracle being used. Likewise, if DreamBeans® detects Oracle is being used, it will substitute the SQL standard “EXCEPT” with the Oracle equivalent, “MINUS”.

· IBM’s DB2 Universal Database does not support the ANSI standard join type, “NATURAL” (implicit common columns). Therefore, DreamBeans® generates “JOIN … ON…”.

· Microsoft SQL Server’s DATETIME is the closest equivalent of a SQL TIMESTAMP.

· Any character string greater than 255 characters in MySQL must be type TEXT or BLOB rather than CHAR or VARCHAR.

· And, so on.

DreamBeans® allows field names of any length with spaces and most other characters. However, most SQL databases are much more restrictive. So, by default, when a SQL DBMS is being used, DreamBeans® will automatically translate the field names to uppercase, replace spaces with underscores, and truncate the length to 30 characters.

Important Note about TextArea fields

A TextArea field is a multiline form field that corresponds to a Java “String” datatype (which can be up to 36,567 characters in length). Most SQL databases use “VARCHAR” for strings less than 256 characters in length. And these SQL databases generally use a different field type, such as “TEXT” or “BLOB” for strings larger than 255 characters in length.

Most SQL databases do not allow the “UNIQUE” attribute on ‘TEXT” or ‘BLOB” field types. And these SQL databases typically do not allow indexing on ‘TEXT” or “BLOB” field types.

Therefore, if you want to use indexing (TextArea’s sorted property set to “true”) and/or want to make your TextArea field “UNIQUE” (TextArea’s field_value_unique property set to “true”), then you should also set the TextArea’s maxCharacters property to be some value less than 256 characters. If you attempt to create a UNIQUE (field_value_unique) or INDEX (field_value_unique) in table (BaseForm) that is greater than 255 characters in length, then at run-time, you will get error messages in both the “Messages” tab of DreamBeans® and in your web page.

Note that is a limitation of SQL databases like MySQL, Oracle, etc. Not having UNIQUE or INDEX attribute on strings larger than 255 characters is not a limitation of the DreamBeans® or the built-in database.

Generating SQL code

Note also, that if you set the servlet context parameter, output_path_SQL then all the SQL code for the tables and views are written out to a file named <your app name>.sql in the specified output path. This is useful when you only want to use DreamBeans® for prototyping, but use the SQL definitions as a starting point for the production code. Note that DreamBeans® does not use views, but it outputs view definitions to a file so that you can quickly duplicate the equivalent application logic of in your legacy ASP/JSP code.

Using External Tables with DreamBeans®

Most “real-world” applications require accessing data in existing database tables. To access an external table, create a BaseForm, set the table_ native property to “false”.  Normally, any change to the field definitions in a BaseForm will cause a new table to be created – destroys the previous table and its contents (assumes you are prototyping and thus no longer interested in the previous table definition). The table_native property tells the database that this table is not created within DreamBeans®. Further, if you attempt run your DreamBeans® generated application and the field definitions do not match those of the existing table, then a “TableSchemaException” is thrown and an error message is displayed in your web page.

When using an existing table, with an integer valued field, then you should set the field_bit_width property to match that of the database table’s width (byte, short, int, or long). Likewise, you should set the field_precision of a floating point to either “single” or “double” to match that in your database table.

You can not use a “LinkField” to reference an external table, because the external table will probably lack a primary key field (column) having the same name as the table name and have the data type of a long/big int. Therefore, to specify the “link” (relationship) to external tables, you must explicitly specify the “common columns”, using the explicit_common_columns property of a GroupField, which is a comma-separated list of common columns. For example, “Account.PersonID=Salary.PersonID, Account.PersonID=Department.PersonID” says that the “PersonID” in the “Account” table is the same as the “PersonID” table in the “Salaray” and “Department” tables.

Chapter 14 Installing your DreamBeans®-generated application

Once you have finished developing an application with DreamBeans®, you need to “install” your application in a Java application server, such as Tomcat, Resin, JBOSS, Weblogic, or Websphere.

Step #1: You must create a database, schema, username, and password if they does not exist in the SQL database you choose.

Step #2 (Optional): Use the “Project | Package” menu item in DreamBeans® to generate a “.war” (web archive) file in your project directory.

Step #3: Copy the generated “.war” file (or all the files in your project’s “webapps” directory) to the appropriate directory for your particular application server. For example, in Tomcat, you would copy your “.war” file to the “webapps” directory. And with JBOSS, you would copy the “.war” file to the “deploy” directory.

Step #4: With some Java webservers (like Tomcat), you must create “context.xml” file that tells Tomcat the name of the “context” of your servlet application. The context name is the same name as the name of your project. For Tomcat, DreamBeans generates a “<project>/conf/server.xml” file that contains this context definition. You can copy-and-paste the context definition in this “server.xml” file into your webserver’s server.xml or paste into a Tomcat context.xml file. And you may have to use your webserver’s “admin” pages to “deploy” the servlet. For JBOSS, you just have to copy the war file to the “deploy” directory.

Step #5: The first time your servlet application runs, it will display a form asking for the name of the database, host, port number, username, and password. It does this because no two Java webservers seem to implement the JNDI (Java Naming Directory Interface) DataSource exactly the same way. That is, the JNDI “standard” is not sufficiently defined that the same web.xml file can be used for every webserver. For example, the web.xml file used to specify a JNDI data source on Tomcat JNDI is a subset of that required for Resin JNDI, etc. Even worse, the various webservers, have very different ways of specifying JNDI. To provide portability across all webservers, DreamBeans provides its own “DataSource”. This makes life a little easier for you, because you don’t have write a webserver-specific JNDI configuration and webserver-specific web.xml.

Chapter 15 Customizing and Extending

Customizing DreamBeans®

Every DreamBeans® application uses a <your_app_name>.css file that let’s you customize the overall look and feel of your application. Also, the DreamBeans® HTML_component bean is a generic HTML component that allows you to define any HTML tags, modifiers, style, style class and content simply by setting its bean properties. Likewise, all forms, form fields, buttons, etc. provide style and style class beans to override the default look and feel. These attributes allow you overrid the default look and feel on a case by case basis. This gives you 100% control of the look and feel of your application.

Extending DreamBeans®

You would want to extend DreamBeans® in two ways:

1) Extend an HTML_component class to create a special bean that you would re-use frequently. For example, you might create an HTML_component displaying your company logo and company name that you can quickly add to any form.

2) Write Java code to extend the behavior of DreamBeans® bean. For example, you might want to do some extensive computations to process the input from a form and then display graph or chart as a response.

You will need a third party Java IDE (such as Borland’s JBuilder, Sun’s NetBeans, IntelliJ’s Jidea, etc.) to create/edit your classes.

Extending the HTML_component class

You may wish to create a special bean that you can frequently re-use. The javarex.beans.servrlet.Image class extends HTML_component because one frequently wants to add an image to their HTML page. The following is the source code to the javarex.beans.servrlet.Image class:

//***************************************************************************************

//****************** Source code javarex.beans.servrlet.Image ****************

package javarex.beans.servlet;

import java.awt.Component;

import javax.servlet.http.HttpServletRequest;

public class Image extends HTML_component {

  /**

   * For cross-browser compatibility, the image is wrapped in a DIV,

   * and style sheet attributes applied to DIV rather than the IMG

   */

  protected HTML_component image = new HTML_component();

  /** height of the image in pixels */

  protected int height = 64;

  /** width of the image in pixels */

  protected int width = 64;

  /** URL of image to display*/

  protected String image_URL = "";

  public Image() {

    setHTML_tag("DIV");

    image.setHTML_tag("IMG");

    add(image);

  }

  public Image(String style_class, String style, String tag_modifiers) {

    HTML_style_class = style_class;

    HTML_style = style_class;

    HTML_tag_modifiers = tag_modifiers;

  }

 /**

 * Sets the height of this image in pixels.  Should always be used because

     * it speeds browser rendering by preallocating space prior to downloading

     * the image.

 *

 * @param int -- the height of the image

 */

public final void setImage_height(int height) {

    this.height = height;

    image.setHTML_tag_modifiers(

      image.getHTML_tag_modifiers() + " HEIGHT=" + height);

  }

 /**

  * gets the height of this image in pixels.

  *

  * @return int

 */

  public final int getImage_height() { return height; }

 /**

 * Sets the width of this image in pixels.  Should always be used because

  * it speeds browser rendering by preallocating space prior to downloading

  * the image.

  *

  * @param int -- the width of the image

  */

public final void setImage_width(int width) {

    this.width = width;

    image.setHTML_tag_modifiers(

      image.getHTML_tag_modifiers() + " WIDTH=" + width);

  }

/**

 * gets the width of this image in pixels.

  *

  * @return int

  */

  public final int getImage_width() { return width; }

  /**

   * Set the URL of the image to display;

   *

   * @param String -- the URL

   */

  public final void setImage_URL(String URL) {

    image_URL = URL;

  }

  /**

   * Get the URL of the image to display;

   *

   * @return String

   */

  public final String setImage_URL() { return image_URL; }

}

//****************** End of source code to Javarex.beans.servrlet.Image ****************

//**********************************************************************************************

In the example above, the extended HTML_component set its HTML_tag property to “DIV”.  It contains another HTML_component, image, with its HTML_tag set to “IMG”. That is, the HTML <DIV> contains an HTML <IMG>. The rest of code simply set the image properties.

Extending a FormField class

javarex.beans.servlet.field.util.BasicText is a subclass of javarex.beans.servlet.field.util.FormField. If your field has textual representation, then you should extend BasicText ( or extend one of it’s subclasses, e.g., Text, TextArea, Date, Timestamp, IntegerField or FloatingPoint). For example, you might want to create a “formatted” text field.

If your field does not have a textual representation, then you would want to extend the FormField class. For example, you might want to create calendar field that displays a pictures of months and days.

FormField has large number of fields, properties and methods. These are all described in the in the API (javadoc) documentation. This section discusses the key methods you will need to implement when extending a FormField.

You must create a constructor with no parameters if you want to use your extended class as a bean. Be sure to call “super();” in your constructor.

After all your properties are set, you might want to perform some final initialization before your class is used.  For this final initialization, DreamBeans® provides the method:

            public void build(Locale locale);

You can extend (never override) this class. The following code is used by IntegerField to extend build:

public void build(Locale locale) {

  super.build(locale);

  if (displayStyle == DISPLAY_ONLY) {

    rendering.setHTML_tag("SPAN");

    setHTML_style_class("displayOnlyNumericField");

    setHTML_VALUE_attribute_allowed(false);

  }

  else

    setHTML_style_class("numericField");

}

IntegerField’s constructor sets it’s HTML tag to <INPUT> with tag modifier “TYPE=TEXT”.  However, if you set the bean property, displayStyle, to DISPLAY_ONLY, then build(Locale) sets the HTML tag to <SPAN>.

FormField is an abstract class, which means it has two methods that need to be implemented.

If the FormField properties, field_visible_in_form and field_value_required, are set to “true”, then the Javascript function, verify(this), is called when the submit button is clicked. Verify() does client-side validation of field input. This reduces network overhead. The constraints are supplied via the function field_constraints().

/**

* This is used for client-side validation of input.

 * Returns a list of constraints for this form field (in Javascript) that is

 * is used by “onClick=verify(this);” when a submit button is clicked.

*

 * @return String

 */

public abstract String field_constraints();

BasicText and it’s subclasses already supplies an implementation of this. If you are extending FormField directly, then simply write a field_constraint() that returns an empty string.

public String field_constraints() {

  return = "";

}

When a form is submitted, the form asks each FormField to get its value from the input field. You must implement the following abstract method to get and validate the input:

/**

 * Gets the field value from input for either database FIND or MODIFY.

 * Any server-side validation of the field input is done here. If the

 * validation is successful, then it returns "true."    

 *

 * @param mode (FIND or MODIFY)

 * @param HttpServletRequest

 *

 * @return boolean -- true if successful

 */

public abstract boolean getFieldValue(int mode, HttpServletRequest request);

The following is the implementation of getFieldValue that IntegerField uses:

public boolean getFieldValue(int mode, HttpServletRequest request) {

  boolean good = true;

  if (isConstantValue) {

    ((LongField) value).set(field_constant_value);

   dataField = field_constant_value;

  }

  else

    if (editing_enabled && field_visible_in_form) {

     String num = request.getParameter(field_name);

     num = num.trim();

     if (!"".equals(num)) {

       try {

         newValue = Long.parseLong(num);

       }

       catch (NumberFormatException e) {

          good = false;

          setError_msg(e.getMessage());

          e.printStackTrace();

      }

    }

    else

      newValue = 0;

    if (mode <= ROW) // find mode

      getSearchCriteria(request, num);

    else // modify (insert/update) mode

      ((LongField) value).set(newValue);

  }

  else

    if (!"".equals(field_default_value)) {

       ((LongField) value).set(field_default_value);

      dataField = field_default_value;

    }

  return good;

}

Extending a Button class

All form buttons extend the abstract class Javarex.beans.servlet.buttons.util.Button. When a button has been selected, DreamBeans® calls the button’s getPage method to do whatever action that button must perform and return the next HTML page to display. getPage is the only method you must implement:

The following abstract method must be implemented:

/**

* Called when this button is selected.

*

* @param HttpServletRequest

* @param HttpServletResponse

* @param Form -- the data form containing this button

*

* @return String -- an HTML page

*/

public abstract String getPage(

  HttpServletRequest request, HttpServletResponse response,

  Form parent_form);

The following is the getPage source code for a GotoButton:

public String getPage(

    HttpServletRequest request, HttpServletResponse response,

    Form parent_form) {

  final Form f = goForm(parent_form, form_target);

  return gotoForm(request, response, f);

}

In the example above, “goForm(parent_form, form_target);” locates the form to display (returns null if not found).  Next, the button goes to the form (returns the HTML for the form (by calling “gotoForm(request, response, f);”).

Extending a Form class

All forms extend Javarex.beans.servlet.util.Form as shown in the following diagram:

You can extend Form, GotoButtonForm, BaseForm, ImportedBaseForm or GroupForm. In practice, almost all extensions will be simply using the object gallery to extend BaseForm and GroupForm by adding various components to create re-usable objects (custom beans). This process is described fully in the “Quick Start” chapter.

However, there may be some rare circumstance where you actually want to do some post-processing on the form just displayed or some pre-processing on the form about to be displayed. What follows is a description of how to do this.

When an HTTP request comes into your servlet, it locates the current form and calls the current form’s getPage method, which processes the request and returns new HTML page. Therefore, to extend a Form with your custom Java code, you will extend the getPage method.

If your class extends either GotoButtonForm, BaseForm or GroupForm, then your getPage method should look like the following:

/**

 * Returns an HTML page.

 *

 * @param HttpServletRequest

 * @param HttpServletResponse

 * @param boolean - true if called by ServletApplication

 * @return String - the HTML for this page

 */

public String getPage(

            HttpServletRequest request,

            HttpServletResponse response,

            boolean from_top) {

  if (from_top) {

    //

    // This is the form that was previously displayed.

    //  Do your custom post-processing after this form is displayed

    //

  }

  else {

    //

    // This form is the next form that will be displayed.

    // Do you custom pre-processing before this form is displayed

    //

  return super.getPage(request, response, from_top);

}

You can use the protected object, table, to access the table in a BaseForm or GroupForm’s getPage method. In the example below, the “Company Name” field is used to determine which company logo to display in this form.

iavarex.beans.servlet.Image companyLogo = new iavarex.beans.servlet.Image();

public String getPage(

            HttpServletRequest request,

            HttpServletResponse response,

            boolean from_top) {

  if (!from_top) {

    //

    // This form is the next form that will be displayed.

    // Do your custom pre-processing before this form is displayed

    //

    final javarex.field.StringField companyName = table.getField(“Company Name”);

    companyLogo.setImage_URL(“http:/images” + companyName + “.gif”));

  }

  return super.getPage(request, response, from_top);

}

Chapter 16 Advanced Topics

Starting at a specified form

By default DreamBeans® applications start at the first form within the ServletApplication class. However, there are times, when you want your application to start at another form. Form example, the frequently asked questions application on the Konsensys website, contains questions/answers for several products. Each link only shows the questions/answers for a particular product.

This is accomplished by attaching to the URL a query string containing the name of a “top-level” form. It’s that simple. You can also attach field names and the name of a button in that form to the query string. For example, the FrequentQuestsions servlet on the Konsensys website uses the following URL:

"http://www.konsensys.com/servlet/FrequentQuestions?form_name=Entry+Form&amp;

Company.Company+Name=Konsensys&amp;Products.Product+Name=DreamBeans&amp;

button_action=Next"

This link specifies “Entry Form” as the first form and passes the parameters specifying the company name (Konsensys) and product name (DreamBeans®) and a selected button (Next), which sends the servlet to “Entry Form”, instantiates the fields to the values “Konsensys” and “DreamBeans”, and then activates the “Next” button action. The result is that the first form displayed is the “Next” form, with just the questions/answers associated with the DreamBeans® product.

NOTE:  That each field name specified in the above example is prefixed with the associated table name, e.g.,

Products.Product+Name=DreamBeans

This is necessary to ensure that the right “Product Name” field is selected.

Advanced Database Design

The things you mommy never taught you on how to avoid trouble

PROBLEM #1:  On very large software applications that have a large number of database tables, developers always run into the tough problem of trying to add new features that require changes to database tables -- which will break older clients or other applications that still rely on the old database format.

When a new version of the application is developed, it is not compatible with some of the previous database tables. And this creates a problem, because now there are two sets of tables (the old and new) that have common fields, which must be updated with the same information!

This tough problem is caused by one thing: a database that was not sufficiently normalized.

The argument for not normalizing a database is always “performance.”  Use the same philosophy that all competent software developers use: Design for long-term maintainability; identify the performance bottlenecks; and optimize just those parts to remove the performance bottlenecks. As computers become ever faster, there is less need to sacrifice maintainable designs for fast performing designs. Further, there many optimizations that can be performed before combining small tables into a larger table to improve the speed of table joins.

The first step in optimization is to look at your database query to see if the order of table “selects” can be rearranged to speed the query result. The second step is to ensure that the common columns are indexed to ensure fast lookup. If the previous steps are still inadequate, then “tune” the database (if the database provides tuning parameters), by increasing the amount memory available, increase the cache for specific tables, adjust the size of the B-tree pages, use hashed indexes where appropriate, etc.

Finally, if all else fails, evaluate if faster computer could solve the performance problem, because this is almost always cheaper than the maintenance cost of a de-normalized database. Ask your VP of engineering to estimate the average “fully burdened” salary of software engineer in your organization. Look in your defect tracking system to estimate the number of reported problems due database design issues and multiply by 3 days to find and fix each problem. Throw in more cost for customer support calls for each reported problem. The cost of talking to customers, finding and fixing only takes 3 or 4 bugs is more than the cost of adding another CPU board to a database server or adding a lot more memory to existing CPUs.  If faster hardware is not an option, then combine a few small tables into a single larger table (the last resort).

Also, most programmers don’t know how to normalize a database! Most programmers don’t even know what “domain key normal form” means.

So, what follows are four simple rules of thumb, that while not guaranteeing sufficient normalization, will get you pretty close:

1. Make a clear separation of “data” fields from “link” fields. Think of “link” fields as being like a “reference” to an object in Java. You don’t know or even care about the numeric value of the address comprising the reference. All you care about is the data in the object pointed to by the reference. Likewise, the primary key should always be some automatically generated value that never changes for the life of the row. And you store your “data” in other fields.
2. Never (absolutely never) define the same data field in more than one table. For example, if you have an “Employee_Name” field, that field should only occur in one table. Other tables should use a numeric foreign key to reference the table/row containing the “Employee_Name” field. If you do have the same “data” field in multiple tables, then your database is not sufficiently normalized.
3. Never define fields that can have NULL values. If a value is optional, then specify a default value. If the value is not yet known put the field into a separate table. This is one of two reasons why DreamBeans® automatically creates all fields with the “NOT NULL” attribute. It’s for your own protection.
4. A table should generally not have more than three “data” fields and not more than three “foreign keys” (LinkFields in DreamBeans®). Thus, only put two or three data fields and no more than three “link” fields in a BaseForm. Use a GroupForm to group the BaseForms into a larger Form. DreamBeans® has a query optimizer that optimizes the query before sending it to the DMBS, so the performance hit of using several small tables instead of one large table should be small. Remember that you can make the GroupForm a reusable object, so that you can treat it like single table that you can easily drop into multiple places in your application. An “old” and “new” application would use different GroupForms (in SQL terms, different VIEWs), containing different a different (intersecting) set of tables.

PROBLEM #2:  On large and complex databases, two things happen often: First, a row is deleted in one table and “dependent” rows in other tables are not deleted. These dependent rows with foreign keys (link fields) that do not reference an existing row are called “orphan” rows. Second, data in one row of a table is changed and the same data in other tables is not also changed. For example, changing the name of a product in one table and not changing the name in other tables. These are called “inconsistent” rows. Orphaned and inconsistent rows are known as referential integrity problems.

Avoiding these problems is very simple. Further, DreamBeans® simply won’t allow you make those mistakes in the first place (ImportedBaseForms being an exception because they are “external” to DreamBeans®).

1. Never use the SQL 92 referential constraint attributes, “SET NULL” and “SET DEFAULT” on foreign keys. Use only the “NO ACTION” or “CASCADE DELETE” attributes. This prevents the orphan row problem. If you feel the desire to use “SET NULL” or “SET DEFAULT” then you should move those fields (columns) to another table, because your current design is not sufficiently normalized.
2. Primary keys should only be a numeric number that is automatically generated (an “AUTONUMBER” or “AUTOINCREMENT” and is never changed for the life of a row. This eliminates most of the inconsistency problems.
3. Never (absolutely never) put the same data in more than one table. Use a foreign key (LinkField) to access information in another table. This, combined with the previous restriction on primary keys, eliminates the inconsistency problems. DreamBeans® helps enforce this with the “default” behavior of treating two fields with same name as being different (not common columns). Yes, that is restrictive. But, in “enterprise-scale” applications, it is just good discipline.

DreamBeans® has a unique “link” feature that enforces the above rules to guarantee the referential integrity of your database.

SUMMARY:  If you follow the above rules for avoiding problems #1 and 2, you will not only save yourself a lot of work as a developer, you will also save your clients a great deal of frustration, time and money. Further, DreamBeans® provides technology that helps you to enforce those rules.

The best analogy for why one wants technology to enforce rigid rules is programming languages. If you want to write a very small program, then using a weakly typed language with polymorphic data types, like Perl or Python, is very convenient. But, on large applications, strong type checking in languages like C++ and Java with explicit casting, while not as convenient, makes large programs easier to maintain. Likewise, DreamBeans® enforces certain rules to make large applications easier to maintain.

Chapter 17 Appendix

Error Messages

INTERNAL ERROR

INTERNAL errors are displayed in dialog boxes by DreamBeans®. These indicate either a bug (defect) in the DreamBeans® product or in Java. To be safe, DreamBeans® exits after an INTERNAL ERROR, to prevent any corruption of your code. At the current time, the only known INTERNAL ERROR messages are caused by bugs in Java for which DreamBeans® has not yet found a work-around. For a list of the known Java bugs that can cause DreamBeans® to crash, see the release notes on the DreamBeans® download page at the Konsensys website.

CONSTRUCTION ERROR

CONSTRUCTION errors are displayed on a web page when the servlet is initializing itself prior to running. The web page has the header “CONSTRUCTION ERROR”.  A CONSTRUCTION error generally indicates that you made an invalid addition of a component to a container or set a property to an invalid value (or forgot to set a value).

DreamBeans® is a computer language that has a syntax. When you add beans together, you are writing a program. Only certain beans can be added to other beans.

To prevent those syntax errors from happening in the first place, DreamBeans® only displays valid components that can be added to currently selected component. Further, when you select a component to add to your application, it will display the important fields that should always be set for that component.

However, there are some cases where you can fool DreamBeans®. For example, after setting the required values when adding a component, you later unset those values, then you will probably get one of these CONSTRUCTION error messages.

The three most common causes of CONSTRUCTION errors are. 1) You have created a servlet application, but have not yet added any forms. Thus, there is nothing to display.  Duh! 2) You misspelled the name of a table in the linked_table_name property of a Link field. 3) You added a bunch of components to GroupForm with a COMBINED layout, and then changed the layout to CARD. And those added components are not valid component of GroupForm with CARD layout. A future version DreamBeans® will create two subclasses of GroupField, one with the layout property set to COMBINED and the other set to CARD. This will prevent that problem from happening in the first place.

If the error message on the web page does not provide sufficient information to identify the cause of the problem, then try looking in the DreamBeans® IDE’s “Message” view (when run from with DreamBeans® IDE) or the Java web server log files. Generally, there will be a stack trace in the log file that will provide more information.

You should not release you application until all CONSTRUCTION errors have been removed.

RUNTIME ERROR

RUNTIME errors are displayed on a web page when you run the generated application. The web page has the header “RUNTIME ERROR”.  A RUNTIME error generally indicates that you set some property to a value that caused a problem at run-time. Most run-time errors are actually construction errors that can not be easily detected until the program is being used.

Examples of not setting properties to valid values that result in a run-time error are: Misspelling the name of target destination form in a Button and specifying the name of a target form that is “out of scope” (inside another form). At the time the button is constructed, the destination form might not yet have been constructed. Thus, there is not way to verify that a specified form actually exists until the application has been completely constructed.

If the error message on the web page does not provide sufficient information to identify the cause of the problem, then try looking in the DreamBeans® “Message” view (when run from with DreamBeans® IDE or the Java web server log files. Generally, there will be a stack trace in the log file that will provide more information.

You should not release your application until all RUNTIME errors have been removed.

EXCEPTION ERRORS

DreamBeans® throws an exception and displays the exception in a web page under the following conditions.

• The DreamBeans® license was not  found, or a trial license key has expired. And the displayed message indicates either the license is not found or expired.
• The browser is not a supported browser. This version of DreamBeans® only supports browsers compliant with the HTML-4 and CSS-2 standards (e.g., IE 5.5 and later or Netscape 6.1 or later). The current version of DreamBeans® is intended to be used either on company-internal web sites, where most browser versions a more carefully controlled, or for prototyping JSP applications where developers almost always use a fairly new browser. The browser displays an error message to that effect.
• Other types of exceptions indicate either a bug in DreamBeans® or bug in your application that DreamBeans® should have detected and reported as either a CONSTRUCTION error or RUNTIME error. Please report this error to Konsensys. You will be asked for the stack trace, and mini program demonstrating the problem (no more than 200 lines). You might also be asked to set the debug_depth property to level 3 or 4, and run the application to generate a trace that can be provided to support. You should not release you application until all stack trace generating errors have been removed.