User's Manual

Chapter 9.
Persistence Tutorial
This chapter presents a tutorial for using the persistence system. It presumes you are familiar with the
concepts covered in Chapter 2 WAF Component: Persistence.
This tutorial will first discuss using Data Objects, which is followed by a tutorial on using the features
of PDL. Referenced throughout this tutorial is the Persistence Glossary.
9.1. Data Objects Tutorial
This section has been assembled to help familiarize you with the concepts and functionality of the
persistence layer. This section assumes a familiarity with the concepts discussed in Chapter 2 WAF
Component: Persistence and in Persistence Glossary. It also assumes that the code is being executed
within a standard WAF installation.
This tutorial will walk you through the use of object persistence in the WAF. It begins by showing you
how to ensure that your server is set up correctly so that the PDL will compile. It then continues with
a simple example of how to create a PDL file and how to write the corresponding Java code to interact
with the database.
After covering the basics of using standalone Data Objects, the tutorial describes how to associate
objects to each other. It discusses several examples, including how to retrieve Data Objects through
arbitrary queries. The tutorial concludes with a list of common mistakes that are made by developers.
9.2. Beginning With Data Objects
This section starts with the basic steps that are required to access information in the database using the
persistence layer. It begins by discussing PDL and Data Objects. It then discusses how to create the
database schema and how it can be represented in PDL. Finally, it covers using the properties defined
in the PDL to access the database in your Java code.
9.2.1. Data Objects and PDL: How are they related?
The persistence layer can be looked at as a way to access objects within the database. Examples of
objects that can be stored in the database are Users, Groups, Articles, Images, and Email Addresses.
In order to abstract out the information regarding object storage within the database, the persistence
layer has implemented the concept of a single Data Object. Data Objects are used by Java classes
to handle all interaction with the database. Because this class is provided, other classes do not need
to know how to create, retrieve, update, or delete a given object. Data Objects are defined by their
Attributes and Object Key.
Every Data Object is associated with a single Object Type. Every object type, in turn, is associated
with events and operations that specify how information is stored in the database and how information
in the database is mapped to Java variables. The role of the PDL file (see Section 9.2.3.1 The PDL
File) is to provide developers with a mechanism to easily specify that object type.
9.2.2. Setting up the Schema
When defining your persistence layer, you need to work through two aspects of your design:
• A UML model of your Data Objects.