500px-Apache-Ant-logo.svgThis page describes how to use Externalizer4J Ant support. Externalizer4J’s Ant supports comes int the form of two easy to use Ant tasks. The Externalizer4J Ant tasks convert bytecode of Serializable classes into Externalizable classes without any additional coding. This page explains how to use Externalilzer4J’s Ant tasks.

Support for other build systems:

  • Apache maven support is available through the externalizer-maven-plugin
  • IntelliJ IDEA users can benefit from the fully integrate IntelliJ plugin

Example of Externalizer4J’s Ant support in action. The build output below shows  how the Externalizer4J task to optimize the classes created by javac. The estimated size gain are reported for each optimized class. This page describes how to include Externalizer4J in an Ant build in just a few steps. A complete build.xml is provided to help you getting started quickly.

 

Ant support in action

Ant support in action

Define the tasks

We provide 2 tasks:

  1. optimized the classes
  2. optimized the test classes

The ExternalizerTestTask is almost identical to the ExternalizerTask.

The xml snippet defines the 2 tasks:

<taskdef name="externalizer" classname="be.biggerbytes.ant.ExternalizerTask">
   <classpath path="${externalizer.jar}"/>
</taskdef>

<taskdef name="externalizerTest" classname="be.biggerbytes.ant.ExternalizerTestTask">
   <classpath path="${externalizer.jar}"/>
</taskdef>

Including Externalizer4J Ant support

In the section above we define the ant tasks take make up Externalizer4J’s ant support. For this to work the JAR with the ant tasks is needed. The Ant <get/> task can be used to retrieve the Externalizer4J jar as shown below. For all the details look at the complete build.xml below on this page.

<get dest="." skipexisting="false">
        <url url="http://www.biggerbytes.be/maven2/be/biggerbytes/externalizer-maven-plugin/${e4j.version}/externalizer-maven-plugin-${e4j.version}.jar"/>
</get>

Optimize the classes

First of let’s assume that the classes are located in ${classes.dir}and the test classes in ${testClasses.dir}. Using the Ant tasks defined in the above section the Ant build can extended with 2 additional tasks: externalizer and externalizeTest. The xml snippet below uses the externalizer tasks to optimize the classes and test classes.

<pre><target name="externalize" description="generate Externalizable classes">
    <externalizer classes="${classes.dir}" classpathref="cp"/>
</target>

<target name="externalizeTest" description="generate Externalizable test classes">
    <externalizerTest testClasses="${testClasses.dir}" classes="${classes.dir}" classpathref="testCp"/>
</target>

Configure Externalizer4J

All the Externalizer4J tools, including the Ant tasks, read one and the same configuration: a file called externalizer4j.properties. Whenever the configuration is missing the tools will display a short message and stop without interrupting the build. The optimization will simply not run.

All the Externalizer4J tools are configured using an externalizer4j.properties file

Externalizer4J optimizer expects the externalizer4j.properties file to be present in the root of the classes directory. In the example below the output of the task is ${classes.dir} for instance. The ExternalizerTask will look in this directory for the externalizer4.properties.

Basic externalizer4j.properties

To get started the externalizer4j.properties file should only contain one line: acceptEULA=true

#
# Accept the EULA by setting to true to activate
#
# default: false
#
acceptEULA=true

The Externalizer4J EULA clearly describes all there is the know when you start to use the tools totally for FREE.

The configuration reference details the more advanced optimizations options, how to get additional information about the optimization process and much more.

Complete build.xml

Here is a complete Ant build file. The default jar target compiles the code, copies the resources, optimizes the classes for serialization and creates a jar.

