The org.nibiru.mobile.core project contains common classes: unified API and generic components. These classes are arranged into different packages, which are explained in the following sections.

The org.nibiru.mobile.core.api.app package contains interfaces related to app setup.

The Bootstrap interface represents the steps which are neccessary in order to start the application on a given platform. To put it in another way, there are specific bootstrap for Android, GWT, etc.

On the other hand, the EntryPoint interface represents startup logic which is application-specific, but platform independent.

Typically, there will be a unique entry point for each application. For example, you could have an entry point like this:

...
imports, etc
...

public class SampleEntryPoint implements EntryPoint {
	private PlaceManager placeManager;

	@Inject
	public SampleEntryPoint(PlaceManager placeManager) {
		this.placeManager = checkNotNull(placeManager);
	}

	@Override
	public void onApplicationStart() {
		this.placeManager.createPlace(DefaultPlaces.LOGIN).go();
	}
}

Since the frameworks aims to be compatible with HTML5 development, it must take into account asynchronous callback handling. In other platforms (such as Android or iOS), you would simply create threads as needed (for example, when you are going to execute a blocking operation). However, GWT code is translated into JavaScript, which is single-threaded. When a blocking operation is excetued (such as an Ajax call or a WebSQL operation) is executed, a callback must be used.

So, portable code must be written using callbacks. In order to accomplish this, the package org.nibiru.mobile.core.api.async provides the Callback interface, which aims to unifiy different callbacks used on different libraries.

The org.nibiru.mobile.core.impl.async package provides some utility classes for asynchronous callback handling.

The BaseCallback is a generic base class which implements the exception callback method, simply showing the error to the user with an alert message.

On a layered application, callbacks usually will pass thorug different classes. However, each layer tipically would excetute some logic (otherwise, maybe the layer is poorly designed). Chaining callbacks is a tedious task, so we provide a class for this purpose, called ChainCallback.

It chains the exception callback method and provides a method for accessing the chained callback. For example, the following snippet shows how a login method could be implemented:

...
private void remoteLogin(final String username,
	final String password,
	Callback<Boolean> callback) {
	this.authenticationService.login(username,
			password,
			new ChainCallback<UserDto, Boolean>(callback) {
		@Override
		public void onSuccess(final UserDto userDto) {
			if (userDto != null) {
				// update profile, etc...
				getChained().onSuccess(true);
			} else {
				getChained().onSuccess(false);
			}
		}
	}
}
...

The org.nibiru.mobile.core.api.config package contains annotations used for application configuration. These include:

• AppName: The name of the application.
• AppVersion: The application version.
• BaseUrl: Base URL, used for remote service calling.

Such annotations are used when configuring IoC injector for a given application (see example code).

The org.nibiru.mobile.core.ioc package provides default Guice-based configuration modules. Specific (RoboGuice for Android, GIN for GWT and plain Guice for iOS/Vaadin) configuration modules can be found on platform-specific projects.

There are interfaces which don't fit well into any of the above categories. They are stored inside org.nibiru.mobile.core.api.common and org.nibiru.mobile.core.impl.common packages - until we improve the design :).

The Configurable interface represent anything that can have parameters. BaseConfigurable provides a base implementation for configurables.

Meanwhile, Identifiable represents anything that has an identifier.

The org.nibiru.mobile.core.api.event package provides an unified interface for accessing an EventBus.

Due to platform limitations, Events are identified by its ID (instead of using the class, as usual). They are represented by Event interface.

Also, an Event can have parameters (Configurable interface). Together with EventBus, you can fire Events using DSL-like method chaining:

...
eventBus.createEvent("showAlert")
		.addParameter("message", message)
		.fire();  
...

The EventHandler interface is also standardized.

The org.nibiru.mobile.core.api.http package provides interfaces for posting HTTP messages in an unified way.

The HttpManager allows sending this kind of messages. (currently, only POST is needed). It receives a HttpCallback which must supply methods for creating the request data and parsing the HTTP response. This way, message creation is decoupled from HTTP messaging implementation.

When sending an object across the network, some kind of serialization is needed. For example, you could convert the object into a JSON or a XML stream. The package org.nibiru.mobile.core.api.serializer provides the Serializer interface, which abstracts such process.

Remote services are also abstracted. They are represented by the RemoteService interface form org.nibiru.mobile.core.api.service package.

Remote service implementation is responsible for building the message body. The org.nibiru.mobile.core.impl.service includes some common implementations:

• JsonRpcService, for JSON-RPC
• RestService, for REST-like messages (a simple POST using the URL for the method name).

Both implementations rely on HttpManager.

The org.nibiru.mobile.core.api.ui package includes interfaces for manipulating user interface. At this level, 2 interfaces are provided:

• AlertManager: It allows showing messages to the user.
• Looper: The looper allows posting events on the UI thread. You tipically won't need to use it directly. Service classes use it to process the response from the server, since the HTTP call runs on a different thread.

The remaining functionality is included in different subpackages.

Navigation between views is represented through places. The org.nibiru.mobile.core.api.ui.place package provides interfaces useful for accomplishing this task.

The Place interface abstracts this concept. Places are created using a PlaceManager instance.

Together, they allows navigating using a DSL-like syntax, using method chaining. For example:

...
placeManager.createPlace(DefaultPlaces.HOME)
			.addParameter("message", message)
			.go(false);  
...

As seen on the example, there is an enumeration with identifiers for common places called DefaultPlaces.

The org.nibiru.mobile.core.api.ui.mvp package provides interfaces for abstracting different implementations for MVP pattern.

Under this pattern, the UI logic is contained into a Presenter which holds a reference to a View.

The view shouldn't contain logic. Its responsibilities should be limited to showing data (including international ization) and firing events. This way, views can be easily replaced when changing the platform, while presenter keeps unchanged. This approach also allows taking advantage of native view capabilities.

When navigating to a specific place, a presenter for handling such place must be selected. This is accomplished by implementing a PresenterMapper.

The org.nibiru.mobile.core.impl.mvp package provides base implementations for both, PresenterMapper and Presenter.

Base class for PresenterMapper is BasePresenterMapper.

The BasePresenter includes an inner class, Cbk, which allows an easy creation of callbacks. It injects the AlertManager automatically into the callback.

Inside a presenter which extends BasePresenter, you can simply could run something like this:

...
geolocationManager.watchPosition(new Cbk<Position>() {
	@Override
	public void onSuccess(Position result) {
		//...
	}
});
...

A simple API for storing user preferences can be found at org.nibiru.mobile.core.api.preferences package. The Preferences interface allows accessing the preferences. It extends Configurable, so preference data can be loaded or stored using its methods.

The org.nibiru.mobile.core.impl.preferences package provides a base class for implementing preferences, AbstractPreferences which provides useful functionality such as data conversion. \end_layout

The org.nibiru.mobile.core.api.geolocation provides fucntionality for accessing to location hardware. The main interface is GeolocationManager.

Location information is accessed using Position and Coordinates interfaces.