PDE Usage Scenarios

If you find a problem with the scenario step, open a Bugzilla defect against component PDE/UI. Include the build number (e.g. RC1, RC2 etc.). Always prefix the description with the step number as in:

B7.5: Debugger does not stop at the second point

Setup

• S1.1 Switch to the Plug-in Development perspective in order to get the property sheet positioned properly.
• S1.2 Alternatively, you can use Java perspective but open Properties and Error Log views on top of the Tasks.

Scenario A: Basic plug-in activities in a simple self-hosting mode

A1. Preparation for work

• A1.1 Ensure that external plug-ins are enabled to avoid compilation errors. To do so, go to Window->Preferences, expand 'Plug-in Development' node and select Target Platform page. Press 'Select All' button to enable all external plug-ins.
• A1.2 Enlarge the workbench window to occupy most of the viewable area (you need some space for all the views and editors that will be showing in the PDE perspective).

A2. Creating a new plug-in project.

• A2.1 Bring the 'New' dialog by selecting File->New->Project... from the menu bar. Select 'Plug-in Development' in the Category list and 'Plug-in Project' in the Wizard list. Press 'Next'.
• A2.2 You are now in 'New Project' wizard of PDE. Enter 'com.example.xyz' as the name of the new project. This name will also be used to initialize plug-in ID but does not have to match it. Press 'Next'.
• A2.3 Observe the settings for the plug-in structure. Run-time library name should be 'xyz.jar' and initial source folder should be 'src'. Press 'Next'. Note: these names are just a 'guess'. In real life, you are free to modify them, and/or add more source folders. For the sake of testing, we will keep the provided names.
• A2.4 At this page, a choice has to be made. A blank plug-in project can be created, together with the build.properties file and a blank plugin.xml. Alternatively, if 'Create plug-in using a template wizard' is selected, a list below the button will be enabled and you can choose between various wizards that provide for the initial plug-in content. For this scenario, select 'Default Plug-In Structure' from the list of wizards. Press 'Next'.
• A2.5 You are now in Default Plug-In Content wizard. Its role is to fill in the initial content of the plugin.xml and to create top-level plug-in Java class. Note: by definition, plug-ins are not required to provide top-level Java class. This feature is used for Java class libraries that are made available to other plug-ins. If a plug-in contributes extensions and/or extension points, this class is required.
• A2.6 Keep all the settings as provided by the wizard. In a real life, you would modify them. Press 'Finish'. Wait for the dialog to close and for manifest editor to open. Note: be patient - there is a brief moment when the wizard closes that the cursor turns to normal, but it will soon turn to hourglass again and the editor will open.

A3. Examining plug-in manifest editor pages

• A3.0 Welcome page. This optional page should show up when a project has been created from a template. It can be turned off using the checkbox at the bottom.
• A3.1 Overview page. This page shows 'plug-in at a glance' view, provide quick links for detail pages and allows changes in the basic plug-in properties like name, version etc. Change the name of the plug-in from 'XYZ Plugin' to 'XYZ Sample Plugin' by typing this name in the provided text field. When done, hit 'Enter'. Observe how 'Save' button enables and page title changes to display the new name. Save the page.
• A3.2 Verify that top-level Java class is created by following the link 'Class' in front of the Java class text field. The link should open the class in Java editor.
• A3.3 Runtime page. Press the button 'More...' in the Runtime Libraries section of the Overview page. This should open Runtime page. The list of libraries should contain a library as defined in the project wizard (xyz.jar). Select the library. In the section on the right, export all the classes in the JAR by selecting 'Export the entire library' radio button. In the section below, verify that the list contains 'src' source folder. Save (Ctrl+S or Save from pop-up menu).
• A3.4 Plugin.jars exclusive access test. While the manifest editor is up, switch to the navigator and open build.properties for editing. A similar looking (form-based) editor should open with a title: Properties (in use or read only). This is because build.properties is currently used by the Runtime page of the manifest editor. This lock prevents changes that are not in sync. The lock works both ways. To verify it, close both the manifest editor and build.properties editor. Open build.properties editor first. The title is now Properties. Buttons in the page are enabled - the file can be modified. Open plugin.xml and go to Runtime page. The bottom section heading should be "Library content (in use - read only)". Close both editors.
• A3.5 Dependencies page. Go back to manifest editor and switch to 'Dependencies' using the appropriate bottom tab. Verify that the section on the left contains three plug-in references: 'org.eclipse.core.runtime', 'org.eclipse.core.resources' and 'org.eclipse.ui'.
• A3.6 External manifests. While in 'Dependencies' page, double-click on the 'org.eclipse.ui' plug-in reference or select 'Open' from the pop-up menu. Manifest editor for the Workbench UI should open. This editor is opened on an external file and is therefore read-only. Verify that (nothing that can cause file change should be enabled). When done, close the editor.
• A3.7 Source page - round-trip. Switch to Source page. It should show plugin.xml source with syntax highlighting. Verify that the content is correct (it should contain three import elements, one library element and the correct attributes for plugin element). Change the value of the 'name' attribute from "XYZ Sample Plugin" to "XYZ Plugin". Do not save. Switch to Overview page. Verify that the change has been propagated to the page (name text field should contain the new name and the title should also reflect it). Save now.
• A3.8 Source page - syntax errors. Return to source page. Find the closing tag of the 'runtime' element. Remove '>' character from the closing tag. Save. The task list should show an error about '>' being expected. In addition, the error marker should appear in the vertical annotation bar.
• A3.9 Source page - error mode. Without saving or correcting the error, select 'Overview' page tab. You should see an error dialog warning you that you cannot leave the source page until syntax errors are corrected.
• A3.10 Source page - error on startup. Save the source page with an error and close the editor. Open the editor by double-clicking on the plugin.xml file. The editor will detect problems in the file and will open editor into source page - error mode.
• A3.11 Source page - recovery. Add the '>' back and save. The error should go away and you should be able to go back to other pages.

