org.liquidplayer.service

Class MicroService

java.lang.Object

org.liquidplayer.service.MicroService

All Implemented Interfaces:

Process.EventListener

public class MicroService
extends java.lang.Object
implements Process.EventListener

A MicroService is the basic building block of LiquidCore. It encapsulates the runtime environment for a client-side micro app. A MicroService is a complete virtual machine whose operation is defined by the code referenced by the service URI. When a MicroService is instantiated, its Node.js environment is set up, its code downloaded (or fetched from cache) from the URI, and is executed in a VM. The host may interact with the VM via a simple message-based API.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	MicroService.EventListener Listens for a specific event emitted by the MicroService
class	MicroService.ServiceAlreadyStartedError This runtime exception is thrown if an attempt is made to re-start a MicroService if it has already been started.
static interface	MicroService.ServiceErrorListener Listens for any errors that may cause the MicroService to shut down unexpectedly.
static interface	MicroService.ServiceExitListener Listens for when the MicroService has exited gracefully.
static interface	MicroService.ServiceStartListener Listens for when the MicroService has been inititialized and the environment is ready to receive event listeners.

Constructor Summary

Constructors

Constructor and Description
MicroService(android.content.Context ctx, java.net.URI serviceURI) Creates a new instance of the MicroService referenced by serviceURI
MicroService(android.content.Context ctx, java.net.URI serviceURI, MicroService.ServiceStartListener start) Creates a new instance of the MicroService referenced by serviceURI
MicroService(android.content.Context ctx, java.net.URI serviceURI, MicroService.ServiceStartListener start, MicroService.ServiceErrorListener error) Creates a new instance of the MicroService referenced by serviceURI
MicroService(android.content.Context ctx, java.net.URI serviceURI, MicroService.ServiceStartListener start, MicroService.ServiceErrorListener error, MicroService.ServiceExitListener exit) Creates a new instance of the MicroService referenced by serviceURI

Method Summary

Modifier and Type	Method and Description
void	addEventListener(java.lang.String event, MicroService.EventListener listener) Adds an event listener for an event triggered by 'LiquidCore.emit(event, payload)' in JavaScript.
static java.net.URI	DevServer() Generates a URI for fetching from a development server on the loopback address (10.0.2.2).
static java.net.URI	DevServer(java.lang.String fileName, java.lang.Integer port) Generates a URI for fetching from a development server on the loopback address (10.0.2.2).
void	emit(java.lang.String event) Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener.
void	emit(java.lang.String event, java.lang.Boolean v) Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener.
void	emit(java.lang.String event, java.lang.Double v) Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener.
void	emit(java.lang.String event, java.lang.Float v) Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener.
void	emit(java.lang.String event, java.lang.Integer v) Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener.
void	emit(java.lang.String event, org.json.JSONArray v) Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener.
void	emit(java.lang.String event, org.json.JSONObject payload) Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener.
void	emit(java.lang.String event, java.lang.Long v) Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener.
void	emit(java.lang.String event, java.lang.String v) Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener.
java.lang.String	getId() Each MicroService instance is mapped to a unique String id.
Process	getProcess() Returns the Node.js Process object.
static MicroService	getService(java.lang.String id) Each MicroService instance is mapped to a unique String id.
java.net.URI	getServiceURI() Returns the URI from which the service was started.
void	onProcessAboutToExit(Process process, int exitCode) Called when a node.js process has completed all of its callbacks and has nothing left to do.
void	onProcessExit(Process process, int exitCode) Called after a process has exited.
void	onProcessFailed(Process process, java.lang.Exception error) Called in the event of a Process failure
void	onProcessStart(Process process, JSContext context) Called when a node.js process is actively running.
void	removeEventListener(java.lang.String event, MicroService.EventListener listener) Removes an EventListener previously added with addEventListener.
void	start(java.lang.String... argv) Starts the MicroService.
static void	uninstall(android.content.Context ctx, java.net.URI serviceURI) Uninstalls the MicroService from this host, and removes any global data associated with the service

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MicroService

public MicroService(android.content.Context ctx,
                    java.net.URI serviceURI,
                    MicroService.ServiceStartListener start,
                    MicroService.ServiceErrorListener error,
                    MicroService.ServiceExitListener exit)

Creates a new instance of the MicroService referenced by serviceURI

Parameters:

ctx - The android context of this app

serviceURI - The URI (can be a network URL or local file/resource) of the MicroService code

start - The ServiceStartListener (optional)

error - The ServiceErrorListener (optional)

exit - The ServiceExitListener (optional)

MicroService

