Skip to content

Latest commit

 

History

History
69 lines (49 loc) · 3.45 KB

README.adoc

File metadata and controls

69 lines (49 loc) · 3.45 KB
Raw

ASP - Asciidoctor Server Protocol

Java CI with Gradle
asp

About

ASP stands for AsciiDoctor Server Protocol - a simple communication protocol between a client and a asciidoctor server instance which will do all Asciidoctor operations. So its a little bit similar to LSP where the language parts are central provided by a server instance.

Why a server?

With AsciiDoctor Editor for eclipse it was extreme hard to handle the OSGI depencencies in conjunction with asciidoctor/asciidoctorj and JRuby (see de-jcup/eclipse-asciidoctor-editor#213)

So instead of handling this always again with new dependencies etc. working with OSGI this project was initiated, to become a standalone solution, which can be used by different editors without spawning always new processes but instead reuse an already started server instance which shall be very much faster than doing a new process communciation to an installed variant.

The editors shall only delegate their conversion tasks to server side and have a communication layer to the server which will produce information about converted output locations (or errors).

Benefits

  • Independent from real installation, can be used ony systems were developers have not possiblity to install asciidoctor

  • Comes up with standard tool setup (will have HTML, docbook and PDF support)

  • Can be used from multiple IDE integrations (eclipse-asciidoctor, …​ more …​)

  • Provides a client library to use the server, so convenient

Why such an "old school" tcp client/server approach and no standard REST server ?

It started with a spring boot application, with rest controller etc., very nice and convenient, but…​ spring bootJar did not correctly work with asciidoctorj + jruby.

Providing an own fat jar solution in combination with spring boot did work after time, but I got at least 59 MB at the very first beginning - this was too much.

Also spring boot comes with many dependencies - and asciidoctorJ has got itself many. To prevent cross site effects the client server protocol should be as simple as possible and has nearly no more dependencies.

How should editors/tools use this server?

Overview

overview

Details

ASP-server-asciidoctorj

You can use ASP server either as an external process or as an embedded server.

As an external process

For this case a specialized launcher was created. Just use ExternalProcessAsciidoctorJServerLauncher as done in ExternalProcessExample.java and ExternalProcessWithDebugOutputExample.java

As embedded server

Same as external variant, but use EmbeddedAsciidoctorJServerLauncher as launcher. For examples look into integration tests.