Skip to content

Running the JAVA LS server from the command line

Roland Grunberg edited this page May 14, 2024 · 18 revisions

Running the JAVA LS server

  1. Choose a connection type from "Managing connection types" section below, and then set those environment variables in your terminal prior to continuing

  2. Make sure to build the server using the steps above in the "Building from command line" section

  3. cd into the build directory of the project: /org.eclipse.jdt.ls.product/target/repository

  4. Prior to starting the server, make sure that your socket (TCP or sock file) server is running for both the IN and OUT sockets. You will get an error if the JDT server cannot connect on your ports/files specified in the environment variables

  5. To start the server in the active terminal, run:

java \
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=1044 \
-Declipse.application=org.eclipse.jdt.ls.core.id1 \
-Dosgi.bundles.defaultStartLevel=4 \
-Declipse.product=org.eclipse.jdt.ls.core.product \
-Dlog.protocol=true -Dlog.level=ALL -Xmx1G \
-jar ./plugins/org.eclipse.equinox.launcher_1.4.0.v20161219-1356.jar \
-configuration ./config_linux -data /path/to/data

When running with JDK9, you need to start the server with some extra parameters:

java \
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=1044 \
-Declipse.application=org.eclipse.jdt.ls.core.id1 \
-Dosgi.bundles.defaultStartLevel=4 \
-Declipse.product=org.eclipse.jdt.ls.core.product -Dlog.protocol=true \
-Dlog.level=ALL -Xmx1G \
-jar ./plugins/org.eclipse.equinox.launcher_1.4.0.v20161219-1356.jar \
-configuration ./config_linux -data /path/to/data \
--add-modules=ALL-SYSTEM --add-opens java.base/java.util=ALL-UNNAMED \
--add-opens java.base/java.lang=ALL-UNNAMED
  1. Choosing a value for -configuration: this is the path to your platform's configuration directory. For linux, use ./config_linux. For windows, use ./config_win. For mac/OS X, use ./config_mac.

  2. Choosing a value for -data: the value for your data directory, should be the directory where your active workspace is, and you wish for the java langserver to add in its default files. Should also be the absolute path to this directory, ie., /home/username/workspace

  3. Notes about debugging: the -agentlib: is for connecting a java debugger agent to the process, and if you wish to debug the server from the start of execution, set suspend=y so that the JVM will wait for your debugger prior to starting the server

  4. Notes on jar versions: the full name of the build jar file above, org.eclipse.equinox.launcher_1.4.0.v20161219-1356.jar, may change incrementally as the project version changes. If java complains about jar not found, then look for the latest version of the org.eclipse.equinox.launcher_* jar in the /org.eclipse.jdt.ls.product/target/repository/plugins directory and replace it in the command after the -jar

Managing connection types

The Java Language server supports sockets and standard streams of the server process to communicate with the client. Client can communicate its preferred connection methods by setting up environment variables.

  • To use a plain socket, set the following environment variables before starting the server:

    • CLIENT_PORT: the port of the socket to connect to
    • CLIENT_HOST: the host name to connect to. If not set, defaults to localhost.

    The connection will be used for in and output.

  • To use standard streams(stdin, stdout) of the server process do not set any of the above environment variables and the server will fall back to standard streams.

For socket, the client is expected to create the connections and wait for the server to connect.

Initialize Request

The initialize request recognizes the following options:

(Note that many of these options are parsed in Preferences.java so this would also be a good resource for any further clarification)

