This application note pertains to Mr Architecture 3.0, unless otherwise stated. This note was last updated on 8th April 2005 to add this line. How to Obtain the Mr Architecture Sources Mr Architecture exists in two repositories. One in DPIWE, and one at SourceForge. The primary repository (at DPIWE) is the machine dove within /usr/local/cvsroot. This repository is maintained by CVS, the Concurrent Version System, which listens via the pserver protocol on port 2401. The connection string is therefore something like: :pserver:khansson@dove:/usr/local/cvsroot Only users of the machine dove can access the repository for reading. Additionally, developers and contractors may be able to submit changes. The secondary repository (at SourceForge) is the machine(s) cvs.sourceforge.net within /cvsroot/dpiwe-mr. This repository is maintained by CVS, the Concurrent Version System, which listens via the pserver protocol on port 2401. The connection string is therefore something like: :pserver:anonymous@cvs.sourceforge.net:/cvsroot/dpiwe-mr Anybody can access the repository for reading. To submit changes, you will need to be a project developer and you will have to use the ext method for secure shell access: secure shell is port 22. The connection string will look something like: :ext:mrkade@cvs.sourceforge.net:/cvsroot/dpiwe-mr The command for retrieving the Mr Architecture module will look like: cvs -z3 -d checkout -P mr You will need to have CVS installed on your system (and somewhere on your executable path) for this to work. Also, to define the ext method you will need to use something like: export CVS_RSH=ssh This sets the CVS_RSH system variable to the value "ssh". *Set CVS_RSH SSh would do in RISC OS. The repository at SourceForge currently lags the one at DPIWE. So if you are within DPIWE, go to dove by preference. Mr Architecture Platform and Dependencies The primary component of Mr Architecture is a Servlet, the CommandServlet. Mr Architecture is deployed on the servers and clients in which it runs. Clients are not expected to run the servlet: instead they run a ClientContainer which talks to a remote CommandServlet. Mr Architecture runs under J2SE 1.4 at a minimum, but versions before 3.0 require an implementation of a Servlet container as well (Jakarta Tomcat is used at DPIWE.) It is also recommended that Mr Architecture 3.0 be run using a third-party Servlet container, because the internal implementation is simplistic, and like all Mr Architecture, not fully compliant with the J2EE Specification. Mr Architecture is based on EJB 2.1 and Servlets 2.4, which are part of Sun Microsystems J2EE Specification, version 1.4. It has been successfully built and executed against both J2EE 1.3 and J2EE 1.4, and is currently built and executed against the latter. A suitable j2ee.jar downloaded from http://java.sun.com/j2ee/ will suffice for building. Execution of Mr Architecture on the server side will additionally require a JDBC driver for your chosen database. Currently only Oracle and Derby are supported databases, but at the time of writing Derby is not tested. Derby is the Apache open source incubator project for IBM DB2 Cloudscape. Building Mr Architecture Note: Building Mr Architecture requires mr.jar. This is because Mr Architecture uses Mr Architecture tools from the au.gov.tas.dpiwe.mr.tool package to simplify the build process. If you manage to break a critical tool, you will have to forcibly revert to a known good mr.jar to get yourself out of trouble. You've been warned. Mr Architecture is currently built by the machine kadeh from sources in the directory /home/khansson/Dove/MrArchitecture. The base of the sources is the subdirectory source and the base of the compiled classes is the subdirectory object. Some additional resource files are kept in object, so it is not advisable to wipe out these directories before performing the build. There are two scripts to build the Architecture. One is makea.sh, which builds the sources as they stand. And the other is makea2.sh, which does a redeployment of the current test beans within the Architecture as well. Redeployment is, of course, carried out by the DeploymentTool, which CodeStripper and CodeUnstripper sort out some chicken and egg problems. See Application Note #6. Batch file equivalents for Windows operating systems are maintained by the BatchFileCreator tool. All these scripts and batch files are kept in the source directory. Currently ANT scripts are not used, but feel free to make some. Building API Documentation for Mr Architecture The javadocs for Mr Architecture are built with the script docsa.sh in the source directory. DocsA.bat is the Windows equivalent. Jarring Mr Architecture Mr Architecture is jarred by the machine kadeh from compiled classes and resource files in the directory object. The script makemrjar.sh produces a signed jar using the DPIWE code signing key. You may store the password in the file passwd. If you don't have the password, you will need to use the script makemrjar2.sh, which produces an unsigned jar. Both scripts have batch file equivalents. Distributing Mr Architecture Internally Mr Architecture is used by the Ms Architecture extension, so its jar is typically distributed to the directory where that is built. (That is currently /home/khansson/Projects/ms in the subdirectory lib on kadeh.) On kadeh, Mr Architecture is also stored in the DPIWE jar library and the distribution copy of same. (Paths are /home/khansson/Work/Program/DPIWE/lib and /home/khansson/Projects/lib respectively.) Mr Architecture is sometimes also installed as a system extension. In this case, its jar should also be distributed to the lib/ext subdirectory of your Java runtime. (Because kadeh is the build machine, it is not installed as a system extension on that machine.) Updating Mr Architecture for External Distribution The distribution sources and resource files for Mr Architecture are kept separate from the build sources and resource files for historical reasons. There is a script on kadeh in the directory /home/khansson/Library called updatemr.sh which refreshes the distribution sources from the build sources. The build sources, as we have seen, are kept in /home/khansson/Dove/MrArchitecture, while the distribution sources are kept in /home/khansson/Projects/mr. /home/khansson/Projects is the home of all checked-out CVS modules on kadeh. The tool MultiCopy is used to perform the update. Adding New Source Files to Mr Architecture If you create a new package, source file or resource file, there are a couple of housekeeping tasks needed at the external distribution stage. There is no need to modify any build script manually unless the source file is part of a new test bean type. (In that case, you will need to alter the appropriate ContainerFactory. Similar problems arise if you have to add a new ContainerFactory: you will have to change makea2.sh.) 1. The package directory, source file or resource file needs to be added to cvs using cvs add. 2. The javadocs should be rebuilt. 3. The new docs need to be added to cvs using cvs add. You can thank the MultiEnumDir tool for keeping this simple, stupid. However, Windows users should read on to the next section. Adding New Packages to Mr Architecture For a new package, you should create a new package.html file in the source directory containing a HTML fragment which describes the new package. See package.html in source/au/gov/tas/dpiwe/mr for a template. Note for Windows users: Because Windows' command line does not support backtick command insertions in batch files (or anywhere else,) you will need to run the BatchFileCreator tool over the source and object directories to generate appropriate batch files for Windows which explicitly list the new packages. Migrating Checked-out Sources from a Windows OS to a UNIX-like OS The tool SourceFileRewriter will rewrite all source files and batch files into UNIX equivalents. You should delete any batch files which are themselves derived from shell files by BatchFileCreator, or otherwise you will impair their functionality. This includes MakeA.bat, MakeA2.bat, DocsA.bat, MakeMrJar.bat, MakeMrJar2.bat and DistributeMr.bat.