It is based on an idea that the most of data the applications operate have a tree or network structure and generally can be presented in the form of the Document Object Model (DOM) or XML files. (That's why XML is widely used to export/import those data and exchange between applications.)

Following that idea, it is possible to imagine that if we had some abstract interface with an ability to represent most of practically used data sources in a from similar to DOM, we could process those data with some a single tool which is based only on the concept of XML (perhaps with a few enhancements) and employs available standards and approaches developed around it.

DocFlex technology was devised as an implementation of that idea for the task of representation of the application's data in some human-readable form, i.e. generating various reports and documentation.

Another idea related to this task and sought to achieve in DocFlex Technology is a universal approach to specifying formatting of the output documents and generating a common network of hyperlinks interconnecting them.

The natural way to achieve all those goals would be to introduce a new programming medium in the form of a scripting language or templates.

The scripting language is something intended for coding manually, then compiling, then running with an interpreter. Normally, this approach provides powerful expressive capabilities however in expense of a rather laborious way of using them. In addition, such a scripting language already exists. It is XSL.

The templates may be considered a less flexible approach rather than scripts, but just this makes them easier to be created using some specialized visual designer tool.

The last approach was chosen as a base for DocFlex Technology. Actually, the DocFlex templates represent a mixture of both approaches, since small scripts called FlexQuery expressions can be used to dynamically adjust some properties of more rigid (but visually expressible) constructions called template components.

2. Data Sources

DocFlex core connects to the data sources provided by Java application using special drivers written with the DocFlex API.

Any such driver represents a particular data source in the form structurally similar to W3C DOM and understandable for DocFlex core. Such a representation is called Data Source Model (or DSM) and any driver supporting it -- a DSM Driver. Such a driver provides the DSM data via special DSM Interface which it should implement.

Any DSM behaves like a virtual XML document. It contains elements (called DSM elements) and attributes (called DSM attributes). However, unlike elements/attributes in XML documents, the DSM elements and DSM attributes are rather special things. Actually, they are instances of specific interfaces implemented by the DSM Driver, which makes them capable to dynamically provide a lot more information from the underlying data source rather than ordinary XML document.

All possible data sources processed by the same DSM Driver are described by a certain DSM Type (which is actually an equivalent of XML DTD). The driver should provide the data structure and type information associated with this DSM Type via special DSM Type Interface.

Note:

Actually, some DSM Driver implementations may process different DSM Types. For instance, DocFlex/XML includes the XML Model Driver which allows to work with the data from XML files. This driver can be initialized from different DTD (or XML Schema) files passed as a parameter, thus presenting each time a DSM Type associated with a given DTD (or XML Schemas).

In fact, all existing applications of the DocFlex Technology (such as DocFlex/XML, DocFlex/Javadoc and DocFlex/Together) represent little more than the DocFlex core plus one or more specific DSM drivers.

3. How Data Processed?

Data processing scheme implemented in DocFlex in many ways is similar to that used in XSL Transformations. In brief, it can be described as the following.

DocFlex templates are built of the nested components called sections. Most important of them are Element Iterators and Area Sections. Each Element Iterator performs iterations by a set of elements which it produces from the context element received from the iterator's parent. The set of iterated elements is generated according to the Location Rules, which are settings based on a subset of XPath specification (with some extensions allowing to traverse element references). During the iterations, each iterated element is selected as a context element and the iterator's content is repeated for it. Area Sections do not perform iterations. Instead, they are programmed to generate some output from the context element. The template interpretation starts from the template's root section block. The root element of the processed XML document becomes the first context element.

It can be seen, that Element Iterators produce the same effect as <xsl:template> / <xsl:apply-templates> directives and DocFlex templates themselves are analogues of XSLT-scripts.

However, it should be mentioned that DocFlex is not directly based on XSL and does not use any XSLT processor internally. Instead, this is a completely new attempt to merge in a single tool:

The ability to work with both XML files and any data sources provided by Java applications in some universal way based on notions of XML and accompanying standards.
The capabilities of data retrieval and processing comparable with those of XSLT (and beyond).
The ability to process data from multiple independent data sources (both XML files and provided by a Java application) and to generate by them single output.
The simplicity of designing and generating the professionally formatted hypertext or plain output documents.

For further information, see Data Processing and Templates/Template Designer features, where you can find many details about DocFlex templates and data processing capabilities.

See also DocFlex/XML | Samples | Alternative to XSLT, which demonstrate how DocFlex can be used as an alternative to XSL Transformations.

4. Generated Output

There are two types of output that can be generated by DocFlex:

Single file documents
Framed multi-file documentation

For those output types there are two types of templates: document template and frameset template.

Each interpretation of a document template normally results in generation of a single output document. Document templates also are the places where all the output formatting specified.

The DocFlex architecture was devised so that to allow designing document templates independently on a particular destination format. The specific format is selected just at the moment of starting the generation. All instructions and settings specified in a document templates will be rendered with appropriate features of the selected output format. For more information about formatting techniques supported in DocFlex, see Formatting Features.

Each document template is associated with a particular DSM Type. This DSM Type is the source of information about the data the template is intended to manipulate. That information is used during the template design.

When the template is interpreted by the generator, an output document produced by it normally contains data from a single DSM for whose type the template was designed.

However, DocFlex provides a way for designing document templates whose output can contain data from several DSMs and even of different DSM Types. This can be achieved by calling from the main template the subordinate ones (or subtemplates).

Each subtemplate is just yet another document template and designed the same way as the main one. When interpreted alone it may also produce a single document. But when called from another document template (a master) it becomes the subtemplate and can be specified to produce not a separate document but a fragment of the main document generated by the master.

Since each document template can be assigned with its own DSM the resulting document will contain data from the multiple DSMs. Which particular DSM is passed to the subtemplate during a call is specified when defining the subtemplate call within the master template. It is also possible to generate hyperlinks between the document's parts produced by different DSMs. See Call Template for more detail.

Frameset templates are entirely based on calls of subtemplates. This time, each subtemplate call generates a separate subordinate document. A frameset template itself generates a special frameset document which contains no actual data, but instead, specifies the frame windows where subordinate documents are displayed.

A typical example of framed documentation is the output produced by Java 2 SDK Javadoc (Standard Doclet). DocFlex can do just the same (see DocFlex/Javadoc | Examples), but now you can design the frameset structure by yourself and specify what exactly is loaded in the frame windows.

Currently, the frameset templates can generate output only in HTML format.

5. DocFlex SDK

DocFlex SDK (Software Development Kit) is an implementation of DocFlex Technology and represents a tool for development of template-based documentation/report generators built into Java applications.

From the external view DocFlex SDK consists of three main components:

DocFlex API
DocFlex Template Designer
DocFlex Generator

DocFlex API

Provides Java-programming interfaces for integration of the DocFlex core with the particular Java application. These interfaces allow

to develop the DSM Drivers, which represent the application's data in the DOM-similar form understandable for DocFlex core.

Besides delivering the data (via DSM Interface) and providing the data structure and type information (via DSM Type Interface), a DSM Driver may also supply
- The graphic images, which may represent some data elements in a specific graphical form (for instance, diagrams, screenshots etc.) to be inserted into the generated documentation. The DSM Driver may also provide imagemaps for such images to generate hyperlink within them.
- The small and big icons representing the data elements, which may be useful for generation of various summaries and references in more illustrative form.
- The additional utility functions which can be called within the FlexQuery expressions in templates to allow access to some specific data and functionality supported by the application.
to launch the DocFlex Template Designer from the Java application.
to launch the DocFlex Generator from the Java application with the ability to track the generation progress and show it (by the application itself in the preferred way) as well as to cancel the generation at any moment.

DocFlex Template Designer

Represents a high quality Graphic User Interface that allows creating and designing DocFlex templates.

This is a ready to use component.

The Template Designer checks all registered DSM Drivers and collects the list of all available DSM Types supported by them.

Using the DSM Type information provided by a particular driver (via DSM Interface), the Template Designer allows to design a template for a selected DSM Type.

DocFlex Generator

This is another DocFlex SDK component, which represents an engine that produces the output documents.

Actually, the DocFlex Generator comprises a set of components because it is designed as some abstract generator plus a number of extensions for each supported output format. Each extension, in effect, represents a separate generator.

The Java application should start some of those generators and provide it with a specified template and a DSM Driver initialized to supply the application's data. The template should be designed for the DSM Type supported by this driver. Then, the generator connects to the DSM provided by the driver and by interpreting the instructions from the templates generates an output document.

This is a simple scheme which involves one template and one data source.

Actually, such a generation may be much more complicated. The application may register multiple DSM Drivers able to dynamically initialize connections to different DSMs according to the parameters they receive from the generator.

Then, the generator is started as previously with a some initial template (called main template) and an initial DSM. But now, the main template may call from itself another templates (subtemplates). Those subtemplates may be designed for absolutely different DSM Types (for instance, the main template may work with a specific application's internal data source, whereas subtemplates may be designed to take their data from some external XML files).

When processing such a call, the generator looks for a registered DSM Driver appropriate to the called subtemplate's DSM Type and initializes it with the parameters specified in the call (for instance, a particular XML file name). Then, the subtemplate is processed so it takes its data from the new DSM initialized for it (e.g. the external XML file).

As the processing of the subtemplate finished, the generator returns to the main template and continues processing it again. In the mean time, during all those changes, the generated output will remain the same. So, the result document will contain data both as directly from the application itself as from some external data sources (e.g. XML files).

Multiple DSM Drivers may be used also when a Java application, though being a single unit, may operate its data using very different interfaces (sometimes based on different notions and directly incompatible with each other). Anyway, there may be some indirect connections between the data provided by those interfaces and, correspondingly, a desire to generate some single documentation by those data.

DocFlex Technology may allow to handle such a task. For example, when developing DocFlex/Together, we have successfully integrated two absolutely different interfaces: RWI and UIBuilder (both provided by Together OpenAPI), so to make possible generating a single documentation from the data supplied by both of them (see DocFlex/Together | Examples | User Interface Documentation).

The user interface for launching the generator should be implemented by the particular Java application. Below, you can see a screenshot of the generator dialog invoked from the DocFlex/XML:

And this is how the dialog looks, when the generator is running: