GeoAR Codebase

The GeoAR codebase is an online storage system for extensions/plugins to be used within the augmented reality client software GeoAR. Currently it supports the download of GeoAR data sources (see also GeoARDatasource) based on Android packages (APK files). The codebase provides methods to list available resources, inspect single resources, upload new resources, and update/change the binary file and metadata of a resource.


  • RESTful service interface
    • Retrieve resource listing
    • Retrieve resource descriptions
    • Retrieve resource file
    • Upload resource
    • Update resource
  • HTML, plain text, and JSON response formats
  • Content negotiation with HTTP Accept headers

Example Deployment

An online deployment of a GeoAR Codebase can be found here:

Using the Codebase

Server Installation

The installation of a GeoAR Codebase requires the following steps:

  1. Check out source code
    See below for instructions.
  2. Configure properties
    • Open the file pom.xml and set the following properties according to your setup:
    • Open.../src/main/java/resources/ with a text editor and set respectively change all required parameters, see Configuration.
    • Adjust the config parameters in the file .../src/main/webapp/WEB-INF/web.xml to your needs, see Configuration.
  1. Run mvn clean package.
  2. Deploy the created web application archive (WAR file) into your Tomcat.
  3. Browse to the welcome page.


  • uploadToken: The token is used to allow upload of new and changes to existing resources, see also section Authentication and Upload. Default value is maven property conf.geoar.codebase.uploadToken.


The web.xml is the generic configuration file for the webapp, but also allows the configuration of context parameters, which are used for variables that must be accessed from JSP files.

Context parameters for GeoAR Codebase

  • serviceUrl: This parameter is used in the JSP file content.jsp to load the correct base URL for the service and to create correct example links on the website, and (most importantly) in the application ( to generate the download links. Example value for local testing: http://localhost:8080/geoar
  • codebasePath: Default and suggested not to change: codebase
  • serviceInfo: Short description of the service, which is included in the responses to describe the source of the information. Change this to a suitable description to your own deployment. Example: Codebase for 52°North GeoAR Augmented Reality Application

Source Code

You can check out the source code from the 52°North Subversion repository:

The SVN follows the typical trunk/branch/tag layout, details here. As of writing this tutorial, all development happens within the trunk.

Browse the code here.

Authentication and Upload

Authentication is handled using simple tokens appended to the query part of the URL.

URL: http://server.url/<webapp_name>/codebase?token=<token_goes_here>

The tokens are stored in the file Currently there is only one token, uploadToken, which allows users to upload new resources to the codebase listing endpoint and to edit existing resources on the resource view endpoint. For defining tokens we strongly recommend using long and arbitrary text, for example from here.

Upload a new Resource

You can also overwrite exsiting resources with this form. Upload uses a regular HTTP POST request, so you can also implement upload with an arbitrary client (not just the HTML form below).


URL Patterns and Response Examples

Landing Page

URL: http://server.url/<webapp_ name>/


HTML Response


Codebase Listing

The contents of the codepage, i.e. an index file.

URL: http://server.url/<webapp name>/codebase/


HTML Response


JSON Response

The JSON response is very similar to the index file. It contains a list of datasources, which are the resources. There is also a description text field.

   "datasources": [
         "description": "just another one", 
         "downloadLink": "", 
         "id": "test", 
         "imageLink": "", 
         "name": "Small test", 
         "platform": "2.3", 
         "version": 1
         "description": "For testing only, if a apk is recognized by Android...", 
         "downloadLink": "", 
         "id": "noisedroidsigned", 
         "imageLink": "", 
         "name": "Noise Droid App", 
         "platform": "2.3", 
         "version": 1
   "service": "Codebase for 52°North GeoAR Augmented Reality Application"

Plain Text Response

Codebase for 52°North GeoAR Augmented Reality Application

Small test
Id: test
Description: just another one

Noise Droid App
Id: noisedroidsigned
Description: For testing only, if a apk is recognized by Android...

Single Resource

This response hold the description of a single resource and a link to the binary file for download.

URL: http://server.url/<webapp name>/codebase/<resource identifier>


HTML Response

This view is the same as the listing, but with just one element.

If you are authenticated with a token for uploading resources, then the HTML page contains a prepared form to edit the properties of the shown resource. You can upload a new file and leave other fields untouched as well as change only one of the available fields.


JSON Response

The JSON format is the same as for the resource listing (see above), just with only a single resource.

Plain Text Response

The plain text format is the same as for the resource listing (see above), just with only a single resource.


If you have a problem, please check the 52°North Geostatistics Community forum and mailing list: (Forum link in the left hand side menu, mailing list subscription and archive in the center. Please note that forum and mailing list are synchronized!)

If you don't find a solution, take a short look at the guidelines and ask your question - you'll be helped!



GeoAR Codebase uses Apache Maven for all dependency management. However, a short list of libraries that are used is shown below.

For a full and updated list please take a look at the POM file:

Development Setup

You can check out the source code (see above) right into your Eclipse workspace. Recommended Eclipse extensions are m2e and Subversive.

Version Numbering

Please follow the guidelines of Semantic Versioning ( for naming new versions.

In addition to that, the project uses the Buildnumber Maven Plugin ( buildnumber-maven-plugin) for automatically attaching a revision number to each build, e.g. . The current build number is stored in the file .../src/main/config/

Persistent Storage

At the time of writing this tutorial, GeoAR Codebase does not use any database but utilizes a manual approach.

Uploaded resources (the code binaries) are stored in the folder .../<webabb_name>/codebase/ on the server.

The resource metadata are stored in the file .../src/main/java/resources/datasources.json in the source, and in the file .../.../datasources.json on the server.

Only resources with both metadata information and binary resource file are listed/accessible!

It is possible to add new resources by editing the index file manually and store the correctly named source binary in the resource folder, however it is recommended to use the upload form or the REST interface to be sure everything is properly tested.

Resource Attributes

  • id: Identifier of the resource. This must be tha same as the name of the APK file in the codebase directory.
  • name: Name of the resource.
  • description: Human-readable short desription of the resource.
  • imageLink: Descriptive picture to show in resource listings.
  • version: Version of the resource, can be used to detect in a client if a new version of a plugin is available.
  • platform: The minimal Android platform version number.


  • Add "Delete" button to a single resource HTML rendering
  • Add image upload (storing the image on the server and putting a link to that file in the resource description)
  • Change persistent storage to simple (file) database
  • Content negotiation change to extension (.json, .xml, .txt), especially .apk and .png (just a Restlet setting!!)
  • ...


  • Topic created by: DanielNuest
  • Topic created on: 2012-06-20
create new tag
, view all tags
Topic revision: r6 - 2013-01-17 - 12:01:04 - HolgerHopmann

  • Search: 
This site is powered by the TWiki collaboration platform Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback