DocBook XSL: Wrapping <programlisting> and <screen> in <pre>

Today I started looking at using a DocBook XSL customization to wrap <programlisting> and <screen> in <pre>.

What took an inordinate amount of time was not finding <xsl:apply-imports />, but instead realizing I needed to take the namespace into account. Currently this is using the 1.76.1 stylesheets.

<xsl:stylesheet ... xmlns:d="http://docbook.org/ns/docbook" exclude-result-prefixes="d"
... >
 <xsl:template match="d:programlisting">
  <pre><xsl:apply-imports /></pre>
 </xsl:template>
...
</xsl:stylesheet>

Without the d: prefix, I was scratching my head and mumbling under my breath. With the prefix, it just works.

OpenDJ: Dev Guide inside the Javadoc?

Matt Swift suggested that instead of having a separate Developer’s Guide for the OpenDJ LDAP SDK, we add the dev guide into the Javadoc.

Java developers’ IDEs already provide direct access to the Javadoc. So this idea addresses one justification for printable documentation — you can keep reading even when offline — preventing you from having to search. At the same time you can still find the Javadoc we post with an online search.  Committing doc into the code also makes it slightly easier for SDK builders like Matt to notice when making a change that affects the documentation.

Perhaps most importantly this idea leads to the “dev guide” matching the modules you actually use. In other words, if we put dev guides in the Javadoc, then when you build a Maven project that grabs org.forgerock.json.resource, i18n-framework, opendj-ldap-sdk, you get just the doc you need without having to leave your IDE. Not only lists of packages, classes, and methods, but also how-tos and so forth.

I’m still figuring out what it means in detail to, “Add the dev guide into the Javadoc.” Clearly not all of the content goes into the code. No doubt a good part of the content sits alongside the body of the code, next to or in overview.html in the main/javadoc/ folder of the LDAP SDK source.

What’s your take on the idea?

OpenAM: Deploy on WebLogic 12c

OpenAM 10.0.0 supports WebLogic 12c as a container.

First download and install WebLogic 12c for example under /path/to/wls.

1. OpenAM needs an FQDN at configuration time.
   To get started quickly, fake an FQDN on your laptop or desktop by giving the system an alias such as laptop.example.com or desktop.example.com. If you have never done so before, it’s not too hard. See the Wikipedia entry on the hosts file.
2. Restart WebLogic with enough max perm gen space to deploy OpenAM (at least 256m, -XX:MaxPermSize=256m).
   With 128m on Linux as suggested in the README.txt for WebLogic 12c, I saw this during configuration:

   Configuring Directory Server ..... 
   
   An unexpected error occurred. Not enough memory to perform the operation. Details: java.lang.OutOfMemoryError: PermGen space

3. Follow the Install Application Assistant instructions.
4. Browse to the OpenAM console such as http://weblogic.example.com:7001/openam to configure OpenAM.
   If you are not sure what to configure, see the Install Guide for hints.

OpenAM: Deploy on JBoss 7

OpenAM 10.0.0 supports JBoss 7 as a container. Victor Ake wrote a Wiki article that I followed to prepare this.

You must get JBoss 7 ready to deploy OpenAM by editing the modules it uses. You must also edit the OpenAM .war file before you deploy to specify where OpenAM stores its configuration.

Prepare JBoss 7

1. Stop JBoss.
2. Add the Sun x509 security module path to the JBoss 7 configuration.
   The following example uses JBoss 7.1.1.

   $ cp /path/to/jboss7/modules/sun/jdk/main/module.xml  /path/to/jboss7/modules/sun/jdk/main/module.orig
   $ vi /path/to/jboss7/modules/sun/jdk/main/module.xml
   $ diff -c /path/to/jboss7/modules/sun/jdk/main/module.orig /path/to/jboss7/modules/sun/jdk/main/module.xml
   *** /path/to/jboss7/modules/sun/jdk/main/module.orig     2012-04-18 14:55:21.766012573 +0200
   --- /path/to/jboss7/modules/sun/jdk/main/module.xml     2012-04-18 14:56:46.426012174 +0200
   ***************
   *** 38,43 ****
   --- 38,44 ----
   <path name="com/sun/security/auth"/>
   <path name="com/sun/security/auth/login"/>
   <path name="com/sun/security/auth/module"/>
   +                 <path name="sun/security/x509"/>
   <path name="sun/misc"/>
   <path name="sun/io"/>
   <path name="sun/nio"/>

