2.5 Creating a Layer of Business Domain Objects for Tables

With the database tables in place, you can create a set of Java components that represents them and simplifies modifying the data they contain. Using entity objects to encapsulate data access and validation related to the tables, any pages you build today or in the future that work with these tables get consistently validated. Since this task is related to the data access and business logic for your application, you'll do it in the context of the Model project. As you work, JDeveloper automatically configures your project to reference any necessary Oracle ADF libraries your application will need at runtime.

2.5.1 Dragging and Dropping to Reverse-Engineer Entity Objects for Tables

You can create business components by using wizards or a diagram. On one hand, the wizards can be faster to use since you can create many components at the same time. For example, in a single step you can create entity objects, related view objects, and an application module to use as your business service with the Business Components from Tables wizard. On the other hand, creating business components on a diagram is often more intuitive and allows you to understand the roles each different kind of business component plays. Since creating business components using the wizards is covered in later chapters, for this walkthrough it is best to take things one steps at a time and work in a visual way.

To create a business components diagram, open the New Gallery and select Business Components Diagram. After creating a new diagram, just drop the tables from the Connection Navigator onto the diagram surface to create entity objects for them. By default, the entity objects get named Users, ExpertiseAreas, and Products based on the names of the tables. Since an entity object represents a single element of business domain data, it's best practice to name them with singular names. You can use the diagram's in-place editing support to rename the entity objects to User, ExpertiseArea, and Product. JDeveloper has extensive support for refactoring to automate changing any related files to use the new names. In addition to the entity objects that were created, the tool also created associations that reflect the foreign keys relating the underlying tables. To help communicate how your entity objects are related to the tables, you can add the tables themselves to the same diagram and draw dependency lines between them, as shown in Figure 2-6.

Figure 2-6 Business Components Diagram Showing Entity Objects and Related Tables

2.5.2 Adding Business Validation Rules to Your Entity Object

Your set of associated entity objects represents a reusable layer of business domain components. Any business validation rules you enforce at this level are enforced consistently throughout any applications you build that satisfy use cases related to Users, ExpertiseAreas, and Products. This applies regardless of the user interface technology that you use. This guide focuses attention on developing web applications with JSF, but validation rules encapsulated in your business domain layer work the same whether used through web, wireless, or Swing user interfaces, as well as through web services. The validation rules can range from the simplest syntactic value-checking to the most complicated enterprise database-backed programmatic rules.

By double-clicking the Users entity object in the diagram, you can access the Entity Object Editor to define declarative validation rules for users. Open the Validation page of the editor to add validation rules. Click New to add a new rule, and add a UniqueKey Validator that will ensure that the primary key for new User rows is unique. As shown in Figure 2-7, you can enter a validation error message that the manager will see if she enters a new user whose ID is already taken. JDeveloper saves the error message in a standard Java message bundle to simplify localizing it for different languages.

Figure 2-7 Adding a New UniqueKey Validator

Next, you could add a regular expression validator on the Email attribute to ensure that managers only enter email address in the expected 8-character, lowercase format. Selecting the Email attribute in the Declarared Validation Rules tree and clicking New again, you can add a Regular Expression Validator. Figure 2-8 shows the regular expression to match from three to eight lowercase characters, and the error message that will appear if the manager enters an email in the wrong format.

Figure 2-8 The Regular Expression Validator Ensures That Email Address Is Correctly Formatted

Select the UserRole attribute and click New to add a List Validator as shown in Figure 2-9 to ensure that the role of a new user can only be user, technician, or manager. Again, you can enter the error message the manager will see if she enters the data incorrectly.

Figure 2-9 The List Validator Ensures That UserRole Has One of Three Legal Values

After doing this, you can see, as shown in Figure 2-10, that all the validation rules in effect are summarized on the Validation page of the Entity Object Editor.

Figure 2-10 The Validation Page Provides One Place to See All Validation Rules in Effect

In a real-world application, you would go on to add a number of method validators that invoke custom validation event handlers that you write in Java. Like the built-in validations, these can be attribute-level rules if they are related just to one specific attribute, or entity-level validation rules if they are more complex and involve consulting multiple attribute values or other entities to determine validity. The code you would write inside the validation events can easily access the properties of any entity object in your business domain layer, or easily perform any SQL query, as part of determining if the method-based validation rule should succeed or fail the validation check.

If you notice a pattern in the kind of custom Java-based validations your team is performing, you can extend the set of built-in validation rules in JDeveloper with custom, parameter-driven rules of your own. Custom rules allow other developers on your team to reuse the common validation patterns in their future work without writing code themselves. Instead they pick your custom validation rule from a list and set a few properties. Either way, whether business rules are implemented declaratively or using validation event handlers written in Java, they all appear in the Validation page of the Entity Object Editor, so that you have a single place to see all business rules in effect for that object.

2.5.3 Defining UI Control Hints for Your Entity Objects

In addition to business rules, other useful resources you can centralize in your entity object layer are the standard UI labels and format masks that your business information will use throughout all applications you build. By opening the Entity Object Editor and selecting individual attributes, you can use the Control Hints tab to define the Label Text, Tooltip Text, Format Type, Format mask and other hints. Since these user-visible labels and format masks need to be sensitive to the preferred language of the end user, JDeveloper manages them for you in a standard Java resource bundle. This way, they are straightforward to translate into other locales for creating multilingual applications.

Assume you've edited the User, ExpertiseArea, and Product entities to define label text hints for all the attributes. You'll see later in the walkthrough how these centralized UI label hints are automatically leveraged in the pages you build that work with data related to these entity objects.