The CodeBeneath

Mutual PKI Authentication With a Java-based Application

2010-11-09T18:35:00.000-08:00

I recently added certificate based authentication to an application I have been working on for awhile. It took longer to get done than I would have thought primarily because the number of moving pieces and most advice and guidance I found online was incomplete. I hope that documenting the complete setup I used will save someone else some time and frustration.

The requirements were:

Wiring together two Java applications via SOAP, using CXF framework
The producing application needed a valid server certificate
The consuming application needed to present a valid client certificate to the server
These certificates needed to be signed by a trusted root and share the same certificate authority
For authentication purposes, no custom code within the application itself
Use the Java keytool program to create keypairs and generate signing requests

The broad strokes:

Create the necessary certificates
Setup tomcat on the producing side to accept only https connections and require client authentication
Setup the consuming application to present client certs that can satisfy the secure authentication handshake

Creating and signing the certificates

I have previously created a CA setup using strictly openssl, but for this project, I needed to lean more heavily on keytool to originate the keypairs and openssl to do the certificate signing. The keytool program comes with the JDK. I used a windows based openssl binaries from SLP.

Setup a directory structure as recommended by openssl installation and set an environment variable, %SSLDIR%, to point to your CA directory.

Create CA and RA

# Create the CA's keypair and self-signed certificate
#   -x509 means create self-sign cert
#   -keyout means generate keypair
#   -nodes means do not encrypt private key.
#   -set_serial sets the serial number of the certificate
openssl req -verbose -x509 -new -nodes -set_serial 1234 -subj "/CN=codebeneathCA/OU=project/O=company/ST=MO/C=US" -days 7300 -out %SSLDIR%/certs/cacert.pem -keyout %SSLDIR%/private/caprivkey.pem -config %SSLDIR%/openssl.config

# Create the Root Authority's keypair and Certificate Request
#    without -x509, we generate an x509 cert request.
#   -keyout means generate keypair
#   -nodes means do not encrypt private key.
openssl req -verbose -new -nodes -subj "/CN=codebeneathRoot/OU=project/O=company/ST=MO/C=US" -days 7300 -out %SSLDIR%/certs/csrra.pem -keyout %SSLDIR%/private/raprivkey.pem -config %SSLDIR%/openssl.config

# Have the CN=codebeneathCA issue a certificate for the CN=codebeneathRoot
# We need -extfile exts -extenstions x509_extensions to make sure
# CN=TheRA can be a Certificate Authority.
openssl ca -batch -days 7300 -cert %SSLDIR%/certs/cacert.pem -keyfile %SSLDIR%/private/caprivkey.pem -in %SSLDIR%/certs/csrra.pem -out %SSLDIR%/certs/ra-ca-cert.pem -extfile exts -extensions x509_extensions -config %SSLDIR%/openssl.config

Create Server Cert

# Create keypairs and Cert Request for a certificate for server
# This procedure must be done in JKS, because we need to use a JKS keystore.
# The current version of CXF using PCKS12 will not work for a number of
# internal CXF reasons.
keytool -genkey -alias codebeneath-server -dname "CN=10.9.5.210,OU=codebeneath-server,O=company,ST=MO,C=US" -keystore C:/certs/server-keystore.jks -storetype jks -storepass password -keypass password -validity 365
keytool -certreq -alias codebeneath-server -keystore C:/certs/server-keystore.jks -storetype jks -storepass password -keypass password -file codebeneath-server-csr.pem

# Have the CN=codebeneathRoot issue a certificate for server via the Certificate Requests.
openssl ca -batch -days 7300 -cert %SSLDIR%/certs/ra-ca-cert.pem -keyfile %SSLDIR%/private/raprivkey.pem -in %SSLDIR%/requests/codebeneath-server-csr.pem -out %SSLDIR%/requests/codebeneath-server-ra.pem -config %SSLDIR%/openssl.config

# Rewrite the certificates in PEM only format. This allows us to concatenate them into chains.
openssl x509 -in %SSLDIR%/certs/cacert.pem -out %SSLDIR%/certs/cacert.pem -outform PEM
openssl x509 -in %SSLDIR%/certs/ra-ca-cert.pem -out %SSLDIR%/certs/ra-ca-cert.pem -outform PEM
openssl x509 -in %SSLDIR%/requests/codebeneath-server-ra.pem -out %SSLDIR%/requests/codebeneath-server-ra.pem -outform PEM

# Create a chain readable by CertificateFactory.getCertificates.
type %SSLDIR%\requests\codebeneath-server-ra.pem %SSLDIR%\certs\ra-ca-cert.pem %SSLDIR%\certs\cacert.pem > %SSLDIR%\requests\codebeneath-server.chain

# Replace the certificate in the server keystore with their respective full chains.
keytool -import -file codebeneath-server.chain -alias codebeneath-server -keystore C:/certs/server-keystore.jks -storetype jks -storepass password -keypass password -noprompt

# Create the server Truststore file containing the CA cert.
keytool -import -file cacert.pem -alias codebeneathCA -keystore C:/certs/server-truststore.jks -storepass password -noprompt

Create Client Cert

# Create keypairs and Cert Request for a certificate for client (codebeneath)
# This procedure must be done in JKS, because we need to use a JKS keystore.
# The current version of CXF using PCKS12 will not work for a number of
# internal CXF reasons.
keytool -genkey -alias codebeneath -dname "CN=10.9.5.105,OU=codebeneath-client,O=company,ST=MO,C=US" -keystore C:/certs/client-keystore.jks -storetype jks -storepass password -keypass password -validity 365
keytool -certreq -alias codebeneath -keystore C:/certs/client-keystore.jks -storetype jks -storepass password -keypass password -file codebeneath-csr.pem

# Have the CN=codebeneathRoot issue a certificate for client via the Certificate Requests.
openssl ca -batch -days 7300 -cert %SSLDIR%/certs/ra-ca-cert.pem -keyfile %SSLDIR%/private/raprivkey.pem -in %SSLDIR%/requests/codebeneath-csr.pem -out %SSLDIR%/requests/codebeneath-ra.pem -config %SSLDIR%/openssl.config

# Rewrite the certificates in PEM only format. This allows us to concatenate them into chains.
openssl x509 -in %SSLDIR%/requests/codebeneath-ra.pem -out %SSLDIR%/requests/codebeneath-ra.pem -outform PEM

# Create a chain readable by CertificateFactory.getCertificates.
type %SSLDIR%\requests\codebeneath-ra.pem %SSLDIR%\certs\ra-ca-cert.pem %SSLDIR%\certs\cacert.pem > %SSLDIR%\requests\codebeneath.chain

# Replace the certificate in the client keystore with their respective full chains.
keytool -import -file codebeneath.chain -alias codebeneath -keystore C:/certs/client-keystore.jks -storetype jks -storepass password -keypass password -noprompt

# Create the client Truststore file containing the CA cert and server cert.
keytool -import -file cacert.pem -alias codebeneathCA -keystore C:/certs/client-truststore.jks -storepass password -noprompt
keytool -import -file codebeneath-server-ra.pem -alias codebeneath-server -keystore C:/certs/client-truststore.jks -storepass password -noprompt

Create trust for the server to know the client

# Import the client cert into the server Truststore.
keytool -import -file codebeneath-ra.pem -alias codebeneath -keystore C:/certs/client-truststore.jks -storepass password -noprompt

Export client cert from keystore for browser import

The keytool program cannot export private keys in any format, so use portecle to do these steps so that we can verify the setup using a browser without involving the actual client application.

Start portecle: java -jar ./portecle.jar
File... Open keystore file... select the ./client-keystore.jks file. Type the password.
Right-client the "codebeneath" certificate name. Select Export...
Export Type: Private Key and Certificates. Export Format: PKCS #12. Click OK. Type the password.
For the PKCS #12 password, it must be non-blank value or else the browser will not import it correctly.
In the browser, import the certificate as a "Personal" certificate.
In the browser, import the CA certificate as a trusted authoritative certificate.

Double check the results so far...

On the server machine:

keytool -list -keystore ./server-keystore.jks

one signed certificate chain, PrivateKeyEntry, alias="codebeneath-server"

keytool -list -keystore ./server-truststore.jks

CA certificate, trustedCertEntry, alias="codebeneathca",
client certificate,trustedCertEntry, alias="codebeneath"

On the client machine:

keytool -list -keystore ./client-keystore.jks

one signed certificate chain, PrivateKeyEntry, alias="codebeneath"

keytool -list -keystore ./client-truststore.jks

CA certificate, trustedCertEntry, alias="codebeneathca",
server certificate, trustedCertEntry, alias="codebeneath-server"

Server setup using tomcat

