This article describes project structure when building applications with DEMUX Framework. Project structure is predefined, so all projects can be built consistently and with minimal effort from user. Each project type can be created automatically using Maven archetype. Each project type is defined bellow.
This is the project type for creating desktop applications based on JavaFX. It provides complete development lifecycle: writing, compiling, debugging, testing and deployment. Each task is automated and required minimal input from user.
This type of project is created using
demux-jfx-archetype. This archetype is available in Maven Central repository. To use this archetype, simply type the following command line:
mvn archetype:generate -Dfilter=com.vektorsoft.demux.tools:demux-jfx-archetype
Enter required information: group ID, artifact ID (e.g. myproject), version and DEMUX Framework version. Once this is complete, you will get the following file structure:
myproject |--config |--pom.xml |--antrun-build.xml
pom.xml is Maven project POM, and
antrun-build.xml is an Ant build file used for some tasks during application development. Directory
config contains configuration files needed to build platform-specific installer pacakges. It is discussed in more details in later sections. At this point, you can build and install application. After that is completed, you will see additional files and directories:
myproject |-target |-dist myproject-1.0.0 |-bundles |-osgi.jar |-demux-desktop-jfx.jar |--pom.xml |--antrun-build.xml |-config.properties
Each of these new file and directories are described bellow:
target/dist- distribution directory. This is where all output files reside
myproject-1.0.0- top-level application directory. Think of it as installation directory for application. This is also working directory where JVM is invoked when application is run. The name of directory is in form
bundles- directory where application OSGI bundles are stored
osgi.jar- OSGI runtime. This JAR is part of application classpath
demux-desktop-jfx- JAR containing main class for DEMUX Framework JavaFX application
config.properties- this file contains some configuration properties for correct build. It is always generated on each build.
Maintaining this project structure is critical for correct build/run/debug lifecycle. Each time the project is built, this structure is updated. When you run application during development, Maven invokes JVM with work directory set to application output directory (target/dist/myproject-1.0.0 in this case). JVM is invoked with
demux-desktop-jfx.jar as executable JAR. When application starts, it will look for bundles inside
For DEMUX Framework, project dependencies are treated as OSGI bundles. If you take a closer look at
pom.xml, you can see that most dependencies are declared with scpope
provided. This is because build system assumes that these are OSGI bundles, and thus dynamic in nature. It means that they should be available at runtime, and are treated as external dependencies of application. Build scripts are configured so that they copy these dependencies (with scope
bundles directory, from where they are loaded at runtime.
When declaring your own dependencies (if they are OSGI bundles), you should declare them in top-level POM, so that they get handled correctly. This is the case even if dependencies are used by only a single bundle. If, however, your dependencies are plain old JAR files, you can declare them in bundle submodule POMs.
As we mentioned before, directory
config contains configuration files needed to build platforms-specific installer packages. Contents of this file are shown bellow:
config |--common | |--myproject.desktop | |--launcher.ini |--deb | |--control | |--postinst |--mac | |--Info.plist |--nsis |--JREDyna_Inetc.nsh |--setup.nsi
common- contains files common for multiple installers
launcher.ini- .ini file for launcher startup. Contains options for installer startup for each platform
myproject.desktop- this is Linux application desktop file. It is placed in KDE/GNOME menu and contains application icon etc. It's name matches artifactId set in Maven project
deb- contains configuration files for creating DEB packages
control- control file for package creation
postinst- post installation script which sets executable flag for launcher
mac- contains configuration files for creating Mac OS X application bundles
Info.plist- bundle information file
nsis- configuration files for creating Windows NSIS installer
JREDyna_Inetc.nsh- header script which will check for required JRE, and download and install one if not present
setup.nsi- main setup script
DEMUX Bundle project
This type of project creates OSGI bundle for DEMUX Framework. Since DEMUX is based on OSGI, bundles are the smallest deployment unit for the code, and so the building blocks of every DEMUX Framework application. We provide Maven archetype for creating this type of project. Archetype is called
Projects based on DEMUX Framework are actually Maven multi-module projects. Each bundle is a separate module project, with top-level project, such as JavaFX project we described above, is the parent. So, in order to generate bundle project, archetype must be invoked from parent project directory.
cd myproject mvn archetype:generate -Dfilter=com.vektorsoft.demux.tools:demux-bundle-archetype
This will create simple Maven project structure. The only additional file is
antrun-build.xml, which is used to perform some specific tasks during the build. If you look at project POM, you can see that packaging type is
bundle, which means that output is packaged as OSGI bundle. To configure to your own needs, simply edit configuration of
pom.xml. More about this plugin's configuration can be found on plugin web page.
Most of the time during development, you will change only one bundle at a time. You don't have to rebuild entire top-level project, only the changed bundle. When built, it will be automatically copied to correct location, so the application can be run with new changes.
install phase is run on bundle, it will copy resulting bundle .jar to correct location of parent project, depending on type of parent project.
- For JavaFX project, bundle will be copied to
target/dist/<artifactId>-<version>/bundlesdirectory of parent project
- For Android project, it will be copied into
app/assets/bundlesdirectory of parent project
DEMUX Android project
To get started with developing applications for Android, DEMUX Framework provides another Maven archetype. Create your Android project using the following command:
mvn archetype:generate -Dfilter=com.vektorsoft.demux.tools:demux-android-archetype
Select the latest version, and fill in required properties, as shown bellow. Note that
package here refers to Android application package, as you would use when creating project with Android tools.
1: remote -> com.vektorsoft.demux.tools:demux-android-archetype (Create Android application structure for DEMUX Framework applications) Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 1 Choose com.vektorsoft.demux.tools:demux-android-archetype version: 1: 0.4.0 2: 0.5.0 Choose a number: 2: 2 Define value for property 'groupId': : com.test Define value for property 'artifactId': : testapp Define value for property 'version': 1.0-SNAPSHOT: : 1.0.0 Define value for property 'package': com.test: : Define value for property 'demuxFrameworkVersion': : 0.5.0
This will generate project
testapp in current directory. Project structure is shown bellow:
testapp |--app | |--libs | |--res | |--src | |--AndroidManifest.xml | |--ant.properties | |--antrun-build.xml | |--build.xml | |--local.properties | |--pom.xml |--pom.xml
To-level directory testapp is Maven parent project, while submodule app contains actual Android project structure as would be created by creating Android tools. This directory will contain final output (.apk files).
To start working, create new bundle project in top level directory, like discussed in previous section. This will be a bundle that will be added to our Android application. When you finish editing bundle project, you can simply build entire application by invoking the following command in top-level directory
mvn install mvn deploy -pl app
This will do the following:
- copy OSGI runtime and DEMUX module needed to start up a framework into
- copy all dependencies declared with scope
app/assets/bundlesdirectory. We assume here that all OSGI dependencies need for application are declared with scope
- build each child bundle we created and copy resulting .jar into
- run DEX tool on all jars inside
app/assets/bundlesto create .dex files (if not already present)
When build completes, you will get fully-funtional .apk in
app/bin directory. You can then deploy this file to device or emulator at will.