=================================================================================================================== SYNOPSIS: After a great deal of effort researching why the Visual Age for Java (VAJ) servlets distributed with the Ant VAJ tasks are not working I believe I have discovered the underlying problem. The true problem revolves around untested changes to the source code and fundamental misunderstandings of what the code is doing.
=================================================================================================================== APOLOGIES: Please understand that I am very thankful for the Ant VAJ task code and documentation that exist. Although the code has problems, it still provides a great deal of guidance. With that said, I am going to be brutally honest as to what I think has happened in the hope that the underlying organizational problem will be solved. =================================================================================================================== OVERVIEW OF THE ENVIRONMENT IN WHICH THE CODE MUST RUN: To understand the Ant VAJ tasks you must first understand the VAJ Remote Tool API (http://www7b.boulder.ibm.com/vajdoc/vahwebx.exe/en_US/vj32/Synch/13711/toolserv/concepts/cwtoolov.htm) as well as the VAJ Tool API (http://www7b.boulder.ibm.com/vajdoc/vahwebx.exe/en_US/vj32/Extract/0/toolint/ref/com.ibm.ivj.util.base.Package.html). IBM has provided a small embedded servlet engine that provides an identical interface to the standard servlet API. Although the interface is the same the classes are entirely different. (i.e. com.ibm.ivj.toolserver.servletclasses.servlet.http.HttpServlet rather than javax.servlet.http.HttpServlet). By writing a servlet for this embedded servlet engine one achieves the ability to externally access the workspace of a running VAJ IDE instance. Within this servlet one can do whatever is necessary including accessing the VAJ Tool API. Unfortunately using the VAJ Remote Tool API seems to be the only way to obtain external access to a VAJ Envy repository. Worse yet this means pushing an IDE instance just to do so. This is bad, but it is the way it is and we must live with it. A very important issue is that making use of the VAJ Remote Tool API is a bit awkward and so far the error messages it returns are fairly cryptic. The secret to successfully using the Remote Tool API is to keep down the dependencies of the servlets created. This is particularly important when it comes to installing them. Any remote client code can be as complex as needed with as many dependencies as necessary, its simply code that runs inside the embedded servlet engine that is tricky. As should be evident by now, properly testing the VAJ Remote Tool servlets without a copy of VAJ is difficult if not impossible. =================================================================================================================== THE EVIL THAT NOW EXISTS: 1) The code has been edited by someone who obviously did not take the time to understand it and the environment in which it must run. Evidence: The imports of the following classes: import com.ibm.ivj.toolserver.servletclasses.servlet.http.HttpServlet; import com.ibm.ivj.toolserver.servletclasses.servlet.http.HttpServletRequest; import com.ibm.ivj.toolserver.servletclasses.servlet.http.HttpServletResponse; import com.ibm.ivj.toolserver.servletclasses.servlet.ServletException; have been changed to: import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import javax.servlet.ServletException; in org.apache.tools.ant.taskdefs.optional.ide.VAJToolsServlet. (See the above explanation of the embedded servlet engine if you don't see why this is wrong.) 2) The code changes to the VAJ Ant tasks were not even halfway tested. Evidence: The problems created by the mistake listed as evil #1 would have been detected. 3) In an effort to bring the VAJ Ant task code up to the Jakarta coding standards the tool server servlets contain more and more dependencies on the Ant libraries. As mentioned previously this would generally be ok except for the difficulties involved in deploying servlets in the embedded servlet engine. I attribute this mistake to evil #1 and #2. Evidence A: JDepend now provides a much longer list of dependencies for the VAJ Ant tasks than is seen in the VAJ Ant documentation. Evidence B: The org.apache.tools.ant.taskdefs.optional.ide.VAJToolsServlet class has been changed to use the StringUtils class in ant. 4) The install procedures provided in the VAJ Ant task documentation is no longer adequate due to evil #3. Evidence: The fact I am having problems. I am sure much more evidence for each evil can be provided, but what is given should be adequate proof. =================================================================================================================== SOLUTIONS: 1) Separate the VAJ Ant Remote Tool API servlets and the classes it depends on from the rest of the Ant VAJ tasks. This should make the install go much more smoothly. This could probably be accomplished by creating a special target in the ant build file. 2) Avoid as many dependencies as possible in the VAJ Ant Remote Tool API servlets. 3) Test any changes to the Ant VAJ tasks. Although awkward it should be possible to write junit tests for this nastiness. I realize this means keeping a version of VAJ around. 4) Understand the code and the environment it must run in before blindly changing it. =================================================================================================================== THANKS: Thank you for your time and consideration in reading this rather long and accusatory posting. James Lee Carpenter Software Engineer Household Technical Services 858-609-2461 [EMAIL PROTECTED] -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