A4. Adding an action set

• A4.1 Switch to Extensions page. It should be empty. Press the 'Add' button. A wizard should appear. Select 'Generic Wizards' category. Select "Schema-based Extension" wizard on the right. Press "Next'.
• A4.2 From the list of available extension points select "Action Sets". Press "Finish". A new extension should appear in the list. Verify that the property sheet shows the correct extension point Id (org.eclipse.ui.actionSets) when extension is selected.
• A4.3 Select the extension and open the pop-up menu. Select New->actionSet (this is possible because PDE has extension point schema for action sets that allows it to calculate valid children of the selected XML element). A new 'actionSet' element should appear as a child of the extension. Select it (if not already selected).
• A4.4 Move to the property sheet. Select 'id' property and change it to 'com.example.xyz.sampleActionSet'. Select 'label' attribute and change it to "Sample Action Set". Observe how element name in the extension tree changes as well.
• A4.5 Go back to the extension tree. Select action set element, bring up the pop-up menu and select 'New->menu'. Select action set again, then select the new element.
• A4.6 Move to the property sheet. Select 'id' property and change it to 'sampleMenu'. Select 'label' property and change it to 'Sample Menu'.
• A4.7 Select the menu element and bring up the pop-up menu. Select 'New->separator'. Select the new element.
• A4.8 Move to the property sheet. Select 'name' property and change it to 'sampleGroup'.
• A4.9 Save. Select action set element, bring up the pop-up menu and select 'New->action'. Select the newly added element.
• A4.10 Move to the property sheet. Change 'id' property to 'com.example.xyz.sampleAction'. Set 'label' property to '&Sample Action'. Set 'menubarPath' to 'sampleMenu/sampleGroup'.
• A4.11 Select 'class' property and bring up property editor dialog. Note: 'class' attribute is marked as 'Java' in 'actionSet' extension point schema. This allows PDE to treat its attribute value as a fully qualified Java class name and interact with Java plug-in to find its value.
• A4.12 Select "Generate a new Java class" radio button. Set the container by selecting "Browse..." and choosing "src" in container selection dialog. Set the package name to "com.example.xyz" (you can browse for the package name if you want). Set the class name to "SampleAction". Hit "Finish". Verify that a new task has appeared in the task list to remind you to finish implementation of the action class.
• A4.13 Wait for SampleAction.java to open in Java editor after it has been created by the wizard.
• A4.14 While inside Java editor, locate 'run' method and add the following statement:

System.out.println("Hello, PDE world!");

Save and close. Return to the manifest editor. Save.
• A4.15 Switch to the Source page. Verify that the file now contains XML code for new extension point. Return to the Extension page.

A5. Testing the newly added action set

• A5.1 Switch back to the manifest editor and make sure there are no unsaved changes. If there are, save.
• A5.2 Select the 'running man' icon on tool bar: not the icon itself by the drop-down menu on the tool bar button. Select 'Run...' option.
• A5.3 Select 'Run-time Workbench' in the list of launch types. Select 'New' button at the lower-left corner of the dialog.
• A5.4 When the launch configuration tabs appear on the right, rename 'New_Configuration' into 'Standard' or something else that will be easy to distinguish.
• A5.5 Press on the "Run" button at the lower-right corner of the dialog. Wait until another Eclipse workbench instance starts.
• A5.6 Select "Window->Customize Perspective...->Other" from the runtime Eclipse window menu bar. Select the checkbox for "Sample Action Set" (the one provided by our new plug-in).
• A5.7 Verify that there is a new top-level menu "Sample Menu" in the menu bar and that it contains menu item "Sample Action". Select it. Verify that the console view shows "Hello, PDE world!" text (blue). Congratulations, you have successfully created your first Eclipse plug-in in PDE!
• A5.8 Select "Perspective->Customize->Other..." and turn "Sample Action Set" off.
• A5.9 Close the run-time workbench, return to the design time instance and switch back to the "Plug-in Development" perspective page.

A6. Refining the action set

• A6.1 Go the Packages view and select "com.example.xyz" project. Bring up the pop-up menu and select "New->Folder". Type in the folder name "icons" and press OK.
• A6.2 Select the newly created folder. Open the "Import..." wizard from the File menu. Select "File system" import engine. Press "Next".
• A6.3 Press "Browse" to select the source directory for the Import. Browse to the Eclipse installation you are running, then drill down to eclipse/plugins/org.eclipse.ui/icons/full/obj16.
• A6.4 Press "Details" button. First deselect all in the left pane. After that, select "info_tsk.gif" in the right pane. Press "OK". Press "Finish" in the wizard. Verify that "info_tsk.gif" file is now in the "icons" directory.
• A6.5 Open plugin.xml using plug-in manifest editor and switch to the Extensions page. Select 'actionSets', 'actionSet' then 'action' element.
• A6.6 Move to the property sheet. Select 'icon' property and press the button to launch the resource selection dialog. Note: 'icon' attribute has been marked with 'resource' flag in 'actionSet' extension point schema. This is an indication for PDE to treat attribute values as resources in the workspace.
• A6.7 Navigate to the 'icons' folder in the left dialog pane. Select the checkbox for 'info_tsk.gif' file in the right pane. Press OK. Verify that the property value is now 'icons/info_tsk.gif'. Also note that the action element icon has changed in the 'Extensions' section and is now showing the newly defined tool bar icon.
• A6.8 Set the 'toolbarPath' property to 'Normal/Sample'. Set the 'tooltip' property to 'Sample tooltip'. Select the editor to bring focus and save.
• A6.9 Run Eclipse as in A5 (this time around, you may use the 'Standard' shortcut from the 'Run' drop-down menu on the tool bar action). Turn on "Sample Action Set". The tool bar button should appear. Verify that the tool tip shows up and that the text is printed on the console when the button is selected. Close the runtime Eclipse instance.