To accomplish the required mutual authentication (server is trusted https:// and client presents a valid certificate) requires setup within tomcat and the server war web.xml file. There is no code involved, it is strictly the setup of the servlet container to handle the security handshaking.

Tomcat server.xml file

Note that the clientAuth attribute must be "true" for things to work properly, even though the specification says that each war may individually be setup to require/not require client auth.

...
<Connector port=\"8443\" protocol=\"HTTP/1.1\" SSLEnabled=\"true\"
        maxThreads=\"150\" scheme=\"https\" secure=\"true\"
        clientAuth=\"true\" sslProtocol=\"TLS\"
        keystoreFile=\"C:/certs/server-keystore.jks\"
        keystorePass=\"password\"
        keyAlias=\"codebeneath-server\"
        truststoreFile=\"C:/certs/server-truststore.jks\"
        truststorePass=\"password\"
        />
...

Tomcat tomcat-users.xml file

Each username must match a client certificate subject line. Use portecle to open the client cert and cut-and-paste the "Subject:" line to this file's username value. So, even though the client certificate is valid given the truststore requirements, each client must also be specifically listed in this file to have access to the server application.

...
<role rolename=\"codebeneathRole\">
<user username=\"CN=10.9.5.43, OU=project, O=company, ST=MO, C=US\" password=\"password\" roles=\"codebeneathRole\">
...

Server war web.xml file

Both "role-name" elements must match the tomcat-users.xml defined rolename. The "auth-method" value of "CLIENT-CERT" will require a client certificate for authentication. The "transport-guarentee" value of "CONFIDENTIAL" will redirect all requests
...

<login-config>
<auth-method>CLIENT-CERT</auth-method>
</login-config>
<security-role>
<role-name>codebeneathRole</role-name>
</security-role>
<security-constraint>
<display-name>CodeBeneath</display-name>
<web-resource-collection>
 <web-resource-name>CodeBeneath</web-resource-name>
 <description></description>
 <url-pattern>/*</url-pattern>
 <http-method>GET</http-method>
 <http-method>POST</http-method>
 <http-method>HEAD</http-method>
 <http-method>PUT</http-method>
 <http-method>OPTIONS</http-method>
 <http-method>TRACE</http-method>
 <http-method>DELETE</http-method>
</web-resource-collection>
<auth-constraint>
 <description>
 <role-name>codebeneathRole</role-name>
</auth-constraint>
<user-data-constraint>
 <description>
 <transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
...

Debug SSL

In the event that the mutual authentication fails, we can enable specific debugging on the server side. In the catalina.bat file, add the switch -Djavax.net.debug=ssl,handshake

Client Setup

Since the project used SOAP WS-*, including WS-Security, on the client side we used the CXF project to handle the wsdl-to-java code generation and to create the client port. My project uses CXF version 2.2.11, with the additional "cxf-rt-ws-security" dependency jar.

Client java code

package com.codebeneath;

import org.apache.cxf.endpoint.Client;
import org.apache.cxf.frontend.ClientProxy;
import org.apache.cxf.jaxws.JaxWsProxyFactoryBean;
//import org.apache.cxf.interceptor.LoggingInInterceptor;
import org.apache.cxf.interceptor.LoggingOutInterceptor;
import org.apache.cxf.transport.http.HTTPConduit;
import org.apache.cxf.configuration.jsse.TLSClientParameters;
import org.apache.cxf.binding.soap.saaj.SAAJOutInterceptor;
import org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor;
import org.apache.ws.security.handler.WSHandlerConstants;

import java.net.URL;
import java.security.GeneralSecurityException;
import java.security.KeyStore;
import java.security.KeyStoreException;
import java.security.NoSuchAlgorithmException;
import java.security.UnrecoverableKeyException;
import java.security.cert.CertificateException;
import java.util.HashMap;
import java.util.Map;
import java.util.logging.Logger;
import javax.net.ssl.KeyManager;
import javax.net.ssl.KeyManagerFactory;
import javax.net.ssl.TrustManager;
import javax.net.ssl.TrustManagerFactory;
import javax.xml.ws.BindingProvider;

/**
* Client a SOAP WS client for the service.  Handles logging support, WS-Security and PKI certificates
*/
public final class Client {

private static final String DEFAULT_PASSWORD = "password";
private static final String KEYSTORE_FILENAME = "/client-keystore.jks";
private static final String TRUSTSTORE_FILENAME = "/client-truststore.jks";

private Client() {
}

/**
 * Create a new WS client
 * @param serviceUrl, the service URL endpoint
 * @param sigPropFile, the properties file for client PKI.  Must be on the classpath at runtime
 * @return client port
 */
public static TroubleTicketServiceSoap createClient(URL serviceUrl, String sigPropFile, String keystoreDir) {

 JaxWsProxyFactoryBean factory = new JaxWsProxyFactoryBean();
 factory.setAddress(serviceUrl.toString());
 factory.setServiceClass(TroubleTicketServiceSoap.class);

 // request and response traces in the server.log
 addLogging(factory);

 // SOAP WS-Security header
 addSecurityHeaders(factory, sigPropFile);

 // create the client
 TroubleTicketServiceSoap port = (TroubleTicketServiceSoap) factory.create();
 ((BindingProvider) port).getRequestContext().put("schema-validation-enabled", Boolean.TRUE.toString());

 // handle trust of server certificates
 addCertificateHandling(port, serviceUrl, keystoreDir);

 return port;
}

private static void addLogging(JaxWsProxyFactoryBean factory) {
 factory.getOutInterceptors().add(new LoggingOutInterceptor());  // SOAP Request
//  factory.getInInterceptors().add(new LoggingInInterceptor());    // SOAP Response
}

private static void addSecurityHeaders(JaxWsProxyFactoryBean factory, String sigPropFile) {

 // setup the properties for WS-Security.  This is PKI signed.  The SIG_PROP_FILE must be on the classpath
 Map wss4jOutProps = new HashMap();
 wss4jOutProps.put(WSHandlerConstants.ACTION, WSHandlerConstants.SIGNATURE);
 wss4jOutProps.put(WSHandlerConstants.USER, "client");
 wss4jOutProps.put(WSHandlerConstants.PW_CALLBACK_CLASS, ClientPasswordCallback.class.getName());
 wss4jOutProps.put(WSHandlerConstants.SIG_PROP_FILE, sigPropFile);
 wss4jOutProps.put(WSHandlerConstants.SIG_KEY_ID, "DirectReference");

 // add required security interceptors
 factory.getOutInterceptors().add(new SAAJOutInterceptor());
 factory.getOutInterceptors().add(new WSS4JOutInterceptor(wss4jOutProps));
}

private static void addCertificateHandling(TroubleTicketServiceSoap port, URL serviceUrl, String keystoreDir) {
 Client proxy = ClientProxy.getClient(port);
 HTTPConduit conduit = (HTTPConduit) proxy.getConduit();
 TLSClientParameters tcp = new TLSClientParameters();
 tcp.setDisableCNCheck(true);

 try {
  KeyStore trustStore = KeyStore.getInstance("JKS");
  KeyStore keyStore = KeyStore.getInstance("JKS");

  // accept all self-signed server certs
//   tcp.setTrustManagers(CertificateAcceptorCXF.acceptAllCerts());

  File truststoreFile = new File(keystoreDir + TRUSTSTORE_FILENAME);
  trustStore.load(new FileInputStream(truststoreFile), DEFAULT_PASSWORD.toCharArray());
  TrustManagerFactory trustFactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
  trustFactory.init(trustStore);
  TrustManager[] tm = trustFactory.getTrustManagers();
  tcp.setTrustManagers(tm);

  // enable client certs for authentication
  File keystoreFile = new File(keystoreDir + KEYSTORE_FILENAME);
  keyStore.load(new FileInputStream(keystoreFile), DEFAULT_PASSWORD.toCharArray());
  KeyManagerFactory keyFactory = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
  keyFactory.init(keyStore, DEFAULT_PASSWORD.toCharArray());
  KeyManager[] km = keyFactory.getKeyManagers();
  tcp.setKeyManagers(km);

 } catch (KeyStoreException kse) {
  System.out.println("Security configuration failed with the following: " + kse.getCause());
 } catch (NoSuchAlgorithmException nsa) {
  System.out.println("Security configuration failed with the following: " + nsa.getCause());
 } catch (FileNotFoundException fnfe) {
  System.out.println("Security configuration failed with the following: " + fnfe.getCause());
 } catch (UnrecoverableKeyException uke) {
  System.out.println("Security configuration failed with the following: " + uke.getCause());
 } catch (CertificateException ce) {
  System.out.println("Security configuration failed with the following: " + ce.getCause());
 } catch (GeneralSecurityException gse) {
  System.out.println("Security configuration failed with the following: " + gse.getCause());
 } catch (IOException ioe) {
  System.out.println("Security configuration failed with the following: " + ioe.getCause());
 }

 if (serviceUrl.getProtocol().trim().equalsIgnoreCase("https")) {
  conduit.setTlsClientParameters(tcp);
  LOG.info("GSTv3 Web Service protocol is 'https' so " + "set the TLSClientParameters on the "
    + "HTTPConduit. This should cause the" + " request to accept all certificates "
    + "and disable the CN Check.");
 } else {
  LOG.info("GSTv3 Web Service url did was not 'https' so did NOT " + "set the TLSClientParameters "
    + "on the HTTPConduit.");
 }
}
}

Client client-sign.properties

# Do not change these two properties
#
org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
# Set your keystore location and password here!
#
org.apache.ws.security.crypto.merlin.file=c:/certs/client-keystore.jks
org.apache.ws.security.crypto.merlin.keystore.password=password
org.apache.ws.security.crypto.merlin.keystore.alias=codebebeath

Conclusion

I hope that this complete picture of mutual PKI certificate authentication helps. If anything is not clear, let me know and I will try to clarify.

"Perfectionism is a crime against humanity"

2010-06-10T07:39:00.000-07:00

I wish I had written this...

You could say that perfectionism is a crime against humanity. Adaptability is the characteristic that enables the species to survive-and if there’s one thing perfectionism does, it rigidifies behavior. It constricts people just when the fast-moving world requires more flexibility and comfort with ambiguity than ever. It turns people into success slaves.

There are several people I work with or deal with in my life that don't realize that the return on investment for their efforts is detrimental to success of the project. It is an ongoing battle and the battle-cry is "Moving on...".

Read the rest of the source article here: Is perfectionism killing your career?

"There’s no success quite like failure"

2009-12-28T07:42:00.000-08:00

From Accept Defeat: The Neuroscience of Screwing Up:

"This is why other people are so helpful: They shock us out of our cognitive box. “I saw this happen all the time,” Dunbar says. “A scientist would be trying to describe their approach, and they’d be getting a little defensive, and then they’d get this quizzical look on their face. It was like they’d finally understood what was important.”

What turned out to be so important, of course, was the unexpected result, the experimental error that felt like a failure. The answer had been there all along — it was just obscured by the imperfect theory, rendered invisible by our small-minded brain. It’s not until we talk to a colleague or translate our idea into an analogy that we glimpse the meaning in our mistake. Bob Dylan, in other words, was right: There’s no success quite like failure."

Grail Projects in Hudson, Pt 2.

2009-12-04T06:21:00.000-08:00

I just recently concluded a first sprints worth of work using Grails for the first time. We delivered.

While cutting the release, I found one additional gotcha in our CI environment. The grails application.properties file holds several key pieces of information including the version number, grails plugin versions and the last build date. This means the file must be checked into source control, but is also modified locally every build by CI (Hudson, nudge, nudge, wink wink). This caused our build to fail while bumping our project version.

CI will fail a grails+maven project if you change the version number of the project in the application.properties file.
- Workaround: 1) Have your CI project perform a clean checkout instead of an update for you build. 2) At the end of your build, add a custom hook to delete the locally modified application.properties file.
- Fix: I think have the build timestamp in this file may be a mistake as Grails grows more mature. As an improvement, it should be removed.

