interactive java support to your tool -- the jshell api and architecture

Copyright © 2015, Oracle and/or its affiliates. All rights reserved. |

JShell API & ArchitectureAdding Interactive Java Support to your Tool

Robert FieldJShell ArchitectCore Language and Tools GroupOracle CorporationNovember 7, 2015

Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | 3

Safe Harbor StatementThe following is intended to outline our general product direction. It is intended for information purposes only, and may not be incorporated into any contract. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described for Oracle’s products remains at the sole discretion of Oracle.


Agenda

Architecture

API

Meta-demo

Completion analysis

Questions

1

2

3

4

5


What is JShell?

• Tool providing a dynamic interaction with the Java™ programming language• Read-Evaluate-Print Loop (REPL) for the Java™ platform– Type in a snippet of Java code, see the results

• Deeply integrated with JDK tool-set– Stays current and compatible

• Also, an API for use within other applications


JShell Guiding Principles

• Compatibily: current and future• Avoid chasing corner-cases• Build on the platform (JDK)• Easy and natural to use• One size does not fit all (API)


JShell Architecture


Implementation: Snippet Processing

• Parsing– Determine the Kind of Snippet and its validity– Uses minor subclassing of standard JavacParser which allows entry into grammar at

the snippet level

• Wrapping– Given knowledge of Kind, wrap as appropriate to create a valid Java program– Generate outer static class, possibly method, var field, temp variable setters, etc

• Analyze – Determine type info and resolution errors (standard compiler API)– Possibly rewrapping one or more times


Implementation: Snippet Processing (cont)

• Compile to bytecode– Use standard compiler API– Use in-memory FileManager– “Corral” body with rewrap on resolution errors

• Remotely Load / Reload– define() on URLClassLoader specialization– Java Debug Interface redefineClasses(…)– Yank into new wrapping class

• Execute


Agenda

Architecture

API

Meta-demo

Completion analysis

Questions

1

2

3

4

5


JShell API


JShell class

• Creation of JShell instances• Evaluation of snippets• Control of environment• Execution control• Snippet enumeration• Snippet mutable state query• Event monitoring/control


JShell class API – JShell instance creation / close

Return Method

JShell create() [static]

JShell.Builder builder() [static]

void close()


JShell class API – Evaluation & Discard

Return Method

Stream<SnippetEvent> eval(String input)

Stream<SnippetEvent>

drop(PersistentSnippet snippet)


JShell class API – Snippet Enumerations

Return Method

Stream<Snippet> snippets()

Stream<VarSnippet> variables()Stream <MethodSnippet> methods()

Stream <TypeDeclSnippet>

types()


JShell class API – Snippet Queries (mutable state)

Return Method

Snippet.Status status(Snippet snippet)

Stream<Diag> diagnostics(Snippet snippet)

Stream<String>unresolvedDependencies( DeclarationSnippet snippet)

String varValue(VarSnippet snippet)


Snippet.Status enum

• VALID• RECOVERABLE_DEFINED• RECOVERABLE_NOT_DEFINED• REJECTED• DROPPED• OVERWRITTEN• NONEXISTENT


JShell.Builder

• Alternative to JShell.create()• Configure JShell instance– Set evaluation input, output, error– ID generation format– Temp variable generation format

• Example: JShell myShell = JShell.builder() .out(myOutStream) .err(myErrStream) .build();


JShell.Builder API

Return Method

JShell.Builderin(java.io.InputStream in)out(java.io.PrintStream out)err(java.io.PrintStream err)

JShell.BuilderidGenerator( BiFunction<Snippet,Integer,String> generator)

JShell.Builder tempVariableNameGenerator( Supplier<String> generator)

JShell build()


SnippetEvent

• Stream of them returned by methods that change the state of Snippets– eval(…)– drop(…)

• Represent a Snippet state transition (including from NONEXISTENT)• Changes to dependents are reported• Immutable


SnippetEvent API – Some queries

Return Method

Snippet snippet()

Snippet.Status status()

Snippet causeSnippet()

String value()

Exception exception()


Snippet

• Represents one source snippet of code• Specialized for the kind of Snippet• Immutable• State of the Snippet (mutable) via JShell query


Snippet Hierarchy

• Snippet• PersistentSnippet•DeclarationSnippet•VarSnippet•MethodSnippet• TypeDeclSnippet• ImportSnippet

• StatementSnippet• ExpressionSnippet• ErroneousSnippet


Snippet API

Return Method

String id()

String source()

Snippet.Kind kind()

Snippet.SubKind subKind()


MethodSnippet API – Additional Queries

Return Method

String name()

String signature()

String parameterTypes()


Agenda

Architecture

API

Meta-demo

Completion analysis

Questions

1

2

3

4

5


Demo


Agenda

Architecture

API

Meta-demo

Completion analysis

Questions

1

2

3

4

5


SourceCodeAnalysis • Find the bounds of a single source snippet• Determine if the input in complete• Suggest completions• Provide documentation• Accessed via JShell.sourceCodeAnalysis()• Suggestions use existing state and full compiler type analysis


SourceCodeAnalysis API

Return Method

SourceCodeAnalysis. CompletionInfo

analyzeCompletion(String input)

Stream< SourceCodeAnalysis. Suggestion>

completionSuggestions( String input, int cursor, int[] anchor)

String documentation( String input, int cursor)


JDK 9 / JShell Information

• Current schedule: GA September 22, 2016• Early access binaries + docs, updated weekly: https://jdk9.java.net/• Source code: http://hg.openjdk.java.net/jdk9/dev/ • -- Kulla (JShell) Project: http://openjdk.java.net/projects/kulla/• JEP 222: jshell: The Java Shell: http://openjdk.java.net/jeps/222

https://jdk9.java.net/

https://jdk9.java.net/

http://hg.openjdk.java.net/jdk9/dev/

http://openjdk.java.net/projects/kulla/

http://openjdk.java.net/jeps/222


The Team

• Engineering– Robert Field– Jan Lahoda

• OpenJDK Commiters– Shinya Yoshida– You?

• Testing– Andrei Eremeev

– Brian Goetz–Maurizio Cimadamore– Joe Darcy– Paul Sandoz– Jonathan Gibbons–Michel Trudeau

– Sundararajan Athijegannathan– Rémi Forax– Arun Gupta–Mani Sarkar– Daniel Daugherty

• Advisors / Cheerleaders / Reviewers


Agenda

Architecture

API

Meta-demo

Completion analysis

Questions

1

2

3

4

5


Q & A


Safe Harbor StatementThe preceding is intended to outline our general product direction. It is intended for information purposes only, and may not be incorporated into any contract. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described for Oracle’s products remains at the sole discretion of Oracle.

interactive java support to your tool -- the jshell api and architecture

Software