Building applications and adapters

If you use Ant tasks, you can build both applications and adapters.

You can use the following examples of Ant XML files to build applications and adapters.

Note: Since V6.2.0, the worklight-ant-builder.jar file is included in the IBM MobileFirst™ Platform Command Line Interface as well as the MobileFirst Server, whereas in earlier versions, it was included only in Worklight Server. By default, worklight-ant-builder.jar is installed in the following location: cli_install_dir/public/worklight-ant-builder.jar. For example, on OSX, the default CLI Install Path is /Applications/IBM/Worklight-CLI. If you use the default installation path, the Ant task is installed here: /Applications/IBM/Worklight-CLI/public/worklight-ant-builder.jar.

In Worklight Server V6.2.0 and MobileFirst Server, the default location of worklight-ant-builder.jar is mfp_server_install_dir/WorklightServer/worklight-ant-builder.jar. This file has the same version as the server.

Building a hybrid application

The Ant task for building a hybrid application has the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<project basedir="." default="target-name">
  <taskdef resource="com/worklight/ant/defaults.properties">
    <classpath>
      <pathelement location="cli_install_dir/public/worklight-ant-builder.jar"/>
    </classpath>
  </taskdef>
  <target name="target-name">
    <app-builder
        worklightserverhost="http://server-address:port"
        applicationFolder="application-source-files-folder"
        environments="list-of-environments"
        nativeProjectPrefix="project-name"
        outputFolder="output-folder"/>
  </target>
</project>

The <app-builder> element has the following attributes:

The worklightserverhost attribute is mandatory and specifies the full URL of your MobileFirst Server.
The applicationFolder attribute specifies the root folder for the application, which contains the application-descriptor.xml file and other source files for the application.
The environments attribute is a comma-separated list of environments to build. This attribute is optional. The default action is to build all environments.
The nativeProjectPrefix attribute is mandatory when you build iOS applications.
The outputFolder attribute specifies the folder to which the resulting .wlapp file is written.

By default, running the Ant task to build an application does not handle the Dojo Toolkit because Ant is not run with build-dojo.xml. You must explicitly configure the task to do so, by using the following app-builder setting in the Ant build file:

skinBuildExtensions=build-dojo.xml

If you use this setting, the Dojo Toolkit files are deployed with your application.

Building a native API application

The Ant task for building a native API application has the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<project basedir="." default="target-name"> 
  <taskdef resource="com/worklight/ant/defaults.properties"> 
    <classpath> 
      <pathelement location="cli_install_dir/public/worklight-ant-builder.jar"/> 
    </classpath> 
  </taskdef>
  <target name="target-name"> 
    <native-app-builder 
      sourcefolder="application-source-files-folder" 
      outputFolder="output-folder"/> 
  </target> 
</project>

The <native-app-builder> element has the following attributes:

The sourceFolder attribute specifies the root folder for the application, which contains the application-descriptor.xml file and other source files for the application.
The outputFolder attribute specifies the folder to which the resulting .wlapp file is written.

Building an adapter

The Ant task for building an adapter has the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<project basedir="." default="target-name">
  <taskdef resource="com/worklight/ant/defaults.properties">
    <classpath>
      <pathelement location="cli_install_dir/public/worklight-ant-builder.jar"/>
    </classpath>
  </taskdef>

  <path id="base.path">
    <pathelement path="/Users/miguel/badjars"/>
  </path>

  <target name="target-name">
    <adapter-builder
      folder="adapter-source-files-folder"
      destinationfolder="destination-folder"
      classpathref="base.path"/>
  </target>
</project>

The <adapter-builder> element has the following attributes:

The folder attribute specifies the folder that contains the source files of the adapter (its .xml and .js files).
The destinationfolder attribute specifies the folder to which the resulting .adapter file is written.
The classpathref attribute specifies a custom class path for the adapter builder. If this property is not specified, then the class path of the running Ant task is used to compile the code.

The classpathref attribute is required to be set for RESTful Java™ adapters. It is not mandatory for JavaScript adapters. You must add the Worklight-jee-library.jar to the class path for Java adapters. In the case of RESTful Java adapters, the task compiles the code in the adapterRootFolder/src directory and copies the compiled classes to the adapterRootFolder/bin directory. Any source files that are not Java are also copied. Error messages are printed in the console.

This Ant task requires that the JAVA_HOME environment variable is set to point to a JDK and not a JRE.

If you must build more than one adapter file, add an <adapter-builder> element for each adapter.

Example:

Building a JavaScript adapter

<adapter-builder
  folder="adapterRootFolder"
  destinationfolder="destination-folder"/>

Building a Java adapter without libs

<path id="my.path">
  <pathelement path="/product_install_dir/WorklightServer/worklight-jee-library.jar"/>
</path>
 
<adapter-builder
  folder="adapterRootFolder"
  destinationfolder="destination-folder"
  classpathref="my.path"/>

Building a Java adapter with the server/lib and the adapter/lib folders in the class path

<path id="my.path">
  <pathelement path="/product_install_dir/WorklightServer/worklight-jee-library.jar"/>
  <fileset dir="adapterRootFolder/lib">
    <include name="*.jar" />
  </fileset>
  <fileset dir="projectRootFolder/server/lib">
    <include name="*.jar" />
  </fileset>
</path>
 
<adapter-builder
  folder="adapterRootFolder"
  destinationfolder="destination-folder"
  classpathref="my.path"/>

Building the Starter project

To use the Ant script starter example, complete the following steps.

Download the Starter Application sample.
Add the build.xml file to the root folder of your project.

