[ANN] Akasha: Typed Browser API

118 views
Skip to first unread message

Peter Donald

unread,
May 26, 2021, 7:11:21 PMMay 26
to GWT Mailing List

What is Akasha?

Akasha is a typed browser API layer that is always up to date with the latest web specifications. These API layers are intended to simplify writing web applications in languages other than pure-Javascript. Akasha currently provides:

  • Closure-compiler externs so that the closure-compiler can perform type checking and advanced type-based optimizations.
  • Jsinterop annotated java classes that can be used in GWT projects.
  • Jsinterop annotated java classes that can be used in J2CL projects.

In the near future, it is expected that bindings for other languages and frameworks will be produced (particularly to support WASM based toolkits). Support will also be re-enabled to generate React4j element factories.

Getting Started

Getting started using the JsInterop annotated classes is relatively easy. The following sections give a basic overview of how to get started in a GWT or J2CL project.

GWT

First you add a dependency on the gwt library to your project. In a Maven-based project is as simple as adding the following dependency:

<dependency>
  <groupId>org.realityforge.akasha</groupId>
  <artifactId>akasha-gwt</artifactId>
  <version>0.11</version>
</dependency>

In a GWT project it is necessary to add a reference to the Akasha library the GWT module in your .gwt.xml file. This is just a single inherit:

<module>
  ...
  <inherits name='akasha.Akasha'/>
  ...
</module>

J2CL/Closure Compiler

First you add a dependency on the j2cl library to your project. In a Maven-based project is as simple as adding the following dependency:

<dependency>
  <groupId>org.realityforge.akasha</groupId>
  <artifactId>akasha-j2cl</artifactId>
  <version>0.11</version>
</dependency>

The closure compiler is shipped with a set of externs that do not align 100% with the externs produced by the Akasha project. Thus it is necessary to pass the arguments -env CUSTOM when running the closure compiler. It is also necessary to add the closure externs shipped as part of the akasha-java artifact. These are included in the artifact under the names; akasha/Akasha.externs.js and akasha/akasha_patches.extern.js. The exact way that these build steps are specified will depend upon the underlying tool but a simple example using Bazel is available at https://github.com/react4j/react4j-todomvc/tree/raw_bazel_j2cl

Java Integration

The easiest way to access browser APIs is to access the static fields or call static methods on the classes that represent the globalThis object within the javascript environment. The "namespaces" within the browser are also exposed as java classes containing static methods and static fields.

For example the javascript:

window.addEventListener( "online", e => console.log( "The network is connected" ) )

Would be translated into Akasha java as:

WindowGlobal.addOnlineListener( e -> Console.log( "The network is connected" ) );

In this scenario, the WindowGlobal java class represents globalThis value in a browser window context and the Console class represents the console namespace. Some browser types can also be created using the new keyword and where this is possible in javascript it is possible in Akasha java. i.e. new WebSocket("wss://..." ) is valid in both javascript and Akasha java.

How does it work?

Akasha is kept with evolving browser standards by fetching WebIDL and processing the WebIDL to generate source code and other artifacts.

WebIDL is used by various specifications to communicate the interfaces that are expected to be implemented in web browsers. Many web browsers also use a WebIDL variant to generate code to implement the specification.

WebIDL published as part of the official specifications are not always perfect representations of the interfaces as implemented by the web browsers. Nor is there a central place that contains the complete WebIDL that a browser is expected to implement. The Akasha suite defines a pipeline for processing WebIDL schemas. The pipeline defines a series of stages. Each stage will either transform a schema, combine multiple schemas or perform an action for the schema. This capability allows the tool to process the WebIDL schemas fetched from the specifications and combine them into a consistent document.

The Akasha suite also includes tools to fetch data from other locations and combine the data with the WebIDL in processing stages. The most significant other data source is the documentation that is scraped from the MDN website and used to add basic documentation to the WebIDL elements. In the near future it is expected that the browser compatibility data will also be scraped so that browser compatibility data for WebIDL elements can be used in the processing pipeline to influence how artifacts are built. Other data from the web specifications could be combined to improve the outputs generated from the suite.

Akasha extends the WebIDL syntax to support additional data being added to the WebIDL. This includes syntax to explicitly declare events emitted by interfaces (i.e. there is a new member element that looks like event ProgressEvent load;). It also supports a Javadoc-like syntax for documenting the WebIDL elements.

