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

On this page:

Summary: This section describes the custom Environment Profiles for JEE that can be created where required.

Introduction

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

TypeDescription
Class PathsConfigure the different entries that constitute the class path of a job. This is specific to the Java files in your project. The analyzer uses this information to search for classes that are referenced in application code but not defined in the source code files. External classes are searched either in Java source files or compiled class files, thus the class path can also been seen as a "source path."

Class path entries can be either a path or an archive. When analyzing a path, the analyzer assumes that classes are correctly deployed on disk and that they respect the naming convention where a package maps to a directory and a class maps to a file.

Class Paths can also be administered at Application or Analysis Unit level. Note, however, that class paths defined at Application or Analysis Unit level will be taken into account BEFORE the class paths defined in an Environment Profile. Take for example a class path entry that defines the com.test.MyClass java class; this class path entry is defined both at Application level and in an Environment Profile; during an analysis, the analyzer will search for the java class first in the source code files, then in the Class Paths definedat Application level and then in the Environment Profile. The search will stop when the item is found.

ParametrizationFor defining Method Parametrization
Java AnnotationsFor defining your Java Annotations not already covered by a predefined Environment Profile. See Manage annotations for more detailed information.
XMLFor defining support for framework XML Configuration files, either via XML Query files or via XQuery files.

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:

Annotation Group NameAllows you to define a group of similar annotations. During the analysis, an XML Annotation file listing all the annotations that were found in your Project (as defined in this Environment Profile) will be created for each Annotation Group you have defined. Then the selected parsing method is used to extract the required data from the XML Annotation File and transform the identified annotations into objects that can be saved in the Analysis Service. You can choose to retain the XML Annotation Files when you use the Run analysis only options (activate the Keep Generated CAST Scripts from XML and Annotations).

Note that you can create only one group for all annotations if you wish. You do not have to create multiple groups.

AnnotationsThis field contains all the annotations for your particular group, listed by Java package.
XML Parsing Mode

This field lists the parsing method chosen for the annotations:

  • XML Query file - traditional method (see Manage annotations )
  • XQuery file - method based on XQuery and Zorba processor (see Support for Java Annotations) and intermediate .castscript language
  • Custom - custom method using a parser of your choice

See section below for more information.

XQuery File or Executable Command Line

This field lists one of the following (depending on the choice of XML Parsing Mode):

  • The path to your XML Query file (for XML Query files method)
  • The path to your XQuery file (for XQuery files method)
  • The path to your chosen parser using special macros (see below)

See section below for more information.

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:
XML Parsing ModeXQuery File or Executable Command Line
CAST XML QueryThis is the traditional CAST method for parsing your annotations using an XML Query file. You need to create this file yourself - some guidelines are provided in Manage annotations - and then enter its path in the field or browse to the file.
XQuerySelect an XQuery file that you have written to parse your annotations. You need to enter its path in the field or browse to the file. The Zorba parser will be automatically used - it is supplied by CAST.

The output will be placed in a temporary .castscript file which is then interpreted by the J2EE Analyzer. You can retain a copy of the .castscript file using a debug option when you use the Run analysis only option.

CustomThis option enables you to use a custom parsing method (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 annotations 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 Application Root Path defined at Analysis Unit level)
  • $(CASTCommonDir): will be replaced by %CommonProgramFiles%\CAST\CAST (for example if you store your XQuery files at this location)

Note that these macros are all case-sensitive.

  • 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
XMLThis column displays the XML file matching criteria (selected XML files (at Analysis Unit level) will be those that match one of the criteria (an OR is performed).
XML Parsing Mode

This field lists the parsing method chosen for the annotations:

  • XML Query file - traditional method consiting 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 parser of your choice

See section below for more information.

XQuery File or Executable Command Line

This field lists one of the following (depending on the choice of XML Parsing Mode):

  • The path to your XML Query file (for XML Query files method)
  • The path to your XQuery file (for XQuery files method)
  • The path to your chosen parser using special macros (see below)

See section below for more information.

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:
XML Parsing ModeXQuery File or Executable Command Line
CAST XML QueryThis is the traditional CAST method for parsing your XML Configuration files using an XML Query file. You need to create this file yourself - see XML Configuration Files Handling (J2EE) for more details on how to write such files and how they are used by the Analyzer - and then enter its path in the field or browse to the file.
XQuerySelect an XQuery file that you have written to parse your annotations. You need to enter its path in the field or browse to the file. The Zorba parser will be automatically used - it is supplied by CAST.

The output will be placed in a temporary .castscript file which is then interpreted by the JEE Analyzer. You can retain a copy of the .castscript file using a debug option when you use the Run analysis only option.

CustomThis option enables you to use a custom parsing method (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)\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 JEE Analyzer to create the objects, links and properties
  • $(AppRoot): will be replaced during the analysis with the Application Root Path defined in the technology options
  • $(CASTCommonDir): will be replaced by %CommonProgramFiles%\CAST\CAST (for example if you store your XQuery files at this location)

Note that these macros are all case-sensitive.

IgnoreYou can use the Ignore option to tell the analyzer to ignore ALL matching XML Configuration files you have have specified with the matching rule - in this case, do NOT add anything in the field - instead group together all the matching criteria for XML Configuration Files you want to ignore in one rule and then create another rule for XML Configuration files you want to take into account.
  • 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.

  • No labels