Changes
Created page with " This page describes the API provided by the [[{{UBIK}} Android SDK]]. == Installation & Usage == === Library References === The {{UBIK}} Android SDK consists of multiple An..."
This page describes the API provided by the [[{{UBIK}} Android SDK]].
== Installation & Usage ==
=== Library References ===
The {{UBIK}} Android SDK consists of multiple Android libraries.
These libraries have to be imported into the IDE's workspace and added as Android library references to the target project (which must be an Android application project).
=== Authenticator Service ===
{{UBIK}} Android needs an authenticator service to work properly. It is already provided by the Kernel library, but it has to be defined in the manifest, too.
Add the following code to your AndroidManifest.xml, inside the Application tag:
<pre>
<!-- The authenticator service -->
<service
android:name="com.augmensys.{{UBIK}}.authentication.AuthenticationService"
android:exported="true" >
<intent-filter>
<action android:name="android.accounts.AccountAuthenticator" />
</intent-filter>
<meta-data
android:name="android.accounts.AccountAuthenticator"
android:resource=
"@your.project.package:xml/authenticator" />
</service>
</pre>
Also, create a file authenticator.xml in the res/xml folder of your project. It should contain the following code:
<pre>
<account-authenticator xmlns:android="http://schemas.android.com/apk/res/android"
android:accountType="@string/{{UBIK}}_account_type"
android:icon="@drawable/ic_launcher"
android:smallIcon="@drawable/ic_launcher"
android:label="@string/app_label"
/>
</pre>
Please replace the phrase "your.project.package" with your app's pacakge name and adjust the account type string resource.
=== Enable Manifest Merger ===
In order for the {{UBIK}} Android SDK’s plugins to be loaded automatically, we need the Android manifest merger to be enabled. Please add the following line to your pro-ject.properties file:
<pre>
manifestmerger.enabled=true
</pre>
== Function and Architecture ==
=== Technical Basis ===
Basically, the {{UBIK}} Android SDK uses the Android Java framework providing {{UBIK}} client functionality organized in the [[Plugins and Modules]] technique.
This means that there are a lot of modules playing together as more or less autonomous singleton entities accessable via an interface.
=== Abstract Architecture ===
On a more abstract level, the {{UBIK}} Android framework is built around the Kernel plugin, which provides basic features for dealing with the {{UBIK}} data models and content, and server interaction.
All further plugins add their own special functions, like a UI, AR features or a Push service.
=== User Management ===
{{UBIK}} Android is a multi-user environment. Every user has their own content and settings (while some settings are user-independent, "global" ones).
=== App Life Cycle ===
All {{UBIK}} Android modules greatly depend on the app's life cycle.
This life cycle knows three timings:
* App Start
* Session Start
* Session End
A session starts with the user logging in and ends with the user logging out.
Most features and modules only work correctly while a session is active, since they depend on user specific settings or content.
=== Content Model ===
A very important basic information is how {{UBIK}} content is organized.
See the official Wiki page for a detailed explanation:
http://wiki.augmensys.com/index.php/Entity_Data_Model
==== Meta Definitions ====
All {{UBIK}} content is described using Meta Classes and Meta Properties.
They define which data types are used and which properties a content object has.
Such meta definitions are needed e.g. when creating a new content.
For example, meta definitions could describe what a pump looks like in general.
One could see meta definitions as the Java equivalent of a class.
==== The !ContentClass ====
A content class instance represents a {{UBIK}} object. It provides access to its properties and related objects.
One could see content objects as the Java equivalent of an instance (of a previously described class).
Content objects are identified by a UUID.
A content object can be accessed via the Data Provider module, various classification modules or several observables notifying listeners when content has changed, e.g. the Content Change Publisher module.
==== Properties ====
Properties contain atomic data on a {{UBIK}} object, consisting of a value and a unit. A {{UBIK}} content object can have multiple properties.
E.g., an object "Pump 1" can have a property "Pressure" of the type Double with the unit "pascal".
Properties are identified by the UUID of their content object and the UUID of their meta property (which describes it).
A property can be accessed using the content object and its methods.
==== Classified Content ====
Meta classes can be classified as specific types of objects. Such classifications mainly describe what a {{UBIK}} object must look like (just like a meta definition does), but also indicates the behaviour of all classified objects.
E.g., {{UBIK}} content can be classified as Document objects, which (amongst other details) defines that there is a file for that object.
Another classification is the Task classification, which tells us that the respectively classified object has a state that can be changed by the user.
=== Synchronization and Data Hierarchy ===
==== Data Hierarchy ====
{{UBIK}} content objects are relational objects, being connected to other objects. The {{UBIK}} content web service delivers data in a hierarchical manner.
This means there is a tree of parent and child objects in the so-called Abstract Content View provided by the web service.
==== Synchronization ====
Hence, the web service provides methods for synchronizing branches of this con-tent tree.
There are methods for uploading content changes (retrieving the resulting, changed content) and for downloading content.
In {{UBIK}} Android, we call the uploading of content “committing” and the downloading “updating”.
The Synchronization Manager is the module that can be used for triggering these commit or update synchronization tasks.
You can get it using the Kernel class:
<pre> ISynchronizationManager syncMan = Kernel.getSynchronizationManager(); </pre>
==== Sync Modes ====
There are three synchronization behaviours or strategies (the “Sync Modes”) in {{UBIK}} Android:
Automatic, Manual and Offline.
In Automatic Mode, all synchronization tasks are executed without consideration, whereas in Manual and Offline Mode you have to explicitely force a commit (upload) sync task if it should be executed.
In Automatic and Manual mode, updates (downloads) needn’t be forced, in Offline Mode even they need to be forced.
Why is this sync mode mechanism interesting?
Imagine your app has a lot of auto-matic synchronization triggers all over the UI (as our standard app does).
In this case you may want to give the user the choice to turn them off or to do things at least partly manually (e.g. uploading changed content).
==== Web Service Client Configuration ====
In order to configure to which service the client should connect, the settings can be adjusted either using the Settings Activity the UI library provides or by adjusting the values programmatically using the {{UBIK}}Settings module the Kernel library provides.
Another possibility is changing the default setting constants in a string resource file, e.g. constants.xml.
== Libraries, Plugins and Modules ==
=== Basic Libraries ===
As a technical basis for the {{UBIK}} Android framework, the ''Common'' and ''!PluginManagement'' libraries are required.
=== Kernel ===
The ''Kernel Plugin'' provides standard functionality like authentication, local data storage access using the Data Provider, synchronization, the user notifier interface and {{UBIK}} settings.
It also allows access to more internal modules that normally shouldn't be used directly like the web service client, the internal settings module and the database adapter.
All modules can be accessed using getters in the static Kernel class.
Inside the Kernel, there are mainly the following interesting modules which can be accessed using the static ''Kernel'' class.
==== Data Provider ====
The data provider has methods for getting and creating content objects. It is also used internally in order to save or delete content.
==== Content Change Publisher ====
You can register listeners at the content change publisher in order to be notified whenever a content object is created, changed or deleted.
==== Synchronization Manager ====
The synchronization manager provides methods for sending ("committing") local changes to the server and fetching ("updating") content from the server.
==== Synchronization Publisher ====
You can register listeners at the synchronization publisher in order to know when synchronization tasks are finished or started.
==== Sync Mode Manager ====
The sync mode manager allows switching the synchronization strategy, e.g. to Offline Mode or Automatic Mode.
==== Document Classification ====
The document classification module provides access to document objects and document-related features.
==== User Notifier ====
The user notifier interface provides methods for communicating with the user via Android Toasts, Notifications and Dialogs.
==== Location Manager ====
The location manager interface provides the device's current location.
==== Authentication Manager ====
The authentication manager provides user account and session related methods, e.g. for logging in and out.
=== UI ===
The ''UI Plugin'' provides modules for user interaction, like the *!ActivityDefinition modules and the respective implementations which encapsule most of the API for this actually.
Mostly activities, widgets and configuration features are available in the UI plugin.
All modules can be accessed using the static UI class.
=== AR ===
The ''AR Plugin'' provides modules for scanning a variety of (optical or electro-magnetic) codes, finding objects and of course the AR POI view and the map view including several filtering features.
All modules can be accessed using the static AR class.
=== Push ===
The ''Push Plugin'' provides a push service including modules for configuring it and reacting to the incoming pushes in a customized manner.
All modules can be accessed using the static Push class.
