| Red Hat Docs > Manuals > Red Hat Web Application Framework > |
|
This document outlines the requirements for a standard Java API for manipulating persistent data objects (Data Objects). The term "Data Object" refers to any persistent entity within a relational database which is exposed to the applications as an object. This text has been written by Karl Goldstein.
Red Hat Web Application Framework applications require persistent storage of data objects, ranging from Users to Products to News Articles. Developers can benefit from a standard API for performing common operations on persistent data objects, including creating, updating, deleting and linking.
This system consists of a package of Java classes, backed by a schema in a relational database. It has no dependencies on other parts of the system.
One of the driving forces behind developing an object persistence layer in an application is to encapsulate the database logic so that you can minimize the schema dependencies by the source code. Another reason for providing an object interface is because software developers intuitively think in terms of objects. Being able to create a User object, for example, and work with it interactively seems much more intuitive than a SQL approach of opening a database connection, selecting a specific row WHERE this and that, and then closing the connection. The direct SQL approach requires the developer to have more of an understanding of how the User information is physically stored. This should be the job of a standard API and not the job of each developer that wants to use User information. Once the Data Objects are available, they can be completely reused anywhere code needs to refer to those objects. This reduces the need to redundantly embed SQL calls.
Meta-data information is used to define the object types that can be instantiated through the framework. The meta-data also provides information that describes how these object types related (or mapped) to a relational datasbase. By modifying the meta-data, one could define new object types and specify how they are stored in a database. This supports a flexible approach to managing the persistent objects in the framework and eliminates the need to have schema information injected into the source code.
Objects API Documentation
Design document
Developer's guide
User's guide
Test plan
Metadata
10 Object Type Metadata
All persistent data objects are associated with a type. All object types in the system are contained in a Model. The Model is the root object of all metadata types in the system. An object type definition shall consist of the following:
10.0.1 Name
A unique system identifier used to identify the object type.
10.0.2 Labels
Each object type must have at least one human-readable label in the default system locale. In addition, it must be possible to specify any number of additional labels in other locales. Each label must have a singular and plural variant.
10.0.3 Attributes
Each object type may define any number of attributes (see below).
10.0.4 Associations
Each object type may define any number associations to other object types (see below).
10.0.5 Inheritance
An object type may inherit attributes and associations from another object type.
20 Attribute Metadata
An attribute represents a scalar value associated with each instance of an object type. The definition of an attribute consists of the following:
20.0.1 Object Type
Attributes must be associated with one and only one object type.
20.0.2 Name
Single Valued
A unique keyword used by the system to identify the attribute. Attribute names for a single object type and its supertypes must be unique.
MultiValued
The system shall allow multi-valued attributes
20.0.3 Labels
Each attribute must have at least one human-readable label in the default system locale. In addition, it must be possible to specify any number of additional labels in other locales. Each label must have a singular and plural variant.
20.0.4 Count
Each object instance is limited to zero or one values for each attribute.
20.0.5 Datatype
20.0.5.1 Scalar types
The type of scalar value represented. The system shall support the following scalar datatypes:
java.math.BigInteger
java.math.BigDecimal
java.lang.Boolean
java.lang.Byte
java.lang.Character
java.util.Date
java.lang.Double
java.lang.Float
java.lang.Integer
java.lang.Long
java.lang.Short
java.lang.String
java.sql.Blob
java.sql.Clob
20.0.5.2 Array types
The datatype may also be an array of scalar datatypes. In the case of an array datatype, the datatype definition may include a minimum and maximum number of values.
20.0.6 Default Value
Each attribute may be associated with a default value.
30.0 Association Metadata
Associations define the relationships that an object of a particular type is allowed to establish with other objects. In addition to generic associations, there are two special types of associations:
Aggregations
Aggregations define "whole-part" relationships, where the parts may exist independent of the whole. For example, an article may contain multiple images, but the same image may be used in several articles. Deleting one article does not imply deleting the images it contains, since the images may be used elsewhere.
Compositions
Compositions are a special form of aggregration, where the parts exist only in the context of one container object. For example, a book may contain multiple chapters. Each chapter belongs to a single book. Deleting a book implies deleting all its chapters.
Generic associations, Aggregations, and Compositions map to the UML concepts of the same names.
The definition of an association includes:
30.0.1 Name (optional)
A system identifier for the association.
30.0.2 Labels (optional)
Each association may have at least one human-readable label in the default system locale. In addition, it must be possible to specify any number of additional labels in other locales. Each label must have a singular and plural variant.
30.0.3 Ends
Each association has at least two ends. The definition of an association end includes:
30.0.3.1 Name
An association end (or role) must have a name which identifies the end. The name must be unique within the object type and its super types just like the attribute names.
30.0.3.2 Labels
Each role must have at least one human-readable label in the default system locale. In addition, it must be possible to specify any number of additional labels in other locales. Each label must have a singular and plural variant.
30.0.3.3 Object type
The object type on that end of the association.
30.0.3.4 Minimum bound
The minimum number of objects that may exist on that end of a link (an instance of this association).
30.0.3.5 Maximum bound
The maximum number of objects that may exist on that end of a link.
30.0.4 Attributes
It must be possible to qualify associations with additional attributes, essentially treating each link as an object in its own right.
Operations
40.0 Metadata Operations
The Objects API must support the following operations on Object Types:
40.0.1 CRUD operations on object type
Given a general set object type parameters, perform the necessary steps to persist the meta-data to: (1) create a new object type; (2) Read the object type; (3) modify general parameters such as a type's labels or Java class association; and (4) delete an object type.
It is not a requirement that the object type name or supertype be modifiable.
40.0.2 CRUD attribute
Given a set of attribute parameters, perform the necessary steps to persist the meta-data to: (1) add an attribute to an object type; (2) read attributes of an object type; (3) modify parameters such as an attribute's labels; and (4) delete an attribute.
40.0.3 CRUD association
Given a set of associaton parameters, perform the necessary steps to persist the meta-data to: (1) create an association among two or more object types; (2) read assocations on an object type; (3) modify association parameters; and (3) delete an association.
50.0 Object Storage
The Objects API must support the following storage operations on individual objects and links:
50.0.1 Create object
Given a set of attribute values, perform the necessary DML to insert a new object into the database.
50.0.2 Update object
Given a set of attribute values, perform the necessary DML to update an existing object in the database.
50.0.3 Delete object
Given a set of attribute values, perform the necessary DML to delete an existing object from the database.
50.0.4 Create associations(s)
Given a set of object references, perform the necessary DML to create links among objects.
50.0.5 Delete associations(s)
Perform the necessary DML to delete links among objects.
50.0.6 Object and Link Retrieval
The Objects API must support the following types of queries:
50.0.6.1 Retrieve object
Perform the necessary SQL query to instantiate a fully-qualified object with all attribute values.
50.0.6.2 Partial object retrieval
Perform the necessary SQL query to confirm existence of an object in the database and instantiate a partial representation of that object, limited to a set of specified attribute values. This is referred to as Lazy Loading in other documents.
50.0.6.3 Retrieve attribute values as records
Perform the necessary SQL query to retrieve attribute values as a simple set of records, avoiding instantiation of an object for each row.
50.0.6.3.1 Filtering
The API shall support selection of objects based on simple parametric criteria applied to attribute values, include equals, not equals, less than, greater than, BETWEEN and IN.
50.0.6.3.2 Ordering
The API shall support ordering of object retrieval based on an arbitrary set of attribute values.
50.0.6.4 Retrieve links
Perform the necessary SQL query to retrieve all links of a particular type associated with a specified object or set of objects. The results may be returned as an enumeration of objects or as a simple set of records.