Grail Projects in Hudson

2009-11-20T15:52:00.000-08:00

Here is a quick reference for adding a Grails project to Hudson. I'm assuming the webtest plugin is installed becuase there is no reason not to use it. It rocks. Also note that for integration into my existing maven build, I'm using the built-in Grails v1.1.1 maven integration. The project structure was created via the maven archetype:

mvn org.apache.maven.plugins:maven-archetype-plugin:2.0-alpha-4:generate \
-DarchetypeGroupId=org.grails \
-DarchetypeArtifactId=grails-maven-archetype \
-DarchetypeVersion=1.1 \
-DgroupId=com.black -DartifactId=grails-project

With that, here is what works so far:

General sequence (these are also the steps for keeping a development team in synch):

```
svn up
```
```
grails upgrade --non-interactive
```
```
mvn clean install -DnonInteractive=true
```

Notes:

Step 2 above: This upgrades the grails project to include all core grails plugins and also creates some important files under web-app/WEB-INF (applicationContext.xml, ...). We would rather run mvn grails:exec -Dcommand=upgrade -DnonInteractive, however, this fails with an error: Embedded error: java.lang.reflect.InvocationTargetException /home/black/dev/branches/parent/grails-project/null/src/war not found. Anybody have an idea on this?
Step 3 above: This step will upgrade all non-core plugins added/modified/removed since the last checkout. Since grails will ask the "are you sure" question, make sure in CI to add the non-interactive switch as above, which will have the effect of cheerfully answering "Y" to all of grails questions.

Problems you may run into:

As part of a big maven multiproject build, grails may consume enough memory to produce an out of memory error.
- Fix: Set MAVEN_OPTS=-Xmx512m -XX:MaxPermSize=150m

Adding new grails plugins to the build will freeze the CI build due to the "are you sure" prompt. The same will happen when removing a grails plugin.
- Fix: Add the non-interactive switch to the build (mvn -DnonInteractive=true or grails --non-interactive)

Webtest launches a window during the test run that needs a display, so CI may need to run the webtests headless.
- Fix: Add non-interactive switch to the build (mvn -DnonInteractive=true or grails --non-interactive)

Webtest starts the jetty server on port 8080 by default which may clash with other services on your CI box using that port.
- Fix: Use the switch mvn -Dserver.port=8183. Note: The webtest.properties file property wt.config.port seems to be used if the code under test were already hosted on another running server besides the provided jetty.

A maven multiproject build that includes a grails project with webtests will look for /test/webtest/conf/webtest.properties in the wrong directory. That is, it will not look in ${basedir}, but always in the root project where you invoked maven to start with.
- Workaround: Create a hudson job that only builds the grails war/webtest project. Create a downstream dependency on your main CI hudson job to trigger this one to build.
- Fix: ?? Anyone have an answer for this one?

I hope this helps. For the few items above that have lingering questions, I would be interested in hearing if you have solved these. Let me know.

"Shipping is a feature."

2009-09-24T07:48:00.000-07:00

Another good variation on Perfect is the Enemy of Very Good:

"A 50%-good solution that people actually have solves more problems and survives longer than a 99% solution that nobody has because it’s in your lab where you’re endlessly polishing the damn thing. Shipping is a feature. A really important feature. Your product must have it."
-- http://www.joelonsoftware.com/items/2009/09/23.html

Hudson Gadget For Google Desktop v1.0

2009-06-24T21:27:00.000-07:00

For all you developers that rely on Hudson for continuous integration build status, I have released version 1.0 of the Hudson Status Gadget for Google Desktop. The code is part of the Hudson project itself, so it is open source.

More information can be found on its home page.

Release note highlights for version 1.0:

In addition to monitoring the multiple main hudson dashboards, any tabbed view can be also be monitored
A scrollbar shows for a large number of jobs that would take more space then the gadget allows
Views can be collapsed to a single line with all jobs statuses of that view aggregating their status to the single view line
A refresh button has been added for manual status refreshes
Blinking build statuses are now animated

Enjoy and let me know how it works out for you.

The Supply Chain of Continuous Integration

2008-11-23T21:00:00.000-08:00

When I was first introduced to Continuous Integration, I viewed it as a black box with a well defined interface. It was the same kind throw-it-over-the-wall mentality that some people have with testing: When the code is "done", give it to the testing shop and mark the checkbox complete. It may or may not return with feedback attached.

I got a different perspective of how CI should work, however, while working on a CI team. More than a little of this new perspective is probably due to working in a company that believes in and practices agile development and scrum management. With agile, we are much better at involving testers into day-to-day activities rather than the cold baton hand-off as sprint review time rolls near.

What got me thinking about a CI supply chain concept was the story from The Earth is Flat about how UPS has evolved from a package delivery company to an integral part of many companies day-to-day business operations. They started with a core business of picking up and shipping packages. But it turns out, there are inefficiencies to this bolted on approach. In order for the shipping to be efficient for both UPS and the contracting company, the entire supply chain had to be prepped in advance. This includes both pre and post shipment. The visibility into business processes had to be bidirectional.

I think the same is true with continuous integration. It is based on the old computer adage, GIGO, Garbage In Garbage Out. So a team that writes plenty of code, but no tests. What is the value of CI for them? The feedback is minimal. To get the most value out of an automated build system, there must be some forethought into what kind of quality feedback you want to see, and then what teams can do to define and integrate the right reporting tools into the build.

For example, even after automated tests written and incorporated into the build, you may want to get feedback on some quality measures on your code. In our case, we wanted Checkstyle and PMD reporting on our Java code. We use maven as our build tool, so adding the reporting into our builds was simple. But then the question becomes, what coding standards do we want to compare to? What PMD rulesets represent a sane minimum that teams can deal with and learn from at the same time?

So now, a team dedicated to providing CI services is recommending quality reports to both developers and stakeholders AND helping to define the rules that code should be compared against. My first take on this approach, deviating from a traditional CI definition was a sense of invasiveness. Upon further reflection, I have embraced the blurred lines between teams for several reasons. Firstly, it breaks artificial team boundaries and keeps communication lines open. CI is no longer a black box, it is a visible, value contributing component of system development. Secondly, developers won't (at least consistently across an organization) take the time to inject QA into their processes. A CI team, however, does have the time to take the first steps and get the ball rolling. The conversation is more constructive when you have something in place actually working then just a bunch of talking going on about what could be.

I think a simple diagram emphasizes the point. If "A" is a development team, "B" is a CI team, and "C" represents the stakeholders of the solution being developed, then the shaded areas pinpoint a missed opportunity unless you adopt the supply chain analogy. These are not hard control points, but juicy overlap, waiting to be optimized by as AB and BC working together.

So far, I've talked about the pre-shipment benefit leading into CI. I also now believe the supply chain post-CI is equally important. That is, where does the feedback go and how do you make is so easy, there is no reason not to use it. In our case, this encompassed two audiences with two different needs.

1) Developers. They need the low level test results, test coverage, Checkstyle and PMD reports.

2) Stakeholders (Project Managers, Solution Owners, Scrum Masters). They need to know that the developer teams are using the system. What is the source control commit frequency? How long do CI builds stay broken? How long are the automated builds taking? In short, the interest is around are they getting their monies worth on CI investment and knowing if the teams "get it". It provides them with just enough information to start asking the right questions to the right people.

So the supply chain from CI into management visibility, in our case, ended up being a enterprise level portal aggregating project CI metrics together into an at-a-glance view of how well their agile teams are performing. This could be stop light charts on current CI conditions or simple graphs of build times or number of tests as plotted over the last 30 days.

As always seem to be the case, the benefit of this proposed supply chain approach is inceased communication.

Again, this initially seemed to stray from traditional core CI functionality, but in reality it is simply providing the visibility into the process that scrum promises. Warts and all.

Hudson Status Google Gadget on Linux

2008-06-04T10:18:00.000-07:00

Google has just announced gadget support for the linux version of Google Desktop. This is exciting news for me as that means the Hudson Status gadget is now cross-platform. For all you developers out there that rely on Hudson, this means you don't have to visit your Hudson site or check your email or your feed reader to get the latest job statuses.

The dots are right there on your desktop!

For you existing users out there, make sure you upgrade to the newest gadget version, which has some important bug fixes. More information about the latest release, v0.9.5, can be found on the Hudson wiki.

Maven SNAPSHOT Traceability

2008-04-21T12:30:00.000-07:00

