Skip to main content
Last updated June 16, 2011 10:35, by Fabrizio Giudici
Feedicon  

bluebook

Use live code examples in your book. This Maven plugin allows to post-process your Java sources so they can be inserted as XML fragments in a book made with DocBook.

Configure your POM

To use the BlueBook Maven Plugin can be configured by putting this fragment in your POM.

<project ...>

    <pluginRepositories>
        <pluginRepository>
            <id>releases-oss.sonatype.org</id>
            <name>Sonatype Releases Repository</name>
            <url>http://oss.sonatype.org/content/repositories/releases/</url>
        </pluginRepository>
        <!-- configure this only if you need plugin snapshots -->
        <pluginRepository>
            <id>snapshots-oss.sonatype.org</id>
            <name>Sonatype Snapshots Repository</name>
            <url>http://oss.sonatype.org/content/repositories/snapshots/</url>
            <releases>
                <enabled>false</enabled>
            </releases>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </pluginRepository>
    </pluginRepositories>

    <build>
        <plugins>
            <plugin>
                <groupId>it.tidalwave.bluebook</groupId>
                <artifactId>bluebook-maven-plugin</artifactId>
                <version>1.0-SNAPSHOT</version>
                <executions>
                    <execution>
			... see configuration examples below
                    </execution>
                </executions>
            </plugin>
        </plugins>
        ...
    </build>
</project>

The snapshots plugin repositories needs only to be configured if you want to use a snapshot version of the plugin.


A simple example


The example is outdated. The current configuration has been improved and it's less verbose The BlueBook Maven Plugin will extract includedFragments of your example source files and store into .xml fragments that can be included in docbook sources with the xi:include directive, such as:

        <xi:include href="target/generated-sources/docbkx/FileModel.java.xml" />

All .xml fragments are stored in target/generated-sources/docbks.

Let's suppose that you have this real-world source file that you'd like to use in your book:

/***********************************************************************************************************************
 *
 * LONG license header here...
 *
 ***********************************************************************************************************************
 *
 * $Id: FileModel.java,v fd8da2c22c4f 2011/02/21 19:24:22 fabrizio $
 *
 **********************************************************************************************************************/
package it.tidalwave.netbeans.examples.nodes.example1.model;

import javax.annotation.Nonnegative;
import javax.annotation.Nonnull;
import lombok.Getter;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
import java.io.File;
import javax.swing.Icon;
import javax.swing.filechooser.FileSystemView;
import org.openide.util.Lookup;
import org.openide.util.lookup.Lookups;
import it.tidalwave.util.DefaultDisplayable;
import it.tidalwave.util.Displayable;
import it.tidalwave.util.IconProvider;
import it.tidalwave.netbeans.nodes.role.Composite;

/***********************************************************************************************************************
 * 
 * @author  Fabrizio Giudici
 * @version $Id: FileModel.java,v fd8da2c22c4f 2011/02/21 19:24:22 fabrizio $
 *
 **********************************************************************************************************************/
public class FileModel implements Lookup.Provider
  {
    @Getter
    private final Lookup lookup;
    
    private final File file;
    
    //@begin Displayable
    private final Displayable displayable;
    //@end Displayable
    
    //@begin IconProvider
    private final IconProvider iconProvider = new IconProvider() 
      {
        @Override @Nonnull
        public Icon getIcon (final @Nonnegative int size) 
          {
            return FileSystemView.getFileSystemView().getSystemIcon(file);
          }
      };
    //@end IconProvider

    //@begin Composite
    private final Composite<FileModel> composite = new Composite<FileModel>()
      {
        @Override @Nonnull
        public Collection<FileModel> getChildren() 
          {
            final List<FileModel> result = new ArrayList<FileModel>();
            final File[] children = file.listFiles();

            if (children != null)
              {
                for (final File child : children)
                  {
                    result.add(new FileModel(child.getAbsolutePath()));
                  }
              }

            return result;
          }
      };
    //@end Composite

    public FileModel (final @Nonnull String path) 
      {        
        file = new File(path);
        //@begin Displayable
        displayable = new DefaultDisplayable(file.getName(), "");
        //@end Displayable
        lookup = Lookups.fixed(displayable, iconProvider, composite); 
      }    
  }

The following configuration:

    <execution>
        <id>id1</id>
        <configuration>
            <groupId>it.tidalwave.netbeans</groupId>
            <artifactId>it-tidalwave-netbeans-examples-nodes-example1</artifactId>
            <fileName>it/tidalwave/netbeans/examples/nodes/example1/model/FileModel.java</fileName>
            <outputFile>FileModel-Displayable.java.xml</outputFile>
            <includedFragment>Displayable</includedFragment>
        </configuration>
        <goals>
            <goal>generate-filtered-source</goal>
        </goals>
        <phase>generate-sources</phase>
    </execution>

will extract this fragment:

private final Displayable displayable;
displayable = new DefaultDisplayable(file.getName(), "");

The second configuration:

    <execution>
        <id>id2</id>
        <configuration>
            <groupId>it.tidalwave.netbeans</groupId>
            <artifactId>it-tidalwave-netbeans-examples-nodes-example1</artifactId>
            <fileName>it/tidalwave/netbeans/examples/nodes/example1/model/FileModel.java</fileName>
            <outputFile>FileModel-IconProvider.java.xml</outputFile>
            <includedFragment>IconProvider</includedFragment>
        </configuration>
        <goals>
            <goal>generate-filtered-source</goal>
        </goals>
        <phase>generate-sources</phase>
    </execution>

will extract this fragment:

private final IconProvider iconProvider = new IconProvider()
  {
    @Override @Nonnull
    public Icon getIcon (final @Nonnegative int size)
      {
        return FileSystemView.getFileSystemView().getSystemIcon(file);
      }
  };

The following configuration:

    <execution>
        <id>id3</id>
        <configuration>
            <groupId>it.tidalwave.netbeans</groupId>
            <artifactId>it-tidalwave-netbeans-examples-nodes-example1</artifactId>
            <fileName>it/tidalwave/netbeans/examples/nodes/example1/model/FileModel.java</fileName>
            <outputFile>FileModel-Composite.java.xml</outputFile>
            <includedFragment>Composite</includedFragment>
        </configuration>
        <goals>
            <goal>generate-filtered-source</goal>
        </goals>
        <phase>generate-sources</phase>
    </execution>

will extract:

private final Composite<FileModel> composite = new Composite<FileModel>()
  {
    @Override @Nonnull
    public Collection<FileModel> getChildren()
      {
        final List<FileModel> result = new ArrayList<FileModel>();
        final File[] children = file.listFiles();

        if (children != null)
          {
            for (final File child : children)
              {
                result.add(new FileModel(child.getAbsolutePath()));
              }
          }

      return result;
    }
};

At last, the following configuration:

    <execution>
        <id>id4</id>
        <configuration>
            <groupId>it.tidalwave.netbeans</groupId>
            <artifactId>it-tidalwave-netbeans-examples-nodes-example1</artifactId>
            <fileName>it/tidalwave/netbeans/examples/nodes/example1/model/FileModel.java</fileName>
            <outputFile>FileModel.java.xml</outputFile>
        </configuration>
        <goals>
            <goal>generate-filtered-source</goal>
        </goals>
        <phase>generate-sources</phase>
    </execution>

will extract the whole file, with comments stripped off.

 
 
Close
loading
Please Confirm
Close