As a bakery, we manufacture edible products based on recipes mom brought over from the old country. There are many different types of recipes in our collection, including, but not limited to cakes, cookies, pies, bread, and for those dog lovers, dog treats. We should note here that the number of different types of recipes, and thus the goods we plan to bake using these recipes, should remain open ended and not be limited to the initial five identified.

Within each recipe is a sequential list of ingredients. Each ingredient has a value that represents the amount of the ingredient to use in the recipe and a unit of measure indicator. For example, a recipe may have an ingredient of flour, with an amount of "5" and a unit of measure of "cup". To keep things simple, we shall not consider the list of ingredients as steps in the mixing and/or baking process.

The data model for our additions to OFBiz are graphically depicted in the following figure. We will be adding four new entities: Recipe, Ingredient, RecipeType, and RecipeIngredient, each with primary and foreign keys shown here:

In addition to the four new entities shown in the figure, we shall use the existing Uom entity to give our ingredients access to several hundred standardized units of measure (UOM) values already preloaded in the database.

Based on our business case and data model, we need to create five new entities. Definitions for each of these entities are shown below. We may either create a new entity definition file and update the component.xml file with the new entity definition file location, or add these entities to an existing entity definition file. In the interest of time, we shall add these to an existing entity definition file.

In the following entity definitions, notice that we use a package name of org.ofbiz.bakery. We are using this name specifically so that we may easily find our entities when using the WebTools Interactive Entity Reference utility. As this tool groups together like-named packages, finding a particular entity is made much easier when using a meaningful package name.

The following defines the Ingredient entity:

<entity entity-name="Ingredient"
package-name="org.ofbiz.bakery"
title=
"One record for each ingredient that makes up a recipe">
<field name="ingredientId" type="id-ne"></field>
<field name="ingredientName" type="id"></field>
<!-- Note: some day make an IngredientType entity -->
<field name="ingredientType" type="id"></field>
<field name="packagingUomId" type="id"></field>
<prim-key field="ingredientId"/>
<relation type="one" fk-name="REC_ING_UOM" rel-entity-name="Uom">
<key-map field-name="packagingUomId" rel-field-name="uomId"/>
</relation>
</entity>

The RecipeType entity that holds information about the type of recipe (cookies, cakes and so on) may be defined as follows:

<entity entity-name="RecipeType"
package-name="org.ofbiz.bakery"
title=
"Recipes come in all shapes and sizes. Keep that info here.">
<field name="recipeTypeId" type="id-ne"></field>
<field name="description" type="description"></field>
<prim-key field="recipeTypeId"/>
</entity>

A Recipe entity with the unique recipe identifier, a recipe name, and pointers to other related entities (foreign keys) is given here:

<entity entity-name="Recipe"
package-name="org.ofbiz.bakery"
title="Recipe holds information about our recipes">
<field name="recipeId" type="id-ne"></field>
<field name="recipeName" type="id-long"></field>
<field name="recipeTypeId" type="id"></field>
<field name="notes" type="very-long"></field>
<prim-key field="recipeId"/>
<relation type="one" fk-name="REC_TO_TYPE"
rel-entity-name="RecipeType">
<key-map field-name="recipeTypeId"/>
</relation>
</entity>

And finally, the entity that ties the recipe with its ingredients is defined here:

<entity entity-name="RecipeIngredient"
package-name="org.ofbiz.bakery"
title=
"A recipe is nothing more than a collection of ingredients.
Here's where the rubber meets the road.">
<field name="recipeId" type="id-ne"></field>
<field name="recipeSeqNo" type="numeric"></field>
<field name="ingredientId" type="id-ne"></field>
<field name="amountUomId" type="id"></field>
<field name="amount" type="numeric"></field>
<field name="fromDate" type="date-time"></field>
<field name="thruDate" type="date-time"></field>
<prim-key field="recipeId"/>
<prim-key field="recipeSeqNumber"/>
<prim-key field="fromDate"/>
<relation type="one" fk-name="REC_ING_ING"
rel-entity-name="Ingredient">
<key-map field-name="ingredientId"/>
</relation>
<relation type="one" fk-name="REC_AMT_UOM" rel-entity-name="Uom">
<key-map field-name="amountUomId" rel-field-name="uomId"/>
</relation>
</entity>