So your scrum team is creating non-unique SNAPSHOT versioned artifacts throughout your sprint. How do trace that SNAPSHOT version back to a baseline that is of any QA relevance (build number, subversion revision, datetime stamp)?


<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-antrun-plugin</artifactId>
 <executions>
   <execution>
     <phase>generate-resources</phase>
     <configuration>
       <tasks>
         <tstamp>
           <format property="now" pattern="MM/dd/yyyy hh:mm" unit="hour" />
         </tstamp>
         <property name="build.version" value="${version} (private-${now}-${user.name})" />
         <property name="hudson.build" value="hudson-${BUILD_NUMBER}, subversion-${SVN_REVISION}" />
                         
         <!-- put the version file -->
         <echo message="The build id is: ${build.version}" />
         <mkdir dir="target/${project.build.finalName}/" />
         <echo file="target/${project.build.finalName}/version.properties">version=${build.version} ${hudson.build}
         </echo>
       </tasks>
     </configuration>
     <goals>
       <goal>run</goal>
     </goals>
   </execution>
 </executions>
</plugin>

...

<profiles>
 <profile>
   <id>release</id>
   <properties>
       <!-- for releases, just use the POM version. -->
       <build.version>${version}</build.version>
       <hudson.build></hudson.build>
   </properties>
 </profile>
</profiles>

This little piece of magic creates a version.properties file that contains some valuable information.

version=1.1.0-SNAPSHOT (private-04/21/2008 02:23-jblack), hudson-453, subversion-1124

When you do a formal release, specify the -Prelease profile to have this file simply hold the pom version.

For the plugin configuration above, this file gets put in a war project root webapp directory, suitable for immediate viewing from your browser!

The mad props for this idea go to Kohsuke. :)

Hudson Gadget For Google Desktop

2008-04-09T22:01:00.001-07:00

I took a first stab at creating a google desktop gadget that can display the job names and statuses of any Hudson instance. Simply configure it to the Hudson server url and it will discover all the jobs and start polling the for blue dots.

Hudson Gadget, Version 0.9.0.

Let me know if you have any improvement ideas or other issues.

[update] This gadget has been contributed to the open source Hudson project.

Code Reuse Inside Your Own Company

2008-03-31T20:44:00.000-07:00

A short read over on Dr. Dobbs, Where Are the Clients In a SOA? made some good observations about the mindset of creating reusable SOA components, especially when the reuse is likely to occur in your own back yard.

"The best "enterprise architecture" plan will never be realized as long as developers assume the client of a piece of code is another piece of code."

"As software developers we are not very good customers of the work our colleagues do. We are quicker to search the Internet for a utility or example than we are to search our own internal repositories."

"More importantly, we aren't thinking about other developers when we create the code. We don't create interfaces that make it easy for people to use our code in ways we have not considered. We don't provide design-level abstractions that help other programmers and architects fit our solution into theirs. We don't market the code to the rest of the team or to other teams within the organization. We don't do any market research to make sure the nontraditional customers of our code are going to make the most of it. We don't package it in ways that also make it easy to use outside our intended use."

The emphasis is mine, although it should be yours, too.

Jersey... Jetty and Maven style!

2008-03-07T08:23:00.000-08:00

I recently created a webapp that due to time constraints, I implemented with plain old servlets which I am comfortable with. In reality, the project was a perfect candidate to implement in RESTful style. I had been loosely following the Jersey project, part of the larger java.net Metro project, so I decided to give Jersey a try.

"Jersey is the open source ... JAX-RS (JSR 311) Reference Implementation for building RESTful Web services. But, it is also more than the Reference Implementation. Jersey provides additional APIs and extension points (SPIs) so that developers may extend Jersey to suite their needs."

My only requirements were really around a quick turn-around dev setup. So I wanted to use maven and the jetty plugin to preview the results quickly.

Jersey is still only available as an early access preview (0.5-ea) , so some of the examples I found were "out of date", as the team is still refactoring the implementation.

So, first step: create a maven war project structure and configure the web.xml to look this this:


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<servlet>
  <servlet-name>Jersey</servlet-name>
  <servlet-class>com.sun.ws.rest.spi.container.servlet.ServletContainer</servlet-class>
  <init-param>
      <param-name>com.sun.ws.rest.config.property.resourceConfigClass</param-name>
      <param-value>com.sun.ws.rest.api.core.PackagesResourceConfig</param-value>
  </init-param>
  <init-param>
      <param-name>com.sun.ws.rest.config.property.packages</param-name>
      <param-value>org.naiade.tutorials.jersey;com.gestalt.gci.rest.resources</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
  <servlet-name>Jersey</servlet-name>
  <url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>

The two key things here are:

use the ServletContainer servlet (not ServletAdapter)
use the pluggable PackagesResourceConfig parameter value. This allows Jersey to auto find all REST resources based on the package names. This is configured in the additional parameter value. Here we provide a couple of packages to look in, semicolon separated.

For the code, I used the ShoeService example I found here.
As I mentioned before, Jersey is still evolving so I ended up making two code changes to still be able to compile under 0.5-ea:

@HttpMethod() changed to @GET or @POST
@UriTemplate() changed to @Path()

The maven project looks like:


<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.shoe</groupId>
<artifactId>shoeservice</artifactId>
<version>1.0</version>
<name>Shoe Service REST</name>
<packaging>war</packaging>
<dependencies>
   <!-- jersery.dev.java.net -->
   <dependency>
       <groupId>jersey</groupId>
       <artifactId>jersey</artifactId>
       <version>0.5-ea</version>
   </dependency> 
</dependencies>
<build>
   <plugins>
       <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-compiler-plugin</artifactId>
           <version>2.0.2</version>
           <configuration>
               <source>1.5</source>
               <target>1.5</target>
           </configuration>
       </plugin>
       <plugin>
           <groupId>org.mortbay.jetty</groupId>
           <artifactId>maven-jetty-plugin</artifactId>
           <version>6.1.8</version>
           <configuration>
               <scanIntervalSeconds>10</scanIntervalSeconds>
           </configuration>
           <dependencies>
               <dependency>
                   <groupId>org.apache.geronimo.specs</groupId>
                   <artifactId>geronimo-j2ee_1.4_spec</artifactId>
                   <version>1.0</version>
                   <scope>provided</scope>
               </dependency>
           </dependencies>
       </plugin>
   </plugins>
</build>
</project>

To bring it all together, it's as simple as

mvn jetty:run

Open you browser and hit http://localhost:8080/shoeservice/shoe

Easy.

I really see Jersey taking off as it is a good project and easy to work with. If you are looking for a good Java solution to creating a RESTful accessible services, give it a try.

NetBeans 6.0 Maven Integration

2008-02-12T12:24:00.000-08:00

As a proponent of continuous integration, I naturally don't endorse one IDE over another. The choice should be free and open for developers to choice what works best for them. The important thing is that the project should not be reliant on an IDE to build. That is, there must be an independent build tool that can function outside of any IDE, whether it be ant or maven or whatever.

I have used several IDEs over the last couple of year to include Eclipse, IDEA and NetBeans . They all have their strengths and weakness and for the projects I have been working on, I ended up switching around quite a bit. With the recent announcement of the new Netbeans 6.0, I wanted to revisit it's capabilities and see what was new, particularly with its maven integration.

While the Netbeans installer was downloading, I started to search for what plugins I would need to do maven->Netbeans or Netbeans ->maven project conversions. Most of what I found looked outdated and didn't look easy to use. With a little stumbling around I found out that the Mevenide project does now support Netbeans 6.0 (this is not apparent on their Netbeans project page). So I installed the Mevenide Maven2 plugin.

And was blown away!

There is no conversion of project types from maven->NetBeans . It just works natively. File > Open Project and browse for your existing maven project. Bingo.

I actually started by opening a parent project, <packaging>pom</packaging>, thinking that the Mavenide wouldn't know what to do with a multi module project, but it just worked, too! It showed me the project files, libraries, test libraries and the modules that this parent included. Too cool.

So then I double clicked my war module name hoping for the best and was not disappointed. It opened the war project in the project pane and I was off and running.

Right click on the project name to run the more common maven goals from right inside NetBeans. To run custom goals, you can create a Custom > Goals... goal that you can use to chain together whatever goals you want for a maven execution. This is the only thing I did that actually created a custom file on my filesystem. Everything else was native.

How's that for a slice of fried gold?

So, here's a big high five to to the Mevenide team on a job well done! (And update your NetBeans project page to highlight that it works in Netbeans 6.0. This is important news to advertise!).

Global Collaboraton In the Second Grade

2008-01-15T13:21:00.000-08:00

I just finished reading The World is Flat by Thomas L. Friedman. He had some good insights and specific example about how the world is increasingly connected and how it functions as a global marketplace. The most interesting take away I had was that simply providing the cabling into countries that had not been previously connected was enough of a spark to allow individuals with curiosity and an innovative spirit to engage a global community.

Those of us in the software business, take this interconnectedness for granted now. I find it fascinating, being a father of two, that my children will know no different; the world was always connected. In the span of a single generation the world got very small indeed. I have friends who grew up their entire life in single small town. Any road trip of more than 100 miles was a big deal. But my kids won't have to "go" anywhere to instantly know what is going on on the other side of the planet or to actively collaborate with people on other continents.

So with this in mind, I had an idea for an education software project. My second-grader already has computer lab class once a week where he and his classmates learn and solve problems on a standalone system. What better time to learn about teamwork, on a global scale, then now, while he is in school.

My idea is a collaborative system that lets kids work together to solve and reinforce basic school (and life) skills. As math is a universal language, it would be a good first subject.

Picture this:

The system is browser-based and has a easy to use, friendly RIA interface.
One student from the USA joins the "Collabmath" course; One student from India joins the same course and they are paired together to solve 5 math problems.
Each student will have a friendly avatar with their county's flag next to it. Each student's name can be clicked on to hear it pronounced in the native language. Google maps can show each student's school marked on a world map.
The math problem will be presented in a large left hand workspace, and a chat window could be in a right-hand pane.
The chat window can be used by the students to provide encouragement or ask for help. The chat would be I18N capable and feature emoticons that would make the session more personable.

Each student takes turns solving a problem a step at a time. When each step is complete, control transfers to the other student, and so on. So, for a simple example, if the problem is to draw an octagon, the first student will draw the first line segment, then the second student will draw a complementary line segment connected to the first. When the octagon is complete, the students will have worked together to solve the problem.
At the conclusion of each problem, a practical real world example of the use of that problem in each culture could be presented. In my example, the students would learn that in America, the octagon is the shape of a traffic stop sign; a related symbolic example could be presented that would be relevant in the country of India.

A wide range subjects and grade levels could be taught, of course, but for starters, this could get the ball rolling. I envision my kids being excited one day, coming home from school, "Dad! Guess what? I learned division and fractions with a kid from China today! Her name was Ming Wu! It was so cool!"

I can see it. Can you?

Continuous Integration Strategies (Part IV)

2007-12-06T07:08:00.000-08:00

Bonus edition.

Check out Continuous Integration Anti-Patterns.

Continuous Integration Strategies (Part III)

2007-12-04T19:24:00.000-08:00

How do you get your code to talk to you? Continuous integration is all about automated feedback. Beyond test reports and self-describing-code there are many techniques and tools that you can use to find out if you are producing "quality" code.

When you pick the right reports and integration them into the software build, the level of effort required to use these tools becomes very low (and we all know that developers are legendarily lazy).

Ideally, you should not have to remember to ask, the code should tell.

It's like being the parent of a teenager. At the dinner table you ask,

"So, how was school today?"
"I dunno."

"What did you learn?"
"Nothin'"

"Did anything interesting happen?"
"I dunno."

"How did you do on your history test"
(shrug)

You would rather he came home with the enthusiasm of a kindergartener eager to tell you about his day as soon as he gets home. No effort on your part to ask, he just gushes unprompted,

"Dad!! Guess what happened today at school?? It was so cool, I got an A+ on my spelling test!!"

That's what continuous integration can do for you.

So, recalling the computer adage, Garbage In, Garbage Out, we have carefully picked a select few reports that we feel give us a good measure of quality and integrated them into our build so that the feedback from CI is meaningful. Although several CI engines (we currently use Hudson) do have plugins to generate quality reports such as unit test results and test coverage, we feel it is important that developers have full access to run all the same reports that CI will run. Since we run maven, it is easy to plugin the reports of interest into the <reporting> section of the pom. That keeps the report configurations in source control along with the code.

So which reports do we run? Here's the rundown:

Checkstyle. Validates source code against coding standards and reports any violations. We customized the ruleset, packaged it in a versioned jar and deployed it to our maven repository. Additionally, we forced it to run as part of every build in the validate phase, and configured it to fail the build if violations are found. It's possible for an individual project to override the custom ruleset, but we don't encourage that.
PMD. Performs design time analysis of the source code against a standard ruleset. We customized the ruleset, packaged it in a versioned jar and deployed it to our maven repository. Additionally, we forced it to run as part of every build in the validate phase, and configured it to fail the build if violations are found.
Test Results (surefire). This is a no-brainer. You want to see the results of your tests.
Code Coverage (cobertura). Shows branch and line coverage for your source files. I think the key to using this metric is to not to set a percentage that the project team must meet, but to be smart about interpreting the trends. "Metrics are meant to help you think, not to do the thinking for you."
Javadoc. Creates the API documentation for your project.
Dashboard. Aggregates maven multiproject build reports into a single report page. This is critical so that developers and stakeholders don't have to hunt and drill down page after page to find the meaningful metrics you worked so hard to set up.

In addition, make full use of Maven's pom to declare all the sections that feed the default generated site, including:

<scm> Source control management. New team members, for example will need to know the subversion URL for checkout.
<developers> Identifies subject matter experts and feeds developer activity reports.
<ciManagement> Identifies the CI engine being used and the URL to see the live status and force new builds.
<issueManagement> Identifies the issue tracking system. I think there are maven plugins that will map issues to source control commits, providing bi-traceability of code to requirements.

Also, don't forget for maven multiproject builds to review the Dependency Convergence report. It will show all dependencies for all projects along with the versions of those dependencies. This will help you find dependencies your using inadvertently using multiple versions of.

Once you have these reports baked in, make the results easy to find. Use your CI engine to generate the maven site on a nightly basis and publish the results to a web server where developers or project stakeholders can find them.

After you spend the time and effort to identify which reports you want and get them configured and working correctly, make it repeatable for new projects by creating an archetype template project. This sets up a model pom.xml and project directory structure right off the bat for new projects. When it's there from the start, with no effort on the team's part, good things happen.

With a little up front effort, your code (with a little help from continuous integration) can talk to you. What are your strategies? How do you use CI to reveal code quality? I would be interested in hearing your strategies.

"The people are the network"

2007-11-02T08:05:00.000-07:00

I found this fantastic read that expands globally off of my previous "organization-charts-get-in-the-way" post. It is long, but well worth the read.

Mob Rules (The Law of Fives)

This is my favorite quote from the text:

“The net regards hierarchy as a failure, and routes around it.”

The summary is equally short and powerful:

"Still, there is one thing I can recommend: have courage and keep moving. Standing still is not an option."

Continuous Integration Strategies (Part II)

2007-10-31T10:39:00.000-07:00

Your CI environment is reporting a broken build. Now what?

I would like to stress that the faster you jump on the problem, the easier it is to solve. The changeset will be smaller and the person who most likely committed the offending code will have the changes he made freshly in mind.

It is a good policy that your team does not commit any additional changes to source control until the build is fixed.

At times, it is too easy to ignore a broken build message, whether it is an email notification or a flashing red light or a lava lamp. Sometimes, the team will assume someone else is working the issue. I will always recommend having immediate and active communication that the problem is being worked so that positive control in maintained.

There were some additional words of wisdom that recently circulated here that I would like to share with you. Props to Chad for nailing the importance of the entire team owning CI and having active communication about its status. The emphasis is mine.

Make sure you're at least running unit tests before you commit. You can also have a buddy immediately update and build if you want feedback before waiting for Cruise Control to build. Also, after you commit, watch your email for a notification that the build has broken. If you're not going to be around, use a check-in buddy as mentioned previously.

If you've just committed a change and receive a build failure notification email, look into what's causing the problem asap. If it's a quick fix, just make the change and re-commit. Optionally reply to the build failure notification so that the team is aware you're putting in the fix. If it's not a quick fix, reply to the build failure notification stating that you're working the issue; again so the team is aware.

...The build is everyone's responsibility.

If you see that the build is remaining broken for a period of time, take it upon yourself to investigate. Find out if anyone is working the issue. If not, try to identify the problem and notify the party responsible so that the build can be fixed quickly. Now if you can't figure out what's wrong and identify who is responsible, take it upon yourself to fix the issue. If you are too busy, find someone that can. If you can't figure it out, ask for help. Use it as an opportunity to learn something. When you do finally find the problem, let the responsible party know what happened. Then they can learn something as well.

To sum it up, there shouldn't be any duration of time where the build is broken but isn't being looked into. While everyone should be watching after they commit to see if they've broken the build, it won't always get caught. You shouldn't be saying to yourself "I didn't break it so it's not my job to fix it".

And that's the word.

Continuous Integration Strategies (Part I.I)

2007-10-19T12:29:00.001-07:00

At the end of each successful continuous integration build and test suite, we label the workspace with a certified build tag within source control. This allows for bi-traceability from build sequence number to the tag name for QA purposes. Additionally, we can also do a simple lookup on the build number in Hudson to get a subversion revision number.

Below are two examples of how we have accomplished this.

Maven 1 and cruisecontrol and cvs:

We wrote a custom jelly goal that called ant's cvs task.


<goal name="nct:createcertifiedtag">
 <ant:cvs command="tag certified-build-${label}" />
</goal>

Notice the "label" property. Cruisecontrol provides maven that property to use at runtime with the value set to the build number. We use this custom goal at the end of the cruisecontrol project's maven goal element:


<maven projectfile="${PROJECT_ROOT}/project.xml" goal=clean install nct:certifiedtag" />

Maven 2 and hudson and subversion:

In the maven pom.xml (or the parent pom.xml), specify the all the source control details so things become easier later. For example, our build includes:


<scm>
 <connection>scm:svn:https://svnhost/svn/sto/trunk</connection>    
 <developerConnection>scm:svn:https://svnhost/svn/sto/trunk</developerConnection>
 <url>https://svnhost/svn/sto/trunk</url>
</scm>

Hudson provides maven a "hudson.build.number" property to use at runtime populated with the build number. We use it by referencing that on the Goals line in the Hudson job configuration. Additionally, we made an improve over using an external process call to 'svn' by using the maven 2 SCM plugin.

clean install scm:tag -Dtag=certified-build-${hudson.build.number}

[update: ${hudson.build.number} seems to be buggy. I have successfully used ${BUILD_NUMBER} in its place]

Continuous Integration Strategies (Part I)

2007-10-18T19:11:00.000-07:00

Continuous integration is a powerful concept, usually associated with only compilation and unit testing. However, there is additional benefit to be had if you look beyond unit testing. I would like to present some strategies that I have tried that allow full suites of tests to be ran in orderly stages, from unit tests, to integration tests to acceptance tests. For this series unit tests are defined as single class tests with no external dependencies on network or container resources. Integration tests are white box testing of class interactions and acceptance tests are black box system tests.

