spacemacs/layers/+lang/java/README.org

Java layer

• Description
  • Features:
• Layer Installation
  • Layer
  • Choosing a backend
• Backends
  • Meghanada
    • Installation
    • About Maven
  • Eclim
    • Installation
      • Eclipse
      • Eclim
    • Configuration
    • Usage
  • ENSIME
    • Installation when using SBT
    • Installation when using Gradle
    • Configuration
    • Usage
    • Issues
  • LSP Java
    • Usage
• Key bindings
  • Meghanada
    • Server
    • Navigation
    • Compilation
    • Tests (junit)
    • Refactoring
    • Tasks
  • Eclim
    • Java-mode
      • Ant
      • Project management
      • Eclim daemon
      • Goto
      • Refactoring
      • Documentation, Find
      • Errors (problems)
      • Tests
    • Errors (problems) buffer
    • Projects buffer
  • Ensime key bindings
    • Search
    • Ensime Search Mode
    • sbt
    • Typecheck
    • Debug
    • Errors
    • Goto
    • Print and yank types
    • Documentation, Inspect
    • Server
    • Refactoring
    • Tests
    • REPL
  • LSP Java
    • Code intelligence shorcuts
    • Debugger shorcuts
  • Maven
  • Gradle

Description

This layer adds support for the Java language.

Features:

• Support for the following backends:

  • Meghanada client/server (default),
  • Eclim client/server,
  • ENSIME client/server.
  • LSP Java client/server.

• Each provides:

  • Auto-completion using company
  • Linting using flycheck integration
  • Maven and Gradle integration

Layer Installation

Layer

To use this configuration layer, add it to your ~/.spacemacs. You will need to add java to the existing dotspacemacs-configuration-layers list in this file.

Choosing a backend

