Red Hat Web Application Framework 6.1 User Manual
Red Hat Web Application
Framework 6.1
WAF Developer Guide
Red Hat Web Application Framework 6.1: WAF Developer Guide
Copyright © 2004 by Red Hat, Inc.
Red Hat, Inc.
1801 Varsity Drive
Raleigh NC 27606-2072 USA
Phone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588
Research Triangle Park NC 27709 USA
rhea-dg-waf-en(EN)-6.1-Print-RHI(2004-03-29-T16:20-0800)
Copyright © 2004 by Red Hat, Inc. This material may be distributedonly subject to the terms and conditions set forth in the
Open Publication License, V1.0 or later (the latest version is presentlyavailableat http://www.opencontent.org/openpub/).
Distribution of substantively modified versions of this document is prohibitedwithout the explicit permission of the copyright
holder.
Distribution of the work or derivative of the work in any standard(paper) book form for commercial purposes is prohibited
unless prior permission is obtained from the copyright holder.
Red Hat, Red Hat Network, the Red Hat "ShadowMan" logo, RPM, Maximum RPM, the RPM logo, Linux Library,
PowerTools,Linux Undercover, RHmember, RHmember More, Rough Cuts, Rawhide and all Red Hat-based trademarks and
logos are trademarks or registered trademarks of Red Hat, Inc. in the United States and other countries.
Linux is a registered trademark of Linus Torvalds.
Motif and UNIX are registeredtrademarks of The Open Group.
Intel and Pentium are registered trademarksof Intel Corporation. Itanium and Celeron are trademarksof Intel Corporation.
AMD, Opteron, Athlon, Duron, and K6 are registered trademarks of Advanced Micro Devices, Inc.
Netscape is a registeredtrademark of Netscape Communications Corporation in the United States and other countries.
Java and Swing are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. or other countries.
Oracle is a registered trademark, and Oracle8i, Oracle9i, and interMedia are trademarks or registeredtrademarks of Oracle
Corporation.
Microsoft and Windows are either registered trademarksor trademarks of Microsoft Corporation in the United States and/or
other countries.
SSH and Secure Shell are trademarks of SSH CommunicationsSecurity, Inc.
FireWire is a trademark of Apple Computer Corporation.
IBM, AS/400, OS/400, RS/6000, S/390, and zSeries are registeredtrademarks of International Business Machines
Corporation. eServer, iSeries, and pSeries are trademarks of International Business Machines Corporation.
All other trademarks and copyrights referredto are the property of their respectiveowners.
The GPG fingerprint of the security@redhat.comkey is:
CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E
Table of Contents
Introduction to the WAF Developer Guide........................................................................................i
1. Assumptions About WAF Developers...................................................................................i
2. Document Conventions..........................................................................................................i
3. Code Presentation Conventions ........................................................................................... iv
I. WAF Concepts ..................................................................................................................................i
1. WAF Overview .....................................................................................................................1
1.1. General Architecture ..............................................................................................2
1.2. Features.................................................................................................................. 3
1.3. Applications ........................................................................................................... 6
2. WAF Component: Persistence .............................................................................................. 9
2.1. Persistence Overview............................................................................................. 9
2.2. Object-Relational Mapping.................................................................................... 9
2.3. Persistence Definition Language (PDL) ................................................................9
2.4. Persistence and Domain APIs (DataObject, DataAssociation, DataCollection,
DomainObjects) ..............................................................................................10
2.5. Session and Transaction Management .................................................................10
3. WAF Component: Kernel....................................................................................................11
3.1. Users and Groups.................................................................................................11
3.2. ACSObject ........................................................................................................... 11
3.3. Permissions .......................................................................................................... 11
3.4. Kernel Resources .................................................................................................12
4. WAF Component: Services.................................................................................................13
4.1. Auditing Service ..................................................................................................13
4.2. Categorization Service ......................................................................................... 13
4.3. Formbuilder Service.............................................................................................14
4.4. Globalization Service ...........................................................................................15
4.5. Mail Service .........................................................................................................16
4.6. Messaging Service ...............................................................................................16
4.7. Notification Service .............................................................................................17
4.8. Portal Service ....................................................................................................... 17
4.9. Search Service...................................................................................................... 17
4.10. Workflow Service...............................................................................................17
4.11. Versioning Service .............................................................................................18
5. WAF Component: Presentation...........................................................................................19
5.1. Overview of Presentation Standards ....................................................................19
5.2. CSS and XSLT.....................................................................................................20
5.3. JavaServer Pages (JSP) ........................................................................................ 24
5.4. Bebop - Reusable Web UI Components .............................................................. 25
6. WAF Component: Web....................................................................................................... 31
6.1. Applications ......................................................................................................... 31
6.2. BaseServlet......................................................................................................31
6.3. Dispatcher ............................................................................................................32
II. Equipping Developers.................................................................................................................. 33
7. Developing with WAF ........................................................................................................ 35
7.1. Developer Education............................................................................................ 35
7.2. Third-Party Development Tools........................................................................... 35
7.3. Developer Support ...............................................................................................36
7.4. Setting Up Eclipse and WAF ...............................................................................38
7.5. Using logging for debugging ............................................................................... 42
8. WAF Application Development Tutorial ............................................................................49
8.1. Terms and Assumptions....................................................................................... 49
8.2. Good Practices ..................................................................................................... 49
8.3. Directories in the Work Area ............................................................................... 49
8.4. Build Tools...........................................................................................................50
8.5. Modeling Your Application ................................................................................. 50
8.6. Persistent Object Types........................................................................................ 51
8.7. Java Domain Objects ........................................................................................... 51
8.8. Initializing the Application Runtime Environment.............................................. 57
8.9. Creating a Web Interface......................................................................................58
8.10. Integrating Your Package With CCM Tools ...................................................... 59
8.11. Creating Upgrade Scripts ...................................................................................60
9. Persistence Tutorial.............................................................................................................63
9.1. Data Objects Tutorial ...........................................................................................63
9.2. Beginning With Data Objects .............................................................................. 63
9.3. Associations ......................................................................................................... 70
9.4. Named SQL Events.............................................................................................. 74
9.5. Filtering, Ordering, and Binding Parameters.......................................................79
9.6. Common Mistakes ............................................................................................... 88
9.7. Transaction Management.....................................................................................90
9.8. Link Attributes ..................................................................................................... 91
9.9. Dynamic Object Types.........................................................................................96
9.10. Frequently Asked Questions ..............................................................................97
10. Kernel Tutorial................................................................................................................103
10.1. Permissions Tutorial ........................................................................................ 103
10.2. Domain Objects Tutorial..................................................................................106
10.3. Security Service FAQ....................................................................................... 118
10.4. Extending the Authentication System.............................................................. 121
11. Services Tutorials............................................................................................................123
11.1. Categorization Tutorial ....................................................................................123
11.2. Categorization Scenarios .................................................................................126
11.3. Notification Tutorial......................................................................................... 132
11.4. Workflow Tutorial............................................................................................ 135
11.5. Versioning Tutorial .......................................................................................... 138
11.6. Search Tutorial.................................................................................................146
12. Presentation (Bebop) Tutorial ......................................................................................... 153
12.1. Calling XSLT from a WAF Application .......................................................... 153
12.2. Handling Pre-Formatted Text........................................................................... 153
12.3. Site-Wide Master Pages ................................................................................... 154
12.4. Varying a Shared Layout.................................................................................. 158
12.5. Special-Case Stylesheets.................................................................................. 159
12.6. UI Tutorial........................................................................................................160
12.7. Working With Formbuilder.............................................................................. 161
13. Web Applications Tutorial.............................................................................................. 165
13.1. Support for Globalization ................................................................................165
13.2. Locale Negotiation........................................................................................... 165
13.3. ResourceBundles and MessageCatalogs .......................................................... 166
13.4. Accessing Resources........................................................................................ 167
13.5. Globalization and Bebop.................................................................................. 169
13.6. Localizing Stylesheets ..................................................................................... 170
13.7. Sending Mail Messages ...................................................................................170
14. References..................................................................................................................................173
III. Appendixes................................................................................................................................ 175
A. Bebop Tag Library Reference..........................................................................................177
A.1. Bebop/JSP .........................................................................................................177
A.2. Available Page Definition Tags .........................................................................177
B. PL/SQL Standards............................................................................................................181
B.1. General .............................................................................................................. 181
B.2. Coding Standards .............................................................................................. 181
B.3. Coding Style......................................................................................................183
B.4. Constraint Naming Standards............................................................................ 183
C. Java Standards .................................................................................................................. 187
C.1. WAF Standards..................................................................................................187
C.2. Java Coding Standards — References and Related Reading ............................188
D. PDL Syntax...................................................................................................................... 189
D.1. PDL Grammar................................................................................................... 189
D.2. PDL Reserved Words........................................................................................191
D.3. PDL and SQL Used in the Tutorial...................................................................194
Persistence Glossary ............................................................................................................. 203
Index................................................................................................................................................. 209
Colophon.......................................................................................................................................... 215
Introduction to the WAF Developer Guide
The Red Hat Web Application Framework is a platform for writing database-backed web applications
in Sun’s Java®. Applications leverage Web Application Framework APIs to enable the authoring of
persistent structured data and to retrieve and display the data as content. The framework also integrates
services such as search, versioning, and permissions into its basic objects, enabling applications to
leverage framework services with little or no extra work.
The Web Application Framework domain layer models basic concepts such as users, groups, and
permissions and has been proven and refined on hundreds of production deployments. A user interface
(UI) framework, UI component library designed for the rapid development and reuse of web user
interfaces, and a powerful object-relational persistence engine are also part of the framework.
Please enjoy this guide and report any bugs with the documentation to http://bugzilla.redhat.com/.
Please report using the unique component name for this guide:
rhea-dg-waf-en(EN)-6.1-Print-RHI (2004-03-29-T16:20-0800)
1. Assumptions About WAF Developers
This manual assumes that the reader is familiar with the Java programming language, HTML, and
relational databases. Familiarity with the J2EE Servlet and JSP specifications, XML, and XSLT are
also helpful. An understanding of the UML and basic object-relational mapping concepts will help the
reader understand the persistence system. For more information, see Section 7.1 Developer Education.
2. Document Conventions
When you read this manual, certain words are represented in different fonts, typefaces, sizes, and
weights. This highlighting is systematic; different words are represented in the same style to indicate
their inclusion in a specific category. The types of words that are represented this way include the
following:
command
Linux commands (and other operating system commands, when used) are represented this way.
This style should indicate to you that you can type the word or phrase on the command line
and press [Enter] to invoke a command. Sometimes a command contains words that would be
displayed in a different style on their own (such as file names). In these cases, they are considered
to be part of the command, so the entire phrase is displayed as a command. For example:
Use the cat testfile command to view the contents of a file, named testfile, in the current
working directory.
file name
File names, directory names, paths, and RPM package names are represented this way. This style
should indicate that a particular file or directory exists by that name on your system. Examples:
The .bashrc file in your home directory contains bash shell definitions and aliases for your own
use.
The /etc/fstab file contains information about different system devices and file systems.
Install the webalizer RPM if you want to use a Web server log file analysis program.
ii Introduction to the WAF Developer Guide
application
This style indicates that the program is an end-user application (as opposed to system software).
For example:
Use Mozilla to browse the Web.
[key]
A key on the keyboard is shown in this style. For example:
To use [Tab] completion, type in a character and then press the [Tab] key. Your terminal displays
the list of files in the directory that start with that letter.
[key]-[combination]
A combination of keystrokes is represented in this way. For example:
The [Ctrl]-[Alt]-[Backspace] key combination exits your graphical session and return you to the
graphical login screen or the console.
text found on a GUI interface
A title, word, or phrase found on a GUI interface screen or window is shown in this style. Text
shown in this style is being used to identify a particular GUI screen or an element on a GUI
screen (such as text associated with a checkbox or field). Example:
Select the Require Password checkbox if you would like your screensaver to require a password
before stopping.
top level of a menu on a GUI screen or window
A word in this style indicates that the word is the top level of a pulldown menu. If you click on
the word on the GUI screen, the rest of the menu should appear. For example:
Under File on a GNOME terminal, the New Tab option allows you to open multiple shell
prompts in the same window.
If you need to type in a sequence of commands from a GUI menu, they are shown like the
following example:
Go to Main Menu Button (on the Panel) => Programming => Emacs to start the Emacs text
editor.
button on a GUI screen or window
This style indicates that the text can be found on a clickable button on a GUI screen. For example:
Click on the Back button to return to the webpage you last viewed.
computer output
Text in this style indicates text displayed to a shell prompt such as error messages and responses
to commands. For example:
The ls command displays the contents of a directory. For example:
Desktop about.html logs paulwesterberg.png
Mail backupfiles mail reports
The output returned in response to the command (in this case, the contents of the directory) is
shown in this style.
prompt
A prompt, which is a computer’s way of signifying that it is ready for you to input something, is
shown in this style. Examples:
Introduction to the WAF Developer Guide iii
$
#
[stephen@maturin stephen]$
leopard login:
user input
Text that the user has to type, either on the command line, or into a text box on a GUI screen, is
displayed in this style. In the following example, text is displayed in this style:
To boot your system into the text based installation program, you must type in the text command at the boot: prompt.
replaceable
Text used for examples which is meant to be replaced with data provided by the user is displayed
in this style. In the following example,
The directory for the kernel source is /usr/src/
number
is the version of the kernel installed on this system.
version-numberis displayed in this style:
version-number/, where
version-
Additionally, we use several different strategies to draw your attention to certain pieces of information. In order of how critical the information is to your system, these items are marked as note, tip,
important, caution, or a warning. For example:
Note
Remember that Linux is case sensitive. In other words, a rose is not a ROSE is not a rOsE.
Tip
The directory /usr/share/doc/ contains additional documentation for packages installed on your
system.
Important
If you modify the DHCP configuration file, the changes will not take effect until you restart the DHCP
daemon.
Caution
Do not perform routine tasks as root — use a regular user account unless you need to use the root
account for system administration tasks.
iv Introduction to the WAF Developer Guide
Warning
Be careful to remove only the necessary Red Hat Applications partitions. Removing other partitions
could result in data loss or a corrupted system environment.
3. Code Presentation Conventions
In addition to the standard document conventions covered in Section 2 Document Conventions, there
are some additional conventions related specifically to discussing source code:
classname
This is the name of a class in an object-oriented (OO) programming language. For example, the
class com.arsdigita.categorization.CategoryTreeNode.
method name
This is the name of a method in an OO programming language, e.g. the method getBase-
DataObjectType.
function
The name of a function or subroutine, as in a programming language. For example, the function
SecurityLogger.warn().
variable name
The name of a variable. For example, the variable BASE_DATA_OBJECT_TYPE.
option
An option for a software command or Method. For example, a user has been granted read
privileges on an object.
return value
The value returned by a function. For example, a method returns null.
replaceable
Content that may, must or will be replaced by the user or a program. For example, the code is
commented with NOTE(n), where n is the number of the NOTE.
program listing
A literal listing of all or part of a program. The \ character is used to break a line for printing
purposes. You will want to reconnect them back into a single line, preserving the spacing in the
line.
import com.arsdigita.kernel.permissions.PermissionService;
import com.arsdigita.kernel.permissions.PermissionDescriptor;
import com.arsdigita.kernel.permissions.PrivilegeDescriptor;
import com.arsdigita.persistence.OID;
OID acsObject = new OID("example.MyACSObject",
new BigDecimal(50));
OID party = new OID("com.arsdigita.kernel.Group", new BigDecimal(5));
Introduction to the WAF Developer Guide v
PermissionDescriptor perm =
new PermissionDescriptor(PrivilegeDescriptor.READ,
acsObject, party);
PermissionService.grantPermission(perm);
first term
The first occurrence of a term, such as the first time we introduce a bulletin-board and note its
abbreviated form, bboard.
vi Introduction to the WAF Developer Guide
I. WAF Concepts
This section covers the concepts of WAF. The intention is to provide both a very high-level architectural view and a closer review of the individual components.
Table of Contents
1. WAF Overview ................................................................................................................................1
2. WAF Component: Persistence ....................................................................................................... 9
3. WAF Component: Kernel.............................................................................................................11
4. WAF Component: Services .......................................................................................................... 13
5. WAF Component: Presentation ................................................................................................... 19
6. WAF Component: Web................................................................................................................. 31
Chapter 1.
WAF Overview
This chapter is an overview of the Web Application Framework architecture. This high-level viewpoint
is especially useful for gaining a good understanding of how WAF works. It is written with both the
technical developer and the technical manager/team leader in mind.
WAF is a web application development framework. Some of the web applications that have been
developed using WAF include Red Hat Content Management System and Red Hat Portal Server.
WAF runs in any standards-compliant servlet container. For more details about system requirements,
see the Red Hat Web Application Framework Installation Guide.
Figure 1-1 describes the architecture of WAF from a high-level perspective.
Figure 1-1. Basic Configuration
2 Chapter 1. WAF Overview
1.1. General Architecture
The WAF architecture described in Figure 1-1 follows the standard n-tier design pattern, with separate
presentation, domain (business logic), data, and data model layers. Web applications built on WAF
also follow the same n-tier design patter, leveraging the infrastructure provided by WAF.
1.1.1. The Layers
The four layers in the WAF architecture are:
• Presentation Layer (UI) — presents information to the user
• Domain Layer (Business Logic) — encapsulates business logic
• Data Layer — stores and retrieves data
• Data Model — stores data in a structured, format in a durable fashion
These layers are shown in Figure 1-2:
Figure 1-2. Basic Configuration
Chapter 1. WAF Overview 3
1.1.1.1. Presentation Layer
The Presentation Layer is responsible for presenting information to the end user. The presentation
layer accepts processed, structured data from the domain layer and is responsible for styling the data
appropriately and delivering the content in a format appropriate for the end user.
1.1.1.2. Domain Layer
The Domain Layer contains Domain Objects, which are abstractions of entities that exist in the business domain, for example, Party, Person, Group, Company, Department, Team, Product, Order, Line
Item.
1.1.1.3. Data Layer
The Data Layer contains two very important components:
Data Objects
Provide read and/or write access to the persistent properties of Domain Objects.
Persistence Metadata
Describes a Domain Object e.g., its name, its properties, and how each property is mapped into
the Data Storage layer. This description is written using the Persistence Definition Language
(PDL) format. PDL was designed to be used specifically in WAF. PDL is discussed in more
detail in Section 2.3 Persistence Definition Language (PDL).
1.1.1.4. Data Storage Layer
The data storage layer Contains the mechanism(s) employed for storing data persistently. This is
typically a relational database (RDBMS) such as Oracle9i™ database or PostgreSQL, combined with
a data model. It may also include other mechanisms, such as an LDAP directory or filesystem.
1.2. Features
In his seminal book Analysis Patterns, Martin Fowler writes that a framework “... should be applicable
across a large domain and be based on an effective conceptual model of that domain” (p. 11). Accordingly, the Web Application Framework defines a set of Domain Objects that are encountered in the
problem domain of most WAF applications. This object model further subdivides into two categories:
kernel and services.
In addition to kernel and services, WAF includes other features that facilitate building database-backed
web applications: infrastructure, persistence, presentation, and web.
1.2.1. Kernel
The kernel provides all the business logic provided by WAF, namely, business logic that is essential to building a web applications. Kernel provides domain objects that represent users, groups, and
permissions.
4 Chapter 1. WAF Overview
Figure 1-3. Basic Configuration
1.2.2. Services
Services are building blocks that address generic requirements common to most WAF applications.
Each requirement defines a set of related Domain Objects, for example, Versioning, Workflow, and
Categorization:
Chapter 1. WAF Overview 5
Figure 1-4. Basic Configuration
As shown in Figure 1-4, all services follow the n-tier design pattern discussed in Section 1.1 General
Architecture, providing:
• A user interface for interacting with the Framework’s Domain Objects.
• Domain logic.
• The metadata (PDL) required for persistence of the Framework’s Domain Objects.
• Data storage as appropriate.
Services are discussed in more detail in Chapter 4 WAF Component: Services.
6 Chapter 1. WAF Overview
1.2.3. Infrastructure
Infrastructure contains software to support the mechanics of application building at each layer of
the architecture (for example, serving page requests, styling the user interface, logging, specifying
metadata, storing data, etc.).
Note
This infrastructure exists independently from any specific problem domain and generally does not
depend on other WAF systems.
1.2.4. Persistence
Persistence handles the storage and retrieval of all information in WAF applications via Data Objects. Data Objects are implemented as a Java class library that supports CRUD (create, read, update,
and delete) operations for any type of Data Object. This is done through a set of generic interfaces:
DataObject, DataCollection, and DataAssociation. Persistence is discussed in detail in Chap-
ter 2 WAF Component: Persistence.
1.2.5. Presentation
Presentation is responsible for presenting data in a structured format to the end user. WAF provides
three basic systems for presentation: Bebop, a web user interface component framework modeled
after Java Swing; Java Server Pages (JSP); and eXtensible Stylesheet Language (XSL). Presentation
is discussed in detail in Chapter 5 WAF Component: Presentation.
1.2.6. Web
The Web component of WAF makes the persistent data and domain logic of your application available
to others over protocols such as HTTP. It integrates the Java Servlet API and the kernel and persistence
components of WAF. For more information, see Chapter 6 WAF Component: Web.
1.3. Applications
Each WAF application adds code and other assets (stylesheets and PDL files) to each layer of the
architecture. The result is a complete application:
Chapter 1. WAF Overview 7
Figure 1-5. Basic Configuration
Again, each application follows the same n-tier design pattern, and builds upon the kernel and services
provided by WAF.
8 Chapter 1. WAF Overview
Chapter 2.
WAF Component: Persistence
This chapter discusses the persistence layer in the overall Web Application Framework. This was
originally discussed in Section 1.2.4 Persistence. You can find persistence tutorials in Chapter 9 Per-
sistence Tutorial.
2.1. Persistence Overview
The storage and retrieval of persistent data is a common requirement of business applications. WAF
provides a persistence layer as a generic solution to this requirement.
The WAF persistence layer allows naturally written Java classes to be persisted to and queried from a
relational database. This is more than simply a method to save Java classes within the database. Developers can use the full range of standard object-oriented modeling techniques, such as inheritance,
interfaces, polymorphism, associations, and composition when writing their Java classes.
WAF persistence is an example of an object-relational mapping layer. This chapter will discuss some
of the concepts required to understand and use WAF persistence. Examples and tutorials are detailed
in Chapter 9 Persistence Tutorial.
2.2. Object-Relational Mapping
An object-relational mapping layer allows developers to use both relational and object modeling in
the development of their applications.
• Relational Modeling — a powerful tool for modeling knowledge. Modern relational databases uti-
lized with well designed relational schemas provide guaranteed data integrity, support for multiple
concurrent transactions, and support for fast and flexible querying.
• Object modeling — a powerful tool for modeling behavior. Object modeling is useful when coupled
with object-oriented (OO) languages and design patterns. OO languages are a common choice for
rapid application development and maintenance.
An object-relational mapping layer can automatically translate operations on an object model into
operations on a relational model and vice versa. This is accomplished through the use of mapping metadata that relates persistent attributes and associations in the object model with tables and
columns in the relational model.
2.3. Persistence Definition Language (PDL)
Because of the flexibility of both relational and object models, it is possible to map a given object
model to many different relational models and to map a single relational model to many different
object models.
WAF persistence uses a modeling and mapping language called Persistence Definition Language
(PDL) to allow developers to describe their object model, their relational model, and how the two
are mapped.
The metadata described in PDL allows the relational engine to efficiently persist changes to the object
model and to construct efficient SQL queries for performing object-level reads. PDL also allows
developers to define their own custom queries and SQL operations to do specialized querying and
updating of the relational model.
10 Chapter 2. WAF Component: Persistence
For a listing of PDL terms, see Appendix D PDL Syntax. Examples of PDL usage can be found in
Chapter 9 Persistence Tutorial.
2.4. Persistence and Domain APIs (DataObject, DataAssociation,
DataCollection, DomainObjects)
Once an object model is described in PDL, the persistent state associated with it may be directly
accessed and manipulated by Java code through use of the DataObject, DataAssociation, and
DataCollection classes that are part of the WAF persistence API.
Developers can then build upon this API in order to add the behavior required to implement their application. This is generally done by extending DomainObject,an abstract base class that encapsulates
a DataObject and uses it to provide persistence capabilities to any derived classes.
2.5. Session and Transaction Management
Domain classes, once written, can be used similarly to any other Java code, with one exception — code
that involves domain objects must be executed within the context of both a session and a transaction.
The session identifies which database that changes are persisted to and queried from, and the transaction allows atomic updates of the database. Setup of the current session and transaction is a simple
process that can usually be centrally handled in an application.
Within WAF, session and transaction management is automatically handled by the BaseServlet
class. The transaction model used by WAF persistence is a simple extension of common relational
database transaction semantics:
• Transactions cannot be nested.
• Once a transaction begins it must either be committed or rolled back.
• Transactions must be rolled back after an error occurs.
Chapter 3.
WAF Component: Kernel
This chapter discusses the kernel layer, which provides services used by several parts of the WAF
system. This component was initially explained in Section 1.2.1 Kernel. This discussion focuses on
the various parts of the kernel component which a developer will need in building for WAF.
For information on how to utilize the kernel in WAF applications, see Chapter 10 Kernel Tutorial.
3.1. Users and Groups
Applications have users. A user is a person who uses an application to accomplish some purpose.
In order to serve the needs of users, applications store information about the users. This information
is used to personalize content, check the permission of a user initiated operation, and to provide
information about a user to other users.
Users are organized into groups. The users in a groups are said to be members of the group. Groups
can also be members of groups. A group exists so that several users and groups can be collectively
identified as an entity.
Groups and users are the two types of parties. This parties system is one of the pieces of the kernel.
The ability to refer to an entity that may be a group or a user provides flexibility to application authors
in writing data models. An example is the definition of a group itself: 1 or more parties. This definition
is recursive, but that recursion reflects the flexibility of having a party type.
3.2. ACSObject
Party, Group, and User are all subtypes of ACSObject. Its purpose is to serve as a base class for use
in common object-level services, such as categorization and permissioning. As such, subclasses are
often types that users directly interact with such as Workflow or Category. The ACSObject object
type also has generic attributes such as a unique id and a displayName.
The ACSObject object type and class are abstract. In order to differentiate among subtypes there are
attributes objectType and defaultDomainClass. These attributes are used to instantiate the appropriate
Java domain class to wrap data objects that are instances of subtypes of ACSObject.
3.3. Permissions
The goal of the permissions system is to provide generic means to both programmers and site administrators to check, grant, or revoke permissions via a consistent interface. For example, an application
developer might decide that viewing a certain set of pages within the application is an operation to be
individually granted or revoked from a user. It’s expected that the permissions system will be heavily
used in production - almost every page will make at least one permissions API call, and some will
make several.
The permissions systems deals with three kinds of objects: ACSObject, Party, Privilege. The
system maintains a set of grants of the form Party p has Privilege priv on ACSObject obj. The
privileges represent actions that are performed on objects.
There are generic privileges that are always defined: read, write, edit, admin, create, and
delete. In addition, applications can define custom privileges, for example categorize.
The permissions system is used to answer questions such as:
12 Chapter 3. WAF Component: Kernel
• What parties have a particular privilege on a particular object?
• What privileges does a particular party have on a particular object?
• On what objects does a particular party have a particular privilege?
Much of the power of the permissions system comes from the flexibility of the model. The assertions
described above are not the only input. Each privilege can imply some set of privileges. In addition,
each ACSObject can have a security context from which it inherits privilege grants. This security
context is just another ACSObject. Groups provide a way of aggregating users and the permissions
system pays attention to group membership.
The power of the permissions system comes from the interaction of these 3 hierarchies: group membership, security context, and privilege implication. Taking these 3 together, the assertion that p has
privilege priv on object obj means that p is a party or a member of a party (at any depth) that was
granted priv or a privilege implying privilege priv on object obj or any parent of obj in the security
context hierarchy.
3.4. Kernel Resources
Resource is a base class in the kernel that represents a user-accessible resource that may serve as a
data container. Resources are organized into a parent-child hierarchy. By default, resources set their
security context to their parent resource.
Currently, the two subclasses of resource are Application (which is web accessible) and Portlet
(which is accessible through Red Hat Portal Server). All Resources have a ResourceType which is
uniquely determined by the specific object type of the Resource. ResourceType has metadata that
is used by some generic navigation and administrative interfaces.
Chapter 4.
WAF Component: Services
WAF provides a number of generic services that can be used in developing a WAF application. Services leverage the business logic provided by the kernel, and provide specialized domain APIs to
solve specific, common business problems. Examples of services include notification, workflow, and
versioning.
Services were originally discussed in Section 1.2.2 Services. Implementation examples are covered in
Chapter 11 Services Tutorials.
4.1. Auditing Service
The auditing service can track when and by whom an object was created and last modified for an
ACSObject. This tracking is optional. The AuditedACSObject class provides methods for accessing
the auditing information.
4.2. Categorization Service
One common WAF application implementation is providing online access to large amounts of information. To make it easier for users to find relevant information, the categorization service is often
employed. It allows various pieces of information such as articles, forum postings, and so on, to be
categorized.
Categories are organized in a tree-like structure that is often called taxonomy or ontology. See Example
4-1.
14 Chapter 4. WAF Component: Services
• Entertainment
• Music
• Movies
• Television Shows
• Education
• Literacy
• Testing
• Home Schooling
• Theories
• Sports
• Scores
• Venues
• Kinds of sports
• Basketball
• Chess
• Soccer
Example 4-1. Sample Taxonomy
The categorization service provides:
• The ability to set up multiple independent taxonomies.
• A system for importing predefined taxonomies from XML files.
• A user interface for managing categories.
• An API for categorizing objects.
4.3. Formbuilder Service
Most applications built with WAF allow users to enter information into the system through a web
browser. A user fills out a number of fields in a form and clicks the Submit button. The user’s input
is validated and stored for later retrieval and display.
Building complex applications with this sort of user interaction usually requires programmer involvement. For example, if you are building a web browser based email client, you need to write code that
knows how to send and retrieve email messages, how to organize messages in folders, and so forth.
There are another class of applications that do not require any special handling of the input data. What
is required is the ability to enter the data in a structured way, and retrieve it later for display, reporting,
printing and so forth.
For example, a group of users wants to input and store data about competing products — they want
to record the product name, the company’s name, a short product description, and the date it was first
Chapter 4. WAF Component: Services 15
introduced to the market. Rather than requiring programming for this straightforward functionality,
WAF provides the formbuilder service.
The formbuilder service enables non-technical users to build such applications via a web interface, without any programmer intervention. The formbuilder service provides a variety of widgets
to choose from, such as a date widget which makes the part of the HTML form that allows you to
specify a date. Validation code is automatically attached to the date widget to ensure that only valid
dates are entered. Various widgets are provided for entering simple strings, numbers, etc.
Once the user has defined the required fields for their custom new document type, the system automatically allocates structured storage in the database. From this point on, other users may enter documents
that require the specified fields to be filled in. Such documents are displayed in the tabular format:
Product name gizmo
Company name Acme, Inc.
Description This gizmo slices, dices, and juliennes.
Date introduced July 22, 1999
Table 4-1. Sample structured document
4.4. Globalization Service
A globalized application is one that tries to equally accommodate readers of different languages and
dialects. Elements of the application’s user interface are shown in the user’s preferred language, if it is
supported. For example, a link to the categories page is displayed as Categories for English speakers
and Kategorien for German speakers.
A partial list of globalization and localization facilities supported by the Java language includes:
• The notion of locale (http://java.sun.com/j2se/1.3/docs/api/java/util/Locale.html).
• Resource bundles (http://java.sun.com/j2se/1.3/docs/api/java/util/ResourceBundle.html) allow you
to organize and maintain locale-specific objects, such as strings to be shown as button labels, e.g.
Categories and Kategorien.
• Locale-specific date format (http://java.sun.com/j2se/1.3/docs/api/java/text/DateFormat.html\ #get-
DateInstance(int,java.util.Locale) — "\" has been inserted to show where the line was broken for
printing purposes; you will need to put both halves together again in e.g. your Web browser URL
window).
• Locale-specific collation (http://java.sun.com/j2se/1.3/docs/api/java/text/Collator.html) of
sequences of strings.
• Miscellaneous other facilities.
The WAF globalization service provides classes and methods that can be roughly divided into the
following three categories.
1. Convenient wrappers around most-frequently used Java globalization APIs, such as resource
bundles.
2. Means of configuring the list of supported languages, locales, and character sets.
3. A mechanism for locale and character set negotiation.
Most modern browsers allow users to select their preferred language or a ranked sequence of
preferred languages. The globalization service looks at the user’s preferred language and locale,
16 Chapter 4. WAF Component: Services
as reported by the user’s browser, and compares them to the list of languages and locales that
the system is configured to support.
For example, a user can configure the preferred first language to be German ("de") and the preferred second language to be British English ("en_GB"). If the system is configured to support
both of the languages, then the globalization service will choose "de" as the preferred locale.
If the system has been configured to support British English, but not German, then the glob-
alization service will choose "en_GB" as the preferred locale. If the system does not support
either of the configured languages, then the service falls back to a default locale which could be
"en_US" (US English).
Once the desired locale is configured, a supported character set must be selected. For example,
pages in German can be displayed using the ISO-8859-11, UTF-8, or UTF-16 character sets.
The user may express a preference by configuring their browser. The user’s preference must
then be reconciled with the list of character sets that the system has been configured to support.
This example of locale and character set negotiation is simplified for this discussion, but it illustrates
the fact that correct negotiation is non-trivial. The globalization service relieves the developer of the
burden of negotiating the preferred locale and character set correctly.
The WAF globalization service provides a set of high-level APIs based on the standard Java globalization facilities that handle issues such as language negotiation and localization of static strings. These
APIs complement the basic globalization infrastructure provided by Java (i.e., ResourceBundles
and property files are still used in WAF) and are specifically designed for use by web applications
built with WAF.
4.5. Mail Service
The mail service acts as a Mail Transport Agent (MTA) for other WAF applications. It provides a
simple mechanism to send plain or rich text messages to any entity with a valid email address. This
service is not typically accessed directly, but rather is used as a building block for higher-level services
such as notification. This service has no dependencies on WAF and exists primarily as a wrapper for
the more cumbersome JavaMail API.
When should you use the mail service directly? If you are writing an application that sends simple
plain-text alerts to users, and you do not require those alerts to be recorded in the database, then it
makes sense to use the mail service. Also, if you are dealing with raw email addresses rather than
WAF parties (users and groups), you probably want to use the mail service directly. Otherwise, you
should consider using the higher-level notification service (see Section 4.7 Notification Service).
4.6. Messaging Service
The WAF messaging service is intended to be used as a building block for messaging applications,
which are WAF applications that use messages to represent various types of communication between
users.
Messages can represent an email from one user to another, or a bulletin-board post, or a comment on
another object in the system. A message can store attachments such as images or other files which are
relevant to the message. Each attachment can be of any arbitrary MIME type.
The implementation follows the RFC8222standard, which has been deprecated by RFC28223.
The Message class models a persistent text message with optional attachments:
1. http://www.htmlhelp.com/reference/charset/
2. http://www.rfc-editor.org/rfc/rfc822.txt
3. http://www.rfc-editor.org/rfc/rfc2822.txt
Loading...