The Open For Business Project

Quick Start Guide

Brett G. Palmer
[email protected]
Updated January 20, 2003

Table of Contents

Introduction
Comparing OFBiz with Other Open Source Projects
Getting Started
Separating the Entity Engine from the Rest
Creating Your First Web Application
Conclusion
References

Introduction

The purpose of this document is to assist people interested in the Open For Business (OFBiz) project to get started as quickly as possible. I have been using the OFBiz framework for a few
months now and have found it to be very helpful in building Java based web applications. There are a lot of components that can significantly reduce the cost of your project. Unfortunately,
like many open source products the documentation is fairly light. This document does not cover everything in detail but does provide some helpful tips to help you started. This Quick Start
document will cover the following topics:

Comparing OFBiz with other projects

Using the Entity engine
Creating web applications through the web controller

Comparing Ofbiz with Other Open Source Projects 

If you found OFBiz chances are you have seen several other open source projects. What makes OFBiz different than most of these projects is that OFBiz is an entire framework of
components and tools to help develop web applications in Java. A good web application is broken down into different logical layers. There is a web or presentation layer, a business logic
layer, and a database or persistent layer. Frameworks such as Struts, Cocoon, and Velocity focus primarily on the web tier. Struts for example, follows a model-view-controller (MVC)
architecture for combining JSP pages with Java Beans or Action classes as they are called. Struts is a very good framework for building web applications but it does not provide components
for accessing databases or controlling workflow. These components you are expected to build yourself. This is where OFBiz differs from many other open source Java projects. If you’re
already working with another Java framework such as Struts you could easily include some of the OFBiz components into your project.

Getting Started 

The easiest way to get started with OFBiz is to download the ofbiz-XX-XX-complete.zip version of the source. This is significantly bigger than the ofbiz-XX-XX-src.zip version because it
includes the entire download of Catalina (Tomcat 4.X), but if you can afford the download time it will be worth it. The complete version comes with several scripts (e.g. ofbiz.bat ) that will
start Catalina with the OFBiz components installed and running without any compiling. And if you have Jakarata Ant you will be able to build the source without modifying anything. This
will save you a lot of time at first. I wouldn’t recommend getting the source from CVS or the even downloading the "source only" version until you are more familiar with OFBiz and its
components. Otherwise you will spend a considerable amount of time setting up classpaths and configuration files.

Requirements:

1. Apache's Ant 1.5 (I have also used 1.4.1 without any problem)
2. ofbiz-XXX-XXX-complete.zip or ofbiz-XXX-XXX-complete.tgz
3. JDK 1.3.x. I was able to run OFBiz with JDK 1.4 but compiling gave me several deprecation warnings.

Recommendations:

1. Learn the Entity Engine

2. Create a small web application

Separating the Entity Engine from Other Components

Getting the sample applications (e.g. E-commerce application) up and running is fairly straightforward, but working with the components separately can be difficult but not impossible. The
difficult part is learning how to configure the components independently from the other components. This section demonstrates how the OFBiz entity engine can be configured and tested
separately from the other components. Working with individual OFBiz components can help you learn more quickly the OFBiz framework.

OFBiz's entity engine is one of the most mature components and I think one of its greatest assets. Writing persistent layer code in JDBC may not be that difficult but it can take a lot of time
and is error prone. OFBiz's entity engine can greatly simplify writing database components and lets you focus on the business logic of the application.

A good strategy for working with the OFBiz entity engine is to create your own JUnit tests that verify that your entity definitions are setup and working correctly. I like the Extreme
Programming (XP) philosophy of code a little, test a little, etc. This is also a good method for maintaining and testing your code base. This is not a tutorial on JUnit for more information
JUnit see the references section below. I have found this to be a good way to work with the OFBiz entity engine components.

Key Files:

entityengine.xml - defines your database delegator and entity definitions to include in your project.
entitygroup.xml - works alongside the entityengine.xml file to group entity definitions into specific group
entity_<your_entity_defs>.xml - your own custom entity definition file

