Eclipse LSP4J

Java binding for the Language Server Protocol and the Debug Adapter Protocol.

How To Use

A brief overview of how to use LSP4J to implement a server or a client can be found here:

• Getting Started
• Core Concepts

Maven Repositories

• Maven Central: https://repo.maven.apache.org/maven2/

p2 Update Sites

• Releases: https://download.eclipse.org/lsp4j/updates/releases/
• Milestones: https://download.eclipse.org/lsp4j/updates/milestones/
• Nightly: https://download.eclipse.org/lsp4j/builds/main/

japicmp reports

• The p2 Update sites listed above (since 0.13.0) contain a japicmp report against the last released version to make it easier to identify API changes.

Snapshots

The snapshots are deployed during the build to:

• https://oss.sonatype.org/content/repositories/snapshots/org/eclipse/lsp4j/

Signed JARs

The Maven Repositories, p2 Update Sites, and the Snapshots contain signed jars. If you plan to simply add them to your own jar, you'll need to remove/exclude or update/override these signatures.

Supported LSP Versions

• LSP4J (Next release) → LSP 3.18.0 plus SymbolTag proposal
• LSP4J 1.0.* → LSP 3.18.0 (specification is not finalized yet) plus SymbolTag proposal
• LSP4J 0.24.* → LSP 3.17.0
• LSP4J 0.23.* → LSP 3.17.0
• LSP4J 0.22.* → LSP 3.17.0
• LSP4J 0.21.* → LSP 3.17.0
• LSP4J 0.20.* → LSP 3.17.0
• LSP4J 0.19.* → LSP 3.17.0
• LSP4J 0.18.* → LSP 3.17.0
• LSP4J 0.17.* → LSP 3.17.0
• LSP4J 0.16.* → LSP 3.17.0
• LSP4J 0.15.* → LSP 3.17.0
• LSP4J 0.14.* → LSP 3.17.0 (except Notebook support and WorkspaceSymbol.data)
• LSP4J 0.13.* → LSP 3.17.0 (except Notebook support and some changes to the LSP 3.17 specification that were added after specification was published as done)
• LSP4J 0.12.* → LSP 3.16.0
• LSP4J 0.11.* → LSP 3.16.0
• LSP4J 0.10.* → LSP 3.16.0 (specification is not finalized yet)
• LSP4J 0.9.* → LSP 3.15.0 (except Progress)
• LSP4J 0.7.*, 0.8.* → LSP 3.14.0
• LSP4J 0.6.* → LSP 3.13.0
• LSP4J 0.5.* → LSP 3.10.0
• LSP4J 0.4.* → LSP 3.7.0
• LSP4J 0.2.*, 0.3.* → LSP 3.0
• LSP4J 0.1.* → LSP 2.1

Supported DAP Versions

• LSP4J (Next release) → DAP 1.70.0
• LSP4J 1.0.* → DAP 1.70.0
• LSP4J 0.24.* → DAP 1.69.0
• LSP4J 0.23.* → DAP 1.65.0
• LSP4J 0.22.* → DAP 1.60.0
• LSP4J 0.21.* → DAP 1.60.0
• LSP4J 0.20.* → DAP 1.58.0
• LSP4J 0.19.* → DAP 1.58.0
• LSP4J 0.18.* → DAP 1.58.0
• LSP4J 0.17.* → DAP 1.58.0
• LSP4J 0.16.* → DAP 1.58.0
• LSP4J 0.15.* → DAP 1.56.0
• LSP4J 0.14.* → DAP 1.55.0
• LSP4J 0.13.* → DAP 1.55.0
• LSP4J 0.12.* → DAP 1.44.0
• LSP4J 0.11.* → DAP 1.44.0
• LSP4J 0.10.* → DAP 1.42.0
• LSP4J 0.9.* → DAP 1.37.0 (except CancelRequest)
• LSP4J 0.8.* → DAP 1.35.0
• LSP4J 0.5.* – 0.7.* → DAP 1.31.0
• LSP4J 0.4.* → DAP 1.25.0
• LSP4J before 0.4.0 did not support DAP

Building and Contributing

To build and contribute to LSP4J please consult the Contribution Guide.

Licenses

LSP4J is published under two licenses:

• Eclipse Public License v. 2.0
• Eclipse Distribution License v. 1.0, a BSD-3-clause license

SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause

API Policy

The Eclipse LSP4J project uses Semantic Versioning to determine the version number increment the project should use, as determined by japicmp. All bundles within LSP4J share a version number to simplify version management, both for LSP4J project as well as API consumers of LSP4J. Therefore the version increment for any LSP4J bundle will be the largest increment required by semantic versioning of any of the bundles.

New versions of LSP and DAP specifications

New versions of LSP and DAP specifications may lead to breaking API changes due to mapping of TypeScript types to Java types.

It is particularly difficult to maintain binary compatibility when adapting to some protocol changes that allow return values or fields to have new/additional types. In JSON-RPC + TypeScript, an additional type is not a breaking change, but in Java with LSP4J this is often a breaking change. For example, in LSP 3.18, Diagnostic.message has changed from string to string | MarkupContent, in Java LSP4J this is represented as a change from String to Either<String, MarkupContent>, which is an API breaking change, and would necessitate a major version bump for semantic versioning.

API Policy for versions before 1.0

Prior to 1.0 version of LSP4J Semantic Versioning was not used.

Published API changes

Breaking API changes are published in the CHANGELOG. In addition, each release and continuous build of LSP4J runs the japicmp tool, wrapped with runjapicmp.sh. The generated japicmp reports for releases and current development branch are linked in the CHANGELOG. The GitHub actions builds save as an artifact the same report for each pull request and commit.

Compare API of two arbitrary versions

Using japicmp online you can compare API between any two versions easily, here is an example of comparing 0.21.0 to 0.24.0 for each of the LSP4J bundles:

• org.eclipse.lsp4j
• org.eclipse.lsp4j.debug
• org.eclipse.lsp4j.generator
• org.eclipse.lsp4j.jsonrpc
• org.eclipse.lsp4j.websocket
• org.eclipse.lsp4j.websocket.jakarta