synchronize JPA selection with updates etc.

13 files changed, 338 insertions, 222 deletions

diff --git a/jpa/plugins/org.eclipse.jpt.jpa.ui/plugin.xml b/jpa/plugins/org.eclipse.jpt.jpa.ui/plugin.xml
index 265977c237..d13e1aa1e8 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.ui/plugin.xml
+++ b/jpa/plugins/org.eclipse.jpt.jpa.ui/plugin.xml
@@ -99,6 +99,13 @@
 			<adapter type="org.eclipse.jpt.jpa.ui.selection.JpaSelectionManager"/>
 		</factory>
 
+		<!-- IWorkbenchPage -> JpaSelectionManager -->
+		<factory
+			adaptableType="org.eclipse.ui.IWorkbenchPage"
+			class="org.eclipse.jpt.jpa.ui.internal.selection.WorkbenchPageAdapterFactory">
+			<adapter type="org.eclipse.jpt.jpa.ui.selection.JpaSelectionManager"/>
+		</factory>
+
 		<!-- ITextEditor -> JpaEditorManager -->
 		<factory
 			adaptableType="org.eclipse.ui.texteditor.ITextEditor"
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.ui/property_files/jpt_ui.properties b/jpa/plugins/org.eclipse.jpt.jpa.ui/property_files/jpt_ui.properties
index d8225b875a..ab6ae15110 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.ui/property_files/jpt_ui.properties
+++ b/jpa/plugins/org.eclipse.jpt.jpa.ui/property_files/jpt_ui.properties
@@ -71,7 +71,7 @@ GenericPlatformUiDialog_notSupportedMessageText=Generate Tables from Entities is
 JpaContent_label=JPA Content
 
 JpaStructureView_structureNotAvailable=A JPA structure is not available.
-JpaStructureView_structureProviderNotAvailable=A JPA structure provider is not available: {0} v. {1}
+JpaStructureView_structureProviderNotAvailable=A JPA structure provider is not available for resource type: {0}
 JpaStructureView_linkWithEditorText=Link with Editor
 JpaStructureView_linkWithEditorDesc=Link with Active Editor
 JpaStructureView_linkWithEditorTooltip=Link with Editor
@@ -202,3 +202,5 @@ SelectJpaProjectWizardPage_title=JPA Project Selection
 SelectJpaProjectWizardPage_msg=Select a JPA project.
 
 SynchronizingClasses_TaskName=Synchronizing classes...
