Special Control File(s)

Team. When we build the "general-purpose" controller and JAVA Enterprise Edition servlet for the do-it-yourself tutorial found in the book CABOOSE in JAVA, we used a control file. This structured file used an extensible markup language (XML) format for describing its contents and the interrelationships between its parts.

XML is a wonderful way of representing structured information and mappings between data plus the associated relationships. However, the software packages and libraries for processing XML often require "wordy" solutions. This is the case with JAVA. It seems that XML's flexibility as a file format promotes this "wordiness".

The author realized that whatever one represents in XML might also be well-organized in a relational database management system. And,  programmatic database access does not require as "wordy" of a solution. Yet, we sought a simple, highly-flexible, and universal solution for our controllers. And, if we chose a particular database management system for storing this information instead of XML files, we would curtail its "range of universality".

Yet, another way of "structuring" "flat" files is comma separated values (CSV). It is a little "wordier" than XML but will not irreversibly bind a database management system solution with our "controller" kernels. So, we have a trade-off. The controller files are more "verbose" than the equivalent XML, but the programmatic solution that reads and interprets them is more "terse".

As a result of extracting the control information from an XML file, we must produce a pair of CSV files.

A sample directory.xml file is below:

<?xml version="1.0" encoding="UTF-8"?>

<!--
To change this license header, choose License Headers in Project Properties.
To change this template file, choose Tools | Templates
and open the template in the editor.
-->

<!-- the model is for the entire application. one view associates
with one page of markup. As attributes this element has an id and a stencil
which is a the filename of the markup. Each view has zero or more replacement
tile child elements associated with it. The tile id attribute appears in the
markup and will be replaced by the String content rendered by the method
uniquely described by the class and method attributes of the tile element.
-->

<model>   

<view id="landing" stencil="/WEB-INF/model/xstencil.xhtml" content-type="text/html;charset=UTF-8">

            <tile id="#PROJECT#" class="org.sharpe.sample.StencilHandler" method="projectRenderer"/>
            <tile id="#MODULE#" class="org.sharpe.sample.StencilHandler" method="moduleRenderer"/>
            <tile id="#CREATE_DATE#" class="org.sharpe.sample.StencilHandler" method="createDateRenderer"/>
           
            <!--
               Uncomment the following three tile elements after deploying and starting the JAXRSHello
               and JAXWSHello web services plus creating the necessary database structure for the Hibernate operations.Take them one at a time.
            --> 
           
            <!--<tile id="#HIBERNATE_MESSAGE#" class="org.sharpe.sample.StencilHandler" method="hibernateMessageRenderer"/>-->

            <!--<tile id="#JAXWS_MESSAGE#" class="org.sharpe.sample.StencilHandler" method="JAXWSMessageRenderer"/>-->

            <!--<tile id="#JAXRS_MESSAGE#" class="org.sharpe.sample.StencilHandler" method="JAXRSMessageRenderer"/>-->

        </view>

        <view id="exception" stencil="/WEB-INF/model/exception.xhtml" content-type="text/html;charset=UTF-8">

            <tile id="#EXCEPTION_MESSAGE#" class="org.sharpe.sample.StencilHandler" method="exceptionRenderer"/>
</view>

</model>

First, the directory holds a mapping between the application level identifiers for the view specifications, "id", and the name of the file which holds the view's markup specification in client-side technologies, "stencil".

So, this information must be held in one CSV, under the headings viewId and stencil.

viewId, stencil

landing,/WEB-INF/model/xstencil.xhtml

exception,/WEB-INF/model/exception.xhtml

Second, the directory holds a mapping between data placeholders ids and the identifiers for the classes and methods that will render a string which eventually shall replace the placeholder in the appropriate markup stencil. 

So, this information must be held in another CSV, under the headings viewId, placeholderId, class, method.

viewId, placeholderId, class, method

landing,#PROJECT#,org.sharpe.sample.StencilHandler,projectRenderer

landing,#MODULE#,org.sharpe.sample.StencilHandler,moduleRenderer
landing,#CREATE_DATE#,org.sharpe.sample.StencilHandler,createDateRenderer

landing,#HIBERNATE_MESSAGE#,org.sharpe.sample.StencilHandler,hibernateMessageRenderer
landing,#JAXWS_MESSAGE#,org.sharpe.sample.StencilHandler,JAXWSMessageRenderer
landing,#JAXRS_MESSAGE#,org.sharpe.sample.StencilHandler,JAXRSMessageRenderer

exception,#EXCEPTION_MESSAGE#,org.sharpe.sample.StencilHandler,exceptionRenderer

It is easy seeing how these might be a pair of "simple" database tables with primary and foreign keys.

Yet, we would like it if we could keep all of this information in a single file. So, we will "create" a CSV with "sections" or a sectioned comma separated values (SCSV) file, using beginning and ending markers like XML elements and the Pascal language.

begin,views

viewId, stencil

landing,/WEB-INF/model/xstencil.xhtml

exception,/WEB-INF/model/exception.xhtml

end,views

begin,placeholders

?We can even implement comments on all lines prefixed with a "single" question mark

viewId, placeholderId, class, method

landing,#PROJECT#,org.sharpe.sample.StencilHandler,projectRenderer

landing,#MODULE#,org.sharpe.sample.StencilHandler,moduleRenderer
landing,#CREATE_DATE#,org.sharpe.sample.StencilHandler,createDateRenderer

landing,#HIBERNATE_MESSAGE#,org.sharpe.sample.StencilHandler,hibernateMessageRenderer
landing,#JAXWS_MESSAGE#,org.sharpe.sample.StencilHandler,JAXWSMessageRenderer
landing,#JAXRS_MESSAGE#,org.sharpe.sample.StencilHandler,JAXRSMessageRenderer

exception,#EXCEPTION_MESSAGE#,org.sharpe.sample.StencilHandler,exceptionRenderer

end.placeholders

This structure in our "special" control file will provide a means for representing all of the interactions that are seen on our view storyboard which is built using client-side technologies. It can be seen as a "meta" programming language for our controller, sitting atop the behavior of controller whose "near" cousin is a command shell or high-level language interpreter. 

Providing a "clearer" view of our controller system and how it works, the xstencil.xhtml file is below:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">

    <head>

        <title>CABOOSE Standard Stencil</title>

        <meta name="viewport" content="width=device-width, initial-scale=1.0"/>

    </head>

    <body bgcolor="F1F8FF">                

        <!-- 

        I chose that my tile replacement identifiers would

        follow the pattern #ALL_CAPS_JAVA_IDENTIFIER#. This

        is only a convention and not strictly enforced by the

        cab. Obviously, the string used should not collide with

        any other one that might be found in a markup document.

        -->

        <table width="640px" cellspacing="10px" cellpadding="20px">

            <tr><td align="center">&nbsp;</td><td align="left" colspan="2">CABOOSE Standard Stencil</td></tr>            

            <tr><td align="left">Project: #PROJECT#</td><td align="left">Page Handler: #MODULE#</td><td align="left">Create Date: #CREATE_DATE#</td></tr>

        </table>

    </body>

</html>

Basically, our controller reads in the entire markup file associated with the "requested" application view. Then, it uses simple programmatic repetition and replaces each placeholder, such as #PROJECT#, #MODULE#, and "CREATE_DATE# with the string produced by their associated class and method in the "directory.scsv" file. This creates the response for the client. The string which the class and method render might be "simple and flat", or it might be a string that describes client-side markup or another technology.

These are our next steps after "just" returning an HTML file.