public MicroService(android.content.Context ctx,
                    java.net.URI serviceURI,
                    MicroService.ServiceStartListener start,
                    MicroService.ServiceErrorListener error)

Creates a new instance of the MicroService referenced by serviceURI

Parameters:

ctx - The android context of this app

serviceURI - The URI (can be a network URL or local file/resource) of the MicroService code

start - The ServiceStartListener (optional)

error - The ServiceErrorListener (optional)

MicroService

public MicroService(android.content.Context ctx,
                    java.net.URI serviceURI,
                    MicroService.ServiceStartListener start)

Creates a new instance of the MicroService referenced by serviceURI

Parameters:

ctx - The android context of this app

serviceURI - The URI (can be a network URL or local file/resource) of the MicroService code

start - The ServiceStartListener (optional)

MicroService

public MicroService(android.content.Context ctx,
                    java.net.URI serviceURI)

Creates a new instance of the MicroService referenced by serviceURI

Parameters:

ctx - The android context of this app

serviceURI - The URI (can be a network URL or local file/resource) of the MicroService code

Method Detail

DevServer

public static java.net.URI DevServer(@Nullable
                                     java.lang.String fileName,
                                     @Nullable
                                     java.lang.Integer port)

Generates a URI for fetching from a development server on the loopback address (10.0.2.2).

Parameters:

fileName - The name of the bundled javascript file to fetch (default: liquid.js)

port - The server's port (default: 8082)

Returns:

A service URI for use in the MicroService constructor

DevServer

public static java.net.URI DevServer()

Generates a URI for fetching from a development server on the loopback address (10.0.2.2). Assumes the entry js file is 'liquid.js' and is served from port 8082 on the emulator's host machine.

Returns:

A service URI for use in the MicroService constructor

addEventListener

public void addEventListener(java.lang.String event,
                             MicroService.EventListener listener)

Adds an event listener for an event triggered by 'LiquidCore.emit(event, payload)' in JavaScript. Example:

     LiquidCore.emit('my_event', { stringData: 'foo', bar : 6 });
 

This will trigger the 'listener' added here, with the JavaScript object represented as a JSONObject payload.

Parameters:

event - The String event id

listener - The event listener

getId

public java.lang.String getId()

Each MicroService instance is mapped to a unique String id. This id can be serialized in UIs and the instance retrieved by a call to MicroService.getService(id)

Returns:

The unique id of this instance

getProcess

public Process getProcess()

Returns the Node.js Process object.

Returns:

The Node.js Process object

getServiceURI

public java.net.URI getServiceURI()

Returns the URI from which the service was started.

Returns:

The URI of the service

removeEventListener

public void removeEventListener(java.lang.String event,
                                MicroService.EventListener listener)

Removes an EventListener previously added with addEventListener.

Parameters:

event - The event for which to unregister the listener

listener - The listener to unregister

emit

public void emit(java.lang.String event,
                 org.json.JSONObject payload)

Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener. Example:

     LiquidCore.on('my_event', function(payload) {
        // Do something with the payload data
        console.log(payload.hello);
     });
 

On the Java side:

     JSONObject foo = new JSONObject();
     foo.putString("hello", "world");
     myService.emit("my_event", foo);
 

Parameters:

event - The event to trigger

payload - The JSONObject data structure to emit

emit

public void emit(java.lang.String event)

Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener. Example:

     LiquidCore.on('my_event', function() {
        console.log('Received my_event');
     });
 

On the Java side:

     myService.emit("my_event");
 

Parameters:

event - The event to trigger

emit

public void emit(java.lang.String event,
                 java.lang.Integer v)

Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener. Example:

     LiquidCore.on('my_event', function(val) {
        console.log('Received: ' + val);
     });
 

On the Java side:

     myService.emit("my_event", 5);
 

Parameters:

event - The event to trigger

v - value to send

emit

public void emit(java.lang.String event,
                 java.lang.Long v)

Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener. Example:

     LiquidCore.on('my_event', function(val) {
        console.log('Received: ' + val);
     });
 

On the Java side:

     myService.emit("my_event", 5L);
 

Parameters:

event - The event to trigger

v - value to send

emit

public void emit(java.lang.String event,
                 java.lang.Float v)

Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener. Example:

     LiquidCore.on('my_event', function(val) {
        console.log('Received: ' + val);
     });
 

On the Java side:

     myService.emit("my_event", 5.2f);
 

Parameters:

event - The event to trigger

v - value to send

emit

public void emit(java.lang.String event,
                 java.lang.Double v)

Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener. Example:

     LiquidCore.on('my_event', function(val) {
        console.log('Received: ' + val);
     });
 

