ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chr...@apache.org
Subject cvs commit: ant/xdocs/projects index.xml
Date Mon, 10 Feb 2003 23:36:15 GMT
chrisw      2003/02/10 15:36:15

  Modified:    xdocs/stylesheets project.xml
  Added:       xdocs/projects/antidote design.xml index.xml module.xml
               xdocs/projects index.xml
  Log:
  Introducing Projects tab and first sub-project ANTidote.
  
  Revision  Changes    Path
  1.14      +3 -3      ant/xdocs/stylesheets/project.xml
  
  Index: project.xml
  ===================================================================
  RCS file: /home/cvs/ant/xdocs/stylesheets/project.xml,v
  retrieving revision 1.13
  retrieving revision 1.14
  diff -u -r1.13 -r1.14
  --- project.xml	10 Feb 2003 12:35:11 -0000	1.13
  +++ project.xml	10 Feb 2003 23:36:15 -0000	1.14
  @@ -5,7 +5,7 @@
       <logo href="images/ant_logo_large.gif">Apache Ant</logo>
   
       <body>
  -<!--       <menusection name="Home" index="0"         href="/index.html"> -->
  +       <menusection name="Home" index="0"         href="/index.html">
               <menu name="Apache Ant">
                   <item name="Welcome"               href="/index.html"/>
                   <item name="License"               href="/license.html"/>
  @@ -45,7 +45,7 @@
                   <item name="Project Guidelines"    href="/guidelines.html"/>
                   <item name="Legal"                 href="/legal.html"/>
               </menu>
  -<!--        </menusection>
  +        </menusection>
   
           <menusection name="Projects" index="1"     href="/projects/index.html">
               <menu name="Projects">
  @@ -56,6 +56,6 @@
                   <item name="Design Overview"       href="/projects/antidote/design.html"/>
                   <item name="Module HOW-TO"         href="/projects/antidote/module.html"/>
               </menu>
  -        </menusection>-->
  +        </menusection>
       </body>
   </project>
  
  
  
  1.1                  ant/xdocs/projects/antidote/design.xml
  
  Index: design.xml
  ===================================================================
  <?xml version="1.0"?>
  <document>
  
    <properties>
      <index value="1"/>
      <author email="simeon@fitch.net">Simeon H. K. Fitch</author>
      <author email="christoph.wilhelms@t-online.de">Christoph Wilhelms</author>
      <title>Design Overview</title>
    </properties>
  
  <body>
  
    <section name="Introduction">
      <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>
    </section>
  
    <section name="Overview">
      <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 modules 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 <code>EventBus</code>
      </p>
    </section>
    <section name="Antidote Component Architecture/Event Bus">
      <source>
     +---------------+ +----------------+ +-------------+ +-------------+<br/>
     |               | |                | |             | |             |<br/>
     | ActionManager | | EventResponder | |  AntModule  | |  AntModule  |<br/>
     |               | |                | |(ProjectNav) | |(SourceEdit) |<br/>
     +---------------+ +----------------+ +-------------+ +-------------+<br/>
             |                  ^               ^               ^<br/>
             |                  |               |               |<br/>
        ActionEvent         EventObject      AntEvent       AntEvent<br/>
             |                  |               |               |<br/>
             v                  v               v               v<br/>
    /---------------------------------------------------------------------\<br/>
   /                                                                       \<br/>
  &lt;                                   EventBus                              &gt;<br/>
   \                                                                       /<br/>
    \---------------------------------------------------------------------/<br/>
             |                  ^               ^               ^<br/>
             |                  |               |               |<br/>
        EventObject         ChangeEvent      BuildEvent     EventObject<br/>
             |                  |               |               |<br/>
             v                  |               |               v<br/>
     +---------------+ +----------------+ +-------------+ +--------------+<br/>
     |               | |                | |             | |              |<br/>
     |   Console     | |  ProjectProxy  | |    Ant      | | (Your Module)|<br/>
     |               | |                | |             | |              |<br/>
     +---------------+ +----------------+ +-------------+ +--------------+
      </source>
      <p>The backbone of the application is the <TT>EventBus</TT>. Any
      component of the application can post events to the
      <code>EventBus</code>. Components that wish to receive events are
      called <code>BusMember</code>s.
      </p>
  
      <p>The <code>EventBus</code> will dispatch any object of type
      <code>java.util.Event</code>, which means that Ant <code>BuildEvent</code>
      objects, as well as <code>AWTEvent</code> objects can be posted (if desired).
A
      new class of events called <code>AntEvent</code> is defined for Antidote
      specific events, which have the additional capability of being
      cancelled mid-dispatch.
      </p>
  
      <p>Each <code>BusMember</code> must provide a <code>BusFilter</code>
instance,
      which is the members' means of telling the bus which
      events it is interested in. This allows a <code>BusMember</code> to,
      say, only receive <code>AntEvent</code> objects.
      </p>
  
      <p>When a <code>BusMember</code> registers itself with the
      <code>EventBus</code>, it must provide a (so called) <i>interrupt
      level</i> which is a integer value defining a relative ordering
      for dispatching <code>EventObject</code>s to <code>BusMember</code>s.
