# Workspace Programming

Most plug-ins that provided function in Eclipse will need to use some portion of the Workspace API. This example contains Workspace programming logic to create resources, create resource listeners, and manipulate resource paths. These functions are exposed as view actions and pop-up menu choices for project and other resources in the Navigator view . The `plugin.xml` defines these action extensions and the code is provided in the `com.ibm.lab.soln.resources` package.

## Running the Solution

To run the example, launch the run-time instance of Eclipse (Run > Run As > Run-time Workbench).

This example demonstrates several of the Workspace APIs using view actions and pop-up menu choices that have been contributed to the Navigator view.

1. Select the action Soln: List Project Locations from the Navigator view drop down menu.
   A dialog is shown listing all the projects in the workspace, with their physical location on the file system:
   This demonstration of using the Workspace API to find all projects is implemented in the `ActionProcessResourceTree` class by the `showProjectDetails()` method.
2. Select any resource in the Navigator view and then the Soln: Resource Tools > Soln: List Path Values pop-up menu choice. This will open a dialog listing the different path representations available using the Workspace API:
   This detailed look at path values is implemented in the `ActionProcessResourceTree` class by the `pathPlay()` method.
3. Select the Soln: Add Tracing RCL Navigator view drop-down menu choice to add a resource change listener.
   Once the listener has been started, the detected resource events are shown in the console. These will be sent to the Console view in the Workbench used to start the runtime Workbench if you are testing the example. If you installed the example as part of your existing Eclipse installation, you can show them in the Console by starting Eclipse with the `-debug` command line option. The following is an example of the trace statements when a `bin` directory with content was deleted:

       RCL_Rpt: 1
       RCL_Rpt: 1 -> Event triggered...
       RCL_Rpt: 1 -> Auto build about to run.
       RCL_Rpt: 2
       RCL_Rpt: 2 -> Event triggered...
       RCL_Rpt: 2 -> Auto build complete.
       RCL_Rpt: 3
       RCL_Rpt: 3 -> Event triggered...
       RCL_Rpt: 3 -> Resource has been changed.
       RCL_Rpt: 3 -> Lets visit the delta...
       RCL_Rpt: 3 -> 	DeltaPrinter:  Resource / has changed.
       RCL_Rpt: 3 -> 	DeltaPrinter:  Resource /a.CustomProject has changed.
       RCL_Rpt: 3 -> 	DeltaPrinter:  Resource /a.CustomProject/bin has changed.
       RCL_Rpt: 3 -> 	DeltaPrinter:  --> Content Replaced
       RCL_Rpt: 3 -> 	DeltaPrinter:  Resource /a.CustomProject/bin/a was removed.
       RCL_Rpt: 3 -> 	DeltaPrinter:  Resource /a.CustomProject/bin/a/b was removed.
       RCL_Rpt: 3 -> 	DeltaPrinter:  Resource /a.CustomProject/bin/a/b/Mainline.class was removed.

   Select the Soln: Remove Tracing RCL Navigator view drop-down menu choice to remove the listener and stop the tracing.

   Note: The marker example makes productive use of a resource change listener by using one to create markers in response to file modifications.

   The listener add and remove actions are implemented in the `ActionManageTraceRCLs` class. The listener is implemented by the `ResourceChangeReporter` class.

