<!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>