project title - ant's nest - a gui for apache...

1 Introduction

Unfortunately, when a really great piece of technology comes along, the creators can sometimes be caught up in the moment and not give much thought to how it will be used; the interface the technology has with the human-world. Apache Ant is a prime example of this.

1.1 What is Apache Ant?

First we must understand what a build tool is. A build tool is an application that is used throughout development, that takes as its input a list of instructions the user wants the tool to automatically perform. According to the Apache Ant website[1], Ant is “a Java-based build tool. In theory, it is kind of like Make, but without Make's wrinkles.” Most build tools out there, such as Make, tend to be OS dependent; but as Ant is written in Java it inherits the portability that comes with it. The format of Make build files can also be very picky; a misplaced or missing tab could bring the whole build to a halt. Ant build files however, are written in XML, once again improving on a file’s portability whilst giving them a loose yet structured format. Another main difference between the two is the way they are extended. Make is extended with shell-based commands, literally typing in the command as it would appear on the command line. As you can imagine this makes the expressive power of Make incredible. But do all commands on UNIX run on Windows? No. Ant’s viewpoint is to create ‘targets’. A target is typically a goal the user wishes to achieve, such as to always have the latest version of the program compiled. The target is then composed of ‘tasks’. There are two tasks in this example; deleting the old files, and compiling the source again. Each task maps to a Java class, which is responsible for carrying out the actions of the task. Therefore Ant can be extended by writing your own tasks, exploiting Java’s platform-independence.

1.2 So what is Ant’s problem?

From the description so far, Ant seems to be pretty impressive. However as it was mentioned earlier, its human interface is poor. The main culprit behind this is the fact that its build files are written in XML. In recent times XML has emerged as the answer to making data portable and easier to process. After all, each piece of information in an XML file is marked-up, and these tags can be analysed efficiently with SAX or DOM technology. The problem though is how easy is it for a human to create one of these files? James Duncan Davidson, the creator of Ant, even recognises this problem:

“In retrospect, and many years later, XML probably wasn’t as good a choice as it seemed at the time. I have now seen build files that are hundreds, and even thousands, of lines long, and, at those sizes, it turns out that XML isn’t quite as friendly a format

to edit as I had hoped.”[10]

A standard XML file by definition involves a lot of typing; for each piece of information in the file, there must also exist a tag marking it up. Each tag must be closed explicitly by an end tag, adding more complexity to creating the file. Now let’s

talk about creating a specialised kind of XML file, an Ant build file. An Ant task is represented as an element in the file, naturally containing attributes like any other element. These attributes vary from task to task, along with the types of data they accept. Some attributes are required by the task, some are optional. Some tasks accept other elements within them, called types. The question is this; how does the user possibly know all of these facts? Additionally, how does the user even know what tasks already exist and what they do?

The current answer to these questions is to look at the documentation provided with Ant. Like an API, all tasks and types are given their own web page, fully explaining any attributes/subtypes needed. For a novice user this can be daunting, and for any user wanting to learn about a new task it can involve a lot of searching.

1.3 Are there currently any solutions?

There are Ant editors out there, but how much do they ease the user’s creation of a build file?

Editor URL CommentsAntidote http://ant.apache.org/projects/

antidote/index.htmlPromised wizards, file generation, and a runner, however it was in development for over five years before finally being retired without even an offcial release.

AntFarm http://plugins.jedit.org/plugins/?AntFarm

Only appears to run build files, only works in JEdit.

JDEE http://jdee.sunsite.dk/ Advanced options for running build files, but none for making them.

Eclipse http://www.eclipse.org/ Integrates Ant nicely, allowing running and creation of build files with autocomplete features. However it still requires a knowledge of the tasks available and whether an attribute is required or not.

1.4 Why can’t they solve the problem?

I believe the main reason applications cannot create an Ant design solution is the lack of an accessible information model behind Ant itself. There is no ‘simple’ way of discovering information at runtime; such things as which tasks are available to the user, which attributes the tasks support, what values the attributes accept, and much more. That is not to say a method to gather this data does not exist, there is a partial solution in the Ant API that will be explained later. But it is just that; a partial solution.

1.5 The Ant Meta-Model is born

Having concluded that there are no complete soulutions currently available, it was decided it was time to make one. As will be explained throughout this report, it was judged the best way to model Ant’s tasks was through the use of XML. Once this model was created (shown throughout chapter 4), its usefulness would be demonstrated by powering two build creation methods. The first would be ‘Ant’s Nest’, a GUI editor for Ant (shown in chapter 5). Apart from being a catchy name it also describes the application in a way; a home for Ant. The author was an Ant user himself, as was his supervisor, so there was a degree of knowledge about the project undertaken. Plus there were plenty of opportunities to gather feedback and opinion from other Ant users through the official Ant mailing lists[2] ran by Apache. The second demonstration of the model’s power would be as an aid to ‘Ant Beans’ (shown in chapter 6). These would be Java Beans that corresponded to Ant targets, providing a COTS aspect to Ant.

1.6 The project goals

The goals of the project are thus:

Create a model of Ant. Produce a method of making an Ant build file that does not involve typing

XML. Produce a method of constructing an Ant build file that does not require the

user to have any knowledge of Ant. Conduct the project ‘open-source’.

It was felt that this project should be conducted ‘open-source’ as Ant itself is; and it would be an ideal chance for the author to ‘give something back’ to the community and gain an expert critique of his ideas.

2 Open-Source Software

Before we go into how the project’s code was formally made open-source software, let’s first understand what this concept means. Normally when someone does something creative, be it writing a program, painting a picture or even composing a sheet of music, it automatically becomes copyrighted. The individual owns the intellectual property rights to that entity. With these rights come constraints on what others can do to the work without the owner’s permission e.g. distribution, modification, etc. For most cases this is a strong piece of protection the individual needs, but for some cases it becomes a hinderance. This project is one of those times.

2.1 How do we make something open-source?

It was desired that the project’s code be made totally free, in the sense of both cost and ownership. As long as the original author was credited for the work, the public were free to do whatever they pleased with the application. This would be the main way the project could trully help Ant; the author would not be able to think of everything. But if anyone and everyone could chip in with their thoughts and upgrades then maybe it would be possible to improve Ant in the areas already discussed. However the intellectual property rights were an obstacle to this.

The way you go about clearing such obstacles is by applying a license to your work. As long as a reference to the license appears on every piece of the project then others would be free to do as they please. There are many different open-source licenses around today, but the one chosen for the project’s code was the Apache License Version 2.0[3]. This is the license that Ant itself is published under, and as the project would involve incorporating the Ant API, then it was thought best to utilise the same license for compatibility. At the top of every piece of code or document would appear the header:

Copyright 200? Christopher Clohosy

Licensed under the Apache License, Version 2.0 (the "License");you may not use this file except in compliance with the License.You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License.

As we can also see, the license excuses the author from any liableness by explicitly not providing any warranty. For developmental, untested software, this is key.

2.2 Where do open-source projects live?

So now the license was arranged it was time to find somewhere willing to host the project. The project needed a solid host, where space was not a problem and access to the project could be gained 24/7 by the public. Luckily for us there is a website dedicated to open-source projects; SourceForge[4].

SourceForge provides outstanding services to a project, for no charge. But to receive these services your project proposal must first be assessed and declared feasible and worth doing. The ideas for the Ant Meta-Model and Ant’s Nest were drafted and submitted to SourceForge, along with the license being used (which is a very important factor in being selected; if you don’t know anything about licenses then you will not have any protection, and neither will SourceForge if something goes wrong). After a few days the project was officially approved and access to the services was authorised. Just forgetting the power we now had, the approval alone was a major confidence boost for the project. SourceForge have seen a lot of projects suceed and fail, so if they thought this one stood a chance then it stood the project in good stead. It had gone from a university project suggestion to having:

Its own web space. A project email address. A CVS server. Nightly backups of everything hosted. A file-release system. Forums dedicated to the project. Mailing lists dedicated to the project. A listing in the SourceForge project directory.

3 The Development Process

From the outset it was clear the project could be broken down into three areas.

The Ant Meta-Model - This was the essential part of the project as it would be strongly interconnected and used by the other parts.

Ant’s Nest – A GUI editor for Ant that could be broken down into further sub-areas. It would use the model as a source for information for creating Ant build files.

Ant Beans – A whole new way of creating an Ant build file, by plugging together partially configured Ant targets (an Ant Bean) and questionning the user to complete the configuration. This would use the model as a source of information on what Ant tasks look like.

3.1 Which development process to use?

There were immediately a few choices of development process to choose from. The ‘waterfall’ approach was ruled out straight away as it meant the whole project would have to be carried out in a very linear manner, one area clearly developed after another. This would hamper the developer as it could be seen there would be overlaps in the development process e.g. Ant’s Nest could be started as soon as the Ant Meta-Model was in a state where it could be queried.

This left one obvious choice for the development process; an incremental method. One that employs iterations and allows these iterations to operate in parallel. If the whole project relied on one big final release at the end, it would be taking on a huge risk that frankly would be quite dangerous.

3.2 How to handle requirements

Requirements-wise, each of the three sub-projects would have a set of ‘global’ requirements, goals if you will. Additionally, each iteration in the instance would have ‘local’ requirements, or specifications as they are sometimes known. These specifications are more directly linked to the ‘machine’ i.e. what exactly the increment produced by this iteration should achieve. These specifications, combined with pieces of knowledge about the domain, help form a satisfaction argument that proves the achievement of a global requirement. More formally this is shown as:

D, S ├ RThe process of planning out the sub-project is therefore quite simple. After

establishing what it is exactly that we want the sub-project to achieve, we make these our global requirements. Then to transform these top-level goals into iterations and delieverables, we simply ask how are we going to achieve these goals. This then moves us from the abstract into more concrete territory, the technicalities of how the

machine will work; the work that physically has to be done. This of course can then be broken down into iterations.

3.3 Good housekeeping

The project is not just about coding and drawing UML diagrams 24/7, there are other things to be done to ensure it is a success. Firstly there’s the Ant build file (found in Appendix A) that will help cut back on the mundane, repetitive tasks faced by the developer. It is essential that this exists as the project is split into so many directories and the management of all these files would be a nightmare if done manually. The complex task of compiling all the source files in this structure, along with adding the jar files it needs to its classpath, is taken care of by the build file. Another thing Ant does for the project is to produce the Java documentation from the source files automatically. This was important as it allows the developer to post the overview of his API straight to the project’s website; this is an open-source project after all.

The build file also automatically tests the project’s code using JUnit. What’s more, it saves the results in an XML format. Then with the addition of the Xalan XML processor[19] it is possible to turn these results into formatted HTML web pages, similar to the Java documentation. And just like those, they can be uploaded to the project’s website for the world to see. Other vital tasks the build file does are to actually run Ant’s Nest (ensuring it has the right jars and environment variables available), produce the zipped distributable of the project, and to create the Ant Bean jar file.

3.4 Keeping the public up-to-date

As previously mentioned, there now exists a way of quickly and easily creating a distributable form of the project; so why not keep the general public in the know by releasing a version every now and then? It would be much better than just surprising them with the finished product at the end, plus it would help with the testing of the code and finding errors before it’s too late. SourceForge has a file release system that enables the easy publication of a distributable, but the project needs some sort of versioning system. In this project’s case it will be very straightforward; the first version will be 1.1, and any subsequent releases will be an increment of 0.1 on the previous version. But to aid version identification even further, each one will be given a code name. The project’s website will then maintain a current download page that will link the user to the latest release in the file system.

4 The Ant Meta-Model

There currently exists no model of the tasks available in Ant or their features. For any budding build file editors out there, this is a major setback and suddenly requires a deep knowledge of the Ant API. Why? Because this is the only way to extract information about Ant, as we will now see.

The current way to make a model

The following walkthrough highlights the complexity of how to currently make an Ant model from the Ant API.

1. Create a new Project object.2. Initialise the object by calling init() on it.3. Retrieve a Hashtable that maps task names to their implementing classes

by calling getTaskDefinitions() on the object.4. Loop through each mapping in the table, creating an

IntrospectionHelper object by passing the Class in the mapping to the static method getHelper() on IntrospectionHelper.

5. The attributes of the task can then be retrieved by calling getAttributes() on the helper object.

6. Any nested elements supported by the task can be found by calling getNestedElements() on the helper.

The advantage of this method is that it can be generated at run-time, modelling the exact version of Ant the user has. However that may also be its downfall. What if the user wishes to develop for a different version of Ant? They may have an old version at home, but they have to produce a build file for a new version that runs in the office. Also what if they have written their own custom tasks? They certainly won’t be accessible using this method.

Another problem with the model produced by this procedure is that it lacks detail. It does the basics of telling you what attributes and nested elements a task supports, but that’s as far as it goes. It does not tell you if an attribute is required by the task, or if it is optional. It does not tell you any conditions that if occurred, would make an attribute required. It also does not advise on what kind of data the attribute holds; is it a Boolean, or a filename, or even a choice from a finite set of values? All we can assume is that it can be represented as a string. If this data was available, then future editors could provide suitable data entry means for attributes.

4.1 The requirements for an Ant Meta-Model

From the research into current modelling techniques carried out, the following requirements were produced for an Ant Meta-Model, and the use cases in figure 1.

ID RequirementAMM1 The model shall know what Ant tasks are available to the user.

AMM2 The model shall know what category a task belongs to.AMM3 The model shall know what attributes a task accepts.AMM4 The model shall know whether attributes are required by the task or

optional.AMM5 The model shall know the type of the data value for an attribute.AMM6 The model shall know nested elements a task accepts.AMM7 The model shall be extendable with the user’s own custom tasks.AMM8 The model shall be open for query.AMM9 The model shall be platform independent.

Figure 1: Ant Meta Model use cases

4.2 Iteration 1

Produce a specification that states what the model will be built in.

This iteration is a short one, but it is fundamental for the whole model. If a poor choice is made here then the model could turn out to be unusable.

The key thing to note here is that the specification produced by this iteration must help form satisfaction arguments for requirements AMMx; if it cannot then no model will ever exist that has the functionality we desire. Firstly we must decide whether the model will be static or dynamic i.e. created seperately from any system that will use it, or created at run-time when it is needed.