3. Disable modules that conflict with OpenAM.
   • The following example uses JBoss 7.1.1 standalone.

     $ cp /path/to/jboss7/standalone/configuration/standalone.xml /path/to/jboss7/standalone/configuration/standalone.orig
     $ vi /path/to/jboss7/standalone/configuration/standalone.xml
     $ diff -c /path/to/jboss7/standalone/configuration/standalone.orig /path/to/jboss7/standalone/configuration/standalone.xml
     *** /path/to/jboss7/standalone/configuration/standalone.orig     2012-04-18 15:00:03.190016793 +0200
     --- /path/to/jboss7/standalone/configuration/standalone.xml     2012-04-18 15:05:12.362011635 +0200
     ***************
     *** 9,15 ****
     <extension module="org.jboss.as.deployment-scanner"/>
     <extension module="org.jboss.as.ee"/>
     <extension module="org.jboss.as.ejb3"/>
     -         <extension module="org.jboss.as.jaxrs"/>
     <extension module="org.jboss.as.jdr"/>
     <extension module="org.jboss.as.jmx"/>
     <extension module="org.jboss.as.jpa"/>
     --- 9,14 ----
     ***************
     *** 24,30 ****
     <extension module="org.jboss.as.threads"/>
     <extension module="org.jboss.as.transactions"/>
     <extension module="org.jboss.as.web"/>
     -         <extension module="org.jboss.as.webservices"/>
     <extension module="org.jboss.as.weld"/>
     </extensions>
     
     --- 23,28 ----
     ***************
     *** 163,169 ****
     </local-cache>
     </cache-container>
     </subsystem>
     -         <subsystem xmlns="urn:jboss:domain:jaxrs:1.0"/>
     <subsystem xmlns="urn:jboss:domain:jca:1.1">
     <archive-validation enabled="true" fail-on-error="true" fail-on-warn="false"/>
     <bean-validation enabled="true"/>
     --- 161,166 ----
     ***************
     *** 262,277 ****
     <alias name="example.com"/>
     </virtual-server>
     </subsystem>
     -         <subsystem xmlns="urn:jboss:domain:webservices:1.1">
     -             <modify-wsdl-address>true</modify-wsdl-address>
     -             <wsdl-host>${jboss.bind.address:127.0.0.1}</wsdl-host>
     -             <endpoint-config name="Standard-Endpoint-Config"/>
     -             <endpoint-config name="Recording-Endpoint-Config">
     -                 <pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM">
     -                     <handler name="RecordingHandler"/>
     -                 </pre-handler-chain>
     -             </endpoint-config>
     -         </subsystem>
     <subsystem xmlns="urn:jboss:domain:weld:1.0"/>
     </profile>
     
     --- 259,264 ----

   • The following example uses JBoss 7.1.1 for a managed domain.

     $ cp /path/to/jboss7/domain/configuration/domain.xml /path/to/jboss7/domain/configuration/domain.orig
     $ vi /path/to/jboss7/domain/configuration/domain.xml
     $ diff -c /path/to/jboss7/domain/configuration/domain.orig /path/to/jboss7/domain/configuration/domain.xml
     *** /path/to/jboss7/domain/configuration/domain.orig     2012-04-18 15:06:35.406024942 +0200
     --- /path/to/jboss7/domain/configuration/domain.xml     2012-04-18 15:08:13.114010802 +0200
     ***************
     *** 11,17 ****
     <extension module="org.jboss.as.ejb3"/>
     <extension module="org.jboss.as.jacorb"/>
     <extension module="org.jboss.as.jaxr"/>
     -         <extension module="org.jboss.as.jaxrs"/>
     <extension module="org.jboss.as.jdr"/>
     <extension module="org.jboss.as.jmx"/>
     <extension module="org.jboss.as.jpa"/>
     --- 11,16 ----
     ***************
     *** 29,35 ****
     <extension module="org.jboss.as.threads"/>
     <extension module="org.jboss.as.transactions"/>
     <extension module="org.jboss.as.web"/>
     -         <extension module="org.jboss.as.webservices"/>
     <extension module="org.jboss.as.weld"/>
     </extensions>
     <system-properties>
     --- 28,33 ----
     ***************
     *** 146,152 ****
     </local-cache>
     </cache-container>
     </subsystem>
     -             <subsystem xmlns="urn:jboss:domain:jaxrs:1.0"/>
     <subsystem xmlns="urn:jboss:domain:jca:1.1">
     <archive-validation enabled="true" fail-on-error="true" fail-on-warn="false"/>
     <bean-validation enabled="true"/>
     --- 144,149 ----
     ***************
     *** 246,261 ****
     <alias name="example.com"/>
     </virtual-server>
     </subsystem>
     -             <subsystem xmlns="urn:jboss:domain:webservices:1.1">
     -                 <modify-wsdl-address>true</modify-wsdl-address>
     -                 <wsdl-host>${jboss.bind.address:127.0.0.1}</wsdl-host>
     -                 <endpoint-config name="Standard-Endpoint-Config"/>
     -                 <endpoint-config name="Recording-Endpoint-Config">
     -                     <pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM">
     -                         <handler name="RecordingHandler"/>
     -                     </pre-handler-chain>
     -                 </endpoint-config>
     -             </subsystem>
     <subsystem xmlns="urn:jboss:domain:weld:1.0"/>
     </profile>
     <profile name="ha">
     --- 243,248 ----
     ***************
     *** 544,559 ****
     <alias name="example.com"/>
     </virtual-server>
     </subsystem>
     -             <subsystem xmlns="urn:jboss:domain:webservices:1.1">
     -                 <modify-wsdl-address>true</modify-wsdl-address>
     -                 <wsdl-host>${jboss.bind.address:127.0.0.1}</wsdl-host>
     -                 <endpoint-config name="Standard-Endpoint-Config"/>
     -                 <endpoint-config name="Recording-Endpoint-Config">
     -                     <pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM">
     -                         <handler name="RecordingHandler"/>
     -                     </pre-handler-chain>
     -                 </endpoint-config>
     -             </subsystem>
     <subsystem xmlns="urn:jboss:domain:weld:1.0"/>
     </profile>
     <profile name="full">
     --- 531,536 ----
     ***************
     *** 859,874 ****
     <alias name="example.com"/>
     </virtual-server>
     </subsystem>
     -             <subsystem xmlns="urn:jboss:domain:webservices:1.1">
     -                 <modify-wsdl-address>true</modify-wsdl-address>
     -                 <wsdl-host>${jboss.bind.address:127.0.0.1}</wsdl-host>
     -                 <endpoint-config name="Standard-Endpoint-Config"/>
     -                 <endpoint-config name="Recording-Endpoint-Config">
     -                     <pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM">
     -                         <handler name="RecordingHandler"/>
     -                     </pre-handler-chain>
     -                 </endpoint-config>
     -             </subsystem>
     <subsystem xmlns="urn:jboss:domain:weld:1.0"/>
     </profile>
     <profile name="full-ha">
     --- 836,841 ----
     ***************
     *** 1275,1290 ****
     <alias name="example.com"/>
     </virtual-server>
     </subsystem>
     -             <subsystem xmlns="urn:jboss:domain:webservices:1.1">
     -                 <modify-wsdl-address>true</modify-wsdl-address>
     -                 <wsdl-host>${jboss.bind.address:127.0.0.1}</wsdl-host>
     -                 <endpoint-config name="Standard-Endpoint-Config"/>
     -                 <endpoint-config name="Recording-Endpoint-Config">
     -                     <pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM">
     -                         <handler name="RecordingHandler"/>
     -                     </pre-handler-chain>
     -                 </endpoint-config>
     -             </subsystem>
     <subsystem xmlns="urn:jboss:domain:weld:1.0"/>
     </profile>
     </profiles>
     --- 1242,1247 ----

Prepare the OpenAM .war File

Edit the bootstrap.properties file to specify the configuration.dir where OpenAM stores its configuration.

$ mkdir /tmp/unpack-openam
$ cd /tmp/unpack-openam
$ jar -xf ~/Downloads/openam.war
$ vi WEB-INF/classes/bootstrap.properties
$ grep ^configuration.dir WEB-INF/classes/bootstrap.properties
configuration.dir=/home/username/openam
$ jar -cf ~/openam.war *

Deploy OpenAM

Deploy the updated .war file to JBoss 7.

1. OpenAM needs an FQDN at configuration time.
   To get started quickly, fake an FQDN on your laptop or desktop by giving the system an alias such as laptop.example.com or desktop.example.com. If you have never done so before, it’s not too hard. See the Wikipedia entry on the hosts file.
2. Start JBoss, and login to the admin console.
3. Manage Deployments > Add Content, and then choose the .war file you prepared.
4. Enable OpenAM to complete deployment of the .war file.
5. Browse to the OpenAM console and proceed to configure OpenAM.
   If you are not sure what to configure, see the Install Guide for hints.

When you reach this point, you can start working with OpenAM.

---

Notes

If like me you are not too familiar with JBoss, and want to access the console from another host, try adding -b ip-listen-address to the startup command, such as -b 0.0.0.0 to listen on all interfaces. Then in the admin console, you can set this for the admin console itself, Admin GUI > Profile > Interfaces > management > Edit… > Inet Address: Change 127.0.0.1 to 0.0.0.0. (Not a recommendation for production, but it might save you some time getting started with your evaluation.)