+
+SetJpaSelection_jobName=Setting JPA selection...
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/JptUiMessages.java b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/JptUiMessages.java
index de595118db..de4ca05d99 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/JptUiMessages.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/JptUiMessages.java
@@ -190,6 +190,8 @@ public class JptUiMessages {
 	public static String JavaQueryConversionWizardPage_title;
 	public static String JavaQueryConversionWizardPage_description;
 
+	public static String SetJpaSelection_jobName;
+
 	private JptUiMessages() {
 		throw new UnsupportedOperationException();
 	}
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/commands/PersistentAttributeMapAsHandler.java b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/commands/PersistentAttributeMapAsHandler.java
index 36eabcf594..93a1ef6796 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/commands/PersistentAttributeMapAsHandler.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/commands/PersistentAttributeMapAsHandler.java
@@ -13,14 +13,8 @@ import java.util.Map;
 import org.eclipse.core.commands.AbstractHandler;
 import org.eclipse.core.commands.ExecutionEvent;
 import org.eclipse.core.commands.ExecutionException;
-import org.eclipse.core.runtime.IProgressMonitor;
-import org.eclipse.core.runtime.IStatus;
-import org.eclipse.core.runtime.Status;
-import org.eclipse.core.runtime.jobs.Job;
 import org.eclipse.jface.viewers.IStructuredSelection;
 import org.eclipse.jpt.common.core.internal.utility.PlatformTools;
-import org.eclipse.jpt.common.ui.internal.util.SWTUtil;
-import org.eclipse.jpt.common.utility.internal.RunnableAdapter;
 import org.eclipse.jpt.jpa.core.context.PersistentAttribute;
 import org.eclipse.jpt.jpa.ui.selection.JpaSelectionManager;
 import org.eclipse.ui.ISources;
@@ -116,50 +110,14 @@ public class PersistentAttributeMapAsHandler
 	 */
 	private void setJpaSelection(Object[] items) {
 		if (items.length == 1) {
-			new PostExecutionJob((PersistentAttribute) items[0]).schedule();
+			JpaSelectionManager mgr = this.getJpaSelectionManager();
+			mgr.setSelection(null);
+			mgr.setSelection((PersistentAttribute) items[0]);
 		}
 	}
 
-	/**
-	 * This job will not run until any outstanding updates etc. are complete.
-	 * As a result, the runnable dispatched to the UI thread will not run
-	 * until the previously scheduled UI runnables are complete also (e.g. the
-	 * events triggered by the aforementioned updates etc.).
-	 */
-	/* CU private */ static class PostExecutionJob
-		extends Job
-	{
-		private final Runnable setSelectionRunnable;
-
-		PostExecutionJob(PersistentAttribute attribute) {
-			super("select attribute");
-			this.setSelectionRunnable = new SetSelectionRunnable(attribute);
-			this.setRule(attribute.getJpaProject().getProject());
-		}
-
-		@Override
-		protected IStatus run(IProgressMonitor monitor) {
-			SWTUtil.execute(this.setSelectionRunnable);
-			return Status.OK_STATUS;
-		}
-
-		/* class private */ static class SetSelectionRunnable
-			extends RunnableAdapter
-		{
-			private final PersistentAttribute attribute;
-
-			SetSelectionRunnable(PersistentAttribute attribute) {
-				super();
-				this.attribute = attribute;
-			}
-
-			@Override
-			public void run() {
-				JpaSelectionManager mgr = PlatformTools.getAdapter(PlatformUI.getWorkbench(), JpaSelectionManager.class);
-				mgr.setSelection(null);
-				mgr.setSelection(attribute);
-			}
-		}
+	private JpaSelectionManager getJpaSelectionManager() {
+		return PlatformTools.getAdapter(PlatformUI.getWorkbench(), JpaSelectionManager.class);
 	}
 
 	public void updateElement(UIElement element, @SuppressWarnings("rawtypes") Map parameters) {
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/JpaPageManager.java b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/JpaPageManager.java
index 920910ba33..9735ee9a24 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/JpaPageManager.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/JpaPageManager.java
@@ -12,17 +12,18 @@ package org.eclipse.jpt.jpa.ui.internal.selection;
 import java.util.HashMap;
 import java.util.HashSet;
 import org.eclipse.jpt.common.ui.internal.utility.PartAdapter2;
+import org.eclipse.jpt.common.utility.internal.AbstractTransformer;
 import org.eclipse.jpt.common.utility.internal.StringTools;
 import org.eclipse.jpt.common.utility.internal.Transformer;
-import org.eclipse.jpt.common.utility.internal.AbstractTransformer;
 import org.eclipse.jpt.common.utility.internal.model.value.DoubleModifiablePropertyValueModel;
 import org.eclipse.jpt.common.utility.internal.model.value.DoublePropertyValueModel;
 import org.eclipse.jpt.common.utility.internal.model.value.SimplePropertyValueModel;
 import org.eclipse.jpt.common.utility.internal.model.value.TransformationPropertyValueModel;
-import org.eclipse.jpt.common.utility.model.value.PropertyValueModel;
 import org.eclipse.jpt.common.utility.model.value.ModifiablePropertyValueModel;
+import org.eclipse.jpt.common.utility.model.value.PropertyValueModel;
 import org.eclipse.jpt.jpa.core.JpaFile;
 import org.eclipse.jpt.jpa.core.JpaStructureNode;
+import org.eclipse.jpt.jpa.ui.internal.plugin.JptJpaUiPlugin;
 import org.eclipse.jpt.jpa.ui.selection.JpaEditorManager;
 import org.eclipse.jpt.jpa.ui.selection.JpaSelectionManager;
 import org.eclipse.jpt.jpa.ui.selection.JpaViewManager;
@@ -48,7 +49,7 @@ import org.eclipse.ui.IWorkbenchPartReference;
  * which should notify the appropriate view managers etc.
  */
 class JpaPageManager
-	implements JpaSelectionManager, JpaViewManager.PageManager
+	implements JpaSelectionManager, JpaViewManager.PageManager, SetJpaSelectionJob.Manager
 {
 	/**
 	 * The manager's parent window manager.
@@ -170,10 +171,18 @@ class JpaPageManager
 	// ********** selection **********
 
 	/**
-	 * This should only be called from the
-	 * {@link #windowManager window manager}.
+	 * @see JpaWorkbenchManager#setSelection(JpaStructureNode)
 	 */
 	public void setSelection(JpaStructureNode selection) {
+		new SetJpaSelectionJob(this, selection).schedule();
+	}
+
+	/**
+	 * Set the JPA selection for the page. Any interested editors or views
+	 * will be listening to the {@link #jpaSelectionModel model}.
+	 * @see SetJpaSelectionJob.SetJpaSelectionRunnable#run()
+	 */
+	public void setSelection_(JpaStructureNode selection) {
 		this.jpaSelectionModel.setValue(selection);
 	}
 
@@ -189,7 +198,7 @@ class JpaPageManager
 		if (editorManager == null) {
 			editorManager = this.buildEditorManager(editor);
 			if (editorManager != null) {
-				JpaWorkbenchManager.debug("add editor manager:", editor); //$NON-NLS-1$
+				JptJpaUiPlugin.instance().trace(TRACE_OPTION, "add editor manager: {0}", editor); //$NON-NLS-1$
 				this.editorManagers.put(editor, editorManager);
 			}
 		}
@@ -211,7 +220,7 @@ class JpaPageManager
 	// ********** view managers **********
 
 	public synchronized void addViewManager(JpaViewManager viewManager) {
-		JpaWorkbenchManager.debug("add view manager:", viewManager); //$NON-NLS-1$
+		JptJpaUiPlugin.instance().trace(TRACE_OPTION, "add view manager: {0}", viewManager); //$NON-NLS-1$
 		if (this.disposed) {
 			// This can happen if the page manager's last view manager is removed
 			// after a page manager was returned to a new view manager but before that
@@ -224,7 +233,7 @@ class JpaPageManager
 	}
 
 	public synchronized void removeViewManager(JpaViewManager viewManager) {
-		JpaWorkbenchManager.debug("remove view manager:", viewManager); //$NON-NLS-1$
+		JptJpaUiPlugin.instance().trace(TRACE_OPTION, "remove view manager: {0}", viewManager); //$NON-NLS-1$
 		if ( ! this.viewManagers.remove(viewManager)) {
 			throw new IllegalArgumentException("missing view manager: " + viewManager); //$NON-NLS-1$
 		}
@@ -284,7 +293,7 @@ class JpaPageManager
 	/* CU private */ synchronized void partClosed(IWorkbenchPart part) {
 		JpaEditorManager editorManager = this.editorManagers.remove(part);
 		if (editorManager != null) {
-			JpaWorkbenchManager.debug("removed editor manager:", part); //$NON-NLS-1$
+			JptJpaUiPlugin.instance().trace(TRACE_OPTION, "removed editor manager: {0}", part); //$NON-NLS-1$
 			editorManager.dispose();
 		}
 		this.updateEditorManagerModel();
@@ -293,4 +302,29 @@ class JpaPageManager
 	/* CU private */ void updateEditorManagerModel() {
 		this.editorManagerModel.setValue(this.getEditorManager(this.page.getActiveEditor()));
 	}
+
+
+	// ********** static methods **********
+
+	/**
+	 * Return <em>null</em> if a manager does not exist.
+	 * @see WorkbenchPageAdapterFactory
+	 */
+	static JpaPageManager forPage(IWorkbenchPage page) {
+		JpaWindowManager manager = JpaWindowManager.forWindow(page.getWorkbenchWindow());
+		return (manager == null) ? null : manager.getPageManager(page);
+	}
+
+	/**
+	 * Construct a new manager if a manager does not exist.
+	 * @see ViewPartAdapterFactory
+	 */
+	static JpaPageManager forPage_(IWorkbenchPage page) {
+		return JpaWindowManager.forWindow_(page.getWorkbenchWindow()).getPageManager_(page);
+	}
+
+
+	// ********** tracing **********
+
+	private static final String TRACE_OPTION = JpaSelectionManager.class.getSimpleName();
 }
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/JpaWindowManager.java b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/JpaWindowManager.java
index 813eb87f43..f81d7c1838 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/JpaWindowManager.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/JpaWindowManager.java
@@ -12,8 +12,8 @@ package org.eclipse.jpt.jpa.ui.internal.selection;
 import java.util.Hashtable;
 import org.eclipse.jpt.common.utility.internal.StringTools;
 import org.eclipse.jpt.jpa.core.JpaStructureNode;
+import org.eclipse.jpt.jpa.ui.internal.plugin.JptJpaUiPlugin;
 import org.eclipse.jpt.jpa.ui.selection.JpaSelectionManager;
-import org.eclipse.ui.IViewPart;
 import org.eclipse.ui.IWorkbenchPage;
 import org.eclipse.ui.IWorkbenchWindow;
 
@@ -21,10 +21,10 @@ import org.eclipse.ui.IWorkbenchWindow;
  * Maintain a collection of
  * {@link JpaSelectionManager JPA selection managers}
  * keyed by {@link IWorkbenchPage workbench page}.
- * Forward the selection to the manager for the active page.
+ * Forward the JPA selection to the manager for the active page.
  */
 class JpaWindowManager
-	implements JpaSelectionManager
+	implements JpaSelectionManager, SetJpaSelectionJob.Manager
 {
 	/**
 	 * The manager's parent workbench manager.
@@ -46,52 +46,54 @@ class JpaWindowManager
 
 	JpaWindowManager(JpaWorkbenchManager workbenchManager, IWorkbenchWindow window) {
 		super();
-		if (window == null) {
-			throw new NullPointerException();
-		}
 		this.workbenchManager = workbenchManager;
 		this.window = window;
 	}
 
 
-	// ********** selection **********
+	// ********** JPA selection **********
 
 	/**
-	 * Forward to the manager for the window's active page.
+	 * @see JpaWorkbenchManager#setSelection(JpaStructureNode)
 	 */
 	public void setSelection(JpaStructureNode selection) {
-		this.getPageManager(this.window.getActivePage()).setSelection(selection);
+		new SetJpaSelectionJob(this, selection).schedule();
+	}
+
+	/**
+	 * Forward to the manager for the window's active page.
+	 * @see SetJpaSelectionJob.SetJpaSelectionRunnable#run()
+	 */
+	public void setSelection_(JpaStructureNode selection) {
+		IWorkbenchPage page = this.window.getActivePage();
+		if (page != null) {
+			JpaPageManager manager = this.pageManagers.get(page);
+			if (manager != null) {
+				// use internal method since we are on the UI thread here
+				manager.setSelection_(selection);
+			}
+		}
 	}
 
 
 	// ********** page managers **********
 
 	/**
-	 * Return the JPA selection manager for the specified
-	 * workbench page.
+	 * Return <code>null</code> if a manager does not exist.
+	 * @see #getPageManager_(IWorkbenchPage)
 	 */
-	private JpaSelectionManager getPageManager(IWorkbenchPage page) {
-		return (page == null) ?
-				JpaSelectionManager.Null.instance() :
-				this.getPageManager_(page);
-	}
-
-	private JpaSelectionManager getPageManager_(IWorkbenchPage page) {
-		JpaPageManager manager = this.pageManagers.get(page);
-		return (manager == null) ?
-				JpaSelectionManager.Null.instance() :
-				manager;
+	JpaPageManager getPageManager(IWorkbenchPage page) {
+		return this.pageManagers.get(page);
 	}
 
 	/**
 	 * <strong>NB:</strong> May trigger construction of page manager.
 	 */
-	JpaPageManager getPageManager(IViewPart view) {
-		IWorkbenchPage page = view.getSite().getPage();
+	JpaPageManager getPageManager_(IWorkbenchPage page) {
 		synchronized (this.pageManagers) {
 			JpaPageManager manager = this.pageManagers.get(page);
 			if (manager == null) {
-				JpaWorkbenchManager.debug("add page manager:", page); //$NON-NLS-1$
+				JptJpaUiPlugin.instance().trace(TRACE_OPTION, "add page manager: {0}", page); //$NON-NLS-1$
 				manager = new JpaPageManager(this, page);
 				this.pageManagers.put(page, manager);
 			}
@@ -104,7 +106,7 @@ class JpaWindowManager
 	 */
 	void removePageManager(IWorkbenchPage page) {
 		synchronized (this.pageManagers) {
-			JpaWorkbenchManager.debug("remove page manager:", page); //$NON-NLS-1$
+			JptJpaUiPlugin.instance().trace(TRACE_OPTION, "remove page manager: {0}", page); //$NON-NLS-1$
 			this.pageManagers.remove(page);
 			if (this.pageManagers.isEmpty()) {
 				this.dispose();
@@ -123,4 +125,28 @@ class JpaWindowManager
 	public String toString() {
 		return StringTools.buildToStringFor(this, this.window);
 	}
+
+
+	// ********** static methods **********
+
+	/**
+	 * Return <em>null</em> if a manager does not exist.
+	 * @see WorkbenchWindowAdapterFactory
+	 */
+	static JpaWindowManager forWindow(IWorkbenchWindow window) {
+		JpaWorkbenchManager manager = JpaWorkbenchManager.forWorkbench(window.getWorkbench());
+		return (manager == null) ? null : manager.getWindowManager(window);
+	}
+
+	/**
+	 * <strong>NB:</strong> May trigger construction of window manager.
+	 */
+	static JpaWindowManager forWindow_(IWorkbenchWindow window) {
+		return JpaWorkbenchManager.forWorkbench_(window.getWorkbench()).getWindowManager_(window);
+	}
+
+
+	// ********** tracing **********
+
+	private static final String TRACE_OPTION = JpaSelectionManager.class.getSimpleName();
 }
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/JpaWorkbenchManager.java b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/JpaWorkbenchManager.java
index 804ccadb6e..f7c28f16aa 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/JpaWorkbenchManager.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/JpaWorkbenchManager.java
@@ -9,15 +9,11 @@
  ******************************************************************************/
 package org.eclipse.jpt.jpa.ui.internal.selection;
 
-import java.text.DateFormat;
-import java.text.SimpleDateFormat;
-import java.util.Date;
 import java.util.Hashtable;
 import org.eclipse.jpt.common.utility.internal.StringTools;
 import org.eclipse.jpt.jpa.core.JpaStructureNode;
+import org.eclipse.jpt.jpa.ui.internal.plugin.JptJpaUiPlugin;
 import org.eclipse.jpt.jpa.ui.selection.JpaSelectionManager;
-import org.eclipse.jpt.jpa.ui.selection.JpaViewManager;
-import org.eclipse.ui.IViewPart;
 import org.eclipse.ui.IWorkbench;
 import org.eclipse.ui.IWorkbenchWindow;
 
@@ -25,12 +21,12 @@ import org.eclipse.ui.IWorkbenchWindow;
  * Maintain a collection of
  * {@link JpaSelectionManager JPA selection managers}
  * keyed by {@link IWorkbenchWindow workbench window}.
- * Forward the selection to the manager for the active window.
+ * Forward any JPA selection to the manager for the active window.
  * 
- * @see WorkbenchWindowAdapterFactory
+ * @see WorkbenchAdapterFactory
  */
 class JpaWorkbenchManager
-	implements JpaSelectionManager
+	implements JpaSelectionManager, SetJpaSelectionJob.Manager
 {
 	/**
 	 * The manager's workbench.
@@ -45,8 +41,7 @@ class JpaWorkbenchManager
 
 
 	/**
-	 * @see #forWorkbench(IWorkbench)
-	 * @see #getPageManager(IViewPart)
+	 * @see #forWorkbench_(IWorkbench)
 	 */
 	private JpaWorkbenchManager(IWorkbench workbench) {
 		super();
@@ -54,55 +49,55 @@ class JpaWorkbenchManager
 	}
 
 
-	// ********** selection **********
+	// ********** JPA selection **********
 
 	/**
-	 * Forward to the manager for the workbench's active window.
+	 * Dispatch to a job so the JPA selection is set after any outstanding
+	 * updates etc; since setting the JPA selection will trigger UI changes.
+	 * @see SetJpaSelectionJob
 	 */
 	public void setSelection(JpaStructureNode selection) {
-		this.getWindowManager(this.workbench.getActiveWorkbenchWindow()).setSelection(selection);
+		new SetJpaSelectionJob(this, selection).schedule();
 	}
 
-
-	// ********** window managers **********
-
 	/**
-	 * Return the JPA selection manager for the specified
-	 * workbench window. Return a "null" manager if the specified window
-	 * is <code>null</code> or contains no JPA views.
-	 * 
-	 * @see #getPageManager_(IViewPart)
+	 * Forward to the manager for the workbench's active window.
+	 * <br>
+	 * <strong>NB:</strong> {@link IWorkbench#getActiveWorkbenchWindow()}
+	 * (and, thus, this method) must
+	 * be called from the UI thread or it will return <code>null</code>.
+	 * @see SetJpaSelectionJob.SetJpaSelectionRunnable#run()
 	 */
-	private JpaSelectionManager getWindowManager(IWorkbenchWindow window) {
-		return (window == null) ?
-				JpaSelectionManager.Null.instance() :
-				this.getWindowManager_(window);
+	public void setSelection_(JpaStructureNode selection) {
+		IWorkbenchWindow window = this.workbench.getActiveWorkbenchWindow();
+		if (window != null) {
+			JpaWindowManager manager = this.windowManagers.get(window);
+			if (manager != null) {
+				// use internal method since we are on the UI thread here
+				manager.setSelection_(selection);
+			}
+		}
 	}
 
-	private JpaSelectionManager getWindowManager_(IWorkbenchWindow window) {
-		JpaWindowManager manager = this.windowManagers.get(window);
-		return (manager != null) ? manager : JpaSelectionManager.Null.instance();
-	}
+
+	// ********** window managers **********
 
 	/**
-	 * Return the page manager for the specified view.
-	 * Construct a new manager for the view's window and page if necessary.
-	 * 
-	 * @see #getWindowManager(IWorkbenchWindow)
+	 * Return <code>null</code> if a manager does not exist.
+	 * @see #getWindowManager_(IWorkbenchWindow)
 	 */
-	private JpaViewManager.PageManager getPageManager_(IViewPart view) {
-		return this.getWindowManager(view).getPageManager(view);
+	JpaWindowManager getWindowManager(IWorkbenchWindow window) {
+		return this.windowManagers.get(window);
 	}
 
 	/**
 	 * <strong>NB:</strong> May trigger construction of window manager.
 	 */
-	private JpaWindowManager getWindowManager(IViewPart view) {
-		IWorkbenchWindow window = view.getSite().getWorkbenchWindow();
+	JpaWindowManager getWindowManager_(IWorkbenchWindow window) {
 		synchronized (this.windowManagers) {
 			JpaWindowManager manager = this.windowManagers.get(window);
 			if (manager == null) {
-				debug("add window manager:", window); //$NON-NLS-1$
+				JptJpaUiPlugin.instance().trace(TRACE_OPTION, "add window manager: {0}", window); //$NON-NLS-1$
 				manager = new JpaWindowManager(this, window);
 				this.windowManagers.put(window, manager);
 			}
@@ -115,7 +110,7 @@ class JpaWorkbenchManager
 	 */
 	void removeWindowManager(IWorkbenchWindow window) {
 		synchronized (this.windowManagers) {
-			debug("remove window manager:", window); //$NON-NLS-1$
+			JptJpaUiPlugin.instance().trace(TRACE_OPTION, "remove window manager: {0}", window); //$NON-NLS-1$
 			this.windowManagers.remove(window);
 			if (this.windowManagers.isEmpty()) {
 				this.dispose();
@@ -127,7 +122,7 @@ class JpaWorkbenchManager
 	// ********** misc **********
 
 	private void dispose() {
-		debug("remove workbench manager:", this.workbench); //$NON-NLS-1$
+		JptJpaUiPlugin.instance().trace(TRACE_OPTION, "remove workbench manager: {0}", this.workbench); //$NON-NLS-1$
 		WORKBENCH_MANAGERS.remove(this.workbench);
 	}
 
@@ -137,7 +132,7 @@ class JpaWorkbenchManager
 	}
 
 
-	// ********** static cache **********
+	// ********** static methods **********
 
 	/**
 	 * Probably only a single manager in this cache....
@@ -145,57 +140,21 @@ class JpaWorkbenchManager
 	private static final Hashtable<IWorkbench, JpaWorkbenchManager> WORKBENCH_MANAGERS = new Hashtable<IWorkbench, JpaWorkbenchManager>();
 
 	/**
-	 * Return a <em>null</em> manager if a manager does not exist.
+	 * Return <em>null</em> if a manager does not exist.
 	 * @see WorkbenchAdapterFactory
 	 */
-	static JpaSelectionManager forWorkbench(IWorkbench workbench) {
-		return (workbench == null) ?
-			JpaSelectionManager.Null.instance() :
-			forWorkbench_(workbench);
-	}
-
-	private static JpaSelectionManager forWorkbench_(IWorkbench workbench) {
-		JpaWorkbenchManager manager = WORKBENCH_MANAGERS.get(workbench);
-		return (manager != null) ? manager : JpaSelectionManager.Null.instance();
-	}
-
-	/**
-	 * Return a <em>null</em> manager if a manager does not exist.
-	 * @see WorkbenchWindowAdapterFactory
-	 */
-	static JpaSelectionManager forWindow(IWorkbenchWindow window) {
-		return (window == null) ?
-			JpaSelectionManager.Null.instance() :
-			forWindow_(window);
-	}
-
-	private static JpaSelectionManager forWindow_(IWorkbenchWindow window) {
-		JpaWorkbenchManager manager = WORKBENCH_MANAGERS.get(window.getWorkbench());
-		return (manager == null) ?
-				JpaSelectionManager.Null.instance() :
-				manager.getWindowManager_(window);
-	}
-
-	/**
-	 * Construct a new manager if a manager does not exist.
-	 * @see ViewPartAdapterFactory
-	 */
-	static JpaViewManager.PageManager getPageManager(IViewPart view) {
-		if (view == null) {
-			throw new NullPointerException();
-		}
-		return getWorkbenchManager(view).getPageManager_(view);
+	static JpaWorkbenchManager forWorkbench(IWorkbench workbench) {
+		return WORKBENCH_MANAGERS.get(workbench);
 	}
 
 	/**
 	 * <strong>NB:</strong> May trigger construction of workbench manager.
 	 */
-	private static JpaWorkbenchManager getWorkbenchManager(IViewPart view) {
-		IWorkbench workbench = view.getSite().getWorkbenchWindow().getWorkbench();
+	static JpaWorkbenchManager forWorkbench_(IWorkbench workbench) {
 		synchronized (WORKBENCH_MANAGERS) {
 			JpaWorkbenchManager manager = WORKBENCH_MANAGERS.get(workbench);
 			if (manager == null) {
-				debug("add workbench manager:", workbench); //$NON-NLS-1$
+				JptJpaUiPlugin.instance().trace(TRACE_OPTION, "add workbench manager: {0}", workbench); //$NON-NLS-1$
 				manager = new JpaWorkbenchManager(workbench);
 				WORKBENCH_MANAGERS.put(workbench, manager);
 			}
@@ -204,48 +163,7 @@ class JpaWorkbenchManager
 	}
 
 
-	// ********** DEBUG **********
-
-	private static final boolean DEBUG = false;
-
-	static void debug(String message) {
-		debug(message, null);
-	}
-
-	static void debug(String message, Object object) {
-		debug(message, object, null);
-	}
+	// ********** tracing **********
 
-	static void debug(String message, Object object, Object additionalInfo) {
-		if (DEBUG) {
-			// lock System.out so the strings are printed out contiguously
-			synchronized (System.out) {
-				debug_(message, object, additionalInfo);
-			}
-		}
-	}
-
-	private static void debug_(String message, Object object, Object additionalInfo) {
-		System.out.print(buildTimestamp());
-		System.out.print(" "); //$NON-NLS-1$
-		System.out.print(Thread.currentThread().getName());
-		System.out.print(": "); //$NON-NLS-1$
-		System.out.print(message);
-		if (object != null) {
-			System.out.print(" "); //$NON-NLS-1$
-			System.out.print(object);
-			if (additionalInfo != null) {
-				System.out.print(" ("); //$NON-NLS-1$
-				System.out.print(additionalInfo);
-				System.out.print(")"); //$NON-NLS-1$
-			}
-		}
-		System.out.println();
-	}
-
-	private static synchronized String buildTimestamp() {
-		return DATE_FORMAT.format(new Date());
-	}
-	private static final String DATE_FORMAT_PATTERN = "yyyy.MM.dd HH:mm:ss.SSS"; //$NON-NLS-1$
-	private static final DateFormat DATE_FORMAT = new SimpleDateFormat(DATE_FORMAT_PATTERN);
+	private static final String TRACE_OPTION = JpaSelectionManager.class.getSimpleName();
 }
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/SetJpaSelectionJob.java b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/SetJpaSelectionJob.java
new file mode 100644
index 0000000000..1bd64995d3
--- /dev/null
+++ b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/SetJpaSelectionJob.java
@@ -0,0 +1,103 @@
+/*******************************************************************************
+ * Copyright (c) 2012 Oracle. 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 http://www.eclipse.org/legal/epl-v10.html.
+ * 
+ * Contributors:
+ *     Oracle - initial API and implementation
+ ******************************************************************************/
+package org.eclipse.jpt.jpa.ui.internal.selection;
+
+import org.eclipse.core.runtime.IProgressMonitor;
+import org.eclipse.core.runtime.IStatus;
+import org.eclipse.core.runtime.Status;
+import org.eclipse.core.runtime.jobs.Job;
+import org.eclipse.jpt.common.ui.internal.util.SWTUtil;
+import org.eclipse.jpt.common.utility.internal.RunnableAdapter;
+import org.eclipse.jpt.jpa.core.JpaStructureNode;
+import org.eclipse.jpt.jpa.ui.internal.JptUiMessages;
+
+/**
+ * This job will not run until any currently outstanding Dali <em>updates</em> etc.
+ * are complete. As a result, the runnable dispatched (by this job) to the
+ * UI thread will not run until the previously scheduled UI runnables are
+ * complete also (e.g. events triggered by the aforementioned <em>updates</em>
+ * etc.).
+ * <p>
+ * Typically, client code will set the JPA selection when some sort of user
+ * action is complete (e.g. when a menu action is complete). The action will
+ * have modified the model (e.g. setting an attribute's mapping) and, if the
+ * action was performed on a single element, will want to select that modified
+ * element once the action is complete (via the appropriate JPA selection
+ * manager). Unless the action is performing its action sychronously
+ * (via a call to
+ * {@link org.eclipse.jpt.jpa.core.JpaProjectManager#execute(org.eclipse.jpt.common.utility.command.Command)
+ * JpaProjectManager#execute(...)}),
+ * the modification(s) will have triggered a background <em>update</em> that
+ * executes in a job that locks the corresponding project. This <em>update</em> will
+ * modify other parts of the model, resulting in events that will modify the UI.
+ * These UI modifications must be dispatched to the UI thread (via something like
+ * {@link org.eclipse.jpt.common.ui.internal.listeners.SWTPropertyChangeListenerWrapper
+ * SWTPropertyChangeListenerWrapper}).
+ * <p>
+ * As a result, the setting of the JPA selection (which, itself, also modifies
+ * the UI via events) is performed via a job that, like the <em>update</em> job,
+ * locks on the corresponding project. As a result this job will not execute
+ * until any outstanding <em>update</em> jobs are complete. Once this job is
+ * executing, it dispatches the actual setting of the JPA selection to the UI
+ * thread; meaning, again, it will not execute until any outstanding UI-targeted
+ * events triggered by the <em>updates</em> have executed.
+ */
+class SetJpaSelectionJob
+	extends Job
+{
+	private final Runnable setJpaSelectionRunnable;
+
+
+	SetJpaSelectionJob(Manager manager, JpaStructureNode selection) {
+		super(JptUiMessages.SetJpaSelection_jobName);
+		this.setJpaSelectionRunnable = new SetJpaSelectionRunnable(manager, selection);
+		this.setRule(selection.getJpaProject().getProject());
+	}
+
+	@Override
+	protected IStatus run(IProgressMonitor monitor) {
+		SWTUtil.asyncExec(this.setJpaSelectionRunnable);
+		return Status.OK_STATUS;
+	}
+
+	/**
+	 * UI runnable.
+	 * @see SetJpaSelectionJob#run(IProgressMonitor)
+	 */
+	private static class SetJpaSelectionRunnable
+		extends RunnableAdapter
+	{
+		private final Manager jpaSelectionManager;
+		private final JpaStructureNode selection;
+
+		SetJpaSelectionRunnable(Manager manager, JpaStructureNode selection) {
+			super();
+			this.jpaSelectionManager = manager;
+			this.selection = selection;
+		}
+
+		@Override
+		public void run() {
+			this.jpaSelectionManager.setSelection_(this.selection);
+		}
+	}
+
+	/**
+	 * Internal interface used to set the JPA selection while executing on
+	 * the UI thread.
+	 * @see SetJpaSelectionRunnable#run()
+	 */
+	interface Manager {
+		/**
+		 * @see SetJpaSelectionRunnable#run()
+		 */
+		void setSelection_(JpaStructureNode selection);
+	}
+}
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/ViewPartAdapterFactory.java b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/ViewPartAdapterFactory.java
index 4901832937..bd94938d4c 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/ViewPartAdapterFactory.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/ViewPartAdapterFactory.java
@@ -17,7 +17,7 @@ import org.eclipse.ui.IViewPart;
  * Factory to build JPA selection adapters for a {@link IViewPart}:<ul>
  * <li>{@link org.eclipse.jpt.jpa.ui.selection.JpaViewManager.PageManager}
  * </ul>
- * See <code>org.eclipse.jpt.jpa.ui/plugin.xml</code>.
+ * See <code>org.eclipse.jpt.jpa.ui/plugin.xml:org.eclipse.core.runtime.adapters</code>.
  */
 public class ViewPartAdapterFactory
 	implements IAdapterFactory
@@ -43,10 +43,10 @@ public class ViewPartAdapterFactory
 	}
 
 	/**
-	 * This will trigger the creation of the appropriate page manager if it does
-	 * not already exist.
+	 * Trigger the creation of the appropriate page manager if it does
+	 * not already exist (i.e. never return <code>null</code>).
 	 */
 	private JpaViewManager.PageManager getPageManager(IViewPart view) {
-		return JpaWorkbenchManager.getPageManager(view);
+		return JpaPageManager.forPage_(view.getSite().getPage());
 	}
 }
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/WorkbenchAdapterFactory.java b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/WorkbenchAdapterFactory.java
index 66cbca6d5c..d963806239 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/WorkbenchAdapterFactory.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/WorkbenchAdapterFactory.java
@@ -17,7 +17,7 @@ import org.eclipse.ui.IWorkbench;
  * Factory to build JPA selection adapters for a {@link IWorkbench}:<ul>
  * <li>{@link JpaSelectionManager}
  * </ul>
- * See <code>org.eclipse.jpt.jpa.ui/plugin.xml</code>.
+ * See <code>org.eclipse.jpt.jpa.ui/plugin.xml:org.eclipse.core.runtime.adapters</code>.
  * 
  * @see JpaWorkbenchManager
  */
@@ -48,6 +48,7 @@ public class WorkbenchAdapterFactory
 	 * Never return <code>null</code>.
 	 */
 	private JpaSelectionManager getJpaSelectionManager(IWorkbench workbench) {
-		return JpaWorkbenchManager.forWorkbench(workbench);
+		JpaSelectionManager manager = JpaWorkbenchManager.forWorkbench(workbench);
+		return (manager != null) ? manager : JpaSelectionManager.Null.instance();
 	}
 }
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/WorkbenchPageAdapterFactory.java b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/WorkbenchPageAdapterFactory.java
new file mode 100644
index 0000000000..2aad8790b1
--- /dev/null
+++ b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/WorkbenchPageAdapterFactory.java
@@ -0,0 +1,54 @@
+/*******************************************************************************
+ * Copyright (c) 2012 Oracle. 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 http://www.eclipse.org/legal/epl-v10.html.
+ * 
+ * Contributors:
+ *     Oracle - initial API and implementation
+ ******************************************************************************/
+package org.eclipse.jpt.jpa.ui.internal.selection;
+
+import org.eclipse.core.runtime.IAdapterFactory;
+import org.eclipse.jpt.jpa.ui.selection.JpaSelectionManager;
+import org.eclipse.ui.IWorkbenchPage;
+
+/**
+ * Factory to build JPA selection adapters for a {@link IWorkbenchPage}:<ul>
+ * <li>{@link JpaSelectionManager}
+ * </ul>
+ * See <code>org.eclipse.jpt.jpa.ui/plugin.xml:org.eclipse.core.runtime.adapters</code>.
+ * 
+ * @see JpaWorkbenchManager
+ */
+public class WorkbenchPageAdapterFactory
+	implements IAdapterFactory
+{
+	private static final Class<?>[] ADAPTER_LIST = new Class[] { JpaSelectionManager.class };
+
+	public Class<?>[] getAdapterList() {
+		return ADAPTER_LIST;
+	}
+
+	public Object getAdapter(Object adaptableObject, @SuppressWarnings("rawtypes") Class adapterType) {
+		if (adaptableObject instanceof IWorkbenchPage) {
+			return this.getAdapter((IWorkbenchPage) adaptableObject, adapterType);
+		}
+		return null;
+	}
+
+	private Object getAdapter(IWorkbenchPage workbenchPage, Class<?> adapterType) {
+		if (adapterType == JpaSelectionManager.class) {
+			return this.getJpaSelectionManager(workbenchPage);
+		}
+		return null;
+	}
+
+	/**
+	 * Never return <code>null</code>.
+	 */
+	private JpaSelectionManager getJpaSelectionManager(IWorkbenchPage workbenchPage) {
+		JpaSelectionManager manager = JpaPageManager.forPage(workbenchPage);
+		return (manager != null) ? manager : JpaSelectionManager.Null.instance();
+	}
+}
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/WorkbenchWindowAdapterFactory.java b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/WorkbenchWindowAdapterFactory.java
index 9a7f125703..b952e40357 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/WorkbenchWindowAdapterFactory.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/internal/selection/WorkbenchWindowAdapterFactory.java
@@ -17,7 +17,7 @@ import org.eclipse.ui.IWorkbenchWindow;
  * Factory to build JPA selection adapters for a {@link IWorkbenchWindow}:<ul>
  * <li>{@link JpaSelectionManager}
  * </ul>
- * See <code>org.eclipse.jpt.jpa.ui/plugin.xml</code>.
+ * See <code>org.eclipse.jpt.jpa.ui/plugin.xml:org.eclipse.core.runtime.adapters</code>.
  * 
  * @see JpaWorkbenchManager
  */
@@ -48,6 +48,7 @@ public class WorkbenchWindowAdapterFactory
 	 * Never return <code>null</code>.
 	 */
 	private JpaSelectionManager getJpaSelectionManager(IWorkbenchWindow workbenchWindow) {
-		return JpaWorkbenchManager.forWindow(workbenchWindow);
+		JpaSelectionManager manager = JpaWindowManager.forWindow(workbenchWindow);
+		return (manager != null) ? manager : JpaSelectionManager.Null.instance();
 	}
 }
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/selection/JpaSelectionManager.java b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/selection/JpaSelectionManager.java
index 8d1179f87a..f0fe03b51b 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/selection/JpaSelectionManager.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.ui/src/org/eclipse/jpt/jpa/ui/selection/JpaSelectionManager.java
@@ -14,16 +14,16 @@ import org.eclipse.jpt.common.utility.internal.StringTools;
 import org.eclipse.jpt.jpa.core.JpaStructureNode;
 
 /**
- * Each {@link org.eclipse.ui.IWorkbench workbench}
- * and {@link org.eclipse.ui.IWorkbenchWindow workbench window} has a corresponding
+ * Each {@link org.eclipse.ui.IWorkbench workbench},
+ * {@link org.eclipse.ui.IWorkbenchWindow workbench window},
+ * and {@link org.eclipse.ui.IWorkbenchPage workbench page} has a corresponding
  * {@link JpaSelectionManager JPA selection manager}
- * that can be used to set the JPA selection in that workbench or window.
+ * that can be used to set the JPA selection in that workbench, window, or page.
  * <p>
  * To access a workbench's JPA selection manager:
  * <pre>
  *     JpaStructureNode structureNode = ...;
- *     IWorkbenchWindow window = ...;
- *     IWorkbench workbench = window.getWorkbench();
+ *     IWorkbench workbench = PlatformUI.getWorkbench();
  *     // even though IWorkbench extends IAdaptable, it does not delegate to the
  *     // Platform adapter manager; so registered adapter factories are *not* used... :-(
  *     // JpaSelectionManager selectionManager = (JpaSelectionManager) workbench.getAdapter(JpaSelectionManager.class);
@@ -39,16 +39,26 @@ import org.eclipse.jpt.jpa.core.JpaStructureNode;
  *     JpaSelectionManager selectionManager = PlatformTools.getAdapter(window, JpaSelectionManager.class);
  *     selectionManager.setSelection(structureNode);
  * </pre>
+ * <p>
+ * To access a workbench page's JPA selection manager:
+ * <pre>
+ *     JpaStructureNode structureNode = ...;
+ *     IWorkbenchPage page = ...;
+ *     // IWorkbenchPage does not extend IAdaptable(!)
+ *     JpaSelectionManager selectionManager = PlatformTools.getAdapter(page, JpaSelectionManager.class);
+ *     selectionManager.setSelection(structureNode);
+ * </pre>
  * 
  * @see org.eclipse.jpt.jpa.ui.internal.selection.WorkbenchAdapterFactory
  * @see org.eclipse.jpt.jpa.ui.internal.selection.WorkbenchWindowAdapterFactory
+ * @see org.eclipse.jpt.jpa.ui.internal.selection.WorkbenchPageAdapterFactory
  * @see org.eclipse.jpt.jpa.ui.internal.selection.JpaWorkbenchManager
  */
 public interface JpaSelectionManager {
 	/**
 	 * Set the JPA selection for the selection manager's subject.
 	 */
-	public void setSelection(JpaStructureNode selection);
+	void setSelection(JpaStructureNode selection);
 
 
 	/**