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