It was decided the model would be half-static, half-dynamic. As we have seen from the previous explanation on how to gather Ant information from the Ant API, it is very difficult (and in places impossible) to create the model needed to satisfy our requirements. This ruled out making the creation of the model completely dynamic. So it would have to be created seperately, before it was ever used. But let’s not forget requirement AMM7; a totally static model would render this unsatisfiable.

The model therefore needed to be built in a language that clearly marked up any data it held, that was portable, and could easily be manipulated and extended. There was now only one choice; XML. The specification produced was thus:

ID RequirementAMM_1.1 The model shall be built in XML.

4.3 Iteration 2

ID RequirementAMM_2.1 The model shall have a consistent structure that can be validated.

Now iteration 1 has revealed how the model will be built it’s time to decide on how it will be structured. AMM_2.1 desires the model to be in a state where it can be validated (helping to satisfy AMM8). In XML the common, tried and tested way to do this is by defining a document type definition (DTD) that explictly says what is allowed in the XML file, and where it goes. This is where requirements AMMx are closely scrutinized as they contain the information we want to model. Therefore:

Requirement DTDAMM2 <!ELEMENT AntTaskModel (Category*)>

<!ATTLIST Category name CDATA #REQUIRED>AMM1 <!ELEMENT Category (Task|Type)+>

<!ATTLIST Task name CDATA #REQUIRED><!ATTLIST Type name CDATA #REQUIRED>

AMM3, AMM4 <!ELEMENT Task (Required?,NotRequired?,Accepts?)><!ELEMENT Type (Required?,NotRequired?,Accepts?)><!ELEMENT Required (Attribute*)><!ELEMENT NotRequired (Attribute*)><!ELEMENT Attribute EMPTY><!ATTLIST Attribute name CDATA #REQUIRED><!ATTLIST Attribute condition CDATA #IMPLIED>

AMM5 <!ATTLIST Attribute entry CDATA #IMPLIED>AMM6 <!ELEMENT Accepts (Type)+>

It can be seen the DTD has been built up directly from the requirements, and it clearly enables validation. The XML model file can be added to as long as it obeys these rules, so AMM7 is not constrained. The static structure also enables straightforward querying, so AMM8 is still possible. What’s more, we now have something concrete to work against in the coming iterations.

4.4 Iteration 3

Produce the Ant Task Model.

The language used to build the model has been decided, as well as the structure of it, so it’s now time to actually make the Ant Task Model. You will have noticed the change in name of the model; this is due to the fact that an Ant Meta-Model could potentially model many more features than the requirements have asked for e.g. how to reduce a build file. The model we are producing is more oriented towards the tasks available in Ant, hence the new name the Ant Task Model. This would fit into a collection of other files that would ultimately make up the meta-model.

4.4.1 So where do we start?

We know there exists no way of generating the model straight from the Ant API as it does not give us all the information we need. However it is a good place to start. Fortunately Ant provides a task that will save us a lot of coding; in fact we will not have to access the Ant API at all. This is the ‘AntStructure’ task. It generates a DTD for Ant, containing information about all tasks known to Ant; an ideal place for us to start.

The first thing we need to do is to somehow convert this DTD into ordinary XML. To do this by hand would be incredibly slow and prone to introducing errors, so some form of automatic conversion is necessary. Luckily there exist programs that can perform this conversion for us; a very good XML editor in general is Stylus Studio[6]. Before the conversion can take place though, the Ant DTD must be slightly modified.

We only want all the tasks to appear once in the generated XML, but in the DTD they can be placed inside a target or a project element. So it was altered so they

only appear in targets. Next, tasks can also appear inside the ‘parallel’ and ‘sequential’ tasks; so these were altered so they do not accept other tasks. This all ensured we would only get one definition of each task in the generated XML. Stylus Studio then took the modified Ant DTD and converted it into XML. The basic structure of the file produced was a top-level ‘target’ node, containing all the tasks in Ant. The name of each element was the task name itself. These elements contained any tasks accepted by the parent task. This created another problem however. To avoid infinite recursion during conversion, the editor was instructed to only ever expand the first instance of a task it finds. For example a ‘fileset’ can contain a ‘patternset’, which in turn can contain another ‘patternset’. If these measures were not taken, the convertor would never stop. But this now meant that asking a task element what nested elements it accepts will not produce the desired result. Referring to my previous example, assume that ‘fileset’ is defined first in the XML file; ‘patternset’ has therefore been defined inside it. Now later on in the file we encounter another task element that accepts ‘patternset’. All we’ll get from it is that it accepts a ‘patternset’; not what a ‘patternset’ actually accepts. What’s more we cannot simply look back in the file for the information, as ‘patternset’ is not on the same level as the other tasks, its definition is hidden inside ‘fileset’.

4.4.2 Moving towards the finished model

Entities such as ‘patternset’ are known as types in Ant. Types are commonly used again and again in many different tasks, so it was decided these were important enough to have their own category in the model. This design decision would also help solve the previous problem we were having, as now references could be left in the places where the type is accepted (i.e. as nested elements in task elements) and we would know exactly where to look for the full definitions.

A Java program was created to perform the conversion from the XML version of the Ant DTD, to somehwere near the structure decided upon in the second iteration. The first step would be to extract all the types and place them in their own category at the top of the XML file. To do this we had to know the names of all the types. Fortunately there only exists a finite amount of them, so they were manually typed into an array. The program then iterated through all the elements in the file; if it hit a type for the first time then it was moved into the ‘Types’ category, else if it hit it again then a reference to the type was left in its place.

The program then took this transformed file and converted all the task and type elements into the structure agreed on. It did this by firstly creating a new ‘Task’ element with a ‘name’ attribute equal to the name of the element being converted e.g. <javac………..> became <Task name=”javac”……….>. This new element was then given nested ‘Required’ and ‘NotRequired’ elements, which could not be used at that time as there was no way to know which attributes would go where. Instead, every attribute in the original element was converted into an ‘Attribute’ element and nested inside the ‘Task’ element e.g. the attribute in <javac srcdir=””……..> became <Attribute name=”srcdir”…….>. Finally an ‘Accepts’ element was nested inside the new task element and the whole procedure repeated with all the nested elements the task accepted.

4.4.3 Frustrations with the Document Object Model

The XML being produced was starting to bear a resembelence to the structure defined in the second iteration, with one drawback that was being caused by using DOM to manipulate the XML. This was used to process the XML as the data being worked on currently did not conform to any DTD, which ruled out using SAX. The general purpose nature of DOM was appealing. It has strict rules on how an XML file is made up, turning the file into a tree like structure of nodes. If an element in the file contains text nested inside it, this is represented as a ‘text’ node inside an ‘element’ node in the DOM structure. However, as any XML element could potentially have text nested in it, DOM believes every single ‘element’ node must always have a ‘text’ node in it somewhere. This may seem like a trivial point; but when you are iterating through a DOM tree expecting every node to be an ‘element’, it causes many problems. After each mini-transformation, the result was stored in a new DOM tree. This was somehow turning these normally invisible text nodes into actual elements in the new tree! The solution was first thought to be simple; check the node types first of all, and if there were any ‘text’ nodes then delete them from the tree. But DOM tightly links these nodes to their parent ‘element’, so when a ‘text’ node is deleted DOM thinks the parent has been deleted to. After all, every node must have a ‘text’ node. So this solution did not work. Next it was proposed to investigate using the JDOM[7] classes instead, as they were tried and tested and claimed to make using DOM in Java much easier. However after downloading and trying JDOM it was found it suffered from the same problem; it was a DOM problem after all and JDOM doesn’t change how DOM is defined.

The way the problem was finally solved was to loop through the XML produced after each mini-transformation, copying it to another new DOM tree. If one of those rogue text elements were encountered, it was not copied across; leaving the DOM tree desired.

4.4.4 Completing a valid model

The state of the model was such that all the tasks were defined with their attribute definitions nested inside them. However whether they were required or optional was still not modelled. It was time for the manual work to begin, as the only way to determine whether an attribute was needed was to look it up in the task’s documentation in the Ant manual. So using a good XML editor, each task definition was looked at one by one, and its attribute definitions were moved inside either the ‘Required’ or ‘NotRequired’ elements within the task definition itself.

The final thing left to do to make the model valid was to group all the task definitions into their appropriate ‘Category’ element. The categories were created (the ‘Types’ category was already made by the conversion program if you remember) using the same groupings used in the Ant manual (‘Archiving’, ‘Filing’, etc). The task definitions were then placed accordingly; leaving a valid Ant Task Model, but not a complete one.

4.4.5 Putting the finishing touches to the model

The final thing left to do to the model was to fill in all the ‘condition’ attributes in the ‘Attribute’ elements. These would contain Boolean expressions that if evaluated to true, would mean the task’s attribute was required. After analysis there were discovered three potential scenarios these conditions would be needed:

When another specific attribute in the task was present/missing. When another specific attribute in the task had a certain value. When a certain nested element in the task was present/missing.

These potential incidents therefore had to be modelled by a simple but appropriate language. This was the language used (remembering that each statement had to evaluate to a Boolean value):

Rule ExampleIf a specific attribute must be present, then just write its name. otherAttIf a specific attribute must not be present, then write its name with an exclamation mark in front of it. !otherAtt

If a specific attribute must have a certain value, then write its name followed by an equals sign, then the required value. otherAtt=true

If a certain nested element must be present, then write its name with an asterix in front of it. *nestedElement

If a certain nested element must not be present, then write its name with an exclamation mark and an asterix in front of it. !*nestedElement

With this final touch the Ant Task Model was complete.

4.5 Iteration 4

Produce code that can query the Ant Task Model.

Now we had the Ant Task Model it was time to develop an API that could extract information from it. It had been ensured that the model was platform-independent so naturally following that it was believed the API should have that same independence. An OS-neutral programming language? It had to be Java.

ID RequirementAMM_4.1 The querying API shall be written in Java.AMM_4.2 The querying API shall be written in a way such that it could be easily

reimplemented by other developers.AMM_4.3 The querying API shall say which task categories are in the model.AMM_4.4 The querying API shall say which tasks belong to a specific category in

the model.AMM_4.5 The querying API shall say which types exist in the model.AMM_4.6 The querying API shall say which attributes a task/type accepts in the

model.

AMM_4.7 The querying API shall say whether an attribute is required or optional in the model.

AMM_4.8 The querying API shall say any conditions that make an attribute required in the model.

AMM_4.9 The querying API shall say which nested elements a task/type accepts in the model.

4.5.1 Identifying interfaces

Java is an object-oriented language, so it provides us with a nice way of constructing the querying API; by breaking it down into different objects with their own state and responsibilities. However before we do this, let’s take a moment to understand AMM_4.2. It exists because the developer is not arrogant enough to believe that his implementation of the querying API will be the most efficient; what’s more who can say what technological developments will happen in the future? Therefore instead of creating concrete classes we must first create and stick to interfaces that are not bound to any implementation. These interfaces are very easily identified by analysing requirements AMM_4.x as follows.

Explanation InterfaceEvery requirement in this group refers to the ‘model’ that is being queried. This is therefore a potential interface that will act as the actual entity being queried in Java.

AntInfo

‘Tasks’ are commonly referred to throughout the requirements so there must exist a representation of one. TaskDefinition

Similarly, ‘types’ are also referred to. TypeDefinition‘Attributes’ carry such complex information, such as conditions, that they must have their own representation. AttributeDefinition

There also exists one other interface that is needed by this package, but which cannot be derived from the requirements; and it stems from how the AntInfo object will be created. A simple approach would be to have a method that initialises the object itself. A better way however would be to use a ‘factory’ design pattern i.e. another class would be responsible for creating AntInfo objects. The major advantages of this are that implementations of AntInfo need not clog up the class with additional setup information; and the querying API is no longer bound to using the Ant Task Model. The two have been de-coupled! The factory class would therefore implement the AntInfoFactory interface.

The next step is to establish what exactly these interfaces needed to do; what methods they support. Once again this can be achieved by analysing the requirements.

Interface ResponsibilitiesAntInfoFactory Create an AntInfo object.AntInfo Know whether a TaskDefinition/TypeDefinition exists. Know

all the different categories. Know all the TaskDefinitions belonging to a specific category. Know a specific

TaskDefinition/TypeDefinition.TaskDefinition Know whether it’s deprecated. Know its name, the name of the

class implementing the task, and the category it belongs to. Know the TypeDefinitions and AttributeDefinitions accepted.

TypeDefinition Know whether it’s deprecated. Know its name, the name of the class implementing the type, and whether it’s a reference to a fuller definition in the ‘Types’ category. Know the TypeDefinitions and AttributeDefinitions accepted.

AttributeDefinition Know its name, whether it’s required, whether it has any conditions, and what those conditions are.

As you can see from figure 2, TaskDefinition and TypeDefinition extend the Definition interface. This is due to the fact they have many methods in common, as can be best seen from the previous interface/responsibilities table.

Figure 2: Interfaces in package antsnest.antinfo

4.5.2 The implementation

Now the package was mapped out, it was time to design the realisation of these interfaces; a default implementation. A default class was created for each interface, but as the interfaces generally only defined ‘get’ operations the classes aditionally provided the accompanying ‘set’ operation and included an instance variable to hold the piece of information in question. For example, DefaultAttributeDefinition included getName(), setName(), and a String variable called name. As Definition extracted similar functionality from TaskDefinition and TypeDefinition, it was only right that this had its own class; DefinitionBasics. The only thing of real complexity was DefaultAntInfoFactory, which had to create an AntInfo object from the Ant Task Model. The following walkthrough explains what happens when parseTaskModel() is called on the factory.

1. The factory is given the path to the Ant Task Model.2. The factory the model into a DOM tree.3. An empty information object is created.4. The ‘Types’ category element is located in the DOM tree.5. The first ‘Type’ element in the category is retrieved.6. A DefaultTypeDefinition object is created to hold information about

the type we have retrieved.7. The ‘Required’ element in the type is retrieved.8. If there are any ‘Attribute’ elements in it then they are processed into

AttributeDefinitions and added to the definition.9. The same process is applied to the ‘NotRequired’ element.10. The ‘Accepts’ element in the type is retrieved.11. If there are any ‘Type’ elements in it then they are processed exactly the same

as the current element is being processed, as the methods to do so were wrote with recursion in mind. The only difference is if the ‘Type’ element is empty it is presumed to be a reference, so its definition is marked as so.