4. Select a project in the Navigator view and then the Soln: Resource Tools > Soln: Setup Project Structure pop-up menu choice. This will create a set of folders and files in the project, if they do not already exist. One file is created by the code, the other is copied from the plug-in's install directory. A Bookmark marker for the txt file is also created, this marker will be visible in the Bookmarks view.
   The result is shown in a message dialog:
   This demonstrates how you can use the Workspace API to create resources and access files included in your plug-in's install directory.
   If you have the tracing resource change listener running, you will see the event detail listed independently for each workspace API action (folder add, file add, file add, marker add, four marker attributes added, and folder add). Only a portion of the trace output is shown here:

       RCL_Rpt: 4
       RCL_Rpt: 4 -> Event triggered...
       RCL_Rpt: 4 -> Auto build about to run.
       RCL_Rpt: 5
       RCL_Rpt: 5 -> Event triggered...
       RCL_Rpt: 5 -> Auto build complete.
       RCL_Rpt: 6
       RCL_Rpt: 6 -> Event triggered...
       RCL_Rpt: 6 -> Resource has been changed.
       RCL_Rpt: 6 -> Lets visit the delta...
       RCL_Rpt: 6 -> 	DeltaPrinter:  Resource / has changed.
       RCL_Rpt: 6 -> 	DeltaPrinter:  Resource /a.CustomProject has changed.
       RCL_Rpt: 6 -> 	DeltaPrinter:  Resource /a.CustomProject/images was added.
         .
         .
         .
       RCL_Rpt: 18
       RCL_Rpt: 18 -> Event triggered...
       RCL_Rpt: 18 -> Resource has been changed.
       RCL_Rpt: 18 -> Lets visit the delta...
       RCL_Rpt: 18 -> 	DeltaPrinter:  Resource / has changed.
       RCL_Rpt: 18 -> 	DeltaPrinter:  Resource /a.CustomProject has changed.
       RCL_Rpt: 18 -> 	DeltaPrinter:  Resource /a.CustomProject/images has changed.
       RCL_Rpt: 18 -> 	DeltaPrinter:  Resource /a.CustomProject/images/image_list.txt has changed.
       RCL_Rpt: 18 -> 	DeltaPrinter:  --------------------> Marker Change
       RCL_Rpt: 18 -> 	DeltaPrinter:  -------------------->lets test for marker changes:
       RCL_Rpt: 18 -> 	DeltaPrinter:  	 Marker delta kind: 4
       RCL_Rpt: 18 -> 	DeltaPrinter:  	 Marker itself: org.eclipse.core.internal.resources.Marker@3e623a94
       RCL_Rpt: 18 -> 	DeltaPrinter:  	 Marker type: org.eclipse.core.resources.bookmark
       RCL_Rpt: 18 -> 	DeltaPrinter:  	 Marker content: [153]
       RCL_Rpt: 18 -> 	DeltaPrinter:  <--------------------
         .
         .
         .
       RCL_Rpt: 27
       RCL_Rpt: 27 -> Event triggered...
       RCL_Rpt: 27 -> Resource has been changed.
       RCL_Rpt: 27 -> Lets visit the delta...
       RCL_Rpt: 27 -> 	DeltaPrinter:  Resource / has changed.
       RCL_Rpt: 27 -> 	DeltaPrinter:  Resource /a.CustomProject has changed.
       RCL_Rpt: 27 -> 	DeltaPrinter:  Resource /a.CustomProject/readme was added.

5. You can compare this with the approach used by the Soln: Resource Tools > Soln: Setup Project Structure using Runnable pop-up menu choice where only one event is triggered with an `IResourceDelta` that includes all the changes made (Note: the images and readme folders created in the previous step were deleted before running the action again):

       RCL_Rpt: 31
       RCL_Rpt: 31 -> Event triggered...
       RCL_Rpt: 31 -> Auto build about to run.
       RCL_Rpt: 32
       RCL_Rpt: 32 -> Event triggered...
       RCL_Rpt: 32 -> Auto build complete.
       RCL_Rpt: 33
       RCL_Rpt: 33 -> Event triggered...
       RCL_Rpt: 33 -> Resource has been changed.
       RCL_Rpt: 33 -> Lets visit the delta...
       RCL_Rpt: 33 -> 	DeltaPrinter:  Resource / has changed.
       RCL_Rpt: 33 -> 	DeltaPrinter:  Resource /a.CustomProject has changed.
       RCL_Rpt: 33 -> 	DeltaPrinter:  Resource /a.CustomProject/images was added.
       RCL_Rpt: 33 -> 	DeltaPrinter:  Resource /a.CustomProject/images/getstart_b.GIF was added.
       RCL_Rpt: 33 -> 	DeltaPrinter:  Resource /a.CustomProject/images/image_list.txt was added.
       RCL_Rpt: 33 -> 	DeltaPrinter:  --------------------> Marker Change
       RCL_Rpt: 33 -> 	DeltaPrinter:  -------------------->lets test for marker changes:
       RCL_Rpt: 33 -> 	DeltaPrinter:  	 Marker delta kind: 1
       RCL_Rpt: 33 -> 	DeltaPrinter:  	 Marker itself: org.eclipse.core.internal.resources.Marker@3e623a95
       RCL_Rpt: 33 -> 	DeltaPrinter:  	 Marker type: org.eclipse.core.resources.bookmark
       RCL_Rpt: 33 -> 	DeltaPrinter:  	 Marker content: [New image_list.txt added, 153, 154]
       RCL_Rpt: 33 -> 	DeltaPrinter:  <--------------------
       RCL_Rpt: 33 -> 	DeltaPrinter:  Resource /a.CustomProject/readme was added.

   This demonstrates the importance of using a runnable to control visibility to your workspace modification actions. With any number of tools adding resource change listeners, you do not want every minor modification to trigger an unknown amount of event related processing. A Workspace runnable can reduce a series of notifications to a single notification.
   These actions are implemented by the `ActionProcessResourceTree` class using the `run()` and `createFolderFile()` methods.
