Page tree
Skip to end of metadata
Go to start of metadata

XML Configuration Files Handling (J2EE)


Note that the CAST Script / FlexFramework feature described in this page is deprecated. You should instead consider using the Extension SDK to handle XML configuration files.

This page provides information about how the J2EE Analyzer handles XML Configuration Files. A web application can contain many configuration files that can be split into two categories:

  1. The Application Descriptor (usually called web.xml)
  2. Framework specific XML configuration Files such as struts-config.xml, tiles-definitions.xml, etc. - predefined profiles for specific frameworks are are selected by default or custom profiles can be created (see Using the Environment Profile Manager). You can also use the J2EE Analysis Unit editor to select XML files individually or per folder.
Application Descriptor

The Application Descriptor is a standard file specified by the JSP specifications. Hence, its format is well known and the J2EE Analyzer can predict how to process it. This is in fact what it does.

The only information it needs to know is the path of this file. Once located and then analyzed, the following objects/links are created:

  1. Application Descriptor (the whole file)
  2. Servlet (for each <servlet> xml element)
  3. Servlet Mapping (for each <servlet-mapping> xml element)
  4. Access Forward link between each Servlet and its corresponding Servlet Mappings.

Note that if a Tiles Definition file is referenced in the application descriptor, this file will also be located and then analyzed. This is triggered by the following code fragment:

<init-param><param-name>definitions-config</param-name><param-value>/WEB-INF/tiles-defs_a.xml,/WEB-INF/tiles-defs_a.xml</param-value></init-param>

In this case, you should not associate the tiles definitions file with an XML Query File/XQuery File (see section on tiles below). Note also that this can also be triggered when present in the struts-config.xml file.

Framework specific XML Configuration Files

Framework specific files use proprietary formats. Since these files have an open structure, the J2EE Analyzer does not know where relevant information is located within these files and thus requires some precision from the user.

To allow this, the J2EE Analyzer provides various ways to specify which piece of information to retrieve and what to do with it (create an object, trace links, etc.).

The two main configuration mechanisms are:

  • Using XQuery files > This method is based on XQuery and Zorba processor outputting the results to an intermediate .castscript language. This is known as the J2EE Analyzer - FlexFramework and is the default process used.
  • Using XML Query files > This configuration mechanism consists of an XML file containing XPATH queries that are used to locate this information.

CAST provides a variety of default XML Query files/XQuery file for various frameworks, which are ordinarily provided via a predefined Environment Profile depending on the Frameworks you include in the analysis. If you require direct access to these XML Query files/XQuery files, they are located in the %CommonProgramFiles(x86)%\CAST\CAST\EnvProf\J2EE sub-folder following a CAST installation. Before writing your own files (and creating your own custom Environment Profiles), take a look at these files and make sure your requirements are not already covered.

NOTE that XQuery files are the default way to handle frameworks. XML Query files will be deprecated in a future release. For new customizations, please use XQuery and CAST Script.

XQuery, Zorba and .castscript - FlexFramework

The FlexFramework is a specific feature for analyzing framework XML Configuration files. This new mechanism is based on XQuery files and the XQuery processor Zorba (http://www.zorba-xquery.com/) - provided by CAST. More information can be found here: J2EE Analyzer - FlexFramework.

This mechanism will take into account third-party frameworks that are increasingly difficult to manage via the existing XML Query file mechanism. The XML Query file mechanism will remain in the J2EE Analyzer for existing frameworks (such as Hibernate, Spring and Struts), but the new mechanism will be used from now on to support new frameworks (such as EJB 3.0) and annotations.

The analysis process functions as follows (a brief overview):

  • XML configuration files for the Frameworks used in your J2EE projects are parsed with Zorba using an XQuery file either supplied by CAST (via an Environment Profile) or defined yourself.
  • The resulting output is called a "CAST Script" (.castscript file). This script is then interpreted within the J2EE Analyzer to create the necessary objects, links and properties.

Writing your own XQuery files

If you want to create your own XQuery file for use against a framework that CAST does not yet support, you need to know various things:

  1. How to write an XQuery file - see http://www.w3schools.com/xquery/default.asp. You can also look at predefined XQuery files provided by CAST and located in %CommonProgramFiles(x86)%\CAST\CAST\EnvProf\J2EE
  2. What the J2EE Analyzer expects as output resulting from the parsing process. The output needs to conform to certain syntax rules, for example:

    use Core.xxx;
    use Core.ConstantsMetamodel;

    /* call to CAST Script function /*
    createComponent(" name ", type) ; /* for type, refer to Core.ConstantsMetamodel */
  3. CAST provides certain common XQuery functions that you can call in your own XQuery files. These functions are located in the file CAST_BasicFunctions.xq stored in %CommonProgramFiles(x86)%\CAST\CAST\EnvProf\J2EE\XQueryLibrary
    To call them in your own XQuery files use the line:

    import module namespace castbasics = "http://www.castsoftware.com/castbasics" at "../XQueryLibrary/CAST_BasicFunctions.xq";

Writing your own CAST Script function

  1. If you want to develop your own functions that will be outputted into the .castscript file, then you must specify these functions and their parent files in a specific location. You can use the CAST Script Library Directory option located in the Platform Settings tab in the J2EE Technology options to define this location.
  2. CAST provides certain castscript Native Functions that can be called by your functions. These functions are located in the folder and sub-folder CAST_INSTALL_DIR\configuration\ Script_Libraries\Core
  3. Write your function in a file under the location you defined in .1
  4. Please see Description of the castscript language for more information.

Notes

  • More detailed information can be found in the CAST Cookbook for J2EE, in addition the J2EE Environment Profiles section explains in more detail how this mechanism works.
  • You can retain the outputted .castscript files by specifying a local or network location in the Debug options when you Run an analysis (see option Keep Generated CAST Scripts from XML and Annotations)
  • You can use the Activate CAST Scripts Traces option in the Debug options when you Run an analysis to display messages in the log relative to the processing of the .castscript files. This can help trace problems and issues with your XQuery files.
XML Query Files

Queries Files, containing instructions in XML format intended for the J2EE Analyzer, can be edited using three main instructions:

  1. <object-node>
  2. <link-node> (previously known as <xref-node>)
  3. <config-file-node>

<object-node> is used to let the J2EE analyzer create an object that will be stored in the Analysis Service. The name, type, scope etc. of the object can be specified using the element's attributes. This element can have any number of <object-node> child elements (provided they have different values for the @name attribute). Relationships with other objects are specified using a <link-node> child element.

<link-node> is used to request link creation from the object introduced by the <object-node> parent element (or the file if parent element is the root element) toward an object that will be searched for using the <link-node> attributes values.

<config-file-node> the purpose of this element is to notify the J2EE Analyzer about a reference to another configuration file within the file against which the current Queries File is run. You can then specify which information to retrieve from the referenced file. To do so, just use the <object-node> and <link-node> elements beneath the <config-file-element>.

Notes

  • Sub-elements are not supported for Tiles Definitions Files yet. This is because the processing of this type of file is done internally. As a result, the <config-file-node> element is used just to indicate the location and type of the file.
  • For each referenced file, an object is created and stored in the Analysis Service. The specific type of the object is given by the @content-type attribute.

Example of a Queries File (to associate with struts-config.xml):

For more details on the attributes, possible child elements and allowed values for each attribute of a given element, refer to the cast-config.xsd file (located in the sub-folder "CAST_INSTALL_DIR\configuration\J2EE\schemas" in the installation folder CAST).

For attributes that accept multiple values (';' separated values) or compound values (i.e. 'resource'), it is recommended that you use them rather than duplicating the containing xml element of the attribute then changing its value.

Finally, set this attribute if you want to gather information from another branch. The obtained value will be used by the variable %context% in the attribute xpath.

Example: xpath="./son[@name=%context%]/val" context="../name"

cast-config.xml (Legacy)

The default cast-config.xml Query File supports struts configuration files. Once this file has been processed, the following objects are created:

  • Forwards (either global forwards or forwards within actions)
  • Action Mapping (for each /struts-config/action-mappings/action element)
  • JSP Bean (for each /struts-config/form-beans/form-bean element)
  • XML Object (for each /struts-config/queries/query , /struts/struts-config/action-mappings/action/exception elements)

For details on how relationships with other objects are created, see the <link-node> child elements of the <object-node> actions that create the objects listed above in the cast-config.xml file.

Sometimes, Forwards @path attributes values (i.e. those containing a URL with the path part ending in .do) may contain, in their query part, information we may be interested in. This is the case when the query part contains a method name as a parameter as in the following code:

<global-forwards> <forward name="logoff" path="/logoff.do?method_name=execute"/> <forward name="logon" path="/logon.jsp"/> <forward name="success" path="/mainMenu.jsp"/></global-forwards>

In this case, we would like to have a link toward the java method execute. To allow that, the new <query-param> element is provided by the J2EE Analyzer. To get the link with the example above, the Queries File needs to contain the following instructions:

<object-node xpath="./forward[@path]" name="./@name" type="forward"> <link-node xpath=".[contains(@path, '.do')]" called-object="./@path" resolve-as="url">  <query-param xpath="./@path"   name="method_name"   resolve-as="java-method"   resolution-scope-src ="/struts-config/action-mappings/action/@type"   default="perform"/> </link-node></object-node>

This tells the J2EE Analyzer to resolve the value of the method_name query parameter, if any, as a java method. If query has no method_name parameter, then use perform as the default value. resolution-scope-src specifies the scope within which the method is to search for. In this example, the /struts-config/action-mappings/action/@type attribute should contain a fully qualified name of a java type.

Notes

  • the resolution-scope-src attribute should normally be set as follows:

    resolution-scope-src = "/struts-config/action-mappings/action[ @path = (begining of this forward's path)]/@type"

    Since the criteria [@path = (begining of this forward's path)] can not be specified with xpath 1.0 (no meanq to reference the forward within the context of an action - in the []), this filter is applied internally: only if <query-param> is used to resolve url parameters of a Forward's path.

    Elsewhere, only the first result returned by the xpath request is considered.
Tiles Definitions File (Tiles 1.0)

CAST supports the Tiles Framework via the processing of its configuration file commonly named tiles-defs.xml. This processing is done internally, meaning that the analyzer recognizes the format of this file and does not need a Queries File to handle it. Hence, you should not associate this type of file with a Queries File while configuring your Job

The J2EE Analyzer finds these files in two ways:

  • While analyzing the Application Descriptor (web.xml)
  • While analyzing the Struts configuration file.

In the first case, the application descriptor contains:

<init-param> <param-name>definitions-config</param-name> <param-value>/WEB-INF/tiles-defs_a.xml,/WEB-INF/tiles-defs_a.xml</param-value></init-param>

In the second case, the Queries File associated with the struts configuration file should contain:

<config-file-node xpath="./struts-config/plug-in/set-property[@property='definitions-config']"content-type="tiles-definitions" location="./@value" /> 

Once these files are located and then processed, the following objects/links will be created:

  • Tiles Definitions File (for each physical file)
  • Tiles Definition (for each /tiles-definitions/definition element)
  • Tiles Definition Attribute (for each /tiles-definitions/definition/put element)

The following table summarizes links traced during the processing. XPath paths are relative to the element that introduced the caller (i.e. for Tiles definition it is /tiles-definitions/definition):

Caller Callee Callee Resolved As Link Type
Tiles Definitions File Each Tiles Definition - Access
Tiles Definition ./@path

./@template

./@page

URL Access + Include
./@extends Bean (Tiles Definition) in global scope Inherit + Extend
./@controllerClass java-type Call
./@controllerUrl URL Call
Tiles Definition Attribute ./@value

./@content

java-type

URL

Bean

Use
Tiles Definition Attribute Tiles Definition Attribute with the same name in the nearest Tiles Definition in inheritance graph - Hide
STXX

Support for STXXThis is done by processing its configuration file commonly called stxx-transforms.xml.

This file can be associated with a Queries File (with STXX 1.1 and 1.2 in plug-in mode). In this case, the object created for the file will have the XML Configuration File type. This is the case for all files that have this association. However, this is not the recommended way if you use STXX above struts and plan to associate the struts configuration file with the default cast-config.xml file. Indeed, this file contains instructions specifying how to find STXX files and what information to retrieve.

The Analyzer finds transforms definitions in three ways according to the STXX version you are using:

1: STXX 1.0 (struts 1.0)

In this version, configuration information required by the framework is located in the Struts configuration file. Hence, each transform definition is placed beneath a forward definition as shown below:

<action path="/contactListExample" type="com.oroad.stxx.example.ContactListExampleAction" scope="request"> <forward name="success">  <transform name="default" path="/contactListExample.xsl"/> </forward></action>

In this case, queries required to process this information are placed in the same file as those dealing with struts-config.xml. An STXX Transform object named "default" (in this example) is then created beneath the Forward object and the value of the @path attribute is resolved as a URL.
The queries corresponding to this should look like this:

<object-node xpath="./forward[transform]" name="./@name" type="forward"> <object-node xpath="./transform" name="./@name" type="stxx-transform">  <link-node xpath="." called-object="./@path" resolve-as="url" /> </object-node></object-node>

2: STXX 1.1 (struts 1.1)

Version 1.1 provides, in addition to the way transforms are defined in version 1.0, another mode known as plug-in mode. In this mode, transforms are defined in an external file (stxx-transforms.xml). The struts-config.xml file references the transforms file using a <plug-in> element as follows:

<plug-in className="com.oroad.stxx.plugin.StxxPlugin" > <set-property property="transform-config" value="/WEB-INF/stxx-transforms.xml" /></plug-in>

Since this code is in the struts configuration file, a <config-file-node> element that points to the <plug-in> node should be used in the Queries File to retrieve the transforms file path. Objects (only Transforms) and links to be created can then be specified using the <object-node> and <link-node> elements beneath <config-file-node> (within the same Queries File):

<config-file-node xpath="./struts-config/plug-in/set-property[@property='transform-config']" content-type="stxx-transforms" location="./@value" version="1.1"> <object-node xpath="./transform-definitions/transform"  name="./@name" type="stxx-transform">  <link-node xpath="." called-object="./xsl/file/@name" resolve-as="url"/>  </object-node></config-file-node>

Transforms are defined this way (in stxx-transforms.xml):

<transform-definitions> <transform name="addressBookExample.dox">  <xsl selector="default">   <file name="/addressBookExample.xsl"/>  </xsl>  <xsl selector="MSIE">   <file name="/addressBookExample_IE.xsl"/>  </xsl> </transform>...</transform-definitions>

For each Transform, a link is traced toward the corresponding file (called-object="./xsl/file/@name" resolve-as="url"). A link is also created between Forwards whose @path attribute value ends with ".dox" and the Transform whose name matches this value.

3: STXX 1.2

Version 1.2 works with the two modes seen above. The difference resides in the transforms file format. Indeed, Transforms are defined within Pipelines (a type of pattern) as follows:

<pipeline-definitions> <pipeline match="simple/*.dox">  <transform type="html">   <param name="path" value="/{1}.xsl" />  </transform> </pipeline></pipeline-definitions>

In this case, the J2EE Analyzer will always create a Pipeline object with the @match attribute value (i.e. "simple/*.dox") for name. For a Transform to be created beneath the pipeline, it needs first to be referenced (i.e. by the @path attribute of a <forward> element in struts-config.xml) and secondly, its associated file should exist physically. This file's path is given by the value of @value attribute of the <param> sub element. This value is not usable as is. Indeed, it contains place holders (digits from 1 to 9) that should be expended using the reference string. The code below gives an example of a reference of the transform defined above.

<action path="/index"type="com.oroad.stxx.example.IndexAction"scope="request"><forward name="success" path="simple/index.dox"/></action>

To resolve the reference string simple/index.dox, the Analyzer first looks for a Pipeline that matches simple/index.dox. The Pipeline of the example does match this string with the * corresponding to index.

  • Each * in the Pipeline name represents a character string without "/".
  • Each ** in the Pipeline name represents a characters string including "/".
  • Each matched string (using both * or **) is referenced within the transform definition using a digit that corresponds to its occurrence order in the Pipeline's name.
  • In the code <param name="path" value="/{1}.xsl" /> the 1 will be matched with the string index leading to <param name="path" value="/index.xsl"/>.

So, if the file /index.xsl is found, then the following objects/links will be created:

  • A Transform named simple/index.dox (beneath the Pipeline object)
  • An eFile object to represent the called file (/index.xsl)
  • A link from the Transform toward the eFile.
  • A link from the Forward toward the Transform.

Notes

  • <param> elements that are taken into account are those having a @name attribute set to "path", "page" or "xform".
  • Configuration for all three STXX versions is done in the default cast-config.xml file.

CAST Website

  • No labels