From 9641fa3847c03c6aff7f510614f2f0ed58e5bc33 Mon Sep 17 00:00:00 2001 From: Christoph Wilhelms Date: Mon, 10 Feb 2003 23:36:15 +0000 Subject: [PATCH] Introducing Projects tab and first sub-project ANTidote. git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@274046 13f79535-47bb-0310-9956-ffa450edef68 --- xdocs/projects/antidote/design.xml | 244 +++++++++++++++++++++++++++++ xdocs/projects/antidote/index.xml | 62 ++++++++ xdocs/projects/antidote/module.xml | 92 +++++++++++ xdocs/projects/index.xml | 25 +++ xdocs/stylesheets/project.xml | 6 +- 5 files changed, 426 insertions(+), 3 deletions(-) create mode 100644 xdocs/projects/antidote/design.xml create mode 100644 xdocs/projects/antidote/index.xml create mode 100644 xdocs/projects/antidote/module.xml create mode 100644 xdocs/projects/index.xml diff --git a/xdocs/projects/antidote/design.xml b/xdocs/projects/antidote/design.xml new file mode 100644 index 000000000..c5d22aab0 --- /dev/null +++ b/xdocs/projects/antidote/design.xml @@ -0,0 +1,244 @@ + + + + + + Simeon H. K. Fitch + Christoph Wilhelms + Design Overview + + + + +
+

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 + ;-) +

+
+ +
+

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. +

+

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. +

+

To a large extent, the configuration of application modules is + driven by localized configuration files, allowing new modules or + data views to be added, as well as providing multi-language + support. +

+

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 EventBus +

+
+
+ + +---------------+ +----------------+ +-------------+ +-------------+
+ | | | | | | | |
+ | ActionManager | | EventResponder | | AntModule | | AntModule |
+ | | | | |(ProjectNav) | |(SourceEdit) |
+ +---------------+ +----------------+ +-------------+ +-------------+
+ | ^ ^ ^
+ | | | |
+ ActionEvent EventObject AntEvent AntEvent
+ | | | |
+ v v v v
+ /---------------------------------------------------------------------\
+ / \
+< EventBus >
+ \ /
+ \---------------------------------------------------------------------/
+ | ^ ^ ^
+ | | | |
+ EventObject ChangeEvent BuildEvent EventObject
+ | | | |
+ v | | v
+ +---------------+ +----------------+ +-------------+ +--------------+
+ | | | | | | | |
+ | Console | | ProjectProxy | | Ant | | (Your Module)|
+ | | | | | | | |
+ +---------------+ +----------------+ +-------------+ +--------------+ + +

The backbone of the application is the EventBus. Any + component of the application can post events to the + EventBus. Components that wish to receive events are + called BusMembers. +

+ +

The EventBus will dispatch any object of type + java.util.Event, which means that Ant BuildEvent + objects, as well as AWTEvent objects can be posted (if desired). A + new class of events called AntEvent is defined for Antidote + specific events, which have the additional capability of being + cancelled mid-dispatch. +

+ +

Each BusMember must provide a BusFilter instance, + which is the members' means of telling the bus which + events it is interested in. This allows a BusMember to, + say, only receive AntEvent objects. +

+ +

When a BusMember registers itself with the + EventBus, it must provide a (so called) interrupt + level which is a integer value defining a relative ordering + for dispatching EventObjects to BusMembers. The + purpose of this is to allow certain BusMember instances + to see an event before others, and in the case of AntEvent + objects, keep the event from propogating onward. The + EventBus class defines the interrupt level constants + VETOING=1, MONITORING=5, and RESPONDING=10 to + help define categories of members. The implied purpose being that: +

+
    + +
  • VETOING: 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 + RESPONDING group. +
    • + +
  • MONITORING: Just listens for events, like a logger + or status monitor. +
    • + +
  • RESPONDING: Process events in a default manner, + knowing that the event has passed any VETOING members. +
    • + +
+ +