The Akasha jsinterop action generates source code with a more java-esque feel than is present in elemental2. It also aims to offer affordances that make working with the browser API easier for java developers. A few differences from Elemental2 include:

  • Javadocs are added for most fields, methods and types if the element is documented on MDN. This often includes references to the specification in which the element is defined.
  • Constants in WebIDL are represented as constants in java. This typically results in smaller code size and may open up additional optimization opportunities.
  • Fields, methods and parameters are annotated with @Nonnull or @Nullable if the type is a non-primitive, non-void type.
  • Read-only attributes in WebIDL are implemented as methods rather than mutable fields or properties with setters.
  • Dictionaries in WebIDL use a "builder" pattern to make construction of these types much easier.
  • No parameterized types exist in the Akasha generated artifacts as WebIDL does not define such constructs. However there are a handful of hand-written jsinterop annotated java classes such as JsArrayJsMapJsSetJsWeakMap and JsWeakSet that make use of parameterized types to support normal java development practices.
  • Event handlers and event listeners are typed according to the type of event expected to be delivered and have a void return type. This simplifies the use of lambdas and method references in java code.
  • @JsOverlay methods are added for known events emitted by an interface. For example, it is possible to use code such as e.addBlurListener(this::processBlurEvent) rather than the more verbose e.addEventListener("blur", e -> processBlurEvent((FocusEvent) e)
  • WebIDL enumerations are annotated with the @MagicConstant annotation when translated to java code. The Jetbrains/IntelliJ IDE suite will detect this annotation and allow auto-completion of enumeration values or report errors when incorrect values are supplied.
  • Several other minor usability improvements, particularly with respect to union types.

One of the greatest advantages of Akasha is the ability to quickly generate API for new specifications. First you run a single command to register the spec url, extracting the WebIDL from the specification and extract the documentation from MDN. Then you run a second command to regenerate the java and library and closure externs.

How does this relate to WebTack?

WebTack was the former name of this project when the scope encompassed building a tool to fetch and process WebIDL files. That name still lives on with that part of the suite but the name is no longer used outside this project.

The project evolution

Akasha grew out of several experiments that helped shape the way the code was generated. Several web apps have been created to explore the feel of using the generated code and these may be interesting to investigate to get a feel of how the project evolved. This has included experiments with the Web Bluetooth API by creating a browser based Heart Rate Monitor, experiments with speech synthesis using the Web Speech API, experiments with WebRTC by creating a video chat application and several other experiments that are not open source.

The next major milestone was for integration of Akasha into a medium sized application with ~600K lines of GWT code that has been in development since 2011. This integration has successfully replaced our previous browser API layers and we are now focusing on fine tuning and optimizing the output.

Adopting Akasha has made it trivial to integrate with new Web APIs as they come out with minimal fuss compared to past approaches such as the handwritten DOM adapters, elemental or elemental2 libraries and we think Akasha is nearing a time where it is suitable for adoption in a broader context.

--
Cheers,

Peter Donald

Juan Pablo Gardella

unread,
May 26, 2021, 7:44:49 PMMay 26
to GWT Users
That's awesome!! Thanks a lot Peter!

--
You received this message because you are subscribed to the Google Groups "GWT Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to google-web-tool...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/google-web-toolkit/CACiKNc4sfFH-JWYnU2OLpEYtC%3Djp4z2k3w80rLDjJRUBhNScBQ%40mail.gmail.com.

Vassilis Virvilis

unread,
May 27, 2021, 3:52:54 AMMay 27
to google-we...@googlegroups.com
Very interesting.

That supersedes elemental2. And the API is not the same (AFAICT) so we are going to have some inevitable churn in our code base.

Will this be endorsed by GWT as elemental2 replacement?

I tried to find the gitnub page for the project (found it: https://github.com/akasha/akasha) but https://github.com/AKASHAorg pops up.

   Vassilis



--
Vassilis Virvilis

Peter Donald

unread,
May 27, 2021, 8:47:02 AMMay 27
to GWT Mailing List
On Thu, May 27, 2021 at 5:52 PM Vassilis Virvilis <vas...@gmail.com> wrote:
That supersedes elemental2. And the API is not the same (AFAICT) so we are going to have some inevitable churn in our code base.

The APIs are different but not substantially so - it took us a couple of hours to convert our code bases which are mid-sized.
 
Will this be endorsed by GWT as elemental2 replacement?

No idea - I also dont know who GWT is ;) Google has a large internal closure code base so it is unlikely that they will adopt as the externs differ. The akasha externs are more strongly typed to try and get slightly better optimizability by CC and if you don't have an existing closure codebase this is an easy win but not so if you have a large existing js codebase.
 
I tried to find the gitnub page for the project (found it: https://github.com/akasha/akasha) but https://github.com/AKASHAorg pops up.

I should have popped that in the email ;)
 
--
Cheers,

Peter Donald

lofid...@gmail.com

unread,
May 27, 2021, 9:09:48 AMMay 27
to GWT Users
Great work Peter!

I like the APIs from Akasha (former WebTack).

If someone wants to compare the APIs from Elemental2 and Akasha checkout this example:
Thanks a lot!
Lofi

Peter Donald

unread,
May 27, 2021, 7:16:45 PMMay 27
to GWT Mailing List
On Thu, May 27, 2021 at 11:10 PM lofid...@gmail.com <lofid...@gmail.com> wrote:
Great work Peter!

I like the APIs from Akasha (former WebTack).

If someone wants to compare the APIs from Elemental2 and Akasha checkout this example:
Oops - that was an super alpha version of the library and one of the APIs has changed since then. I will send a PR to fix that up ;) 

--
Cheers,

Peter Donald

lofid...@gmail.com

unread,
Jun 6, 2021, 3:43:50 PMJun 6
to GWT Users
Hi Peter,

thanks a lot for your PR, I accepted it and I add GitHub Actions for building the projects:

https://github.com/lofidewanto/jsinterop-simple-jsframework-example

Cheers,
Lofi

lofid...@gmail.com

unread,
Jun 6, 2021, 4:00:51 PMJun 6
to GWT Users
Hi Peter, 


Cool work!
Lofi

foal

unread,
Jun 14, 2021, 4:59:31 PMJun 14
to GWT Users
Hi, do you have support for Intl API? 
S.

Peter Donald

unread,
Jun 14, 2021, 6:54:56 PMJun 14
to GWT Mailing List
On Tue, Jun 15, 2021 at 6:59 AM foal <sspir...@gmail.com> wrote:
Hi, do you have support for Intl API? 

Not as yet. It is a javascript specification rather than a browser interface specification which means there is no WebIDL to use to generate the API. This would mean I would need to write the WebIDL or manually construct the jsinterop types ... which looks easy enough ... but I have yet to get to it ;)

--
Cheers,

Peter Donald

Andrea Stocchero

unread,
Jun 15, 2021, 11:02:41 AMJun 15
to GWT Users
For INTL Number and Date format, there is an implementation here: https://github.com/pepstock-org/Charba/tree/master/src/org/pepstock/charba/client/intl
If you are not using that chart lib, it could be a starting point.
Reply all
Reply to author
Forward
0 new messages