Extending the application server import framework

AppScan® Source allows you to import Java™ applications from Apache Tomcat and WebSphere® Application Server Liberty profile. You can import Java™ applications from other application servers by extending the application server import framework, as explained in this topic.

About this task

The application server import framework includes accompanying API documentation that is not available by PDF. If you are accessing this help topic via Adobe™ PDF, you can only access the API documentation by launching the AppScan® Source for Analysis online help and navigating to Extending product function > Extending the application server import framework > Application server import extension API classes and methods - or by locating that section of help at http://help.hcl-software.com/appscan/Source/10.1.0/index.html.

To extend the application server import framework, complete the steps below. These steps will have you do these things:

Configure an Eclipse integrated development environment
Create a new plug-in in Eclipse
Set the necessary dependencies in the newly-created plug-in
In the plug-in, define an extension for your application server
Test the plug-in
Enable the plug-in for AppScan® Source for Analysis

Procedure

Configure an Eclipse integrated development environment for the dependencies that are necessary for the AppScan® Source application server import framework:
1. In Eclipse, select Window > Preferences from the main menu.
2. In the Preferences dialog box, expand Plug-in Development and then select Target Platform.
3. In the Target Platform preference page, click Add to create a new target definition.
4. In the Target Definition wizard page, select Nothing: Start with an empty target definition and then press Next.
5. In the Target Content wizard page, enter a name for the target in the Name field and then click Add to add your AppScan® Source installation directory (see Installation and user data file locations).
6. Optional: Select Show location content to verify that plug-ins are available.
7. Click Finish.
8. In the Target Platform preference page, select the target platform that you just created and press Apply. Then press OK.
Create a new plug-in in Eclipse:
1. Select File > New Project from the main menu to open the New Project wizard.
2. In the Select a wizard page, select Plug-in Project and then press Next.
3. In the Plug-in Project page, enter a name for the plug-in in the Project name field (this help topic will use com.example.appserverimporter as an example) and then press Next.
4. In the Content page, deselect Generate an activator, a Java class that controls the plug-in's life cycle and then press Finish.
In the plug-in that you just created, set the necessary dependencies:
1. Open META-INF\MANIFEST.MF and then select the Dependencies tab.
2. In the Required Plug-ins section of the editor:
  - Click Add and then add com.ouncelabs.core.appserverimporter and org.eclipse.core.runtime.
  - Select the com.ouncelabs.core.appserverimporter plug-in that was just added and click Properties. In the plug-in properties, remove any entries in the Minimum Version and Maximum Version fields and then click OK.
  - Repeat the above step for the org.eclipse.core.runtime plug-in.
3. Select File > Save from the main menu to save all changes that have been made to the editor.
4. The next step will have you define an extension to your application server. For that step, you will continue working in the META-INF\MANIFEST.MF editor.

Define an importer extension for your application server by following these steps:

Select the Extensions tab and then click Add to add com.ouncelabs.appserver - and then select File > Save from the main menu.

Select the plugin.xml tab. Its contents should look similar to this:

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
  <extension
    point="com.ouncelabs.appserver">
  </extension>
</plugin>

Complete the extension definition by editing this. For example:

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
  <extension
    point="com.ouncelabs.appserver">
    <importer
     class="com.example.appserverimporter.MyAppServerImporter"
     id="com.example.appserverimporter.myappserver"
     name="My App Server">
   </importer>
 </extension>
</plugin>

Select File > Save from the main menu to save the changes that were made to plugin.xml.

Create the importer class (in this example, com.example.appserverimporter.MyAppServerImporter) to define the behavior of the new application server importer. This class must extend BaseAppServerImporterBaseAppServerImporter, the framework's base implementation for the AppServerImporterAppServerImporter interface. In this class:
1. Implement AppServerImporter.importAppServer(String). This is used by the framework to determine which Java™ EE projects to import and where they are located. Typically, only the name and the path of the Java™ EE project is required for each project. If EAR Projects are created, the contained Java™ EE projects will be hidden when selecting projects in the AppScan® Source user interface. In this case, the entire EAR will be imported. Otherwise, all projects are listed to be selected individually.
  Using these methods is highly recommended, where applicable:
  - BaseAppServerImporter.processDropInsFolder(AppServerProfile, File)
  - BaseAppServerImporter.processEARFile(AppServerProfile, File)