The
      purpose of this is to allow certain <code>BusMember</code> instances
      to see an event before others, and in the case of <code>AntEvent</code>
      objects, keep the event from propogating onward. The
      <code>EventBus</code> class defines the interrupt level constants
      <code>VETOING=1</code>, <code>MONITORING=5</code>, and <code>RESPONDING=10</code>
to
      help define categories of members. The implied purpose being that:
      </p>
      <ul>
  
        <li><code>VETOING</code>: 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
          <code>RESPONDING</code> group.
        </li>
  
        <li><code>MONITORING</code>: Just listens for events, like a logger
          or status monitor.
        </li>
  
        <li><code>RESPONDING</code>: Process events in a default manner,
          knowing that the event has passed any <code>VETOING</code> members.
        </li>
  
      </ul>
  
      <p>Within a specific interrupt level, the order in which members will
      receive events is undefied. A <code>BusMember</code> may be registered
      at a level that is +/- of one of the defined levels, as long as it
      follows the constraint <code>MONITORING &lt;= interruptLevel &lt;=
      MAX_INTERRUPT</code>.
      </p>
    </section>
  
    <section name="Actions and ActionManager">
      <p>Extensive use of the <code>javax.swing.Action</code> interface
is
      made for defining the set of menu and tool bar options that are
      available. The configuration file <code>action.properties</code>
      exists to define what should appear in the menu and toolbar, how
      it is displayed, and the <code>Action</code> command name that is
      dispatched when the user invokes that action. A class called
      <code>ActionManager</code> exists for not only processing the
      configuration file, but also for dispatching invoked action events
      to the <code>EventBus</code>, and for controlling the enabled state of
      an <code>Action</code>. When a new menu item or toolbar button is
      desired, first it is added to the <code>action.properties</code> file,
      and then the code to respond to it is added to the
      <code>EventResponder</code> (see below).
      </p>
    </section>
    <section name="Commands and EventResponder">
    <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 <code>Command</code> interface is defined to classify
      code which performs some task or operation. This is distinct from
      an <code>Action</code>, which is a user request for an operation. A
      <code>Command</code> class is the encapsulation of the operation
      itself.
      </p>
  
      <p>When an <code>Action</code> generates an <code>ActionEvent</code>,
the
      event is posted to the <code>EventBus</code> which delivers the event
      to all interested <code>BusMember</code>s. It eventually makes it to
      the <code>EventResponder</code> instance (registered at the
      <code>RESPONDING</code> interrupt level), which is responsible for
      translating specific events into <code>Command</code> objects, and
      then executing the <code>Command</code> object. For example, when the
      user selects the "Open..." menu option, an <code>ActionEvent</code> is
      generated by the Swing <code>MenuItem</code> class, which is then
      posted to the <code>EventBus</code> by the <code>ActionManager</code>.
The
      <code>ActionEvent</code> is delivered to the <code>EventResponder</code>,
      which converts the <code>ActionEvent</code> into a <code>Command</code>
      instance. The <code>EventResponder</code> then calls the method
      <code>Command.execute()</code> to invoke the command (which displays a
      dialog for selecting a file to open).
      </p>
  
      <p>When adding new <code>Action</code>s or general tasks to the
      application, a <code>Command</code> 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>
    </section>
    <section name="Data Model and Views">
      <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. Right now the data model is encapsulated in the package
      <code>org.apache.tools.ant.gui.acs</code> (where "<code>acs</code>"
stands for "Ant Construction Set").</i>
      </p>
    </section>
    <section name="Application Context">
      <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 <code>AppContext</code> is the catch-all
      class for containing the application state. Most modules and
      <code>Command</code> classes require an instance of the
      <code>AppContext</code> class. Because all state information in
      contained in an <code>AppContext</code> instance, multiple instances
      of Antidote can run inside the same JVM as long as each has it's
      own <code>AppContext</code>. (Interestingly, two instances of the
      Antidote could conceivably share an <code>AppContext</code> instance
      through RMI, allowing remote interaction/collaboration.)
      </p>
    </section>
    <section name="Configuration and ResourceManager">
      <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
      <code>antidote.properties</code>, 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 <code>ResourceManager</code> 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 "<code>org.apache.tools.ant.gui.About.message</code>" for the text
      message it should display. Therefore, the <code>ResourceManager</code>
      method <code>getString()</code> takes a <code>Class</code> instance
as
      well as a <code>String</code> key. Please see the
      <code>ResourceManager</code> documentation for more information. Given
      this support, no user visible strings should appear in the source
      code itself.
      </p>
    </section>
  
  </body>
  </document>
  
  
  
  
  1.1                  ant/xdocs/projects/antidote/index.xml
  
  Index: index.xml
  ===================================================================
  <?xml version="1.0"?>
  <document>
  
    <properties>
      <index value="1"/>
      <author email="christoph.wilhelms@t-online.de">Christoph Wilhelms</author>
      <title>About Antidote</title>
    </properties>
  
  <body>
  
    <section name="About">
      <h3>ANTidote is the GUI for Ant...</h3>
  
      <p>... 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 <a href="http://ant.netbeans.org">NetBeans</a>
        or <a href="http://www.eclipse.org">Eclipse</a>. 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.
      </p>
      <p>With these other Ant GUIs Antidote became less important and it seemed there
