Fix API documentation
diff --git a/ui/org.eclipse.pde.core/src/org/eclipse/pde/core/target/ITargetLocation.java b/ui/org.eclipse.pde.core/src/org/eclipse/pde/core/target/ITargetLocation.java
index 7ab4053..a0ae5c9 100644
--- a/ui/org.eclipse.pde.core/src/org/eclipse/pde/core/target/ITargetLocation.java
+++ b/ui/org.eclipse.pde.core/src/org/eclipse/pde/core/target/ITargetLocation.java
@@ -21,12 +21,24 @@
* to be persisted correctly, clients must provide a factory through the
* <code>org.eclipse.pde.core.targetLocations</code> extension point.
* </p><p>
- * To display an implementation in the PDE UI, clients must supply an adapter factory
- * that adapts their ITargetLocation implementation to the following:
+ * To display an implementation in the PDE UI, clients may do the following:
* </p><p>
- * <code>IWizardNode</code>: Provides a IWizardNode object to supply a wizard for creating new locations of this type
+ * - Implement <code>ITargetLocationWizard</code> and contribute to the <code>org.eclipse.pde.ui.targetLocationProvisioners</code>
+ * extension point.
* </p><p>
- * <code>ILabelProvider</code>: Provides label text and image for the location implementation in the UI
+ * - Have their target location adapt to <code>org.eclipse.jface.viewers.ILabelProvider</code>
+ * to provide text and icon labels in the target definition wizard and editor.
+ * </p><p>
+ * - Have their target location adapt to <code>org.eclipse.jface.viewers.ITreeContentProvider</code>
+ * to provide children items in the target definition wizard and editor. The children must adapt to
+ * <code>ILabelProvider</code> to get text and icon labels in the tree.
+ * </p><p>
+ * - Have their target location adapt to <code>org.eclipse.pde.ui.target.ITargetLocationEditor</code>
+ * to open an edit wizard when the edit button is pressed on the target definition wizard and editor.
+ * </p><p>
+ * - Have their target location adapt to <code>org.eclipse.pde.ui.target.ITargetLocationUpdater</code>
+ * to run an update job on the location when the update button is pressed on the target definition
+ * wizard and editor.
* </p>
*
* @since 3.8
diff --git a/ui/org.eclipse.pde.ui/plugin.xml b/ui/org.eclipse.pde.ui/plugin.xml
index 053884b..5af374c 100644
--- a/ui/org.eclipse.pde.ui/plugin.xml
+++ b/ui/org.eclipse.pde.ui/plugin.xml
@@ -2191,8 +2191,7 @@
class="org.eclipse.pde.internal.ui.shared.target.InstallableUnitWizard"
icon="icons/obj16/metadata_repo_obj.gif"
id="org.eclipse.pde.ui.InstallableUnitProvisioner"
- name="%targetLocationProvider.IU.name"
- type="org.eclipse.pde.ui.locationProvider1">
+ name="%targetLocationProvider.IU.name">
<description>
%targetLocationProvider.IU.description
</description>
diff --git a/ui/org.eclipse.pde.ui/schema/targetLocationProvisioners.exsd b/ui/org.eclipse.pde.ui/schema/targetLocationProvisioners.exsd
index 04a5ff6..bdd3dfb 100644
--- a/ui/org.eclipse.pde.ui/schema/targetLocationProvisioners.exsd
+++ b/ui/org.eclipse.pde.ui/schema/targetLocationProvisioners.exsd
@@ -1,182 +1,183 @@
-<?xml version='1.0' encoding='UTF-8'?>
-<!-- Schema file written by PDE -->
-<schema targetNamespace="org.eclipse.pde.ui" xmlns="http://www.w3.org/2001/XMLSchema">
-<annotation>
- <appInfo>
- <meta.schema plugin="org.eclipse.pde.ui" id="targetLocationProvisioners" name="Target Location Provisioners"/>
- </appInfo>
- <documentation>
- <p>
-This extension point is used to register new target plug-in location provider. Each plug-in location provider is listed when the user attempts to add plug-ins from the PDE Target Platform's Preference Page. The selected location provider is responsible for providing the target location which contain plug-ins the user wants to add to the Target Platform.
-</p>
- </documentation>
- </annotation>
-
- <element name="extension">
- <annotation>
- <appInfo>
- <meta.element />
- </appInfo>
- </annotation>
- <complexType>
- <sequence>
- <element ref="locationProvider" minOccurs="1" maxOccurs="unbounded"/>
- </sequence>
- <attribute name="point" type="string" use="required">
- <annotation>
- <documentation>
-
- </documentation>
- </annotation>
- </attribute>
- <attribute name="id" type="string">
- <annotation>
- <documentation>
-
- </documentation>
- </annotation>
- </attribute>
- <attribute name="name" type="string">
- <annotation>
- <documentation>
-
- </documentation>
- <appInfo>
- <meta.attribute translatable="true"/>
- </appInfo>
- </annotation>
- </attribute>
- </complexType>
- </element>
-
- <element name="locationProvider">
- <annotation>
- <appInfo>
- <meta.element labelAttribute="name" icon="icon"/>
- </appInfo>
- </annotation>
- <complexType>
- <sequence>
- <element ref="description" minOccurs="0" maxOccurs="1"/>
- </sequence>
- <attribute name="id" type="string" use="required">
- <annotation>
- <documentation>
- a unique identifier of the provisioner
- </documentation>
- </annotation>
- </attribute>
- <attribute name="name" type="string" use="required">
- <annotation>
- <documentation>
- human readable name of the provisioner
- </documentation>
- <appInfo>
- <meta.attribute translatable="true"/>
- </appInfo>
- </annotation>
- </attribute>
- <attribute name="icon" type="string">
- <annotation>
- <documentation>
- a relative path of an icon that will be used to visually
-represent the provisioner.
- </documentation>
- <appInfo>
- <meta.attribute kind="resource"/>
- </appInfo>
- </annotation>
- </attribute>
- <attribute name="class" type="string" use="required">
- <annotation>
- <documentation>
- a class that provides a wizard for the user to add content to the target. The value of this attribute is the fully qualified name of the Java class that implements <code>org.eclipse.pde.ui.target.ITargetLocationWizard</code>.
- </documentation>
- <appInfo>
- <meta.attribute kind="java" basedOn=":org.eclipse.pde.ui.target.ITargetLocationWizard"/>
- </appInfo>
- </annotation>
- </attribute>
- </complexType>
- </element>
-
- <element name="description" type="string">
- <annotation>
- <appInfo>
- <meta.element translatable="true"/>
- </appInfo>
- <documentation>
- human-readable description of the provisioner
- </documentation>
- </annotation>
- </element>
-
- <annotation>
- <appInfo>
- <meta.section type="since"/>
- </appInfo>
- <documentation>
- 3.8
- </documentation>
- </annotation>
-
- <annotation>
- <appInfo>
- <meta.section type="examples"/>
- </appInfo>
- <documentation>
- <p>
-The following is an example of the extension point:
-<pre>
- <extension
- point="org.eclipse.pde.ui.targetLocationProviders">
- <locationProvider
- icon="icons/obj16/metadata_repo_obj.gif"
- id="org.eclipse.pde.ui.InstallableUnit"
- name="%targetLocationProvider.IU.name"
- type="InstallableUnit"
- uifactory="org.eclipse.pde.internal.ui.shared.target.IUFactory">
- <description>
- %targetLocationProvider.IU.description
- </description>
- </locationProvider>
- </extension>
-</pre>
- </documentation>
- </annotation>
-
- <annotation>
- <appInfo>
- <meta.section type="implementation"/>
- </appInfo>
- <documentation>
- <p>
-PDE supplies an update site location provider to add plug-ins from repositories.
-</p>
- </documentation>
- </annotation>
-
- <annotation>
- <appInfo>
- <meta.section type="copyright"/>
- </appInfo>
- <documentation>
- Copyright (c) 2011 IBM Corporation and others.
-<br>
-All rights reserved. This program and the accompanying materials are made
-available under the terms of the Eclipse Public License v1.0 which
-accompanies this distribution, and is available at
-<a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>.
- </documentation>
- </annotation>
-
- <annotation>
- <appInfo>
- <meta.section type="apiInfo"/>
- </appInfo>
- <documentation>
- Each template mut provide an adapter factory to provide labels and contents for the target location. It may optionally implement <code>org.eclipse.pde.ui.ILocationUIFactory</code> interface if it needs to be seeded with the target definition.
- </documentation>
- </annotation>
-
-</schema>
+<?xml version='1.0' encoding='UTF-8'?>
+<!-- Schema file written by PDE -->
+<schema targetNamespace="org.eclipse.pde.ui" xmlns="http://www.w3.org/2001/XMLSchema">
+<annotation>
+ <appInfo>
+ <meta.schema plugin="org.eclipse.pde.ui" id="targetLocationProvisioners" name="Target Location Provisioners"/>
+ </appInfo>
+ <documentation>
+ <p>
+This extension point is used to register a target location provisioner wizard that will create new target locations. Each plug-in provisioner is listed when the user attempts to add plug-ins to a target definition from the Target Platform Preference Page or Target Editor. The selected provisioner is responsible for providing the target location or locations to add to the target definition.
+</p><p>
+Clients can provide their own target location implementations through the <code>org.eclipse.pde.core.targetLocations</code> extension point. This extension point allows custom location implementations to be added by the user. Additional UI interaction is handled using the adapter framework (see documentation on <code>org.eclipse.pde.core.target.ITargetDefinition</code>).
+</p>
+ </documentation>
+ </annotation>
+
+ <element name="extension">
+ <annotation>
+ <appInfo>
+ <meta.element />
+ </appInfo>
+ </annotation>
+ <complexType>
+ <sequence>
+ <element ref="locationProvider" minOccurs="1" maxOccurs="unbounded"/>
+ </sequence>
+ <attribute name="point" type="string" use="required">
+ <annotation>
+ <documentation>
+
+ </documentation>
+ </annotation>
+ </attribute>
+ <attribute name="id" type="string">
+ <annotation>
+ <documentation>
+
+ </documentation>
+ </annotation>
+ </attribute>
+ <attribute name="name" type="string">
+ <annotation>
+ <documentation>
+
+ </documentation>
+ <appInfo>
+ <meta.attribute translatable="true"/>
+ </appInfo>
+ </annotation>
+ </attribute>
+ </complexType>
+ </element>
+
+ <element name="locationProvider">
+ <annotation>
+ <appInfo>
+ <meta.element labelAttribute="name" icon="icon"/>
+ </appInfo>
+ </annotation>
+ <complexType>
+ <sequence>
+ <element ref="description" minOccurs="0" maxOccurs="1"/>
+ </sequence>
+ <attribute name="id" type="string" use="required">
+ <annotation>
+ <documentation>
+ a unique identifier of the provisioner
+ </documentation>
+ </annotation>
+ </attribute>
+ <attribute name="name" type="string" use="required">
+ <annotation>
+ <documentation>
+ human readable name of the provisioner
+ </documentation>
+ <appInfo>
+ <meta.attribute translatable="true"/>
+ </appInfo>
+ </annotation>
+ </attribute>
+ <attribute name="icon" type="string">
+ <annotation>
+ <documentation>
+ a relative path of an icon that will be used to visually
+represent the provisioner.
+ </documentation>
+ <appInfo>
+ <meta.attribute kind="resource"/>
+ </appInfo>
+ </annotation>
+ </attribute>
+ <attribute name="class" type="string" use="required">
+ <annotation>
+ <documentation>
+ a class that provides a wizard for the user to add content to the target. The value of this attribute is the fully qualified name of the Java class that implements <code>org.eclipse.pde.ui.target.ITargetLocationWizard</code>.
+ </documentation>
+ <appInfo>
+ <meta.attribute kind="java" basedOn=":org.eclipse.pde.ui.target.ITargetLocationWizard"/>
+ </appInfo>
+ </annotation>
+ </attribute>
+ </complexType>
+ </element>
+
+ <element name="description" type="string">
+ <annotation>
+ <appInfo>
+ <meta.element translatable="true"/>
+ </appInfo>
+ <documentation>
+ human-readable description of the provisioner
+ </documentation>
+ </annotation>
+ </element>
+
+ <annotation>
+ <appInfo>
+ <meta.section type="since"/>
+ </appInfo>
+ <documentation>
+ 3.7 Juno
+ </documentation>
+ </annotation>
+
+ <annotation>
+ <appInfo>
+ <meta.section type="examples"/>
+ </appInfo>
+ <documentation>
+ <p>
+The following is an example of the extension point:
+<pre>
+ <extension
+ point="org.eclipse.pde.ui.targetLocationProvisioners">
+ <locationProvider
+ class="org.eclipse.example.exampleTargetWizard"
+ icon="icons/obj16/exampleTargetLocation.gif"
+ id="org.eclipse.example.exampleTargetProvisioner"
+ name="%targetLocationProvider.example.name"
+ <description>
+ %targetLocationProvider.example.description
+ </description>
+ </locationProvider>
+ </extension>
+</pre>
+ </documentation>
+ </annotation>
+
+ <annotation>
+ <appInfo>
+ <meta.section type="implementation"/>
+ </appInfo>
+ <documentation>
+ <p>
+PDE supplies an internal location provisioner implementation to add plug-ins from update sites and p2 repositories. See <code>org.eclipse.pde.ui.shared.target.InstallableUnitWizard</code>.
+</p>
+ </documentation>
+ </annotation>
+
+ <annotation>
+ <appInfo>
+ <meta.section type="copyright"/>
+ </appInfo>
+ <documentation>
+ Copyright (c) 2011 IBM Corporation and others.
+<br>
+All rights reserved. This program and the accompanying materials are made
+available under the terms of the Eclipse Public License v1.0 which
+accompanies this distribution, and is available at
+<a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>.
+ </documentation>
+ </annotation>
+
+ <annotation>
+ <appInfo>
+ <meta.section type="apiInfo"/>
+ </appInfo>
+ <documentation>
+ The wizard contributed by this extension point must implement <code>org.eclipse.pde.ui.target.ITargetLocationWizard</code>.
+ </documentation>
+ </annotation>
+
+</schema>
diff --git a/ui/org.eclipse.pde.ui/schema/targetProvisioners.exsd b/ui/org.eclipse.pde.ui/schema/targetProvisioners.exsd
index 110af1f..4300fd7 100644
--- a/ui/org.eclipse.pde.ui/schema/targetProvisioners.exsd
+++ b/ui/org.eclipse.pde.ui/schema/targetProvisioners.exsd
@@ -8,6 +8,8 @@
<documentation>
<p>
This extension point is used to register new target plug-in provisioners. Each plug-in provisioner is listed when the user attempts to add plug-ins from the PDE Target Platform's Preference Page. The selected provisioner is responsible for providing the target location which contain plug-ins the user wants to add to the Target Platform.
+</p><p>
+This extension point is deprecated. Please use the <code>org.eclipse.pde.ui.targetLocationProvisioners</code> extension point instead.
</p>
</documentation>
</annotation>
@@ -125,7 +127,7 @@
<meta.section type="since"/>
</appInfo>
<documentation>
- 3.8
+ 3.3
</documentation>
</annotation>
@@ -153,16 +155,6 @@
</documentation>
</annotation>
- <annotation>
- <appInfo>
- <meta.section type="implementation"/>
- </appInfo>
- <documentation>
- <p>
-PDE supplies an update site provisioner to add plug-ins from repositories.
-</p>
- </documentation>
- </annotation>
<annotation>
<appInfo>
diff --git a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/internal/ui/shared/target/TargetLocationsGroup.java b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/internal/ui/shared/target/TargetLocationsGroup.java
index 8396831..a0966dd 100644
--- a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/internal/ui/shared/target/TargetLocationsGroup.java
+++ b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/internal/ui/shared/target/TargetLocationsGroup.java
@@ -317,7 +317,7 @@
break; //Only open for one selected item
}
} else if (location instanceof AbstractBundleContainer) {
- // TODO Custom code for locations that don't use adapaters yet
+ // TODO Custom code for locations that don't use adapters yet
Shell parent = fTreeViewer.getTree().getShell();
EditBundleContainerWizard wizard = new EditBundleContainerWizard(fTarget, location);
WizardDialog dialog = new WizardDialog(parent, wizard);
@@ -560,6 +560,7 @@
return status.getChildren();
}
} else {
+ // Always check for provider last to avoid hurting performance
ITreeContentProvider provider = (ITreeContentProvider) Platform.getAdapterManager().getAdapter(parentElement, ITreeContentProvider.class);
if (provider != null) {
return provider.getChildren(parentElement);
diff --git a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationEditor.java b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationEditor.java
index ffe8ce3..7c9aaf3 100644
--- a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationEditor.java
+++ b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationEditor.java
@@ -15,19 +15,33 @@
import org.eclipse.pde.core.target.ITargetLocation;
/**
- * Target contents that implement or adapt to this interface can be Target contents such as {@link ITargetLocation} implementations The Target Locations and their children can adapt to this interface to convey if they
- * support removal and updation
+ * Contributed target locations that want to support editing in the target wizard and editor must adapt
+ * their {@link ITargetLocation} to this interface.
*
* @noextend This interface is not intended to be extended by clients.
* @since 3.7
*/
public interface ITargetLocationEditor {
- // TODO No way to restore selection after
- // TODO We always perform a normal resolve after, forcing re-resolve ( no way to know result)
- // TODO No way to consider the current selection
+ /**
+ * Returns whether this target location can be edited by this editor. This method will be
+ * called when a selection is made to determine if the edit button should be enabled.
+ *
+ * @param target the target definition being edited
+ * @param targetLocation the target location to edit
+ * @return whether this editor can edit the target location
+ */
public boolean canEdit(ITargetDefinition target, ITargetLocation targetLocation);
+ /**
+ * Returns a wizard that will be opened to edit the given target location. The wizard
+ * is responsible for modifying the target location and/or target. The target definition
+ * will be resolved if the wizard completes successfully.
+ *
+ * @param target the target definition being edited
+ * @param targetLocation the target location to edit
+ * @return wizard to open for editing the target location
+ */
public IWizard getEditWizard(ITargetDefinition target, ITargetLocation targetLocation);
}
diff --git a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationUpdater.java b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationUpdater.java
index 85342f6..89d9b85 100644
--- a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationUpdater.java
+++ b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationUpdater.java
@@ -16,8 +16,8 @@
import org.eclipse.pde.core.target.ITargetLocation;
/**
- * Target contents that implement or adapt to this interface can be Target contents such as {@link ITargetLocation} implementations The Target Locations and their children can adapt to this interface to convey if they
- * support removal and updation
+ * Contributed target locations that want to support updating in the target wizard and editor must adapt
+ * their {@link ITargetLocation} to this interface.
*
* @noextend This interface is not intended to be extended by clients.
* @since 3.7
@@ -32,8 +32,29 @@
*/
public static final int STATUS_CODE_NO_CHANGE = 101;
+ /**
+ * Returns whether this updater can update the given target location. This method will be called
+ * when a selection is made to determine if the update button should be enabled.
+ *
+ * @param target the target definition being edited
+ * @param targetLocation the target location to update
+ * @return whether this update can update the given target location
+ */
public boolean canUpdate(ITargetDefinition target, ITargetLocation targetLocation);
+ /**
+ * Updates the given target location. If an OK status is returned, the target will be resolved
+ * unless the status has the code {@link #STATUS_CODE_NO_CHANGE}. If a non-OK status is returned
+ * the message will be presented to the user.
+ * <p>
+ * This method may be called from a non-UI thread. A progress monitor is provided.
+ * </p>
+ *
+ * @param target the target definition being edited
+ * @param targetLocation the target location to update
+ * @param monitor progress monitor
+ * @return result of the update, use an OK status with {@link #STATUS_CODE_NO_CHANGE} to indicate everything is up to date
+ */
public IStatus update(ITargetDefinition target, ITargetLocation targetLocation, IProgressMonitor monitor);
}
diff --git a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationWizard.java b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationWizard.java
index 9c4c226..fabf396 100644
--- a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationWizard.java
+++ b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationWizard.java
@@ -15,18 +15,20 @@
import org.eclipse.pde.core.target.ITargetLocation;
/**
- * This interface represents a wizard which will be used to add plug-ins to
- * the Target Platform. Implementors must have a default constructor (zero
+ * This interface represents a wizard which will be used to add target locations
+ * to a target definition. The wizard will be available from the Add... button
+ * on the locations tab in the target wizard or editor. Implementors must contribute
+ * their wizards through the <code>org.eclipse.pde.ui.targetLocationProvisioners</code>
+ * extension point. Implementing classes must have a default constructor (zero
* arguments) for the class to be created from the extension.
*
* @noextend This interface is not intended to be extended by clients.
* @since 3.7
*/
-
public interface ITargetLocationWizard extends IWizard {
/**
- * After this wizard is created, this method will be called, providing this wizard with information
+ * After the wizard is created this method will be called, providing this wizard with information
* from the target definition the new location(s) will be added to. It is not recommended that
* implementors modify the target as UI behaviour is not API (it may change between releases).
*
@@ -35,10 +37,10 @@
public void setTarget(ITargetDefinition target);
/**
- * Returns an array of target locations which contain plug-ins to be added to
- * the Target Platform.
+ * Returns an array of target locations to be added to the target definition. Will be
+ * called after the wizard is closed.
*
- * @return an array that represent the locations that will provide new plug-ins.
+ * @return an array of target locations to add to the target definition
*/
public ITargetLocation[] getLocations();