12. Once the whole ‘Type’ element has been processed it is added to the AntInfo object (or its parent definition if appropriate).

13. The next ‘Type’ element is then processed.14. Once the whole ‘Types’ category has been processed, the task categories are

dealt with one by one.15. The first ‘Task’ element in the category is retrieved.16. A DefaultTaskDefinition object is created to hold information about

the task we have retrieved.17. It is then processed in exactly the same way as a ‘Type’ element would; the

recursive methods mentioned earlier take advantage of the fact that a task definition and a type definition both extend from Definition, so a single method can be used.

18. Once the whole ‘Task’ element has been processed it is added to the AntInfo object.

19. The rest of the ‘Task’ elements in the rest of the categories are then processed until the information object is complete.

Figure 3 summarises the whole parsing stage:

4.5.3 Resolving references

If a TypeDefinition turns out to be a reference then whenever the user queries that definition for its attributes, etc then it must somehow know its fuller version. DefaultTypeDefinition achieves this by holding a link to the

Figure 3: How the Ant Task Model is parsed

AntInfo object it belongs to; so whenever it is asked for the said information, it simply calls getType() with its own name and uses the returned TypeDefinition as if it was itself.

The final thing to say about the implementation and its interfaces is that they were grouped together in the package antsnest.antinfo.

4.5.4 Testing

All the basic data structure classes such as DefaultAttributeDefinition and DefaultTaskDefinition were tested using JUnit tests; ensuring that they were adding and removing their various sub-components correctly. The most important test involved systematically checking every item in the Ant Task Model was included in the AntInfo object returned from calling getAntInfo() on DefaultAntInfoFactory. As it did we could be assured that the object was complete in its knowledge. Tests were grouped into package testthenest.antsnest.antinfo.

4.6 Iteration 5

ID RequirementAMM_5.1 The querying API shall provide a way to add to the model.AMM_5.2 The querying API shall be able to create a definition of a user’s custom

task from its compiled Java code.

It is clear that requirement AMM_5.1 will satisfy AMM7; if a model can be added to them it is certainly extendable with the user’s own custom tasks. We have seen that the querying API mainly works with ‘definitions’ of items, so it would be helpful if we could pass one of these definitions to the API, and it then ammended the Ant Task Model so it contained the new definition. A quick and simple method must be created to do this; and the simplest way would be to take the user’s custom task (which we know will be written in Java) and generate a TaskDefinition from that. Fortunately the latest version of Java has introduced a technology that is perfect for achieving this; annotations.

4.6.1 Java Annotations

Java has for a while supported a constrained form of meta-data in the form of javadoc tags. However, only the javadoc program itself could parse these tags and make any use from them. Now with annotations, it is possible to properly mark up your java classes with meta-data (in a similar form to a javadoc tag) and use the reflection API to gather this information at runtime. These annotations could therefore be used to mark up a custom Ant task with the information needed by the Ant Task Model, such as required attributes, the name of the task, etc.

An annotation first has to be created for each category of information we wish to know; and in keeping with the Java tradition, these annotations are themselves classes:

Information Captured AnnotationThe name of the task. AntNameThe name of an attribute the task accepts, including whether it is required or not, and any conditions that make the attribute required.

AntAttribute

The names of any nested elements the task accepts. AntAcceptsThe name of any supertask the task extends. AntExtends

These annotation classes were created and stored in package antsnest.annotation.

4.6.2 Generating the definition

Class TaskClassScanner was created with the sole responsibility of generating a TaskDefinition from one of these annotated custom task classes. Here is what happens when the static method scan() is called:

1. The custom task’s Class is retrieved using reflection.2. The AntName annotation is retrieved from the Class, an

InvalidAntTaskException is thrown if one does not exist.3. Create the new DefaultTaskDefinition with the name contained in the

annotation, and belonging to the category ‘User-Defined’.4. Set the definition’s classname to that of it’s implementing Class.5. Check to see whether an AntExtends annotates the Class.

a. If it does then the TaskDefinition it refers to is retrieved from the model being used.

b. This definition’s accepted AttributeDefinitions and TypeDefinitions are copied to the new DefaultTaskDefinition.

6. Retrieve all the Methods that belong to the underlying Class.7. Check if any of these Methods are annotated with an AntAttribute.8. For those that are, create an AttributeDefinition from their annotation

and add these to the new DefaultTaskDefinition.9. Check to see whether an AntAccepts annotates the Class.

a. If it does, then for every element mentioned in it create a new TypeDefinition that has the same name as the element, and is a reference.

b. Add all these definitions to the new DefaultTaskDefinition.

Figure 4 illustrates the process:

Figure 4: How a user’s custom task is parsed into the Ant information object

Now we have the definition, it can be simply added to an AntInfo by calling addTask().

TaskClassScanner was tested by challenging it to scan a legally and an illegally marked up class. For the former it produced the desired TaskDefinition, the latter it threw the expected InvalidAntTaskException.

4.6.3 Making the custom definition persistent

As it stands right now, the custom task definition purely exists only in the AntInfo object in memory; when the garbage collector siezes that object then the definition will have been forgotten. It needs to be made persistent, and this concept has an effect on how AMM_5.1 is satisfied.

The Ant Task Model is a global entity; the way a default Ant task is defined on one person’s system is highly likely to be the same as one on another’s system. Thinking along the lines of a networked application using the model, this means there only ever needs to be one version of the model accessible by all users. But let’s consider this. A single user’s custom definition is highly likely to be different from another user’s. If they were to store it inside the global Ant Task Model then sooner or later it would be overwritten with the other person’s version. Custom task definitions are not unique for everyone. It is for this reason that they will be stored in a separate XML file, the ‘Ant Task Extension Model’. This file will be stored in the user’s home directory and the tasks contained inside it will belong to the category ‘User-Defined’. Now this decision has been made, we need a way of actually storing the user-defined definitions.

Once the TaskDefinition has been generated using the previous procedure, it is added to the AntInfo object containing the other definitions. Therefore they need to be extracted back out before being written out into XML. Class TaskExtModelOutputStream takes care of both these steps. It uses the Java XML transformation packages to create this output stream; a Transformer takes a Source and turns it into a Result, in this case a StreamResult. As specialist behaviour is required (i.e. extracting the custom definitions) then a SAXSource is the only viable option to use, and this requires a parser to pick out the bits of the AntInfo we want written. TaskExtensionModelParser takes the information object and does just this; it searches for the category ‘User-Defined’ and generates SAX events so the relevant definitions are written out to the Ant Task Extension Model file.

4.6.4 Ammending the AntInfoFactory

The final thing to note is that now there exists the Ant Task Extension Model, there now exists two different places the DefaultAntInfoFactory has to look for information. As the extension model obeyed the same DTD as the main model, the same recursive parsing code could be reused by the factory. A method, setTaskExtModel(), was added to DefaultAntInfoFactory so it knew the

location of the Ant Task Extension Model. After the main model had been processed, the extension model was read in and processed in exactly the same manner.

4.7 Evaluation

The Ant Task Model and its querying API, antsnest.antinfo, were produced precisely as intended. They both have many plus points, including:

The model is portable; one version of it can be understood on multiple platforms.

The model contains information that cannot otherwise be discovered at runtime; such as whether an attribute is required.

The model is easily extended with a user’s custom task definitions. The actual structure of the model could be extended without disrupting

existing users of it; the querying API only looks for the existence of certain XML tags, it doesn’t crash if it finds tags it was not expecting.

The querying API is based on a set of interfaces; it is quite reasonable for another developer to code a completely different implementation that doesn’t even use the model.

They could even create an AntInfoFactory that produced a partial AntInfo object, by using the introspection/reflection methods in the Ant API discussed earlier.

Looking from the other point of view, if a developer did not like the querying API, they could easily write their own as the model is in XML; which is now a pretty standard format.

However, it is just as (maybe even more) important to understand what is holding them back as well:

As there is no complete way of automatically creating the model at runtime, or compile-time for that matter, there would have to be a separate model made for each version of Ant.

There exists no way of testing whether the model reflects correct information apart from sitting down and comparing it with the Ant documentation; which itself is not complete.

But having identified these problems, a solution does spring to mind. If the annotation system introduced in this project were to be used as a standard to mark up all Ant task classes, including the default ones that ship with Ant, then the model would be able to be automatically produced. What’s more, they could also be used akin to javadoc to automatically create the relevant help documentation.

4.7.1 What the real world thought

The Ant Task Model was released on the SourceForge site, and was sent to the offcial Ant users mailing list for a real-life evaluation (Appendix B). This ended up provoking a heated online debate.

The first opinions received were advising the developer to simply use reflection to capture the desired information; no need for a model at all. A reply was sent back to the list outlining exactly why reflection was not good enough, as already discussed in this report. Then the comments started arriving from those with strong ties to Ant, and that’s when it started getting interesting. Following on from the reflection point of view, the next recommendation was to use the Ant introspection classes to extract the necessary information. Once again the reply argued why this was still not appropriate, along the same lines as the reflection argument. However a suggestion was made that could improve the whole antsnest.antinfo package. The procedure described in iteration 5 for registering a user’s custom task definition with the model relies on the user actually having to physically signal a class should be registered. It is separate from the way the class would be registered with Ant itself. The suggestion however, noted that at runtime it is possible to scan the classpath for antlib.xml resources, which contain the classnames of the user’s custom tasks; these could then be fed to TaskClassScanner. So that is an issue that will be looked at closely in the future.

The major disagreemment that arose from the mailing list was concerned with the use of Java annotations to mark up Ant task class files with meta-data. This was seen as ‘reinventing the wheel’ as the core task classes were already marked up with XDoclet tags. The idea of a model for Ant received very welcoming feedback overall, but why bother creating a whole new tagging system when one has already been used? The reply highlighted the following key points:

The author of the criticising email even conceded himself that these XDoclet tags “probably have not been kept up-to-date”; but that’s minor.

No tool vendor ever really picked up on the existence of these tags, so as such they have remained unused and made no impact; which is a great shame.

Java annotations are now an integral part of the Java API, whereas XDoclets require an external library.

The overall defence was that what the XDoclets and annotations are trying to achieve is nearly identical; but as the XDoclets were never adopted as an Ant standard and annotations do the job so tightly integrated with Java, annotations should be used from now on. This was a very thought provoking topic and it gave the developer a slight sense of achievement that he had managed to start it.

Finally came a highly respected source of backing for the model; from the Eclipse project[8]. Eclipse is more than a programming editor, it is a whole programming environment that is highly extendable with a whole assortment of plugins. The team lead for the Ant integration within Eclipse contacted the developer, enquiring about using the Ant Task Model and its querying API within the project. The idea was to use the model to help provide more Ant information to Eclipse’s build file plugin. They were also very interested in the annotation system, but could not currently use it as Eclipse did not support Java 1.5 (where annotations first arise). In general they were keen to gather the thoughts and opinions of the developer as he had obviously investigated the whole area.

5 Ant’s Nest – A GUI for Ant

As we showed in the introduction, the Ant build file editors currently available do not do enough to help the novice, or advanced, Ant user. This was attributed to the lack of an explicit Ant Meta-Model; so as one has just been created it would be a good demonstration of the model’s power to indeed develop a build file editor that uses it. That editor will be ‘Ant’s Nest’.

5.1 The requirements for an Ant build file editor

ID RequirementAN1 The editor shall provide a simpler, alternative way of editing an Ant build file.AN2 The editor shall be easily extendable with new ways of editing an Ant build

file.AN3 The editor shall provide a way to execute an Ant build file.AN4 The editor shall be easily extendable with new utilities that are concerned with

Ant build files.AN5 The editor shall provide a significant amount of help to users making an Ant

build file.AN6 The editor shall have a mechanism to integrate users’ own custom tasks.AN7 The editor shall provide a way to edit an Ant build file’s XML directly.

Figure 5: Ant’s Nest use cases

5.2 Iteration 1

Produce a data structure that represents an Ant build file.

Before we can start making the GUI there has to be some data structure that can be used to mimic an Ant build file, an internal representation. This structure would be the fundamental thing being edited by the GUI, so it must be simple enough to translate between it and the build file’s XML; and vice-versa. Looking ahead, any possible solutions to AN2 (extending the GUI with alternative ways of editing a build file) would need to communicate and provide conversions to this data structure so its design had to be well thought out and straightforward to use.

ID RequirementAN_1.1 The data structure shall represent an Ant build file.AN_1.2 The data structure shall be of a form such that conversion to and from XML

is straightforward.AN_1.3 The data structure shall have the potential to be extended.

5.2.1 Finding an appropriate structure

The first thoughts concerning the data structure were to directly use the structures employed in the Ant API. This would save a lot of time and would also help greatly towards satisfying AN3, executing the build file, as these data structures are already integrated with the mechanisms to execute the build. However, upon further investigation it was found these structures were overly complex for the task at hand (akin to cracking a nut with a sledgehammer), and if they were to be used then they would needed to have been extended to hide some of the complex behaviour. This would have ultimately defeated the main advantage of using them in the first place if they were to be manipulated.

There were good design hints to be taken away from the analysis though, mainly to do with how the Ant API’s structures sectioned a build file. They break it down into a main ‘project’ node containing ‘task’, ‘type’, and ‘target’ nodes (which in turn can contain more instances of ‘tasks’ and ‘types’). This got the developer thinking; where had he seen a good way to organise these nodes before? The DOM.

Instead of directly subtyping the DOM classes (it would have allowed behaviour not desired by the data structure, such as adding nodes in erroneous positions) it was decided to create the data structure based on it instead. The principle of DOM is that a tree is made up of parent nodes containing child nodes. There can exist specialist types of node but in the end they are still just nodes and are treated as such. This concept was carried straight over into our data structure; which was now going to be a tree with the following nodes:

Node Name DescriptionAntProject The root node of the tree that would represent the <project> tag in the

build file.AntTarget The node that would hold information about a <target> tag in the

build file.AntElement The node that would represent either a task tag (e.g. <javac>) or a

type tag (e.g. <fileset>) in the build file. The two have been merged into one kind of node as they become undistinguishable from each other the way they appear in a build file; types can appear where tasks can (e.g. at the target level) and tasks can appear inside other tasks (e.g. the ‘parallel’ task).