interface InitializationOptions {
        /**
         * a list of Java LS extensions
         */
        bundles?: string[];
        /**
         * a list of workspace folders (as URIs)
         */
        workspaceFolders?: string[];
        /**
         * Java LS configuration settings
         */
        settings?: JavaConfigurationSettings[];
}
interface JavaConfigurationSettings {
        /**
         * Java Configuration
         */
        java?: JavaConfiguration;

}
interface JavaConfiguration {
        /**
         * Enable/disable the 'auto build',
         * default is true
         */
        autobuild?: EnabledOption;
        cleanup?: CleanUpOption;
        codeGeneration: CodeGenerationOption
        codeAction: CodeActionOption;
        completion: CompletionOptions;
        configuration?: ConfigurationOptions;
        contentProvider?: ContentProvider;
        eclipse?: EclipseOptions;
        errors?: ErrorsOptions;
        executeCommand?: EnabledOption;
        foldingRange?: EnabledOption;
        /**
         * Enable/disable default Java formatter,
         * default is true
         */
        format?: FormatOption;
        /**
         * Specifies the folder path to the JDK (8 or more recent) used to launch the Java Language Server.
         * On Windows, backslashes must be escaped, i.e."java.home":"C:\\Program Files\\Java\\jdk1.8.0_161"
         */
        home?: string;
        /**
         * Enable/disable the implementations code lens,
         * default is false
         */
        implementationsCodeLens?: EnabledOption;
        import?: ImportOption;
        inlayhints?: InlayHints;
        jdt?: JDTOptions;
        maven?: MavenOptions;
        maxConcurrentBuilds?: number;
        memberSortOrder?: string;
        project?: ProjectOptions;
        quickfix?: QuickFixOption;
        /**
         * Enable/disable the references code lens,
         * default is false
         */
        referenceCodeLens?: EnabledOption;
        references?: ReferencesOption;
        rename?: EnabledOption;
        saveActions?: SaveActions;
        selectionRange?: EnabledOption;
        settings?: SettingsOption;
        /**
         * Enable/disable the signature help,
         * default is false
         */
        signatureHelp?: SignatureHelpOption;
        sources?: SourcesOption;
        symbols?: SymbolsOption;
        templates?: TemplatesOption;
        trace?: TraceOptions;
        edit?: EditOption;
}
enum CleanUpOnSaveActions {
        qualifyMembers = 'qualifyMembers',
        qualifyStaticMembers = 'qualifyStaticMembers',
        addOverride = 'addOverride',
        addDeprecated = 'addDeprecated',
        stringConcatToTextBlock = 'stringConcatToTextBlock',
        invertEquals = 'invertEquals',
        addFinalModifier = 'addFinalModifier',
        instanceofPatternMatch = 'instanceofPatternMatch',
        lambdaExpression = 'lambdaExpression',
        switchExpression = 'switchExpression'
}
interface CleanUpOption {
        actionsOnSave?: CleanUpOnSaveActions[];
}
interface CodeActionOption {
        sortMembers: SortMembersOption;
}
interface CodeGenerationOption {
        generateComments?: boolean;
        hashCodeEquals?: HashCodeOption;
        insertionLocation?: string;
        toString?: ToStringOption;
        useBlocks?: boolean;
}
enum CompletionMatchCaseOption {
        off = 'OFF',
        firstletter = 'FIRSTLETTER'
}
interface CompletionOptions {
        enabled?: boolean;
        /**
         * Defines a list of static members or types with static members.
         * Content assist will propose those static members even if the import is missing
         * default is
         * [
         *   "org.junit.Assert.*",
         *   "org.junit.Assume.*",
         *   "org.junit.jupiter.api.Assertions.*",
         *   "org.junit.jupiter.api.Assumptions.*",
         *   "org.junit.jupiter.api.DynamicContainer.*",
         *   "org.junit.jupiter.api.DynamicTest.*"
         * ]
         */
        favoriteStaticMembers?: string[];
        /** 
         * Defines the sorting order of import statements. 
         * A package or type name prefix (e.g. 'org.eclipse') is a valid entry.
         * An import is always added to the most specific group.
         * default is
         * [
         *   "java",
         *   "javax",
         *   "com",
         *   "org"
         * ]
         */
        filteredTypes?:string[];
        guessMethodArguments?: boolean;
        importOrder?: string[];
        matchCase?: CompletionMatchCaseOption;
        maxResults?: number;
        overwrite?: boolean;
        postfix?: EnabledOption;
}
interface ConfigurationOptions {
        maven?: MavenOption;
        runtimes?: RuntimeOption[];
        /**
         * Specifies how modifications on build files update the Java classpath/configuration
         * default is 'interactive'
         */
        updateBuildConfiguration: UpdateBuildConfigurationKind;
}
interface ContentProvider {
        /**
         * Preferred content provider (a 3rd party decompiler id, usually)
         */
        preferred: string;

}
interface EclipseOptions {
        downloadSources: boolean;
}
enum ExecutionEnvironment {
        J2SE_1_5 = 'J2SE-1.5',
        JavaSE_1_6 = 'JavaSE-1.6',
        JavaSE_1_7 = 'JavaSE-1.7',
        JavaSE_1_8 = 'JavaSE-1.8',
        JavaSE_9 = 'JavaSE-9',
        JavaSE_10 = 'JavaSE-10',
        JavaSE_11 = 'JavaSE-11',
        JavaSE_12 = 'JavaSE-12',
        JavaSE_13 = 'JavaSE-13',
        JavaSE_14 = 'JavaSE-14',
        JavaSE_15 = 'JavaSE-15',
        JavaSE_16 = 'JavaSE-16',
        JavaSE_17 = 'JavaSE-17',
        JavaSE_18 = 'JavaSE-18',
        JAVASE_19 = 'JavaSE-19',
        JAVASE_20 = 'JavaSE-20',
        JAVASE_21 = 'JavaSE-21',
        JAVASE_22 = 'JavaSE-22'
}
interface EnabledOption {
        enabled: boolean;
}
interface ErrorsOptions {
        incompleteClasspath: IncompleteClasspath;
}
interface FormatOption {
        comments?: EnabledOption;
        enabled?: boolean;
        insertSpaces?: boolean;
        onType?: EnabledOption;
        settings?: FormatSettingsOption;
        tabSize?: number;
}
interface FormatSettingsOption {
        profile?: string;
        url?: string;
}
interface GradleOption {
        annotationProcessing?: EnabledOption;
        arguments?: string[];
        enabled?: boolean;
        home?: string;
        java?: HomeOption;
        jvmArguments?: string[];
        offline?: EnabledOption;
        user?: HomeOption;
        version?: string;
        wrapper?: GradleWrapperOption;
}
interface GradleWrapperOption {
        enabled?: boolean;
        checksums?: string[];
}
interface HashCodeOption {
        useInstanceof?: boolean;
        useJava7Objects?: boolean;
}
interface HomeOption {
        home: string;
}
interface ImportOption {
        exclusions: string[];
        /**
         * Enable/disable the Gradle importer,
         * default is true
         */
        gradle?: GradleOption;
        /**
         * Enable/disable the Maven importer,
         * default is true
         */
        maven?: MavenImportOption;
        /**
         * Configure glob patterns for excluding folders,
         * default is 
         * [
         *   "**/node_modules/**",
         *   "**/.metadata/**",
         *   "**/archetype-resources/**",
         *   "**/META-INF/maven/**"
         * ]
         */
}
interface ImportsOption {

}
interface IncompleteClasspath {
        /**
         * Specifies the severity of the message when the classpath is incomplete for a Java file,
         * default is 'warning'
         */
        severity: SeverityKind;
}
interface InlayHints {
        parameterNames: ParameterNamesOption;
}
interface JDTLSOptions {
        androidSupport?: EnabledOption;
        lombokSupport?: EnabledOption;
        protofBufSupport?: EnabledOption;
}
interface JDTOptions {
        ls?: JDTLSOptions;
}       
interface OrganizeImportsOption {
        starThreshold?: number;
        staticStarThreshold?: number;
}
interface QuickFixOption {
        showAt: string;
}
interface MavenOption {
        /**
         * Absolute path to Maven's settings.xml"
         */
        userSettings?: string;
        globalSettings?: string;
        notCoveredPluginExecutionSeverity?: string;
}
interface MavenImportOption {
        enabled?: boolean;
        offline?: EnabledOption;
}
interface MavenOptions {
        downloadSources?: boolean;
        updateSnapshots?: boolean;
}
enum InlayHintsParameterMode {
        none = 'none',
        literals = 'literals',
        all = 'all'
}
interface ParameterNamesOption {
        enabled: InlayHintsParameterMode;
        exclusions?: string[];
}
enum ProjectEncodingOption {
        ignore = 'IGNORE',
        warning = 'WARNING',
        setdefault = 'SETDEFAULT'
}
interface ProjectOptions {
        encoding?: ProjectEncodingOption;
        outputPath?: string;
        referencedLibraries?: string[] | ReferencedLibrariesOption; 
        resourceFilters?: string [];
        sourcePaths?: string [];
}
interface ReferencedLibrariesOption {
        exclude?: string[];
        include: string[];
        sources?: SourceOption[];
}
interface ReferencesOption {
        includeAccessors?: boolean;
        includeDecompiledSources?: boolean;
}
interface RuntimeOption {
        name: ExecutionEnvironment;
        path: string;
        javadoc?: string;
        sources?: string;
        default?: boolean;
}
interface SaveActions {
        /**
         * Enable/disable auto organize imports on save action,
         * default is false
         */
        organizeImports: boolean;

}
interface SettingsOption {
        url?: string;
}
enum SeverityKind {
        ignore = 'ignore',
        info = 'info',
        warning = 'warning',
        error = 'error'
}
interface SignatureHelpOption {
        enabled: boolean;
        description?: EnabledOption;
}
interface SortMembersOption {
        avoidVolatileChanges?: boolean;
}
interface SourceOption {
        library: string;
        source: string;
}
interface SourcesOption {
        organizeImports: OrganizeImportsOption;
}
interface SymbolsOption {
        includeSourceMethodDeclarations?: boolean;
}
interface TemplatesOption {
        fileHeader?: string[];
        typeComment?: string[];
}
interface ToStringOption {
        codeStyle?: string;
        limitElements?: number;
        listArrayContents?: boolean;
        skipNullValues?: boolean;
        template?: string;
}
interface TraceOptions {
        /**
         * Traces the communication between VS Code and the Java language server,
         * default is 'of'
         */
        server: TraceKind;
}
enum TraceKind {
        off = 'off',
        messages = 'messages',
        verbose = 'verbose'
}
enum UpdateBuildConfigurationKind {
        disabled = 'disabled',
        interactive = 'interactive',
        automatic = 'automatic'
}
interface EditOption {
        /**
         * Select the diagnostics strategy for unsaved changes when editing a Java file.
         * For more information on how clients can use this setting, see https://github.com/eclipse/eclipse.jdt.ls/pull/2587#issue-1660481868
         */
        validateAllOpenBuffersOnChanges?: boolean;
}

