Break down io.typefox.lsapi.services module

[akosyakov]

I would like to break down io.typefox.lsapi.services on the following modules:

module	responsibility	languages	depends on
io.typefox.lsapi.services	java interfaces for services defined by the language server protocol	java	io.typefox.lsapi
io.typefox.lsapi.transport	base interfaces to organize communication between the client (tool) and server sides like LanguageEndpoint, MessageReader, MessageWriter, MessageTracer and base or typical implementations of them, like AbstractLanguageEndpoint, ConcurrentMessageReader and PrintMessageTracer	java, xtend	io.typefox.lsapi
io.typefox.lsapi.json	JSON based implementation of MessageReader and MessageWriter	java, xtend	io.typefox.lsapi.transport
io.typefox.lsapi.client	the client (tool) side implementation of LanguageEndpoint for communication with the server side	java, xtend	io.typefox.lsapi.transport
io.typefox.lsapi.server	the server side implementation of LanguageEndpoint for communication with the client (tool) side	java, xtend	io.typefox.lsapi.transport

Such structure let users only consume what they need, for example:

• for communication with a json based language server io.typefox.lsapi.client and io.typefox.lsapi.json are required;
• for communication with a non-json based language server io.typefox.lsapi.client is required and custom implementation of MessageReader and MessageWriter should be provided;
• for communication with a json based client of the language server io.typefox.lsapi.server and io.typefox.lsapi.json are required;
• for communication with a non-json based client of the language server io.typefox.lsapi.server is required and custom implementation of MessageReader and MessageWriter should be provided.

[akosyakov]

For comparison a decomposition of typescript SDK: https://github.com/Microsoft/vscode-languageserver-node#vscode-language-server---node. It consist of a base package hiding implementation details of the base jsonrpc protocol, and client and server wrappers packaged correspondingly.

Notice how all connection interfaces expose generic method for registering handlers and sending requests and notification, so one can easily extend the protocol.

[spoenemann]

What do you mean by modules? Packages or Jars?

[akosyakov]

@spoenemann jars

[spoenemann]

I don't see the benefit in such a fine-grained splitting into multiple jars. I would understand separating the JSON dependent part in order to get rid of the Gson dependency in cases where you want to implement you own message passing, but otherwise it shouldn't matter to have a few kilobytes more code than you actually need?

[akosyakov]

@spoenemann I don't care about a size either, but rather about clear structure and API. if one implement a server he should not bother with client side interfaces and classes, the same for the client side.

[spoenemann]

Ok, we should discuss this when we review the API after the code transfer to Eclipse.

[akosyakov]

microsoft/language-server-protocol#86 (comment) - arguments to decouple the LS protocol from the transport level and the transport from json based implementation

[akosyakov]

Also think we should have io.typefox.lsapi.shared that have common useful service on the LS protocol level, e.g. FileWatchingLanguageServer can watch file changes and be applied on the client and server sides.

[svenefftinge]

For lsp4j I splitted it up in two separate modules

• org.eclipse.lsp4j.jsonrpc (just the jsonrpc implementation, without any knowledge of LSP)
• org.eclipse.lsp4j (the LSP definitions using jsonrpc)

I think this is a reasonable splitting, I don't see how anyone would want to use jsonrpc without json, but even that would be possible now. It is just that the json specific stuff is not in its own module (but package).

For the client / server separation, on jsonrpc level there is no distinction as both are just endpoints. On LSP level it makes sense to have the interfaces in one module, as a language server usually gets parameterized with a language client to communicate back (and vice versa).