Within a specific interrupt level, the order in which members will + receive events is undefied. A BusMember may be registered + at a level that is +/- of one of the defined levels, as long as it + follows the constraint MONITORING <= interruptLevel <= + MAX_INTERRUPT. +

+
+ +
+

Extensive use of the javax.swing.Action interface is + made for defining the set of menu and tool bar options that are + available. The configuration file action.properties + exists to define what should appear in the menu and toolbar, how + it is displayed, and the Action command name that is + dispatched when the user invokes that action. A class called + ActionManager exists for not only processing the + configuration file, but also for dispatching invoked action events + to the EventBus, and for controlling the enabled state of + an Action. When a new menu item or toolbar button is + desired, first it is added to the action.properties file, + and then the code to respond to it is added to the + EventResponder (see below). +

+
+
+

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 Command interface is defined to classify + code which performs some task or operation. This is distinct from + an Action, which is a user request for an operation. A + Command class is the encapsulation of the operation + itself. +

+ +

When an Action generates an ActionEvent, the + event is posted to the EventBus which delivers the event + to all interested BusMembers. It eventually makes it to + the EventResponder instance (registered at the + RESPONDING interrupt level), which is responsible for + translating specific events into Command objects, and + then executing the Command object. For example, when the + user selects the "Open..." menu option, an ActionEvent is + generated by the Swing MenuItem class, which is then + posted to the EventBus by the ActionManager. The + ActionEvent is delivered to the EventResponder, + which converts the ActionEvent into a Command + instance. The EventResponder then calls the method + Command.execute() to invoke the command (which displays a + dialog for selecting a file to open). +

+ +

When adding new Actions or general tasks to the + application, a Command object should be created to + encapsulate the behavior. This includes most operations which + modify the state of the data model. +

+ +

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. +

+
+
+

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. Right now the data model is encapsulated in the package + org.apache.tools.ant.gui.acs (where "acs" stands for "Ant Construction Set"). +

+
+
+

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 AppContext is the catch-all + class for containing the application state. Most modules and + Command classes require an instance of the + AppContext class. Because all state information in + contained in an AppContext instance, multiple instances + of Antidote can run inside the same JVM as long as each has it's + own AppContext. (Interestingly, two instances of the + Antidote could conceivably share an AppContext instance + through RMI, allowing remote interaction/collaboration.) +

+
+
+

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 + antidote.properties, which is located (with other UI + resources) in the subpackage "resources". +

+ +

To aid in the lookup of text properties, as well as other + resources like icons, a class called ResourceManager 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. +

+ +

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 "org.apache.tools.ant.gui.About.message" for the text + message it should display. Therefore, the ResourceManager + method getString() takes a Class instance as + well as a String key. Please see the + ResourceManager documentation for more information. Given + this support, no user visible strings should appear in the source + code itself. +

+
+ + + + diff --git a/xdocs/projects/antidote/index.xml b/xdocs/projects/antidote/index.xml new file mode 100644 index 000000000..839c12544 --- /dev/null +++ b/xdocs/projects/antidote/index.xml @@ -0,0 +1,62 @@ + + + + + + Christoph Wilhelms + About Antidote + + + + +
+

ANTidote is the GUI for Ant...

+ +

... in fact it is the Ant GUI by the Apache Ant project itself, because, + as you might know, there are several other grafical user interfaces covering Ant. + Most of them are integrated in IDEs such as NetBeans + or Eclipse. To be honest Antidote + has started a long time ago (spring 2000) and was designed to become integratible into + IDEs by it's original Author Simeon H. K. Fitch, who did the most work on Antidote. + Unfortunately the Antidote community never came really "to speed" and so the IDE-guys + where faster with their integrations. +

+

With these other Ant GUIs Antidote became less important and it seemed there was not much + interest in such a tool... +

+

Anyways: The "sleeping beauty" Antidote has been awaken and is now being developed to + a full featured, stand alone, JFC/Swing-based Ant GUI to grafically create, edit and run + build-files to be quite useful for the developer who do not use an IDE at all. So one of + the goals of Antidote development is to make it small, fast and really neat :)! +