AntComment The node that would represent an XML comment in the build file.AntCData The node that would represent an XML CDATA section in the build

file.AntNodeText The node that would represent any text nested inside a node. This was

important as this is the form of data entry for some AntElement’s (e.g. ‘description’).

The main difference between our data structure and DOM is that DOM treats attributes of nodes as nodes themselves, whereas we do not.

5.2.2 Generating interfaces

Figure 6: Interfaces in package antsnest.datastructure

The different types of node identified could obviously become the interfaces for the datastructure package, as illustrated above. The Constants class is included as each AntNode knows its own type, which is a valuye from this class. The AntNode also contains generic things an element in a build file has, such as a description, a parent and nested text. Attribute/node addition, removal and movement are essential and are therefore also taken care of. The cloning of nodes and attributes has been included as it may become important to want to edit a version of the data structure without effecting any other users of it. The rest of the interfaces define the behaviour needed to manipulate and work with specific nodes; such as editing the ‘if’, ‘unless’ and ‘depends’ attributes of an AntTarget.

5.2.3 Assembly Rules

Even though there exists no solid DTD for an Ant build file, there do still exist rules governing which types of node another node can contain. They are as follows:

Node Type Cannot ContainAntProject AntProjectAntTarget AntProject

AntTargetAntElement AntProject

AntTargetAntComment Anything

AntCData AnythingAntNodeText Anything

These must therefore be enforced by the implementations of the data structure interfaces, throwing a CannotAddNodeException if needs be.

5.2.4 Is an attribute required?

If you recall, a problem with existing build file editors is that whether an attribute is required or not is unknown. The intelligence mechanism in DefaultAntAttribute, along with information gathered from the Ant Task Model, solves that problem in the form of class Condition.

A Condition is primed with two pieces of information: the name of the entity that the condition depends on, and whether this entity is a nested AntElement (if this is false then the entity must be an AntAttribute). In the example “!*fileset”, the name of the entity is “fileset” and it is a nested AntElement (as reflected by the asterix). The Condition is then given two more pieces of information: whether the entity in question must not be present/have a value, and if it should have a specific value (in the case of AntAttributes). Referring back to the example, the exclamation mark indicates the fileset must not be present. Conditions are created from the Ant Task Model as in the following diagram:

As we can see from figure 7, a collection of these Conditions are stored in a ConditionList; each DefaultAntAttribute has one. These lists turn out to play a fundamental part in assessing whether an attribute is required or not; as each attribute may have many conditions that make it mandatory e.g. the attributes in the ‘property’ task. This list needs to be updated with any changes occuring to the build file, just in case one of them effects a Condition. It therefore has method

Figure 7: How conditions are created from the Ant Task Model

updateConditions() which takes a ChangeEvent as a parameter. This event stores either the AntAttribute or AntElement that has changed, and whether it has been added to the build file or removed. From this event a Condition can calculate whether it has been met or not, as shown in figure 8:

When a ConditionList receives notification that a change has happened in the build file, it makes sure all its contained Conditions are updated. A DefaultAntAttribute is therefore required if and only if all the Conditions in its ConditionList are met. But how does the list know when a change has occurred in the build file?

First let’s limit the scope of the changes we are interested in. An attribute is only concerned with changes to other attributes or nested elements within its own parent node. It is therefore the responsibility of that parent node to alert all its attributes when a change occurs within it. A rather natural design pattern to use in this scenario was that of an ‘event-listener’ relationship between DefaultAntElement and DefaultAntAttribute, an instance of which is illustrated by figure 9

Figure 8: How an attribute moves between being required and optional

(noting that DefaultAntAttribute implements ChangeListener which specifies the method nodeChanged()):

The data structure and the other classes it uses are all grouped in package antsnest.datastructure.

5.2.5 Testing

This new data structure was extensively tested using the unit tests in package testthenest.antsnest.datastructure. They included testing that all the different types of AntNode were managing their attributes and nested nodes correctly, that a Condition was updating itself right, and that a DefaultAntElement was firing the right events when a change occurs to it.

5.3 Iteration 2

Produce I/O streams for Ant build files.

As a data structure for Ant’s Nest now exists, the next step is to make an input and an output stream that sits between the actual build file that is persistently stored, and our data structure version of it in memory.

Figure 9: How conditions get updated

ID RequirementAN_2.1 The input stream shall create an AntProject object from a build file.AN_2.2 The input stream shall create an AntNode object from a fragment of a build

file.AN_2.3 The output stream shall create a build file from an AntProject object.AN_2.4 The output stream shall create a fragment of a build file from an AntNode

object.

5.3.1 I/O interfaces

The first step as ever was to turn requirements AN_2.x into interfaces that would guide the development for the rest of this iteration. It was a simple transformation, giving us AntInputStream and AntOutputStream. Now to implement. As an AntProject is an AntNode, it was decided that the method public AntNode read() would cover both AN_2.1 and AN_2.2; whilst public void write(AntNode node, OutputStream stream) would satisfy both AN_2.3 and AN_2.4.

5.3.2 Reading in a build file

The main problem that had to be solved here was to convert XML into an AntNode. As the data structure was loosely based on a DOM tree, the first attempt at the read method tried to parse the XML into DOM, then convert the DOM tree into an AntNode. On first inspection it seemed to have worked perfectly; however upon closer analysis it became evident that the order of any XML attributes in the build file was not being maintained. Further investigation into this problem led to the DOM pages in the Java API documentation, which states for a NamedNodeMap:

“Note that NamedNodeMap does not inherit from NodeList; NamedNodeMaps are not maintained in any particular order. Objects contained in an object implementing

NamedNodeMap may also be accessed by an ordinal index, but this is simply to allow convenient enumeration of the contents of a NamedNodeMap, and does not imply that

the DOM specifies an order to these Nodes.” [9]

A DOM Node stores its attributes in a NamedNodeMap, and it was seen that the XML attributes were being rearranged into alphabetical order, over which the developer had no control. Ordering of attributes in a build file is important to the file’s creator so this ruled DOM out of the input process. This left SAX as the technology chosen to do the conversion. The benefits of this were that SAX works quicker than DOM and that there should only be one conversion going on; from the XML straight into an AntNode.

The way SAX parsing works is to walk its way sequentially through the XML, firing events when it encounters the start of an XML element, or the end of one, or an XML comment, and so on. The developer writes effectively a listener class that gets notified when these events occur, and acts appropriately. BuildFileHandler is

the class that carries out this role, and is naturally responsible for producing the new AntNode. The key points as to how the transformation takes place are as follows:

Whenever the start of an XML elelement is encountered its name is analysed to work out whether the element is an Ant project, target, or if it is any other name, then it must be an Ant task or type.

An appropriate AntNode is created for the XML element discovered and then pushed onto a Stack. This stack structure is used to maintain the order in which the XML document is being processed i.e. the current AntNode in scope can be found by popping the top of the stack.

If the new node being created is an AntElement then a lookup is done using the AntInfo object, to find out which attributes belong to the element. These are then added to the new AntElement and if the XML document has values for these attributes then they are copied.

The new AntNode is then added as a child to the node currently at the top of the stack.

The default way AntNodes are identified is through a unique ID number, managed through an IDPool object. Whenever a whole build file is being transformed, the new DefaultAntProject creates this pool and passes it down to any children added. These then pass it onto their children and so forth; so every AntNode in that project is ensured a unique ID. If however only a section of a build file is being transformed, the user of the handler must provide the IDPool object to be used instead.

Whenever the end of an XML element is encountered then processing must have finished on it, so its associate AntNode is popped off the top of the stack for good.

Whenever an XML comment is encountered then it is straightforwardly transformed into an AntComment and added to the AntNode currently at the top of the stack.

If the start of an XML CDATA section is hit, then the handler makes a note that it’s currently in the section. Then whenever character data is encountered from then on, it is stored in a variable private to the handler, identified as CDATA. Then when the end of the section comes the character data is turned into AntCData and added to the AntNode currently in scope.

If the handler is not in one of these sections and character data is found, then the data is simply added as nested text data to the AntNode at the top of the stack.

The transformed build file can then be retrieved by calling getAntNode() on the handler object.

5.3.3 Writing out a build file

The process of transforming an AntProject into an XML build file is essentially the opposite of how it was read into the data structure. Instead this time a custom parser (AntNodeParser) that implements XMLReader was used for the

conversion. Any AntAttributes in any AntNodes that do not have a value are ignored and not written out.

The DefaultAntOutputStream that used this process wrote out a technically correct build file, however it was just plain ugly and needed a little bit of formatting to make it easier to read for humans. Therefore before the build file was actually written out, it was first passed through AntBuildFileBeautifier to tidy up the XML. This basically involved:

1. Finding any XML elements that had nothing nested inside them, and reducing these to a single line that had the start tag explicitly ended with a ‘/’ at the end of it.

2. Spacing the XML elements appropriately, for example adding a blank line to separate targets.

Only after these modifications was the build file then written out.

5.3.4 Testing

Unit tests were produced in package testthenest.antsnest.io that ensure an AntProject is converted to XML in the manner we’d expect, that an XML build file is correctly transformed into an AntProject, and that the beautifier formats the rough XML output into the version we desire.

5.4 Iteration 3

Produce the editor’s extendable architecture.

This was a key goal of the editor as if there was to be any hope of encouraging other developers to produce their Ant-based views and tools for Ant’s Nest, then there had to exist a simple way to develop plugins.

ID RequirementAN_3.1 The architecture shall split the different ways of editing the data structure

into levels.AN_3.2 The architecture shall split the different build file utilities into levels. AN_3.3 Each level shall be an encapsulated entity, unaware of other levels.AN_3.4 Each level shall operate on the same AntProject object.AN_3.5 A level manager shall manage all the levels.AN_3.6 The level manager shall be able to load and unload levels dynamically.AN_3.7 Each level shall be provided with operations to achieve general tasks only

the main editor is capable of doing.AN_3.8 Each level shall be provided with a means to notify the editor when

something happens that may have implications for other levels.AN_3.9 Each level shall have a graphical representation.

These requirements give a solid foundation for how the architecture is to be designed, mainly through the introduction of levels. AN_3.2 and AN_3.3 actually aid AN_3.6 by treating both utilities and editing methods as the same kind of object, a Level. This is an interface that all plugins implement, allowing the editor a standard means of communication to and from them. Decisions were made as to what should actually be implemented by a Level.

5.4.1 The architecture design

As can be seen from figure 10, each Level has a unique ID so the LevelManager can efficiently organise and manage them. Utilities would have negative Ids whereas editing views would have positive ones. It also knows the name of the class that’s implementing the Level. When a Level is registered with the manager, it is persistently stored in a text file. Then whenever the editor is used again, the manager reads in this file, gets the class names, and uses Class.forName() to dynamically load the level’s class into the virtual machine. Finally newInstance() is called on the Class to create the Level. No prior knowledge of any Level implementations is therefore necessary. Any Level must also have procedures in place to perform a cut, copy, and paste; for whenever the AntProject/AntInfo has changed, and for when the Level is about to be shown/hidden. But how exactly is AN_3.9 satisfied?

Some of the operations defined in Level can have default implementations so LevelImpl does this. But to satisfy AN_3.9 it was decided a good idea to make

Figure 10: The classes and interfaces that comprise the editor’s architecture

this class extend JPanel. This way the plugin developer has a base to create their GUI on, and the panel can be inserted/removed within the editor at will. AN_3.8 is satisfied as there exists an entity that can transmit messages to all levels at once; LevelManager.

All that was left to satisfy now was AN_3.7. The utility object that would help provide all these globally scoped services would be of type ApplicationTasks. All Levels were given an instance of this type when they were first loaded up by the LevelManager and it gave them the power to do such things as: shut the whole editor down safely, make the editor work on a new project, load/save the currently worked on build file, get the Ant information object, get a user-input string after being prompted with a message, notify the editor that you have significantly changed the project and it is currently unsaved, ask the editor to perform cut, copy, paste operations in the current Level, and finally to display a URL in an external window.

This interface would be implemented in the main editor window, MasterFrame, which was a natural choice as it had access to pretty much everything in some form. It uses its instance of LevelManager to track what the current Level on show is and renders it in its frame. Whenver this is changed (via a drop-down list on the editor’s menu bar) the LevelManager is informed of the selected Level, MasterFrame removes the old Level’s panel from itself and adds that of the new one.

The drop-down list uses the toString() version of a Level to identify it. LevelImpl’s default behaviour is to concatenate the Level’s ID with what its description, as seen above. However this can be overridden by the actual implementation.

5.4.2 Correcting mistakes

Nobody’s perfect and it is inevitable that when editing a build file a mistake is made and it is necessary to go back to the state before the mistake was made. That’s why most applications these days have undo buttons. Ant’s Nest should be no different so UndoManager was created to oversee this process. Before it could be implemented though, it was essential to model (figure 11) what the developer’s view on undoing/redoing was:

If any edit is made the project has a past state it can go back to but no future state.

If all edits are undone then the project has no past state but definetely a future state.

If a redo/undo is done the project may have both a past and future state.

UndoManager uses a Stack each to maintain an AntProject’s past and future state, and a variable to hold its current state. The manager gets notified by

MasterFrame when the project has been modified, and this is when the current state is pushed onto the past stack and the new state stored as the current state. If an undo occurs, the manager pushes the current state onto the future stack, pops the top of the past stack and sets this as the new current state. If a redo occurs, the managers pushes the curent state onto the past stack, pops the top of the future stack and sets this as the new current state.

The only question now is how an AntProject’s state is represented. The first and rather naïve approach tried was to directly clone the AntProject and use that as its state. This method worked fine with small build files but when large (>500Kb) files were used the stacks quickly used up all the virtual machine’s

Figure 11: The undo model used by Ant’s Nest

memory. Thus an approach where the state was written to disk temporarily was needed. Whenever a state needs to be placed on any stack, the AntProject is serialized out to a temporary directory. The filename of the state is the time in milliseconds when the procedure takes place, to ensure uniqueness. The filename rather than the actual state is then stored on the stacks. Thus whenever a state is recalled from either stack, the filename is popped off and the state’s serialization read in to recover the AntProject. If a state is no longer needed then its serialized file is simply deleted, as are all of them when the program exits.

5.4.3 Copying and pasting

