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

On this page:

Summary: this pages describes all analysis configuration options that are available for the JEE Analyzer.

Introduction to analysis configuration options

The CAST Management Studio has three levels at which analysis configuration options can be set:

Technology
  • The options available at this level are valid for all Applications managed in the CAST Management Studio.
  • These are the default options that will be used to populate the same fields at Application and Analysis Unit level. If you need to define specific options for a specific Application or Analysis Unit, then you can override them.
  • If you make a change to a specific option at Application or Analysis Unit level, and then subsequently change the same option at Technology level, this setting will NOT be mirrored back to the Application or Analysis Unit - this is because specific settings at Application and Analysis Unit level have precedence if they have been changed from the default setting available at Technology level.
Application
  • The options available at this level set are valid for all corresponding Analysis Units defined in the current Application (so making changes to a specific option will mean all Analysis Units in that specific Technology will "inherit" the same setting). If you need to define specific options for a specific Analysis Unit in a specific Technology, then you can do so at Analysis Unit level.
Analysis Unit
  • Options available at this level are valid only for the specific Analysis Unit.
  • An Analysis Unit can best be described as a set of configuration settings that govern how a perimeter of source code is consistently analyzed.
  • Analysis Units are automatically created when you use the Set as current version option to deploy the delivered source code - as such they correspond to Projects discovered by the CAST Delivery Manager Tool. However, they can also be created manually for situations where no Analysis Unit has been automatically created for a given project.
    • When the Analysis Unit has been created automatically, options will "inherit" their initial configuration settings from the discovery process in the CAST Delivery Manager Tool (i.e. "project" settings). Where an option could not be defined automatically via the CAST Delivery Manager Tool, it will "inherit" its initial configuration settings from those defined at Technology level and at Application level.
    • Analysis Units that are manually defined will "inherit" their initial configuration settings from the settings defined at Technology level and at Application level.
  • Modifying an identical option at Technology level or at Application level will automatically update the same option in the Analysis Unit editor unless that specific option has already been modified independently in the Analysis Unit editor.

Some settings at Application and Analysis Unit level have a "Reset" option - using this will reset the option to the value set at the parent level:

Auto-configuration validation

Technology / Application level

Using the Technology level or Application level options, validate the Analysis settings for JEE packages. Make any update as required. These settings apply to the Technology or Application as a whole (i.e. all Analysis Units):

Analysis Unit level

As explained in JEE Analyzer - Packaging, delivering and analyzing your source code, the CAST Delivery Manager Tool extracts relevant information used to create the automated analysis configuration from the JEE project files. Currently the extension supports these build project files:

  • Eclipse - all version greater than 3
  • Maven - version 2 and 3

For any other build project format (e.g. Apache -ant) the CAST Delivery Manager Tool will not be able to automatically retrieve build information: no Analysis Unit will be created and no analysis configuration provided. To address this situation, the Analysis Unit and the analysis configuration should be created manually. This case falls outside of the out-of-the-box support and is out of scope of a standard analysis.

To inspect the auto-generated analysis configuration, you should review the settings in each Analysis Unit - they can be accessed through the Application editor:

Technology options

The available options for configuring an analysis are described below. Note that some options are not available at specific levels (Technology/Application/Analysis Unit):

Source Settings

This tab and its child tabs (Java, Resources and Web Application) show the location of each type of source code in the JEE Analysis Unit - this is determined automatically by the CAST Delivery Manager Tool. You should, however, review the configuration and make any changes you need (click to enlarge):

Java tab

Java File ExtensionsThis section displays a list of the file extensions that are included in the current file filter for your Java code analysis. Only files that match these file extensions will be taken into account during the analysis.
Java Files

Use this section to include or exclude specific source files for the Analysis Unit for analysis purposes - these are mainly to be used when you are manually creating your Analysis Unit but can also be used if you are modifying an automatically created Analysis Unit.

  • Use the the various buttons to include or exclude specific Source Files (in the case of files, only files matching the choices made in Java File Extensions above will be considered) or Source Folders (folders are searched recursively).
  • By default CAST will automatically suggest the Deployment Folder set in the Current Version tab (at Application level) for your Package when adding new source code folders or files.
  • If this Analysis Unit is automatically defined and you have added additional entries, use the  button to reset the list to the entries defined by the CAST Delivery Manager Tool