This first post on the subject deals with strategies using maven and cruisecontrol. Later posts will move on to maven 2 and hudson.

First off, a lesson learned. When we first migrated from ant to maven, we were not sure how best to configure cruisecontrol to handle CI. Our code base is a large selection of components that comprise a toolset of capabilities. There are many small projects that build on each other, so there are many dependencies on our on artifacts. In fact, from a maven point of view, we could build our toolset with a single, rather large, multiproject build.

It seemed logical to map each component maven project (itself a multiproject consisting of api + implementations + tests) to a cruisecontrol project. That presented a nice one-to-one view of the system on the build status page. Each project was independently triggered via cvs commits. This seemed to work for awhile, but it became clear that this is highly unstable because commits spanning multiple cruisecontrol projects would trigger the builds in an unpredictable order, causing the build to break or tests to fail.

The lesson learned and correction we took was to not fight maven, but let it determine the build order from start to finish. So we created a single cruisecontrol project, pointed it at the top-most maven project.xml with the goal multiproject:install and the property -Dmaven.test.failure.ignore=true. Then for each component project we wanted test status granularity on, we created a cruisecontrol project that ran a custom maven plugin that scanned the test-results directory and failed that project if test failures were found. Additionally, that cruisecontrol project also used <merge> to aggregate maven's test-results files so our developers could drill down and see which test failed and the details why.

As a quick aside, Hudson has very nice maven integration that mimics (and improves on) this kind of setup automatically.

Our next step was to enable a controlled progression of testing, where all unit test would run first, followed by integration tests only if all unit tests passed. This was accomplished in three steps: 1) one maven multiproject build responsible for compiling and unit testing, 2) a custom test failure check plugin (basically find + grep) serving as the go-no-go gate, then 3) another maven multiproject build running only integration tests. This three step orchestration was handled by a custom maven plugin running a mix of jelly and shell scripting.

The different types of tests were in different directories, as maven subprojects, under the component, so we were able to use maven.multiproject.includes and maven.multiproject.excludes on the directory names to achieve steps 1) and 3) above.

To facilitate the the including and excluding for the unit test pass, the ~/build.properties included these properties:

  maven.multiproject.includes=**/project.xml
 maven.multiproject.excludes=project.xml,*/project.xml,**/inttest/project.xml,**/tck/project.xml

For the integration test pass, the ~/build.properties included these properties:

  gcp.integration.multiproject.includes=**/inttest/project.xml
 gcp.integration.multiproject.excludes=**/tck/project.xml

and the plugin goal to actually run the integration tests looked like this:

  <goal name="gcp:integration-tests">
   <j:set var="usethese" scope="parent" value="${gcp.integration.multiproject.includes}"/>
   <j:set var="notthese" scope="parent" value="${gcp.integration.multiproject.excludes}"/>
   <j:set var="thisgoal" scope="parent" value="test:test"/>
   ${systemScope.put('maven.multiproject.includes', usethese)}
   ${systemScope.put('maven.multiproject.excludes', notthese)}
   ${systemScope.put('goal', thisgoal)}
   <maven:maven descriptor="${CC_HOME}/checkout/gcp/project.xml" goals="multiproject:goal"/>
 </goal>

The crazy jelly maneuvering to get the includes and excludes properties to stick after the call to maven:maven is a story for another day. (If you want a sneek peek, however, start here.) The concept of dynamically using maven properties to properly setup the integration test run should still be clear.

Hopefully, this first post in a series will help you think about ways to get more out of your CI environment. I'm curious to know what you think about the strategy we took and I invite you to share how you accomplish CI for your projects.

Hudson, At Your Continuous Integration Service

2007-10-10T13:35:00.000-07:00

I love Hudson. I have previously been a CruiseControl fan, but no longer. Hudson just works and has some excellent integration features with Maven2 and Subversion.

Generally, Hudson does this kind of stuff you would expect from a CI engine:

Easy installation: Just java -jar hudson.war, or deploy it in a servlet container. No additional install, no database.
Easy configuration: Hudson can be configured entirely from its friendly web GUI with extensive on-the-fly error checks and inline help. There's no need to tweak XML manually anymore, although if you'd like to do so, you can do that, too.
Change set support: Hudson can generate a list of changes made into the build from CVS/Subversion. This is also done in a fairly efficient fashion, to reduce the load of the repository.
RSS/E-mail Integration: Monitor build results by RSS or e-mail to get real-time notifications on failures.
JUnit/TestNG test reporting: JUnit test reports can be tabulated, summarized, and displayed with history information, such as when it started breaking, etc. History trend is plotted into a graph.
Distributed builds: Hudson can distribute build/test loads to multiple computers. This lets you get the most out of those idle workstations sitting beneath developers' desks.
Plugin Support: Hudson can be extended via 3rd party plugins. You can write plugins to make Hudson support tools/processes that your team uses.

Then the cool stuff kicks in!

Since each build has a persistent workspace, we can go back in time to see that workspace to trace what happened. This means Hudson can do after-the-fact tagging and has permanent links to all builds, including "latest build"/"latest successful build", so that they can be easily linked from elsewhere.

I really like the matrix style jobs that you can create. For a matrix build, you can specify the JDK version as one axis and a slave Hudson (distributed builds) as another axis. Add to that a third axis of arbitrary property/values pairs that your build understands and can act on (e.g. think, maven -PmyProfile or -Dapp.runSystemTests=true or -Ddatabase.flavor=mysql). This is powerful stuff right out of the box to support multiple compilers, OSes, etc., without having to create a new job for each configuration.

For maven 2 projects, Hudson will autodiscover the <modules> in a multiproject build and list them as sub-jobs in Hudson, complete with their own status and viewable workspaces. Links to project artifacts are linked to from the build status pages.

The plugins are also starting to become plentiful. There are plugins for JIRA and Trac integration, code violations charting, publishing builds to Google calendar!, and many more. The one with the most potential I think is the Jabber plugin. Not only can it send IM notifications to an individual or a group, but the newest (cvs head) version comes with a bot that you can interact with to schedule builds, get project statuses, and monitor the build queue.

As always, sometimes small things mean a lot. An example I appreciate in Hudson is seeing the build in progress scrolling by via the browser. For CruiseControl, you would have to login to the build box and "tail -f" to get the same real-time information.

I'm not a groovy fan yet, but I was blown away when I found a built in groovy console right there in the web UI! You can use for trouble-shooting and diagnostics of your builds or plugins.

All in all, I am really, really impressed with Hudson as a product, and with the support and development going on around it. There is a new version released literally every week. It makes me, for the first time, want to contribute to an OSS project. This is good stuff. Check it out.

"Continuous Partial Attention"

2007-10-08T07:53:00.000-07:00

I have blogged about being a "knowledge worker" before, but just found another good slideshare resource about it thanks to a link by Jim S.

The funniest thing was on slide 25 where a knowledge worker is described as having "Continuous Partial Attention."

I love that description.

I work with several people who exhibit this trait and it is one the key characteristics, I think, that makes them successful in the workplace. To be sure, they are also criticized because their team-level focus seems to be lacking, however, this is made up for in the bigger benefit to the company. This is just another way to transcend team boundaries and have organization-wide impact.

And the reason it's funny is because it's true.

How to Host a Web Server at Home With Dynamic DNS

2007-09-25T23:29:00.000-07:00

There are a lot of moving parts to get right to do this, and not a lot of good advice about how to do it successfully. I hope that my steps will help you get it right the first time.

My need for an at home hosted web service came from trying to develop a simple FaceBook application. I needed my application hosted somewhere quick and didn't want to pay for hosting. I'm comfortable using Tomcat to host my java applications, so I decided to try to host my application at my computer at home for easier development and debugging.

The trick for hosting a site that is publicly accessible is to be able to use a non-moving target for DNS servers to resolve. Since most people don't get a static IP for home use without paying extra for it, they are stuck with a Dynamic IP address. This means that behind the scenes, you are "leasing" the IP address for a period of time, after which it is revoked and another address is assigned to you. For normal internet use, this is a seamless operation, but for web hosting we need a little help. I suggest using the free service offered by DynDNS to do hostname to Dynamic IP mapping. With their service you can create a hostname (for example, http://codebeneath.dyndns.org, a subdomain to dyndns.org) and configure that to resolve to your current IP address, which they detect for you. Or if you prefer, hit IP Chicken :)

Now, you need a way to detect when your IP address changes and automatically update your DynDNS entry. There are standalone clients that can do this, but I was lucky enough to have the capability built into my router, a LinkSys BEFSX41.

I have heard that some internet providers block port 80, so I decided just to use the default Tomcat port, which is 8080. If you stick with port 80 and run into problems, this may be the cause.

Next, we need to configure the router to forward all incoming port 8080 traffic to Tomcat. There are several ways to do this, depending on your router. The solution I don't recommend is enabling the DMZ Host setting (this is overkill and a potential security problem if you don't know what you are doing). The remaining alternatives are Port Range Forwarding and UPnP Forwarding. Port Range Forwarding is geared more for specialized internet applications such as videoconferencing or online gaming and can be used to forward an entire block of address at once.

For my case, I picked the simplest thing that worked: UPnP Forwarding. When I started, this was not the clear choice of how to do this, and many differing opinions steered me to conflicting directions. Compounding my confusion was an out-dated router firmware that provided administrative pages with different terminology and that did not even have UPnP Forwarding as an option.

I do recommend updating your router's firmware to avoid the same confusion I had and to have the latest security patches in place.