6. The `EDUResources` plug-in also includes logic that adds a workspace save participant when the plug-in is started (see the `startup()` method). The saved state that can be returned when adding a save participant is processed in the `addMy_SaveP` method using the `ResourceChangeReporter` class. The save participant is implemented by the `WorkspaceSaveParticipant` class.
   If you have visibility to console messages (Console view for runtime Workbench testing or when starting Eclipse with the `-debug` parameter), you will see trace output for the IResourceDelta passed back as part of the saved state and when the save participant logic is triggered. For example, opening up a new project will trigger a workspace save event which is processed by the `WorkspaceSaveParticipant` class.
   The example save participant does not implement any real function (the JDT save participant is a more complete example), but the startup logic does process the resource change events that can be passed to a save participant on a subsequent start. Assuming you have the resources plug-in included in your workspace and are testing the code in a runtime Workbench, you can test this save participant processing logic by performing the following steps:
   1. If not already started, run the Workbench instance that has the resources plug-in active. Open the Preferences dialog and find the Workbench -> Startup page. Deselect the entry for the Soln: Resources Plug-in.
      This will disable the automatic startup of the `EDUResources` plug-in and allow the save participant to start later.
   2. Add the following to a project in the workspace:
      - A folder named abc
      - A folder named qrs
      - A file named abc.txt
      Then remove the folder named qrs.
   3. Trigger activation of the resources plug-in by selecting the Soln: List Project Locations choice from the Navigator view. This will allow plug-in startup logic to add the save participant after resource changes have been made.
   4. The logic used to add the save participant will detect that resource events can be processed and use the ResourceChangeReporter to process these changes. The following will be shown in the console:

          WkSavePart ->:  0 *----------> MyWorkSpaceSaveParticipant created.
          WkSavePart ->: Event: 1
          WkSavePart ->: Event: 1 -> Event triggered...
          WkSavePart ->: Event: 1 -> Auto build complete.
          WkSavePart ->: Event: 1 -> Lets visit the delta...
          WkSavePart ->: Event: 1 -> 	DeltaPrinter:  Resource / has changed.
          WkSavePart ->: Event: 1 -> 	DeltaPrinter:  Resource /a.custom has changed.
          WkSavePart ->: Event: 1 -> 	DeltaPrinter:  Resource /a.custom/abc was added.
          WkSavePart ->: Event: 1 -> 	DeltaPrinter:  Resource /a.custom/abc.txt was added.

      The changes that occurred before the plug-in was started are available to the save participant. Note that the add and then removal of the folder qrs is not reported. The two events cancel each other out.

## Roadmap to the Solution

This example includes both pop-up and view action contributions that demonstrate the use of the Workspace API. The extension definitions for the actions can be found in the plugin.xml. The available actions, with the class that implements the function, are shown below.

Action (view or pop-up) Extension | Implementation
--- | ---
Navigator view: Soln: List Project Locations | Implemented by the `showProjectDetails()` method in the `ActionProcessResourceTree` class.
Navigator view: Soln: Add Tracing RCL | The add and remove actions are implemented in the `ActionManageTraceRCLs` class.
Navigator view: Soln: Remove Tracing RCL
Soln: Resources > Soln: List Path Values | Implemented the `pathPlay()` method in the `ActionProcessResourceTree` class.
Soln: Resources > Soln: Setup Project Structure | The project structure actions are implemented by the `ActionProcessResourceTree` class using the `run()` and `createFolderFile()` methods.
Soln: Resources > Soln: Setup Project Structure using Runnable

This plug-in includes a plug-in class that adds a workspace save participant during startup, a resource change listener added by an action contribution, and a resource delta visitor that is used to report on the content of a resource delta. The plug-in is implemented by the `EDUResourcesPlugin` class. `WorkspaceSaveParticipant` implements the workspace save participant.

Object | Implementation
--- | ---
Plug-in | Implemented by the `EDUResourcesPlugin` class.
Resource Change Listener | Implemented by the `ResourceChangeReporter` class.
Workspace Save Participant | Implemented by the `WorkspaceSaveParticipant` class.
Resource Delta Visitor | Implemented by the `ResourceDeltaPrinter` class. This class is used by both the `ResourceChangeReporter` and the `WorkspaceSaveParticipant`.

© Copyright International Business Machines Corporation, 2003.
All rights reserved.