Complete the following properties inside the build.xml file with the correct values. These values depend on your computer and the location where IBM MobileFirst Platform Foundation is installed.

<!-- The admin console URL -->
<property name="mfp.admin.url" value="http://localhost:10080/worklightadmin"/>    
<!-- The MobileFirst server host to be written in the app configuration file (wlconfig.properties or worklight.plist) -->
<property name="mfp.server.url" value="http://localhost:10080/worklight"/>
<!-- The MobileFirst builder jar - This jar contains all the builder ant tasks -->
<property name="mfp.ant.builder.jar" value="product_install_dir/WorklightServer/worklight-ant-builder.jar"/>
<!-- The MobileFirst deployer jar - This jar contains all the deployer ant tasks -->
<property name="mfp.ant.deployer.jar" value="product_install_dir/WorklightServer/worklight-ant-deployer.jar"/>
<!-- The MobileFirst server Java EE library jar - This jar is required for building the server/java folder and for building Java adapters as well -->
<property name="mfp.jee.library.jar" value="product_install_dir/WorklightServer/worklight-jee-library-production.jar"/>

Ensure that the MobileFirst Server is running and that MobileFirst WAR is installed on it.
Run the ant command. The ant command builds and deploys the app and the adapter of the Starter Application project. It also builds, but does not deploy, the WAR.

<?xml version="1.0"?>
  <project default="build-all-and-deploy" name="build-tools" basedir=".">
    <property name="mfp.runtime.name" value="worklight"/>
      <!-- The admin console URL -->
    <property name="mfp.admin.url" value="http://localhost:10080/worklightadmin"/>
      <!-- The MobileFirst server host to be written in the app configuration file (wlconfig.properties or worklight.plist) -->
    <property name="mfp.server.url" value="http://localhost:10080/worklight"/>
      <!-- The MobileFirst builder jar - This jar contains all the builder ant tasks -->
    <property name="mfp.ant.builder.jar" value="product_install_dir/WorklightServer/worklight-ant-builder.jar"/>
      <!-- The MobileFirst deployer jar - This jar contains all the deployer ant tasks -->
    <property name="mfp.ant.deployer.jar" value="product_install_dir/WorklightServer/worklight-ant-deployer.jar"/>
      <!-- The MobileFirst server Java EE library jar - This jar is required for building the server/java folder and for building Java adapters as well -->
    <property name="mfp.jee.library.jar" value="product_install_dir/WorklightServer/worklight-jee-library-production.jar"/>
    <taskdef resource="com/worklight/ant/defaults.properties">
      <classpath>
        <pathelement location="${mfp.ant.builder.jar}"/>
      </classpath>
    </taskdef>
    <taskdef resource="com/worklight/ant/deployers/antlib.xml">
      <classpath>
        <pathelement location="${mfp.ant.deployer.jar}"/>
      </classpath>
    </taskdef>
    <target name="build-all-and-deploy">
      <antcall target="build-war"/>
      <antcall target="build-applications"/>
      <antcall target="build-adapters"/>
      <antcall target="deploy"/>
    </target>
    <target name="build-war">
      <path id="compiler-classpath">
        <pathelement location="${mfp.jee.library.jar}"/>
      </path>
      <mkdir dir="bin/classes"/>
      <javac classpath="${mfp.jee.library.jar}" destdir="bin/classes" srcdir="server/java">
        <classpath refid="compiler-classpath"/>
      </javac>
      <war-builder classesFolder="bin/classes" warfile="bin/StarterApplication.war" destinationfolder="bin" projectfolder="."/>
    </target>
  <target name="build-applications">
    <echo>Building Hybrid application "StarterApplication"...</echo>
    <app-builder environments="android,iphone,windowsphone8,desktopbrowser,ipad,mobilewebapp,windows8,windowsphoneunversal,common" 
      nativeprojectprefix="StarterApplication" outputfolder="bin" worklightserverhost="${mfp.server.url}" applicationfolder="apps/StarterApplication"/>
    <echo>Building Native iOS application "NativeiOS"...</echo>
    <native-app-builder worklightserverhost="${mfp.server.url}" outputFolder="bin" sourcefolder="apps/NativeiOS"/>
    <echo>Building Native Android application "NativeAndroid"...</echo>
    <native-app-builder worklightserverhost="${mfp.server.url}" outputFolder="bin" sourcefolder="apps/NativeAndroid"/>
    <echo>Building Native WP8 application "NativeWP8"...</echo>
    <native-app-builder worklightserverhost="${mfp.server.url}" outputFolder="bin" sourcefolder="apps/NativeWP8"/></target>
  <target name="build-adapters">
    <antcall target="build-adapter">
      <param name="adapter.folder" value="adapters/StarterApplicationAdapter"/>
    </antcall>
  </target>
  <target name="build-adapter">
    <path id="compiler-classpath">
      <fileset dir="${adapter.folder}/lib">
        <include name="*.jar"/>
      </fileset>
      <fileset dir="server/lib">
        <include name="*.jar"/>
      </fileset>
      <pathelement location="${mfp.jee.library.jar}"/>
    </path>
    <echo>Building adapter ${adapter.name}</echo>
    <adapter-builder destinationfolder="bin" classpathref="compiler-classpath" folder="${adapter.folder}"/>
  </target>
  <target name="deploy">
    <wladm password="admin" user="admin" secure="false" url="${mfp.admin.url}">
      <deploy-adapter file="bin/StarterApplicationAdapter.adapter" runtime="${mfp.runtime.name}"/>
      <deploy-app file="bin/StarterApplication-all.wlapp" runtime="${mfp.runtime.name}"/>
    </wladm>
  </target>
</project>