<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
  <header>
    <title>Embedding in a Java application</title>
    <authors>
      <person id="jmaerki" name="Jeremias Märki" email="jmaerki@users.sourceforge.net"/>
    </authors>
  </header>
  <body>
    <section>
      <title>Introduction</title>
      <p>
        This page describes how to integrate <strong>Barcode4J</strong> in a 
        Java application.
      </p>
    </section>
    <section>
      <title>Basic steps</title>
      <p>
        There are several basic steps involved for generating barcodes:
      </p>
      <ol>
        <li>Provide an Avalon Configuration object to configure the barcode engine</li>
        <li>Create a BarcodeGenerator</li>
        <li>Create a CanvasProvider (depending on the output format)</li>
        <li>Finally generate the barcode</li>
      </ol>
    </section>
    <section>
      <title>Providing an Avalon Configuration object</title>
      <p>
        <strong>Barcode4J</strong> uses Avalon Framework for configure the 
        barcode symbology used. This is done in the form of a Configuration object.
        Please refer to the Avalon documentation for further examples. We simply 
        provide an example for the most frequently used approach to get such a
        Configuration object. We load the Configuration from an XML file:
      </p>
      <p>Here's an example:</p>
      <source><![CDATA[
import org.apache.avalon.framework.configuration.Configuration;
import org.apache.avalon.framework.configuration.DefaultConfigurationBuilder;

[..]
      
DefaultConfigurationBuilder builder = new DefaultConfigurationBuilder();
Configuration cfg = builder.buildFromFile(new File("C:\Temp\barcode-cfg.xml"));]]></source>
      <p>
        An XML loaded in the above way would have to look like the following example. 
        You will notice that this is basically the <link href="barcode-xml.html">Barcode XML</link>.
      </p>
      <source><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<barcode>
  <ean13>
    <module-width>0.4mm</module-width>
  </ean13>
</barcode>]]></source>
      <p>
        For other ways to build the Configuration object please check the Avalon 
        documentation or browse the source code of <strong>Barcode4J</strong>
        for more examples.
      </p>
    </section>
    <section>
      <title>Creating a BarcodeGenerator</title>
      <p>
        The BarcodeGenerator is used to generate the logical parts of a barcode 
        (narrow bars, wide bars etc.).
      </p>
      <p>
        To make it easy to create the BarcodeGenerator use the BarcodeUtil singleton 
        class. This class will choose the correct barcode implementation depending on
        the configuration you've built above.
      </p>
      <source><![CDATA[
BarcodeGenerator gen = BarcodeUtil.getInstance().createBarcodeGenerator( cfg );]]></source>
    </section>
    <section>
      <title>Creating the CanvasProvider and generating the barcode</title>
      <p>
        We combine the last two steps in one section because the last step 
        depends heavily on the other.
      </p>
      <p>
        The CanvasProvider takes the painting instructions and transforms 
        them to the target format. Depending on the desired output format 
        you need to instantiate a different class.
      </p>
      <p>
        All CanvasProvider classes support an orientation value as the last parameter. 
        Normally, you will just specify "0", but you can rotate the barcode in steps 
        of 90 degrees. Valid values are 0, 90, -90, 180, -180, 270 and -270.
      </p>
      <section>
        <title>SVG</title>
        <p>
          Here you have two classes to choose from, depending on the preferred DOM 
          implementation (W3C DOM or JDOM).
        </p>
        <source><![CDATA[
SVGCanvasProvider provider = new SVGCanvasProvider(false, 0);
gen.generateBarcode(provider, msg);
org.w3c.dom.DocumentFragment frag = provider.getDOMFragment();]]></source>
        <p>..or..</p>
        <source><![CDATA[
JDOMSVGCanvasProvider provider = new JDOMSVGCanvasProvider(false, 0);
gen.generateBarcode(provider, msg);
org.jdom.Document doc = provider.getDocument();]]></source>
        <p>
          The boolean parameter on the two constructors instruct the implementation not to use
          namespaces for the output (in this example). There are also constructors where you can
          freely choose the prefix to use. Please refer to the javadocs for more information.
        </p>
        <p>
          If you need the barcode as an XML file, it is quite simple to use basic JAXP code to 
          <link href="svg-dom.html#serialize-dom">serialize the DOM to a file</link>.
        </p>
      </section>
      <section>
        <title>EPS</title>
        <p>
          The EPS output simply takes an OutputStream to write to. One speciality is the need to
          call the finish() method after the generation because the EPS needs to be finished with
          a trailer part.
        </p>
        <source><![CDATA[
OutputStream out = new java.io.FileOutputStream(new File("output.eps"));
EPSCanvasProvider provider = new EPSCanvasProvider(out, 0);
gen.generateBarcode(provider, msg);
provider.finish();]]></source>
      </section>
      <section>
        <title>Bitmaps</title>
        <p>
          The bitmap output, like the EPS output, takes an OutputStream to write to. But in addition 
          to that it needs the MIME type (or short format type) of the desired output format. Furthermore,
          it needs the resolution of the bitmap in dpi (dots per inch), the image type (which is 
          one of BufferedImage's constants defining the color depth) and a boolean to enable or disable
          anti-aliasing. The BitmapCanvasProvider also needs a call to the finish() method to encode
          the internally built image to the desired image format.
        </p>
        <source><![CDATA[
OutputStream out = new java.io.FileOutputStream(new File("output.png"));
BitmapCanvasProvider provider = new BitmapCanvasProvider(
    out, "image/x-png", 300, BufferedImage.TYPE_BYTE_GRAY, true, 0);
gen.generateBarcode(provider, msg);
provider.finish();]]></source>
        <p>
          The example here produces a grayscale PNG with 300 dpi and anti-aliasing.
        </p>
        <note>
          Although JPEG output is supported, it is NOT recommended as it is a lossy
          compression format and contrast will suffer and thus degrading the 
          readability of the generated barcode. 
        </note>
        <p>
          Instead of writing the bitmap to a file you can fetch the BufferedImage instead. That 
          would look like this:
        </p>
        <source><![CDATA[
BitmapCanvasProvider provider = new BitmapCanvasProvider(
    300, BufferedImage.TYPE_BYTE_GRAY, true, 0);
gen.generateBarcode(provider, msg);
provider.finish();
BufferedImage barcodeImage = provider.getBufferedImage();]]></source>
      </section>
      <section>
        <title>Java2D (AWT)</title>
        <p>
          Finally, we'll want to show you how to paint a barcode on a surface of your choosing.
          In principle, you just need to provide the Java2DCanvasProvider with a Graphics2D 
          interface that it can paint on. However, since the Java2D output internally works with
          millimeters (mm) you need to make sure the Graphics2D is prepared for that. This means
          you may need to apply a transformation before painting the barcode. See the BitmapBuilder
          class for an example. BitmapBuilder is responsible to set up the Graphics2D object for
          painting barcodes on bitmaps for the bitmap output support.
        </p>
        <p>
          It's a good idea, if possible, to enable fractional 
          metrics for higher quality: <code>g2d.setRenderingHint( RenderingHints.KEY_FRACTIONALMETRICS, RenderingHints.VALUE_FRACTIONALMETRICS_ON )</code>
        </p>
        <source><![CDATA[
Graphics2D g2d = <something>
Java2DCanvasProvider provider = new Java2DCanvasProvider(g2d, 0);
gen.generateBarcode(provider, msg);]]></source>
      </section>
    </section>
  </body>
</document>
