# Debugging Extensions

When debugging extensions, your setup needs to take into account the fact that the IDE only becomes aware of your extension at startup. With that in mind, these debugging recommendations describe a process in which WebLogic Workshop builds your extension and copies it to a place where the IDE can find it, then starts a new IDE instance that is aware of the newly built extension. Breakpoints you set in the first IDE instance will be recognized as you work with your extension in the second.

This topic includes:

Setting Up Extension Debugging Properties

Debugging IDE Extensions

Debugging Java Controls

## Setting Up Extension Debugging Properties

When setting up for debugging, begin by ensuring that the properties for the project you're debugging specify the following values on the Debugger pane. If you want to load a separate application when the second IDE instance starts, see the section below.

To Specify IDE Extension Debugger Properties

1. In WebLogic Workshop, in the Application window, right-click the folder for your control project, then click Properties.
2. In the Project Properties dialog, in the left pane, click Debugger.
3. Specify the following values for debugger properties:

Option | Value
Build before debugging | Selected
Pause all threads after stepping | Cleared
Create new process | Selected
Attach to process | Cleared
Main class | workshop.core.Workshop
Parameters | If you don't want the IDE to load a specific application when it starts the second IDE instance, you can leave this empty. To load a specific application, enter here a path to the WORK file of the application to load. Note that this path must be relative to the path specified in the Home directory box.
VM parameters | When debugging with 8.1 GA: -ea -Xmx512m -Xms128m -Dsun.java2d.d3d=false -Dworkshop.home=../workshop When debugging with 8.1 SP2 and later: -ea -Xmx512m -Xms128m -Dsun.java2d.d3d=false -Djava.system.class.loader=workshop.core.AppClassLoader
Home directory | If you don't want the IDE to load a specific application when it starts the second IDE instance, leave this as the WebLogic Workshop home directory, which is automatically set by the installer. To load a specific application, it's a good idea to have something here. The path you give in Parameters to the WORK file of the application to load must be relative to what is given here. Having a path here will make this connection easier to keep track of.
Application classpath | Must include WORKSHOP_HOME/wlw-ide.jar, WORKSHOP_HOME/lib/jdom.jar and WORKSHOP_HOME/lib/wlw-ide-schemas.jar.
Automatically append Library JARs | Selected
Automatically append server classpath | Selected
Smart debugging | Selected

### Specifying an Application to Load for Testing

When you launch a new instance of the IDE for debugging an extension, you can specify that the new instance load a particular application. This can be useful if you've created a test application separate from the one you're creating your extension in. If you don't specify a particular application, WebLogic Workshop will load whatever it would have loaded on startup anyway — typically the application that was open the last time you shut down the IDE.

You specify an app to load through the values you give for the Home directory and Parameters debugging properties.

For example, imagine you want to load the SamplesApp that is installed with WebLogic Workshop. SamplesApp might be located here:

> C:\bea\weblogic81\samples\workshop\SamplesApp.work

You could make your Home directory the directory containing your extension application:

> C:\bea\user_projects\applications\MyApp

In the Parameters box you'd enter the path to the SamplesApp application's WORK file, relative to your Home directory. In Parameters, you'd enter this:

> ../../../weblogic81/samples/workshop/SamplesApp/SamplesApp.work

## Debugging IDE Extensions

When you debug an IDE extension, your build process needs to copy the build output (the extension ZIP file) to the WORKSHOP_HOME/extensions folder. That's where WebLogic Workshop looks for extensions to load on startup. In other words, setting up for debugging IDE extensions includes:

- Creating an Ant build file that copies build output to the correct folder in addition to building your sources.
- Setting up extension debugging properties so that a new instance of the IDE is started.

### Creating an Ant Build File for Use When Debugging

When you build, the resulting extension ZIP file goes into the WORKSHOP_HOME/extensions folder, where it can be found by the IDE on startup. This is a simple matter of creating an Ant build file and adding a zip task to the file generated by WebLogic Workshop.

The following steps assume you don't yet have a build.xml file you're building with.

1. Right-click the project folder, then click Properties.
2. In the Project Properties dialog, on the Build panel, click Export to Ant file, then click Cancel.
3. In the Application window, locate the exported_build.xml file generated for you.
4. Rename exported_build.xml to simply build.xml, then double-click the file to open it in Source View.
5. In the build.xml file, scroll down to the "build" target, the add the following as the last task in the target:

    <zip destfile="${platformhome.local.directory}/workshop/extensions/${output.filename}"
            basedir="${dest.path}"
            includes="**/*.*"
            encoding="UTF8"> <!-- jar filenames are UTF8-encoded -->
            <zipfileset dir="${project.local.directory}"
            excludes="build.xml,**/CVS/**,**/*.java,${output.filename}"
            includes="**/*.*"/>
    </zip>

This zip task zips your extension output and copies it to the WORKSHOP_HOME/extensions folder, where WebLogic Workshop can find it when the IDE starts.

6. Save and close the file.
7. Right-click the project folder, then click Properties.
8. In the Project Properties dialog, on the Build panel, click Use Ant build. By default, the build target should be displayed as "build", and that's as it should be.
9. Click OK.

## Debugging Java Controls

When debugging Java controls, you'll need to specify debugging properties. You'll also need to ensure that wlw-ide.jar is visible to the IDE on the classpath.

When you build the control project, WebLogic Workshop will by default copy the resulting JAR file to the Libraries folder. That's where the IDE looks for controls.

#### Adding wlw-ide.jar to the Classpath

The IDE requires that the JAR be on its view of the classpath (the classpath used by the IDE for resolving dependencies, and so avoiding errors in Source View). This JAR contains the IDE extension API that's needed by controls that use an IDE extension, such as a custom insert wizard. Because a control project doesn't provide a project-specific a way to specify external JARs that are visible to the IDE's code checker, you'll need to add the JAR at the application level.

Note: Once the controls are built and deployed, they can locate wlw-ide.jar from within the Libraries folder where the control JAR ends up. You just need to do this to get them built.

To add wlw-ide.jar to an application's classpath where the IDE can see it:

1. Right-click the application folder (the top folder), then click Properties.
2. On the right, scroll down to the bottom of the panel.
3. Under Server classpath additions, click Add Jar and browse for the following JAR:

   BEA_HOME\weblogic81\workshop\wlw-ide.jar

4. Select the JAR, then click Select Jar.
5. Click OK.

## Related Topics

None.