Configuration Steps

Here are some steps you can use to help you understand how to configure the OFBiz entity engine. I use JBuilder 5.0 Professional for my development. Some of my examples will be specific
to JBuilder, but you should be able extract the necessary information for you development environment.

1. Define your own entity definition and place it in the <OFBIZ_HOME>\commonapp\entitydefs directory. For example, if I was building a online bookstore I might have a entity definition file entitymodel_bookstore.xml. For
specific examples of entity definitions look at the entitymodel_order.xml and entitymodel_product.xml definitions that are part of the OFBiz E-commerce application.

2. Modify the entityengine.xml file in the <OFBIZ_HOME>\commonapp\etc directory. You need to include your own entity definition in the entityengine.xml file. Here is an example of how this could be entered for step1 above.
<entity-model-reader name="main">

<resource loader="mainfile" location="entitymodel.xml"/>

<resource loader="mainfile" location="entitymodel_bookstore.xml"/>

</entity-model-reader>

3. Define your datasource(s) in the entityengine.xml file. You access your entities through a GenericDelegator. The delegators are specified in the entityengine.xml file. You can have multiple delegators and multiple datasources
defined in the entityengine.xml file. Here is an example of a delegator and datasource configuration.

<delegator name="default" entity-model-reader="main" entity-group-reader="main">

<group-map group-name="org.ofbiz.commonapp" datasource-name="localhsql"/>

<group-map group-name="com.mybookstore.bookstore" datasource-name="other_datasource"/>

</delegator>

<datasource name="localhsql"

helper-class="org.ofbiz.core.entity.GenericHelperDAO"

field-type-name="hsql"

check-on-start="true"

add-missing-on-start="true";

use-foreign-keys="true";

use-foreign-keys-indices="true";

use-fk-initially-deferred="false";

join-style="theta-oracle">

<sql-load-path path="commonapp/db" prepend-env="ofbiz.home"/>

<sql-load-path path="ecommerce/etc" prepend-env="ofbiz.home"/>

<inline-jdbc

jdbc-driver="org.hsqldb.jdbcDriver"

jdbc-uri="jdbc:hsqldb:../../data/ofbiz"

jdbc-username="sa"

jdbc-password=""

isolation-level="ReadUncommitted"/>

<!-- <jndi-jdbc jndi-server-name="localjndi" jndi-name="java:/HsqlDataSource"/> -->

</datasource>

This delegator example uses the OFBiz 'default' delegator. The example demonstrates how you can use 'group-maps' to group components into different data sources. In this example all of the org.ofbiz.commonapp components use the
localhsql (hypersonic database) and the com.mybookstore.bookstore components use the 'other_datasource' data source. This feature let you use different databases from a single delegator.

4. Modify the entitygroup.xml file in the <OFBIZ_HOME>\commonapp\entitydef directory. This is important point that I often forget when setting up new entity definitions. If you forget to include new entity definitions in the
entitygroup.xml file you entities will not be dynamically created when you start the delegator. And any code that tries to access these entities will fail.

<!-- ========================================================= -->

<! - Bookstore Entities -->

<!-- ========================================================= -->

<entity-group group="com.mybookstore.bookstore" entity="Store" />

<entity-group group="com.mybookstore.bookstore" entity="Books" />

<entity-group group="com.mybookstore.bookstore " entity="Authors" />

In the above example, I have defined three entities that are included in the entitymodel_bookstore.xml. Note also that these entities belong to the group com.mybookstore.bookstore which we defined in the entityengine.xml in step 3.
This means the entity tables for Store, Books, and Authors will be found in the 'other_datasource' configuration.

JBuilder Setup

Steps 5 through 8 describe how to setup an OFBiz entity project in JBuilder. Your development environment may be different but hopefully you can extract the necessary information to get an
OFBiz entity project setup in your Java IDE. I like to use a combination of an IDE for source level debugging and the OFBiz Ant scripts to build, setup, and deploy the entire web application.
For this reason I keep the configuration files in the same location for both development environments.