Once all our new entity definitions are created, the next task is to test these entities to ensure accuracy. An easy and reliable way to begin testing is to first see if the entities are present and viewable using the OFBiz WebTools Entity Reference - Interactive Version. To run this test, restart OFBiz, making sure that no obvious entity-related errors are posted to the command-line window and/or primary OFBiz log file (ofbiz/runtime/ofbiz.log). If errors are encountered during startup, we need to go back and fix our entity definitions.

If OFBiz startup is successful, we may navigate to the WebTools Entity Reference - Interactive Version main web page, and since our new entities were created using the package name org.ofbiz.bakery, we may easily scroll down the left side of the web page to locate our package name and link as shown in the following figure:

From the WebTools Entity Reference - Interactive Version, we may test adding data to our new entities. And so we would, but to speed things up a bit, we shall use the WebTools XML Data Import tool to load data a little at a time—so we can view results—from XML documents that we created offline. For example, here we add data to the RecipeType entity by copying from a text file and then pasting in the XML Import to DataSource tool's HTML form:

To verify that our data is indeed added to the database, use WebTools and list the RecipeType entity as shown here:

So, it looks like we are on the right track with our entity definitions. In the real world, we would be writing an OFBiz webapp to allow for HTML form-based data entry in addition to loading data directly into the database. For the rest of this chapter, we shall assume that the following data has been preloaded:

* Because this field is designated as a foreign key, any values added must already exist in the related table.

** fromDate set to "2010-01-01 00:00:00.000" for all records.

A report we want to produce quickly after going live with our new OFBiz bakery and recipe system is a list of all the recipes by type. For example, a list of all the cookie recipes. To create such a list using our existing data model requires that we access more than one entity. To do that, that is, join together data from multiple entities, we create an OFBiz view-entity.

Our first view-entity will merge together data from the RecipeType and Recipe entity as shown here:

<view-entity entity-name="RecipeTypeView"
package-name="org.ofbiz.bakery"
title="Show all recipes by type">
<member-entity entity-alias="REC" entity-name="Recipe"/>
<member-entity entity-alias="TYP" entity-name="RecipeType"/>
<alias-all entity-alias="REC"/>
<alias-all entity-alias="TYP"/>
<view-link entity-alias="REC" rel-entity-alias="TYP">
<key-map field-name="recipeTypeId"
rel-field-name="recipeTypeId"/>
</view-link>
</view-entity>

Not one to gloat over our success so far using the Entity Engine, the next report will draw from three different tables to list all the recipes with ingredients, by type:

<view-entity entity-name="RecipeTypeAndIngredientsView"
package-name="org.ofbiz.bakery"
title="Show all recipes by type">
<member-entity entity-alias="REC" entity-name="Recipe"/>
<member-entity entity-alias="TYP" entity-name="RecipeType"/>
<member-entity entity-alias="REIN" entity-name="RecipeIngredient"/>
<alias-all entity-alias="REC"/>
<alias-all entity-alias="TYP"/>
<alias-all entity-alias="REIN"/>
<view-link entity-alias="REC" rel-entity-alias="TYP">
<key-map field-name="recipeTypeId"
rel-field-name="recipeTypeId"/>
</view-link>
<!-- Note the order of entity-alias here is important.
Each Recipe record points to one or more
RecipeIngredient records -->
<view-link entity-alias="REC" rel-entity-alias="REIN">
<key-map field-name="recipeId" />
</view-link>
<relation type="many" rel-entity-name="RecipeIngredient">
<key-map field-name="recipeId"/>
</relation>
</view-entity>

With the view-entities in place, we can easily query the database without constructing complex SQL statements. To test that our new view-entities are doing the job, we can use the OFBiz WebTools Entity Reference - Interactive Version to run a quick report as shown here:

That's it. That is how easy it is to augment OFBiz to support additional application data storage needs. Your experiences will be informed by how complex your data model becomes. With OFBiz, you can have your cake and eat it too. You can start by developing a simple prototype as shown in this section, and grow your data management capabilities as your business grows. You can even move your entire database from vendor-to-vendor (tired of Oracle? Ccheckout PostgreSQL, SQL Server, mySQL or just about any database imaginable) without changing a single line of code.

In the next few sections, we shall take a closer look at using some Java application-level tools provided by OFBiz to implement data-driven applications programmatically.