As already mentioned, a Level can not only perform cut, copy, and paste operations, but it can also be notified of them. Due to the fact that there are different levels doing different activities, including future levels that haven’t even been dreampt about yet, then there needs to exist a standard way of doing a simple copy and paste. It was decided that this way should involve passing/requesting a String to/from a Level whenever one of these actions is executed. This String should be build file XML, that way every single (and potential) Level can understand it and also produce it by using the Ant I/O streams already discussed in iteration 2. The major advantage of this method is that favoured ways of doing things in an existing build file can be copied into the clipboard from any bog-standard text editor, and then pasted straight into the project data structure in a Level. Vice-versa is also true. However copying and pasting will not be applicable for all Levels, so in this case if they provide null data when requested for a copy, the editor will take no further action.

5.4.4 Testing

The LevelImpl abstract class is tested in package testthenest.antsnest.level to ensure it behaves as expected, especially when being compared to other objects for equality and comparison (this is important for the GUI level selector). LevelManager is also tested to make sure levels are assigned appropriate ID’s based on whether they are an Ant utility or not. UndoManager is tested in testthenest.antsnest.undo. The unit test for this examines an undo and a redo, ensuring that firstly the correct state is retrieved, and secondly that side-effects of the operation are correct (such as any GUI components associated with performing an undo are disabled if there are no states to revert back to).

5.5 Iteration 4

Produce a technology for managing user’s preferences and the general configuration of the editor.

This was an obvious next step really as any editor with any worth these days allows its users to tailor the application to their satisfaction.

ID RequirementAN_4.1 The editor shall provide a means for levels to store preference information

for their users.AN_4.2 The editor shall use a startup manager to configure itself when it is started

up.AN_4.3 The editor shall know the path to the Ant Task Model.AN_4.4 The editor shall know the path to the Ant Task Extension Model.AN_4.5 The editor shall know the last level that was being viewed when it last shut

down.AN_4.6 The editor shall know the path of the last build file it was editing.AN_4.7 The editor shall know the paths to any Ant task documentation.

5.5.1 Properties

It can be seen that a solution to AN_4.1 would actually help satisfy AN_4.3 – AN_4.7. This is because each of these requirements can be seen as preference information, not for the user but for the actual editor. Therefore a way of satisfying AN_4.1 was tackled first, and this would be in the form of AntsNestProperties. This class was an extension of the Properties class in package java.util, as this already contained methods for saving and loading the properties to/from XML and for setting/removing your own properties. As long as the property the Level wanted to store could be reduced to a String then it could easily be stored by the global AntsNestProperties instance obtained by calling getProperties() from its ApplicationTasks object.

This subclass also provides methods for setting/getting the information desired by requirements AN_4.3 – AN_4.7. The path to the last build file being edited is always set by the editor whenever it loads a build file in, as is the classname of the last Level being viewed; set when the editor is shutdown.

5.5.2 The configuration manager

StartupManager is responsible for loading up the editor and providing it with the items it requires i.e. an AntsNestProperties and a LevelManager instance. But how does it know where or how to get these instances? This is where ConfigurationManager comes in. This manager class knows exactly where the files are that contain the properties and level information and generates objects of the correct type for StartupManager. If the required files cannot be located (e.g. when the editor is first used) then ConfigurationManager is able to create default objects that can be used instead.

Thinking ahead, a possible scenario of use for the editor could be across a network, for example at a university or company. Users would use the one location of the program, yet that would mean they would all have to share the same property and level information files. The fix to this, thus enabling true user customization of the editor, is to store these files in the user’s home directory and for

ConfigurationManager to look there when configuring the various objects. In Java this is relatively easy; as System.getProperty( “user.home” ) returns the home directory path. Now this one occurrence of the application can seem completely different between users; they can personalise any way allowed.

Finally it’s worth pointing out here that the editor makes extensive use of the ANT_HOME environment variable that should be set for any Ant installation. ConfigurationManager uses it to locate the paths to the various Ant task documentation and the program launch file overall uses it to add the Ant API to the application’s classpath. It is therefore a mandatory system requirement that this variable is set.

5.5.3 Testing

The AntsNestProperties class is unit tested in package testthenest.antsnest.configuration, making sure that the default property values (such as the location of the Ant Task Model) are set up correctly and that their integrit is maintained when saving and reloading.

5.6 Iteration 5

Produce a level where a build file’s XML can de directly edited.

Now the editor’s architecture has been developed and tested, all the tools and support are there for us to start making Levels. Developers have been writing their build files in text editors for so long that this is what they are immediately used to, and thus shouldn’t be deprived of; even if it is slow and mundane. There is also an argument that this kind of editing is still needed for cases where a small, specific change needs to be made quickly.

ID RequirementAN_5.1 The level shall provide a basic text editor to edit build file XML.AN_5.2 The level shall provide a graphical overview of the build file.AN_5.3 The graphical overview shall show all attributes accepted by an Ant entity.AN_5.4 The graphical overview shall show which attributes are required and

which are optional.AN_5.5 The graphical overview shall provide a data entry mechanism for

attributes.AN_5.6 The graphical overview shall allow Ant entities to be repositioned.AN_5.7 The graphical overview shall indicate which nested elements are accepted

by an Ant task or type.AN_5.8 The graphical overview shall allow the user to add comments and CDATA

sections to the build file.AN_5.9 The graphical overview shall set an attribute’s value to an Ant property’s

name if it is dropped on top of it.AN_5.10 The text editor shall provide an auto-complete mechanism that shows the

user possible strings that could be inserted into that point in a build file.

It can be seen that these requirements help satisfy higher level goals AN5 (as the graphical overview will provide help to the user through AN_5.3 – AN_5.10) and AN7 (via AN_5.1). This Level will be known as ‘level 0’ as it is the most basic form of editing a user can do.

5.6.1 The XML editor

As can be seen from figure 12, the XML editor within Level 0 is a very basic text editor in the fact that it allows a user to edit text and perform operations such as cut, copy, and paste. A KeyListener monitors the user’s typing and if at any stage a ‘>’ or an ‘enter’ is typed then the ApplicationTasks object is notified via projectChanged() and the graphical overview of the project is updated. At the same time the actual text in the editor is formatted and redrawn to screen, ensuring the cursor is still in the same typing place. Level 0 achieves this by taking the current AntProject being worked on, and feeding it through the DefaultAntOutputStream to get the XML version of the build file. It is then displayed in the text area.

Also noticeable in the above diagram is the auto-complete selection box. This can be ‘popped up’ at any time by pressing the ‘F1’ key. When the text editor detects this button press it passes to AutoCompleter a String starting where the last ‘<’

Figure 12: The text area where the build file XML is displayed and edited

is and ending where the cursor currently sits, and the AntInfo object. The process shown in figure 13 then populates the selection box with valid insertion choices:

The user then selects a choice from the list and it is inserted where the cursor currently lay.

5.6.2 The graphical overview

Before any work could begin on the graphical overview of the build file, a decision had to be made on how it would appear to the user. There were a few options available, such as different lists representing different levels in the XML hierarchy, or even a table. But the best structure overall was the expandable/retractable trees used by the likes of directory browsers in Microsoft Windows. These naturally suited the

Figure 13: How the auto-complete function works

tree-like structure of a build file and made very efficient use of the space it would have on screen.

As can be seen from figure 14, different font styles are used for various Ant entities, for example build file properties are shown in brown and comments are displayed in italics; helping the user visually navigate their build file easier. When one of these tree nodes is selected (like ‘pathelement’ in the diagram) then all its possible attributes are displayed in the box below the tree, allowing them to be edited. Required attributes are displayed in red i.e. ‘location’. But how does this all work, what’s going on behind the scenes?

Class BuildTree is the extension of JTree that represents this graphical component. Like any other component of a Level, the tree has access to the AntProject being edited via the ApplicationTasks object. What enables the tree to edit the AntProject so effectively is the fact that each AntNode in the project is held in a DefaultMutableTreeNode in the tree. This, combined with the way Java has call-by-reference semantics, means that as long as the programmer can get the TreeNode that was selected by the user, they can also get the reference to the AntNode it contains. In turn this means this AntNode can be directly edited and the changes will be reflected on a global scale; eliminating the need for long update algorithms.

Figure 14: The panel where the project can be manipulated graphically

BuildTree has a ProjectTreeListener attached to it which monitors mouse activity within it. More specifically if one of the nodes in the tree is double-clicked, getType() is called on it to find out whether it was either an AntComment or AntCData node. If it was then a text area is brought up to allow the user to edit the values of these nodes; as the JTextField for attribute editing is not appropriate due to its inability to handle new lines. If however the node selected was an AntElement, then a search for the task/type’s documentation is carried out. This is achieved by appending the element’s name to the end of each of the documentation paths returned by getAntDocPaths() (in AntsNestProperties), and discovering whether the new path actually exists. If it does then we must have found the element’s documentation, so it is then displayed in the simple HTMLViewer.

If one of the nodes in the tree is clicked only once, then that indicates the user wishes to edit that node via the attribute box at the bottom of the panel. In this case the listener tells the BuildTree to update the attributes being displayed in the AttributeList; by retrieving the AntNode held and getting references to its AntAttributes. As these are once again references, they can be edited directly and the changes reflected in every Level. The required attributes are identified by AttributeListRenderer and drawn in red, to bring them to the user’s attention. When one of these attributes is selected then its current value is displayed in the JTextField for editing; with the user pushing ‘enter’ to confirm their change.

Now we’ll move onto how the build file can be restructured using the BuildTree, in other words how data is transferred within the tree. Java Swing GUI components are able to share information via ‘drag and drop’ operations, and any component wishing to take advantage of this must define a TransferHandler. This is a class that amongst other things, instructs the GUI component how to wrap up the source object of the transfer for dispatch. This wrapper has to be an implementation of Transferable to be understood. There are a few kinds of object that can be dragged around the editor; on this Level an AntNode can be moved anywhere in the tree, or it can be dropped on an attribute (if it’s a ‘property’ AntElement then the name of the property is set as the attribute’s value). Their wrappers share some common functionality so they therefore have a common supertype, AntsNestTransferable. The transfer process is illustrated in figure 15:

There are two types of behaviour that can happen when an AntNode is dropped onto another. The default is for the dragged node to be moved inside the node that it was dropped onto. However sometimes it may be desired to move a node to a specific position. To do this the user holds down the ‘CTRL’ key when dragging the node, and it is inserted into the position of the node it was dropped on; with all other nodes shifted to make allowance. This is easily implemented by a KeyListener in BuildTree. The node construction rules discussed in iteration 1 ensure only valid drag and drops are made.

A user interface problem encountered with the tree came when using a custom component to render it. ProjectTreeRenderer makes JLabel representations of each node in the tree, however for some reason its dimensions are not dynamic i.e. they do not resize when the text inside them gets longer than what it was. Having looked for solutions to this problem, one cannot currently be found; so whenever a node in the tree changes like that, refresh() is called to rebuild the whole tree. This then introduced the problem of maintaining what nodes were expanded and

Figure 15: The events that can happen when project panel nodes are dragged and dropped

selected, as the whole tree was being built from scratch and the same TreeNode in our eyes would be seen as different from the Java VM’s perspective (different objects). Fortunately we did have a way of uniquely identifying each node, via the AntNode’s ID number. So the IDs of all the expanded nodes, along with any selected node, were stored in a Vector before the tree was rebuilt. Then an algorithm scanned through the tree, expanding any nodes with an ID in the Vector or selecting the previously selected one. It is acknowledged that this approach will slow down the application as build files get larger, however having tested it on files of around 500Kb in size, the lag was noticeable but not the end of the world. It will achieve its goal in the short term whilst a more suitable solution can be found to the original rendering problem.

Now onto satisfying AN_5.7 and AN_5.8, concerned with adding entities to the build file via the graphical overview. We have already seen something similar to this with the auto-complete function in the BuildTextArea, so why not learn from it? Screen space is quite valuable in our case as the application is an editor at the end of the day, so the best way to implement this feature is through a popup menu triggered by the user right-clicking on the node they wish to add to. Populating that menu with the valid addition choices is essentially the same as AutoCompleter, except this time the menu must hold TypeDefinitions rather than Strings. This is because instead of manipulating simple text like earlier, we are actually going to add an AntNode to the data structure. If one of these definitions is selected then the node to add must obviously be an AntElement, so a default implementation of one is created using the TypeDefinition and the appropriate constructor in DefaultAntElement. However the popup menu also contains the functionality to add a comment, CDATA section, nested text section, and a target to nodes, if allowed. It also allows the user to add their own task or attribute, by asking them for the name of the new entity (in turn using the ‘get a string’ methods provided by ApplicationTasks).

5.6.3 The active component

Another problem this level encounters is when a cut, copy or paste operation is performed by the user. There are two predominant components on this level that have very different ways of dealing with these operations, so how does the level know which one to take a copy from, or paste to? The solution to this problem is to use FocusListeners attached to the menu and toolbar buttons. When one of these is clicked, getOppositeComponent() on the FocusEvent is called to get the Component that was being used before the button selection. Then via ApplicationTasks, the Level can query what this component was and act appropriately.

5.6.4 Distributing space

As mentioned before, space is of the essence in an application like Ant’s Nest and it is important for the user to be able to redistribute the space between components as they desire. It is for this reason that Level 0 places the

BuildTextArea and the graphical overview on different sides of a JSplitPane. A user may mainly type their build files or they may prefer to make use of the Ant information encapsulated within BuildTree; it doesn’t matter as they can allocate the space manually. It also allows the user to correct any miscalculations by the Swing layout manager (which do happen).

5.7 Iteration 6

Produce a level that provides simpler ways of editing a build file than typing XML.

This is basically where the project has been aiming to get to, the Holy Grail. As mentioned time and time again, many Ant editors out there are glorified XML editors and there has to exist an easier way for both expert and novice Ant users alike. This Level will hopefully go some way to achieving that.

ID RequirementAN_6.1 The level shall allow a user to reproduce anything they could have done in

XML.AN_6.2 The level shall provide a graphical overview of the build file.AN_6.3 The level shall provide an information panel.AN_6.4 The information panel shall display all Ant tasks available to the user,

including the user’s own custom ones.AN_6.5 The information panel shall display the documentation for any selected Ant

task.AN_6.6 The level shall provide a way of constructing a build file from the Ant tasks

