A generic object maintenance user interface for Maintainable types. Dataview provides a complete web-based user interface without the need to code any HTML. Instead, a simple XML file is used to specify properties necessary to construct a user interface for a type. For more information, see the Dataview DTD.

Type Requirements

To be maintainable through this facility, a type must satisfy the following requirements:

The best way to understand how to construct types that can be managed by Dataview is to define types using Datagen.

Major User Interface Concepts

Meaningful URL Scheme
Resources available on the web should be available through meaningful and permanent URLs. Consequently Dataview uses a meaningful URL scheme. The Dataview URL scheme is:
<function>/<Type>{/<object-id>{/<attr-name>}}*

The Dataview URL scheme has these essential properties:

Canonical HTTP Interaction Patterns
GET is used only for queries. GET requests are idempotent.

POST is used only for commands.

If a POST request cannot be satisfied (usually because of a user error), the response to the POST is the form submission page with error information.

If a POST request is successful, the response to the POST is an HTTP redirect, so that the next page visible in the browser is the result of an HTTP GET.

Form processing employs both of these patterns, as shown in this sequence diagram.

User Interface Configurability
The appearance of the Dataview web application user interface is fully configurable using CSS. Applications may substitute their own style sheet by placing it in the classpath before the Dataman JAR at /gov/va/med/term/access/maint/ui/dataview/content/style.css.
User Interface Consistency
The structure and behavior of the Dataview user interface is completely controlled by Dataview based on metadata provided by applications. Dataview takes responsibility for implementing the appropriate UI design patterns based on the structure of application data. Ensuring complete consistency across all application datatypes and even across all applications that use Dataview increases end user productivity and task effectiveness.

Occasionally the Dataview interface for a given datatype may appear sub-optimal. This is to be expected with a generic approach, and is a reasonable tradeoff for consistency. In such a case it may be possible to enhance Dataview's logic or metamodel to support the desired behavior.

Major Domain Model Concepts

Application
An application is a set of types defined to Dataview. Each application must be defined as a separate web application to the servlet container.

An application is identified by its root package. Each application is assumed to have a unique root package. The application's root package is defined in the application's web.xml file using a context-param named "application-package".

Ownership
Ownership is equivalent to existence-dependence. If type A owns type B, type B is existence-dependent on type A. The database representation of type B has a foreign key to type A. In a UML model, ownership appears either as a composition relationship (the composite owns the component) or as an association class (the association class is owned by each association relationship participant).

Owned types are not displayed on the main menu generated by Dataview for an application. Instead, they are displayed as tabs on the view and edit pages for the owning type.

Selection Availability
When an attribute is of a user-defined type, it is sometimes desirable to restrict the set of values available for selection. This is particularly true for owned types. Consider a type A that participates in an association relationship with type B. Assume that there can be a maximum of one association between any given objects 'a' and 'b'. When editing 'a', the set of instances of B that are already related to 'a' through this association should be excluded from the set of values available for selection.

Types control availability by providing an optional method named 'availableAttributeNameSelections' that takes an optional 'parent' argument used for owned types to indicate the known owning object. For an association class, the parent argument is the parent from which this object was traversed to.

Constraining Selections
A constraining selection is a selection that constrains the values available for another selection. Consider a type that has two attributes, 'a' and 'b', of types A and B, where type A owns type B. A selection for attribute 'a' constrains the selections available for attribute 'b' to those instances of B that are owned by the instance of A selected. (Example: Address has attributes Country and State. The selections for State are constrained by the selection of Country.)

Constraining selections are implemented in client-side Javascript so that no server interaction is required.

Major Design Concepts

Framework Architecture
Dataview is designed to be used as a black-box framework. Dataview is not an application: applications use Dataview. To deploy a data administration application, an application that uses Dataview must create a web application archive file that includes the Dataman JAR.

A key design objective for Dataview as a black-box framework is that the only actions needed to incorporate Dataview should be to include the Dataman JAR in the application's WAR file and to configure the deployment descriptor to serve Dataview resources. This design objective has several key impacts on user interface component design.

Static Content Servlet
The Java web application deployment model does not support web application frameworks. Static content is expected to be placed into a directory structure whose root corresponds with the application's document root. This would require a framework to provide a directory tree of static content so that a client application could copy that tree into the directory structure of the web application archive. This is not a framework interface.

To enable a framework interface, Dataview static content is served using the {@link gov.va.med.term.access.maint.ui.servlet.ContentServlet ContentServlet} or {@link gov.va.med.term.access.maint.ui.servlet.CachingContentServlet CachingContentServlet}, both of which serve content residing in the classpath. Use of these servlets allows all static content to be delivered in the Dataman JAR.

Page Templates
The Java web application deployment model expects JSP files to reside in the same directory structure as static content. This makes JSP ineligible for use by an application framework, since there appears to be no way to obtain a RequestDispatcher for a JSP that resides only in the classpath. Instead, Dataview uses page templates: program modules that output HTML. These modules can be incorporated into a JAR file because they are normal Java classes. Each page template is an {@link gov.va.med.term.access.maint.ui.Outputter Outputter}.
Dynamator
Page templates are generated using Dynamator from pure HTML and program logic files. Dynamator provides a number of benefits. It enables absolute separation of program logic from static content. It enables reuse of program logic both within and across pages. It makes validation of the user interface as easy as validating a static web site. Without Dynamator, the use of page templates as Outputters would introduce unacceptable maintenance overhead.

While it would be possible to use a third-party template engine such as Velocity or Freemarker, this would add an unnecessary runtime dependency without achieving any of the additional benefits provided by Dynamator. Dynamator adds no runtime dependency because it is used only in the development environment.

User Interface Design

Page Navigation
The basic Dataview page navigation model is here. This model shows page navigation for a simple datatype that does not have dependents.

The navigation model for types with dependents is hierarchical and recursive. A tab is displayed for each dependent type. When the tab is selected, a list of dependents is displayed within the tab pane. Navigation within the tab pane follows the same pattern as the basic navigation model.

Dataview's add page is designed to support bulk add: after an object has been added, the add page is redisplayed to allow another object to be added.

HTML Design

Configuration

To configure Dataview for use in a servlet container, see the {@link gov.va.med.term.access.maint.ui.dataview.servlets.DataViewServlet DataViewServlet}. @.maintenance Classes in this package whose names begin with "Page" support URL-based UIs. The other classes in this package are sufficiently general to support any UI.

Implementation Design

A high-level structure model of the implementation is here.

A {@link gov.va.med.term.access.maint.ui.dataview.PageStack PageStack} object is created for each request. The interaction model for PageStack creation is shown here.

A high-level interaction model for GET request fulfillment is here.

A high-level interaction model for POST request fulfillment is here.

File Locations

HTML files are in dataman/html. The files in that directory are complete, valid HTML, but do not comprise a static demo site. (A static demo site is a set of files that can be displayed in a browser to show the appearance of the site without requiring server interaction.) To create a static demo site, run 'ant create-demosite'; the static demo site is created in directory dataman/demosite.

Dynamator files are in dataman/dynjava.