2. Implement AppServerImporter.isValidLocation(String). This is used to detect the type of server, given the installation directory.
3. Optional: Override BaseAppServerImporter.getJSPCompilerType(). This method returns the JSP compiler to be used for the AppScan® Source project. If this is not done, the base implementation returns null, and the product default JSP compiler will be used.
Optional: As an advanced option, you can customize the JSP compilation to use a precompiled JSP compiler (JSP compilation will take place before or during the import):
1. Override BaseAppServerImporter.getJSPCompilerType() to return JSPCompilerType.PRECOMPILED.
2. Override BaseAppServerImporter.getJSPCompilerType() to call JMX, Java™ API, external scripts to compile the JSP files - or to simply copy class files to the staging directory of the AppScan® Source project. Use Application.getStagingDirectory(Project)Application.getStagingDirectory(Project) to get the staging directory.
3. Override BaseAppServerImporter.createJSPCompilerSupport() to return a custom extension of JSPCompilerSupportJSPCompilerSupport. This is used to persist the mapping between JSP files and the generated class files - and for validation after JSP compilation.
4. Override BaseAppServerImporter.createClasspathProvider() to return a custom implementation of AppServerClasspathProviderAppServerClasspathProvider. This class is required for compiling any Java™ or JSP file that has dependencies on server libraries. The class must extend BaseAppServerClasspathProviderBaseAppServerClasspathProvider. Note that BaseAppServerClasspathProvider.installDirectory will already be set to the installation directory for the application server when getClasspathEntries() is called.
Test the plug-in by following these steps:
1. Select Run > Run Configurations from the main menu (or Run > Debug if you want to test in debug mode).
2. Create a new Eclipse Application configuration.
  - Go to the Main tab of the new configuration. In the Program to Run section, select Run a product and then set it to run com.ouncelabs.osa.rcp.product.
  - Go to the Arguments tab. In the Working directory section, select Other and then enter your AppScan® Source data directory in the field (see Installation and user data file locations).
  - In the Plug-ins tab, set the Launch with selection to plug-ins selected below only. Expand Workspace and ensure that the plug-in that you created is selected - and then deselect these plug-ins under Target Platform:
    - com.ouncelabs.plugin.base
    - com.ouncelabs.plugin.base
    - com.ouncelabs.plugin.base.nl
    - com.ouncelabs.plugin.base.nl
    - com.ouncelabs.plugin.enhanced
    - com.ouncelabs.plugin.enhanced
    - com.ouncelabs.plugin.enhanced.nl
    - com.ouncelabs.plugin.enhanced.nl
3. Before you click Run in the Run Configurations dialog box, go to your AppScan® Source installation directory and run bin\OunceScanner.exe.
4. Return to the Run Configurations dialog box and click Run to launch AppScan® Source for Analysis and test the plug-in.
Enable the plug-in for AppScan® Source for Analysis by following these steps:
1. Right-click the project and select Export.
2. In the Select page of the Export wizard, expand Plug-in Development, select Deployable plug-ins and fragments, and then click Next.
3. In the Deployable plug-ins and fragments page:
  - Go to the Destination tab and set the Directory by browsing to a temporary directory on your machine.
  - Go to the Options tab and select Package plug-ins as individual JAR archives and Qualifier replacement.
  - Click Finish.
4. Locate the temporary directory that was used as the destination for exporting the plug-in and then open its plugins\ folder. In this folder, locate the .jar file that was created and copy it to <install_dir>\dropins (where <install_dir> is the location of your AppScan® Source installation).
  Note:
  - If the \dropins directory does not exist, you will need to manually create it.
  - Altering the AppScan® Source installation directory may require administrative privileges.
5. Locate <install_dir>\configuration\org.eclipse.equinox.simpleconfigurator\bundles.info. Make a backup copy of this file - and then edit the file and add this to the end of it:
```
<my_plugin>,<my_plugin_version>,
dropins/<my_plugin>_<my_plugin_version>.jar,4,false
```
```
<my_plugin>,<my_plugin_version>,dropins/<my_plugin>_<my_plugin_version>.jar,4,false
```
  Where:
  - <my_plugin> is the name of the plug-in that you created.
  - <my_plugin_version> is the version number of the plug-in that you created.
  Note: At the beginning of this entry, <my_plugin>, <my_plugin_version>, and the dropins/ location are separated by commas (,).
6. Start AppScan® Source for Analysis.
7. Select Help > About AppScan® Source for Analysis from the main menu and then click Installation Details. Select the Plug-ins tab and ensure that your plug-in is listed in it.
8. Close the Installation Details dialog box and begin using your application server import framework.