listed in the information panel.

It is clear that this combination of requirements, especially AN_6.6, will lead to a build file construction method that needn’t require a deep user knowledge of Ant tasks.

5.7.1 No need to reinvent the wheel

As soon as AN_6.2 was written a large smile came across the developer’s face as he realised the whole of the graphical overview code from the last iteration could be reused by this level. Due to the fact that it had been written in a modularised way, only really relying on the ApplicationTasks object that all Levels have, it could in theory slip neatly into any other Level. All the complex functionality such as the popup menu of possible nested elements, the repositioning of nodes and the editing of attributes; all self-contained by class ProjectPanel. This was a major boost as apart from cutting down on programming time, it inspired the way to satisfy AN_6.6, as will be explained later.

5.7.2 The information panel

As seen in figure 16, a JTabbedPane has been used to organise the Ant tasks into their appropriate categories, including a deprecated section, a section that lists all tasks in alphabetical order, and a section for the user’s own tasks (which cannot be seen on the diagram). This graphical component was chosen as it fits a lot of information into a constrained space, plus it is a natural way of viewing the contents of the Ant Task Model. The documentation viewer is a JEditorPane which allows the Level to find the documentation URL as in iteration 5, and feed it straight to the pane for display. This pane and the list of tasks are contained in the same panel (InformationPanel.InfoPanel), and every tab has its own instance of this panel, so there is a need for them all to be kept synchronised with what documentation they are displaying. This is achieved by maintaining a variable that keeps track of the name of the task currently being displayed, and using a ChangeListener on the tabbed pane. If another tab is selected, then the parent InformationPanel ensures the documentation viewer in the newly displayed InfoPanel shows the current task’s HTML page. The first attempt to solve this problem changed all the JEditorPanes on every tab. Even though it was easier to implement, it turned out to be a very slow solution so it was abandoned. As for the actual setup of the tabs and their categories, the following algorithm was used:

The InformationPanel gets all the category names contained within the Ant Task Model by calling getCategoryNames() on AntInfo.

Figure 16: The panel that contains Ant task information

For each of these categories, the TaskDefinitions belonging to them are retrieved using getTasks(categoryName) on AntInfo.

These definitions are passed to a new InfoPanel, where they are stored in the JList that is at the top of the panel.

The new panel is then added as a new tab to the JTabbedPane, with a tab name that matches the category name.

As the InfoPanel stores actual TaskDefinitions, and Java Swing components are capable of ‘drag and drop’ data transfer, the application is able to satisfy AN_6.6 through the reuse of BuildTree. If you recall, the tree used BuildTreeTransferHandler to manage any nodes dragged from it, or any dropped onto it. Well the handler can also accept drops containing TaskDefinitions, which DefinitionListTransferHandler (used by InfoPanel) knows how to wrap up in a drag. As the tree can locate where the drop occurred (see before) then a DefaultAntElement can be made from the Definition and added to the data structure.

Draft drawings of this level and the one in the previous iteration can be found in Appendix C. The final GUI layout was based on these.

5.8 Iteration 7

Produce a level that will execute an Ant build file.

This was a natural next step, as for any application that edits something that can be run, should be able to do the running. Else the user will become tired of forever having to switch back and forth between Ant’s Nest and the command line to execute their build. The whole point of Ant after all is to ease the development process!

ID RequirementAN_7.1 The level shall execute the default build file target automatically.AN_7.2 The level shall be able to execute any target within the build file.AN_7.3 The level shall tell the user when the execution has failed, and where.AN_7.4 The level shall inform the user of the progress of the execution.

It can be seen that all these requirements contribute to the satisfaction of AN3.

5.8.1 Using what is already available

The Level already has available to it the AntProject that is currently being edited, and we assume this is the representation of the build file they wish to execute. But the question is, what do they want to execute? To find this out, the level will have to offer a selection of targets from the build file to the user, and they must choose the one they want to run. An obvious way of doing this is through the use of a

JList that stored all the AntTargets in the data structure, which was the method chosen. This behaviour was encapsulated in RunnerProjectList, which carries out the task of displaying the targets when given an AntProject.

From figure 17 it can be seen that as well as listing all the targets available for execution, the list also includes the project name in green. If this is selected then the default target is executed.

5.8.2 Execution feedback

AN_7.3 and AN_7.4 desire that the user is provided with feedback about how the build is executing (this can be seen in the above diagram). But before we discuss how the feedback is provided, we must first understand how a build is executed.

Imagine this scenario. A user is editing their build file in Ant’s Nest but have yet to save it. This is not a mistake but they intentionally haven’t saved it for whatever reason. The approach used to execute the build involves having an XML version of the build saved to file. But we have to assume the user doesn’t want their current editing saved, so that rules out a straight save to the currently worked on file. So why not just save a copy to a temporary directory and execute that instead? This is also not possible as a build file works from the concept of a ‘base directory’ that its file paths are relative to. So if the build file is executed from a different directory, it is possible its targets will not execute properly. What Ant’s Nest chooses to do is to append the word “copy” to the beginning of the current filename, save a copy to that position

Figure 17: The build file execution level in Ant’s Nest

instead (using DefaultAntOutputStream and the current AntProject), perform the execution, then delete the copy.

The execution procedure makes extensive use of what is already available through the Ant API. This is why there must exist an XML build file, as the Ant API can execute it. The interactions between the various classes are shown in the figure 18.

Finally we can discuss how the execution feedback is implemented. When the ProjectExecutor is started, it calls executeTarget() on the Project it contains. Whilst the Project is executing, it fires events when the build has started or ended, when a target is started or ended, etc. Classes can register to be notified of these events by implementing BuildListener and adding themselves as such to the Project object. In the case of our Level, the text area (RunnerTextArea) acts as a listener and is therefore informed when one of these events occur. This system could be left as it is, ensuring it adds a line to the text area whenever it receives a messageLogged() call; after all it is providing the feedback to the user. However it could be made slightly better (and is) by using different fonts and colours

Figure 18: The steps involved in executing the build file

for the many kinds of message displayed; ensuring the user can quickly identify the feedback they are interested in.

To achieve this in Java, a simple JTextArea is not good enough as it doesn’t support multiple text styles. The more sophisticated JTextPane does however. It reduces the task to providing the text you wish to insert with where you want to insert it and in what style. So first things first, the constructor of RunnerTextArea creates and stores several styles in a HashMap for easy access. The styles are:

Style ID Descriptionbuild Used whenever a build is started or finished; a black and bold style.target Used whenever a target is started or finished; a plain, green style.task Used whenever a task is started or finished; a plain, brown style.error Used whenever an error occurs during task execution; a plain, red style.log Used for any other kind of message; a black and plain style.

Only messages with a priority level of Project.MSG_ERR or Project.MSG_INFO are displayed in the text area, as the other messages are deemed not necessary for the user to see (things like the jar files being used by Ant, etc). As for where the message is inserted in the text area, the end position can be found by calling getDocument().getLength().

The other option for the implementation of the text area would be to use HTML inside a JEditorPane. This was rejected though, as ensuring the HTML tags match up would be an added degree of complexity; and if other styles were to be added in the future the JEditorPane would not be as effective as the HashMap store.

The final thing left to say about the feedback text area is how GUI ‘freezing’ is avoided. If ProjectExecutor was not used, and the Project was instead executed from within the RunnerLevel itself, then the user would still get the execution feedback; just it would all be dumped on the screen when the execution has finished. This is because the GUI would have blocked whilst waiting for the execute() method to complete and return. ProjectExecutor is therefore a separate Thread that executes the build file whilst not blocking the GUI.

5.9 Evaluation

The developer believes Ant’s Nest is a fairly unique Ant GUI. This boils down to its extension mechanism – levels. Never before has there been an editor solely dedicated to Ant that allows other developers to create their own plugins and tools, and append them to the editor. The closest thing out there is the Eclipse IDE[8], but as already discussed in the introduction, its Ant support is currently not up to scratch. It’s good, don’t get me wrong, but as far as providing help to novice users, it’s lacking. The major plus for Ant’s Nest, as for any other extendable architecture, is that the application is no longer constrained by its developer’s mind. It’s not impossible to say

that in a year’s time someone may dream up a new and innovative way of editing an Ant build file; and the door is wide open to them to develop a plugin level for the editor. In fact, the data structures, I/O streams, and miscellaneous tasks already implemented by the editor should encourage a developer to write a level rather than starting from scratch.

Then we come to a very special level already provided by the editor, the ‘model’ level, so called due to the heavy use it makes of the Ant Task Model. This level is the result of much of the work in this project, and it does indeed combine it nicely. Any Ant user will benefit from its use. A novice user no longer has to have three or four windows open when writing their first builds; the tasks are all categorised and listed, their documentation is just a double-click away, and every attribute (required or not) is listed when the task is added to the project. But this added help does not slow down the expert user. The option to add your own custom tasks, the quick construction of a build file via drag ‘n’ drop and popup menus, and the ability to quickly see which attributes in a task are needed in fact aid this breed of user. To reiterate; this is largely thanks to the existence of an Ant Task Model. And what if the expert user finds it quicker to type their build files manually? Well they can just switch to the XML editing level; that’s another advantage of the editor.

But at the end of the day this is the developer’s viewpoint, and although a strong case has been made for Ant’s Nest, it is the end-users’ opinions that matter. So as with the Ant Task Model, Ant’s Nest was released and advertised to the Ant users’ mailing list for review (Appendix B). As always the feedback was greatly appreciated and vital for the editor’s progression. The first comment received was that the editor froze when loading in a large (700Kb) build file. As the editor had only been tested on relatively small builds since then, this problem uncovered scalability issues when industrial builds were loaded in. Upon further inspection it was found the problem was due to how AntNode IDs were being assigned, and that the algorithm for it was hardly linear. Also the BuildFileBeautifier used String concatenation rather than a StringBuffer, which caused a massive lag. Once corrected the large build loaded in fine and all subsequent tests were performed on the large files. Another problem found was that XML comments before the opening ‘project’ tag caused the editor to think the file was invaild. This was once again a problem only real use would’ve found so this review turned out to be highly valuable.

Apart from the problems found, there was also positive feedback for Ant’s Nest. Students on the Ant user list were especially keen to use the editor, as Ant is taught on all good computer science degree courses, so this led to the developer advertising Ant’s Nest to the main student mailing list in the UCL computer science department. Not only did they take a look at it but they actually used it to create, in some cases, their first ever build files. More experienced users commented on how easy the drag and drop had made the creation process.

The SourceForge statistics are also very encouraging for such a new project. As of the 7th of April 2005, the application had been downloaded 70 times and the home page viewed over 950 times. The project is also listed on the Google and Yahoo! Search engines, as well as being recommended by TestDriven.com[11] and TestingReflections[12]. Other web sites also keep the public up-to-date on the latest versions of Ant’s Nest, such as machine.zive.net[13] and Artima.com[14]. Plus

there’s the odd recommendation on people’s weblogs, such as in LookSmart’s Furl[15].

Finally it has to be confessed that Ant’s Nest was used to create Ant’s Nest. No that’s not a typo. The build file used to recompile, run, document, and test Ant’s Nest was itself edited and executed from within Ant’s Nest. It was used as a development tool even when it was being developed.

6 Ant Beans – A COTS feel for Ant

It is crystal clear that the ‘model’ level in Ant’s Nest provides an easy-to-use interface for creating and editing Ant build files, and that it takes advantage of the Ant Task Model to actually provide guidance to the user; rather than relying on them having existing Ant knowledge. In this respect the project has now solved the problems that were brought to light in the introduction. But we have to ask ourselves, can we think of an even simpler way to create and edit an Ant build file by using the Ant Task Model? The answer to that is yes, and it comes in the form of ‘Ant Beans’.

The need for a COTS option

The funny thing about Ant Beans is that they would never have even been dreampt of if Ant’s Nest and the model hadn’t been sent out to the Ant user’s mailing list for review. It was whilst the developer was monitoring this list for feedback on the project so far that he noticed just how many problems users have finding a particular way to do something with Ant, and that there always seems to be a developer who can solve said problem. In addition, some problems are quite common (especially for novice users) and the developer has to repeat the solution to the list. Then there’s the fact that the user still can’t fix their problem, as they cannot understand the developer’s reply. So all of this led to the thinking, what if these solutions could be encapsulated in component form? They could then be published publically and the user would be guaranteed their problem fixed; as they wouldn’t have to implement the solution. Ant therefore needs a ‘Components Off The Shelf’ option.

Aside from users with problems, who else could this idea benefit? ‘Ant-Contrib’[16] is a SourceForge project that produces new tasks for Ant; but they are not the only ones doing this, from individuals to big companies. These tasks can seem foreign to even an experienced user, as they are new after all. The producer of the new task wants it to be successful, and only they trully know the ins and outs of how it works, so what better way to package all this knowledge up than with an Ant Bean? Then there’s the problem we’ve all faced where we find we keep reusing the same code over and over again, for example, compiling. Why not create an Ant Bean that knows how to do this and use that from then on? Finally let’s not forget users that plain just have a favourite way of doing something; this way they can save it instead of having to rewite the same target over and over again.

Having said all this, it is important to remember that most times there is no generic solution to a problem, there must be at least one parameter that is specific to each user. An Ant Bean must therefore take this into account and have a mechanism for eliciting the information it needs from the user.

These use cases are shown in figure 19:

Java Beans

If we are talking COTS in Java then we’ve got to be talking about Java Beans[17]. This is Java’s technology that not only allows a component to be customized with external tools (as well as code), but also to store the component’s state persistently.

The other major advantage to Java Beans is just how easy they are to create. Any Java class is capable of being a bean and the concept is very simple; if you want the bean to have a feature that can be customized, then turn it into an instance variable and write public getter and setter methods for it. If the state is to be read-only, then just write the get method. If the variable is of a primitive type such as an int or char, then you need do no more. If however it is of a more complex type (such as another bean) then you must design a class that is capable of editing the variable.

Once all that is done, all that’s left to do is to bundle the beans up into a jar file. Then the file can be loaded into any bean GUI editor (known as a bean-box) and instances of the bean can be created and configured appropriately, then saved. The current Java Bean technology encodes the instance in XML, which means the serialization will be able to be understood across future Java versions. Any developer can then reload this instance back into their code using the Java Bean API and use it like any other object. It is mainly because of this that the technology is perfect for the Ant Bean concept, hence the name.

