Attachment featured reviews



JspDoc: Documenting JSP made simple

Table of content

I - Context and 'user needs' for JspDoc 1

II - Standard template for jsp 2

III - Using JspDoc presentation jsp 5

IV - Programming with JspDoc API 8

V - Known limitations & Planned extensions 10

VI Installation and environment 10

VII Utilities: conversion from 'classic' to XML format (JSP1.2) 12

VIII Documentation revision history 14

I - Context and 'user needs' for JspDoc

Who

The 'JspDoc' feature targets Administrators and Jsp Developers and allow them to

• Implement a standard 'documentation' for Jsp

• Browse on-line the documentation of a Jsp collection

• Understand the Jsp structure and learn about them or debug them

Why, What

There is no standard tools to document a jsp collection analogous to Javadoc for java packages. We had to develop a set of presentation jsp and java classes documenting jsp providing

• A classified view of the jsp directory of an application server, including summary and categorization of each file

• A detailed view for any jsp file including a documentation section (embedded inside the jsp relying on our proposed standard) and summarizing the main elements of a jsp (directives, taglib tags, java objects declaration…)

• A rendering of the final layout, where all the html is 'as in the final page' but all jsp processing instructions rendered as embedded html text

• We also provide a 'classic' to 'xml' converter for those who wants to transform jsp in one or the other format.

Those features are implemented with 3 jsps and a set of Java classes supporting jsp parsing and some data processing to simplify the jsp presentation task (selecting and sorting).

Benefit

- The benefit of such an approach is that the jsp is the unique source of information not only for processing of course but also for documenting what are provided services (a jsp becomes a self documenting unit). As with javadoc, this system has the intelligence of what the Jsp structure is and tells a lot without verbose over documentation by the jsp programmer: the documentation section should really be a functional description of the service provided by the jsp, jspDoc complements it providing intelligent information about all the different elements processed by the jsp: what are the directives used, what are the beans or taglibs entries used, what are the Java objects and the methods called (either in scriptlet or expressions)…

- This tool, being on-line and real time (every time a modification is done on a given jsp is reflected in the documentation) provides a valuable resource to learn and debug a set of jsp.

- One other benefit of this utility is to provide a verification tool allowing to verify the jsp and html syntax of all the jsp files. This is quite useful as both, application servers and browsers are fault-tolerant and accept input source not so well formed but that can produce not exactly what is wanted.

- Finally this tool can be used as a jsp learning tool depicting all the different facets of this technology. And really, this tool does what a jsp programmer does will reading jsp code…

II - Standard template for jsp

Introduction: writing the doc section of a jsp

In order to organize the jsp documentation, we propose to add in each jsp the following comment ( use doctemplate.jsp as a template)

We recommend to have only one section like this in a given jsp file, but if more than one exist in a given file, it will be collected by the processing jsp and associated java beans.

As you can see, the above comment sections are embedded inside a javadoc complying section inside a scriptlet ()

Inside this we decided to encode fields in xml to inform the documentation system about different facets of the jsp.

Documentation

|name |Directory2.jsp |

|category |System |

|summary |List all jsp files with category and summary |

|history |10/08/01 us Gilbert Brault creation |

|outline |if refresh set or new session, list all jsp files of the server and parse them |

| |List files according to the following criteria |

