AppXray: Introduction

This document describes the following:

1. What Is AppXray?

Provided by OEPE, AppXray technology analyzes the JSP pages, Java source files, resource bundles, and Web configuration files of your application and uses this information to provide validation and consistency checking across many layers of the application, as well as source code completion and hyperlink navigation.

You can enable AppXray for your existing Web projects, or use it with your new dynamic Web projects for which it is enabled by default. Once available, AppXray will build its application database that allows it to track artifacts and populate it. If you have created a project using standard Web technologies, or if your project is JSP or JSF-enabled, those artifacts will be detected and added to the database. If you have enabled AppXray on an existing project, then artifacts in that project will be detected and added to the database. AppXray then uses this database for validation. As you work with your application, AppXray will automatically maintain the application database. If this degrades performance, you can selectively disable automatic maintenance and rebuild the application database as required.

Errors detected by AppXray are displayed in the Problems view, whereas dependencies are graphically displayed in AppXaminer.

AppXray collects information about the following:

  • The project's web.xml file

  • Faces configuration

  • JSP pages

  • JSP artifacts

  • JSF configuration artifacts

  • Resource bundles

  • CSS

  • Image files

2. Enabling and Disabling AppXray

You can enable or disable AppXray for a workspace or a project as follows:
  • Right-click your project in the Project Explorer and select Properties from the drop-down menu. This opens the Properties dialog, as Figure 1 shows.

    Figure 1.
    Properties Dialog

  • In the Properties dialog, highlight the AppXray node. On the editor pane on the right, click Configure workspace settings, and then use the expanded Preferences > AppXray dialog that Figure 2 shows to enable settings specific to your project, as well as fine-tune the technologies that you want AppXray to include in dependency discovery and collection, both of which are AppXray features used for finding missing resources, as well as collecting information about them (collection):
    • The role of discovery is to find variables in JSP pages. For example, disabling JSF discovery will cause managed beans to no longer appear in the Data Palette view.
    • Collection deals with all items that are available in the AppXaminer view (such as broken links, missing resources, JSP variables) and provides the navigation between files (for example, from a JSF commandLink tag to the section of the faces-config.xml file that defines the navigation rule.

    Note that you can disable collection and leave discovery enabled for a particular technology, but not vice versa.

    Figure 2.
    Properties Dialog - Expanded AppXray

Note that you cannot modify default project-level settings.

3. Visualizing AppXray Dependencies

With AppXray, you can expect to have a view of all Web project dependencies. By viewing these interrelationships graphically, missing resources and broken links become immediately apparent and application structure diagrams can be created by drilling down through the layers of your application.

To view dependencies for a Web project, do the following:

  • Right-click your Web project in the Project Explorer and select Show AppXray Dependencies from the drop-down menu, as Figure 3 shows. This opens the AppXaminer view.

    Figure 3.
    Displaying AppXray Dependencies

    AppXaminer analyzes page, action, class, and many other dependency types. Initially all dependency types are active but can be easily reduced. AppXaminer displays a graph of dependencies between technology-specific artifacts in the project. You can drill down into additional detail on particular references: each dependency link has a number that indicates how many references the focal node contains to the referenced file, with upstream dependency nodes having an indicator on the source end of the link, and downstream nodes having the indicator on the destination end of the link. By clicking the number, you bring up a detail showing the nature of each reference, as Figure 4 shows.

    Figure 4.
    Reference Detail

    By clicking one of the references you navigate to the corresponding reference location in the referring file. Figure 5 shows an example of how clicking on bean:message key="login.title" from the login.jsp file would opens the appropriate reference in in the source view.

    Figure 5.
    Reference in Source View

    You can also right-click on a resource displayed in the AppXaminer diagram and select one of the following options from the drop-down menu:
    • Open - to open the default editor on the file represented by the resource node.
    • Show AppXray Dependencies - to refocus the view on the selected node. Note that this option is disabled for the focal node.
    • Expand All and Collapse All - to expand or collapse nodes. Note that only one or the other is ever enabled, depending on the corresponding state of the node's expand/collapse button. If the node does not have an expand/collapse button, both options are disabled. Since the focal node potentially has two expand/collapse buttons, the options will affect both.

  • To display the chain of dependencies for the application, in AppXaminer view click the plus signs next to a dependency to drill down into the project and reveal the page structure of the application. Note that the Eclipse Outline view (which you open by selecting Window > Show View > Outline from the top-level menu) is synchronized with AppXaminer. If the AppXaminer diagram becomes too big, you can use the Outline view to scroll around the diagram.

  • You can filter dependencies by clicking the Filter Dependency button located in the upper right-hand corner of AppXaminer to list the types of dependencies that can be tracked. This opens the Filter Dependency dialog that Figure 6 and Figure 7 show. This dialog lets you filter either the project technology-specific artifacts, or artifacts by file extension.

    Figure 6.
    Filter Dependency Dialog - Artifact Types

    Figure 7.
    Filter Dependency Dialog - File Extensions

    You can define your custom filter extensions on the Filter Dependency > File Extensions dialog. By filtering out dependencies, you reduce the number of dependencies displayed in the diagram.
    Note the following:
    • The artifact types available for display and filtering depend on the technologies used in the project.
    • All artifact types are shown by default.
    • All filter settings persist across invocations, for each technology type.
Figure 8 shows AppXaminer's toolbar located in the upper right-hand corner of AppXaminer window. You can use this toolbar to zoom in and out of the view, print the diagram, and save it to an image file.

Figure 8.
AppXaminer Toolbar

4. Related Information