Figure 19: Ant Bean use cases

6.1 Requirements

The following table indicates the fundamental requirements of an Ant Bean:

ID RequirementAB1 The bean shall be a Java Bean.AB2 The bean shall encapsulate an Ant target.AB3 The bean shall be able to elicit the information it needs to configure itself from

the user.

6.2 Iteration 1

Design a class that represents an Ant Bean.

As we want an Ant Bean to be as simple and easy-to-use as possible, the class behind it should therefore not be that complex; so we should be able to satisfy all the main requirements in this iteration.

6.2.1 The bean is a target

Starting with AB2, we know that an Ant Bean is equivelant to an Ant build file target. Therefore, whatever a target needs to know, the bean must also know. As the class is going to be a Java Bean (AB1), we have our first set of states that need to be maintained; the target name and the target description. These are simply pieces of text so they are of type String in AntBean, with their respective getters and setters. An Ant target also has the ‘depends’, ‘if’ and ‘unless’ attributes but these will not be included in the bean as they would create dependencies between beans; which is not desired at this time. But what else does a target contain? Tasks of course!

The bean is a solution to a problem, equivelant to a target. Like any solution there has to be steps to it, in this case the tasks. These get performed in a sequential order, so the bean must know this order. But if the bean stored all the information about a task, such as what attributes it accepts, which nested elements it can hold, etc, then the bean will have a dramatic increase in state; leading to a much larger file size when serialized. This is where the Ant Task Model comes to our rescue. Given the name of a task, the model can tell us everything we need to know, therefore a bean only ever need know the names of the tasks that form the solution; and the order in which they are performed. An AntBean will thus have a List property that contains the task name Strings.

6.2.2 Customizing the bean

An AntBean now knows the tasks it has to carry out to solve the problem; but it doesn’t know the parameters needed for execution. A parameter can be thought

of as a value that can be set to one or more task attributes in the target. Class AntBeanProperty represents one of these parameters, and can be used in two ways. The first is as a default property the bean comes already set with. This is a parameter that is known at design time by the problem-solver and is not machine dependent; for the compiling example this could be the ‘includes’ attribute in a fileset as the bean designer would know only ‘**/*.java’ files should be used. The second way a property is used is to elicit the information it needs from the user. These are usually machine dependent things not known at design time, such as directories for files to be compiled to. Now the problem arises of how AntBeanProperty finds out this information.

The parameter object finds out the value it requires in the same way a normal human being would; it asks the user. What better way is there? AntBean therefore has a String property to hold the question that the user must answer. But what if the bean developer only wants a certain kind of parameter value, like from a certain set of possible answers? Well an AntBean also has a List property that can be filled with potential answers that the user will be shown when configuring the bean.

6.2.3 How to locate a task attribute

The final thing to talk about concerning an AntBean is how it knows what task attributes it is setting. It is not good enough to store just the name of the attribute as these are not unique amongst tasks, so some form of addressing scheme is required. We could invent our own one but there already exists a technology for referencing XML, and that is XPath[18]. The XPath Processor allows a user to query an XML document and retrieve a subset of it. The addressing scheme used by XPath is commonly used and well-defined, so instead of reinventing the wheel we’ll just use that instead. It may also benefit Ant Beans in the future as such a well-known standard is being used.

Of all the things you can specify with the XPath addressing scheme, we are only concerned with how XML attributes are referenced. The basic form of the address is:

/ task_name / nested_element_name / @attribute_name

The task name is essential and must be required. The nested element name is optional and is only included if the attribute belongs to a nested element in the task, e.g. a fileset. Finally the attribute name is always prepended with an ‘@’ symbol. Other valid forms of XPath address are possible, such as:

// @attribute_name

This refers to all the attributes called ‘attribute_name’ in every task in the target.

6.2.4 Bringing it all together

Figure 20 shows how the two main classes in package antsnest.antbeans are composed. As can be seen, the AntBean separates the two uses of AntBeanProperty into presets and properties, and the parameter class itself holds all the potential answers and the paths of the attributes that must be set to value. As AntBeanPropertys are concerned with eliciting information from the user, they should each have unique questions. This is therefore the way in which they are identified from each other, as implemented in equals(). The toString() method uses this identification tactic as well, returning the question.

6.2.5 Testing

Package testthenest.antsnest.antbeans contains unit tests for the main Ant Bean classes. These test the getter and setter methods of the classes, ensuring they are valid, working Java Beans.

6.3 Iteration 2

Produce a level for Ant’s Nest that is capable of creating and editing Ant Beans.

Now we have the Ant Bean technology at our fingertips, we obviously now need a way of making them; and this would be the perfect opportunity to demonstrate yet another Level for Ant’s Nest.

ID RequirementAB_2.1 The level shall be capable of gathering the information needed to create a

fully defined Ant Bean.

Figure 20: The two main classes of the Ant Bean concepts

AB_2.2 The level shall be able to save an Ant Bean.AB_2.3 The level shall be able to load in an Ant Bean for editing.AB_2.4 The level shall provide help with creating the XPath addresses needed to

identify the task names that make up the bean.AB_2.5 The level shall provide help with creating the XPath addresses needed to

identify the attributes that must be set by the bean.

These are very straightforward requirements, with the real complexity of the level coming from AB_2.4 and AB_2.5.

6.3.1 The layout

As can be seen from the screenshot in figure 21, the layout for the Ant Bean editor has been made very open so all the information about the bean can be seen. This is opposed to a wizard-like interface for creating beans as firstly, editing beans would be problematic, and secondly, it would not really fit in with the WYSIWIG feel of Ant’s Nest levels. With this layout the general AntBean details are displayed on the left hand side of the level, and the specific details of AntBeanPropertys shown on the right.

Whilst developing this Level, it was found that the JList graphical component wasn’t up to the tasks desired of it. In particular the procedures to see whether the list contains an object, to add/remove/update objects in the list, and for getting the objects in the list are not as simple and straightforward as they could be.

Figure 21: The layout of the Ant Bean Editor

So ObjectList (an extension of JList) was created to wrap this complex behaviour into a single method call for each task. Each of these methods basically sets a new ListModel for the list to use. The ObjectList also takes responsibility for listening for certain events and acting appropriately; for example whenever ‘delete’ is pressed the list will remove the selected object from itself.

6.3.2 Creating a bean

To create an AntBean in this Level, first enter the basic details of the name and description into the text fields. Then to get the task name entry dialog up, the user double-clicks anywhere in that vacinity. The dialog looks like figure 22:

The drop-down list is populated with all the tasks and types the Ant Task Model knows about (satisfying AB_2.4); prepended with a forward slash as these have to be XPath addresses remember. However the user is not restricted to having to select one of these, they can still type in their own task names. This is because the bean may currently be being developed on a system where the Ant Task-Extension Model does not contain the tasks needed. It is important to remember these task names must be entered in the order the tasks would appear in the Ant target.

Now we’ll discuss how AntBeanPropertys are created. First of all the bean developer must decide whether they want to create a parameter that must be set by themselves or by the end-user. If it’s the former then the developer must first click the ‘Preset Properties’ label, else if it’s the latter, they must click the ‘User Properties’ label. The AntBeanPanel has a flag that is set via these clicks, therefore knowing what list to add the next AntBeanProperty to. If a parameter already exists in these lists and it is selected, then it is sent to the AntBeanPropertyPanel; where its details are extracted and displayed for editing.

The editing of a parameter is also very simple. The associated question and the optional default value can be typed in as normal, and a potential answer can be added by double-clicking the ‘Answers’ label. By double-clicking the ‘Attribute Paths’ label, the dialog in figure 23 will be displayed to aid the user in specifying the attributes that must be set by this parameter (satisfying AB_2.5):

Figure 22: The task name entry dialog

The dialog automatically lists suggestions for the attribute addresses. It does this by retrieving the task names listed in AntBeanPanel and extracting out the last names in the paths i.e. the text following the last forward slash. It then iterates through these Strings and looks for a TaskDefinition or TypeDefinition from the AntInfo object. If it finds one it then creates an entry in the dropdown list for each AttributeDefinition contained in the parent Definition. Once again, the bean developer is free to edit or add their own attribute path.

Now the parameter details have been entered, the bean developer clicks the ‘Add’ button to append the parameter to the relevant list in AntBeanPanel. An AntBeanProperty is uniquely identified by its question, so if it already exists in the list then it will replace the old version. The bean can then be saved by clicking the ‘Save’ button, which then uses Java Beans’ own XMLEncoder to write the Ant Bean out. The ‘Edit’ button loads a bean in for editing, by using XMLDecoder.

6.4 Iteration 3

Enable the user to run an Ant Bean in Ant’s Nest.

The final thing left to do is to allow the user to benefit from the work done in the last two iterations and use Ant Beans. Ant’s Nest is the platform the runner will be made for, but should it be accessed via the menubar, or a whole Level in its own? The answer is actually straightforward. The whole point of an Ant Bean is that it can be used anywhere an Ant target can i.e. it should be able to appear in every level that edits the build file. A separate Level may be appealing if there were more wizard-like features in executing the bean, but for now there are not enough to warrant making the process so heavyweight.

6.4.1 How a bean is executed

AntBeanRunner is the class responsible for executing an AntBean and it works as follows:

Figure 23: The attribute entry dialog

1. The runner is activated by the user selecting ‘Use Ant Bean’ from the ‘Tools’ menu.

2. The current ApplicationTasks object is given to the runner so it can add the new target to the project when it is done.

3. The user is prompted to select the saved Ant Bean they wish to use from a file chooser dialog.

4. The AntBeanPropertys that the user must configure are extracted from the loaded AntBean.

5. Each of these parameters are displayed to the user one by one, soughting an answer to the question contained in the AntBeanProperty. If potential answers are available, these are also offered to the user.

6. The answers provided by the user complete the user-set AntBeanPropertys and conversion to an Ant target can finally begin.

7. A DefaultAntTarget is created with a name and description matching that of the AntBean.

8. The task names are retrieved from the bean, and for every one in turn, the following occurs.

a. The AntInfo object is queried to see if a Definition exists for the current task name.

b. If it finds one then a DefaultAntElement is created from it and added to the target, else the whole execution exits.

c. Both the preset and user-configured AntBeanPropertys are checked to see if they contain attribute paths that effect this AntElement.

d. If one does, then the relevant AntAttribute’s value is changed to whatever the answer is for that AntBeanProperty.

9. The target now complete, the runner gets the current AntProject being edited via the ApplicationTasks object, appends the target to the end of it, and informs all Levels the project has changed (once again via ApplicationTasks).

6.5 Evaluation

The idealogical goal at the beginning of this project was to develop a method of producing an Ant build file that did not require the user to have any knowledge of Apache’s Ant. Ant Beans achieve this beyond any shadow of a doubt. The end-user

Figure 24: Example Ant Bean question dialog

does not need to know any details of any tasks available in Ant, nor about the attributes they contain. The whole process has been simplified to answering questions.

There is however, currently a constraint with the Ant Bean specification produced in iteration 1. A bean cannot be produced that has multiples of the same task following each other. An example of a task like this is ‘manifest’, which accepts multiple nested ‘attribute’ elements. The current AntBean class doesn’t stop the bean developer from creating a task name structure like this; but Ant Bean runners will find it impossible to tell which attributes to set as the addressing scheme presumes only one instance of a task name is present (AntBeanRunner will set all the multiple tasks to be the same because of this). However this doesn’t mean the AntBeanProperty class needs to be changed in the future; just the attribute addressing scheme needs to be added to so a bean developer can reference a particular one of these multiple tasks.

As the development of Ant Beans came towards the end of the project, there was no time to actively publish them for acceptance testing on the Ant users’ mailing list like before. This was a regret as their opinion would have been highly sought, but this will happen in the near future.

7 Conclusions

A formal conclusion would be to discuss whether the project achieved its goals. To reiterate what these were:

Create a model of Ant.

Chapter 4 showcased how an XML model of the tasks Ant can perform was constructed. The Ant Task Model faithfully provides the same information that can be sought from various reflection techniques on the Apache Ant API, along with additional information that cannot. An example of this additional knowledge is whether an attribute in a task is required or not; something that any Ant user really needs to know. Due to the XML format of the model, its use is not limited to Java applications and its structure is easily extendable.

Also produced during these iterations was a Java API for accessing and loading the model. This package worked very well and was in no small part responsible for the successful outcome of both Ant’s Nest and Ant Beans. The API also allows for a second, user-scoped source of a task model, known as the Ant Task-Extension Model. This allows users to integrate their own Ant tasks into the model’s world. This was achieved through the marking up of the task’s Java source with annotations. As there is currently no standard for adding meta-data to Ant task files, it is suggested Java annotations are given serious consideration due to their tight binding with the language itself.

Produce a method of making an Ant build file that does not involve typing XML.

This goal was achieved through the creation of an Ant GUI, Ant’s Nest. A basic XML editor was included to allow for minor touching-up of the build file, but even that was helped by the Ant Task Model with the use of the auto-completer. A level was created that allowed the user to drag and drop their desired tasks onto a build tree, thus not having to type any XML. Everything that could be done by typing XML could be reproduced using the D ‘n’ D and through popup menus. Once again, this was all aided by the data structure holding the build file; which in turn owed a huge debt to the existence of the Ant Task Model.

Produce a method of constructing an Ant build file that does not require the user to have any knowledge of Ant.

In chapter 6 the concept of Ant Beans was introduced to the world. The way they encapsulated an experienced Ant user’s knowledge of how to achieve something will surely make them a success in the future. Fulfilling the goal, the end-user of the bean need not know how a target is composed, just simply answer the questions that appear in front of them. The whole task of creating a build file has been reduced considerably. And as we once again witnessed; the actual execution of an Ant Bean owes a huge debt to the Ant Task Model.

Conduct the project ‘open-source’.

Without a doubt this was the most enjoyable aspect of the project. There was a real sense of accomplishment as each iteration was produced and released to the website. Being able to help people all over the world and to see them taking an actual interest in what was being produced was extremely fulfilling. It was seen as a subgoal by the author to promote the use of Ant within his university and this was also achieved; because at the end of the day, being able to construct Ant build files is an incredibly important string on your bow.

Achievements aside, the developer learnt an incredible amount during the course of this project. New programming techniques like advanced DOM and SAX processing, the Ant API, dynamic class loading, and Java beans were learnt, as well as where they sometimes fault. Plus there were things to learn on the project management side, like licensing your code and how to deal with a real-life user base. All essential things the developer is grateful he has now experienced.

To summarise; the title of this project is “A Meta-Model for Ant – How it would open up new ways to create a build file”, and the author believes this has clearly been shown.

8 Bibliography

[1] http://ant.apache.org/

[2] http://ant.apache.org/mail.html

[3] http://www.apache.org/licenses/LICENSE-2.0

[4] http://www.sourceforge.net/

[5] http://www.cs.ucl.ac.uk/staff/W.Emmerich/lectures/3C05-03-04/USDP.pdf

[6] http://www.stylusstudio.com/

[7] http://www.jdom.org/

[8] http://www.eclipse.org/

[9] http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/NamedNodeMap.html

[10] Mike Clark. Pragmatic Project Automation. 2004.

[11] http://www.testdriven.com/modules/mylinks/singlelink.php?cid=27&lid=789

[12] http://www.testingreflections.com/node/view/1463?PHPSESSID=46c0f760e6fc3e0ec4e98936b4ad1aa8

[13] http://machine.zive.net/weblog/archives/02-01-2005_02-28-2005.html

[14] http://www.artima.com/forums/flat.jsp?forum=136&thread=88781

[15] http://www.furl.net/members/bumble/Imported%20Bookmarks

[16] http://ant-contrib.sourceforge.net/

[17] http://java.sun.com/products/javabeans/

[18] http://www.w3schools.com/xpath/default.asp

[19] http://xml.apache.org/xalan-j/

http://xml.apache.org/xalan-j/

http://www.w3schools.com/xpath/default.asp

http://java.sun.com/products/javabeans/

http://ant-contrib.sourceforge.net/

http://www.furl.net/members/bumble/Imported%20Bookmarks

http://www.artima.com/forums/flat.jsp?forum=136&thread=88781

http://machine.zive.net/weblog/archives/02-01-2005_02-28-2005.html

http://www.testingreflections.com/node/view/1463?PHPSESSID=46c0f760e6fc3e0ec4e98936b4ad1aa8

http://www.testdriven.com/modules/mylinks/singlelink.php?cid=27&lid=789

http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/NamedNodeMap.html

http://www.eclipse.org/

http://www.jdom.org/

http://www.stylusstudio.com/

http://www.cs.ucl.ac.uk/staff/W.Emmerich/lectures/3C05-03-04/USDP.pdf

http://www.sourceforge.net/

http://www.apache.org/licenses/LICENSE-2.0

http://ant.apache.org/mail.html

http://ant.apache.org/

Appendix A – Project Build File

<?xml version="1.0" encoding="UTF-8"?>

<project name="AntsNest" default="compile" basedir=".">

<property name="src" location="src"/> <property name="dest" location="build"/> <property name="api" location="website/api"/> <property name="test" location="src/testthenest"/> <property name="junitclasspath" location="c:\ProgramFiles\eclipse\plugins\org.junit_3.8.1\junit.jar"/> <property name="junitreports" location="website/tests"/> <property name="crc" location="website/crc"/> <property name="jgoodies" location="looks-1.2.2.jar"/> <property environment="env"/>

<target name="compile"> <delete> <fileset dir="${dest}" includes="**/*.class"/> </delete> <javac srcdir="${src}" destdir="${dest}"> <classpath> <pathelement location="${junitclasspath}"/> <pathelement location="${jgoodies}"/> <fileset dir="${env.ANT_HOME}/lib"> <include name="*.jar"/> </fileset> </classpath> <exclude name="**/*.dtd"/> <exclude name="**/*.jpg"/> <exclude name="**/*.xml"/> <exclude name="**/*.vsd"/> </javac> </target>

