Tutorial

Introduction

These notes provide a short tutorial on building a Java module implementation.

It is assumed that a declaration of the API exists in WebIDL, and that the interface definition complies with the restrictions imposed by the bridge (which mainly relate to the uses of particular types, and are set out in the type mapping documentation).

Prerequisites

Locate the Java module SDK.

There are no other dependencies, but these notes generally assume that the Java development is being conducted in Eclipse.

Generate Java declarations for each interface and dictionary type

Automated support for this step, using the WebIDL text as input, is planned. However, for now this must be done by hand.

Refer to the type mapping documentation.

Interfaces - platform objects

For each interface defining a platform object, create an abstract java class that (directly or indirectly) extends org.meshpoint.anode.java.Base.

The class must include a constructor that passes an instance of org.meshpoint.anode.idl.IDLInterface (which contains metadata relating to the interface) to the superclass constructor, and it is recommended that it takes the following form.

package com.example.api;

import org.meshpoint.anode.bridge.Env;
import org.meshpoint.anode.idl.IDLInterface;
import org.meshpoint.anode.java.Base;

public abstract class PlatformInterfaceExample extends Base {
	private static IDLInterface iface = Env.getCurrent().getInterfaceManager().getByClass(PlatformInterfaceExample.class);
	protected PlatformInterfaceExample() { super(iface.getID()); }

...
}

Next, declare the constants, attributes and operations belonging to the IDL interface in accordance with the defined type mapping.

package com.example.api;

import org.meshpoint.anode.bridge.Env;
import org.meshpoint.anode.idl.IDLInterface;
import org.meshpoint.anode.java.Base;

public abstract PlatformInterfaceExample extends Base {
	private static IDLInterface iface = Env.getCurrent().getInterfaceManager().getByClass(PlatformInterfaceExample.class);
	protected Contact() { super(iface.getID()); }

	public String attribute1;
	public int    attribute2;
	public abstract void operation1(String arg1, DictExample arg2, CallbackExample arg3);
}

Interfaces - user objects

For each interface defining a user object, create a java interface that (directly or indirectly) extends org.meshpoint.anode.idl.Callback.

Add a method declaration for each declared operation, and a getter and a setter method declaration for each declared attribute. Also, add a public static final field for each declared constant.

package com.example.api;

import org.meshpoint.anode.idl.Callback;

public interface CallbackExample extends Callback {

	public static final String constant1 = "Hello world!"
	public void operation1(String arg1);
	public int getStatus();
	public void setStatus();
}

Dictionaries

For each dictionary type, write a Java class that declares the dictionary members with the appropriate mapped Java type.

package com.example.api;

import org.meshpoint.anode.idl.Dictionary;

public class DictExample extends Dictionary {

	public static final String constant1 = "Bye!"
	public String member1;
	public boolean member2;
}

Create concrete implementation classes for each platform interface

Create a class that concretely implements the abstract class defined for the interface to be implemented by a platform object. This class will contain all of the real module functionality for that interface.

package com.example.impl;

import com.example.PlatformInterfaceExample;
public class PlatformImplExample extends PlatformInterfaceExample {



	PlatformImplExample() {
		attribute1 = "a default value";
		attribute2 = 42; 
	}

	public void operation1(String arg1, DictExample arg2, CallbackExample arg3) {
		arg3.operation1(arg2.member1 + arg1);
	}
}

Note that the argument arg2, of declared dictionary type, is simply an instance of the corresponding declared Java class. Also, the platform object simply calls one of the declared methods on the supplied user object, providing arguments of the correct type.

All mapping to and from JS and Java types, including the coercions expected by WebIDL, are implemented by the bridge.

Create a concrete implementation of the IModule interface

In order for these Java classes to be loadable, there needs to be an implementation of the IModule interface.

It is common for the top-level platform object class (which is often a singleton, "Manager" class) to itself be the implementation of IModule.

package com.example.impl;

import com.example.PlatformInterfaceExample;
import org.meshpoint.anode.module.IModule;
import org.meshpoint.anode.module.IModuleContext;

public class PlatformImplExample extends PlatformInterfaceExample implements IModule {
	PlatformImplExample() {
		attribute1 = "a default value";
		attribute2 = 42; 
	}

	public void operation1(String arg1, DictExample arg2, CallbackExample arg3) {
		arg3.operation1(arg2.member1 + arg1);
	}

	public Object startModule(IModuleContext ctx) {
		return this;
	}

	public void stopModule() {}
}