| |creation order (item #) column |

| |file name (no case sensitive) |

| |category of processing |

|todo |Display modification date and allow ordering by dates |

|copyright |Schneider-Electric 2001 |

Example of documentation rendering

Introduction: parsing the doc section of a jsp

The parsing section of the documentation section ( jspDoc() method of the PharosDoc class) collects and parse all the ( sections of scriptlet) and builds a Dom which can be accessed by getDomDoc().

Some facilities are already implemented to facilitate jsp doc creation. For example the method jspDoc() returns an ArrayList of (String[2]), String[0] are the level 1 xml tags and String[1] are the xml chucnk ambraced by the level 1 tag.

This allows for example to display with the following code the document fragment of a given jsp (assumes name contains the filename).

InputStream in = servletContext.getResourceAsStream("/"+name+".jsp");

com.schneider_electric.ebase.jspdoc.split.PharosDoc pharosDoc =

new com.schneider_electric.ebase.jspdoc.split.PharosDoc(in);

pharosDoc.parse(); // jsp parsing

ArrayList jspDoc = pharosDoc.jspDoc();

%>

Documentation

Note: if html is embedded inside comments, use

to make the appropriate layout: in the above case, if first level comment entries are "outline" or "todo", we suppose that comments are html based, so spit it raw. In all other cases, normalize tags to present them…

As you can see, the first level interface of documentation is quite open and some more guidelines, for a given package, as Pharos, should be given to yield to a coherent documentation framework.

Reference cards for Pharos jsp documentation tags and categories

We are now going to provide those guidelines and explain the rational

|TAG |Description |

|Doc(1) |The doc tag is the outermost tag for documentation collect |

|Name(1) |Jsp file name: to relate the document fragment to the source file, good for printed version of this document chunk |

|Category(1) |At least one tag among a set of tags relevant for the application and allowing to group jsp according to those tags. |

| |For Pharos see the following table of recommended categories |

|Summary(1) |A one line comment depicting what it is about |

|History(n) |Description of all the modification done in the jsp code. Includes the following sub-tags |

| |The text-field is the Author |

| |Date (1): when the modification was achieved |

| |Action (n): what was fixed or enhanced |

|Outline(1) | list providing a set of important concept to grasp and possibly the main functions implemented by this jsp |

|Todo(1) | list for improvement and/or correction to implement in future release |

|Copyright(n) |Protection of the intellectual property rights |

(1) means only one tag, (n) possibly more than one

Recommended tags for Pharos jsp documentation

|Category |Description |

|System |All jsp related to System use. For example, the documentation jsp belong to this category |

|Presentation |All jsp doing some generic layout functions like header, footer… |

|Classification |All jsp processing Pharos categories and search or query features |

|Discussion |Jsp related to Threaded discussion feature (Forums) |

|FAQ |Jsp related to Frequently Asked Question feature (FAQ) |

|Folder |Jsp making collections of publication (may be obsolete ?) |

|Glossary |Jsp related to Glossary feature |

|Mail |Jsp editing and sending e-mails |

|Management |Jsp related to Community organization |

|Publication |Jsp related to publications |

|Generated |Custom specific publication |

|… | |

Recommended categories for Pharos jsp

III - Using JspDoc presentation jsp

JspDoc presentation jsp job

|Name |Description |

|Directoryjsp2.jsp |Is placed in the targeted application to document in a given application server (with the appropriate java classes |

| |see the installation section for further information) |

| |Collects all the jsp running in the current application, parse them |

| |Render a table which entries are jsp and for each of them provides |

| |The Jsp order number (as created in the directory) |

| |The Jsp name |

| |The Jsp category field (if provided in the documentation section) |

| |The Jsp summary fiel (if provided in the documentation section) |

|Documentjsp.jsp |Same installation comments as above |

| |For a given Jsp and if those elements are present inside it, provides |

| |A documentation section (see the above for detailed information) |

| |The list of all directives (field like ) |

| |The list of all anchors (field like ) |

| |The list of all form header (field like ) |

| |The list of scriptlet declared java object |

| |The list of jsp expression (field like ) |

| |The list of java expression calling methods of any java object |

|Skeltonjsp.jsp |Same installation comment than above |

| |Render a jsp with |

| |All html fetured renderd as they will actually be rendered if the jsp was executing |

| |Embed all the jsp processing instructions as html text |

Features of the different documentation jsp

Screen shot

[pic]

directoryjsp2.jsp layout

[pic]

skeltonjsp.jsp layout (executed on directoryjsp2.jsp)

[pic]

documentjsp.jsp layout

IV - Programming with JspDoc API

There are two classes PharosDir and PharosDoc which belong to

package com.schneider_electric.ebase.jspdoc.split;

PharosDir

|Method Name |Description |

|load() |Input: a valid directory path including jsp files to process |

| |Output: an ArrayList of string[4] providing |

| |[0] an order number |

| |[1] the file name |

| |[2] the category field of the doc section if it exists |

| |[3] the summary field of the doc section if it exists |

| |State variable: the output ArrayList (jspDirectory) |

|orderedByName() |Input: the state variable |

| |Output: a TreeSet with the same content as the ArrayList, ordered by file name |

|orderedByCategory() |Input: the state variable |

| |Output: a TreeSet with the same content as the ArrayList, ordered by category fields |

Summary of PharosDir API

PharosDoc

+-----+ new PharosDoc(input)

| jsp |

+--+--+

| jspDeclarations()

+ parse() jspExpressions()

| jspDirectives()

+-----+ jspTags()

| DOM | 'domSplit' jspDoc() jspDocCategory()

+-+-+-+ jspDocSummary()

jspJavaBlob() | | jspHtml()

+---------+ +-----------+

| |

+---+--+ +---+---+

'sJavaBlob'|String| |String | 'sJspHtml'

+---+--+ +---+---+

parseJavaBlob() | | parseHtml()

| |

+---+--+ +---+---+

| DOM | | DOM |

+------+ +-------+

'domJavaBlob' 'DomJspHtml'

javaBloblocalvariables() jspHtmlanchors()

javaBlobExpressions() jspHtmlforms()

|Method Name |input |output |Description |

|PharosDoc() |Reader | |Constructor, input represent an open Reader on the jsp byte stream |

| | | |representation |

|parse() |Reader |domSplit |Reads the input and builds a DOM |

|jspDeclarations() |domSplit |ArrayList |Select jspDeclaration nodes and returns an ArrayList of String |

| | | |representing the content of those tags |

|JspExpressions() |domSplit |ArrayList |Select jspExpressions nodes and returns an ArrayList of String |

| | | |representing the content of those tags |

|JspDirectives() |domSplit |ArrayList |Select jspDirectives nodes and returns an ArrayList of String |

| | | |representing the content of those tags |

|JspTags() |domSplit |ArrayList |Select jspTags (jsp: or taglig) nodes and returns an ArrayList of String |

| | | |representing the content of those tags |

|JspDoc() |domSplit |ArrayList |Select doccomments nodes aggregate and parse them into a single DOM |

| | | |document domDoc, returns an array of strings for each level 1 |

| | | |documentation tags |

|jspJavaBlob() |domSplit |String |Spit into a string all the javablob elements of domSplit |

|JspHtml() |domSplit |String |Spit all elements of domSplit into a string, pass through 'html' elements|

| | | |and 'normalize' (transformation of html special chars into &; |

| | | |equivalent ) any other elements |

|JspDocCategory() |domDoc |ArrayList |Select 'Category' tags from domDoc and return the according arraylist |

| | | |(usually a singleton) |

|jspDocSummary() |domDoc |ArrayList |Select 'Summary' tags from domDoc and return the according arraylist |

| | | |(usually a singleton) |

|ParseJavaBlob() |String |DomJavaBlob |Takes the output of jspjavaBlob() and parse it into a DOM (domJavaBlob) |

| | | |tagging every java object according to java 1.2 grammar (JavaCC) |

|JavaBloblocalvariables() |DomJavaBlob |ArrayList |Select appropriate tag nodes and returns an ArrayList of String |

| | | |representing local variable declared in this jsp |

|javaBlobExpressions() |DomJavaBlob |ArrayList |Select appropriate tag nodes and returns an ArrayList of String |

| | | |representing expression used in scriptlet calling methods of java objects|

|parseHtml() |String |domHtml |Takes the output of jspHtml() and parse it into a DOM (domJavaBlob) |

| | | |tagging every html object according to html 4.0 grammar (JavaCC) |

|jspHtmlanchors() |domHtml |ArrayList |Select appropriate tag nodes and returns an ArrayList of String |

| | | |representing tags declared in this jsp |

|jspHtmlforms() |domHtml |ArrayList |Select appropriate tag nodes and returns an ArrayList of String |

| | | |representing tags declared in this jsp |

Summary of PharosDoc API

V - Known limitations & Planned extensions

Functional limitations

• HTML parsing verifies all tags semantic , tag balancing is checked but not tag names balancing

• No checking of taglib tags

• HTML only parse forms and anchors

Planned extensions

• Cross-referencing summary for a jsp file who is referencing it

• With an include directive

• With an anchor hyperlink or a form action

• With a call to include or forward directive applied on a 'java' dispatcher

• Hyperlink on javadocs or taglib documentation files

• CSS documentation

• Deployement 'houskeeping' (jars, wars…)

• Parsing "XML" jsp

Parsing XML JSP

Initially Jsp output is html, but now, one can use jsp to spit xml documents. As such, those document have there own grammar and cannot be parsed with today split grammar. We plan to reshuffle split in two branches, the existing one and the xml track.

VI Installation and environment

Jsp installation

For the application you intend to document, place on the appropriate jsp directory the following jsp

• Directoryjsp2.jsp

• Documentjsp.jsp

• Skeltonjsp.jsp

After installing java classes and changing accordingly the classpath of your server you can access to this service with the following url:

http://[:port]/directoryjsp2.jsp

Note: doInitPage.jsp include directive is only for Pharos, you can comment it to use this service elsewhere.

Java Classes installation

For run time

jspDoc depends on the following jars: xerces_1.4.1.jar and the classes are not wrapped into a jar yet, so you should install the run time under a given directory and set accordingly the classpath. The run time include the following directories

• Com/schneider_electric/ebase/jspdoc/html

• Com/schneider_electric/ebase/jspdoc/javablob

• Com/schneider_electric/ebase/jspdoc/split

For build time

JspDoc assumes ant and javacc are installed on your environement, patch accordingly the env.bat (for windows based system and create a bash file for unix based on nt batch files).

See Build.xml for further details.

Source files are included in

• src/html/input

• src/javablob/input

• src/split/input

All other source files are generated by jjtree and javacc. You can use jjdoc to derive the bnf grammars of the according *.jjt files.

The jspdoc.zip distribution file includes all of the above excluding ant, xerces, javacc.

VII Utilities: conversion from 'classic' to XML format (JSP1.2)

Jsp 1.2 standards defines an alternative format for jsp, complying with an xml grammar.

For example:

'classic' jsp format

*

* positiveTagLib

*

*

*

*

*

* Positive Test taglib directive

*

*

'xml' jsp format

*

*

*

* positiveTagLig

*

* ]]>

*

*

* Positive test taglib directive

*

*

*

*

* ]]>

*

*

|Classic |XML |

| | |

| | |

| | |

| | |

There are two utilities ToXML and ToJSP which convert classic to xml and xml to classic respectively.

ToXML from classic to xml

Usage is: java com.schneider_electric.ebase.jspdoc.ToXML

The performed actions are:

• Get args[0] has the root for jsp file name input

• Create a new PharosDoc, to parse the input file to generate a JSP2XML Dom

• traverse the created document to transform it from JSP2XML Dom format to the JSP 1.2 Dom format

• save this Dom into a .jsp.xml file

ToJSP from xml to classic

Usage is: java com.schneider_electric.ebase.jspdoc.ToJSP

The performed actions are:

• Read a file base on argrs[0]+.jsp.xml

• Parse this file with a regular Dom reader

• Traverse this Dom and transform it to a String representing the jsp

• save the result as argrs[0]+.xml.jsp

VIII Documentation revision history

|Author |Date |Action |

|Gilbert Brault |10/10/01 |Creation of JSPDoc documentation |

|Gilbert Brault |19/10/01 |Documenting translation from 'classic' to xml of jsp |

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download