To choose a default backend set the layer variable java-backend:

  (java :variables java-backend 'eclim)

Backend can be chosen on a per project basis using directory local variables (files named .dir-locals.el at the root of a project), an example to use the eclim backend:

  ;;; Directory Local Variables
  ;;; For more information see (info "(emacs) Directory Variables")

  ((java-mode (java-backend . eclim)))

Note: you can easily add a directory local variable with SPC f v d.

If you want to use the Ensime backend, you should modify your ~/.spacemacs to use the recommended Ensime version (Stable). Please add the following lines to dotspacemacs/user-init:

  (add-to-list 'configuration-layer-elpa-archives '("melpa-stable" . "stable.melpa.org/packages/"))
  (add-to-list 'package-pinned-packages '(ensime . "melpa-stable"))

Backends

Meghanada

Meghanada is composed of a lightweight server and an Emacs minor mode. It is unintrusive and integrates with company and flycheck.

Both Gradle and Maven projects are compatible with Meghanada.

Meghanada is the default backend used by this layer, see Choosing a backend in order to lean how to select a different backend.

Installation

The Meghanada server will be installed automatically whenever a Java file is opened.

If you get issues with the auto-installation you can either download the last version of the server manually there or build from source hosted on the GitHub repository and copy the jar file to .emacs.d/.cache/meghanada folder.

No additional configuration is necessary!

About Maven

Maven is not fully supported by Meghanada (but should still work fine for most projects). If you encounter disconnection from the server then run mvn install at the root of your project first.

Eclim

Eclim provides the ability to access Eclipse features such as code completion, searching, code validation, and many more.

Installation

Eclipse

First you need the last version of Eclispe from the official Eclipse site.

Note: if you are on MacOS there some issues between the new native Eclipse application installed by the Eclispe-install.app wizard and the Eclim installer wizard. The recommended way to install Eclipse on MacOS is by using homebrew or by get the tar.gz compressed file instead. With homebrew the command line to install Eclipse is brew cask install eclipse-jee.

Eclim

For installation of Eclim check the official page to download the installer then double click on it or launch it in the command line with the following command (the example is for MacOS, replace the eclispe.home definition by your correct location as well as the current version of eclim):

  $ java -Dvim.skip=true -Declipse.home=/Applications/Eclipse.app/Contents/Eclipse -jar eclim_2.6.0.jar install

Configuration

You may need to set the Eclipse and Eclim paths in your dotfile as layer variables or in the dotspacemacs/user-config, for instance on MacOS as layer variables:

  (java :variables java-backend 'eclim
                   eclim-eclipse-dirs '("/Applications/Eclipse.app/Contents/Eclipse/")
                   eclim-executable "/Applications/Eclipse.app/Contents/Eclipse/eclim")

You can also configure useful other options like the default location for the Eclim workspace (default value is ~/workspace), as shown below:

  (setq
   ;; Specify the workspace to use by default
   eclimd-default-workspace "/path/to/default/eclipse/workspace"
   ;; whether autostarting eclimd or not (default nil)
   eclimd-autostart t
   ;; Whether or not to block emacs until eclimd is ready (default nil)
   eclimd-wait-for-process t)

Usage

Start the eclim daemon with SPC m D s and stop it with SPC m D k. (See below.)

Syntax checking is performed only on demand with SPC e e to preserve perfomance.

Auto-save feature may freeze Emacs sometimes, use C-g to unfreeze Emacs or atlernatively you can set dotspacemacs-auto-save-file-location to nil.

ENSIME

Another backend option is the ENSIME server, which is a lot more responsive than Eclim. ENSIME is originally made to work with Scala but it now works with plain Java projects as well.

Installation when using SBT

Find it with your favourite package manager, eg:

  nix-env --install sbt

or refer to the sbt installation instructions.

Installation when using Gradle

Refer to the Ensime installation instructions to install the ensime-gradle plugin.

Configuration

Follow the ENSIME configuration instructions. Spacemacs uses the development version of Ensime so follow the appropriate steps.

To use the build functions under SPC m b you need to use version 0.13.5 or newer of sbt, and specify that in your project's project/build.properties. For example,

  sbt.version=0.13.11

Usage

SPC SPC spacemacs/ensime-gen-and-restart or SPC m D r generates a new config for a project and starts the server. Afterwards SPC SPC ensime or SPC m D s will suffice do the trick.

Issues

ENSIME is originally built for Scala, so support for java is not complete, in particular refactoring doesn't work.

LSP Java

LSP Java is the Java adapter for LSP Mode which is the Emacs client for Language Server Protocol.

Usage

Open a java file and the lsp-java will automatically download the server and ask you which projects you want to import.

Key bindings

Meghanada

Server

Key binding	Description
SPC m D c	Connect to server
SPC m D d	Disconnect from server
SPC m D i	Install server (should be done automatically
SPC m D k	Kill server
SPC m D l	Clear server cache
SPC m D p	Ping server
SPC m D r	Restart server
SPC m D s	Start server
SPC m D u	Update server
SPC m D v	Print version of the server

Navigation

Key binding	Description
SPC m g b	Jump back to previous location
SPC m g g	Jump to declaration

Compilation

Key binding	Description
SPC m c b	Compile file (buffer)
SPC m c c	Compile project

Tests (junit)

Key binding	Description
SPC m t a	Run all tests
SPC m t c	Run test class around point
SPC m t l	Run last tests
SPC m t t	Run test cause around point

Refactoring

Key binding	Description
SPC m =	Beautify code
SPC m r i	Optimize imports
SPC m r I	Import all
SPC m r n	Create a new class, interface, or enum

Tasks

Key binding	Description
SPC m x :	Run task

Eclim

Java-mode

Ant

Key binding	Description
SPC m a a	Run Ant
SPC m a c	Clear Ant cache
SPC m a r	Run Ant
SPC m a v	Validate

Project management

Key binding	Description
SPC m p b	Build project
SPC m p c	Create project
SPC m p d	Delete project
SPC m p g	Open file in current project
SPC m p i	Import project
SPC m p j	Information about project
SPC m p k	Close project
SPC m p o	Open project
SPC m p p	Open project management buffer
SPC m p r	Run project
SPC m p u	Update project

Eclim daemon

Key binding	Description
SPC m D k	Kill daemon
SPC m D s	Start daemon

Goto

Key binding	Description
M-​,​	jump back from go to declaration/definition
SPC m g g	go to declaration
SPC m g t	go to type definition

Refactoring

Key binding	Description
SPC m r c	create a constructor
SPC m r f	format file
SPC m r g	generate getter and setter
SPC m r i	optimize imports
SPC m r j	implement or override a method
SPC m r n	create a new class, enum, or interface
SPC m r r	rename symbol

Documentation, Find

Key binding	Description
SPC m f f	general find in project
SPC m h c	call hierarchy
SPC m h h	show documentation for symbol at point
SPC m h i	view hierarchy
SPC m h u	show usages for symbol at point

Errors (problems)

Key binding	Description
SPC e e	Force an error check
SPC e l	List errors
SPC e n	Next error
SPC e p	Previous error
SPC m e e	Correct error around point

Tests

Key binding	Description
SPC m t t	run JUnit tests for current method or current file or project

Errors (problems) buffer

Key binding	Description
RET	go to problem place
a	show all problems
e	show only errors
f	show problems only for current file
g	refresh problems
q	quit
w	show only warnings

Projects buffer

Key binding	Description
RET	go to current project
c	go to problem place
D	delete project
g	refresh buffer
i	info about current project
I	import existing project into the workspace
m	mark current project
M	mark all projects
N	create new project
o	open project
p	update project
q	quit
R	rename current project
u	unmark current project
U	unmark all projects

Ensime key bindings

Search

Key binding	Description
SPC m /	incremental search using ensime-scalex major mode
SPC m ?	incremental search in all live buffers

Ensime Search Mode

Key binding	Description
C-j	Move to next match
C-k	Move to previous match
C-i	Insert at point import of current result
RET	Jump to the target of the currently selected ensime-search-result
C-q	Quit ensime search

sbt

Key binding	Description
SPC m b .	sbt transient state
SPC m b b	sbt command
SPC m b c	compile
SPC m b C	clean command
SPC m b i	switch to sbt shell
SPC m b p	package command
SPC m b r	run command

Typecheck

Key binding	Description
SPC m c t	type check the current file

Debug

Key binding	Description
SPC m d A	Attach to a remote debugger
SPC m d b	set breakpoint
SPC m d B	clear breakpoint
SPC m d C	clear all breakpoints
SPC m d c	continue
SPC m d i	inspect value at point
SPC m d n	next
SPC m d o	step out
SPC m d q	quit
SPC m d r	run
SPC m d s	step
SPC m d t	backtrace

Note: These key bindings need a transient-state, PR welcome :-)

Errors

Key binding	Description
SPC m e e	print error at point
SPC m e s	switch to buffer containing the stack trace parser

Goto

Key binding	Description
SPC m g g	go to definition

Print and yank types

SPC m h T	print full type name at point
SPC m h t	print short type name at point
SPC m y T	yank full type name at point
SPC m y t	yank short type name at point

Documentation, Inspect

Key binding	Description
SPC m h h	show documentation for symbol at point
SPC m h u	show uses for symbol at point

Server

Key binding	Description
SPC m D f	reload open files
SPC m D r	regenerate the .ensime and restart the ensime server
SPC m D s	start ensime server

Refactoring

Key binding	Description
SPC m r a	add type annotation
SPC m r d	get rid of an intermediate variable (ensime-refactor-inline-local)
SPC m r D	get rid of an intermediate variable (ensime-undo-peek)
SPC m r i	organize imports
SPC m r m	extract a range of code into a method
SPC m r r	rename a symbol project wide
SPC m r t	import type at point
SPC m r v	extract a range of code into a variable
SPC m z	expand/contract region

Tests

Key binding	Description
SPC m t a	test command (sbt)
SPC m t r	test quick command (sbt)
SPC m t t	test only (sbt)

REPL

Key binding	Description
SPC m s a	ask for a file to be loaded in the REPL
SPC m s b	send buffer to the REPL
SPC m s B	send buffer to the REPL and focus the REPL buffer in insert state
SPC m s i	start or switch to the REPL inferior process
SPC m s r	send region to the REPL
SPC m s R	send region to the REPL and focus the REPL buffer in insert state

LSP Java

Code intelligence shorcuts

Key binding	Description
SPC m g g	Go to definition
SPC m g r	Find references
SPC m g R	Peek references using lsp-ui
SPC m g d	Goto type definition
SPC m g a	Search type in project
SPC m g A	Search type in project using lsp-ui
SPC m h h	Describe thing at point
SPC m e l	List project errors/warnings
SPC m p u	Refresh user settings
SPC m e a	Execute code action
SPC m q r	Restart workspace
SPC m r o i	Organize imports
SPC m r r	Rename symbol
SPC m r a i	Add import
SPC m r a m	Add unimplemented methods
SPC m r c p	Create parameter
SPC m r c f	Create field
SPC m r e c	Extract constant
SPC m r e l	Extract local
SPC m r e m	Extract method
SPC m r c i	Convert to static import
SPC m r a t	Add throws exception
SPC m r a a	Assign all parameters to fields
SPC m r a f	Assign parameter to field
SPC m r g g	Generate getters/setters
SPC m r g e	Generate equals and hashCode methods
SPC m r g t	Generate toString method
SPC m r g o	Generate method overrides
SPC m c c	Build project
SPC m c p	Create spring boot project
SPC m a n	Actionable notifications
SPC m =	Format code

Debugger shorcuts

Key binding	Description
SPC m d t t	Debug test method
SPC m d t c	Debug test class
SPC m d j	Debug java class(main method).
SPC m t t	Run test method
SPC m t c	Run test class
SPC m d d d	start debugging
SPC m d d l	debug last configuration
SPC m d d r	debug recent configuration
SPC m d c	continue
SPC m d i	step in
SPC m d o	step out
SPC m d s	next step
SPC m d v	inspect value at point
SPC m d r	restart frame
SPC m d .	debug transient state
SPC m d a	abandon current session
SPC m d A	abandon all process
SPC m d e e	eval
SPC m d e r	eval region
SPC m d e t	eval value at point
SPC m d S s	switch session
SPC m d S t	switch thread
SPC m d S f	switch frame
SPC m d I i	inspect
SPC m d I r	inspect region
SPC m d I t	inspect value at point
SPC m d b b	toggle a breakpoint
SPC m d b c	change breakpoint condition
SPC m d b l	change breakpoint log condition
SPC m d b h	change breakpoint hit count
SPC m d b a	add a breakpoint
SPC m d b d	delete a breakpoint
SPC m d b D	clear all breakpoints
SPC m d '_	Run debug REPL
SPC m d w l	list local variables
SPC m d w o	goto output buffer if present
SPC m d w s	list sessions
SPC m d w b	list breakpoints

Maven

Key binding	Description
SPC m m c c	Compile
SPC m m c C	Clean
SPC m m c r	Clean and compile
SPC m m g a	Switch between class and test file
SPC m m g A	Switch between class and test file in another window
SPC m m t a	Run all tests
SPC m m t C-a	Clean and run all tests
SPC m m t b	Run current buffer tests
SPC m m t i	Test and install
SPC m m t t	Run a specific test

Gradle

Key binding	Description
SPC m l c c	Compile
SPC m l c C	Clean
SPC m l c r	Clean and compile
SPC m l t a	Run all tests
SPC m l t b	Run current buffer tests
SPC m l t t	Run a specific test
SPC m l x	Execute a Gradle task