If this Analysis Unit is automatically defined, then any auto defined entries will be read only.

Resources tab

XML / properties files

These options manage the location of your XML and .properties files.

You can find out more about:

XML File Extensions

This section displays a list of the file extensions that are included in the current file filter for the XML files in your analysis. Only files that match these file extensions will be taken into account during the analysis.

Equivalent option is not available for .properties files.
Also use Project Root Path for XML / Property FilesIf you select this option, the project root path (i.e. the location of the .project file for the Analysis Unit) will be used as a source for the XML / .properties files. If you wish to add additional source files use the option described below.
XML / Property Files

Use this section to include or exclude specific source files for the Analysis Unit for analysis purposes - these are mainly to be used when you are manually creating your Analysis Unit but can also be used if you are modifying an automatically created Analysis Unit.

  • Use the the various buttons to include or exclude specific Source Files (in the case of files, only files matching the choices made in XML / Properties File Extensions above will be considered) or Source Folders (folders are searched recursively).
  • By default CAST will automatically suggest the Deployment Folder set in the Current Version tab (at Application level) for your Package when adding new source code folders or files.
  • If this Analysis Unit is automatically defined and you have added additional entries, use the  button to reset the list to the entries defined by the CAST Delivery Manager Tool
If this Analysis Unit is automatically defined, then any auto defined entries will be read only.

Web Application tab

The JEE Analyzer extension supports the analysis of web applications that do not contain a web.xml application descriptor. In this situation, the "Web Application Root Path" (i.e. the location of web server files such as *.XHTML and *.JSP) can be automatically discovered by the analyzer based on the location of the web files on disk. To this end, the field Web Application Root Path at Analysis Unit level is now an optional field in the CAST Management Studio. If the source code does not contain a web.xml file, the Web Application Root Path is now automatically discovered by exploring each Analysis Unit's project path (i.e. the location of the .project file) on disk, however, it can be overridden manually.

Web Application Root PathIndicates the folder that is defined as the web application root folder for the Analysis Unit for analysis purposes. The Web Application Root Path is the path to the folder that contains web server files (*.XHTML, *.JSP etc.). This field does not need to be populated (i.e. it is optional).

If this Analysis Unit has been automatically defined during the "Set as Current Version", then the JEE Analyzer will attempt to populate this field automatically. You can choose a different location (use Browse) if necessary, however, CAST recommends letting the CAST Management Studio handle this.