Login to your router by pointing your browser at the admin URL. For my LinkSys, the admin URL is http://192.168.1.1/. The default username is blank (none) and the password is "admin"

If you still have your default password, change it immediately before proceeding further!

Click "Applications and Gaming" > "UPnP Fowarding".

On the first blank line enter "tomcat" as the application name, "8080" as the Ext. Port, "TCP" as the protocol to allow, "8080" as Int. Port, your internal network address (e.g. 192.168.1.xxx) and mark the Enabled checkbox. To obtain your internal network address, open a command shell and type ipconfig. A gotcha to watch out for is that your internal address may also be dynamic if your router assigns addresses via DHCP. To avoid this, you could statically configure your network devices addresses, but for my purposes DHCP was OK.

Save the router settings and close your browser.

Start Tomcat and make sure you can access http://localhost:8080. If so, then try the public address you created at DynDNS (in my case http://codebeneath.dyndns.org:8080). If all is well, you should be seeing the Tomcat welcome page! Deploy your web application and happy web hosting.

Broncos, 2-0

2007-09-18T06:42:00.000-07:00

tHERE gOES gRAVITY

2007-09-13T23:44:00.000-07:00

What's another word for 'empowered'? I don't like it because it is overused as a corporate buzzword and under appreciated as a game-changing concept. It's the concept that I like. In your company, do you feel free to cross those invisible corporate boundaries to make things happen? To discuss, collaborate, act? I'm lucky enough to work for a company that makes me feel that way. And it's not because they make a big announcement heralding the idea to the masses: "You are empowered to make decisions".

I've heard that before and it wasn't true. There were still job titles, egos and chains of command to contended with.

'Empowered' sounds like you're being granted permission from those higher up the food chain to act. I guess the people surrounding me today, the CEO, the CIO, and my co-workers make me want to be Accountable; a concept I believe is self-granted. If I have an idea, I can own it, grow it and make it work. And not as a solo effort, either. We are encouraged to reach out and work directly with the people who can make ideas into reality.

The actions I see on a daily basis speak louder than any words to confirm this. After being hired, I met several of people in senior leadership positions in the company. As an example of their commitment to keep the communication channels open, they were adamant that there should not be an company organization chart.

Not this:

This:

No artificial power structures in place or asking permission from the boss to talk to your peers who happen to work in a different department or on a different contract. As an organization, we are very flat, by design, and it Just Works. It's like a big tree, whose branches are weighed down by an ice storm, all suddenly shake free their icy repression and spring up to the same height as the highest branch.

oh, tHERE gOES gRAVITY!

Being in an environment like this has changed me. I am no longer in a cubicle reporting to a single boss. I am one of many influences in the company who increasingly don't see team boundaries, we see Singularity. We see opportunities to improve our business and our culture and we're making it happen.

This is individual accountability to own and promote ideas and to collaborate as a next generation enterprise using lightweight, online tools (including the phone!) to make it easy. This is collaborating on ideas on your corporate wiki. This is sharing your bookmarked feeds collectively through Yahoo Pipes. This is about sharing your experiences and knowledge by blogging about it. This is keeping a pulse on new technologies, not for your team, but for other teams in the company. This is a call.

This is the Manifesto that I believe in.

As Charlie says, "Advertise yourself", your knowledge and what you are passionate about, so when the time comes, people will also reach out to you to collaborate with.

Even with obstacles removed from your path, it can still be tough to follow through. I am out of my personal comfort zone on a regular basis. However, I know it's the way forward, for my company, but most importantly for me. It's my way of providing leadership at work. I can't do it with words. I have to do it by leading by example.

You can, too. Make it an infectious attitude. Lose Yourself.

Simple SOAP posting from the command line

2007-08-30T08:15:00.000-07:00

From the linux command line, you can do use curl to submit a soap file to a URL.

curl -H "Content-Type: text/xml; charset=utf-8" \
     -H "SOAPAction:" \
     -d @soap.txt \
     -X POST http://localhost:18181/httpWSDLService/httpWSDLPort

where the @ specifies a file as input and soap.txt is the file.

Microformats: A DoD Use Case

2007-08-28T15:32:00.000-07:00

Microformats have been around awhile, but I have just recently took the time to find out what they are and what they can do. A good starting place I can recommend is microformats.org. Basically, using microformats means adding attributes to existing html elements to enhance the meaning of the content.

The physical address presented on this blog is marked up, for example, as a hCard.

<div class="vcard">
  <div class="adr">
    <div class="org fn">
      <div class="organization-name">Gestalt-LLC</div>
    </div>
    <div class="street-address">320 East 4th Street</div>
    <span class="locality">Joplin</span>, 
    <abbr class="region" title="Missouri">MO</abbr>
    <span class="postal-code">65801</span>
  </div>
</div>

This could be thought of as a lightweight semantic web enabler. And the beauty of course is the simplicity of it. It is suitable for use in marking up HTML, RSS, Atom or XML.

So now the question: what could be accomplished with microformats? What might be a scenario in a military domain?

A soldier is observing and recording enemy aircraft taking off from a hostile airfield. He microblogs about it on a ruggedized PDA marking up the aircraft information in a military airframe microformat (date, time, aircraft type, payload configuration, number of aircraft in formation, observed tail numbers, for example).
This is an unanticipated observation, so the data may not be immediately useful or actionable.
But, Google will find it (and yes, the DoD has Google appliances running on their classified networks). Not necessarily based on the microformating, but based on its normal searchable content. Technorati, however, does have a microformat search engine.
These search results are microformat parsed and fed into a Temporal Analysis System (TAS) whose job in life is to predict the future by comparing recent events with similar historical events chains and their outcomes.
It turns out that what the soldier observed, perhaps 10 cargo aircraft, all with extra fuel pods, bearing NNW, from grid reference 18SUU8401, is a 90% predictor that the hostile battalion will be mobilizing and deploying in 72 hours.
Useful information to know derived from someone outside the normal chain of command and information flow!

Powerful and simple.

Source Control Tips for Netbeans Projects

2007-08-27T07:08:00.000-07:00

This post is specifically for SOA projects centered around JBI composite applications and service units, but I think 90% would still apply to any project type. If you create the projects inside of NetBeans and use an external source control tool, like SmartSVN, these are the directories you'll want to exclude and ignore.

For a service unit project, like a BPEL module, exclude

build
nbproject/private

For a composite application, exclude

build
dist
nbproject/private
src/jbiasa
src/jbiServiceUnits

After you successfully commit the projects, make sure the above directories stay out of subversion by setting the ignore property. In SmartSVN, do this by clicking on the the project name and using the menu bar to select Properties > Edit Ignore Patterns.... Enter the directory names, save and don't forget to commit!

Procrastination

2007-08-21T13:06:00.000-07:00

Hard work often pays off after time, but laziness always pays off now.

Using BPELs doXslTransform() function

2007-08-21T12:04:00.001-07:00

As a improvement to my previous design of aggregating RSS feeds from various continuous integration systems, I wanted to do a simple XSL transform to make my post-processing easier. If I could get each element to be on it's own line, then things become much easier for the later parsing that I have to do.

Given that I am using OpenESB and JBI to accomplish my goals, I have two choices of how to perform the transform. 1) Use the XSLTSE or 2) Use the BPEL function doXslTransform(). I choose the latter option because it was the simplest thing that worked. (I will have another post about using the XSLTSE though. Stay tuned!)

To start, I created the XSL stylesheet that takes input and produces output that validated to the same schema (rssbcext.xsd in this case). Then in my Netbeans BPEL editor, I clicked on the Assign1 operation.

This brings up the BPEL Mapper. Add the doXslTranform functoid (and no, I did not come up with that term).

The Netbeans tooling is not yet complete for this function, so we have to add the stylesheet file-name as a URN string literal. In my case it was 'urn:stylesheet:citransform.xsl'. Drag the RSSConsumerWSDLOperationIn.part1 to the node-set and drag the return-node to the FileWSDLOperationIn.part1.

Clean and Build, then deploy to Glassfish. That's all there is to it. My RSS feeds are now in a compact format, making my processing easier and saving valuable disk space. :)

Using JBI To Keep An Eye on Continuous Integration

2007-08-17T13:00:00.000-07:00

I'm a big fan of Continuous Integration. We thrive on it at work to get feedback for our code integration on a constant basis. As part of a bigger company effort, we wanted to be able to create team dashboards showing CI health (server up, building, not broken too long, etc). The teams here mostly use CruiseControl, but we also a few teams utilizing Hudson and Luntbuild.

So what's an easy way to keep tabs on 3 different build systems? RSS of course!

CruiseControl publishes out an RSS feed, Luntbuild publishes an ATOM feed and Luntbuild recently added RSS and ATOM feeds (committed, but not distributed yet, as of 1 Aug 2007).

And I don't want to write any code to aggregate these feeds together.

Enter JBI, Open-ESB, and the RSS Binding Component (BC).

Start by downloading the latest Open-ESB/Glassfish bundle. Start up Netbeans. To subscribe to multiple RSS feeds via the RSS BC, we need an RSS provider and an RSS consumer composite application.

Create the provider BPEL module by creating a new Netbeans project (New Project > Service Oriented Architecture > BPEL Module). Name it CIProviderBpelModule. Now we need to import two xml schemas into our project (rssbcext.xsd and wsaext.xsd). Follow the steps outlined here to do the imports.

The WS-Addressing extension schema is used to have access to the element EndpointReferenceList, which we'll use to feed the RSS feed URLs into the system via a SOAP request.

Create two WSDLs, one for http and the other for rss, with the New WSDL Document wizard.

