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

#+TITLE: Java layer

[[file:img/java.png]]

* Table of Contents                     :TOC_4_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#layer-installation][Layer Installation]]
  - [[#layer][Layer]]
  - [[#choosing-a-backend][Choosing a backend]]
- [[#backends][Backends]]
  - [[#meghanada][Meghanada]]
    - [[#installation][Installation]]
    - [[#about-maven][About Maven]]
  - [[#eclim][Eclim]]
    - [[#installation-1][Installation]]
      - [[#eclipse][Eclipse]]
      - [[#eclim-1][Eclim]]
    - [[#configuration][Configuration]]
    - [[#usage][Usage]]
  - [[#ensime][ENSIME]]
    - [[#installation-when-using-sbt][Installation when using SBT]]
    - [[#installation-when-using-gradle][Installation when using Gradle]]
    - [[#configuration-1][Configuration]]
    - [[#usage-1][Usage]]
    - [[#issues][Issues]]
  - [[#lsp-java][LSP Java]]
    - [[#usage-2][Usage]]
- [[#key-bindings][Key bindings]]
  - [[#meghanada-1][Meghanada]]
    - [[#server][Server]]
    - [[#navigation][Navigation]]
    - [[#compilation][Compilation]]
    - [[#tests-junit][Tests (junit)]]
    - [[#refactoring][Refactoring]]
    - [[#tasks][Tasks]]
  - [[#eclim-2][Eclim]]
    - [[#java-mode][Java-mode]]
      - [[#ant][Ant]]
      - [[#project-management][Project management]]
      - [[#eclim-daemon][Eclim daemon]]
      - [[#goto][Goto]]
      - [[#refactoring-1][Refactoring]]
      - [[#documentation-find][Documentation, Find]]
      - [[#errors-problems][Errors (problems)]]
      - [[#tests][Tests]]
    - [[#errors-problems-buffer][Errors (problems) buffer]]
    - [[#projects-buffer][Projects buffer]]
  - [[#ensime-key-bindings][Ensime key bindings]]
    - [[#search][Search]]
    - [[#ensime-search-mode][Ensime Search Mode]]
    - [[#sbt][sbt]]
    - [[#typecheck][Typecheck]]
    - [[#debug][Debug]]
    - [[#errors][Errors]]
    - [[#goto-1][Goto]]
    - [[#print-and-yank-types][Print and yank types]]
    - [[#documentation-inspect][Documentation, Inspect]]
    - [[#server-1][Server]]
    - [[#refactoring-2][Refactoring]]
    - [[#tests-1][Tests]]
    - [[#repl][REPL]]
  - [[#lsp-java-1][LSP Java]]
    - [[#code-intelligence-shorcuts][Code intelligence shorcuts]]
    - [[#debugger-shorcuts][Debugger shorcuts]]
  - [[#maven][Maven]]
  - [[#gradle][Gradle]]

* Description
This layer adds support for the Java language.

** Features:
- Support for the following backends:
  - [[https://github.com/mopemope/meghanada-emacs][Meghanada]] client/server (default),
  - [[http://eclim.org][Eclim]] client/server,
  - [[https://ensime.github.io/][ENSIME]] client/server.
  - [[https://github.com/emacs-lsp/lsp-java][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=:

#+BEGIN_SRC elisp
  (java :variables java-backend 'eclim)
#+END_SRC

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:

#+BEGIN_SRC elisp
  ;;; Directory Local Variables
  ;;; For more information see (info "(emacs) Directory Variables")

  ((java-mode (java-backend . eclim)))
#+END_SRC

*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=:

#+BEGIN_SRC emacs-lisp
  (add-to-list 'configuration-layer-elpa-archives '("melpa-stable" . "stable.melpa.org/packages/"))
  (add-to-list 'package-pinned-packages '(ensime . "melpa-stable"))
#+END_SRC

* 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][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 [[https://dl.bintray.com/mopemope/meghanada/][there]] or build from source hosted on [[https://github.com/mopemope/meghanada-server][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 [[https://www.eclipse.org/downloads/eclipse-packages/][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 [[http://eclim.org/install.html#download][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):

#+BEGIN_SRC shell
  $ java -Dvim.skip=true -Declipse.home=/Applications/Eclipse.app/Contents/Eclipse -jar eclim_2.6.0.jar install
#+END_SRC

*** 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:

#+BEGIN_SRC elisp
  (java :variables java-backend 'eclim
                   eclim-eclipse-dirs '("/Applications/Eclipse.app/Contents/Eclipse/")
                   eclim-executable "/Applications/Eclipse.app/Contents/Eclipse/eclim")
#+END_SRC

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

#+BEGIN_SRC elisp
  (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)
#+END_SRC

*** 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:

#+BEGIN_SRC shell
  nix-env --install sbt
#+END_SRC

or refer to [[http://www.scala-sbt.org/download.html][the sbt installation instructions]].

*** Installation when using Gradle
Refer to the [[https://ensime.github.io/build_tools/gradle/][Ensime installation instructions]] to install the =ensime-gradle=
plugin.

*** Configuration
Follow [[https://ensime.github.io/build_tools/sbt/][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,

#+BEGIN_SRC scala
  sbt.version=0.13.11
#+END_SRC

*** 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 [[https://github.com/emacs-lsp/lsp-mode][LSP Mode]] which is the Emacs client for [[https://github.com/Microsoft/language-server-protocol][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 c c~   | Build 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    |