Best Practices Guide

Written By: David E. Jones, jonesde@ofbiz.org

Table of Contents 

• Introduction
• General Concepts
• Data Layer
• Logic Layer
• Presentation Layer
• Before Starting - Methodology Recommendations
• Managing Your Source Differences

Introduction

This documents presents best-practices for development and architecture related to The Open For Business Project.

...

Note that this document assumes some knowledge of the OFBiz Core Framework. With some basic knowledge it can answer a lot of questions about how certain things should be used. If you are not familiar with the OFBiz Core Framework this will give you an introduction to it, but some things may not make a lot of sense to you.

General Concepts

Reduce Code Redundancy & Size

There are various techniques that can be applied to this problem that produce good results. The most common, but least effective, practice is code generation. Because it is not something that I consider to be a best practice, I won't discuss it further here.

...

A special purpose language is used to create logic in a language or using a tool that fits the specific need more appropriately than a general purpose procedural language like Java. This reduces code because it is easier to describe what you want in a context that closely matches the problem that needs to be solved than it is to use a generic language. High level conepts can be expressed without the need to write a lot of code.

Data Layer

The best-practice tool to use in the data layer is the OFBiz Entity Engine. For most applications the Entity Engine will elegantly do the work for 99% of your database interaction needs. In the few cases where the Entity Engine is not sufficient I recommend using custom JDBC code for your queries or other commands. That would be one of the second-best-practices that are sometimes needed.

...

Always use primary keys and avoid the use of generic sequenced primary keys when a more descriptive composite key is possible. Always use relationship definitions to document how entities are used together, to make it easier to get at related data, to constrain field by foreign keys, and to improve performance through automatic foreign key based indexes.

Logic Layer

The best tool to use for invoking logic is the OFBiz Service Engine. Nearly all business logic should be implemented as a service to improve reusability and facilitate component based development.

...

Most of the time you will want to let the Service Engine automatically wrap your service call in a transaciton so that the whole thing will succeed, or the whole thing will fail. Note that if you call a service inside an existing transaction it will recognize the current transaction and use it instead of trying to create another one.

Presentation Layer

Always separate input processing logic, view data preparation logic, and view presentation templates. This will make it easy to reuse logic not only in web applications, but also for independent fat client applications. It will also make it easier to organize your code and find a specific piece of functionality when debugging or exploring to find out how a component works.

For each of the three separate pieces there are special best-practices tools to use.

Input Processing Logic

Input processing logic should always be associated with a request in the controller.xml file and never with a view. Input processing logic should generally be implemented as a service and called through the service event handler which will automatically pull data from request parameters or attributes and convert it from a string to the object type defined in the service definition. This makes it easy to specify which parameters you care about processing just using the service definition, and let the framework get them ready for you.

...

Always let the Control Servlet configuration handle decisions about the appropriate response to take for a request given the result string from an event. In most cases the response will be the generation of a view, but sometimes it will make sense to chain requests together to acheive logic reuse or more advanced flow control.

View Data Preparation Logic

View data preparation logic should always be associated with the view template it is meant to prepare data for. This should be done through the OFBiz Screen Widget in the screen definition XML file by specifying a script action. When a screen is split up into multiple templates or screens the data preparation action should be associated only with the individual small screen that it prepares data for. This makes it easier to move templates and content pieces around and reuse them in many places.

...

Note that when using JSP for a view template you cannot use JPublish so the actions facility will not be available. Our recommendation for JSPs is to have a single scriplet at the top of the page that prepares the data. In this case try to call worker services or worker Java methods to do most of the work and to keep as much logic as possible out of the page.

View Presentation Templates

The best-practice template engine that we recommend for HTML and other text generation is FreeMarker. It is like Velocity from Jakarta, but much more flexible and fits in nicely with other OFBiz Core Framework tools. Rather than running FreeMarker templates directly we strongly recommend using the OFBiz Screen Widget so that actions can be associated with screens and they can be decorated with common templates. We'll describe how to best use this below.

...

When using FreeMarker is not possible or practical we recommend using another dynamic templating language such as Velocity. When that is also not possible or practical we recommend using JSPs. But, note that when using JSPs you cannot take advantage of the actions or decoration templates because you cannot run it through JPublish. This is thanks to limitations in the JSP specification. Even through you cannot use the decorator patter, you can use the composite view pattern with the OFBiz Regions framework. Regions are specified in the regions.xml file. Note that these are not as easy to use as Screen Widget composite views, and they do not support actions. But the Regions framework does offer a lot of flexibility and is very useful in many cases.

Before Starting - Metodology Recommendations 

Before you can build something that something has to be defined. Every detail has to be decided at some point. Because of the difficulty of communication between individuals and the difficulties that are inherently involved in complex systems we recommend various practices.

