Project bcool standards document

Project BCOOL Standards Document


DoTheSimplestThingThatCouldPossiblyWork

Confidential Page 1 of 16 4/10/2023

http://www.c2.com/cgi/wiki?DoTheSimplestThingThatCouldPossiblyWork


Table of Contents1. ENGINEERING STANDARDS................................................................................................................................. 3

1.1 BASELINE STANDARDS...................................................................................................................................... 31.1.1 Basic “Image”............................................................................................................................................ 31.1.2 Source Control + Defect/Feature Tracking on LOKI...............................................................................31.1.3 Java 2 Platform.......................................................................................................................................... 3

1.2 TOOLSET........................................................................................................................................................... 31.2.1 Java Technology....................................................................................................................................... 31.2.2 XML tools for Java..................................................................................................................................... 31.2.3 OOAD/Schema Design.............................................................................................................................. 31.2.4 Microsoft Java........................................................................................................................................... 31.2.5 Life Cycle tools (for each iteration)..........................................................................................................3

1.3 CODING STANDARDS......................................................................................................................................... 41.3.1 Java Coding Standard............................................................................................................................... 41.3.2 Java Source Code Beautifier....................................................................................................................41.3.3 C++ Coding Standard................................................................................................................................ 4

1.4 QA & TESTING STANDARDS............................................................................................................................... 41.4.1 Unit Testing Standards............................................................................................................................. 41.4.2 Use Case (Scenario) Testing Standards..................................................................................................41.4.3 Load Testing & Performance Testing Standards....................................................................................41.4.4 Regression Testing Standards.................................................................................................................4

1.5 VERSION CONTROL............................................................................................................................................ 51.5.1 UmlModel- Model database...................................................................................................................... 51.5.2 Codebase- Code database........................................................................................................................ 51.5.3 Docs- Document database........................................................................................................................ 5

1.6 USING IBM VISUALAGE FOR JAVA..................................................................................................................... 61.6.1 VAJ with EJB/JSP support....................................................................................................................... 61.6.2 VAJ with SAP R/3 support........................................................................................................................ 61.6.3 VAJ with VSS............................................................................................................................................. 7

1.7 LABELING THE BUILD FROM COMMAND-LINE INTO VSS “CODEBASE”...................................................................81.8 PROPOSED BUILD CONFIGURATION INFRASTRUCTURE: HARDWARE & SOFTWARE.................................................9

1.8.1 Nightly Build on Build Machine................................................................................................................91.8.2 Nightly Deployment on Development Server (Stage I)...........................................................................91.8.3 Weekly Deployment on Staging Server (Stage II)...................................................................................91.8.4 Milestone Deployment on Demo/Mirror Servers (Stage III)..................................................................101.8.5 Making the build on Development Servers...........................................................................................10

1.9 DEPLOYING THE BCOOL APPLICATION FROM THE BUILD MACHINE....................................................................131.10 WHAT IF THE BUILD IS “BROKEN”?.................................................................................................................. 131.11 INSTALLATION PROCESS FOR DEMOS................................................................................................................13

1.11.1 InstallAnywhere Standard Edition API..............................................................................................131.12 TESTING THE BUILD FOR DEMOS....................................................................................................................... 13

2 REFERENCE WEBSITES...................................................................................................................................... 14

2.1 Issues............................................................................................................................................................ 14

Table of figuresFigure 1: The BCOOL hierarchy of java packages should look like combination of these two...............................5Figure 2: SAP R/3 support in VAJ Enterprise...............................................................................................................6Figure 3: Connecting VAJ with VSS “codebase”.........................................................................................................7Figure 4: Defining/changing the VSS connection from VAJ.......................................................................................7Figure 5: Adding VAJ files to VSS "codebase"............................................................................................................8Figure 6: Proposed Build configuration infrastructures.............................................................................................9Figure 7: The results of running Ant build tool from command-line........................................................................10Figure 8: Setting ant.Main properties after importing and versioning Ant and JAXP.............................................11Figure 9: The results of running build.xml in VisualAge for Java............................................................................12Figure 10: Bristlecone Software Development Process Model.................................................................................13



1. Engineering StandardsThe proposed engineering standards and toolset for the BCOOL project are as follows:

1.1 Baseline StandardsBaseline Standards w/ Version Development PC Dev/Staging Servers Demo Servers Demo Client

