A template for OpenJPA Samples¶

Introduction¶

A paragraph describing the basic purpose of the presented sample. In general, the purpose of a sample could be, but not limited to,

• to highlight some new feature introduced in a release (e.g. Bean Validation or Criteria API)
• to describe wiring between frameworks e.g. JSF and JPA, GWT and JPA
• to demonstrate operation within a container e.g. OSGi, Spring, Tomcat or JEE
• a combination of the above

For example,
"this sample demonstrates usage of new Bean Validation API in a multi-tier web application" or "this sample integrates client-side Google Web Toolkit architecture with sever-side JPA application".

The functional features of the samples such as "This OpenBooks example can be used to place order and browse books" -- are not that important in this context but can be mentioned.

Installation¶

State the availability of the sample. For example,

• Is the distribution available as a downloadable archieve? If packaged in an archieve, all source code, build instructions must be available in the distribution itself. A README.txt should be inside and outside the distribution.

• Is the sample to be checked out from code repository? In such cases, building the sample should be done with Ant or Maven. Prefer Ant to make the dependencies and steps more visible.

The steps in this section should be clear and concise for an user to follow them to build, deploy and run the sample.

Environment¶

Enumerate the software artifacts required to build, deploy and run the sample. The artifacts should be categorized into build time and run time dependencies.

Configuration¶

Often building a sample will require the user to configure dependencies (such as OpenJPA libraries or JDBC Driver), for his/her local environment. The ANT build scripts for a sample must accept configurable properties via build.properties or similar configurable mechanics. The properties configuration file itself should be documented to explain the dependencies and how the build script use them. Maven based build scripts can make these dependencies more implicit and saves the user to explicitly satisfy such dependencies. However, ANT based builds are preferred over Maven for the samples, so that the build steps and dependencies are made more visible to the user.

Best Practices¶

The samples, besides demonstration of a feature, are a suitable vehicle of showing good development practices in JPA application programming model such as persistent domain modeling or architectural practices. It is recommended that such best practices be mentioned in several places:

• in the source code
• build scripts
• a separate document that enumerates them in one place.

Caveats¶

The complete develop-build-run cycle of a sample will often bring out the special considerations. For example, reported common errors in deployment in a container and their remedies or certain undesirable usage patterns. The description of a sample should highlight these special considerations rather than making the exercise appear as a series of perfectly easy steps. The caveats can be further highlighted by linking them to relevant JIRA issues or forum discussions or external blogs etc.