Effective Documentation

A plate of bacon, lettuce, and tomato is not a BLT sandwich until you stack the parts together. Unfortunately, too many engineers stop short of building the complete sandwich.
For example, Java XML Digital Signature API can't be used unless appropriate security service provider is registered. Otherwise, one gets a NoSuchMechanismException. To register the provider, you have to have the provider's full class name. For default JSR 105 provider, its:


but, to find that out, you'll have to google or search the jar classes or Sun source code looking for an implementation of java.security.Provider. Duh.
Anyway, to register the provider for all of your java apps, add the following line to $JAVA_HOME/lib/security/java.security file:


To register just for selected apps, add following line of code:

XMLSignatureFactory.getInstance("DOM", (Provider) Class.forName(System.getProperty("jsr105Provider", "org.jcp.xml.dsig.internal.dom.XMLDSigRI")).newInstance());

For Java 6 (aka JDK 1.6), this is done automatically since the API package is bundled.