1.1.1 Basic “Image”Operating System v4.0SP6/2000 NT2000 Pro NT2k Server NT2k Server Win95/98/2kBrowsers (HTML4.0 compliant) IE 5.xx IE5, IE5.5 IE5.5 IE5.5Web Server (HTTP1.1 complaint) MS Personal Web Server IIS Server IIS NONEDatabase (SQL-92/3.0 compliant) Connect to database server SQL Server 7.0 SQL Server 7.0 NONEB2B XML Server (XML 1.0 based) NONE BizTalk Server BizTalk Server NONEPersonalization Engine (MS DB 2.1) File-system SQL Server SQL Server NONEVisualization Engine (2.0.3) InXight InXight InXight NONEOptimization Engine(ILOG OPL 3.1) OPLCOM API OPLCOM API OPLCOM API NONERules Engine (ILOG JRules) ILOG JRules (optional) (optional) NONE

1.1.2 Source Control + Defect/Feature Tracking on LOKIVSS v6.0 SCCS API client VSS Server NONE NONEClearQuest v2001 client for vss, or web version CQ Server NONE NONE

1.1.3 Java 2 PlatformJava 2 Standard Edition v1.2.2 IBM JDK 1.2.2 IBM JDK 1.2.2 IBM JRE 1.2.2 IE w/ MSVMJava 2 Enterprise Edition server jBoss WebLogic 6.0 / IBM WAS 3.5 WebLogic 6.0 / IBM WAS 3.5 NONE

1.2 Toolset

1.2.1 Java TechnologyIDE for Java 2 platform v3.5 IBM VAJ Pro/Ent IBM VAJ Pro 3.5 NONE NONEJDBC 2.0 Driver jdbc-odbc bridge (IBM/MS) WebLogic / OPTA2000 WebLogic / OPTA2000 NONEJavaServlets v2.2 IBM VAJ Pro/Ent WebLogic / Websphere WebLogic / WebSphere NONEJavaServer Pages v1.1 WebSphere Studio WebLogic jspc compiler NONE NONEScripting HTML/ASP/JavaScript etc… ScriptBuilder / SitePad pro ScriptBuilder NONE NONEEJB v1.1 VAJ Websphere Test Env WebLogic/ Websphere WebLogic / Websphere NONEJavaMail (for alerts) v1.1.3 1.1.3 ref implementation ? ? NONEJava De-compiler tool DeCafe NONE NONE NONE

1.2.2 XML tools for JavaXML parser for Java (v1.1.2) Xerces/XML4J Xerces/XML4J Xerces AelfredXML-Schema v4/7/2000 XML Spy 3.5 XML Spy 3.5 NONE NONEXML v1.0 editor XML Spy 3.5 XML Spy 3.5 NONE NONEXML DTD editor (v 12/17/1999) XML Spy 3.5 XML Spy 3.5 NONE NONEXSL v1.0 editor XML Spy 3.5 XML Spy 3.5 NONE NONEXSLT v1.0 editor XML Spy 3.5 XML Spy 3.5 NONE NONEWML v1.0 editor ScriptBuilder ScriptBuilder NONE NONEXpath v1.0 for Java (v0.20.0) Xalan XSLT Processor Xalan XSLT Processor Xalan XSLT Processor NONEXSLT Processor for Java (v0.20.0) Xalan XSLT Processor Xalan XSLT Processor Xalan XSLT Processor NONE

1.2.3 OOAD/Schema DesignUML/OOD (UML 1.3) Rose/Ent 2001/Visio Ent NONE NONE NONEER Modeling (UML data modeling ext) Rose/Ent 2001/Visio Ent NONE NONE NONE

1.2.4 Microsoft JavaMicorsoft Java SDK v4.0 MS Java SDK (NOT VJ++) NONE NONE NONE

1.2.5 Life Cycle tools (for each iteration)Build tool Ant Ant NONE NONEEJB Deployment tool Ant / Bean-test Ant / Bean-test NONE NONEInstallation software InstallAnywhere InstallAnywhere NONE NONEDemo software DemoShield / Toolbook NONE NONE DemoShield



HTML Documentation tool Frontpage w/ CSS styles NONE NONE NONE



1.3 Coding StandardsThe “WIKI” web is the best programming practices reference: http://www.c2.com/cgi/wiki?ExtremeProgrammingRoadmap