was not much
        interest in such a tool...
      </p>
      <p>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 :)!
      </p>
    </section>
  
    <section name="Get a glimps">
      <p>
        <img src="images/screenshot.jpg" width="648" height="595" alt="Screenshot"/>
      </p>
      <p>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 <a href="http://mlf.sourceforge.net">here</a>
if you want to try it!
      </p>
    </section>
  
    <section name="Get Involved">
      <p>Antidote is discussed on the main Ant mailing lists you can find here:
      </p>
  <ul>
  <li><a href="http://jakarta.apache.org/getinvolved/getinvolvedindex.html">Get
Involved</a></li>
  <li><a href="mail.html">Join Mailing Lists</a></li>
  <li><a href="http://marc.theaimsgroup.com/?l=ant-dev&amp;r=1&amp;w=2">Search
the Dev Mailing List</a>
  </li>
  <li><a href="http://marc.theaimsgroup.com/?l=ant-user&amp;r=1&amp;w=2">Search
the User Mailing List</a>
  </li>
  </ul>
  
  
  
    </section>
  
  </body>
  </document>
  
  
  
  
  1.1                  ant/xdocs/projects/antidote/module.xml
  
  Index: module.xml
  ===================================================================
  <?xml version="1.0"?>
  <document>
  
    <properties>
      <index value="1"/>
      <author email="simeon@fitch.net">Simeon H. K. Fitch</author>
      <author email="christoph.wilhelms@t-online.de">Christoph Wilhelms</author>
      <title>Module HOW-TO</title>
    </properties>
  
  <body>
  
    <section name="Introduction">
      <p>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 <a href="./design.html">The Antidote
      Design Overview</a> for information on what a module is and how it
      fits into Antidote. If you've already got all that, then read
      on!
      </p>
  
      <p>NB: <i>Please submit updates and criticisms to this, particularly
      areas that were unclear, missing, or difficult to follow.</i>
      </p>
    </section>
  
    <section name="Step by step">
      <h2>1) Specialize <code>org.apache.tools.ant.gui.core.AntModule</code></h2>
  
      <p>All modules must inherit from the <code>AntModule</code>
      class. This will probably irritate some of you, but it essentially
      enforces inheritance from <code>javax.swing.JComponent</code> and
      provides encapsulated handling of the <code>AppContext</code> instance
      that is so important to this class.
      </p>
  
      <p>Your module is required to implement the
      <code>AntModule.contextualize(AppContext)</code> method. The first
      thing this method should do is call
      <code>AntModule.setContext(AppContext)</code>, and then it is safe for
      it to begin constructing its display, using whatever resources it
      needs from the given <code>AppContext</code> instance. Think of this
      in a similar manner to <code>Applet.init()</code> or
      <code>Servlet.init()</code>.
      </p>
  
      <h2>2) Update
         <code>org/apache/tools/ant/gui/resources/antidote.properties</code></h2>
  
      <h3>2a) Externalize All Displayable Strings</h3>
  
      <p>All displayable strings must be externalized to the
      <code>antidote.properties</code> file, and looked up via the
      <code>AppContext.getResources()</code> method after the
      <code>AntModule.contextualize()</code> 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
      <b>during</b> 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.
      </p>
  
      <h3>2b) Add Module to List of Auto-Loaded Modules</h3>
  
      <p>Look for the properties with the format
      <code>org.apache.tools.ant.gui.Antidote.xxx.modules</code> where
      <code>xxx</code> 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 <code>javax.swing.JTabbedPane</code>.
      </p>
  
      <p>NB:<i>This goofy way of constructing the main screen will probably
      change to something much more general (but not as general as, say
      <a href="http://www.alphaworks.ibm.com/tech/bml">BML</a>).</i>
      </p>
  
      <h2>Run it!</h2>
      <p>That should be all you need to do, at least to get your module
      plugged in. Check out the source code for
      <code>ProjectNavigator</code> and <code>PropertyEditor</code>
for module
      examples that use the various facilities of the Antidote
      framework.
      </p>
  
    </section>
  </body>
  </document>
  
  
  
  
  1.1                  ant/xdocs/projects/index.xml
  
  Index: index.xml
  ===================================================================
  <?xml version="1.0"?>
  <document>
  
    <properties>
      <index value="1"/>
      <author email="christoph.wilhelms@t-online.de">Christoph Wilhelms</author>
      <title>Welcome</title>
    </properties>
  
  <body>
  
    <section name="Welcome to the Ant Projects Area">
      <h3>This is where the Ant sub-projects live!</h3>
  
      <p>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 <a href="antidote/index.html">Antidote</a>,
      the Ant GUI, is included, but some others may follow!
      </p>
      <p>To make shure you do not miss anything: Stay tuned and visit this page from
time to time :)!
      </p>
    </section>
  
  </body>
  </document>
  
  
  
  

Mime
View raw message