Selecting a Java Program to Query (GUI)

To query a Java program, one has to load this program as a Java project in an Eclipse workspace first. Next, SOUL has to launch Eclipse to query the Java project. This can be done either from the Smalltalk GUI or from the command line using a configuration file. 

The following steps describe the former approach. Afterwards, proceed either to Querying from Smalltalk (if you want to interact with SOUL from within the Smallltalk IDE) or Querying from Eclipse (if you want to interact with SOUL from within the Eclipse IDE) for information on how to launch a SOUL query and inspect its results. 

1. Start JavaConnect by choosing JavaConnect from the Tools menu of the VisualsWorks launcher. This will start a new JVM within VisualWorks.

Starting JavaConnect in VisualWorks.

 

2. If this is the first time you are starting JavaConnect, you will be asked for the directory containing your Eclipse installation. Navigate towards the directory that contains the 'plugins' directory and select 'Open':

Select the Eclipse installation directory.

 

3. Select a VM configuration from the next dialog. This will determine the classpath JavaConnect starts the JVM with. 

  • Choose 'penumbra' if you want to query the source code of a Java program from within Smalltalk. This configuration does not support launching Eclipse headfull. 
  • Choose 'penumbra_soot' if you want to use features of SOUL that require the results of program analyses (e.g., domain-specific unification or example-based specifications). This configuration does not support launching Eclipse headfull. 
  • Choose 'barista' if you want to to launch Eclipse headfull and use features of SOUL that require the results of program analyses. 

When in doubt, choose 'barista'.

Selecting a JVM configuration when starting JavaConnect.
After choosing 'OK', a dialog box will inform you that JavaConnect has been started successfully.

4. Select 'PenumbraConsole' from the Tools menu of the VisualWorks launcher. This will open a dialog with two tabs: 'Eclipse Main' and 'Cava'. In the 'Eclipse Main' tab, click on 'Choose' to locate the Eclipse workspace containing your Java project. 

 

 

 

 

 

 


If you want to launch Eclipse headfull (i.e., with a GUI), do not enable the check box 'Headless Eclipse'. If you want to launch Eclipse headless (i.e., with the GUI hidden), enable the check box 'Headless Eclipse'. Whether or not you are able to toggle the checkbox depends on the configuration you launched the JVM with in step 3. The 'barista' configuration is required to launch Eclipse headfull. 

Click on 'Start Eclipse' to launch Eclipse. Continue to step 5 on this page if you want to query Eclipse from within Smalltalk (valid for headless and headfull Eclipse launches). Continue to our page on the Barista plugin if you want to query Eclipse from within Eclipse (valid for headfull Eclipse launches only). 

5. A headless or headfull instance of Eclipse has now been started. Switch to the 'Cava' tab of the console and select the Eclipse project containing the Java program you want to query:

Select the Eclipse project to be queried.
You are now able to open a query browser from within Smalltalk to launch queries over the selected Java project. This is explained in Opening a query browser. 

6. (Optional) This step is only required if you want to use features of SOUL that require the results of program analyses (e.g., domain-specific unification or example-based specifications). Otherwise, continue to the next step. Click on 'Show classes' and select the 'Main' class of your program in the newly populated bottom pane. Click on 'Start Soot'. Before running the Soot analyses, make sure that the build path of your Eclipse project has been configured correctly. Note that running the Soot analyses may take a while.

Run the Soot program analyses.

 

7. (Optional) Click on 'Reification caches'. This will pre-compute some frequently used information about your program to speed up program queries. Afterwards, you can close this window.