bundles/org.eclipse.core.commands/src/org/eclipse/core/commands/contexts/package.html - platform/eclipse.platform.ui - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 <title>Package-level Javadoc</title>
 <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css"
 	type="text/css">
 </head>
 <body style="background-color: rgb(255, 255, 255); color: rgb(0, 0, 0)">
 Application programming interfaces for contexts.
 <h2>Package Specification</h2>
 <p>
 This package provides API and implementation classes to define abstract
 representations of application state.  These representations of application
 state can be used as an abstraction of the event-listener model -- where
 different sections of code do not (or cannot) refer to each directly.
 </p>
 <p>
 This package is designed so that its elements can be public and dynamic.  That
 is, elements in this package can appear and disappear over the life of the
 application.
 </p>
 <h3>Context</h3>
 <p>
 A context is an answer to the question, "When?"  For example, there might be a
 context called "server running".  When the server is running, then that context
 would be active.  If a program module other than the server wants to test for
 this, they can simply check to see if the context is active.  This allows the
 two program modules to be decoupled from each other.  In fact, a different
 server module could be dropped in place of the first.
 </p>
 <p>
 Contexts are managed by an instance of <code>ContextManager</code>.  In fact, a
 context cannot be constructed directly.  Contexts are constructed using the
 method <code>ContextManager.getContext(String)</code>.  This ensures that there
 is only ever one context with a given identifier ever associated with a context
 manager.
 </p>
 <p>
 When a context is first constructed, it is undefined.  An undefined context is
 one that is carrying no information except for an id.  Attempts to interact
 with a context that is undefined will result in a
 <code>NotDefinedException</code>.  Through this mechanism, it is possible for
 clients to hold references to contexts, and still have those contexts
 "disappear" (i.e., become undefined).  This is particularly useful in a system
 built around dynamic components (e.g., plug-ins).
 </p>
 <p>
 It is also possible to attach listeners to both contexts and context managers.
 A listener on a context manager will be notified if the list of defined
 contexts changes.
 </p>
 <h4>Examples</h4>
 <blockquote><pre><code>
 	ContextManager manager = new ContextManager();
 	Context context = manager.getContext("contextId");
 	context.define("name", "description", null);
 </code></pre></blockquote>
 <p>
 This example shows how to create a context from scratch -- with no existing
 manager.
 </p>
 <blockquote><pre><code>
 	context.undefine();
 	context = null;
 </code></pre></blockquote>
 <p>
 If you wish to get rid of the context, then you simply undefine it.  This
 will send notification to the appropriate listeners, and future attempts to
 access it will fail.  If you are the only one holding on to the context, then
 it will be garbage collected.  However, if other people still have a reference
 to the context, then the stub will remain until they respond to the change.
 </p>
 <blockquote><pre><code>
 	String name;
 	try {
 		name = context.getName();
 	} catch (NotDefinedException e) {
 		// Clean-up my reference to the context.
 		context = null;
 		return;
 	}
 </code></pre></blockquote>
 <p>
 This shows one way of dealing with contexts.  Instead of listening for
 changes to the contexts, you can simply listen for the exceptions to be thrown.
 When a <code>NotDefinedException</code> is thrown, you can clean up your own
 code.  How you clean up is application dependent.  In this case, the reference
 is cleared and we return from the method.
 </p>
 <blockquote><pre><code>
 	try {
 		String name = context.getName();

 		// Do all your work in the block.

 	} catch (NotDefinedException e) {
 		// Ignore, or possibly throw an error
 	}

 	...

 	public contextChanged(ContextEvent e) {
 		if (e.hasDefinedChanged()) {
 			context.removeListener(this);
 			context = null;
 		}
 	}
 </code></pre></blockquote>
 <p>
 Another way is to attach a listener, and then simply ignore the exceptions.
 When the context becomes undefined, you will be notified.  This gives your the
 opportunity to unhook your listener and release your reference.
 </p>
 <blockquote><pre><code>
 	ContextManager manager = new ContextManager();
 	Context parent = manager.getContext("parentId");
 	parent.define("name", "description", null);
 	Context child = manager.getContext("childId");
 	child.define("name", "description", "parentId");
 </code></pre></blockquote>
 <p>
 Contexts can be related to each other with a parent-child relationship.  How
 your application deals with this is up to you.  In the case of the keyboard
 shortcuts in Eclipse, this is used to allow behaviour attributed to child
 contexts to override behaviour attributed to parent contexts.
 </p>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	<html>
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	<title>Package-level Javadoc</title>
	<link rel="stylesheet" href="http://dev.eclipse.org/default_style.css"
	type="text/css">
	</head>
	<body style="background-color: rgb(255, 255, 255); color: rgb(0, 0, 0)">
	Application programming interfaces for contexts.
	<h2>Package Specification</h2>
	<p>
	This package provides API and implementation classes to define abstract
	representations of application state. These representations of application
	state can be used as an abstraction of the event-listener model -- where
	different sections of code do not (or cannot) refer to each directly.
	</p>
	<p>
	This package is designed so that its elements can be public and dynamic. That
	is, elements in this package can appear and disappear over the life of the
	application.
	</p>
	<h3>Context</h3>
	<p>
	A context is an answer to the question, "When?" For example, there might be a
	context called "server running". When the server is running, then that context
	would be active. If a program module other than the server wants to test for
	this, they can simply check to see if the context is active. This allows the
	two program modules to be decoupled from each other. In fact, a different
	server module could be dropped in place of the first.
	</p>
	<p>
	Contexts are managed by an instance of <code>ContextManager</code>. In fact, a
	context cannot be constructed directly. Contexts are constructed using the
	method <code>ContextManager.getContext(String)</code>. This ensures that there
	is only ever one context with a given identifier ever associated with a context
	manager.
	</p>
	<p>
	When a context is first constructed, it is undefined. An undefined context is
	one that is carrying no information except for an id. Attempts to interact
	with a context that is undefined will result in a
	<code>NotDefinedException</code>. Through this mechanism, it is possible for
	clients to hold references to contexts, and still have those contexts
	"disappear" (i.e., become undefined). This is particularly useful in a system
	built around dynamic components (e.g., plug-ins).
	</p>
	<p>
	It is also possible to attach listeners to both contexts and context managers.
	A listener on a context manager will be notified if the list of defined
	contexts changes.
	</p>
	<h4>Examples</h4>
	<blockquote><pre><code>
	ContextManager manager = new ContextManager();
	Context context = manager.getContext("contextId");
	context.define("name", "description", null);
	</code></pre></blockquote>
	<p>
	This example shows how to create a context from scratch -- with no existing
	manager.
	</p>
	<blockquote><pre><code>
	context.undefine();
	context = null;
	</code></pre></blockquote>
	<p>
	If you wish to get rid of the context, then you simply undefine it. This
	will send notification to the appropriate listeners, and future attempts to
	access it will fail. If you are the only one holding on to the context, then
	it will be garbage collected. However, if other people still have a reference
	to the context, then the stub will remain until they respond to the change.
	</p>
	<blockquote><pre><code>
	String name;
	try {
	name = context.getName();
	} catch (NotDefinedException e) {
	// Clean-up my reference to the context.
	context = null;
	return;
	}
	</code></pre></blockquote>
	<p>
	This shows one way of dealing with contexts. Instead of listening for
	changes to the contexts, you can simply listen for the exceptions to be thrown.
	When a <code>NotDefinedException</code> is thrown, you can clean up your own
	code. How you clean up is application dependent. In this case, the reference
	is cleared and we return from the method.
	</p>
	<blockquote><pre><code>
	try {
	String name = context.getName();

	// Do all your work in the block.

	} catch (NotDefinedException e) {
	// Ignore, or possibly throw an error
	}

	...

	public contextChanged(ContextEvent e) {
	if (e.hasDefinedChanged()) {
	context.removeListener(this);
	context = null;
	}
	}
	</code></pre></blockquote>
	<p>
	Another way is to attach a listener, and then simply ignore the exceptions.
	When the context becomes undefined, you will be notified. This gives your the
	opportunity to unhook your listener and release your reference.
	</p>
	<blockquote><pre><code>
	ContextManager manager = new ContextManager();
	Context parent = manager.getContext("parentId");
	parent.define("name", "description", null);
	Context child = manager.getContext("childId");
	child.define("name", "description", "parentId");
	</code></pre></blockquote>
	<p>
	Contexts can be related to each other with a parent-child relationship. How
	your application deals with this is up to you. In the case of the keyboard
	shortcuts in Eclipse, this is used to allow behaviour attributed to child
	contexts to override behaviour attributed to parent contexts.
	</p>
	</body>
	</html>