|
|
|
@@ -0,0 +1,258 @@ |
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "strict.dtd"> |
|
|
|
<HTML> |
|
|
|
<HEAD> |
|
|
|
<TITLE>Antidote Design Overview</TITLE> |
|
|
|
</HEAD> |
|
|
|
|
|
|
|
<BODY> |
|
|
|
|
|
|
|
<H1>Antidote Design Overview</H1> |
|
|
|
|
|
|
|
<P>Version 0.1 (2000/11/02)</P> |
|
|
|
|
|
|
|
<P>Authors: |
|
|
|
<A HREF="mailto:simeon@fitch.net">Simeon H.K. Fitch</A> |
|
|
|
</P> |
|
|
|
|
|
|
|
<H2>Introduction</H2> |
|
|
|
|
|
|
|
<P>The purpose of this document is to communicate the overall |
|
|
|
structure and design patters used in Antidote, the GUI for |
|
|
|
Ant. This document is a work in progress, as well as a living |
|
|
|
document, and it is most likely not be in full synchronization with |
|
|
|
the source code. Therefore, if there is any doubt, view the source |
|
|
|
;-)</P> |
|
|
|
|
|
|
|
<H2>Overview</H2> |
|
|
|
|
|
|
|
<P>The Antidote architecture design aims to provide a high level |
|
|
|
of modularity and extensibility. Ideally the components of |
|
|
|
Antidote will be able to be assembled in different configurations |
|
|
|
to provide the type of application or plug-in desired.</P> |
|
|
|
|
|
|
|
<P>To acheive this modularity, a high level of decoupling is |
|
|
|
necessary. The standard UI design approach of providing separation |
|
|
|
of view (presentation) from model (data) is applied, leveraging |
|
|
|
the built-in Ant data model where possible, as well as the |
|
|
|
predifined Swing model interfaces. Furthermore, the architecture |
|
|
|
is highly event driven, whereby modules communicate via a shared |
|
|
|
communications channel.</P> |
|
|
|
|
|
|
|
<P>To a large extent, the configuration of application modules is |
|
|
|
driven by localized configuration files, allowing new editors or |
|
|
|
data views to be added, as well as providing multi-language |
|
|
|
support.</P> |
|
|
|
|
|
|
|
<P>The diagram below conveys a high altitude view of the |
|
|
|
application's structure. As the application grows, new components |
|
|
|
will be plugged in to what will be described as the <TT>EventBus</TT>. |
|
|
|
|
|
|
|
<TT><PRE> |
|
|
|
|
|
|
|
Antidote Component Architecture |
|
|
|
|
|
|
|
+---------------+ +----------------+ +-------------+ +-------------+ |
|
|
|
| | | | | | | | |
|
|
|
| ActionManager | | EventResponder | | AntEditor | | AntEditor | |
|
|
|
| | | | |(ProjectNav) | |(SourceEdit) | |
|
|
|
+---------------+ +----------------+ +-------------+ +-------------+ |
|
|
|
| ^ ^ ^ |
|
|
|
| | | | |
|
|
|
ActionEvent EventObject AntEvent AntEvent |
|
|
|
| | | | |
|
|
|
v v v v |
|
|
|
/---------------------------------------------------------------------\ |
|
|
|
/ \ |
|
|
|
< EventBus > |
|
|
|
\ / |
|
|
|
\---------------------------------------------------------------------/ |
|
|
|
| ^ ^ ^ |
|
|
|
| | | | |
|
|
|
EventObject ChangeEvent BuildEvent EventObject |
|
|
|
| | | | |
|
|
|
v | | v |
|
|
|
+---------------+ +----------------+ +-------------+ +--------------+ |
|
|
|
| | | | | | | | |
|
|
|
| Console | | ProjectProxy | | Ant | | (Your Module)| |
|
|
|
| | | | | | | | |
|
|
|
+---------------+ +----------------+ +-------------+ +--------------+ |
|
|
|
|
|
|
|
</TT></PRE> |
|
|
|
|
|
|
|
<H2>Event Bus</H2> |
|
|
|
|
|
|
|
<P>The backbone of the application is the <TT>EventBus</TT>. Any |
|
|
|
component of the application can post events to the |
|
|
|
<TT>EventBus</TT>. Components that wish to receive events are |
|
|
|
called <TT>BusMember</TT>s.</P> |
|
|
|
|
|
|
|
<P>The <TT>EventBus</TT> will dispatch any object of type |
|
|
|
<TT>java.util.EventBus</TT>, which means that Ant <TT>BuildEvent</TT> |
|
|
|
objects, as well as <TT>AWTEvent</TT> objects can be posted (if desired). A |
|
|
|
new class of events called <TT>AntEvent</TT> is defined for Antidote |
|
|
|
specific events, which have the additional capability of being |
|
|
|
cancelled mid-dispatch.</P> |
|
|
|
|
|
|
|
<P>Each <TT>BusMember</TT> must provide a <TT>BusFilter</TT> instance, |
|
|
|
which is the members' means of telling the bus which |
|
|
|
events it is interested in. This allows a <TT>BusMember</TT> to, |
|
|
|
say, only receive <TT>AntEvent</TT> objects.</P> |
|
|
|
|
|
|
|
<P>When a <TT>BusMember</TT> registers itself with the |
|
|
|
<TT>EventBus</TT>, it must provide a (so called) <I>interrupt |
|
|
|
level</I> which is a integer value defining a relative ordering |
|
|
|
for dispatching <TT>EventObject</TT>s to <TT>BusMember</TT>s. The |
|
|
|
purpose of this is to allow certain <TT>BusMember</TT> instances |
|
|
|
to see an event before others, and in the case of <TT>AntEvent</TT |
|
|
|
objects, keep the event from propogating onward. The |
|
|
|
<TT>EventBus</TT> class defines the interrupt level constants |
|
|
|
<TT>MONITORING=1</TT>, <TT>VETOING=5</TT>, and <TT>RESPONDING=10</TT> to |
|
|
|
help define categories of members. The implied purpose being that: |
|
|
|
<UL> |
|
|
|
|
|
|
|
<LI><TT>MONITORING</TT>: Just listens for events, like a logger |
|
|
|
or status monitor.</LI> |
|
|
|
|
|
|
|
<LI><TT>VETOING</TT>: Listens for certain types of events, and |
|
|
|
may process them in a non-default manner to determine if the |
|
|
|
event should be cancelled before being dispatched to the |
|
|
|
<TT>RESPONDING</TT> group. An example of this might be to handle |
|
|
|
a <I>SaveAs</I> event, whereby a <TT>VETOING</TT> member will |
|
|
|
check to see if the file exists, and ask the user if they are |
|
|
|
sure they want to overwrite the existing file. The <I>SaveAs</I> |
|
|
|
event could then be cancelled before the operation is executed.</LI> |
|
|
|
|
|
|
|
<LI><TT>RESPONDING</TT>: Process events in a default manner, |
|
|
|
knowing that the event has passed any <TT>VETOING</TT> members.</LI> |
|
|
|
|
|
|
|
</UL> |
|
|
|
|
|
|
|
Within a specific interrupt level, the order in which members will |
|
|
|
receive events is undefied. A <TT>BusMember</TT> may be registered |
|
|
|
at a level that is +/- of one of the defined levels, as long as it |
|
|
|
follows the constraint <TT>MONITORING <= interruptLevel <= |
|
|
|
MAX_INTERRUPT</TT>.</P> |
|
|
|
|
|
|
|
|
|
|
|
<H2>Actions and ActionManager</H2> |
|
|
|
|
|
|
|
<P>Extensive use of the <TT>javax.swing.Action</TT> interface is |
|
|
|
made for defining the set of menu and tool bar options that are |
|
|
|
available. The configuration file <TT>action.properties</TT> |
|
|
|
exists to define what should appear in the menu and toolbar, how |
|
|
|
it is displayed, and the <TT>Action</TT> command name that is |
|
|
|
dispatched when the user invokes that action. A class called |
|
|
|
<TT>ActionManager</TT> exists for not only processing the |
|
|
|
configuration file, but also for dispatching invoked action events |
|
|
|
to the <TT>EventBus</TT>, and for controlling the enabled state of |
|
|
|
an <TT>Action</TT>. When a new menu item or toolbar button is |
|
|
|
desired, first it is added to the <TT>action.properties</TT> file, |
|
|
|
and then the code to respond to it is added to the |
|
|
|
<TT>EventResponder</TT> (see below). |
|
|
|
|
|
|
|
|
|
|
|
<H2>Commands and EventResponder</H2> |
|
|
|
|
|
|
|
<P>At some point in the stages of event processing, an event may |
|
|
|
require the data model to be modified, or some other task be |
|
|
|
performed. The <TT>Command</TT> interface is defined to classify |
|
|
|
code which performs some task or operation. This is distinct from |
|
|
|
an <TT>Action</TT>, which is a user request for an operation. A |
|
|
|
<TT>Command</TT> class is the encapsulation of the operation |
|
|
|
itself.</P> |
|
|
|
|
|
|
|
<P>When an <TT>Action</TT> generates an <TT>ActionEvent</TT>, the |
|
|
|
event is posted to the <TT>EventBus</TT> which delivers the event |
|
|
|
to all interested <TT>BusMember</TT>s. It eventually makes it to |
|
|
|
the <TT>EventResponder</TT> instance (registered at the |
|
|
|
<TT>RESPONDING</TT> interrupt level), which is responsible for |
|
|
|
translating specific events into <TT>Command</TT> objects, and |
|
|
|
then executing the <TT>Command</TT> object. For example, when the |
|
|
|
user selects the "Open..." menu option, an <TT>ActionEvent</TT> is |
|
|
|
generated by the Swing <TT>MenuItem</TT> class, which is then |
|
|
|
posted to the <TT>EventBus</TT> by the <TT>ActionManager</TT>. The |
|
|
|
<TT>ActionEvent</TT> is delivered to the <TT>EventResponder</TT>, |
|
|
|
which converts the <TT>ActionEvent</TT> into a <TT>Command</TT> |
|
|
|
instance. The <TT>EventResponder</TT> then calls the method |
|
|
|
<TT>Command.execute()</TT> to invoke the command (which displays a |
|
|
|
dialog for selecting a file to open).</P> |
|
|
|
|
|
|
|
<P>When adding new <TT>Action</TT>s or general tasks to the |
|
|
|
application, a <TT>Command</TT> object should be created to |
|
|
|
encapsulate the behavior. This includes most operations which |
|
|
|
modify the state of the data model.</P> |
|
|
|
|
|
|
|
<P>The purpose of this encapsulation is to allow the clean |
|
|
|
separation of making a request, and servicing a request. Due to |
|
|
|
various conditions in the application state, the actualy response |
|
|
|
to a request may change, as well as who services it. This |
|
|
|
design approach facilitates that.</P> |
|
|
|
|
|
|
|
<H2>Data Model and Views</H2> |
|
|
|
|
|
|
|
<P>The data model is mainly defined by the Ant application, |
|
|
|
primarily through the <TT>Project</TT>, <TT>Target</TT>, and |
|
|
|
<TT>Task</TT> classes.<P> However, Antidote defines the class |
|
|
|
<TT>ProjectProxy</TT> to act not only as a proxy to the real |
|
|
|
<TT>Project</TT> class, but also as creator of GUI <I>views</I> of |
|
|
|
the <TT>Project</TT>. A <I>view</I> is essentially a flyweight or |
|
|
|
data proxy; it provides an orgainizational perspective on the actual |
|
|
|
<TT>Project</TT> structure. For example, to render a |
|
|
|
<TT>JTree</TT> version of the <TT>Project</TT>, one would call the |
|
|
|
method <TT>ProjectProxy.getTreeModel()</TT>. Similarly, to get a |
|
|
|
<TT>Document</TT> version of the <TT>Project</TT>, the |
|
|
|
<TT>ProjectProxy,getDocument()</TT> method is used.</P> |
|
|
|
|
|
|
|
<P><I>NB: This part of the architecture is not fleshed out very |
|
|
|
well. There needs to be a discussion of the degree to which the |
|
|
|
Antidote development should be able to impose changes on the Ant |
|
|
|
data model, and to what level that model should be mirrored in the |
|
|
|
Antidote code base. The coupling between them should be kept low, |
|
|
|
and at the same time changes to one should affect the other |
|
|
|
minimally. Still, features like property change events and bean |
|
|
|
introspection (or BeanInfo) may be needed to be added to the Ant |
|
|
|
data model. Having each view into the data go to the ProjectProxy |
|
|
|
for its data model may not be the best approach. In other words, |
|
|
|
lots of thought needs to occur here.</I></P> |
|
|
|
|
|
|
|
<H2>Application Context</H2> |
|
|
|
|
|
|
|
<P>In order to keep the coupling amoung application modules to a |
|
|
|
minimum, a single point of reference is needed for coordination |
|
|
|
and data sharing. The class <TT>AppContext</TT> is the catch-all |
|
|
|
class for containing the application state. Most modules and |
|
|
|
<TT>Command</TT> classes require an instance of the |
|
|
|
<TT>AppContext</TT> class. Because all state information in |
|
|
|
contained in an <TT>AppContext</TT> instance, multiple instances |
|
|
|
of Antidote can run inside the same JVM as long as each has it's |
|
|
|
own <TT>AppContext</TT>. (Interestingly, two instances of the |
|
|
|
Antidote could conceivably share an <TT>AppContext</TT> instance |
|
|
|
through RMI, allowing remote interaction/collaboration.)</P> |
|
|
|
|
|
|
|
<H2>Configuration and ResourceManager</H2> |
|
|
|
|
|
|
|
<P>Full "i18n" support should be assumed in modern applications, |
|
|
|
and all user viewable strings should be defined in a configuration |
|
|
|
file. For Antidote this configuraiton file is |
|
|
|
<TT>antidote.properties</TT>, which is located (with other UI |
|
|
|
resources) in the subpackage "resources".</P> |
|
|
|
|
|
|
|
<P>To aid in the lookup of text properties, as well as other |
|
|
|
resources like icons, a class called <TT>ResourceManager</TT> is |
|
|
|
defined. There are various convenience methods attached to this |
|
|
|
class, which will likely grow to make looking up configuration |
|
|
|
values as easy as possible.</P> |
|
|
|
|
|
|
|
<P>The organization of configuration properties is based on the |
|
|
|
fully qualifed path of the class that requires the property. For |
|
|
|
example, the "about" box contains a messages, so it looks for the |
|
|
|
property "<TT>org.apache.tools.ant.gui.About.message</TT>" for the text |
|
|
|
message it should display. Therefore, the <TT>ResourceManager</TT> |
|
|
|
method <TT>getString()</TT> takes a <TT>Class</TT> instance as |
|
|
|
well as a <TT>String</TT> key. Please see the |
|
|
|
<TT>ResourceManager</TT> documentation for more information. Given |
|
|
|
this support, no user visible strings should appear in the source |
|
|
|
code itself.</P> |
|
|
|
|
|
|
|
</BODY> |
|
|
|
</HTML> |
Stefan Bodewig