OpenAM: Deploy on Jetty 7

OpenAM 10.0.0 supports Jetty 7 as a container.

This one is quick once you have managed to download OpenAM and Jetty, and have unpacked Jetty for example under /path/to/jetty.

1. OpenAM needs an FQDN at configuration time.
   To get started quickly, fake an FQDN on your laptop or desktop by giving the system an alias such as laptop.example.com or desktop.example.com. If you have never done so before, it’s not too hard. See the Wikipedia entry on the hosts file.
2. Copy the OpenAM .war to the webapps/folder for Jetty.

   $ cp ~/Downloads/openam.war /path/to/jetty/webapps/

3. Start Jetty with enough memory to run OpenAM comfortably for evaluation.

   $ cd /path/to/jetty
   $ java -server -Xmx1024m -XX:MaxPermSize=256m -jar start.jar

4. Browse to the OpenAM console to configure OpenAM.
   If you are not sure what to configure, see the Install Guide for hints.

OpenAM: Deploy on GlassFish v2

OpenAM 10.0.0 supports GlassFish v2 as a container.

Before You Deploy

1. Install GlassFish v2. I found a file called glassfish-installer-v2-b58g.jar on the download site, and installed it on Linux.
2. Start GlassFish and login to the admin console (default port: 4848).
3. Under Application Server > JVM Settings > JVM Options, adjust at least the heap and permanent generation sizes, and use the server option. The following list shows changes for evaluation:
   • Change -XX:MaxPermSize=192m to -XX:MaxPermSize=256m.
   • Change -client to -server.
   • Change -Xmx512m to -Xmx1024m.
4. Restart GlassFish for your changes to take effect.

Deploying OpenAM

1. OpenAM needs an FQDN at configuration time.
   To get started quickly, fake an FQDN on your laptop or desktop by giving the system an alias such as laptop.example.com or desktop.example.com. If you have never done so before, it’s not too hard. See the Wikipedia entry on the hosts file.
2. Login to the GlassFish admin console.
3. Under Common Tasks > Deployment, select Deploy Web Application (.war).
4. Deploy the OpenAM .war. (I usually rename this one to openam.war.)
5. Launch OpenAM after deployment, and configure OpenAM.

Enjoy.

Kindle: Formatting Code and Commands?

Although Amazon’s policy around the Kindle could stand to be revised, the device itself works for me. Good for text, lightweight, long lasting battery charge, built-in Wifi, large storage (for text), relatively cheap, the Kindle suffices as a book replacement. Since I bought one last summer, 33 out of the probably 40 books I read for recreation were on the Kindle.

The Kindle should be a great way to carry around a bunch of ForgeRock documentation, too. Yet for <pre>-style text like code, long commands, wide literal identifiers like com.sun.identity.agents.config.ignore.path.info.for.not.enforced.list, and lists that use indentation for formatting, the Kindle is not so great.

The default fonts seem to allow for about 45 characters in portrait layout. Even on the 7.5′ x 9′ pages we have been using for PDF, 80 characters of monospace font can fit without sprawling into the wide left margin.

This brings me to my questions:

• How should non-trivial DocBook output be styled for the Kindle? (While this is less of a problem on something like an iPad, it may be even more of a problem on something a sys admin is sure to have when most everything else drops offline: a phone. There’s an interesting discussion on APK at docbook-apps. But what size font will you have to use to read lists, wide literals, command lines, etc.)
• And by the way, what’s the right way with Maven to build Kindle-ready output from DocBook directly?

Github: Highly Recommended

Do you work on more than one computer? Do you work on shared files with other people? Do you ever make mistakes?