While these techniques are used for some components in the core Open For Business functionality they are primarily meant for those who are creating derivative works based on OFBiz. The reason for this is that OFBiz is a generic framework, set of application components and suite of applications. In many cases these applications can be used as is but they are not meant to be everything to everyone. Because of this work will likely be needed for derivative works that are targeted at a specific industry, type of business, or specific end user.

Methodology: Keep it simple, but not too simple

There are dozens of different software development methodologies, and more are being introducted all the time. There are lots of good ideas presented in the hundreds, or even thousands, of documents available about different methodologies. In general we recommend the "agile" approach, but that needs to be qualified given the different perspectives that have been attached to that name. In general we recommend keeping it as simple as possible, but not too simple. For more specifics on agile software development see the Agile Alliance web site.

So the big question is generally: what is the minimum that we need to handle this project? The more methodology you have the more time and money you will spend on it. The less methodology you have the greater the chance that the requirements of the project will not be satisfied.

Minimal Roles

There are really only two roles necessary for any project: a buyer and a seller. In the case of software projects, and other service offerings, the more common terms are customer and developer. Those are the terms that will be used in this document. The term developer is used loosely here and refers to anyone that produces actual deliverables. The term customer is also used loosely here and refers to anyone that specifies what will be done and pays for it to be done. In some cases the customer and developer will be the same person, or the same group of people.

...

Another variation on this is where a group creates a product targeted at hundreds or thousands of customers. In this case the "customer" that defines the product will be part of the same organization that produces the product. Given the definition of customer above the sales, marketing, and testing groups should be in the customer group, and an agent from that combined group should coordinate with the development group.

Minimal Communication

The biggest trick with communication is to find the balance between to much and too little communication. The burden for this is generally on the customer because it is customer that specifies what will be build. Like I said at the beginning of this section everything that will be built MUST be defined sooner or later. Anything that is not specified by the customer can be handled in one of two ways. The developer can decide what will fit into the gaps or the developer can request clarification and details from the customer.

To facilitate communication and make sure that the final result satisfies the needs requested by the customer the following process is recommended.

Minimal Process

One important aspect of this process is that it should be repeated frequently and the scope for each pass should be kept small so that when miscommunications occur they can be identified and resolved quickly.

...

Defining tasks is generally fairly simple and should be done by the developer in a form and using terms that the developer will understand. There is a lot of meta-data that is generally associated with such a task. Examples include esimated and actual time and cost, start and end dates, all parties performing or otherwise involved with the task, and so on.

Conclusion

Some basic preparations should always be done before getting into the implementation. Some basic principles and a basic process has been presented. Because of the nature of how most projects work all of the steps in the process will be done in one way or another. Following this process does not require the creation of any written documents, although in many cases that will help quite a lot. It can be done through verbal conversation, or even a series of thoughts inside one's head.

The process described is meant to be customized to your needs. Following it as is should do for most medium sized projects. When there is only one or two individuals involved, or tens or hundreds of individuals, changes will obviously be desired. When modifying the process keep in mind the basic principles presented and be especially careful about leaving out communication steps, espcially the communication verification steps.

Managing Your Source Differences

When customizing OFBiz components for your specific business requirements you will most likely come across situations where small changes to files are needed and it doesn't make sense to replace a component completely or attach logic to it through Service ECA rules or other means. So, how should you manage the differences between your code and the OFBiz baseline code so that updating from the OFBiz baseline will be as painless as possible?

...

We have heard a lot of questions about using simple merge scripts to apply differences to source in the ofbizdiff tree so that full files do not have to be stored ant maintained there. This is fine, but it is a LOT harder to perform the diff/merge or other code synchronization when you don't have the complete files to do a three way diff/merge. So, we don't recommend using minimal diff files that can be applied as part of preparation for the build process. Just copy the file from ofbizbase to ofbizdiff and make the changes you need as recommended above.

For Those Comfortable With CVS Branching/Merging

If you are comfortable with the branching and merging features in CVS you can use those very effectively to easily maintain you differences from the OFBiz base source tree, and still keep up-to-date with the latest from OFBiz without too much trouble. CVS does three-way diff/merge operations all the time when doing updates, and this same feature can be used to do the three-way diff/merge described above, but in an automatic way that only requires your involvement for merge collisions.
To get started do a fresh checkout from the OFBiz CVS repository, then remove all CVS directories and import the tree into a new module in your local CVS repository. Tag this set of files with a name like OFBIZ_20030612 (adjust for the current date) using a command like "cvs tag -b OFBIZ_20030612". Now just change/add things as you please. Note that you are not working on that branch, you are working on the HEAD branch unless you do something like "cvs update -rOFBIZ_20030612".

...