Getting Started with the File Based Server

Introduction

This quickstart is intended to show the basic functionality of ACE: deploying bundles to a remote OSGi framework running a management agent.

Using ACE to replicate remote FileInstall

FileInstall can be used to automatically 'watch' directories for new bundles and configuration files, which will be processed.

To get roughly the same functionality as FileInstall, but remote, we can use the simplest server target available. After building ACE, it can be found under core/deploy/target/dev-server-filebased.
Start this server by using the .sh or .bat file from the directory, and start a target (dev-gateway).
The target will show some exceptions relating to auditlog information; that's correct, our server does not support auditlog information now.

To deploy bundles to the target, find the store directory in the server. In this directory, add a new directory for each target (the default target uses "configuredGatewayID"), and in that, add directories for all versions (note that the versions should actually be valid OSGi deployment package version, so 1.0.0 is valid, but 1 is not). In these version directories, drop any bundles you want to have provisioned. That's it!
Remember that any version you create will be installed at most once: if you create a version directory, and then start adding files to it, you run the risk that your empty folder will get installed, and all additional bundles will be removed from the target. It's easiest to create the version folder somewhere else on your system, and move it to the target's directory when you're done.

Slightly advanced

• To use a 'real' remote server, you can edit the target's configuration. Edit conf/org.apache.ace.discovery.property.cfg to contain your server IP (or name). Remember that, when using multiple targets, each target should have its own name. This can be found in conf/org.apache.ace.identification.property.cfg.

How does this work?

Simply speaking, the target will poll for updated versions, and the server will create a deployment package based on the contents of the file system.

The (configurable) scheduler will, by default, check every two seconds for an update. It does so by connecting to the server it finds in conf/org.apache.ace.discovery.property.cfg, on the endpoint /deployment. It first checks whether there are new versions by looking up /deployment/<gatewayID> (you can try this all in a browser, by the way). If there is a newer version than the one already installed, it will request the newest version, stating its own version.

The server receives the requests for either a list of versions, or a deployment package for some version, and passes it on to the resident deployment provider (in this case, a FileBasedProvider). This will check the file system, and inform the StreamGenerator of the deployment package to be generated. The StreamGenerator will generate a fixpackage (see OSGi compendium, 114.3.3). This will then be returned to the target.

The target will receive the stream, and pass it on to its DeploymentAdmin, which will take care of installing the package.