On the Name and Location step, name the rss WSDL "rssciprovider" and import the rssbcext.xsd schema, By File, with a prefix of "rssbcext". On the Concrete Configuration section, make sure RSS is selected as the Binding Type.

On the Name and Location step, name the http WSDL "httpci" and import the wsaext.xsd schema, By File, with a prefix of "wsaext". On the Concrete Configuration section, make sure SOAP is selected as the Binding Type.

At this point both WSDLs should validate (Alt+Shift+F9) correctly. This will make sure all schemas are imported correctly.

Open the httpci.wsdl and navigate to the request message part1. Click the element and then in the Properties pane of Netbeans, change the element attribute from type="xsd:string" to element="wsa:EndpointReferenceList" Do the same for the reply message part1. (Make sure you pick element and not type. Thanks James!).

Open the rssciprovider.wsdl and navigate to the request message part1. Change the type to an wsaext element EndpointReferenceList as above. You can also remove the reply message and the output from the operation and binding as this will be an In-Only message. For the binding operation, change the input to . For the service port change the rss:input to . This correlationId is important and will match up to a correlationId in our rssciconsumer.wsdl.

Validate the WSDLs and then Process Files > New > BPEL Process. Give it a name "rssProviderBpelProcess". Drag and drop the two WSDLs into the process flow diagram; this will create partner links. Name them "httpPartnerLink" and "rssProviderPartnerLink". Swap Roles for the rssPartnerLink to "Partner Role".

From the Palette pane, drag and drop Receive, Assign, Invoke, Assign and Reply operations onto the BPEL flow. Edit Receive1 to point to the httpPartnerLink and create an input variable. Edit Invoke1 to point to rssProviderPartnerLink and create an input variable. Edit Reply1 to point to httpPartnerLink and create an output variable. Click Assign1 and using the BPEL Mapper pane at the bottom of Netbeans drag a line from HttpciOperationIn.part1 to RSSciOperationIn.part1 (ignore data types don't match warning).

For the SOAP response, we will just hardcode something to acknowledge the RSS provider is subscribed. Click Assign2 and using the BPEL Mapper create a String Literal with a value of "Done.". Drag a line from the String Literal to HttpciOperationOut.part1.

Validate the BPEL file.

Create a new Composite Application project "CIProviderCA" and add the JBI Module project CIProviderBpelModule to it. Clean and build.

Halfway there!

Create the consumer BPEL module by creating a new Netbeans project named CIConsumerBpelModule. Import the rssbcext.xsd schema into the project.

Create a rssciconsumer.wsdl with the rssbcext.xsd schema imported as before. Make sure "RSS" is selected as the Binding Type. Edit the wsdl and change the message part element to element="rssbcext:EntryList". Change the operation input to . Change the service port address to .

Create a fileci.wsdl with the rssbcext.xsd schema imported as before. Make sure "File" is selected as the Binding Type. Edit the wsdl and change the message part element to element="rssbcext:EntryList". Remove all output references; In-Only again. Change the operation input to .

Validate the WSDLs and then create a new BPEL Process named "rssConsumerBpelProcess". Drag and drop the two WSDLs into the process flow diagram; this will create partner links. Name them "filePartnerLink" and "rssConsumerPartnerLink". Swap Roles for the filePartnerLink to "Partner Role".

From the Palette pane, drag and drop Receive, Assign, Invoke operations onto the BPEL flow. Edit Receive1 to point to the rssConsumerPartnerLink and create an input variable. Edit Invoke1 to point to filePartnerLink and create an input variable. Click Assign1 and using the BPEL Mapper drag a line from RssciconsumerOperationIn.part1 to FileciOperationIn.part1 (ignore data types don't match warning).

Validate the BPEL file.

Create a new Composite Application project "CIConsumerCA" and add the JBI Module project CIConsumerBpelModule to it. Clean and build.

Start glassfish and deploy both JBI Composite Applications to it.

In the provider CA project, create a test a new test case, pointing it to the httpci.wsdl and the httpciOperation. Sweeeeeeeeet. Edit the test case input. Each Endpoint reference only needs the Address element to be valid. Add as many as EndpointRerefences as you need to the EndpointRerefenceList. Run the test.

Look in C:\Temp (or whatever directory the file service port referenced) and you should see a ci-feeds.xml file with an aggregation of all the continuous integration RSS/ATOM feeds in it.

Accountability and the Knowledge Worker

2007-08-13T10:00:00.001-07:00

Are you a Knowledge Worker? Fred Nickols really sets the framework for how companies can really make a difference when they are drive by a new breed of accountable individual (any he did this back in the '80s)

I seek out and I set direction.
I resist supervision; I welcome support.
I work at my own pace within the constraints posed by the situation.
I put my name on what I do -- and the names of those who contribute in any way to any endeavor for which I am accountable.
I promote, praise, recognize and reward accomplishment and service.
I contribute more than I consume.
I seek control over myself and influence over events about me.
I care about my work -- it is a reflection of me.

I care about the enterprise of which I am a part and I will do my best to protect it against all threats -- whether they are external or internal.
I care about the people with whom I work; they are not just co-workers or colleagues -- they are also friends, allies and comrades.
I refuse to simply "obey orders" and "go along with the program."
I will hold my superiors as accountable for their actions as they hold me accountable for mine.
I will not turn a "blind eye" or a "deaf ear" to wrongdoing at any level of any organization of which I am a part.
I will do my best to share what I know with those who are interested in learning from me and I will do my best to learn from those who are skilled, knowledgeable or competent in areas I am not.
I will at all times strive to advance and improve the knowledge base that undergirds my skills, abilities and accomplishments.

This ties in nicely with the theme of accountability. What it's not: imposed on you by others. What it is: self-directed behavior.

Testing Karma

2007-08-01T07:59:00.000-07:00

I think Earl said it best when he said "Do good things, and good things happen." What kind of good things? How about good software engineering practices? Use Case modeling, sequence diagramming, continuous integration and automated testing are all good starts.

Diagrams and models are good because they clearly communicate intent. The picture is worth more than a thousand words if a stakeholder (or peer) can talk to the diagram and say something as simple as "delete that line and add this one", or "change the arrow to point the other way on the sequence flow". Then everyone goes, "ah... now I get it". Practices like these definitely pay dividends over waiting to fix any architectural flaw later in the lifecycle of the system.

Creating automated tests, too, are equally valuable. And not hard. And can help you develop better code. Sometimes writing unit tests after the fact can be a real head-scratcher. Thinking about the code and the test as a singular unit can help structure the code in better ways. "When you think of code and test as one, testing is easy and code is beautiful."

Also from artima :

The perfect is the enemy of the good. An imperfect test today is better than a perfect test someday.
Rejoice when they pass; Rejoice when they fail.

Be creative and flexible when writing your tests. Write that ugly test for the "untestable" code. Take that first step and good things start to happen. And when you're walking, you won't notice the steps because they will have become habit.

Unit testing advice

2007-08-01T07:46:00.002-07:00

Good stuff from the guys over at the Google Testing Blog.

I had never really given much thought to naming the methods in a unit test class. But if you give it a little though, the method names by themselves can read like a list of low-level functional requirements.

Why write test methods like

testClient() or
testURI() or
testRun()

when you can name the methods

testTryToInvokeServiceBehindFirewallDirect() or
testCompiledInputCommandIsConvertedAndDispatched() or
testWriteDataToFile()?

The rest of the world is so smart

2007-08-01T07:46:00.001-07:00

North America really needs to get with the world program. Witness:

Paper Sizes:

http://www.cl.cam.ac.uk/~mgk25/iso-paper.html

Date and Time:

http://www.cl.cam.ac.uk/~mgk25/iso-time.html

and of course the Metric System:

http://www.cl.cam.ac.uk/~mgk25/metric-system-faq.txt

Words from the guy who was responsible for the Google SOAP API

2007-08-01T07:44:00.000-07:00

Nelson Minar doesn't work for Google anymore and bears no ill will that Google yanked the SOAP API that he was responsible for. If fact, he has a pretty negative view of SOAP, its interoperability problems and brittleness.

But I particularly liked the last sentence of his post, "Just do something that works". It ties in nicely with my last post, Solving The Problem in a Very Good (Not Perfect) Way.

http://www.somebits.com/weblog/tech/bad/whySoapSucks.html

Perfect is the enemy of Very Good

2007-08-01T07:27:00.000-07:00

I found this a good, quick read and helpful as a reminder on how to tackle hard problems. My takeaway was to take action and not wait until "all the data is in" before making a decision. In short, deliver the Very Good as opposed to Perfection. As the CEO of the company I work for said recently, working in a vaguely correct direction is better than standing still. [Update: In the software business, the remark about "working in a vaguely correct direction is better than standing still" works because of Scrum. If you are talking to your client and demonstrating your solution every 30 days, your can have that meaningful conversation where both parties refine the problem and the solution together.]

The full discussion for the quotes below is here: http://pliantalliance.org/?p=34

Never let perfect stand in the way of very good.

It may be tempting to wait until you have the time, the knowledge, or the inclination to design the “perfect” solution, especially if you aim to solve the real problem. However, you must temper this instinct with practicality. While it may look like you are holding out for “the perfect solution” (that solves the whole, real problem), what you are really doing is preventing “the very good solution” that can be applied in the interim. We must recognize that perfection can only be approached asymptotically through evolution of design and implementation: in essence by refining our deployed very good solutions to make them more perfect. Solving the real problem should be applied where scope allows and it should guide our path to tell us where perfect is, but we are allowed to get there in more than one step. Very good solutions have value, and value delayed is value lost.

The same site had a good collection of quotes regarding change and flexibility:

http://pliantalliance.org/?page_id=5

"He that will not apply new remedies must expect new evils; for time is the greatest innovator.."