Skip to content

Latest commit

 

History

History
148 lines (85 loc) · 7.54 KB

README.md

File metadata and controls

148 lines (85 loc) · 7.54 KB
Raw

PlantUML going serverless

Up to now, you need either a local installation of PlantUML or a server (remote or local) to be able to generate diagrams.

Thanks for CheerpJ, we have published a pure Javascript implementation of PlantUML.

This implementation runs within a simple browser.

The goal of this core project is to provide a very basic library, so that other libraries could be built from it:

What is CheerpJ?

CheerpJ is a Java bytecode to WebAssembly and JavaScript compiler, compatible with 100% of Java, which allows to compile any Java SE application, library or Java applet into a WebAssembly/JavaScript application.

We are going to use the two following components from CheerpJ:

  • The CheerpJ AOT compiler, an LLVM-based Java-bytecode to JavaScript compiler. This can be used to convert Java archives (e.g. plantuml-core.jar) files to JavaScript.
  • The CheerpJ runtime library, a full Java SE runtime in WebAssembly and JavaScript, that can be distributed in part or in full with applications converted with CheerpJ.

Note that it does not work with a local file (with double-clicking on the file). Files must be served by some webserver (even if it is a local one).

How it works?

The plantuml-core project provides a dedicated version of PlantUML that can be compiled to Javascript with CheerpJ. The jar file plantuml-core.jar can be compiled to javascript with the simple command:

cheerpj_2.3/cheerpjfy.py --deps cheerpj_2.3/cheerpj-dom.jar plantuml-core.jar

You can get both files plantuml-core.jar and plantuml-core.jar.js from Github.

Online demo for the impatient

All those pages are intentionally as simple as possible, so that people could quickly understand how they work and develop their own libraries:

Javascript API

SVG generation

First, you have to load the runtime provided by Leaning Technology:

<script src="https://cjrtnc.leaningtech.com/2.3/loader.js"></script>

Then, you have to init PlantUML itself:

cheerpjRunMain("com.plantuml.api.cheerpj.v1.RunInit", "/app/plantuml-core.jar")

The /app/ is a virtual file-system that is the root of your webserver. In the previous example, it means that both files plantuml-core.jar and plantuml-core.jar.js must be stored at the root of your server (so something like http://127.0.0.1:8080/plantuml-core.jar.js).

Finally, you can get the SVG version of any diagram:

cjCall("com.plantuml.api.cheerpj.v1.Svg", "convert", "light", text);

where:

  • "light": could be either dark or light depending of the theme you want to use.
  • text: String that contains the diagram source text.

Working demo

PNG generation

Note that PNG generation is slower, because PNG compression takes time.

Once again, you have to load the runtime provided by Leaning Technology:

<script src="https://cjrtnc.leaningtech.com/2.3/loader.js"></script>

Then, you have to init PlantUML itself:

cheerpjRunMain("com.plantuml.api.cheerpj.v1.RunInit", "/app/plantuml-core.jar")

Finally, you can get the PNG version of any diagram:

cjCall("com.plantuml.api.cheerpj.v1.Png", "convertToBlob", "light", text, "/files/result.png");

where:

  • "light": could be either dark or light depending of the theme you want to use.
  • text: String that contains the diagram source text.

Working demo

Complete list of available functions

Class Method Description Arguments Return
Svg convert Generate an diagram using SVG format
  1. mode: either "dark" or "light"
  2. text: the text source of the diagram
 Either:
  • The SVG source code generated if everything is ok
  • Or a JSON description of what was wrong
Png convertToBase64 Generate an diagram using PNG format encoded in Base64
  1. mode: either "dark" or "light"
  2. text: the text source of the diagram
 Either:
  • A Base64 String of a PNG imag
  • Or a JSON description of what was wrong
Png convertToBlob Generate an diagram in PNG to a Blob
  1. mode: either "dark" or "light"
  2. text: the text source of the diagram
  3. pathOut: path of the Blob
 A JSON description of the conversion.

The image itself is in the Blob.
Raw convertToBlob Generate an diagram in raw (uncompressed) graphics to a Blob
  1. mode: either "dark" or "light"
  2. text: the text source of the diagram
  3. pathOut: path of the Blob
 A JSON description of the conversion.

The image itself is in the Blob in raw format (RGBA).
Info decode Decode a PlantUML Text Encoding encoded String.
  1. text: some encoded string
 The decoded text of the diagram.
Info encode Encode some diagram text to a PlantUML Text Encoding encoded String.
  1. text: The text of the diagram
 The encoded string.
Info syntaxCheck Check if a text diagram is syntaxically correct.
  1. text: The text source of the diagram
 A JSON description of the syntax.

Limitations

Need for a web server

Even if this is a 100% Javascript application, it does NOT run by simple opening the HTML page directly from disk.

The URL in the browser should always start with http:// or https://, if it starts with file:// CheerpJ will not work. You need to use a local web server during testing.

If you have python installed, you can for example use in the current directory python3 -m http.server 8080 or python -m http.server 8080

Smetana limitation

This version of PlantUML depends on Smetana, a port from C to Java of GraphViz/DOT source code.

Simple diagrams are working fine, however, this port is not 100% finished, so there might be some issue on complex diagrams.

CheerpJ Licence

CheerpJ Licence is provided for non commercial use. See licence details here.

Startup time

The startup time may be improved.

To take advantage of parallel downloads, and reduce download and startup time, CheerpJ allows to pre-specify a list of resources (CheerpJ runtime modules) to be loaded at startup.

This feature is not used with PlantUML up to now.