Apache ACE™

Home » Docs

Setting up a development environment

Everything you need to know to start developing Apache ACE can be found here.

Obtaining the sources

There are two ways to obtain a copy of the source code. You can either download one of the source releases, or checkout the code from subversion.

Download the sources

Point your browser to the ACE download page.

On that page you will find, amongst others, a link to the latest released sources, plus an archive containing all binary third-party dependencies. The page will automatically select a download mirror close to you. Download both the source and dependencies archive and then type:

$ unzip apache-ace-2.1.0-src.zip
$ unzip apache-ace-2.1.0-deps.zip

Note that when unzipping the second archive, you will get some warnings about overlapping files. Those are the required NOTICE and LICENSE files, which are in the same location in both archives. It is fine to overwriting theses files.

Checkout from subversion

Alternatively, you can check out the sources directly from the main Apache source repositories:

$ svn co http://svn.apache.org/repos/asf/ace/trunk apache-ace

or

$ git clone git://git.apache.org/ace apache-ace

In both cases you end up with a copy of the source code. Note: committers should always use Subversion as the Git mirror is read-only.

Building the sources

There are two ways to build the sources. You can either run a command line build or use Eclipse with the Bndtools plugin to build everything. If you want to actively start developing, we strongly recommend you use Eclipse with Bndtools as this is by far the most convenient way to build and run Apache ACE.

Eclipse with Bndtools

Prerequisites

For developing ACE using Eclipse, you need:

For building or exporting the compiled artifacts of ACE without Eclipse, you can use the Gradle wrapper script that is available in the source repository.

Eclipse set up

Start Eclipse with a new, empty, workspace. To set up the projects you can do either:

  1. if you use the same root folder/directory in which your ACE sources are checked out (or extracted) as your Eclipse workspace, you can import the projects directly using "File -> Import... -> General -> Existing Projects into Workspace";
  2. checkout the sources from Subversion as described below.
Checking out the latest sources

If you created a new and empty workspace, you need to grab the latest sources from ACE's Subversion repository. To do this, open up the "SVN Repository Exploring" perspective, and add the following URL as new SVN repository using the yellow add-icon in the "SVN Repositories" view:

https://svn.apache.org/repos/asf/ace/trunk/

After this, expand the newly created tree node named after the SVN URL, and select all individual projects underneath. Note: do not (only) select the root node or the files that reside underneath the root node, as this won't let you properly import the individual projects.

Right click on the selected (sub)projects, and choose "Checkout..." from the context menu. Leave all default settings as-is and click "finish". Now relax and wait until the checkout is completed, and all projects are imported into your workspace.

Switching back to the "Bndtools" perspective should give you a long list of imported projects.

Coding guidelines

If you want to develop for ACE, you might want to import the code templates and formatter rules for ACE. The formatter can be found in the etc folder in subversion, and you can import it into Eclipse as your default formatter for this workspace.

Running & debugging

One of the benefits of the migration to BndTools is that we can now directly run ACE from Eclipse with almost zero effort. In fact, it is even possible to directly debug or profile ACE from Eclipse. By convention, all runnable projects start with "run-" and contain a ".bndrun" file.

To start a project, right-click the "bndrun" file and select "Run As" -> "Bnd OSGi Run Launcher" or "Debug As" -> "Bnd OSGi Run Launcher".

There are several projects that can be run which we outline in the next sections.

run-develop

This project allows you to directly start an ACE target that receives software from the ACE server. By default, the target is started with a Gogo shell to allow you to interact with it, making it easy to debug or troubleshoot it. Note: since the Gogo bundles are already installed, do not provision them using ACE! The deployment will fail.

To run or debug the ACE server, use the "develop.bndrun" file in the "run-develop" project.

run-target

This project allows you to directly start an ACE target that receives software from the ACE server. In contrast to the "run-develop" project, this target does only start an ACE management agent and nothing else.

To run or debug the ACE server, use the "target.bndrun" file in the "run-target" project.

run-server

This project allows you to start a plain ACE server without an OBR and (web)client. Its endpoints can be reached on port 8080. The server expects an OBR to be available at the same host on port 8082.

To run or debug the ACE server, use the "server.bndrun" file in the "run-server" project.

run-obr

This will start an OBR for your artifacts. By default, its endpoints can be reached through port 8082.

