Skip to content

Importing and building the source

Alvaro Fides edited this page Oct 11, 2017 · 19 revisions

The universAAL Middleware Android Application is just a regular Android application, but the source code is not as regular: it has some particularities that make it a bit more difficult to import in an IDE than other apps.

Table of Contents

Importing in Eclipse

The universAAL application combines two different project natures: it is an Android project, with its Android Manifest, but it is also a Maven project, with a POM file. It gets its dependencies from these two sources, both from the Android dependencies and private libraries, and from the Maven dependencies declared in the POM. In practice, you can treat it like any other Android project, only you can add Maven dependencies to its POM.

Before getting into details, it is assumed that you already know and have installed the Java JDK (JDK 7), the Android SDK (with Android 2.3.3 or above) and the Eclipse IDE. Because of the dual nature of the application, you will need the Android ADT plugin (update site: http://dl-ssl.google.com/android/eclipse/), the Maven plugin (usually included in Eclipse, but just in case the update site is http://download.eclipse.org/technology/m2e/releases) and finally an Android-Maven integration plugin, available from the update site: http://rgladwell.github.com/m2e-android/updates/

  1. When Eclipse is properly set up, you can clone/download the source of the application from https://github.com/universAAL/nativeandroid/tree/master/mw.container.android . Then import it as an Existing Eclipse project: File > Import > General > Existing Projects into Workspace.
  2. Once imported it will show some error. This is normal: to ease the dependency configuration process we included a static reference to the Google Play Services library. To fix it, first import a copy of the Google Play Services library following the steps in http://developer.android.com/google/play-services/setup.html#Setup . Make sure you have selected "Using Eclipse with ADT" from the drop-down.
  3. Once you have imported the Play Services library (remember to make it a copy in your workspace), right click the uAAL app project and select properties > Android. In the bottom box, remove the missing library and add the Play Services library you just imported.

Importing in Android Studio

There is a branch of the uAAL app source as a Gradle-based project, which you can import in the Intelli-J based Android Studio IDE. Just check out the "gradle" branch in GitHub (https://github.com/universAAL/nativeandroid/tree/gradle) and import the project in mw.container.android in Android Studio. No extra configuration steps needed. Just take into account that because of the different project structure it is a bit tricky to keep this branch up to date with the changes in "master", so some fixes may take a while to be committed.

Customizing the code

You can find an overall description of the structure of the source code in the first wiki page. One of the reasons you may ant to modify the source code is deployment: to properly run universAAL it must be configured to your needs before it starts. In large deployment scenarios it would be time-consuming to manually set up many installations of the app, so you may find it is better to pre-compile the uAAL app with your own default configurations.

Settings

You can find a description of all settings and options here. If you would like to set your own defaults, you would need to modify the following:

  • Open the AppConstants.java class in org.universAAL.android.utils. At the bottom you will find all the defaults for the settings. Set them to your own values.
  • Open the defaults.xml file in the res/values resource folder. It also contains the default settings. Make sure they are the same as in AppConstants.java.
Another option is using Android intents to configure the uAAL settings in runtime. Check this too to see how to do it.

Ontologies

The uAAL app includes the core ontologies of universAAL: phWorld, profile, unit and measurement. You can add any other ontology you want by modifying the following:

  1. Dex the jar files of the ontologies you want to include, and change their names so they use only alphanumeric characters (i.e. no dots).
  2. Place the dexed jar files in the res/raw fodler of the uAAL app project.
  3. Change their extension from '.jar' to something else, like '.ja' (This is to prevent a bug in Android Studio).
  4. Open the Config.java class from org.universAAL.android.utils
  5. Find the "createFiles" method and uncomment the commented lines you will find there. Follow the examples there but with the ontologies you added. Make sure you put them in the right ontology startup order (If you use ontologies.cfg or activators.cfg to determine the order, add that file here too, the same way).

Building and running

If you try to simply run or export the uAAL Android application from the source you imported it will probably fail: it has a lot of dependencies and it will hit the 65536 method limit. This is actually Google's fault, for cramming so many APIs into Google Play Services. There are some workarounds to avoid this limitation, which you can find in https://developer.android.com/tools/building/multidex.html. However the quickest thing to do is chop down Google Play Services. Using Gradle it is a simple as referencing only the parts of the Play Services APIs you need as dependencies (universAAL only needs the Google Cloud Messaging API) and/or activating the "jumbo" mode in the Gradle script. But there is no equivalent easy way using Eclipse ADT.

However, there is a dirty way to do this: When you imported Google Play Services in Eclipse in the above instructions you (sould have) made a copy into your workspace.

  1. Locate that copy in your workspace and find the .jar file that contains the actual library (usually in {yourWorkspace}\google-play-services_lib\libs).
  2. Open the .jar file (something like WinRAR will do) and start removing the packages you don't need from com/google/android/gms (things like appdatasearch, cast, drive, fitness, games, location, maps, nearby, panorama, wallet, wearable... just don't remove gcm and common packages).
  3. Once you are done, refresh and rebuild all projects and uAAL should be ready to run, build or export as any other Android app (e.g. richt click > run as > Android application).

Using the project as a library

In cases where you are going to deploy an app of your own that uses uAAL, you may find it cumbersome to also have to install uAAL first. In these cases it may be useful to embed uAAL directly into your app. All Android application projects can be turned into libraries that can be used in other Android projects. The uAAL app is no different.

Before converting to library

We recommend removing the Intent Filter of HandlerActivity from the uAAL manifest. This prevents having multiple activities in the launcher. Instead, you can add some method from your app to access the uAAL SettingsActivity. Remember however that you can modify the settings and start/stop the middleware through Android intents too.

If you are embedding uAAL in your app, remember you probably want to customize the ontologies and settings in the source. Check the previous sections.

IMPORTANT: The uAAL MW usually blocks some threads and can kill its own process. To protect your app, add android:process=":uaal" as an attribute to all non-activity components (receivers, services...) in the uAAL manifest.

Convert to library in Eclipse

All you need to do is right-click the uAAL project, go to properties > Android, and check the "Is library" option. Now you will be able to import it as an Android library: go to the same Android settings window in the destination project and "add" the uAAL project.

There are some additional steps to perform to avoid erros when building, though. First, make sure there are no duplicated dependencies or libraries between your app and uAAL. The most common case is Google Play Services. Remove the dependency from either your app or uAAL (be careful in the case of Play Services if you removed packages from it as described in the previous section).

The other step to perform is merging the Android manifest, so that all Android permissions, services and receivers in uAAL are also copied in your app manifest.

Convert to library in Android Studio

Check this out if you use the Gradle version of uAAL in Android Studio, to turn it into a library. Later you can import it in your app in different ways:

  • Import the full source as another module into your project: File > New > Import Module... . You will need to copy the repositories in the mwcontainerandroid gradle file and paste them into your project repositories section in your gradle file.
  • Import the library 'aar' binary into your project: File > New > New Module... > Import JAR/AAR. You may find problems with missing classes when running it. In that case check out this issue
For the last option you need the 'aar' binary. To generate it from uAAL (once it is a library), execute the 'assembleRelease' Gradle task or the Android Studio 'Build APK' command. The file will be in the module's build/outputs/aar.