Note that:

  • when available, the Project path (i.e. the location of the .project file) of the Analysis Unit is used as a base folder to discover XML / Properties and for Web files (when there is no Web Application Root Path configured).
  • when a Project path (i.e. the location of the .project file) is not available (for a User Defined Analysis Unit for example), the "Web Application Root Path" is still used as before (i.e. it indicates the folder that is defined as the root folder for the Analysis Unit for analysis purposes.
  • It is possible to analyze web applications that do not contain a web.xml file (mandatory to support Servlet 3.0). In this case, the "Web Application Root Path" will be automatically discovered by the analyzer based on the location of the web files on disk (if the field is populated then this path will be used instead of an automatic discovery).
Web Application Descriptor

Indicates the JEE application's Web Application Descriptor. By default, the JEE Analyzer will use the Web Application Root Path set above and append \WEB-INF\web.xml. If this is not correct for your application, you can choose a new Application Descriptor.

Note that path resolution for the objects defined inside the selected web.xml file (for example tag libraries) is made using the default location of the web.xml file (\WEB-INF folder).

Web Server

Web Server File ExtensionsThis section displays a list of the file extensions that are included in the current file filter for your source code analysis. Only files that match these file extensions will be included in the analysis.
Also use Web Application Root Path for Web Server FilesIf you select this option, the Web Application Root Path will be used as a source for the web server files. If you wish to add additional source files use the option described below.
Web Server Files

Use this section to include or exclude specific source files for the Analysis Unit for analysis purposes - these are mainly to be used when you are manually creating your Analysis Unit but can also be used if you are modifying an automatically created Analysis Unit.

  • Use the the various buttons to include or exclude specific Source Files (in the case of files, only files matching the choices made in Web Server File Extensions above will be considered) or Source Folders (folders are searched recursively).
  • By default CAST will automatically suggest the Deployment Folder set in the Current Version tab (at Application level) for your Package when adding new source code folders or files.
  • If this Analysis Unit is automatically defined and you have added additional entries, use the  button to reset the list to the entries defined by the CAST Delivery Manager Tool
If this Analysis Unit is automatically defined, then any auto defined entries will be read only.

Web Client Files

The JEE Analyzer does not support the analysis of web client files such as *.HTML, *.CSS, *.JS. These files must now handled by the HTML5 and JavaScript extension.

Analysis

The settings in this tab govern how the source code is handled by the analyzer (click to enlarge):

Java

Java Version

The analyzer will assume that that latest version of the JDK has been used to compile the application source code.

If your application source code does not use the latest JDK, you can override the selection manually:

Note that:

  • selecting a JDK version will automatically apply the corresponding default Environment Profile.
  • Java version selection is used for syntax and semantic checking.
Class Paths

 Class Paths are automatically discovered by the CAST Delivery Manager Tool through the inspection of the project files. If the project files are missing, Class Paths must be added manually to the Analysis Unit and must be discovered via inspection of the delivered source code or by inquiring with the Application Team.

The analyzer uses this information to search for external classes that are referenced in project code but not defined in your source code files. Classpath entries can be either a file or a folder. When analyzing a folder, the analyzer assumes that classes are correctly deployed on disk and that they respect the naming convention where a package maps to a folder and a class maps to a file.

  • Use the Add button to define your class path files (typically an archive file) or folders. You will be prompted to select the type you want to add:

Add New Archive FileIf the project uses external classes packaged in a JAR file, use this option to define the location of a single JAR file. You can define multiple JAR files as separate entries, although consider using the Add New Archive Folder option if the project uses multiple JAR files.
Add New CLASS Root FolderIf the project uses external classes defined in .class files, use this option to define the location of the root folder. You can define multiple CLASS root folders. All .class files in the folder and any sub folders (if the Recursive option is ticked) will be taken into account. .java files are ignored.
Add New Archive FolderIf the project uses external classes packaged in JAR files, use this option to define the location of the folder containing the JAR files. You can define multiple Archive Folders. All JAR files in the folder and any sub folders (if the Recursive option is ticked) will be taken into account
  • Use the Edit button to edit an existing class path.
  • Use the Up arrow and Down arrow buttons to re-order the list of class paths. This is important because the order in which the items appear in the list, is the order in which the analyzer will handle them.
  • Use the Delete button to remove an existing entry
  • If this Analysis Unit is automatically defined and you have added additional entries, use the button to reset the list to the entries defined by the CAST Delivery Manager Tool
  • If you define any JAR archives (individual archives or archives located in a folder), during the analysis the archive(s) will be unpacked in memory and analyzed.
  • For all options, only .class files are taken into account. .java and .XML files will be ignored. This includes the two options allowing you to specify JAR archives.
  • By default all folders defined will have the Recursive option activated indicating that all folders contained within the selected folder will be searched recursively. You can toggle this as required:

  • When defining a class path, instead of listing all the subdirectories of package, it is more convenient to add the folder that contains the package. For example: if a Java file contains: "import com.Pkg1.Pkg2.*" and these packages are located in the folder "<DIR>/com/Pkg1/Pkg2", simply add the folder <DIR> to the class path.

Web Application

This section governs the settings that will be applied if your JEE project is defined as a web application:

Enable JEE Web Profile Analysis

YESWhen set to the default YES position, the analyzer is capable of analyzing web files (.JSP, .XHTML etc) even if no Web Application Descriptor (web.xml) is present in each Analysis Unit in the Application. These web files are instead identified for analysis by exploring each Analysis Unit's Analysis Unit's project path (i.e. the location of the .project file).
NO

When set to the NO position, the behaviour will revert to pre-CAST AIP 8.2.x. In other words a Web Application Descriptor (web.xml) must be present in the Application and defined in the relevant field in each Analysis Unit in order that web files (.JSP, .XHTML etc.) are analyzed.

Web Client Files

The JEE Analyzer does not support the analysis of web client files such as *.HTML, *.CSS, *.JS. These files must now handled by the HTML5 and JavaScript extension.


JEE (Servlets/JSP) version used by the application

The analyzer will assume that that latest Servlet/JSP version has been used to compile the application source code.

Use the drop down list box to choose the correct option if your application source code uses an older version. It is possible to obtain the JSP version in use by opening the application's web.xml file and locating the DTD version used to define the servlet - this is the servlet version. The servlet version is 2.3 in the example below:

<!DOCTYPE web-app PUBLIC
   "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
   "http://java.sun.com/dtd/web-app_2_3.dtd">

Using this information, see the table below for equivalence:

Servlet versionJSP version
2.1 or 2.21.1
2.31.2
2.42.0
2.52.1
3.02.2
3.12.3

Frameworks

For more information about frameworks see JEE framework analysis.

The Framework section governs the analysis settings used when a specific Java framework is present in your source code. These pre-defined settings are designed to address specific recurrent issues during analysis and correspond to default Environment Profiles. Each framework has an associated drop down list box with various options:

JPA (Hibernate), Struts and Spring

By default, the option for these Frameworks will be set to "Latest". In other words, the analyzer always assumes that you are using the latest available release supported by the JEE analyzer extension. You can override the default setting if required:

Note that from in JEE Analyzer ≥ 1.1.0, the Struts Version combo box has no impact: by default, all supported versions of Apache Struts are handled by default. The combo box will be removed in a future release.

Web Service (WBS) Version and EJB2 (Enterprise Java Bean) Version

Auto discovery and configuration of Web Services (WBS Services) and Enterprise Java Bean (EJB) is not supported. The CAST AI Admin will need to gather the required information from the application team or inspect the delivered source code to determine the proper configuration of these parameters. Then a decision will need to be made to select the correct version of each:

Web Services

EJB

Note:

  • To find out if your application implements web services, simply search for files with the extension .wsdl or .wsdd in the source file directories. Usually, these files are located in the META-INF directory, but as the source folders do not always match the production folder tree, we recommend searching all the source files.
  • If you explicitly select an EJB2 profile (see above) then all configuration regarding EJB 3.x will be automatically deactivated.

Other frameworks

Other frameworks, such as those listed below are always handled "out-of-the box":

  • EJB3, 3.1, 3.2
  • JSF
  • CDI
  • Common-logging
  • Dom4
  • JUnit
  • Log4J
  • MX4J
  • CICS ECI/CTG

Note:

  • versions for EJB 3.x, JSF, CDI will follow the Java Version (i.e. the JDK) that is set for the source code.
  • if you explicitly select an EJB2 profile (see above) then all configuration regarding EJB 3.x will be automatically deactivated.

When unsupported frameworks (i.e. not supported out-of the box) are part of the delivery, a Custom Environment Profile needs to be created to enable correct processing. To identify unknown frameworks or custom frameworks, there are various methods:

  • Find all the XML files and look at the DTD they are referring to. This allows you to find frameworks like Spring, Hibernate... (You can use UltraEdit or a grep command to find the pattern DTD inside XML files in one go). Examples:

Framework

DTD

Hibernate

<!DOCTYPE hibernate-mapping PUBLIC 
"-//Hibernate/Hibernate Mapping DTD 2.0//EN" 
"http://hibernate.sourceforge.net/hibernate-mapping-2.0.dtd"> 
<!DOCTYPE hibernate-configuration PUBLIC 
"-//Hibernate/Hibernate Configuration DTD 2.0//EN" 
"http://hibernate.sourceforge.net/hibernate-configuration-2.0.dtd">

iBATIS

<!DOCTYPE daoConfigPUBLIC "-//iBATIS.com//DTD DAO Configuration 2.0//EN""http://www.ibatis.com/dtd/dao-2.dtd">

Spring

<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
  • Look at the libraries: the names of the libraries can give you an indication. Examples:

Framework

Libraries

Hibernate

hibernate3.jar

iBATIS

ibatis-common-2.jar 
ibatis-dao-2.jar 
ibatis-sqlmap-2.jar

Spring

spring-1.2.7.jar

If you have detected this framework through an XML file, you can start to customize the support of this XML (see Manage XML configuration files), but in any case, CAST recommend that you read up how it works and how it is configured.

Text Replacements

This section enables you to define Regular Expressions (that match character strings in your selected files) that you want to replace with other text:

  • Click the Add button to add a new line to the table listing the Text Replacements
  • Double click the new line in the table and a hidden section will appear in which you can enter the details you require:

  • Enter the Regular Expression in the Regular Expression field.
  • Chose the type of Regular Expression in the drop down list:
    • Perl (default format) - Specifies that when a regular expression match is to be replaced by a new string, that the new string is constructed using the same rules as Perl 5.
    • Sed - Specifies that when a regular expression match is to be replaced by a new string, that the new string is constructed using the rules used by the Unix Sed utility in IEEE Std 1003.1-2001, Portable Operating System Interface (POSIX), Shells and Utilities.
    • Tcl - Specifies that when a regular expression match is to be replaced by a new string, the text that matches the regular expression will be replaced by the replacement text.
  • Enter the text you want to replace the Regular Expression with, in the Replacing Text field.
  • The new line in the table above should now be populated with your changes:

 

  • The arrow buttons enable you to re-order the text replacements. This is important because the order in which the items appear in the list, is the order in which the analyzer will replace the character strings that match the Regular Expressions. Thus, if you have a complicated set of Regular Expressions and replacement texts, difficulties could arise if the order in which they are dealt with is not correct.
  • Use Text Replacement with caution. First try to change the source tree to reflect the production environment and then use Text Replacement for other cases.

Production

Data to generate

Add called files to selected files listSelecting this option will automatically add any files to the list of files selected for analysis that are called by files that you have already selected.
Add included files to selected files listSelecting this option will add any files to the analysis list that are included in files that you have already selected.
Maximal Complexity
This option enables you to manually enter a percentage which will refer to the m complexity of the analysis process.
  • A complexity percentage of 100 (default) corresponds to a maximum of 10,000 function analyses (function * context) for a given file.
  • A complexity percentage of 70 corresponds to a maximum of 7,000 function analyses (function * context) for a given file.
  • A complexity percentage of 0 corresponds to an unlimited analysis of all the called functions.

 

If the maximum number of function analyses is reached, this will be logged.
File analysis too complex. Next function calls will not be followed by a function analysis if the function has already been analyzed

When the limit is reached, links to the function will be created correctly, but links from the function will not be created.

You should alter the complexity percentage if your analyses are taking a long time to complete with the default setting of 100%. Changing the percentage to a lower figure will reduce the number of function analyses for a given file, thus improving performance. Remember though that doing will cause some links not to be created.

Process Settings

Inference Engine

Use Inference EngineUse this option to activate the Inference Engine during the analysis. Run time type information will be computed in order to simulate program behaviour during execution of the analyzer and thus identify additional links that would not otherwise be "discovered" using standard analysis techniques. This technology detects a reference to an object wherever its name is mentioned, regardless of the context in which this reference occurs.

Please note that disabling the Inference Engine:

  • will cause the CAST Quality Rule "Serialize session objects" to not be calculated.
  • will not affect the execution of the User Input Security feature - the same results will be achieved.
String Concatenation

When the Inference Engine is active, this value limits the number of strings that will be found during the search of each object value.

Note that limiting the number of strings can lead to incomplete results, however, performance is improved.

Procedure Call Depth

When the Inference Engine is active, this value limits the number of intermediate values that the Inference Engine must resolve in order to obtain the value of the object that is being searched for.

Note that limiting the number of intermediate values can lead to incomplete results, however, performance is improved. The lowest value you can enter is 1.

Local Procedure Complexity

When the Inference Engine is active, this value limits searches of large methods that have a high Cyclomatic Complexity level.

Dataflow

Procedure Call DepthWhen the User Input Security feature is active, this value limits the number of intermediate values that the User Input Security Engine must resolve in order to obtain the value of the object that is being searched for.

Note that limiting the number of intermediate values can lead to incomplete results, however, performance is improved. The lowest value you can enter is 1.

Execution

Number of Instances

This option allows you to limit the number of objects held in memory before they are committed to disk during the save process of an analysis.

Please contact CAST Support before modifying this option.

See the CAST Management Studio help for more information about this global option.

Platform Setting

The Platform Setting tab is only visible at Technology level.
CAST Script Library DirectoryAs part of CAST's framework XML Configuration file and Java Annotation extraction process via XQuery and Zorba, you are free to design your own XQuery files that will output data to a .castscript file in a syntax that can be understood by the analyzer.

However, 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 Custom CAST Script Root Library path option (see above) to define this location.

These libraries will then be used when they are invoked in the .castscript file during the analysis.

Please see Manage XML configuration files for more information about this.

CAST Tags Extension FolderUse this option to designate a local folder that will contain your .tagsextension files. An absolute path to the folder is required. Please see Manage JSP custom tags for more information.
Choose Deployment FolderThis option can be used when an analysis fails if a path to .JAR file (or its subfolders) that is unpacked to disk during the analysis exceeds the maximum Windows file path length (260 characters). CAST recommends entering a folder located near the root of the drive (for example D:\CAST) or a folder with as short a path as possible.
XQuery CommandThis option enables you to use a custom parsing method for parsing your XML Configuration files (for example an XSLT transformation) with a parser of your choice (for example XQuilla).

If you intend to use this option you need to enter a command line as specified in the following example for XQuilla (see http://xqilla.sourceforge.net/CommandLine).

C:\Program Files\XQilla\xquilla.exe $(CASTCommonDir)\EnvProf\iBatis\iBatis.xquery -i $(Input) -o $(Output) -v root $(AppRoot)

  • $(Input): will be replaced during the analysis with the XML file to parse (i.e. your framework specific XML configuration file)
  • $(Output): will be replaced during the analysis with the temporary .castscript file, which is then used by the J2EE Analyzer to create the objects, links and properties
  • $(AppRoot): will be replaced during the analysis with the Web Application Root Path defined in the J2EE Analysis Unit editor
  • $(CASTCommonDir): will be replaced by C:\Program Files\Common Files\CAST\CAST (for example if you store your XQuery files at this location)

Note that these macros are all case-sensitive. Please see also: JEE Analyzer - Environment Profiles

Dependency settings

If the CAST Delivery Manager Tool did not detect any inter-Analysis Unit dependencies (i.e. Discovered dependencies) then it will create a "global" default dependency between JEE and JEE. CAST highly recommends that this default rule is removed if the deployed package contains more than three Analysis Units. In addition, CAST highly recommends that you avoid creating a custom JEE > JEE rule if the deployed package contains more than three Analysis Units.

This global default rule can cause the creation of inaccurate links between objects which has a knock on effect on Quality Rule results and on Quality Rule results and on Transaction flow.

Manual configuration

When the automated configuration fails or it is not possible (i.e. project build file format not supported), the CAST AI Admin must resort to an in-depth inspection of the source code to build the Analysis Unit and configure them manually.  For typical JEE applications this would require the identification of all application components including:

  • A presentation layer
  • A persistent/session layer
  • A business layer
  • (Optionally) a web service layer
  • (Optionally) other components

Advanced J2EE Configuration

Please see the following pages for more information about advanced J2EE analysis configuration:

The discovering of frameworks, other than Hibernate, Struts or Spring, supported out-of the-box by CAST AIP, is based on pattern matching on the .jar files delivered. Configuration for those is a simple Yes (if a .jar file matching is found) and No otherwise. When unsupported frameworks (i.e. not supported out-of the box) are part of the delivery, a Custom Environment Profile need to be created to enable correct processing. See  Review Dynamic Links for further details about how to address missing links situations.

  • No labels