DEVELOPING.md

Developing Eclipse LSP4Jakarta

• Projects
• Prerequisites
• Project setup in the Eclipse IDE
• Common errors
• Run and Debug
• Snippets

Projects

This repository contains a few projects that provide language support for Jakarta EE APIs.

• jakarta.ls- Language Server for Jakarta EE
• jakarta.jdt - Eclipse JDT LS extension for Eclipse LSP4Jakarta
• jakarta.eclipse - Eclipse IDE client (for local testing) that consumes Eclipse LSP4Jakarta

To test the changes interactively, you must use a language client.

In the following sections, we document how to build and test using the Eclipse IDE client in this repository (./jakarta.eclipse).

Prerequisites

Java SE 17, Maven, and Eclipse (Eclipse IDE for Enterprise Java and Web Developers is recommended) are required to build the Eclipse LSP4Jakarta project.

Ensure the Eclipse Plug-in Development Environment (PDE) is installed in your Eclipse workspace.

Project setup in the Eclipse IDE

The following instructions explain how to set up your Eclipse IDE workspace.

1. Clone this repository onto your local machine

   git clone https://github.com/eclipse/lsp4jakarta.git

2. Build the project with Maven by running the ./buildAll.sh script from the lsp4jakarta directory with Maven and Tycho. This script runs mvn clean install on the components in the following order:

   1. Builds Eclipse JDT LS extension for Eclipse LSP4Jakarta (./jakarta.jdt) and runs automated tests

   2. Builds Language Server for Jakarta EE (./jakarta.ls), creating the org.eclipse.lsp4jakarta.ls-x.x.x-SNAPSHOT-jar-with-dependencies.jar

   3. Builds Eclipse IDE client plug-in that consumes Eclipse LSP4Jakarta (./jakarta.eclipse) and runs automated tests, copies the org.eclipse.lsp4jakarta.ls-x.x.x-SNAPSHOT-jar-with-dependencies.jar to the ./jakarta.eclipse/org.eclipse.lsp4jakarta.lsp4jakarta.lsp4e.core/server/ directory

3. Import jakarta.ls, org.eclipse.lsp4jakarta.core, org.eclipse.lsp4jakarta.tests and lsp4jakarta projects in Eclipse (File --> Open projects from file system --> Select your LSP4Jakarta clone)

   

   You may also need to install Tycho Project Configurations to resolve Maven plug-in execution errors.

   

   

4. Ensure that the Java projects are being built with JavaSE-17 (Right-click project --> "Properties" --> "Java Build Path" --> "Libraries")

5. Configure the Java build path for the org.eclipse.lsp4jakarta.lsp4e.core project:

   1. Right-click "org.eclipse.lsp4jakarta.lsp4e.core project" --> "Properties" --> "Java Build Path" --> "Libraries"

      

   2. Select "Add External JARs..." and point to the jar located at ./jakarta.eclipse/org.eclipse.lsp4jakarta.lsp4jakarta.lsp4e.core/server/org.eclipse.lsp4jakarta.ls-x.x.x-SNAPSHOT-jar-with-dependencies.jar

      

Common Errors

1. When setting up the Eclipse workspace:
    - Bundle 'org.apache.commons.lang3' cannot be resolved in Eclipse workspace
    Solution: #46

2. If during initial setup mvn verify returns errors or compilation failures, verify that you are using JavaSE-17. You may have to configure $JAVA_HOME variable and make sure it is pointing to the correct location.

Run and Debug

Run org.eclipse.lsp4jakarta.lsp4e.core as an Eclipse Application to launch a new instance of the Eclipse IDE with Eclipse LSP4Jakarta (Right-click on the org.eclipse.lsp4jakarta.lsp4e.core project, "Run As" --> "Eclipse Application"). A new Eclipse application will launch with the Eclipse LSP4Jakarta Eclipse IDE client plug-in installed.

To Debug:

Debug org.eclipse.lsp4jakarta.lsp4e.core as an Eclipse Application to launch a new instance of the Eclipse IDE with Eclipse LSP4Jakarta (Right-click on the org.eclipse.lsp4jakarta.lsp4e.core project, "Debug As" --> "Eclipse Application"). A new Eclipse application will launch with the Eclipse LSP4Jakarta Eclipse IDE client plug-in installed.

Snippets

Code snippets are completion items that quickly generate common blocks of code. Snippets in Eclipse LSP4Jakarta are contributed through JSON files. If you add new snippets, update the features documentation.

Snippets use the following format:

"<Jakarta EE API Name> - <brief description>": {
      "prefix": "<Jakarta EE API shortened name>_<noun describing the snippet>",
      "body": [
        "<body of snippet, this is the code that will be injected on selection>"
      ],
      "description": "<brief description of snippet, should not be longer than 1 sentence>",
      "context": {
        // snippets will only appear for users if the package specified here is found on the
        // project's class path and the content type is valid in the cursor's context.
        "type": "<package required for snippet (e.g. jakarta.servlet.http.HttpServlet)>"
        "contentType": "<descriptor from enum SnippetContentType (e.g. field)>"
      }
    }