To run or debug the ACE OBR, use the "obr.bndrun" file in the "run-obr" project.

run-client

This project allows you to start the web-based client. The web UI can be reached by opening localhost:8081/ in your browser. The ACE client expects a (plain) ACE server to be available on the same host through port 8080 and an ACE OBR to be available on the same on port 8082.

To run or debug the ACE client, use the "client.bndrun" file in the "run-client" project.

run-server-allinone

In case you just want to start everything in one go, you can use the "all-in-one" server. This starts the ACE server, OBR and web-based client and allows you to reach all endpoints through port 8080.

To run or debug the "all in one" ACE server, use the "server-allinone.bndrun" file in the "run-server-allinone" project.

run-relay

This project allows you to start a relay server that you can use to distribute the load from your main ACE server. Instead of all clients talking directly to one ACE server, you can let clients talk to one or more relay servers. The default relay configuration expects an ACE server to run at port 8080 and an OBR to run at port 8082. Its endpoints are reacheable through port 8282.

To run or debug the relay server, use the "relay.bndrun" file in the "run-relay" project.

Unit tests

ACE uses TestNG for its unit tests. To run a single test or a package of tests, use "Run As -> TestNG Test" or "Debug As -> TestNG Test".

Integration tests

The integration tests of ACE are placed in separate projects that are, by convention, named with a '.itest' suffix. These integration tests use BndTools to get an OSGi framework up and running. To run one or all integration tests, use "Run As -> Bnd OSGi Test Launcher (JUnit)" or "Debug As -> Bnd OSGi Test Launcher (JUnit)".

Command line build

The command line build for Apache ACE is based on Gradle.

The build is structured as a flat hierarchy of projects, and you can go into any of these projects to build just that project and its dependencies. There are two special projects:

  1. cnf -- Which is collection of repositories and configuration files that contain all the required dependencies for building and running Apache ACE;
  2. build -- A project that contains the necessary scripts and tools to do source and binary releases.

So, to build Apache ACE, we issue the following command:

$ ./gradlew build

This will build everything, and run all unit and integration tests. In the end, this leaves us with a set of bundles (in the generated folder of each individual project).

The following targets are available (there actually are a few more, use the tasks target for that, but these are the most important ones):

You can prefix these task names with the <project-name>: to execute them for a single project. For example, run-target:export would create the runnable JAR file for the run-target project only.

How to...

...use my favorite IDE (not Eclipse)?

Unfortunately, the easy answer is "no". Until somebody ports Bndtools to your favorite IDE, you either have to use Eclipse, or a combination of your IDE and manual builds using Gradle (though not recommended).

...build this thing in Eclipse?

Normally, you don't. Seriously. If "Build Automatically" is enabled, as soon as you hit save after changing a line of code, Bndtools will automatically build your bundle(s) for you. In fact, if any project is already running, Bndtools will even redeploy all changed bundles to it automatically allowing you to directly test your changes at runtime.

...get rid of all those red crosses in Eclipse?

If Eclipse complaints about missing test libraries, you probably forgot to install the TestNG plugin. If this plugin is installed, it will automatically cause your projects to get the required dependency to the TestNG library. Without this plugin, Eclipse won't have the required library and fails to compile the code correctly. In case you are importing the projects into Eclipse for the first time, it takes a while and a couple of builds to get rid of all build errors. If the problem does not go away, please drop a line on the mailing lists to get additional help.

...add an OSGi bundle

The easiest way to add an OSGi bundle, is to drag it onto the "Local" repository entry in the "Repositories" view, or to use the "Add files to repository" toolbar icon. Bndtools will analyze the files you try to add and show their metadata if they're indeed valid bundles.

The bundles will end up in the local repository inside the cnf project.

...add a Java library

If you want to add a library that does not contain any OSGi metadata, you can follow the steps below to add it to the "Library Repository" so it can be used in all other projects within Apache ACE. If your library does have sensible OSGi metadata, please follow the "...add an OSGi bundle" instructions above.

  1. Copy the library to the right location. The jar file for the library should be copied to the following location: cnf/lib/foo/foo-1.0.0.jar. Note that the directory name should be equal to the basename of the added JAR file, that is, everything before the version-string of the JAR;
  2. Refresh the repositories in Bnd by invoking "Bndtools -> Refresh Repositories".

Your library should be now available "Repositories" view and can be used normally in any OSGi project.