On the Java side:

     myService.emit("my_event", 15.6);
 

Parameters:

event - The event to trigger

v - value to send

emit

public void emit(java.lang.String event,
                 java.lang.String v)

Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener. Example:

     LiquidCore.on('my_event', function(val) {
        console.log('Received: ' + val);
     });
 

On the Java side:

     myService.emit("my_event", "foo");
 

Parameters:

event - The event to trigger

v - value to send

emit

public void emit(java.lang.String event,
                 java.lang.Boolean v)

Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener. Example:

     LiquidCore.on('my_event', function(val) {
        console.log('Received: ' + val);
     });
 

On the Java side:

     myService.emit("my_event", true);
 

Parameters:

event - The event to trigger

v - value to send

emit

public void emit(java.lang.String event,
                 org.json.JSONArray v)

Emits an event that can be received by the JavaScript code, if the MicroService has registered a listener. Example:

     LiquidCore.on('my_event', function(val) {
        console.log('Received: ' + val);
     });
 

On the Java side:

     JSONArray a = new JSONArray();
     a.put(0);
     a.put("two");
     myService.emit("my_event", a);
 

Parameters:

event - The event to trigger

v - value to send

start

public void start(java.lang.String... argv)

Starts the MicroService. This method will return immediately and initialization and startup will occur asynchronously in a separate thread. It will download the code from the service URI (if not cached), set the arguments in `process.argv` and execute the script.

Parameters:

argv - The list of arguments to sent to the MicroService. This is similar to running node from a command line. The first two arguments will be the application (node) followed by the local module code (/home/module/[service.js]. 'argv' arguments will then be appended in process.argv[2:]

uninstall

public static void uninstall(android.content.Context ctx,
                             java.net.URI serviceURI)

Uninstalls the MicroService from this host, and removes any global data associated with the service

Parameters:

ctx - The Android context

serviceURI - The URI of the service (should be the same URI that the service was started with)

onProcessStart

public void onProcessStart(Process process,
                           JSContext context)

Description copied from interface: Process.EventListener

Called when a node.js process is actively running. This is the one and only opportunity to start running JavaScript in the process. If the receiver returns from this method without executing asynchronous JS, the process will exit almost immediately afterward. This is the time to execute scripts. If the caller requires this process to remain alive so scripts can be executed later, Process.keepAlive() should be called here. This method is called inside of the node.js process thread, so any JavaScript code called here is executed synchronously. In the event that an EventListener is added by Process.addEventListener() after a process has already started, this method will be called immediately (in the process thread) if the process is still active. Otherwise, onProcessExit() will be called. Clients must hold a reference to the context for as long as they want the process to remain active. If the context is garbage collected, the process will be exited automatically in order to prevent misuse.

Specified by:

onProcessStart in interface Process.EventListener

Parameters:

process - The node.js Process object

context - The JavaScript JSContext for this process

onProcessAboutToExit

public void onProcessAboutToExit(Process process,
                                 int exitCode)

Description copied from interface: Process.EventListener

Called when a node.js process has completed all of its callbacks and has nothing left to do. If there is any cleanup required, now is the time to do it. If the caller would like the process to abort its exit sequence, this is the time to either call Process.keepAlive() or execute an asynchronous operation. If no callbacks are pending after this method returns, then the process will exit. This method is called inside of the node.js process thread, so any JavaScript code called here is executed synchronously.

Specified by:

onProcessAboutToExit in interface Process.EventListener

Parameters:

process - The node.js Process object

exitCode - The node.js exit code

onProcessExit

public void onProcessExit(Process process,
                          int exitCode)

Description copied from interface: Process.EventListener

Called after a process has exited. The process is no longer active and cannot be used. In the event that an EventListener is added by Process.addEventListener() after a process has already exited, this method will be called immediately.

Specified by:

onProcessExit in interface Process.EventListener

Parameters:

process - The defunct node.js Process object

exitCode - The node.js exit code

onProcessFailed

public void onProcessFailed(Process process,
                            java.lang.Exception error)

Description copied from interface: Process.EventListener

Called in the event of a Process failure

Specified by:

onProcessFailed in interface Process.EventListener

Parameters:

process - The node.js process object

error - The thrown exception

getService

public static MicroService getService(java.lang.String id)

Each MicroService instance is mapped to a unique String id. This id can be serialized in UIs and the instance retrieved by a call to MicroService.getService(id)

Parameters:

id - An id returned by MicroService.getId()

Returns:

The associated MicroService or null if no such service is active