Example:

InitializeParams: {
    ...
    "initializationOptions": {
        "bundles": [
        ],
        "workspaceFolders": [
            "file:///home/snjeza/Project"
        ],
        "settings": {
            "java": {
                "home": "/usr/local/jdk-9.0.1",
                "errors": {
                    "incompleteClasspath": {
                        "severity": "warning"
                    }
                },
                "configuration": {
                    "updateBuildConfiguration": "interactive",
                    "maven": {
                        "userSettings": null
                    }
                },
                "trace": {
                    "server": "verbose"
                },
                "import": {
                    "gradle": {
                        "enabled": true
                    },
                    "maven": {
                        "enabled": true
                    },
                    "exclusions": [
                        "**/node_modules/**",
                        "**/.metadata/**",
                        "**/archetype-resources/**",
                        "**/META-INF/maven/**",
                        "/**/test/**"
                    ]
                },
                "referencesCodeLens": {
                    "enabled": false
                },
                "signatureHelp": {
                    "enabled": false
                },
                "implementationsCodeLens": {
                    "enabled": false
                },
                "format": {
                    "enabled": true
                },
                "saveActions": {
                    "organizeImports": false
                },
                "contentProvider": {
                    "preferred": null
                },
                "autobuild": {
                    "enabled": false
                },
                "completion": {
                    "favoriteStaticMembers": [
                        "org.junit.Assert.*",
                        "org.junit.Assume.*",
                        "org.junit.jupiter.api.Assertions.*",
                        "org.junit.jupiter.api.Assumptions.*",
                        "org.junit.jupiter.api.DynamicContainer.*",
                        "org.junit.jupiter.api.DynamicTest.*"
                    ],
                    "importOrder": [
                        "java",
                        "javax",
                        "com",
                        "org"
                    ]
                }
            }
        }
    },
    ...
}