1.3.1 Java Coding StandardThe coding standards that we should use are described in the pocketbook “the elements of Java Style” by Scott Ambler and Rougewave developers. These are based on the Sun Code Conventions (http://java.sun.com/docs/codeconv/).

1.3.2 Java Source Code BeautifierUse JIndent with the Sun-Style.jin configurationhttp://home.wtal.de/software-solutions/jindent/frameset.html

1.3.3 C++ Coding StandardC++ code should be gcc 2.95.2 compilable.

C++ coding rules from Ellemtel http://www.cs.umd.edu/users/cml/cstyle/Ellemtel-rules.pdf

Also available in “Industrial Strength C++: Rules and Recommendations” by Mats Henricson and Erik Nyquist, a book recommended on the “WIKI” web: http://www.c2.com/cgi/wiki?IndustrialStrengthCplusPlusSee Also books like:

“Effective C++” book/CD by Scott Myers.“Large-Scale C++ Software Design” by John Lakos

1.4 QA & Testing Standards

1.4.1 Unit Testing StandardsXP framework for unit testing:

1.4.1.1 Junit 3.2

JavaUnit link from the “WIKI” web:http://www.c2.com/cgi/wiki?JavaUnit

JunitCreator for VAJ from “BigBenTools” link on the “WIKI” web: http://www.xpdeveloper.com/cgi-bin/wiki.cgi?BigBenTools

1.4.1.2 CPPunit 1.5

http://www.c2.com/cgi/wiki?CppUnit

1.4.2 Use Case (Scenario) Testing StandardsRational QualityArchitect, an addin for Rational Rose Enterprise, should be used for scenario based test of J2EE and COM components.

1.4.3 Load Testing & Performance Testing StandardsWe can use Microsoft Web Stress Testing tool for now.Tool such as Empirix Bean-Test or Rational PerformanceArchitect may be required in future.

1.4.4 Regression Testing StandardsRational TestStudio or similar regression testing tool may be required in future.


http://www.c2.com/cgi/wiki?JavaUnit

http://www.c2.com/cgi/wiki?IndustrialStrengthCplusPlus

http://www.cs.umd.edu/users/cml/cstyle/Ellemtel-rules.pdf

http://home.wtal.de/software-solutions/jindent/frameset.html

http://java.sun.com/docs/codeconv/

http://www.c2.com/cgi/wiki?ExtremeProgrammingRoadmap

http://www.c2.com/cgi/wiki?ExtremeProgrammingRoadmap


1.5 Version ControlVisual SourceSafe clients should be used from development PCs. VSS server will be running on the LOKI server. Typical VSS options- checking in a file in respective java package, checking it out for write access, canceling a checkout in case the build broke or your code regressed, and getting latest for readonly access.Three types of Visual SourceSafe databases should be used:

1.5.1 UmlModel- Model databaseThe “UmlModel” is the database version controlled for the entire architectural baseline- use case models, system functions w/ algorithms, UML diagrams (domain object models, sequence diagram. class designs, state machines etc), and the data model (schema design).

1.5.2 Codebase- Code databaseThe “Codebase” is the database version controlled for the entire codebase, pluggable into Java IDE and modeling tool. The schema “file” will be stored in the codebase. (Note that the schema “design”-diagram- should be stored in the UmlModel database.) Even the Java Archieve files – JARs, WARs and EARs, XML meta-info, EJB descriptors – are stored here. JavaDoc files also are generated from within the codebase. It should conform to the JavaDoc standards, for API documentation in the least. Patch release is used whenever branching is made.J2EE comes with an enterprise application, eStore. The codebase should be structurally baselined on the eStore package structures, to begin with. The entire BCOOL hierarchy of java packages should look like combination of these:

Figure 1: The BCOOL hierarchy of java packages should look like combination of these two.

1.5.3 Docs- Document databaseThe “Docs” is the database version controlled for the entire documentation- Word/html documents, and so on. Refer to the “BristleCone Technical Notes Process”, technotes.doc for further details. The HTML documentation created can also be used in the RUP style sophisticated project website, by inserting “css-“stylish html docs into javadoc style comments.



1.6 Using IBM VisualAge for Java

1.6.1 VAJ with EJB/JSP supportRefer to IBM’s website for the ”VisualAge for Java and WebSphere Studio Tutorials” series, e.g. http://www7.software.ibm.com/vad.nsf/data/document3936

1.6.2 VAJ with SAP R/3 supportThe screenshots for Advanced generation of Java proxies using the “AccessBuilder for SAP R/3” in VAJ3.5 are given below. The AdvancedGenerationDlg option in the AccessBuilder.ini file has to be set to 'true' for it to be enabled, default is false. Setting it to true brings up the screen in AccessBuilder as shown below:

Figure 2: SAP R/3 support in VAJ Enterprise



1.6.3 VAJ with VSS

1.6.3.1 Connecting VAJ with VSS “codebase”

To point to the VSS “codebase” database, you will have to first install VSS client on your machine and then you need to point to the “//loki/vss/codebase/sourcesafe.ini” file, vss is the share on the //loki server.

Figure 3: Connecting VAJ with VSS “codebase”

When you define your “connection” to the VSS “codebase” database, with the “$ProductName/src” VSS project; you have to set to the “src” subdir of your working folder on your hard disk.

Figure 4: Defining/changing the VSS connection from VAJ



1.6.3.2 Adding class “files” from VAJ to VSS “codebase”

You need to add to “codebase” the class “files” you created newly in VAJ as follows:

Figure 5: Adding VAJ files to VSS "codebase"

1.6.3.3 Other VSS options

These options work from within VAJ, just as they do for any other tool such as Rational Rose. But what if you do NOT use VAJ repository? If you use a file editor instead, then you must add your file to the VSS codebase “packages”, appropriately. VAJ developers then can either “get” or “checkout” that file, if needed.

1.7 Labeling the Build from command-line into VSS “codebase”The VSS "codebase" should have all files checked in for the build. The build process should begin with an email notification of the "check-in within 15 minutes" kind. After the VSS “get latest” codebase, the build process should end up in a (hopefully unbroken) successful build. Start labeling the build with the build date, e.g. 20000731-1 for a build #1, dated 07/31/2000. Most "Rational" builds follow this type of convention. For each build, the labeling should be done by the build master against the VSS “project” $/bcoolBuild/src. We will use the ant build tool to do the command line label operations with VSS at the end of the successful “build”. We will also explore if we can use the ant build tool to do deployment for Bea Weblogic server. Please refer to the updated documentation on the build process from VSS “docs”. The buildmaster sends an email to [email protected] re. the structure of bcool build document whenever it is updated. That will reinforce the classpath across the dev/qa boxes for the bcool team.



1.8 Proposed Build configuration infrastructure: hardware & software

Figure 6: Proposed Build configuration infrastructures

1.8.1 Nightly Build on Build MachineWe run the ant build.xml based builds to develop the web/ejb/eis tiers on development build machine.The build should be scheduled to start exactly at 2 AM every night.

1.8.2 Nightly Deployment on Development Server (Stage I)We should ideally not do builds on development servers, since other developers might be testing their JSPs against the servlets and EJBs deployed the previous night. We run the ant deploy.xml script to deploy the WAR, the EJB-JAR and the EAR files (wherever applicable) on the development server.The deployment script should be scheduled to start exactly at 2 AM every night.

1.8.3 Weekly Deployment on Staging Server (Stage II)We should ideally not do builds on staging servers. We run the ant deploy.xml script to deploy the WAR, the EJB-JAR and the EAR files (wherever applicable) on the staging server. The deployment script should be scheduled to start exactly at 2 AM every Friday.


DATABASE SERVERNT 4.0 Server (MSDN)SQL Server (MSDN)ClearQuest and Rose (floating license server)SourceSafe ServerFile serverILOG (floating server)

R/3 SERVERNT 4.0 Server (MSDN)R/3 w/ Oracle (SAP Production copy)

BW SERVERNT 4.0 Server (MSDN)BW 2.0B w/ Oracle (SAP Production copy)

APO SERVERNT 4.0 Server (MSDN)APO 2.0B w/ Oracle (SAP Production copy)

DEMO I (SERVER)Win2k Server (MSDN)WebLogicR/3 w/ SQL Server (SAP Customer copy)Dashboard (MSDN)ILOG (node-locked)Bcool build

STAGING SERVERWin2k Server (MSDN)WebLogicSQL Server (MSDN)Dashboard (MSDN)ILOG COM APIBcool build

DEMO II (Mirror)Win2k Server (MSDN)WebLogicR/3 w/ SQL Server (SAP customer copy)Dashboard (MSDN)ILOG (node-locked)Bcool build

DEVELOPMENT SERVERWin2k Server (MSDN)WebLogicSQL Server (MSDN)Dashboard (MSDN)ILOG COM APIBcool build


1.8.4 Milestone Deployment on Demo/Mirror Servers (Stage III)We should never do builds on demo/production servers. We run the ant deploy.xml script to deploy the WAR, the EJB-JAR and the EAR files (wherever applicable) on the demo/production boxes. The deployment script should be scheduled to start exactly at 2 AM every milestone-end.We also update the database server and the R/3 server with the latest test data.

1.8.5 Making the build on Development Servers

1.8.5.1 Bill of Materials(BOM) for builds

Refer to the build document, “Structure of Bcool Build” for Bcool build structure & the build process.

1.8.5.2 Making the Build using Ant command-line

Assuming you have Ant installed, to execute this build, change to the directory where you've done a VSS “get” on the file “build.xml” and from a command line enter ant. You should see the output shown below.

Figure 7: The results of running Ant build tool from command-line

Admittedly, it's not too useful so far, but it does show you the basic structure of a build.xml file. The Ant documentation explains the options and tasks available, and Ant provides its own build file that you can model your builds on.



1.8.5.3 Making the Build using Ant in VisualAge for Java

While Ant is most often used as a command-line tool for automated nightly builds, the command line is not the easiest place to debug problems with your build or create custom tasks. It's easier to integrate Ant into VisualAge for Java to create and debug custom tasks.

1.8.5.3.1 Importing Ant into VisualAge for JavaThe most effective way to import Ant into VisualAge for Java is to import the source code. It's easier to debug your custom tasks when you can step through all the code and see what's happening. Ant uses a Java API for XML Parsing (JAXP) compliant XML parser to read the build.xml files. The binary release of Ant includes Sun's jaxp.jar and parser.jar files, the reference implementation of JAXP. You can get the JAXP parser from Sun.

To import Ant into VisualAge for Java:Extract the source code from jakarta-ant.tar.gz into the /tmp directory. Import from the directory /tmp/jakarta-ant/src into a new project named Ant. Import the .jar files /tmp/jakarta-ant/lib/jaxp.jar and /tmp/jakarta-ant/lib/parser.jar into a project named JAXP. Select the class org.apache.tools.ant.Main in the Ant project, and select Properties from the Selected menu. Select the Classpath tab, and select Edit beside the Project Path field. Select JAXP, then OK twice. Select IBM XML Parser for Java, then OK twice.Version the Ant project to 1.1, IBM XML Parser for Java to 1.0, and the JAXP project to 1.0.

Once you are done, set the ant.Main properties in your Workbench as shown below:

Figure 8: Setting ant.Main properties after importing and versioning Ant and JAXP



1.8.5.4 Running & Debugging the build from within VisualAge for Java

The simplest way to run a build from within VisualAge for Java is to execute the main method of the org.apache.tools.ant.Main class, passing in any parameters on the command line. When you run Ant without any options, it looks for a build.xml file in its current directory. Due to the way VisualAge for Java starts an application, that current directory will always be ~/vaj/ide/project_resources/Ant, where ~/vaj is the directory where you installed VisualAge for Java. So to run your build, you can either import build.xml with the Import dialog into your project resources directory, or you can use the -buildfile command-line option, which lets you specify which build file to use.

Running the main method of the org.apache.tools.ant.Main class produces the output as shown below:

Figure 9: The results of running build.xml in VisualAge for Java



1.9 Deploying the BCOOL application from the build machineRefer to “Structure of Bcool Deployment” document for details on Bcool deployment structure & deployment process.Also refer to the “Bristlecone Software Development Process Model” shown below, Implementation, test and deployment process workflows:

Figure 10: Bristlecone Software Development Process Model

1.10What if the Build is “broken”?Penalty ;-) Penalize the developer responsible for breaking the build! Even if the unit tests were successful, it does not mean that the build can be integrated from these.