5. Setup you source paths in your JBuilder project. If your project just involves the entity engine then the minimal source paths you will need are the following:

<OFBIZ_HOME>\core\src\entity
<OFBIZ_HOME>\core\src\share
Any of you own source directories

You can add other source directories to your project as you need them.

6. Add the necessary libraries to compile your project. To avoid conflicts with the JBuilder build and the OFBiz Ant builds I only include the libraries necessary to build the source. You could build all the OFBiz libraries and
include them in your project but then when you try to build using Ant you have to close JBuilder since it has the libraries open. The necessary Jar files can be found in the following directories:

<OFBIZ_HOME>\lib\compile
<OFBIZ_HOME>\lib\common
<OFBIZ_HOME>\lib\share

7. To run a test against your entity engine configuration you need to setup some environment variables within JBuilder. Many of the OFBiz components work from the relative path of the ofbiz.home environment variable. You can
specify this environment variable in the Projects Run tab under the category VM parameters (e.g. '-Dofbiz.home=c:\ofbiz\ofbiz')

8. There are some other files that need to be in your classpath for the entity engine to function properly. JBuilder seems to only allow directories or Jar files to be added to a classpath. To work around this limitation I created Jar
files for the specific files that I needed. Then I added these Jar files to my project like the other libraries I added in step 6. Note: this is only a problem in running the entity engine from within JBuilder. The OFBiz Ant builds put
all the files in their appropriate Jar files during deployment. The files that you need are the entityengine.xml and the DTD files that define XML schemas. These can be found in the following directories:

<OFBIZ_HOME>\commonapp\etc - contains the entityengine.xml file

<OFBIZ_HOME>\core\docs\xmldefs\ofbiz - contains all the DTD files for the OFBiz components.

For the etc directory I create the jar file as follows:

jar cvf ofbiz_etc.jar *.xml

And for the DTD files I include all of them with the command:

jar cvf ofbiz_dtd.jar *

9. It should be noted that the OFBiz Ant build puts all the DTD files in the core/lib/ofbcore-share.jar file which you could use except you will get conflicts when you try to build with Ant while having JBuilder running.

10. Create your JUnit test to validate your entity definitions. Here is an example of a method that validates my entity code:

public void testFindByPrimaryKey() {

try {

Debug.logInfo("Entered testFindByPrimaryKey");

//Instantiate the delegator.

GenericDelegator delegator = GenericDelegator.getGenericDelegator("default");

assertNotNull("Error creating delegator object", delegator);

//Create an Book Entity

String bookId = delegator.getNextSeqId("Book").toString();

GenericValue bookValue = delegator.makeValue("Book",

UtilMisc.toMap("bookId", bookId,

"author", "Joe Smith',

"name", "My Favorite Book",

"publisher", "Some Publisher"));

GenericValue book = delegator.create(bookValue);

assertNotNull("Couldn't create Book entity", book);

// Find book by primary key

GenericValue foundBook = delegator.findByPrimaryKey("Book",

UtilMisc.toMap("bookId", bookId));

assertNotNull("Couldn't find Book: " + bookId, foundBook);

Creating Your First Web Application

Again the easiest way to learn OFBiz is to start using it and the easiest way to learn the OFBiz web controller is to use one existing web application that is already setup. For example in the
<OFBIZ_HOME> directory there is a ecommerce, ordermgr, workeffort, and webtools application. Each of the projects includes a webapps directory where all the JSP and control files
exists. You need to become familiar with the following files when dealing with the web controller. .

Key Files:

<CATALINA_HOME>\conf\server.xml - contains the context settings for your OFBiz web applications when Catalina is started.
controller.xml - OFBiz's web controller configuration file that is contained in each applications WEB-INF directory.
regions.xml - file to organize JSP pages into different sections of an HTML page. This allows you to create custom header, footer, sidebars, and menus and share them across several
JSP pages. This file is also located in the applications WEB-INF directory for each application.

Here are some steps you can take to quickly get a web application working in OFBiz:

1. Copy an existing OFBiz application to a start a new web application and change the name to your application. For example, you could copy the existing ecommerce directory and create
a new directory called 'bookstore'. Later you will have to remove some of the directories in the webapps directory that you won’t be using,. Now you have a working skeleton of files
and directories that adhere to the OFBiz development environment and you can start making changes to this new application without breaking the existing applications that come with
OFBiz.
2. Modify catalina's server.xml file to include the new application. Since the OFBiz applications are not contained in catalina’s default webapps directory (i.e.
<CATALINA_HOME\webapps) you need to add a new 'context' entry in catalina’s server.xml file as follows:

<Context path="/your_webapp" docBase="../../ofbiz/your_webapp/webapp"

debug="0" reloadable="true">

<Logger className="org.apache.catalina.logger.FileLogger"

prefix="your_webapp_log." suffix=".txt" timestamp="true"/>

</Context>

3. Create a link to a service that you can access from your browser. This is done by making an entry in the controller.xml file in your applications WEB-INF directory. Here is an example
of an entry.

<request-map uri="listbooks"><security https="true" auth="false"/>

<event type="java" path="com.mybookstore.books.BookEvents" invoke="listBooks"/>

<response name="success" type="view" value="listbooks"/>

<response name="error" type="view" value="error"/>

</request-map>

<view-map name="listbooks" type="region"/>

Assuming the default context for my application is 'bookstore', you would access the above URI by putting in http://localhost:8080\bookstore\control\listbooks in your browser if you
were running Catalina locally. The OFBiz web controller would then execute the method 'listBooks' in the BookEvents class. If the listBooks method returned the string 'success' the
controller would pass the response to a 'view' called 'listbooks.' If an error occurred the controller would pass the response to the 'error' view. Views in OFBiz are mapped to a region.
Regions are specified in the regions.xml file explained in step 4. The example shows a Java event but there are other event types that you can use. See the OFBiz documents for more
details on the other event services that are available.

4. Create the appropriate responses and views for the new service. Views let you combine JSP pages into a single HTML page. This lets you create headers, footers, menus, etc. The
ecommerce application has lots of example such as a dynamic shopping cart that displays your current purchases while you are browsing other merchandise. The view is the final
format of the response of your request. Here an example of a view definition for 'listbooks' that was shown in step 3.

<define id='listbooks' region='LEFT_ONLY_REGION'>

<put section='title'>List of Books</put>

<put section='content' content='/books/listbooks.jsp'/>

</define>

<define id='LEFT_ONLY_REGION' region='MAIN_REGION'>

<put section='leftbar' content='LEFTBAR_REGION'/>

</define>

<define id='LEFTBAR_REGION' template='/templates/leftbar_template.jsp'>

<put section='first' content='/menus/adminmenu.jsp'/>

<put section='second' content='/menus/customermenu.jsp'/>

</define>

5. Remove links that are not part of the new application. Since you copied an existing application to get started once you get familiar with how the web controller works you will won’t to
clean up the irrelevant links and files.
6. Continue to learn and develop new services that are available from OFBiz. This example only touched on a simple Java event. There are other event types that can be used as well as a
rules and workflow engine. Once you get familiar with the basics of OFBiz you should start investigating many of the other features of OFBiz.

Conclusion

This document provides some tips for starting with OFBiz. There are many other topics that are not covered in this document. If you find errors in this document please forward them to me
and I will make the corrections. Also, if there are other tips or helps you would like included in this document please let me know. The OFBiz project has many components that you can
include in your project. Some of these components include a rules engine, workflow engine, and simple languages. Future 'Quick Tips' documents on these topics will be forth coming.

References 

Open For Business Project: www.ofbiz.org

Ant: http://jakarta.apache.org/ant/index.html
JUnit: www.junit.org
Struts: http://jakarta.apache.org/struts/index.html
Cocoon: http://xml.apache.org/cocoon/index.html
Velocity: http://jakarta.apache.org/velocity/index.html