<target name="document" depends="compile"> <delete> <fileset dir="${api}"/> <fileset dir="${crc}" excludes="index.html"/> <fileset file="website/requirements.html"/> </delete> <javadoc destdir="${api}" author="true" stylesheetfile="website/stylesheet.css"> <fileset dir="${src}"> <exclude name="testthenest/**"/> <exclude name="**/*.dtd"/> <exclude name="**/*.xml"/> <exclude name="**/*.vsd"/> <exclude name="**/*.jpg"/> </fileset> <link href="http://java.sun.com/j2se/1.5.0/docs/api/"/> </javadoc> <xslt basedir="${src}" destdir="${crc}" style="CRC.xsl"> <include name="**/CRC-*.xml"/> </xslt> <move todir="${crc}" flatten="true"> <fileset dir="${crc}"> <include name="**/CRC-*.html"/> </fileset>

</move> <delete dir="${crc}/antsnest"/> <xslt basedir="${basedir}" destdir="website" style="docs/requirements.xsl"> <include name="docs/requirements.xml"/> </xslt> <move todir="website" flatten="true"> <fileset dir="website/docs"> <include name="requirements.html"/> </fileset> </move> <delete dir="website/docs"/> </target>

<target name="test" depends="compile"> <delete> <fileset dir="${junitreports}"/> </delete> <junit> <classpath> <pathelement location="${dest}"/> </classpath> <formatter type="brief" usefile="false"/> <formatter type="xml"/> <batchtest todir="${junitreports}"> <fileset dir="${dest}" includes="**/*Test.class"/> </batchtest> </junit> <junitreport> <fileset dir="${junitreports}"> <include name="TEST-*.xml"/> </fileset> <report format="frames" todir="${junitreports}"/> </junitreport> <delete> <fileset file="${junitreports}/stylesheet.css"/> </delete> <copy file="website/junit.css" tofile="${junitreports}/stylesheet.css"/> </target>

<target name="run" depends="compile"> <java classname="antsnest.configuration.StartupManager" classpath="${dest}" fork="true"> <classpath> <pathelement location="${dest}"/> <pathelement location="${jgoodies}"/> <fileset dir="${env.ANT_HOME}/lib"> <include name="*.jar"/> </fileset> <fileset dir="${env.JAVA_HOME}/lib"> <include name="*.jar"/> </fileset> </classpath> </java> </target>

<target name="distribute" depends="compile"> <delete file="antsnest.zip"/> <zip destfile="antsnest.zip"> <zipfileset dir="antmetamodel" excludes="basework/**" prefix="antsnest/antmetamodel"/> <zipfileset dir="src" excludes="testthenest/**" includes="**/*.java" prefix="antsnest/src"/> <zipfileset dir="images" prefix="antsnest/images"/>

Appendix B – Select E-mails

These cannot be shown as the permission of the authors has not been sought.

Appendix C – Level Design Drawings

Appendix D – An Example Ant Bean

The following is an example Ant Bean that would be common amongst university students; it always ensures a fresh version of Java classes is used before running the application.

General

Name: RunApp

Description: Runs the most up-to-date version of an application.

Task Names: /delete/delete/fileset/javac/java

Preset Parameters

Question: Should Ant fork into a separate JVM?

Value: true

Paths: /javac/@fork/java/@fork

User-set Parameters

Question: Where is the root of your source file hierarchy?

Paths: /javac/@srcdir

Question: Where would you like the compiled classes to go?

Paths: /delete/fileset/@dir/javac/@destdir

Question: What is the classpath needed for the application?

Paths: /javac/@classpath/java/@classpath

Question: What is the main class of the application?

mailto:/java/@classpath

mailto:/javac/@classpath

mailto:/javac/@destdir

mailto:/delete/fileset/@dir

mailto:/javac/@srcdir

mailto:/java/@fork

mailto:/javac/@fork

Paths: /java/@classname

mailto:/java/@classname

Appendix E – Test Result Summary Page

Appendix F – User Manual

Contents

StartingLoading and SavingLevelsLevel 0 (XML View)Level 1 (Model View)The Ant RunnerAnt BeansAdding Your Own TasksKnown Issues

Starting...

To start up Ant's Nest first change to the 'antsnest' directory on your command prompt/x-term. Then execute the command 'ant -f antsnestbuild.xml' and the program should start after a few seconds.

Loading and Saving

The 'open' and 'save' options you would expect to see are available on the 'file' menu and toolbar. You can also create a new project from here and perform 'undo' and 'redo' actions.

Levels

Ant's Nest is a pluggable application in the sense that other developers can create 'levels'. A level is a specialist view that allows an Ant build file to be edited. The application comes with two default levels. To change the level you are working in, select your desired one from the drop-down list.

Level 0 (XML View)

The first default level displays a tree view of the build file on the left, and the actual build file XML on the right.

The Build Tree

This always shows a 'Project' as the root of the tree, and this cannot be deleted. To delete any other node in the tree, select it then press the 'Del' key. To add a new type of node (e.g. a target) to an existing one (e.g. a project), right-click the existing node and select the new type of node from the popup menu. For 'task' nodes the menu will also contain the nested elements accepted by the task. To move a node so it is a child of another node, drag and drop it onto its new parent node. To place it in an exact position, hold the 'Ctrl' key down as you make the drop. To see the attributes of a node click on the node and the attribute list will fill up. To edit an attribute, first select it in the list, then edit it in the text field. Once satisfied push 'Enter' and the attribute will be changed. To move an attribute to another position, drag and drop it. To edit comments and CDATA sections, double-click them to bring up a more appropriate editor. When a node in the tree is copied, it is converted its equivalent XML and sent to the system clipboard. When a paste is performed, the data in the clipboard is converted from XML into a node, and added as a child to the currently selected node. Finally, if you double-click a task node then its documentation will open up in a separate window.

The XML Editor

This displays the XML that will be saved. Here you can manually add to and edit the build file to fine tune it. However, please note that the XML is formatted and beautified and will delete any bits of text that do not make sense in an Ant build file. Normal copying and pasting usage applies. An auto-complete function is also available by pressing 'F1' whilst in the angled-brackets of any Ant entity.

Level 1 (Model View)

The second default level is similar to the first, except it provides an information panel on the right now.

The Information Panel

Each tab in this panel contains a specific category of Ant tasks. By double-clicking on a task in the list, its documentation will appear in the documentation window. From here you can get a better understanding of the task, e.g. what the attributes mean. To add this task to the project, simply drag and drop it from the task list onto its new parent node in the build tree.

The Ant Runner

This level will run the Ant build file. On the left is a list of the project's targets. To run one, first select it then click 'Execute' on the main panel. To run the default target, select the project name, then 'Execute'. The build progress is output to the main panel.

Ant Beans

Ant's Nest is capable of creating and executing Ant Beans. These are Java Beans that are equivalent to an Ant target.

Creating an Ant Bean

The 'Ant Bean Editor' level is capable of creating and editing Ant Beans. As each target in a build file must have a name and an optional description, these can be entered here. By double-clicking the 'Task Names' label a dialog will appear to allow you to select the name of the task or type that make up the target. These names MUST be in the order they appear in the target and must be XPath addresses.

A target must have attributes so these are what's configured next. Some attributes you will want to preset yourself (like a 'java' task must fork), others you will want the user to set (such as the location of their java class files). Click the relevant label on the left hand panel then edit the bean parameter on the right hand side. A parameter MUST have a question for ID purposes. For user-configured parameters this is the question they will be asked when the bean is executed. By double-clicking the 'Answers' label, you can also provide potential answers to that question. Finally

the attributes that are to be set to whatever the value of the parameter is must be specified. You can do this by double-clicking the 'Attribute Paths' label and selecting the XPath addresses of the relevant task attributes. Once editing of the parameter is complete, click 'Add' to add it to the bean.

Once the bean has been set up, it can be saved by clicking 'Save'.

Executing an Ant Bean

To execute an Ant Bean in any level, select the option from the 'Tools' menu. Then select the saved bean and it will begin running, asking you questions about the information it needs to know. Once all the questions have been answered, the bean will be converted into a target and appended to the end of the currently open build file.

Adding Your Own Tasks

Ant's Nest can scan user-written tasks and add them to the Ant Task-Extension Model, so they can be used like any other task. To do this, select the option from the 'Tools' menu. You must then enter the fully qualified classname of the task you wish to add. This task must have been marked up with annotations from package 'antsnest.annotation' for it to be integrated into Ant's Nest.

Known Issues The editor does slow down slightly with very large (>500K) build files. When levels are changed, the project's state is recorded in the application's undo manager. If you try to exit or change project when the current one has not been saved, the dialog that appears does not have a cancel button.

Appendix G – Web Site Homepage

Appendix H – Original Project Plan

Name: Christopher Clohosy

Project Title: Ant’s Nest – A Graphical User Interface for Apache Ant

Supervisor: Dr Graham Roberts

Aim: To reduce the complexity and difficulty of producing an Ant build file.

Objectives: Develop a way of creating an Ant build file without typing XML.

Show which attributes in an Ant task are required.

Display useful information that will help users produce a build file.

Edit existing build files.

Create a way of offering helpful services that are powered by Ant.

Outcomes: A piece of software that reduces the complexity and difficulty of producing an Ant build file.

A model of the tasks in Ant and how they are made up.

An open source website that documents and explains how the system works.

Work Plan: Summer 2004 – Develop an XML model of the tasks available in Ant, including what attributes and nested elements they accept.

First term, first half – Create an API to read in and process the Ant Task Model.

Christmas 2004 – Released the first version of the application, which contains levels 0 (XML view) and 1 (model view).

Start of second term – Begun project report and have an annotation system in place so Ant’s Nest can incorporate users’ own tasks.

Second term, second half – Begun the services side of the project (level 2).

Supervisor Signature: ______________________________________

Appendix I – Interim Report

Name: Christopher Clohosy

Old ProjectTitle: Ant’s Nest – A GUI for Apache Ant.

Project Title: A Meta-Model for Ant – How it would open new ways of creating a build file.

Supervisor: Dr. Graham Roberts

Progress Made: Developed Ant Meta-Model.

Developed querying API for model.

Developed Ant’s Nest Editor.

Developed plug and play system for editor.

Done a quarter of the project report.

Began developing AntBeans.

Work To Do: Finish project report.

Finish developing AntBeans.

Supervisor’sSignature: _________________________________________________

Appendix J – Sample Code

This has been omitted from the public report as all the source code can be viewed from the project’s CVS repository.

project title - ant's nest - a gui for apache...

Documents