Developing Components: Compilation

Compiling Your Component

Openwings uses a cross platform compilation tool called Ant to compile components. Ant is a make-like utility that uses Java and XML build files to perform platform independent builds. These build files perform compilation tasks and other build tasks all in the interests of developing and deploying components. Ant primarily uses a build file called build.xml.

Ant is developed by the Apache Software Foundation, is freely available, is easy to use, and comes with a good manual. Ant uses XML to build scripts so it’s advantageous to know something about XML.

XML (Extensible Markup Language) provides a way to make data portable by using HTML-like tags. Briefly, XML separates data, content and the presentation of how text is to be displayed. Ant and Openwings use XML files as a tool to make the development and execution of software platform independent.

There are over 50 core tasks that correspond to XML tags within Ant and over 40 optional tasks. Ant allows you to create your own tasks as well. Some of the more common core tasks used in Openwings Ant build files are listed below.

Task

Definition

Copy

copies a file or a fileset to a new directory

Delete

deletes either a single file, all files in a specified directory or sub-directory, or a set of files specified by one or more filesets.

Filesets

group files

Jar

jars a set of files

Mkdir

creates a directory

Java

executes a Java class within a running (Ant) VM or forks another VM if specified

Javac

compiles a Java source tree

Using Ant with the Demo Applications

Several demo applications have been provided to help you learn Openwings, including HelloWorld, Launcher and Image. All of the demo applications include Ant build files, so use these to experiment with Ant.
Be aware the order of compilations of the demo components matter. This is because there are dependencies between components. For example, Image_im depends on both ImageUI_im and ImageService_im. And ImageUI_im depends on ImageService_im. So ImageService_im must be compiled first, and then ImageUI_im and finally Image_im.

As far as the hello world components go, only the hello world service components must be compiled first. The remaining hello world components can be compiled in any order.

To reiterate, the components are listed below:

Hello World Synchronous

HelloWorldServiceSync_im - must be first

HelloWorldProvider_im

HelloWorldUser_im

HelloWorldSimpleUser_im

Hello World Asynchronous

HelloWorldServiceAsync_im - must be first

HelloWorldPublisher_im

HelloWorldSubscriber_im

Launcher

Launcher_im

Image

ImageService_im - must be first

ImageUI_im - must be second

Image_im - must be last

Build.xml

The build.xml file is what you will be using to build components. If you have reviewed the Quick Start portion of this tutorial, you already know how to compile the demo components. Using the command line, simply change directory to the component directory and type "ant". Ant automatically looks for the build.xml file to build components. This command executes default tasks including:

compiling the component code

generating the policies

generating any connectors

creating javadocs

creating an installable component jar

That’s the easy way. But what if you want to perform other tasks? Well, there are other tasks already built for you. To understand these tasks you will need to know about Ant targets.

Generally, ant commands are of the form "ant <target>".

Below is a table representing key tasks (or targets) that can be conducted from build.xml. Build.xml is also heavily commented and contains the same information that you see below.

Target

Definition

all

This target does everything this build file is capable of. This includes cleaning, building, imaging, deploying, testing, and publishing the component.

main

This is the default target. This target builds and images the component.

build

This target will build the component. This includes compiling component code, generating policies, jar-ing the main classes, and generating connectors

clean

This target will clean up all products normally created by this build file.

compile

This target compiles the main classes of this component.

policy

This target generates all policies associated with this component. This should be an empty target that depends on each policy to be generated, i.e. policy1, policy2, etc. Policies typically get put in the main jar file.

jar

This target creates the main jar file

connector

This target generates all connectors associated with this component. This should be an empty target that depends on each connector to be generated, i.e. connector1, connector2, etc. Connectors each go in their own jar file.

image

This target creates an installable component jar. Part of imaging includes creating javadocs.

docs

This targets creates any javadocs for the component.

deploy

This target will copy your component to the hotinstall directory of Openwings.

test

This target will perform regression testing of the component.

publish

This target will copy your component to the webserver.

Note: Test, deploy and publish targets will be developed in the future.

Naturally, you can define your own target and target structure. However, we provided the above defaults for ease of development.

Targets have dependencies. Here is a graphical layout of target dependencies:

Click above image to see full size

So, if you want to perform the task "jar" on a component, all you have to do is use the command line, change directory to where the build.xml file resides and type "ant jar". Try it on the HelloWorld example. The build.xml file is located at:

<OW_HOME>/<componentName>/src/com/gd/openwings/demo/helloworld/[provider or user or service]/build.xml

Try using some of the ant commands and view the results:

ant

ant jar

ant compile

ant clean

ant docs

Also try using the "ant –v <target>" command. The "v" is for verbose. You can use this to watch Ant perform any task.

Other Ant Files to be Aware of

The buildEnv.xml file is a short file containing environment information in the form of a properties file. The first line is a comment and demonstrates what commented lines look like in XML. You can get a copy of this template file from here.

You do not need to change the buildEnv.xml file. Just know this file exists and is an important part of the build process. Observe the key value pairs. You will see these keys in other build.xml files. You will find the buildEnv.xml file at:

<OW_HOME>/<componentName>/src/buildEnv.xml

Other build.xml Files

Perhaps you have noticed a build.xml file in the same directory as the buildEnv.xml file. This type of build.xml file simply provides a file path to follow when certain Ant targets are used. We did this for simplicity. If you followed the Quick Start tutorial, you probably noticed that keying in "ant" in the <OW_HOME>/componentName directory was a very simple thing to do to compile a component. The build.xml file in that directory provides a path to be followed in an effort to find the actual build.xml file containing all the code needed to compile and build components.

Look at the example here. Notice the target called "children" simply denotes the next directory to use.

Building Your Own build.xml File

You can get a build.xml template file from here and use it to make your own Ant build file for a component you are developing. Using a text editor to modify build.xml, execute a "find" command for the following variables and set them to the required information. For more concrete examples, examine one of the build.xml files provided for you in any of the demo applications. The HelloWorld, Launcher and Image applications all include sample code and together cover everything you need to properly build new components to be run on Openwings.

Variable

Description

RELATIVE_PATH_HERE

The relative path of the build.xml file

PACKAGE_NAME_HERE

Your component's package name

RELATIVE_SRC_DIR_HERE

The relative source directory

COMPONENT_JAR_NAME_HERE

<componentName>.jar

CONNECTOR_IF_NAME_HERE

Connector interface name

CONNECTOR_JAR_NAME_HERE

<connectorName>.jar

POLICY_NAME_HERE

The name of your policy. Policy generation is covered here. There are no special policies for HelloWorld components.

Another thing to be aware of is that there exists a quirk in some of the Ant built-in tasks that prevents a classpath in a manifest from being used. Just make sure that your classpath is complete when you create your build files. If you are not sure in what executable Jar file the class you need resides, don’t worry. There is a findclass command in the Openwings shell that you can use. All you need to do is specify a directory on the local file system to be searched. If no directory is specified, the current directory will be searched (you can change the current directory with the lcd command) See the Openwings Shell tutorial trail for more details.

Next: Connector Generation