JSweet Candies

A JSweet candy is a specially-packaged Maven artifact that corresponds to a library/framework/API that you can include in your JSweet project to build JavaScript applications. A candy contains three elements:

1. a Java API and/or implementation,
2. the corresponding TypeScript definitions (necessary for the TypeScript to JavaScript compilation),
3. and, optionally, the compiled JavaScript implementation, to be used for running the library/framework/API.

Candies are of two different kinds:

• A regular JS candy (a.k.a. a bridge): a bridge to an existing JavaScript library/framework/API. For instance: Backbone, Angular, JQuery, Nodejs, and Cordova are all packaged as JSweet candies. JS candies contain well-typed Java declarations, which are conceptually similar to header files in C (*.h files). Library declarations imply no runtime and are “only” used to ensure typing and the correct use of external JavaScript libraries at compile time.
• A Java candy: a JSweet-compiled implementation of a Java library/framework/API. Java candies can be created as reusable modules for your project. A Java candy will contain the Java implementation (which can be fully Java-compatible), the TypeScript definitions, and the JSweet-compiled JavaScript. Some useful Java libraries are already compiled and can be found as J4TS candies, which are part of the J4TS organization. In many cases, J4TS candies are just Java libraries excerpts that can be compiled as is with JSweet.

When using Maven, from Java, you can simply include any JavaScript or Java library by adding a dependency to the corresponding candy (if available).

Where to find candies?

Anyone can build a new candy. However, there are places where to find already-made candies.

Library kind	Link	Description
JavaScript	Releases	Releases for all the available candies (includes automatically generated candies from DefinitelyTyped, and JSweet candies written in Github/jsweet-candies). This space includes online Javadoc.
	Github/jsweet-candies	In this Github organization, you will find all candies that are written and editable as JSweet definitions.
Java	Github/j4ts	In this Github organization, you will find all JSweet implementations for Java APIs. These will help the programmers to share Java code between a Java server and a WEB client. They can also help to port legacy Java applications to the WEB. Maven group: org.jsweet.candies.j4ts.

Besides, you can browse our Maven repository to look up for releases and snapshots. Candies are in the org.jsweet.candies Maven group. J4TS candies are located in org.jsweet.candies.j4ts.

How to create/update your own candies

Creating your own candy is quite straightforward. When creating a candy for an existing JavaScript API, all you need to do it to bridge that API with well-typed Java declarations (similarly to *.h header files in C). In JSweet, you just need to declare your variables/functions/classes in a def.libname package so that JSweet understands that it is an API bridge. Declarations in the def package contain no implementations and all methods are native methods. They are compile-time entities, which are used by the compiler to ensure typing.

Note that in your JSweet project, you can create your own bridges on the fly just by creating a def package. Once you want to share these bridges with several projects, you may want to package them as actual candies (Maven artifacts). To get started, you can clone the following template, which contains a basic API bridge example packaged with Maven: jsweet-candy-js-quickstart.

Although it is simple to write your own bridges, it can be quite boring to rewrite all the APIs for a given library. JSweet provides an open source API translator / candy generator that can give you a head start when translating API from TypeScript definition files (*.d.ts). A TypeScript definition file contains declarations, exactly like JSweet declarations in the def package, and can be automatically translated to Java.

Finally, when writing a program with JSweet, or when reusing an existing Java library, you may want to share it with other JSweet programs, or even with TypeScript and JavaScript programs. The jsweet-candy-quickstart project provides a basic template to get started packaging and publishing such projects. Check also the J4TS organization as a place to package existing Java libraries as JSweet candies.

JSweet Maven repositories

All JSweet candies are available in our Maven Artifactory: http://repository.jsweet.org/artifactory. You can perform advanced search to find candies and other JSweet artifacts through the Artifactory WEB GUI.

Within our Maven Artifactory, you will get the release and the snapshot repositories. You you must include these repositories in your pom.xml before declaring dependencies.

<project>
        ...
	<repositories>
		<repository>
			<id>jsweet-central</id>
			<name>libs-release</name>
			<url>http://repository.jsweet.org/artifactory/libs-release-local</url>
		</repository>
		<repository>
			<snapshots />
			<id>jsweet-snapshots</id>
			<name>libs-snapshot</name>
			<url>http://repository.jsweet.org/artifactory/libs-snapshot-local</url>
		</repository>
	</repositories>
        ...
</project>

Understanding candies versioning

Candies versions are defined as x.y.z-qualifier where x.y.z is the version of the bridged JavaScript library, and qualifier is a unique (and growing) string representing the id of that release. The qualifier may contain the transpiler version, but most often it only contains a date timestamp (yyyymmdd). Of course, for Maven snapshots, the qualifier is worth SNAPSHOT.

Although not encouraged, the bridged JavaScript library version may be left unspecified… in that case the version is 0.0.0-qualifier, which means latest or unknown (sometimes, the version does not matter because the API never changes).