+
+ +
+

+ Screenshot +

+

This is a screenshot of how Antidote looks today. Still there is, of course, a lot to do + and you are welcome to contribute! It shows Antidote using a custom look and feel called + "Metouia" which you can find here if you want to try it! +

+
+ +
+

Antidote is discussed on the main Ant mailing lists you can find here: +

+ + + + +
+ + + + diff --git a/xdocs/projects/antidote/module.xml b/xdocs/projects/antidote/module.xml new file mode 100644 index 000000000..f3e6e6c81 --- /dev/null +++ b/xdocs/projects/antidote/module.xml @@ -0,0 +1,92 @@ + + + + + + Simeon H. K. Fitch + Christoph Wilhelms + Module HOW-TO + + + + +
+

The purpose of this document is to provide an overview of the + basic steps one must undertake to add a new module to + Antidote. Please see The Antidote + Design Overview for information on what a module is and how it + fits into Antidote. If you've already got all that, then read + on! +

+ +

NB: Please submit updates and criticisms to this, particularly + areas that were unclear, missing, or difficult to follow. +

+
+ +
+

1) Specialize org.apache.tools.ant.gui.core.AntModule

+ +

All modules must inherit from the AntModule + class. This will probably irritate some of you, but it essentially + enforces inheritance from javax.swing.JComponent and + provides encapsulated handling of the AppContext instance + that is so important to this class. +

+ +

Your module is required to implement the + AntModule.contextualize(AppContext) method. The first + thing this method should do is call + AntModule.setContext(AppContext), and then it is safe for + it to begin constructing its display, using whatever resources it + needs from the given AppContext instance. Think of this + in a similar manner to Applet.init() or + Servlet.init(). +

+ +

2) Update + org/apache/tools/ant/gui/resources/antidote.properties

+ +

2a) Externalize All Displayable Strings

+ +

All displayable strings must be externalized to the + antidote.properties file, and looked up via the + AppContext.getResources() method after the + AntModule.contextualize() method has been called. Follow + the naming convention currently used in the properties file and + you should have to problems. This task should be done + during development of your module. Under no cercumstances + should your module be submitted or committed without this task + being completed. Remember that Antidote has an international + audience. +

+ +

2b) Add Module to List of Auto-Loaded Modules

+ +

Look for the properties with the format + org.apache.tools.ant.gui.Antidote.xxx.modules where + xxx is one of {left | right | top | bottom}. Depending on + where you want your module to appear, and the order that you want + it to appear in relationship to the other modules, add the class + name of your module appropriately. If multiple modules are listed + for a single property (via a comma delimited list), then each + module will have it's own tab in a javax.swing.JTabbedPane. +

+ +

NB:This goofy way of constructing the main screen will probably + change to something much more general (but not as general as, say + BML). +

+ +

Run it!

+

That should be all you need to do, at least to get your module + plugged in. Check out the source code for + ProjectNavigator and PropertyEditor for module + examples that use the various facilities of the Antidote + framework. +

+ +
+ + + diff --git a/xdocs/projects/index.xml b/xdocs/projects/index.xml new file mode 100644 index 000000000..87396612a --- /dev/null +++ b/xdocs/projects/index.xml @@ -0,0 +1,25 @@ + + + + + + Christoph Wilhelms + Welcome + + + + +
+

This is where the Ant sub-projects live!

+ +

Now, that Ant has become an Apache Top-Level Project it is time to make space on this + Web-Page for Ant sub-projects. In the first step Antidote, + the Ant GUI, is included, but some others may follow! +

+

To make shure you do not miss anything: Stay tuned and visit this page from time to time :)! +

+
+ + + + diff --git a/xdocs/stylesheets/project.xml b/xdocs/stylesheets/project.xml index b110ffece..9442d98ab 100644 --- a/xdocs/stylesheets/project.xml +++ b/xdocs/stylesheets/project.xml @@ -5,7 +5,7 @@ Apache Ant - + @@ -45,7 +45,7 @@ - +