A7. Debugging action set code

• A7.1 Switch to the 'Overview' page of the plug-in manifest editor. Open XyzPlugin.java by following the hyperlink "Class". Place a breakpoint at the first statement in the constructor (double-click on the annotation bar on the left edge of the editor).
• A7.2 While still in the 'Overview' page, follow the link 'Action Sets' in the 'Extensions' section. When in 'Extensions', expand the extension and select 'action' element of the action set. Go to the property sheet and select 'class' property. Use local tool bar button "Open file in editor" to open SampleAction.java. Place a breakpoint at the 'println' statement of the 'run' method.
• A7.3 Run the debugger by selecting the 'Debug' button on the tool bar (similar to A6.9, you can select the 'Standard' shortcut instead of going through the Launch configuration dialog).
• A7.4 After the runtime Eclipse instance started, activate the action by activating the action set first, and then pressing the tool bar button. This should prompt the debugger to stop at the first breakpoint (plug-in constructor) because this is the first time plug-ins has been used. Note: the debugger will not be brought to the front when it stops - you need to keep an eye on it (do not obscure the design time Eclipse window completely).
• A7.5 Resume the debugger. It should stop at the second breakpoint ('run' method of the action). Resume it again.
• A7.6 Press the 'Sample Action' button again. The debugger should stop at the second breakpoint only, because the plug-in has now been loaded and its constructor will not be called again for the duration of the runtime session.
• A7.7 Close the runtime workbench and switch back to the PDE perspective using the perspective icon on the perspective bar on the left edge of the design Eclipse instance.

A8. Creating a new extension point

• A8.1 Activate the manifest editor and switch to "Extension Points" page. Select the "Add..." button. A wizard should appear.
• A8.2 Type the ID of the new extension point: "parsers". Observe how extension point schema file follows (it does not have to have the same name as the extension point, but it is a good convention). Type the name of the extension point: "Sample Parsers". Hit "Finish".
• A8.3 As a result of the wizard, a new extension point entry will appear and XML Schema editor for the extension point will be opened.
• A8.4 Select the "extension" object in Schema editor and open the pop-up menu. Select "New->Element". Change the name of the newly created element from the temp. value to "parser" using Properties view.
• A8.5 Select the "parser" element and open the pop-up menu. Select "New->Attribute". Change the name of the attribute into "id". Change the "use" property to "required" (observe how the icon for the attribute changes).
• A8.6 While still in the property sheet, select the "Clone" local tool bar button to clone the current attribute. This should create a copy. Modify the name of the copy into "name". Keep the other properties.
• A8.6a Select the element 'parser' and set the value of the 'Label Attribute' property to 'name'. Note: This attribute tells PDE to use the value of the specified attribute when presenting the element in the UI. The value must resolve to one of the currently defined attributes, otherwise the property validation will complain.
• A8.7 Clone the attribute again. This time, change the name of the new attribute into "class". Change the property "kind" into "java". Again, observe the icon. Set the value of "basedOn" property to "com.example.xyz.IParser" (a fictitious interface that this class needs to implement).
• A8.8 Clone the attribute. Set the 'name' to 'mode'. Set the 'use' to 'optional'. Set the 'kind' to 'string'. Clear the 'basedOn' property.
• A8.9 Select the 'restriction' property and bring up the restriction dialog. For restriction type, select 'enumeration'. Enter choices by adding the following names and pressing 'Add' button: "never", "always", "manual". Press "OK". Observe how choices are now showing for the property value.
• A8.10 Select 'use' property and change it to 'default'. Select 'value' property and type in 'always'. Note how Eclipse status line shows error message for values that do not belong to the choices set in the restriction.
• A8.11 Bring the page back into focus and save the editor. Select "id" attribute again. In the text area below, enter the following text and press "Apply" button when done:


a unique name that will be used to reference this parser.

• A8.12 Select "name" attribute. Enter the following text in the description field and press "Apply":


a translatable name that will be used for presenting this parser in the UI.

• A8.13 Select "class" attribute. Enter the following text and press "Apply":


a fully qualified name of the Java class that implements <samp>com.example.xyz.IParser</samp> interface.

Note the HTML tags - this text will be used to compose the reference documentation for this extension point.

• A8.14 Select 'mode' attribute. Enter the following text and save (Ctrl+S):


an optional flag that indicates how often this parser instance will run (default is <samp>always</samp>).

Note that you didn't press 'Apply' - when the text is modified, 'Save' will apply first (transfer text to the model) and then save to the file.

• A8.11 Select "extension" element. In the "Grammar" section, select the "Sequence" object and open the pop-up menu. Select "New->Reference->Parser". This has added "Parser" element as the only valid element that can be a child of this extension.
• A8.12 Modify properties of the Parser reference. For minOccurs, type in "0". For maxOccurs, type in "unbounded". Notice how the status line warns about invalid value until the correct word is entered. Also notice how the label below the Grammar section shows the approximate DTD representation of the grammar (which means that any number of "parser" elements can appear in this extension, including 0). Save.
• A8.13 Switch to the Documentation page. Select "Overview" from the combo box above the text editor. Replace the stub text with the following and press Apply button:


This extension point is used to plug in additional parsers.
 
 

• A8.14 Select "Examples" in the combo box. Enter the following text exactly as follows and press "Apply" button:

The following is an example of the extension point usage:
<p>
<pre>
   <extension point="com.example.xyz.parsers">
      <parser
         id="com.example.xyz.parser1"
         name="Sample Parser 1"
         class="com.example.xyz.SampleParser1">
      </parser>
   </extension>
</pre>
</p>

• A8.15 Select "API Information" in the combo box. Enter the following text and save:

Plug-ins that want to extend this extension point must implement <samp>com.example.xyz.IParser</samp> interface.
 
 
• A8.16 Selection "Supplied Implementation" in the combo box. Enter the following text:


XYZ Plugin provides default implementation of the parser.
 
 

• A8.17 Save the document again. Preview the reference HTML by selecting 'Preview Reference Document' from the pop-up menu.
• A8.18 Select 'com.example.xyz' project in the Navigator. Select File->New->Other... in the menu bar. In the left pane of the wizard, select 'Java'. In the right pane, select 'Java Interface'. Press 'Next'.
• A8.19 Select 'Browse...' to search for a package. Pick 'com.example.xyz'. For interface name choose 'IParser'. Press 'Finish'.
• A8.20 When Java editor opens with the new interface, add the following abstract method:

public void parse(int mode);

Save and close.
• A8.21 Close the Schema editor and switch back to manifest editor. Save. Switch to the Source page. Verify the presence of the extension point declaration.

A9. Using the new extension point

• A9.1 Bring the manifest editor back up. Go to Extensions page.
• A9.2 Press the 'Add...' button. In the wizard left pane, select 'Generic wizards'. In the left pane, select 'Schema-based extensions'. Press Next.
• A9.3 Choose 'com.example.xyz.parsers' from the list (that's the one we have created in A8). Press 'Finish'.
• A9.4 Select the new extension and bring up the pop-up menu. Select 'New->parser'.
• A9.5 Move to the property sheet. Set 'id' to 'com.example.xyz.defaultParser'. Set 'name' to "Default Parser".
• A9.6 Select 'mode' property. Press on the 'value' column to edit it. Notice how the first value to appear is the default value set in A8.10. The combo box should contain three choices. Select 'manual'.
• A9.7 Select 'class' attribute. Press the button to open dialog cell editor. Press 'Browse...' for the container and select "XYZ Plugin" folder. Keep 'com.example.xyz' package. Change the class name to "DefaultParser". Press "Finish".
• A9.8 While the 'class' attribute is still selected, press on the local tool bar button to open the Java file. It should implement com.example.xyz.IParser interface that we specified in A8.7 and created in A8.18.

A10. Unresolved and cyclical plug-in references

• A10.1 While the manifest editor for XYZ Plugin is still opened, bring the New wizard (File->New->Other...). Select Plug-in Project again. Press "Next".
• A10.2 Type in the name of the new project: "com.example.bogus". Press "Next".
• A10.3 Just skip the next page.
• A10.4 Select the 'Default Plugin Content' wizard and press "Next".
• A10.5 Press "Finish". Wait for the wizard to close and for the new manifest editor to open. Switch to "Dependencies" page.
• A10.6 Press the 'Add...' button and select 'XYZ Plugin' from the list of choices. Save the editor.
• A10.7 Switch to XYZ Plugin manifest editor (still up). Go to "Dependencies" page. Press the 'Add...' button and select Bogus Plugin from the list. Notice how the description text in the wizard changes to "WARNING: selected dependencies will create cyclical references.".
• A10.8 Ignore the warning and press 'Finish'. Note how 'Dependency Status' section now has a loop node called 'Loop 1'. Expand it. It should contain plug-ins that are members of the loop (XYZ Plugin and Bogus Plugin). Switch to the "Overview" page. Notice how "Alert" section contains a line about cyclical references. When you move the mouse over the line, it should turn into a hyperlink. Select it - it should bring you back to the "Dependencies page". Break the cycle (remove Bogus Plugin from the list).
• A10.9 Switch to the Source page. Add another element to the list of "import" elements (DO NOT SAVE):

<import plugin="org.eclipse.unknown"/>

Switch to the Dependencies page. The added import will appear with an error icon overlay. You can fix it by either importing the plug-in with the missing Id or removing the dependency. Go back to the Source page and remove the element. Save. Note: Unresolved references can only happen in PDE if plug-ins are removed, since references are typically added through form pages. However, if references are typed in directly into the Source page, it is also possible to introduce them by a typing error.

A11. Tracing Control

• A11.1 Bring up the Launch Configuration dialog by pressing 'Run...' option (drop down menu from the 'running man' tool bar button). Select the 'Standard' configuration we created earlier and switch to the 'Tracing' tab.
• A11.2 Enable tracing and select 'org.eclipse.core.runtime' plug-in. Turn the loader tracing on (loader/debug property to 'true') and for 'loader/debug/filter/class' property "com.example.xyz.*" and hit 'Enter'. Press "Apply". Close.
• A11.3 Turn the 'hidden' file filter off in the Packages (the one for the '.*' match). Select com.example.xyz project. Create a new file ".options".
• A11.4 Add the following lines in the new file:

      com.example.xyz/debug = true
      com.example.xyz/debug/variables=*
      com.example.xyz/debug/flags=false

• A11.5 Save and close. Bring up the Launch Configuration dialog again as in A11.1. Select "Workspace Plug-ins" node. Verify that it now contains "XYZ Plug-in" and that the variables defined in .options are listed in the property sheet.
• A11.6 Change the value of "debug/flags" option to "true". Press 'Apply'. Close.
• A11.7 Bring the dialog again. Verify that the variable value has been saved.
• A11.8 Run the configuration. You should see a lot of 'blue' messages on the console (startup tracing) as well as notification when classes from XYZ Plugin are loaded.

A12. Creating new plug-ins using plug-in templates

This scenario is most likely to be exercised with a fresh workspace (new install). If you spent some time testing PDE before this, exit Eclipse and start by pointing at a new workspace using "-data <workspace>" command line option.

• A12.1 Starting from a new install, go to "Help->Welcome..." menu, bring up the dialog and select PDE welcome page. Scroll down the 'Welcome' page until you reach the link for "plug-in project". Follow the link to bring up the New plug-in wizard.
• A12.2 Choose 'com.example.xyz' for a plug-in id. Press 'Next'.
• A12.2 Keep the default settings. Press 'Next'.
• A12.3 Move selection in the list of wizards. Verify that the rich text description in the right pane follows the selection.
• A12.4 Pick the custom wizard that allows you to choose from the list of templates. Press 'Next'.
• A12.5 Leave all the template checked. Move the selection in the list of templates to verify that individual descriptions show up correctly in the description area below the list. Press Next.
• A12.6 You can keep pressing 'Next' through all the individual template pages or press Finish when allowed by the wizard.
• A12.7 You should be asked if the wizard should enable external plug-ins in order to avoid compile errors. Accept it.
• A12.8 Once the generation is finished, manifest editor should open in the the 'Welcome' page. The page should list all the templates that were used to generate initial content. It should also contain general tips on how to use the plug-in.
• A12.9 Jump to the 'Extensions' page to verify that it contains all the extensions.
• A12.10 Run the plug-in and verify that all the extensions have been generated correctly. Test the presence of the preference page, new view, 'Hello, World' button and menu etc. You can read the 'Welcome' page in the design time instance as a reference as to what to expect.
• A12.11 Close the manifest editor.
• A12.12 Open the editor again. It should still contain the 'Welcome' page (the default page should be the last one that was selected when the editor was closed).
• A12.13 Switch to the 'Welcome' page, scroll to the bottom and check the button that will get rid of the page. Close the editor. Open it again. It should not contain 'Welcome' page any more.

A13. Adding new extensions using extension templates

• A13.1 Create a 'Hello, world' plug-in by following A12 scenario but selecting 'Hello, World' template wizard in step A12.4.
• A13.2 Switch to 'Extensions' page. Select 'Add'.
• A13.3 Select 'Extension Templates' category. From the list on the right, select 'Sample View' template. Press 'Next'.
• A13.4 Keep the default settings or change them at will. Press 'Finish'.
• A13.5 You should see the newly added view extension. Also verify that view class has been created in the chosen package.
• A13.6 Run the plug-in to verify that there is a sample view showing up in addition to the Hello, World menu and button.
• A13.7 Keep adding other templates.

A14. Manifest editor editing support

This is a free-form scenario. The goal is to test clipboard and undo/redo support in manifest editor form pages. Each non-source page in the manifest editor fully supports cut/copy/paste and undo/redo operations. In addition, object property changes through Properties view are also under Undo/Redo control. 

• A14.1 Test clipboard operations by cutting or copying elements from sections and pasting them back.
• A14.2 Copy an element from the section and paste it into the Notepad or another valid Paste operation target that can only handle text. Verify that the result is a valid XML fragment for the selected object. For example, if a 'library' element is selected, it should paste a valid 'library' element XML into Notepad.
• A14.3 Delete elements from lists and bring them back by selecting 'Undo'. Also verify that 'Undo' and 'Redo' actions show the correct custom label (e.g. 'Undo Remove', 'Undo Add') instead of the stock 'Undo/Redo'.
• A14.4 Open two manifest editors for two manifest files in two plug-in projects. Copy compatible objects from one to another using only form pages (do not switch to the Source page). Verify that you can copy an 'extension' element from one Extensions page to another, but you cannot paste that element into the 'Runtime' page, for example.
• A14.5 Select an element in on of the form pages in one editor and paste it in the Source page of another.

Scenario B: Advanced self-hosting

It is recommended to finish scenarios 'A' (at least to the point where you have a plug-in that compiles and runs against external plug-ins). We will then migrate this plug-in to use binary projects.

B1. Setting up the environment for binary self-hosting

• B1.1 Open Preferences->Plug-In Development. Deselect all external plug-ins by selecting button "Deselect All". This will reduce the plug-in set to the workspace only and all the references will have to be resolved there.

B2. Importing binary projects

• B2.1 Select 'File->Import->External Plug-ins and Fragments' wizard. Press 'Next'.
• B2.2 Leave the default values on the first wizard page. Press 'Next'.
• B2.3 Select all the provided plug-ins in the second page. Press 'Finish'. Wait for the wizard to complete the operation (it may take some time).
• B2.4 Verify that you have a long list of projects in the workspace and that they are all marked with a 'binary' overlay icon in the upper-left corner (except any source plug-ins you already have in the workspace).
• B2.5 Create a working set that only contains source projects (in Packages, select the drop-down menu and pick the 'Select working set' option). If you have "XYZ Plug-in" from A-set of scenarios, just choose it. You should see all the binary project going away and XYZ Plug-in should be the only one remaining.

B3. Migrating XYZ Plug-in to binary projects

• B3.1 Select com.example.xyz project and bring up 'Properties->Java Buildpath'. Verify that it contains 4 external JAR entries, each prefixed with ECLIPSE_HOME variable. Close the dialog.
• B3.2 While the project is still selected, bring up the pop-up menu and select 'Update classpath' option. There should be a list of projects with only com.example.xyz selected. Press 'Finish'. This should trigger a build and complete without errors.
• B3.3 Repeat the step B3.1. Verify that the build path now contains 4 project references instead of ECLIPSE_HOME-prefixed JARs. If it does, the migration is complete and the workspace is now in full binary self-hosting mode.

B4. Mixed-mode self-hosting

In this mode, we will import only the binary projects that are in the required subset of the entire external plug-in list. The rest of the plug-ins will be used as external.

• B4.1 If there are any binary projects in the workspace created in the previous scenarios, remove them. This will result in 'Missing required project' errors if B3. scenario has already been executed (the migration is complete).
• B4.2 Select the Plug-in Import wizard again (as in B2.1).
• B4.3 Check 'org.eclipse.resources' and 'org.eclipse.ui' plug-ins, then press 'Add Required Plug-ins' button. You should have 21 plug-in selected in total. Press 'Finish'.
• B4.4 Open Preferences->PDE->Target Platform and press 'Not in Workspace' button. You should have 44 selected plug-ins.
• B4.5 Select 'com.example.xyz' plug-in and update the classpath again. The new classpath should contain only project references for required plug-ins.
• B4.6 Bring up the Launch Configurations dialog. Switch to the Plug-ins and Fragments page. Press on the 'Plug-in Path' and verify that it contains a mix of external and workspace paths. Note: if you imported binary projects using linking (without copying source), the actual plug-in path will still point to the original (external) location. In this case, there will be no different in binary and external paths - they will all come from the same place.

B5. Migrating back to external plug-ins

• B5.1 Clear the working set so that all the projects show up.
• B5.2 Select all the binary projects (skip XYZ Plug-in) and delete them WITH their contents. This should result in four 'missing required Java project' errors.
• B5.3 Go back to Preferences->Plug-in Development->Target Platform' and enable all the external plug-ins (Not In Workspace will give you the same results).
• B5.4 Update the classpath of com.example.xyz project as in B3.2. After the build, the errors should go away.
• B5.5 Repeat step B3.3. The classpath should again contain 4 external JAR references with ECLIPSE_HOME variable.

B6. Adaptive self-hosting and Plug-ins view

In the scenarios above, switching from external to binary projects was not automatic. Each time we changed the way required plug-ins were represented, the classpath didn't follow. We had to explicitly recompute it to make it in sync with the changed environment. PDE has an alternative way of representing required plug-ins using classpath containers. In this mechanism, all the required plug-in entries are replaced with one dynamic classpath container entry. This entry computes 'real' entries in real time - reacting to changes.

• B6.1 Go to 'Preferences->PDE->Java Build Path Control'. Turn the 'Use classpath container...' checkbox on. Apply and close.
• B6.2 Select 'com.example.xyz' project and update its classpath. Observe how all the external JARs are gone and replaced with 'Required plug-in entries'. When you expand it, it should contain the external JARs but without ECLIPSE_HOME variable.
• B6.3 Select 'com.example.xyz' project and bring up the 'Java Build Path' page in Properties. Switch to 'Libraries' tab. Select 'Required plug-in entries' and press 'Edit...' button. Verify that you can see all the entries and that 'Attach Source...' button enables when you select the entry. 
• B6.4 If in PDE perspective, switch to Plug-ins view. If in Java perspective, open it and stack it with the Package Explorer.
• B6.5 Spend some time in the view. Expand external plug-ins, browse the content, explore the pop-up menus etc. Open files into the editors and ensure you cannot modify them (these are external plug-ins).
• B6.6 Select plug-in org.eclipse.ant.core (or any other). Expand it. Observe how 'antsupport.jar' is shown as a plain file. Bring up the pop-up menu and select 'Add to Java Search'. Notice how the icon of the Jar has changed and how you can drill into the Jar and see packages and class files. Select the plug-in again and select 'Remove from Java Search'. The JAR should return to being a simple file.
• B6.7 Select any plug-in and choose 'Open Dependencies' from the pop-up menu. Explore the Dependencies view that will open stacked with the Tasks.
• B6.8 Select 'org.eclipse.core.resources' plug-in and choose 'Import->As Binary Project' from the pop-up menu. Switch to the Project Explorer and expand 'Required plug-in entries'. Notice how 'org.eclipse.core.resources' JAR is missing from the list. Open Java Build Path properties for the project, switch to the Libraries tab and notice how there is a new project entry there.
  
  Known JDT problem: 32569 Classpath container does not show project entries in Package Explorer
  
• B6.9 Remove the 'org.eclipse.core.resource' binary project. Check the classpath of com.example.xyz again. Notice how it switched back to using the external JAR for this plug-in automatically. Note: unlike with the fixed classpath, the location of the required plug-ins (workspace or external) is dynamically tracked and classpath is always in sync. Also note that binary project org.eclipse.core.resources also has dynamic classpath so that we didn't have to import all the binary projects it required.

Scenario  C: Various tasks

C1. Converting Java projects into PDE projects

• C1.1 Create a new Java project named 'com.example.java'. When setting up source location, choose to create a new source folder and name it 'src'.
• C1.2 Launch 'New' wizard using 'File->New->Other...'. Select "Plug-in Development" category, wizard "Convert Java to Plug-in Projects". Press "Next".
• C1.3 The newly created project should be available as a choice. Select it and press Finish.
• Verify that the project now has PDE nature and two PDE builders (by browsing the '.project' file). Also verify that plugin.xml has been created with minimal content).

