api v4 guidelines

API v4.x Guidelines

Since version 4.0 the Javascript API supports only GraalVM Javascript engine.

API developers have to follow the rules below when introducing new APIs, which require communication with the JVM underneath:

Facades

1. From the Java side a "facade" has to be implemented with public methods, which are supposed to be called by the Javascript engine.

Sample Java Facade:

    ...

    public static final String getAttribute(String name) {
		HttpServletRequest request = getRequest();
		if (request == null) {
			throw new InvalidStateException(NO_VALID_REQUEST);
		}
		return request.getAttribute(name) != null ? request.getAttribute(name).toString() : null;
    }

    ...

Sample Javascript Call:

    ...

    exports.getAttribute = function(name) {
	var attr = org.eclipse.dirigible.api.v3.http.HttpRequestFacade.getAttribute(name);
	return attr;
    };

    ...

Note: for custom packages use Packages object:

exports.isInert = function() {
	var output = Packages.io.dirigible.helium.HeliumFacade.isInert();
	return output;
};

Note: an option is to use JavaImporter:

exports.isInert = function() {
	var helium = new JavaImporter(Packages.io.dirigible.helium);
	with (helium) {
		var output = HeliumFacade.isInert();
		return output;
	}
};

2. It is highly recommended the the Java facade and Javascript API module to relate to each other as 1:1
3. The Javascript modules must be placed in repositories in the GitHub's DirigibleLabs organization following the naming convention "api-XXX" where the XXX is the particular name of the API group of modules e.g. core, http, utils, etc.

e.g. https://github.com/dirigiblelabs/api-http

4. The repository should have a root folder named in the same way as the API group part of the repository following the subfolder "v4". All the modules in this group should be placed under "v4" subfolder and below.
5. A separate module in the main Eclipse Dirigible repository have to be created under the "content" subfolder containing all the "webjars" modules.

e.g. https://github.com/eclipse/dirigible/tree/master/api/api-javascript/api-http

6. The necessary test cases have to be introduced in the "dirigible-api-tests" module https://github.com/eclipse/dirigible/blob/master/api/api-facades/api-tests/src/main/java/org/eclipse/dirigible/api/v3/test/AbstractApiSuiteTest.java, to guarantee the compatibility between the Javascript engines.

e.g. https://github.com/eclipse/dirigible/tree/master/api/api-facades/api-tests/src/main/resources/http/v4