1.11Installation Process for demos

1.11.1 InstallAnywhere Standard Edition APIReference website http://www.zerog.com

1.12Testing the build for demosRefer to the test plan documentation, created by test lead, Vijay Aliseti.



2 Reference websitesWe need to expand this list for all items listed in the topics “Engineering Standards”, “Coding Standards”, and “Bill of materials for the build machine”:

The Apache XML projecthttp://xml.apache.org/index.html

UNIX toolset for Windowshttp://sourceware.cygnus.com/cygwin/

2.1 Issues The JSP developer’s JSP tag library can call the EJB developer’s session bean, which may call the entity

beans or directly execute the SQL statements (using JDBC) on the build machine running SQL server. The repository of IBM VisualAge for Java connects using the SCCS API to the VSS version control “codebase”

database on the build machine. The JDBC RowSet 1.0 spec (part of JDBC 2.0 Optional package API) should be used for client-side caching.

This concept is similar to Microsoft COM+ concept of disconnected recordsets. When does Rational Rose “synchronize” code with VSS codebase? The “code freeze” time looks good for this,

after the build is installed and tested on the build machine, with no major regressions. Test planning documentation pending until Vijay Aliseti begins working on it. The command line scripts need to be developed- for labeling the VSS codebase, incremental builds, and to do

the master build. Defect/Feature tracking process and tool TBD.


http://sourceware.cygnus.com/cygwin/

http://xml.apache.org/index.html


EpilogueEat own dog food.

Courtesy: “Show-Stopper!: The Breakneck Race to Create Windows NT and the Next Generation at Microsoft” By G. Pascal Zachary. Hardcover (October 1994)