Okay, enough rhetorical questions. This is not exactly news, but… Unless you need to hide your work, GitHub can help.* This is especially true for work on code, because the underlying tool, git, is built for distributed version control and source code management. Thus for work on text files where all the formatting matters, you can compare, look at what happened over time, merge independent changes, and so forth. GitHub adds the advantage giving you a place to store stuff in a way that is easy to view and to share. That’s handy even for — yuck! — binary files.

Plenty of other little features from automatically formatting a Markdown-based README to a nice source browser make GitHub more fun/less a pain in the nether regions than other solutions. If you also use another version control system, such as Subversion, then in theory you can use both together without losing any history. For my small projects, I found this not to be worth the effort.

*GitHub can also help if you need to hide your work, but you’ll have to pay for it.

OpenAM: Deploy 10.0.0 on GlassFish 3.1.2

GlassFish 3.1.2 and OpenAM 10.0.0 have some library conflicts that you can resolve. The key part of this explanation — removing glassfish-full-profile and metro packages — is from Peter Major.

Before You Deploy

Note that this is not currently a supported configuration. As Peter mentions in OPENAM-33, you might have problems in the Web Services parts of OpenAM.

Remove glassfish-full-profile and metro packages before deploying OpenAM 10.0.0. Do this either when you install GlassFish, or after you have stopped the server.

$ cd /path/to
$ unzip ~/Downloads/glassfish-3.1.2.zip
...
$ /path/to/glassfish3/bin/pkg uninstall glassfish-full-profile

The software needed for this command (pkg) is not installed.
...
Software successfully installed. You may now re-run this command (pkg).
$ /path/to/glassfish3/bin/pkg uninstall glassfish-full-profile
PHASE                                        ACTIONS
Removal Phase                                  19/19
$ /path/to/glassfish3/bin/pkg uninstall metro
PHASE                                        ACTIONS
Removal Phase                                  36/36
$ /path/to/glassfish3/bin/asadmin start-domain domain1
Waiting for domain1 to start ....
Successfully started the domain : domain1
domain  Location: /path/to/glassfish3/glassfish/domains/domain1
Log File: /path/to/glassfish3/glassfish/domains/domain1/logs/server.log
Admin Port: 4848
Command start-domain executed successfully.

Deploying OpenAM

1. OpenAM needs an FQDN at configuration time.
   To get started quickly, fake an FQDN on your laptop or desktop by giving the system an alias such as laptop.example.com or desktop.example.com. If you have never done so before, it’s not too hard. See the Wikipedia entry on the hosts file.
2. In your browser, open the GlassFish admin console.
3. Under Common Tasks > Deployment, select Deploy an Application.
4. Deploy the OpenAM .war. (I usually rename this one to openam.war.)
5. Browse to OpenAM and configure your server.

Domain Settings

As mentioned in the Installation Guide, “OpenAM core services require a minimum JVM heap size of 1 GB, and a permanent generation size of 256 MB.”

$ /path/to/glassfish3/bin/asadmin stop-domain domain1
Waiting for the domain to stop ............
Command stop-domain executed successfully.
$ cp glassfish3/glassfish/domains/domain1/config/domain.xml glassfish3/glassfish/domains/domain1/config/domain.orig
$ vi glassfish3/glassfish/domains/domain1/config/domain.xml
$ diff glassfish3/glassfish/domains/domain1/config/domain.xml glassfish3/glassfish/domains/domain1/config/domain.orig
153c153
<         -XX:MaxPermSize=256m
---
>         -XX:MaxPermSize=192m
155c155
<         -server
---
>         -client
163c163
<         -Xmx1024m
---
>         -Xmx512m
$ /path/to/glassfish3/bin/asadmin start-domain domain1
Waiting for domain1 to start ......................................
Successfully started the domain : domain1
domain  Location: /path/to/glassfish3/glassfish/domains/domain1
Log File: /path/to/glassfish3/glassfish/domains/domain1/logs/server.log
Admin Port: 4848
Command start-domain executed successfully.

After the restart, OpenAM should be ready to use.

OpenAM: 10.0.0 Released

OpenAM 10.0.0, the latest major version of ForgeRock’s open source authentication, authorization, entitlement and federation solution, is out of testing and available for download.

OpenAM 10.0.0 includes many fixes, improvements, and new features, as detailed in the release notes. The full OpenAM 10.0.0 core documentation set is available at docs.forgerock.org.

Thanks to everyone who helped with testing and doc review along the way!