C2. Plug-in Search

• C2.1 Open the Search dialog and switch to the Plug-in Search tab.
• C2.2 Type in 'org.eclipse.jdt.*' in the entry, search for 'Plug-in' and limit to 'Declarations'. Search. Verify that you got 9 matches (all JDT plug-ins). Double-click on the entries to open individual manifest files.
• C2.3 Bring up the dialog again. Type in '*', search for 'Extension Point' and 'Declarations'. You should get 107 entries (last time I checked :-). Double-click on the entry. It should open into the "Extension Points' page of the owning manifest. Switch to source page. Note how markers are showing the hits. Also test 'Description' action on the pop-up menu of the search result list.
• C2.4 Bring up the dialog again. Type in 'org.eclipse.core.resources.natures', search for 'Extension Point' and 'References'. You should get all the extensions that plug into this extension point.
• C2.5 Keep playing with the search, forming the queries at will.

C3. Plug-in Build and Export

• C3.1 Open 'build.properties' file in com.example.xyz project and verify that 'bin.includes' contains all the files you want to build. By default, it cointains the manifest that all the jars (*.jar). You need to add 'icons/' and any other file or folder you want to end up in the build.
• C3.2 Select plugin.xml in 'com.example.xyz' project. Choose 'Create Ant build file' from the pop-up menu. Verify that the file has been created and that you can run it to get the libraries built. Note: 'Run Ant...' action is owned by the PDE Build team. If you notice a problem, open it against PDE Core component.
• C3.3 Using PDE template wizard, create another plug-in project 'com.example.view' and select 'Plug-in with a view' template. Repeat C3.1 for this plug-in.
• C3.4 Select 'Export...' to open export wizard. From the list of wizards, choose 'Deployable plug-ins and fragments'.
• C3.5 Choose 'com.example.xyz' and 'com.example.view' from the list of plug-ins. Also choose the path for the target zip file. Press 'Finish'.
• C3.6 When finished, verify that the zip file contains the expected content (all the files and the built libraries).
• C3.7 Unzip the zip file into a temp directory. Verify that resources for plug-in 'com.example.xyz' fall under eclipse/plugins/com.example.xyz_1.0.0/ and that resources for plug-in 'com.example.view' fall under eclipse/plugins/com.example.view_1.0.0/.

