To use the Dataman framework, application domain classes must implement both the gov.va.med.term.access.types.Referenceable and {@link gov.va.med.term.access.maint.util.Maintainable Maintainable} interfaces. The Dataman UI provides several optional features based on the availability of additional methods; see the {@link gov.va.med.term.access.maint.ui.dataview Dataview} documentation for details.
Many classes in Dataman are designed explicitly to provide technology independence. The {@link gov.va.med.term.access.maint.util.UserErrors UserErrors} class abstracts the concept of a set of error messages from both the technology used to display those messages and message format. Dataman often uses dictionaries as a technology-independent values holder. For example, the Dataman servlet framework's {@link gov.va.med.term.access.maint.ui.servlet.ServletArgumentDictionary ServletArgumentDictionary} allows servlet arguments to be read by general-purpose components without binding those components to the servlet API.
Dataman's lack of explicit support for EJBs also derives from the objective of technology independence. Dataman does not prevent client applications from using EJBs. Instead, it allows client applications to use any technology.
Dataman places minimal requirements on client applications. Domain types need only implement {@link gov.va.med.term.access.maint.util.Maintainable Maintainable} and gov.va.med.term.access.types.Referenceable, conform to JavaBean naming conventions, and provide a static valueOf(String) method to reify an object given a String representation of its key.
Every Dataman function that requires persistent data specifies an abstract factory to obtain it. By convention, and to eliminate cyclic dependencies, factories are defined as nested interfaces within the classes that they generate. Concrete factories are located using the {@link gov.va.med.term.access.util.ImplementorRegistry ImplementorRegistry}.
Client applications may implement their own factories for Dataman objects, if desired. Client applications are encouraged to use this pattern in their own code as well.
Dataman is organized into layers of packages, with each layer dependent on the ones below. A diagram showing the high-level structure is here.
Starting from the bottom:
General-purpose architecture-independent classes, not part of Dataman.
(The java.* and javax.* packages are in this layer but omitted from this discussion, as are implementation library dependencies such as Castor and Hibernate.)
These classes are packaged separately from Dataman because they can be used in contexts where data maintenance is not provided. For example, the VA Standard Data Service read-only API uses Standard Data—Basic without using Dataman.
Consists of:
Used by:
This layer is independent.
Consists of:
Used by nearly every Dataman package.
This layer is dependent only on the pre-existent layer.
Consists of:
Packages in this layer typically depend on the utility layer and the pre-existent layer.
Consists of:
Packages in this layer may or may not depend on the technology support layer. Their chief differentiator is that they expect to operate on domain objects that conform to a set of conventions such as the JavaBeans naming pattern. The Command package uses both the Conversion package (in the technology support layer) and the Utilities package. The Validation package uses only the Utilities package.
Consists of:
Packages in this layer typically depend on all lower layers.
An application built using the Dataman framework will typically have the following elements:
Dataman is loosely-coupled. While a factory-based design is recommended for architectural goodness, it is not necessary. While domain classes must provide validation, they do not need to use the Dataman validation service. While Dataview provides a default user interface, the Dataman framework has value even if Dataview is not used.
Dataview provides an administrative interface for data maintenance. End-user applications are likely to require a custom, hand-crafted interface with custom Commands that use application domain types.
API trail documentation is here [+].
With the popularity of Struts, two questions are inevitable: why build a product on Dataman instead of Struts, and why isn't Dataman itself built on Struts? There are several reasons.
First, the products have different scopes. Struts has a much smaller scope than Dataman: it is a framework for writing user interfaces. In contrast, Dataman is a complete application framework for data maintenance, including a metadata-driven data maintenance application.
Second, the products have different philosophies. Struts is servlet-centric; every Struts package has at least one class that depends on the Java servlet API. Dataman is domain-centric. Dependencies on the Java servlet API are restricted to the small set of packages that use that API, and those packages are easily replaceable with others that use a different API or interface mechanism. In general, domain-centric components trump UI-centric components. For example, Dataman's domain-centric validation framework is much more powerful than Strut's UI-centric validation framework.
Third, the minimal feature set for writing an effective web user interface is much smaller than the Struts feature set. Over 50% of Struts' core source code is devoted to JSP tag libraries, which aren't needed at all if Dynamator is used. Most web applications do not benefit from the configurability enabled by Struts; instead, this excess of configurability usually makes applications harder to create and maintain. Dataman's {@link gov.va.med.term.access.maint.ui.servlet.PageServlet PageServlet} and {@link gov.va.med.term.access.maint.ui.servlet.Page Page} classes support the needs of most web applications more simply, powerfully, and flexibly than Struts ActionServlet and Action classes. In fact, the model-view-controller implementation in {@link gov.va.med.term.access.maint.ui.servlet.Page Page} is more complete and more faithful to the MVC ideal than Struts.
Dataman does not attempt to compete with Struts feature-by-feature. The only servlet UI features implemented in Dataman are those needed by Dataman servlets. On the other hand, Dataman's servlet support includes some features not present in Struts, such as the {@link gov.va.med.term.access.maint.ui.servlet.ContentServlet ContentServlet}, in order to support JAR file application deployment.
Finally, the two products motivate very different application construction models. Using Struts, a project spends much of its time on the UI layer. Struts provides no guidance for the domain layer; in fact, it doesn't even require a domain layer. Using Dataman, a project spends most of its time on the domain layer. Once the domain layer is complete, the data administration user interface can be defined quickly and easily using Dataview XML type definition files.
Notably missing from Dataman is the ability to define application-specific pages that can be integrated into the Dataview application. This has been out of scope, but may be added in a later release. @.maintenance