From 392ba48cd214dff27f4229d6d63a63acb640c69d Mon Sep 17 00:00:00 2001
From: Oleg Besedin
Date: Fri, 24 Feb 2012 11:33:17 -0500
Subject: Bug 371289 - Add "active" context variables

---
 .../eclipse/e4/core/contexts/IEclipseContext.java  | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/IEclipseContext.java b/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/IEclipseContext.java
index 50015f3c6..8a6a19e8f 100644
--- a/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/IEclipseContext.java
+++ b/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/IEclipseContext.java
@@ -286,8 +286,17 @@ public interface IEclipseContext {
 	public void dispose();
 
 	/**
-	 * <STRONG>EXPERIMENTAL, DO NOT USE</STRONG>
 	 * Returns the value stored on the active leaf node of the context's tree.
+	 * <p>
+	 * This method is similar to <code>getActiveLeaf().get(clazz)</code> but optimized
+	 * for a large number of repeat invocations.
+	 * </p>
+	 * <p>Use this method in code paths that are going to receive a large number
+	 * of repeat calls, such as inside {@link RunAndTrack#changed(IEclipseContext)}.
+	 * </p>
+	 * <p>In the code paths that won't be cycled through large number of times, 
+	 * consider using <code>getActiveLeaf().get(clazz)</code>.
+	 * </p>
 	 * @param clazz the class that needs to be found in the active context
 	 * @return an object corresponding to the given class, or <code>null</code>
 	 * @see IEclipseContext#getActiveLeaf()
@@ -295,8 +304,17 @@ public interface IEclipseContext {
 	public <T> T getActive(Class<T> clazz);
 
 	/**
-	 * <STRONG>EXPERIMENTAL, DO NOT USE</STRONG>
 	 * Returns the named value stored on the active leaf node of the context's tree.
+	 * <p>
+	 * This method is similar to <code>getActiveLeaf().get(name)</code> but optimized
+	 * for a large number of repeat invocations.
+	 * </p>
+	 * <p>Use this method in code paths that are going to receive a large number
+	 * of repeat calls, such as inside {@link RunAndTrack#changed(IEclipseContext)}.
+	 * </p>
+	 * <p>In the code paths that won't be cycled through large number of times, 
+	 * consider using <code>getActiveLeaf().get(name)</code>.
+	 * </p>
 	 * @param name the name of the value to return
 	 * @return an object corresponding to the given name, or <code>null</code>
 	 * @see IEclipseContext#getActiveLeaf()
-- 
cgit v1.2.3