C4. Dependency Extent and Unused Dependencies

• C4.1 Open 'com.example.xyz' plug-in manifest. Switch to Dependencies page. Select one of the entries in the list and choose 'Compute Dependency Extent' on the pop-up menu. After the search has finished, verify that it contains Java types and extension points.
  C4.2 Press 'Add...' and add any plug-in from the list. After that, select 'Find Unused Dependencies' from the pop-up menu. It
  should detect that the newly added dependency is not used anywhere (no extensions that plug into the plug-in's extension points, no referenced code).

Scenario D: Fragments

D1. Fragment Project Creation

• D1.1 Ensure that you went through setup and preparation for work as described in A1.
• D1.2 Select "File->New->Projects...", "Plug-in Development", then "Fragment Project".
• D1.3 In the fragment name field, type "com.example.german". Press "Next".
• D1.4 Leave the Structure page as-is. Press 'Next". Select the default content wizard. Press Next.
• D1.5 In "Simple Fragment Content" page leave the first three fields as-is. Select "Browse" button to bring the plug-in selection dialog up.
• D1.6 Find tree node "Workspace Plug-ins" and select "XYZ Plug-in". Press "OK". Verify that plug-in ID and version have been set and that the wizard can finish.
• D1.7 Choose the match rule 'Compatible' from the combo box. Press 'Finish'.
• D1.8 Verify that the new project has been created and that fragment.xml has been opened for editing.

D2. Adding Fragment Extension

• D2.1 While in fragment manifest editor, go to "Extensions" page. Press 'New' to bring the Extension wizard up.
• D2.2 Select "Generic Wizards" and "Schema-based extension". Press Next. Select "Actions Sets" from the list of extension points. Press "Finish".
• D2.3 Select new action set. Bring pop-up menu and select "New->actionSet".
• D2.4 Move to the property sheet and change the "label" property to "Deutsche Aktionsmenge".
• D2.5 Move back to the "All Elements" section. bring up the pop-up menu. Select "New->menu".
• D2.6 Change "label" property of the menu to "Beispiel Menu" and "id" property to "beispielMenu".
• D2.7 Select menu element again and select "New->separator" from the pop-up menu. Change its name in properties to "beispielGruppe". Save (from the pop-up menu).
• D2.8 Similar to D2.5, create new "action" element. Set the label property to "Beispiel Aktion". Set the menuPath to "beispielMenu/beispielGruppe".
• D2.9 Select "class" property for editing and bring up the cell editor dialog. Select "Generate a new class" radio button.
• D2.10 Browse for the class container and select "GERMAN Fragment" folder in com.example.german project.
• D2.11 Change the class name to "GermanSampleAction". Press "Finish".
• D2.12 When Java editor with the new class opens, find "run" method and add the following:

System.out.println("Hallo, welt!");

Save and close the Java editor.
• D2.13 Save fragment manifest editor.

D3. Running the Fragment

• D3.1 Run the run-time workbench as before. Wait until run-time Eclipse instance starts up.
• D3.2 Open "Window->Customize Perspective" and select "Other...". It should contain "Deutsche Aktionsmenge" set. Select it.
• D3.3 Verify that "Beispiel Menu" has appeared on the menu bar. Also verify that it contains one menu item with "Beispiel Aktion" label.
• D3.4 Press the item. Verify that the console shows "Hallo, welt!" each time it is selected.

Scenario E: Features

E1. Feature Project Creation

• E1.1 Ensure that you went through Setup and preparation for work as described in A1.
• E1.2 As described in A2, create a new plug-in project 'com.example.xyz'.
• E1.3 Repeat E1.2 using project name 'com.example.bogus'.
• E1.4 Repeat E1.2 using project name 'com.example.another'.
• E1.5 As described in D1, create a new fragment 'com.example.german'.
• E1.6 By now, you should have four PDE plug-in projects in the workspace and four manifest editors opened. Close them all.
• E1.7 Select 'File->New->Project...'. In the left wizard pane, select "Plug-in Development". In the right pane, select "Feature Project". Press Next.
• E1.8 In the project name field, type "com.example.xyz-feature". Press Next.
• E1.9 Enter "XYZ Feature" for the feature name and "Acme Inc." for the provider. Press 'Next'.
• E1.10 The next page should contain a list of all PDE plug-ins and fragments in the workspace. Select them all using checkboxes next to their names. Press 'Next'.
• E1.11 Verify that the project has been created and that the feature manifest file (feature.xml) is opened for editing.

E2. Feature Manifest Editor

• E2.1 Manifest editor should already be opened after E1.11. Ensure that the data shown in the form page is the data entered during E1 and that the correct plug-in and fragment references have been checked.
• E2.2 Switch to the Source page and examine the XML source. Switch to "Content" page.
• E2.4 Select "Discovery URLs" in "Component URLs" section of the Overview page. Bring up pop-up menu and select "New->Discovery URL".
• E2.5 Select the new URL and move to the property sheet. Change "label" to "Main Eclipse Discovery Site". Change URL to "http://update.eclipse.org/testUpdates".
• E2.6 Select "Update URLs". Bring up the pop-up menu and select "New->Update URL".
• E2.7 Select the new URL and move to the property sheet. Change "label" to "Main Eclipse Update Site". Change URL to "http://update.eclipse.org/testUpdates". Return focus to the editor and save. Note: URLs are real, but this feature does not exist there so any search for new version will fail.
• E2.8 Expand Supported Environments section and ensure that each Edit button (...) provides the appropriate list of choices for the associated text field.
• E2.9 Switch to the 'Information' page and enter some dummy content for 'Description', 'License and 'Copyright' topics. For the Description topic, also define the URL to be "http://www.eclipse.org".
• E2.10 Switch to the 'Content' page. Remove all the plug-ins from the 'Required' list and re-compute them by pressing the 'Compute' button. Also verify that you can add these plug-ins manually by selecting the 'Add...' button.

E3. Nested features

• E3.1 Keep feature created in E1 and repeat the scenario, but this time do not include any plug-ins (create an empty feature). Call it 'com.example.product', name 'Sample Product'.
• E3.2 When the editor opens, switch to the 'Advanced' page and press 'Add...' button. Select 'Sample Feature' from the list.
• E3.3 Switch to the source page. Verify that 'includes' element has been created.

E4. Feature Preview

• E4.1 From within 'Sample Product' feature opened into the manifest editor, bring up the pop-up menu and select 'Preview'. Once the Preview view opens, position it somewhere to be able to see it changing (for example, stack it over the Tasks view).
• E4.2 The basic content should match, the hyperlinks for More Info, License and Copyright should work and 'Supported Platforms' should show the choices set in the E2.8.
• E4.3 Switch to the main page of the manifest editor. Copy a gif image into the feature project and reference it by pressing 'Browse' button. Select 'Preview' again. The image should replace the default image in the preview view.

E5. Feature Build

• E5.1 Go through E1 to E3 to ensure you have 'com.example.xyz-feature' and 'com.example.product' feature projects in your workspace.
• E5.2 Select 'Export->Deployable Features' wizard. Select both features in the list. Choose to export update archives and specify the destination directory. Verify that JAR archives for plug-ins have been created and placed under a plugins/ subdirectory of the directory you specified. Verify that feature JAR archives have been created and placed under a features/ subdirectory of the directory you specified.
• E5.3 Repeat E5.2, but choose the 'deployable ZIP *with* source' option. Verify that the zip file you specified is generated. Unzip it in a temp directory. Verify that resources for features are placed under eclipse/features, resources for plugins are placed under eclipse/plugins, with source zip files being packaged alongside the libraries.

Scenario F: Update Sites

This scenario shows how update sites can be built as workspace projects. A prerequisite is to have features created in scenario E.

F1. Creating a site project

• F1.1 Bring up 'New->Plug-in Development'. Select 'Update Site' from the list of wizards. Press Next.
• F1.2 For the name of the project, enter 'sampleUpdateSite'. Press 'Finish'. Decline to switch to the Resource perspective.
• F1.3 Verify that a new project has been created with 'site.xml' file, 'features' and 'plugins' folders and that site manifest editor has been opened.

F2. Working with the site manifest editor

• F2.1 Select the project in the Package Explorer and choose 'New->File'. Enter 'index.html' for the name of the file. If the external editor/browser has opened for the file, close it and open it in the internal text editor. Copy and paste the following:

• F2.2 Enter 'index.html' in the URL entry in the Site Description section.
• F2.3 Press 'Add...' in the Category Definitions and create a new category definition with name 'sample-category', label 'Sample Category' and some random text for the description.
• F2.4 Switch to the 'Build' page. Press 'Add...' in the Features To Build section. Select all the features in the provided list. Once the features appear in the list, check only 'com.example.product' (we want both to be built, but only the product should show up in the site manifest - the other will be downloaded by the inclusion). Notice how the entry appeared in the outline view.
• F2.5 Switch to the Features page and verify that it has one entry (com.example.product). Select it and check the category in the 'Categories' list. Save.
• F2.6 Switch back to the 'Build' page and press 'Build'. After the build, verify that 'plugins' contains two plug-ins and 'features' contains two features. Select the 'Build Log' link and examine the build log.
  
  Known problem: 32574 F2.6: Site builder leaves files behind in the related projects
  Known problem: 32575 F2.6: Update site build log could be more informative
  
  
• F2.7 Switch to the feature manifest file of 'com.example.xyz' feature and make any change (just add a blank and remove it - anything to trigger a change). Go back to the 'Build' page of the site manifest and press 'Build'. Verify that only 'com.example.xyz' is rebuilt. Note: the builder keeps a list of changed projects and rebuilds only those changed since the last build, unlike 'Build All' that always builds all the features.
• F2.8 Open Update Manager using 'Help->Software Updates->Update Manager'. Switch to the 'Updates' view. Starting from My Computer, drill down into the location of the workspace until the site is reached (it should show up as an Update site already). Bookmark that location as "Update Site Preview" and collapse all using local tool bar button.
• F2.9 Click on the site bookmark and follow link 'Site home page' in the Preview. Verify that 'index.html' file is opened into the configured HTML view (on Windows, either embedded or default browser; on other platforms, browser only).
• F2.10 Expand the site bookmark and verify that it has the category 'Sample Category'. Click on it and verify that the description you put is showing in the Preview.
• F2.11 Expand the category. Verify that 'XYZ Product' is shown. Select it. It should have the data we put in the features. Click on the 'Copyright' and 'License' links and check the text.
• F2.12 Expand XYZ Product feature. Verify that XYZ Feature is showing as a child and that it has all the correct content in the Preview view.
• F2.13 Switch back to the working perspective. Open XYZ Product feature and add some more text in the description. Save. Switch to the site manifest editor, 'Build' page and press 'Build' button. Switch to the Update perspective, select the site bookmark and press 'Refresh' on the pop-up menu. Expand and verify that the new description is now showing in the Preview.