Introduction

JEE Environment Profiles provide the means to configure various J2EE analysis variables:

Creating a profile

After clicking the  icon next to J2EE Environment Profile, a new screen will be displayed containing various tabs:

• General > For defining a name for the Environment Profile and for defining Class Paths
• Parametrization > For defining Method Parametrization
• Java Annotations > For defining support Java Annotations
• XML > For defining support for XML Configuration files
• JavaScript Frameworks > For defining the JavaScript libraries used in your source code that you want to flag as "external".

General tab

• Enter a name for the Environment Profile. Choose a name that is easily recognizable as this name will be displayed in the left hand collapsible list and will be used when you add the Environment Profile at Application or Analysis Unit level.

Class Paths

• Click the following to:
  
  > add a new path. Note that, when defining a class path, instead of listing all the subdirectories of package, it is more convenient to add the directory that contains the package. For example: if a JAVA file contains: "import com.Pkg1.Pkg2.*" and these packages are located in the directory "<DIR>/com/Pkg1/Pkg2", simply add the directory <DIR> to the class path.
  
  This will save you time both during job creation and during the analysis.
  
    > add a new archive folder  > add a new archive
• You can add as many Class Paths as you want.
• The columns Recursive and Save Called Objects in KB will automatically be selected (a green check mark will be displayed in the list) - except for archives where the Recursive option is not available:
  
  - Recursive indicates that the contents of all sub-folders in your path will be included if selected.
  - Save Called Objects in KB indicates that any objects in the Include Path will be automatically stored in the Analysis Service. As a result you will be able to view the associated links and objects in CAST Enlighten and compute Quality Rules and metrics that depend on them. If you need them only to resolve external references and want to save space in the Analysis Service you should uncheck the option - they will not be stored in the Analysis Service.
  
  If you do not require either of these options, click the green check mark in each column. The check mark will then be removed indicating the option is not activated.
• You can use the  button to make an identical copy of a selected Class Path
• You can use the  button to remove a selected Class Path
• If you have two or more Class Paths, then you can use the Up and Down arrow buttons to re-order the paths. This is important as the order they appear in the dialog box is the order in which the paths are dealt with during the analysis process.
• Please note that you can also use the CAST AIP environment variable $(CastCommonDir) when adding an include path. This variable corresponds to the CAST installation folder "%CommonProgramFiles%\CAST\CAST". When you are using a non-English version of the Windows, this variable will be localized.

To apply the new paths, make sure you click the Apply button. If you want to clear the entire window and revert to the default settings, click the Restore button.

Parametrization tab

The Parametrization tab enables you to define Method Parametrization so that the analyzer can correctly identify links that are created with custom methods.

You can either import existing Java methods from the Analysis Service (results from previous analyses that have already been run) or add new custom Java methods or methods that cannot be imported as they do not form part of an existing analysis stored in the Analysis Service. You then need to define your method rules and the action that the analyzer needs to undertake when the method in question is encountered during an analysis.

The parametrization process is complex and as such a much more detailed explanation of the configuration process can be found in the CAST Management Studio product help.

Briefly:

• Click the  icon to import existing methods from the CAST Analysis Service. The Import dialog box will be displayed.
• Click the  icon to create a new parametrization rule - the Add/Edit Rule dialog box will be displayed.
• You can add as many Methods as you want (click the  icon again).
• You can use the  button to make an identical copy of a selected Method
• You can use the  button to remove a selected Method an its parameterization

To apply the settings, make sure you click the Apply button. If you want to clear the entire window and revert to the default settings, click the Restore button.

Java Annotations tab

The Java Annotations tab enables you to define Java Annotations that are present in your J2EE project. A more detailed explanation of Java Annotations and how they are supported can be found here: Support for Java Annotations

Note that CAST provides predefined Environment Profiles for some Annotations. See for example the Hibernate 3.2 Environment Profile that contains support for Hibernate 3.2 Annotations, or the EJB 3.x Environment Profile (both of which are applied by default). If you require direct access to these XML Query Files and XQuery files, they are located in the "%PROGRAMDATA%\CAST\CAST\Extensions\com.castsoftware.jee.<version>\EnvProf\J2EE" sub-folder. Before writing your own XML Query Files and XQuery files, take a look at these files and make sure your requirements are not already covered.

The tab contains the following column headings:

Creating a Java Annotation rule

• Click the  icon to create a new Java Annotation rule - the Add/Edit Rule dialog box will be displayed:

• Enter a name for your Annotations Group in the Annotation Group Name field
• Click the  button to add an initial set of annotations - you simply need to click in the field to enter the package containing the annotations

Note also that you can Ignore a particular annotation package if required - simply tick the Ignore column in the Add/Edit Rule dialog box:

• During the analysis, the analyzer will then ignore any matching Annotations (they will still be saved to the Analysis Service, but the matching annotations will not be saved in the generated XML Annotation File as is the case for other annotations referenced in the Environment Profile when Ignore is not selected. In addition, warnings about this annotation will no longer appear in the Log window).
• Next choose the XML Parsing Method from the drop down list. This also affects what you choose in the XQuery File or Executable Command Line field directly underneath:

• Click OK to save the settings (this will close the Add/Edit Rule dialog box)
• You can add as many Annotation packages as you want (click the  icon again).
• You can use the  button to make an identical copy of a selected Annotation rule
• You can use the  button to remove a selected Annotation rule

To apply the settings, make sure you click the Apply button. If you want to clear the entire window and revert to the default settings, click the Restore button.

XML tab

The XML tab has been provided so that you can more easily add XML Configuration files to your analysis that match certain criteria:

• XML Filename Pattern
• XPath
• DTD Pattern
• XSD Pattern

If you wish to select specific XML Configuration files, please do so at Analysis Unit level which allows the selection of files individually or per folder and then select the appropriate Environment Profile that will automatically take into account these XML Files. These XML Configuration Files can have any structure you want provided they are written in XML language. 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 configuration mechanism provides a way to specify which piece of information to retrieve and what to do with it (create an object, trace links, etc.).

There are three methods of extracting the information from the XML Configuration files:

• XML Query file - traditional method consisting of an XML file containing XPATH queries that are used to locate this information. These files are known as XML Query Files. See Manage XML configuration files for more details on how to write such files and how they are used by the Analyzer.
• XQuery file - method based on XQuery and Zorba processor (see Manage XML configuration files) and intermediate .castscript language
• Custom - custom method using a processor of your choice

CAST provides a variety of default XML Query Files and XQuery files for various frameworks, with appropriate Environment Profiles that define which XML Configuration files must be handled by these XML Query Files and XQuery files. If you require direct access to these XML Query Files and XQuery files, they are located in the "%PROGRAMDATA%\CAST\CAST\Extensions\com.castsoftware.jee.<version>\EnvProf\J2EE" sub-folder following a CAST installation. Before writing your own XML Query Files and XQuery files, take a look at these files and make sure your requirements are not already covered.

Column Headings

The following columns are displayed in the XML tab:

• XML - This column displays the XML file matching criteria (selected XML files will be those that match one of the criteria (an OR is performed).
• Ignore - This column indicates whether the matching XML Configuration files are to be ignored in an analysis
• XML Query - This column indicates which XML Query file has been associated to the XML files that meet the matching criteria

Adding new matching criteria/XML Query Files

• Click the  icon to create a new matching rule - the Add/Edit Rule dialog box will be displayed.
• Use one of the following buttons to first enter your matching criteria:
  •  - Allows you to add XML Configuration files according to a specific filename pattern. Use the following Regular Expressions:
    • * = a string of characters not containing any "/". E.g.: *-servlet.xml (would match cast-servlet.xml)
    • ** = a string of characters that contain "/". E.g.: **-servlet.xml (would match test/project/new/cast-servlet.xml, or test/cast2-servlet.xml)
    • ? = one character. E.g.: ?-servlet.xml (would match a-servlet.xml)
  •  - Allows you to define an XPath. Then, all XML files that contain the specific XPath will be taken into account.
  •  - This option enables you to define a pattern that matches the path of a DTD, which the required XML Configuration files must conform to. The aim of this option is to provide support for files that have no reference to a specific DTD or schema. It will thus be applied to XML Configuration files that have not been taken into account by other entry types listed here.
  •  - This option enables you to define a pattern that matches a schema reference that the required XML Configuration files must contain.
  •  - Choose this option if you simply want to add a specific XML Configuration file. A Windows Browse dialog will be displayed enabling you to choose the file you require.
• Next choose the XML Parsing Method from the drop down list. This also affects what you choose in the XQuery File or Executable Command Line field directly underneath:

• Click OK to save the settings (this will close the Add/Edit Rule dialog box)
• You can use the  button to make an identical copy of a selected matching criteria
• You can use the  button to remove a selected matching criteria
• Finally, you can use the Test button located in the top right of the dialog box to check that the criteria you have entered will function correctly (click to enlarge):

• Choose a directory in which your XML Configuration Files are located, then choose a specific extension in the Type Selection drop down list. Now click Test. The CAST Management Studio will then check which XML files in the chosen directory will be detected using the matching criteria you have already specified. Those that match and will be taken into account are listed with a green tick.
• You can use the right click shortcut menu to manipulate the files. In addition you can click each column heading to sort the list of files - this can be useful for quickly viewing those that match and those that do not.
• When you have added all the required matching criteria, click Close. This will return you to the main Environment Profiles Manager.

To apply the settings, make sure you click the Apply button. If you want to clear the entire window and revert to the default settings, click the Restore button.