<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="Externalizer4J demo" basedir="." default="jar" xmlns:artifact="urn:maven-artifact-ant">

    <property name="e4j.version" value="2015.8.2-SNAPSHOT"/>
    <property name="src.dir" value="src/main/java"/>
    <property name="testSrc.dir" value="src/test/java"/>
    <property name="classes.dir" value="classesAnt"/>
    <property name="testClasses.dir" value="testClassesAnt"/>
    <property name="maven.ant.tasks.jar" value="maven-ant-tasks-2.1.0.jar"/>
    <property name="m2repo" value="${user.home}/.m2/repository"/>
    <property name="externalizer.jar" value="${m2repo}/be/biggerbytes/externalizer-maven-plugin/${e4j.version}/externalizer-maven-plugin-${e4j.version}.jar"/>

    <path id="cp">
        <pathelement path="${m2repo}/org/openjdk/jmh/jmh-core/1.3.3/jmh-core-1.3.3.jar"/>
        <pathelement path="${m2repo}/org/openjdk/jmh/jmh-generator-annprocess/1.3.3/jmh-generator-annprocess-1.3.3.jar"/>
    </path>

    <path id="testCp">
        <path refid="cp"/>
        <pathelement path="${m2repo}/junit/junit/4.8.2/junit-4.8.2.jar"/>
    </path>

    <get dest="." skipexisting="false">
        <url url="http://www.biggerbytes.be/maven2/be/biggerbytes/externalizer-maven-plugin/${e4j.version}/externalizer-maven-plugin-${e4j.version}.jar"/>
    </get>

    <taskdef name="externalizer" classname="be.biggerbytes.ant.ExternalizerTask">
        <classpath path="${externalizer.jar}"/>
    </taskdef>

    <taskdef name="externalizerTest" classname="be.biggerbytes.ant.ExternalizerTestTask">
        <classpath path="${externalizer.jar}"/>
    </taskdef>

    <target name="clean" description="Delete all generated files">
        <delete dir="${classes.dir}" failonerror="false"/>
        <delete dir="${testClasses.dir}" failonerror="false"/>
        <delete file="${ant.project.name}.jar"/>
    </target>

    <!-- depends="download-libs"-->
    <target name="compile" description="Compiles the Task" >
        <mkdir dir="${classes.dir}"/>
        <javac srcdir="${src.dir}" destdir="${classes.dir}" classpathref="cp"/>
    </target>

    <target name="compileTest" description="Compiles the test Task" >
        <mkdir dir="${testClasses.dir}"/>
        <javac srcdir="${testSrc.dir}" destdir="${testClasses.dir}" classpathref="testCp"/>
    </target>

    <target name="copy_resource">
        <copy todir="${classes.dir}">
            <fileset dir="${src.dir}/../resources"
                     includes="**/*.properties"/>
        </copy>
    </target>

    <!-- The copy_resources should be called first so that externalizer4j.properties can be
     found in the classes directory -->
    <target name="externalize" description="generate Externalizable classes">
        <externalizer classes="${classes.dir}" classpathref="cp"/>
    </target>

    <target name="externalizeTest" description="generate Externalizable test classes">
        <externalizerTest testClasses="${testClasses.dir}" classes="${classes.dir}" classpathref="testCp"/>
    </target>

    <target name="jar" description="JARs the classes" depends="compile,copy_resource,externalize">
        <jar destfile="${ant.project.name}.jar" basedir="${classes.dir}"/>
    </target>

    <target name="testJar" description="JARs the test class" depends="compileTest,externalizeTest">
        <jar destfile="${ant.project.name}-test.jar" basedir="${testClasses.dir}"/>
    </target>

    <!-- Automate deps download from maven repo with tasks below -->

    <target name="download-libs" depends="-init-maven-task">
        <artifact:dependencies pathId="dependencies.classpath">
            <dependency groupId="org.openjdk.jmh"
                        artifactId="jmh-core"
                        version="1.3.3"/>
            <remoteRepository id="maven-central"
                              url="http://repo1.maven.org/maven2/"/>
        </artifact:dependencies>

        <move todir=".">
            <path refid="dependencies.classpath"/>
        </move>
    </target>

    <target name="-init-maven-task" depends="-obtain-maven-task-jar">
        <available property="maven.ant.tasks.jar.exists"
                   file="${maven.ant.tasks.jar}"/>
        <typedef resource="org/apache/maven/artifact/ant/antlib.xml"
                 uri="urn:maven-artifact-ant" classpath="${maven.ant.tasks.jar}"/>
    </target>

    <target name="-obtain-maven-task-jar">
        <available property="maven.ant.tasks.jar.exists"
                   file="${maven.ant.tasks.jar}"/>
        <antcall target="download-maven-jar"/>
    </target>

    <target name="download-maven-jar" unless="maven.ant.tasks.jar.exists">
        <property name="maven.ant.tasks.url"
                  value="http://www.apache.org/dist/maven/binaries/${maven.ant.tasks.jar}"/>
        <get src="${maven.ant.tasks.url}" dest="${maven.ant.tasks.jar}"/>
    </target>
</project>

Download

The build file above automatically downloads the jar. But all the jars are freely available from our FTP site.  Download the jar to include it in any existing Ant build.

IMPORTANT REMARKS:

  1. the same jar contains both the Apache Ant tasks and the Apache Maven plugins
  2. the jarcontains all the classes needed at runtime
    1. the jar contains the classes of the open source libraries mentioned on the Credits page.

Give it a try!

Getting started is easy. The page contains all the snippet you need to get started in less than 5 minutes. Cut & paste and start optimizing the serialization of all your products!

Questions?

Is you have some question CONTACT US! Either on Google+ or on our contact page.