diff --git a/Dockerfile b/Dockerfile index 9febf2f..d262945 100644 --- a/Dockerfile +++ b/Dockerfile @@ -3,10 +3,12 @@ WORKDIR /app COPY ["package.json", "./"] COPY ["gulpfile.js", "./"] -COPY ["app", "./app"] RUN npm install gulp -g RUN npm install + +COPY ["app", "./app"] + RUN gulp build -CMD ["gulp", "serve"] \ No newline at end of file +CMD ["gulp", "serve"] diff --git a/README.md b/README.md index f900a97..fc01462 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -# Dev.java +# Contributing to Dev.java -[Dev.java](https://dev.java) is the official website for the Java platform and language maintained by the Java Platform Group at Oracle. +[Dev.java](https://dev.java) is the official website for the Java platform and language maintained by the Java Platform Group at Oracle. We accept contributions from community members through this repository. [Click here](https://dev.java/authors) for examples of contributed content. -We [recently announced](https://inside.java) that we are accepting contributions to Dev.java. This repository contains most of the content for the website, a lightweight JavaScript toolchain to build the site into static HTML, and guidelines for contributing to it. +This repository contains the contribution guidelines as well as a lightweight JavaScript toolchain to build the site into static HTML. Here are the sections of this document: @@ -11,6 +11,7 @@ Here are the sections of this document: * [Content Lifecycle](#content-lifecycle) * [Content Proposal](#content-proposal) * [GitHub Workflow](#github-workflow) + * [Content License](#content-license) * [Building the Site](#building-the-site) * [Working with Content](#working-with-content) @@ -61,7 +62,7 @@ All content must start with a Content Proposal. This will be in the form of a Gi ### GitHub Workflow -Once your proposal has been moved to the `accepted` stage, you can begin working on your content. Here are the steps to do this: +Once your proposal has been moved to the `approved` stage, you can begin working on your content. Here are the steps to do this: 1. Fork this repo 1. Create a branch off of `main` for each piece of content @@ -70,6 +71,10 @@ Once your proposal has been moved to the `accepted` stage, you can begin working 1. Submit a pull request back to this repo +### Content License + +Contributors must sign the [Oracle Contributor Agreement](https://oca.opensource.oracle.com/) which will be verified once there is a pull request created. Contributed content is made available under the [UPL license](https://oss.oracle.com/licenses/upl/). You can find examples [here](https://dev.java/authors). + ## Building the Site @@ -86,12 +91,14 @@ A browser should launch viewing [https://localhost:3000](https://localhost:3000) ### Option 2: Use Docker -1. docker build --tag devjava . -1. docker run --publish 3000:3000 devjava +1. `docker build --tag devjava .` +1. `docker run --publish 3000:3000 --init -it --rm devjava` You should then be able to open a browser and visit [https://localhost:3000](https://localhost:3000) +(For a more dynamic development experience avoiding a Docker build after every change, you can mount the local /app folder to the container by adding option `-v $PWD/app:/app/app` to your `docker run` command. Note: $PWD may not work in Windows.) + ## Working with Content -See [working with content guide](/docs/working-with-content.md) \ No newline at end of file +See [working with content guide](/docs/working-with-content.md) diff --git a/app/assets/images/eclipse/breakpoint.png b/app/assets/images/eclipse/breakpoint.png new file mode 100644 index 0000000..fecc252 Binary files /dev/null and b/app/assets/images/eclipse/breakpoint.png differ diff --git a/app/assets/images/eclipse/compilation_error.png b/app/assets/images/eclipse/compilation_error.png new file mode 100644 index 0000000..e6ebe05 Binary files /dev/null and b/app/assets/images/eclipse/compilation_error.png differ diff --git a/app/assets/images/eclipse/console_output.png b/app/assets/images/eclipse/console_output.png new file mode 100644 index 0000000..8b8677c Binary files /dev/null and b/app/assets/images/eclipse/console_output.png differ diff --git a/app/assets/images/eclipse/content_assist_main.png b/app/assets/images/eclipse/content_assist_main.png new file mode 100644 index 0000000..d7658b9 Binary files /dev/null and b/app/assets/images/eclipse/content_assist_main.png differ diff --git a/app/assets/images/eclipse/content_assist_suggest_class.png b/app/assets/images/eclipse/content_assist_suggest_class.png new file mode 100644 index 0000000..93f3768 Binary files /dev/null and b/app/assets/images/eclipse/content_assist_suggest_class.png differ diff --git a/app/assets/images/eclipse/content_assist_suggest_method.png b/app/assets/images/eclipse/content_assist_suggest_method.png new file mode 100644 index 0000000..0e115ff Binary files /dev/null and b/app/assets/images/eclipse/content_assist_suggest_method.png differ diff --git a/app/assets/images/eclipse/content_assist_sysout.png b/app/assets/images/eclipse/content_assist_sysout.png new file mode 100644 index 0000000..ee7706f Binary files /dev/null and b/app/assets/images/eclipse/content_assist_sysout.png differ diff --git a/app/assets/images/eclipse/context_generate_getters_setters.png b/app/assets/images/eclipse/context_generate_getters_setters.png new file mode 100644 index 0000000..b921406 Binary files /dev/null and b/app/assets/images/eclipse/context_generate_getters_setters.png differ diff --git a/app/assets/images/eclipse/context_generate_hashcode_equals.png b/app/assets/images/eclipse/context_generate_hashcode_equals.png new file mode 100644 index 0000000..a2dd637 Binary files /dev/null and b/app/assets/images/eclipse/context_generate_hashcode_equals.png differ diff --git a/app/assets/images/eclipse/context_rename.png b/app/assets/images/eclipse/context_rename.png new file mode 100644 index 0000000..adce4b6 Binary files /dev/null and b/app/assets/images/eclipse/context_rename.png differ diff --git a/app/assets/images/eclipse/context_tostring.png b/app/assets/images/eclipse/context_tostring.png new file mode 100644 index 0000000..6373314 Binary files /dev/null and b/app/assets/images/eclipse/context_tostring.png differ diff --git a/app/assets/images/eclipse/create_class.png b/app/assets/images/eclipse/create_class.png new file mode 100644 index 0000000..7f25f1c Binary files /dev/null and b/app/assets/images/eclipse/create_class.png differ diff --git a/app/assets/images/eclipse/create_java_project.gif b/app/assets/images/eclipse/create_java_project.gif new file mode 100644 index 0000000..c69edd0 Binary files /dev/null and b/app/assets/images/eclipse/create_java_project.gif differ diff --git a/app/assets/images/eclipse/debug_button.png b/app/assets/images/eclipse/debug_button.png new file mode 100644 index 0000000..0e16e2e Binary files /dev/null and b/app/assets/images/eclipse/debug_button.png differ diff --git a/app/assets/images/eclipse/debug_button_in_toolbar.png b/app/assets/images/eclipse/debug_button_in_toolbar.png new file mode 100644 index 0000000..27f3f2d Binary files /dev/null and b/app/assets/images/eclipse/debug_button_in_toolbar.png differ diff --git a/app/assets/images/eclipse/debug_perspective.png b/app/assets/images/eclipse/debug_perspective.png new file mode 100644 index 0000000..d682536 Binary files /dev/null and b/app/assets/images/eclipse/debug_perspective.png differ diff --git a/app/assets/images/eclipse/debug_perspective_switch.png b/app/assets/images/eclipse/debug_perspective_switch.png new file mode 100644 index 0000000..407e6aa Binary files /dev/null and b/app/assets/images/eclipse/debug_perspective_switch.png differ diff --git a/app/assets/images/eclipse/debug_resume.png b/app/assets/images/eclipse/debug_resume.png new file mode 100644 index 0000000..74b903e Binary files /dev/null and b/app/assets/images/eclipse/debug_resume.png differ diff --git a/app/assets/images/eclipse/debug_step_into.png b/app/assets/images/eclipse/debug_step_into.png new file mode 100644 index 0000000..e3ae83c Binary files /dev/null and b/app/assets/images/eclipse/debug_step_into.png differ diff --git a/app/assets/images/eclipse/debug_step_over.png b/app/assets/images/eclipse/debug_step_over.png new file mode 100644 index 0000000..b928ddc Binary files /dev/null and b/app/assets/images/eclipse/debug_step_over.png differ diff --git a/app/assets/images/eclipse/debug_toolbar_buttons.png b/app/assets/images/eclipse/debug_toolbar_buttons.png new file mode 100644 index 0000000..3441f4e Binary files /dev/null and b/app/assets/images/eclipse/debug_toolbar_buttons.png differ diff --git a/app/assets/images/eclipse/file_create_project.png b/app/assets/images/eclipse/file_create_project.png new file mode 100644 index 0000000..a478d33 Binary files /dev/null and b/app/assets/images/eclipse/file_create_project.png differ diff --git a/app/assets/images/eclipse/getter_setter_modal.png b/app/assets/images/eclipse/getter_setter_modal.png new file mode 100644 index 0000000..f1a3a70 Binary files /dev/null and b/app/assets/images/eclipse/getter_setter_modal.png differ diff --git a/app/assets/images/eclipse/hashcode_equals_modal.png b/app/assets/images/eclipse/hashcode_equals_modal.png new file mode 100644 index 0000000..e482359 Binary files /dev/null and b/app/assets/images/eclipse/hashcode_equals_modal.png differ diff --git a/app/assets/images/eclipse/install.png b/app/assets/images/eclipse/install.png new file mode 100644 index 0000000..994474d Binary files /dev/null and b/app/assets/images/eclipse/install.png differ diff --git a/app/assets/images/eclipse/java_class_creation.png b/app/assets/images/eclipse/java_class_creation.png new file mode 100644 index 0000000..06d3368 Binary files /dev/null and b/app/assets/images/eclipse/java_class_creation.png differ diff --git a/app/assets/images/eclipse/open_problems_view.png b/app/assets/images/eclipse/open_problems_view.png new file mode 100644 index 0000000..5c32f95 Binary files /dev/null and b/app/assets/images/eclipse/open_problems_view.png differ diff --git a/app/assets/images/eclipse/problems_view.png b/app/assets/images/eclipse/problems_view.png new file mode 100644 index 0000000..7955656 Binary files /dev/null and b/app/assets/images/eclipse/problems_view.png differ diff --git a/app/assets/images/eclipse/problems_view_warning.png b/app/assets/images/eclipse/problems_view_warning.png new file mode 100644 index 0000000..90a125e Binary files /dev/null and b/app/assets/images/eclipse/problems_view_warning.png differ diff --git a/app/assets/images/eclipse/rename_box.png b/app/assets/images/eclipse/rename_box.png new file mode 100644 index 0000000..8915382 Binary files /dev/null and b/app/assets/images/eclipse/rename_box.png differ diff --git a/app/assets/images/eclipse/rename_different_text.png b/app/assets/images/eclipse/rename_different_text.png new file mode 100644 index 0000000..eb1c19c Binary files /dev/null and b/app/assets/images/eclipse/rename_different_text.png differ diff --git a/app/assets/images/eclipse/run_as_editor.png b/app/assets/images/eclipse/run_as_editor.png new file mode 100644 index 0000000..6c97d36 Binary files /dev/null and b/app/assets/images/eclipse/run_as_editor.png differ diff --git a/app/assets/images/eclipse/run_as_package_explorer.png b/app/assets/images/eclipse/run_as_package_explorer.png new file mode 100644 index 0000000..0fa6d1c Binary files /dev/null and b/app/assets/images/eclipse/run_as_package_explorer.png differ diff --git a/app/assets/images/eclipse/run_button.png b/app/assets/images/eclipse/run_button.png new file mode 100644 index 0000000..33e46e4 Binary files /dev/null and b/app/assets/images/eclipse/run_button.png differ diff --git a/app/assets/images/eclipse/run_buttons_toolbar.png b/app/assets/images/eclipse/run_buttons_toolbar.png new file mode 100644 index 0000000..7a256f4 Binary files /dev/null and b/app/assets/images/eclipse/run_buttons_toolbar.png differ diff --git a/app/assets/images/eclipse/tostring_options.png b/app/assets/images/eclipse/tostring_options.png new file mode 100644 index 0000000..e5ea8e6 Binary files /dev/null and b/app/assets/images/eclipse/tostring_options.png differ diff --git a/app/assets/images/eclipse/warning.png b/app/assets/images/eclipse/warning.png new file mode 100644 index 0000000..3e7b23b Binary files /dev/null and b/app/assets/images/eclipse/warning.png differ diff --git a/app/assets/images/eclipse/welcome.png b/app/assets/images/eclipse/welcome.png new file mode 100644 index 0000000..c82aa6c Binary files /dev/null and b/app/assets/images/eclipse/welcome.png differ diff --git a/app/assets/images/eclipse/workspace_selection.png b/app/assets/images/eclipse/workspace_selection.png new file mode 100644 index 0000000..306118b Binary files /dev/null and b/app/assets/images/eclipse/workspace_selection.png differ diff --git a/app/assets/images/intellij-idea/alt-enter.png b/app/assets/images/intellij-idea/alt-enter.png new file mode 100644 index 0000000..9f06c58 Binary files /dev/null and b/app/assets/images/intellij-idea/alt-enter.png differ diff --git a/app/assets/images/intellij-idea/create-test.png b/app/assets/images/intellij-idea/create-test.png new file mode 100644 index 0000000..dc545c6 Binary files /dev/null and b/app/assets/images/intellij-idea/create-test.png differ diff --git a/app/assets/images/intellij-idea/debug.gif b/app/assets/images/intellij-idea/debug.gif new file mode 100644 index 0000000..72588a4 Binary files /dev/null and b/app/assets/images/intellij-idea/debug.gif differ diff --git a/app/assets/images/intellij-idea/download-jdk-popup.png b/app/assets/images/intellij-idea/download-jdk-popup.png new file mode 100644 index 0000000..43bb3d0 Binary files /dev/null and b/app/assets/images/intellij-idea/download-jdk-popup.png differ diff --git a/app/assets/images/intellij-idea/edit-configurations.png b/app/assets/images/intellij-idea/edit-configurations.png new file mode 100644 index 0000000..65b694f Binary files /dev/null and b/app/assets/images/intellij-idea/edit-configurations.png differ diff --git a/app/assets/images/intellij-idea/find-in-files.png b/app/assets/images/intellij-idea/find-in-files.png new file mode 100644 index 0000000..f52b675 Binary files /dev/null and b/app/assets/images/intellij-idea/find-in-files.png differ diff --git a/app/assets/images/intellij-idea/generate-code.png b/app/assets/images/intellij-idea/generate-code.png new file mode 100644 index 0000000..50857cd Binary files /dev/null and b/app/assets/images/intellij-idea/generate-code.png differ diff --git a/app/assets/images/intellij-idea/hello-world.gif b/app/assets/images/intellij-idea/hello-world.gif new file mode 100644 index 0000000..ec3453c Binary files /dev/null and b/app/assets/images/intellij-idea/hello-world.gif differ diff --git a/app/assets/images/intellij-idea/junit5-dependencies.png b/app/assets/images/intellij-idea/junit5-dependencies.png new file mode 100644 index 0000000..f69bd3f Binary files /dev/null and b/app/assets/images/intellij-idea/junit5-dependencies.png differ diff --git a/app/assets/images/intellij-idea/main-method.png b/app/assets/images/intellij-idea/main-method.png new file mode 100644 index 0000000..6db76fb Binary files /dev/null and b/app/assets/images/intellij-idea/main-method.png differ diff --git a/app/assets/images/intellij-idea/new-java-class.png b/app/assets/images/intellij-idea/new-java-class.png new file mode 100644 index 0000000..86ce5b1 Binary files /dev/null and b/app/assets/images/intellij-idea/new-java-class.png differ diff --git a/app/assets/images/intellij-idea/new-project-menu.png b/app/assets/images/intellij-idea/new-project-menu.png new file mode 100644 index 0000000..e2816f3 Binary files /dev/null and b/app/assets/images/intellij-idea/new-project-menu.png differ diff --git a/app/assets/images/intellij-idea/new-project.png b/app/assets/images/intellij-idea/new-project.png new file mode 100644 index 0000000..1eea291 Binary files /dev/null and b/app/assets/images/intellij-idea/new-project.png differ diff --git a/app/assets/images/intellij-idea/project.png b/app/assets/images/intellij-idea/project.png new file mode 100644 index 0000000..166caa2 Binary files /dev/null and b/app/assets/images/intellij-idea/project.png differ diff --git a/app/assets/images/intellij-idea/refactor.gif b/app/assets/images/intellij-idea/refactor.gif new file mode 100644 index 0000000..b9b910a Binary files /dev/null and b/app/assets/images/intellij-idea/refactor.gif differ diff --git a/app/assets/images/intellij-idea/run-config.png b/app/assets/images/intellij-idea/run-config.png new file mode 100644 index 0000000..ac281b1 Binary files /dev/null and b/app/assets/images/intellij-idea/run-config.png differ diff --git a/app/assets/images/intellij-idea/run.png b/app/assets/images/intellij-idea/run.png new file mode 100644 index 0000000..fa5a38f Binary files /dev/null and b/app/assets/images/intellij-idea/run.png differ diff --git a/app/assets/images/intellij-idea/search-everywhere.png b/app/assets/images/intellij-idea/search-everywhere.png new file mode 100644 index 0000000..7d1385c Binary files /dev/null and b/app/assets/images/intellij-idea/search-everywhere.png differ diff --git a/app/assets/images/intellij-idea/welcome-screen.png b/app/assets/images/intellij-idea/welcome-screen.png new file mode 100644 index 0000000..56ca568 Binary files /dev/null and b/app/assets/images/intellij-idea/welcome-screen.png differ diff --git a/app/assets/images/javafx/animation/interpolator/discrete-example.gif b/app/assets/images/javafx/animation/interpolator/discrete-example.gif new file mode 100644 index 0000000..b755231 Binary files /dev/null and b/app/assets/images/javafx/animation/interpolator/discrete-example.gif differ diff --git a/app/assets/images/javafx/animation/interpolator/ease-both-example.gif b/app/assets/images/javafx/animation/interpolator/ease-both-example.gif new file mode 100644 index 0000000..58f46ff Binary files /dev/null and b/app/assets/images/javafx/animation/interpolator/ease-both-example.gif differ diff --git a/app/assets/images/javafx/animation/interpolator/ease-in-example.gif b/app/assets/images/javafx/animation/interpolator/ease-in-example.gif new file mode 100644 index 0000000..bd392bd Binary files /dev/null and b/app/assets/images/javafx/animation/interpolator/ease-in-example.gif differ diff --git a/app/assets/images/javafx/animation/interpolator/ease-out-example.gif b/app/assets/images/javafx/animation/interpolator/ease-out-example.gif new file mode 100644 index 0000000..e283435 Binary files /dev/null and b/app/assets/images/javafx/animation/interpolator/ease-out-example.gif differ diff --git a/app/assets/images/javafx/animation/interpolator/linear-example.gif b/app/assets/images/javafx/animation/interpolator/linear-example.gif new file mode 100644 index 0000000..8175bb3 Binary files /dev/null and b/app/assets/images/javafx/animation/interpolator/linear-example.gif differ diff --git a/app/assets/images/javafx/animation/timeline-example.gif b/app/assets/images/javafx/animation/timeline-example.gif new file mode 100644 index 0000000..1af1aeb Binary files /dev/null and b/app/assets/images/javafx/animation/timeline-example.gif differ diff --git a/app/assets/images/javafx/animation/transition/fade-example.gif b/app/assets/images/javafx/animation/transition/fade-example.gif new file mode 100644 index 0000000..af6bfcf Binary files /dev/null and b/app/assets/images/javafx/animation/transition/fade-example.gif differ diff --git a/app/assets/images/javafx/animation/transition/fill-example.gif b/app/assets/images/javafx/animation/transition/fill-example.gif new file mode 100644 index 0000000..df955c2 Binary files /dev/null and b/app/assets/images/javafx/animation/transition/fill-example.gif differ diff --git a/app/assets/images/javafx/animation/transition/parallel-example.gif b/app/assets/images/javafx/animation/transition/parallel-example.gif new file mode 100644 index 0000000..2cc0907 Binary files /dev/null and b/app/assets/images/javafx/animation/transition/parallel-example.gif differ diff --git a/app/assets/images/javafx/animation/transition/path-example.gif b/app/assets/images/javafx/animation/transition/path-example.gif new file mode 100644 index 0000000..b025af3 Binary files /dev/null and b/app/assets/images/javafx/animation/transition/path-example.gif differ diff --git a/app/assets/images/javafx/animation/transition/pause-example.gif b/app/assets/images/javafx/animation/transition/pause-example.gif new file mode 100644 index 0000000..bafc066 Binary files /dev/null and b/app/assets/images/javafx/animation/transition/pause-example.gif differ diff --git a/app/assets/images/javafx/animation/transition/rotate-example.gif b/app/assets/images/javafx/animation/transition/rotate-example.gif new file mode 100644 index 0000000..b584b57 Binary files /dev/null and b/app/assets/images/javafx/animation/transition/rotate-example.gif differ diff --git a/app/assets/images/javafx/animation/transition/scale-example.gif b/app/assets/images/javafx/animation/transition/scale-example.gif new file mode 100644 index 0000000..6194da2 Binary files /dev/null and b/app/assets/images/javafx/animation/transition/scale-example.gif differ diff --git a/app/assets/images/javafx/animation/transition/stroke-example.gif b/app/assets/images/javafx/animation/transition/stroke-example.gif new file mode 100644 index 0000000..5eff105 Binary files /dev/null and b/app/assets/images/javafx/animation/transition/stroke-example.gif differ diff --git a/app/assets/images/javafx/animation/transition/translate-example.gif b/app/assets/images/javafx/animation/transition/translate-example.gif new file mode 100644 index 0000000..c5a2303 Binary files /dev/null and b/app/assets/images/javafx/animation/transition/translate-example.gif differ diff --git a/app/data/authors.yaml b/app/data/authors.yaml index a41d060..96c500d 100644 --- a/app/data/authors.yaml +++ b/app/data/authors.yaml @@ -20,7 +20,6 @@ moderator on CodeRanch which is the best java discussion forum on the web. She has moderated on topics including JDBC, Testing, IDEs, Process and Performance. She is one of the leaders of javasig.com and mentors a high school robotics team in her free time. - - name: Cay Horstmann email: cay@horstmann.com @@ -81,4 +80,38 @@ photo_url: https://danthe1st.github.io/img/Daniel.jpg website: https://danthe1st.github.io/ description: | - Daniel is a Java Developer from Austria who is also managing the Discord Java Community. \ No newline at end of file + Daniel is a Java Developer from Austria who is also managing the Discord Java Community. + +- name: Marit van Dijk + email: mlvandijk@gmail.com + photo_url: https://maritvandijk.com/wp-content/uploads/2022/08/cropped-marit-van-dijk-1.jpeg + github: mlvandijk + twitter: MaritvanDijk77 + website: https://maritvandijk.com + description: | + Marit is a Software Developer, a Java Champion and works as a Developer Advocate at JetBrains. + She speaks at international conferences (including JavaZone, Devoxx, Voxxed Days, JSpring, JFall, JFokus and GOTO), local JUGs, podcasts and webinars, + and has contributed to the book “97 Things Every Java Programmer Should Know” (O’Reilly Media). + +- name: Connor Schweighöfer + email: squidxtv@gmail.com + photo_url: https://squidxtv.me/img/Connor.png + github: SquidXTV + twitter: SquidXTV + website: https://squidxtv.me/ + description: | + Connor is a Java Developer and high school student from Germany with four years of programming experience. + He is a top helper and community lead in Together Java, one of the largest Java communities on Discord, with over 30,000 users. + Connor has worked on various Java projects, including Discord bots, Minecraft plugins and JavaFX applications. + +- name: Nataliia Dziubenko + github: smthelusive + twitter: worth_exploring + photo_url: https://nataliiadziubenko.com/assets/images/nataliia.png + website: https://nataliiadziubenko.com/ + description: | + Nataliia is a Senior Software Engineer at Xebia. She began her career in 2015 and has since worked with diverse + technologies and domains, primarily focusing on the JVM ecosystem. Nataliia is passionate and curious about everything + around JVM. She enjoys digging into the low-level concepts and diving into how things work under the hood. She also + loves sharing knowledge, so she speaks at conferences such as JFall, JSpring, Voxxed Days, and Java User Groups, + and writes a blog about JVM. \ No newline at end of file diff --git a/app/data/javadoc.json b/app/data/javadoc.json index df3c007..a22629c 100644 --- a/app/data/javadoc.json +++ b/app/data/javadoc.json @@ -1,8 +1,10 @@ { - "current_release": "19", + "current_release": "23", "java-documentation": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/", + "java-documentation-summary": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/docs/api/java.naming/module-summary.html", "javadoc_root": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/docs/api/", + "jdk-release-note": "https://www.oracle.com/java/technologies/javase/jdk-relnotes-index.html", "security-standard-names": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/docs/specs/security/standard-names.html", "jre-jdk-cryptoroadmap": "https://www.java.com/en/jre-jdk-cryptoroadmap.html", @@ -13,7 +15,7 @@ "jpackage": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/docs/specs/man/jpackage.html", "java-api-docs": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/docs/api/index.html", "specification": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/docs/api/index.html", - "release-notes": "https://www.oracle.com/java/technologies/javase/@@CURRENT_RELEASE@@-relnotes.html", + "release-notes": "https://www.oracle.com/java/technologies/javase/@@CURRENT_RELEASE@@u-relnotes.html", "jvm-guide": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/vm/java-virtual-machine-technology-overview.html", "gc-tuning": { "link": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/gctuning/introduction-garbage-collection-tuning.html", @@ -52,6 +54,7 @@ "jmod": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/docs/specs/man/jmod.html", "jdeps": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/docs/specs/man/jdeps.html", "jdeprscan": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/docs/specs/man/jdeprscan.html", + "jwebserver": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/docs/specs/man/jwebserver.html", "jfr": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/docs/specs/man/jfr.html", "jconsole": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/docs/specs/man/jconsole.html", "jps": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/docs/specs/man/jps.html", @@ -77,9 +80,13 @@ "rfc-5246": "https://www.ietf.org/rfc/rfc5246.html", "rfc-8446": "https://www.ietf.org/rfc/rfc8446.html", "rfc-8017": "https://www.ietf.org/rfc/rfc8017.html", + "rfc-8032": "https://tools.ietf.org/html/rfc8032", + "trec-x509": "https://www.itu.int/rec/T-REC-X.509/en", + "dss": "https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf", + "rfc-1422": "https://www.ietf.org/rfc/rfc1422.html", "ANSI-20X9.62": "https://standards.globalspec.com/std/1955141/ANSI%20X9.62", - "ide-eclipse": "https://www.eclipse.org/", + "ide-eclipse": "https://www.eclipseide.org/", "ide-netbeans": "https://netbeans.apache.org/", "ide-intellij": "https://www.jetbrains.com/idea/", @@ -121,6 +128,8 @@ "Object.wait(long)": "java.base/java/lang/Object.html#wait(long)", "Object.wait(long,int)": "java.base/java/lang/Object.html#wait(long,int)", + "ClassLoader": "java.base/java/lang/ClassLoader.html", + "NullPointerException": "java.base/java/lang/NullPointerException.html", "Override": "java.base/java/lang/Override.html", @@ -138,26 +147,17 @@ "Cloneable": "java.base/java/lang/Cloneable.html", "CloneNotSupportedException": "java.base/java/lang/CloneNotSupportedException.html", - "Class": "java.base/java/lang/Class.html", - "Class.getFields()": "java.base/java/lang/Class.html#getFields()", - "Class.getInterfaces()": "java.base/java/lang/Class.html#getInterfaces()", - "Class.getMethods()": "java.base/java/lang/Class.html#getMethods()", - "Class.getSimpleName()": "java.base/java/lang/Class.html#getSimpleName()", - "Class.getSuperclass()": "java.base/java/lang/Class.html#getSuperclass()", - "Class.isAnnotation()": "java.base/java/lang/Class.html#isAnnotation()", - "Class.isEnum()": "java.base/java/lang/Class.html#isEnum()", - "Class.isInterface()": "java.base/java/lang/Class.html#isInterface()", - "Record": "java.base/java/lang/Record.html", "System": "java.base/java/lang/System.html", "System.out": "java.base/java/lang/System.html#out", "System.arraycopy(java.lang.Object,int,java.lang.Object,int,int)": "java.base/java/lang/System.html#arraycopy(java.lang.Object,int,java.lang.Object,int,int)", + "System.console()": "java.base/java/lang/System.html#console()", "Long": "java.base/java/lang/Long.html", "Long.compareTo(Long)": "java.base/java/lang/Long.html#compareTo(java.lang.Long)", - "Long.compareUnsigned(int,int)": "java.base/java/lang/Long.html#compareUnsigned(int,int)", - "Long.divideUnsigned(int,int)": "java.base/java/lang/Long.html#divideUnsigned(int,int)", + "Long.compareUnsigned(long,long)": "java.base/java/lang/Long.html#compareUnsigned(long,long)", + "Long.divideUnsigned(long,long)": "java.base/java/lang/Long.html#divideUnsigned(long,long)", "Arrays": "java.base/java/util/Arrays.html", "Arrays.asList()": "java.base/java/util/Arrays.html#asList(T...)", @@ -237,10 +237,6 @@ "Math.toRadians(double)": "java.base/java/lang/Math.html#toRadians(double)", "Math": "java.base/java/lang/Math.html", - "Collections.sort(List)": "java.base/java/util/Collections.html#sort(java.util.List)", - "Collections.sort(List,comparator)": "java.base/java/util/Collections.html#sort(java.util.List,java.util.Comparator)", - "Collections.emptyList()": "java.base/java/util/Collections.html#emptyList()", - "File": "java.base/java/io/File.html", "File(String)": "java.base/java/io/File.html#%3Cinit%3E(java.lang.String)", "File(String,String)" : "java.base/java/io/File.html#%3Cinit%3E(java.lang.String,java.lang.String)", @@ -275,6 +271,7 @@ "File.toURI()" : "java.base/java/io/File.html#toURI()", "File.isHidden()" : "java.base/java/io/File.html#isHidden()", "File.list()" : "java.base/java/io/File.html#list()", + "File.listFiles()" : "java.base/java/io/File.html#listFiles()", "File.mkdir()" : "java.base/java/io/File.html#mkdir()", "File.mkdirs()" : "java.base/java/io/File.html#mkdirs()", "File.listRoots()" : "java.base/java/io/File.html#listRoots()", @@ -314,6 +311,8 @@ "Files.readAllLines(Path)": "java.base/java/nio/file/Files.html#readAllLines(java.nio.file.Path)", "Files.readAllLines(Path,Charset)": "java.base/java/nio/file/Files.html#readAllLines(java.nio.file.Path,java.nio.charset.Charset)", "Files.write(byte)": "java.base/java/nio/file/Files.html#write(java.nio.file.Path,byte%5B%5D,java.nio.file.OpenOption...)", + "Files.writeString()": "java.base/java/nio/file/Files.html#writeString(java.nio.file.Path,java.lang.CharSequence,java.nio.file.OpenOption...)", + "Files.write()": "java.base/java/nio/file/Files.html#write(java.nio.file.Path,byte%5B%5D,java.nio.file.OpenOption...)", "Files.write(Iterable)": "java.base/java/nio/file/Files.html#write(java.nio.file.Path,java.lang.Iterable,java.nio.charset.Charset,java.nio.file.OpenOption...)", "Files.newBufferedReader(CharSet)": "java.base/java/nio/file/Files.html#newBufferedReader(java.nio.file.Path,java.nio.charset.Charset)", "Files.newBufferedWriter()": "java.base/java/nio/file/Files.html#newBufferedWriter(java.nio.file.Path,java.nio.charset.Charset,java.nio.file.OpenOption...)", @@ -335,9 +334,16 @@ "Files.readSymbolicLink(Path)": "java.base/java/nio/file/Files.html#readSymbolicLink(java.nio.file.Path)", "Files.probeContentType(Path)": "java.base/java/nio/file/Files.html#probeContentType(java.nio.file.Path)", "Files.lines(Path)": "java.base/java/nio/file/Files.html#lines(java.nio.file.Path)", + "Files.list(Path)": "java.base/java/nio/file/Files.html#list(java.nio.file.Path)", + "Files.find(Path)": "java.base/java/nio/file/Files.html#find(java.nio.file.Path,int,java.util.function.BiPredicate,java.nio.file.FileVisitOption...)", + "Files.walk(Path)": "java.base/java/nio/file/Files.html#walk(java.nio.file.Path,java.nio.file.FileVisitOption...)", + "Files.walk(Path,depth)": "java.base/java/nio/file/Files.html#walk(java.nio.file.Path,int,java.nio.file.FileVisitOption...)", + "Files.walkFileTree(Path)": "java.base/java/nio/file/Files.html#walkFileTree(java.nio.file.Path,java.nio.file.FileVisitor)", "Files.copy(InputStream,Path,CopyOption)": "java.base/java/nio/file/Files.html#copy(java.io.InputStream,java.nio.file.Path,java.nio.file.CopyOption...)", "Files.copy(Path,OutputStream)": "java.base/java/nio/file/Files.html#copy(java.nio.file.Path,java.io.OutputStream)", "Files.copy(Path,Path,CopyOption)": "java.base/java/nio/file/Files.html#copy(java.nio.file.Path,java.nio.file.Path,java.nio.file.CopyOption...)", + "Files.readString(Path)": "java.base/java/nio/file/Files.html#readString(java.nio.file.Path)", + "Files.readAllBytes(Path)": "java.base/java/nio/file/Files.html#readAllBytes(java.nio.file.Path)", "Files.setAttribute(Path,String,Object,LinkOption)": "java.base/java/nio/file/Files.html#setAttribute(java.nio.file.Path,java.lang.String,java.lang.Object,java.nio.file.LinkOption...)", "Files.createTempFile(String,String,FileAttribute)": "java.base/java/nio/file/Files.html#createTempFile(java.lang.String,java.lang.String,java.nio.file.attribute.FileAttribute...)", "Files.createTempFile(Path,String,String,FileAttribute)": "java.base/java/nio/file/Files.html#createTempFile(java.nio.file.Path,java.lang.String,java.lang.String,java.nio.file.attribute.FileAttribute...)", @@ -407,9 +413,7 @@ "FileTime": "java.base/java/nio/file/attribute/FileTime.html", - "Iterable": "java.base/java/lang/Iterable.html", - "Iterable.forEach()": "java.base/java/lang/Iterable.html#forEach(java.util.function.Consumer)", - "Iterable.iterator()": "java.base/java/lang/Iterable.html#iterator()", + "Console": "java.base/java/io/Console.html", "Path": "java.base/java/nio/file/Path.html", "Path.toFile()": "java.base/java/nio/file/Path.html#toFile()", @@ -451,6 +455,8 @@ "Float.parseFloat(String)": "java.base/java/lang/Float.html#parseFloat(java.lang.String)", "Double": "java.base/java/lang/Double.html", + "Double.toString(double)": "java.base/java/lang/Double.html#Double.html#toString(double)", + "Double.parseDouble(String)": "java.base/java/lang/Double.html#parseDouble(java.lang.String)", "Double.compareTo(Double)": "java.base/java/lang/Double.html#compareTo(java.lang.Double)", "Character": "java.base/java/lang/Character.html", @@ -504,7 +510,9 @@ "String.regionMatches(int,String,int,int)": "java.base/java/lang/String.html#regionMatches(int,java.lang.String,int,int)", "String.equals(Object)": "java.base/java/lang/String.html#equals(java.lang.Object)", "String.regionMatches(boolean,int,String,int,int)": "java.base/java/lang/String.html#regionMatches(boolean,int,java.lang.String,int,int)", - "String.join(CharSequence,CharSequence)": "java.base/java/lang/String.html#join(java.lang.CharSequence,java.lang.CharSequence)", + "String.join(CharSequence,CharSequence)": "java.base/java/lang/String.html#join(java.lang.CharSequence,java.lang.CharSequence...)", + "String.join(CharSequence,Iterable)": "java.base/java/lang/String.html#join(java.lang.CharSequence,java.lang.Iterable)", + "String.valueOf(Object)": "java.base/java/lang/String.html#valueOf(java.lang.Object)", "StringIndexOutOfBoundsException": "java.base/java/lang/StringIndexOutOfBoundsException.html", @@ -513,8 +521,8 @@ "StringBuilder": "java.base/java/lang/StringBuilder.html", "StringBuilder()": "java.base/java/lang/StringBuilder.html#%3Cinit%3E()", - "StringBuilder(CharSequence)": "java/lang/StringBuilder.html#%3Cinit%3E(java.lang.CharSequence)", - "StringBuilder(String)": "java/lang/StringBuilder.html#%3Cinit%3E(java.lang.String)", + "StringBuilder(CharSequence)": "java.base/java/lang/StringBuilder.html#%3Cinit%3E(java.lang.CharSequence)", + "StringBuilder(String)": "java.base/java/lang/StringBuilder.html#%3Cinit%3E(java.lang.String)", "StringBuilder(int)": "java.base/java/lang/StringBuilder.html#%3Cinit%3E(int)", "StringBuilder.length()": "java.base/java/lang/StringBuilder.html#length()", "StringBuilder.capacity()": "java.base/java/lang/StringBuilder.html#capacity()", @@ -555,6 +563,7 @@ "Externalizable": "java.base/java/io/Externalizable.html", "Writer": "java.base/java/io/Writer.html", + "FileWriter": "java.base/java/io/FileWriter.html", "FileReader": "java.base/java/io/FileReader.html", "FilterWriter": "java.base/java/io/FilterWriter.html", "CharArrayReader": "java.base/java/io/CharArrayReader.html", @@ -566,6 +575,7 @@ "LineNumberReader": "java.base/java/io/LineNumberReader.html", "BufferedWriter": "java.base/java/io/BufferedWriter.html", + "BufferedWriter.write(int)": "java.base/java/io/BufferedWriter.html#write(int)", "BufferedWriter.close()": "java.base/java/io/BufferedWriter.html#close()", "FileNotFoundException": "java.base/java/io/FileNotFoundException.html", @@ -601,10 +611,14 @@ "BufferedOutputStream": "java.base/java/io/BufferedOutputStream.html", "PrintWriter": "java.base/java/io/PrintWriter.html", + "PrintWriter.printf()": "java.base/java/io/PrintWriter.html#printf(java.lang.String,java.lang.Object...)", "PrintWriter.println()": "java.base/java/io/PrintWriter.html#println()", - "GZIPInputStream": "java.base/java/io/GZIPInputStream.html", - "GZIPOutputStream": "java.base/java/io/GZIPOutputStream.html", + "ZipInputStream": "java.base/java/util/zip/ZipInputStream.html", + "ZipOutputStream": "java.base/java/util/zip/ZipOutputStream.html", + + "GZIPInputStream": "java.base/java/util/zip/GZIPInputStream.html", + "GZIPOutputStream": "java.base/java/util/zip/GZIPOutputStream.html", "DataOutputStream": "java.base/java/io/DataOutputStream.html", "DataOutputStream.writeBoolean(boolean)": "java.base/java/io/DataOutputStream#writeBoolean(boolean)", @@ -641,6 +655,8 @@ "InputStreamReader": "java.base/java/io/InputStreamReader.html", "OutputStreamWriter": "java.base/java/io/OutputStreamWriter.html", + "Scanner": "java.base/java/util/Scanner.html", + "Closeable": "java.base/java/io/Closeable.html", "Closeable.close()": "java.base/java/io/Closeable.html#close()", @@ -670,6 +686,8 @@ "SeekableByteChannel.write(ByteBuffer)": "java.base/java/nio/channels/SeekableByteChannel.html#write(java.nio.ByteBuffer)", "SeekableByteChannel.truncate(long)": "java.base/java/nio/channels/SeekableByteChannel.html#truncate(long)", + "ImageIO.read(URL)": "java.desktop/javax/imageio/ImageIO.html#read(java.net.URL)", + "URI": "java.base/java/net/URI.html", "LinkedList": "java.base/java/util/LinkedList.html", @@ -917,7 +935,8 @@ "TimeZone.toZoneId()": "java.base/java/util/TimeZone.html#toZoneId()", "DateTimeParseException": "java.base/java/time/format/DateTimeParseException.html", - "DateTimeException": "java.base/java/time/format/DateTimeException.html", + + "DateTimeException": "java.base/java/time/DateTimeException.html", "DecimalFormat": "java.base/java/text/DecimalFormat.html", @@ -949,6 +968,7 @@ "NegativeArraySizeException": "java.base/java/lang/NegativeArraySizeException.html", "EmptyStackException": "java.base/java/util/EmptyStackException.html", "RuntimeException": "java.base/java/lang/RuntimeException.html", + "ReflectiveOperationException": "java.base/java/lang/ReflectiveOperationException.html", "ArrayStoreException": "java.base/java/lang/ArrayStoreException.html", "ClassCastException": "java.base/java/lang/ClassCastException.html", @@ -1042,9 +1062,6 @@ "RetentionPolicy.RUNTIME": "java.base/java/lang/annotation/RetentionPolicy.html#RUNTIME", "RetentionPolicy.SOURCE": "java.base/java/lang/annotation/RetentionPolicy.html#SOURCE", "Target": "java.base/java/lang/annotation/Target.html", - "AnnotatedElement": "java.base/java/lang/reflect/AnnotatedElement.html", - "AnnotatedElement.getAnnotation(Class)": "java.base/java/lang/reflect/AnnotatedElement.html#getAnnotation(java.lang.Class)", - "AnnotatedElement.getAnnotationsByType(Class)": "java.base/java/lang/reflect/AnnotatedElement.html#getAnnotationsByType(java.lang.Class)", "IllegalArgumentException": "java.base/java/lang/IllegalArgumentException.html", "IllegalStateException": "java.base/java/lang/IllegalStateException.html", @@ -1054,9 +1071,20 @@ "ArrayDeque": "java.base/java/util/ArrayDeque.html", + "Iterator": "java.base/java/util/Iterator.html", + "Iterator.hasNext()": "java.base/java/util/Iterator.html#hasNext()", + "Iterator.next()": "java.base/java/util/Iterator.html#next()", + "Iterator.remove()": "java.base/java/util/Iterator.html#remove()", + "Iterator.forEachRemaining(Consumer)": "java.base/java/util/Iterator.html#forEachRemaining(java.util.function.Consumer)", + + "Iterable": "java.base/java/lang/Iterable.html", + "Iterable.forEach()": "java.base/java/lang/Iterable.html#forEach(java.util.function.Consumer)", + "Iterable.iterator()": "java.base/java/lang/Iterable.html#iterator()", + "Collection": "java.base/java/util/Collection.html", "Collection.removeIf(Predicate)": "java.base/java/util/Collection.html#removeIf(java.util.function.Predicate)", "Collection.add(E)": "java.base/java/util/Collection.html#add(E)", + "Collection.remove(Object)": "java.base/java/util/Collection.html#remove(java.lang.Object)", "Collection.addAll(Collection)": "java.base/java/util/Collection.html#addAll(java.util.Collection)", "Collection.clear()": "java.base/java/util/Collection.html#clear()", "Collection.contains(Object)": "java.base/java/util/Collection.html#contains(java.lang.Object)", @@ -1078,8 +1106,11 @@ "Collections.min(Collection)": "java.base/java/util/Collections.html#min(java.util.Collection)", "Collections.reverse(List)": "java.base/java/util/Collections.html#reverse(java.util.List)", "Collections.rotate(List,int)": "java.base/java/util/Collections.html#rotate(java.util.List,int)", - "Collections.shuffle(List)": "java.base/java/util/Collections.html#shuffle(java.util.List)", "Collections.swap(List,int,int)": "java.base/java/util/Collections.html#swap(java.util.List,int,int)", + "Collections.sort(List)": "java.base/java/util/Collections.html#sort(java.util.List)", + "Collections.shuffle(List)": "java.base/java/util/Collections.html#shuffle(java.util.List)", + "Collections.sort(List,comparator)": "java.base/java/util/Collections.html#sort(java.util.List,java.util.Comparator)", + "Collections.emptyList()": "java.base/java/util/Collections.html#emptyList()", "Deque": "java.base/java/util/Deque.html", "Deque.addFirst(E)": "java.base/java/util/Deque.html#addFirst(E)", @@ -1107,11 +1138,6 @@ "IdentityHashMap": "java.base/java/util/IdentityHashMap.html", - "Iterator": "java.base/java/util/Iterator.html", - "Iterator.hasNext()": "java.base/java/util/Iterator.html#hasNext()", - "Iterator.next()": "java.base/java/util/Iterator.html#next()", - "Iterator.remove()": "java.base/java/util/Iterator.html#remove()", - "LinkedHashMap": "java.base/java/util/LinkedHashMap.html", "List": "java.base/java/util/List.html", @@ -1192,6 +1218,9 @@ "NavigableMap.subMap(K,boolean,K,boolean)": "java.base/java/util/NavigableMap.html#subMap(K,boolean,K,boolean)", "NavigableMap.tailMap(K)": "java.base/java/util/NavigableMap.html#tailMap(K)", + "ConcurrentMap": "java.base/java/util/concurrent/ConcurrentMap.html", + "ConcurrentMap.putIfAbsent()": "java.base/java/util/concurrent/ConcurrentMap.html#putIfAbsent()", + "NavigableSet": "java.base/java/util/NavigableSet.html", "NavigableSet.ceiling(E)": "java.base/java/util/NavigableSet.html#ceiling(E)", "NavigableSet.descendingIterator()": "java.base/java/util/NavigableSet.html#descendingIterator()", @@ -1255,6 +1284,7 @@ "NumberFormatException": "java.base/java/lang/NumberFormatException.html", "OutOfMemoryError": "java.base/java/lang/OutOfMemoryError.html", + "Character.UnicodeBlock": "java.base/java/lang/Character.UnicodeBlock.html", "Character.toString(int)": "java.base/java/lang/Character.html#toString(int)", "Charset": "java.base/java/nio/charset/Charset.html", @@ -1391,6 +1421,7 @@ "Stream.toArray()": "java.base/java/util/stream/Stream.html#toArray()", "Stream.toList()": "java.base/java/util/stream/Stream.html#toList()", + "HttpClient": "java.net.http/java/net/http/HttpClient.html", "HttpClient.send(HttpRequest,HttpResponse.BodyHandler)": "java.net.http/java/net/http/HttpClient.html#send(java.net.http.HttpRequest,java.net.http.HttpResponse.BodyHandler)", "HttpResponse.BodyHandlers.ofLines()": "java.net.http/java/net/http/HttpResponse.BodyHandlers.html#ofLines()", @@ -1406,6 +1437,167 @@ "MessageDigest": "java.base/java/security/MessageDigest.html", "Security.getProviders()": "java.base/java/security/Security.html#getProviders()", "Security.addProvider(java.security.Provider)": "java.base/java/security/Security.html#addProvider(java.security.Provider)", - "Security.insertProviderAt": "java.base/java/security/Security.html#insertProviderAt(java.security.Provider,int)" - + "Security.insertProviderAt": "java.base/java/security/Security.html#insertProviderAt(java.security.Provider,int)", + "Certificate": "java.base/java/security/cert/Certificate.html", + "X509Certificate": "java.base/java/security/cert/X509Certificate.html", + "TrustAnchor": "java.base/java/security/cert/TrustAnchor.html", + "CertPathValidator": "java.base/java/security/cert/CertPathValidator.html", + "Security": "java.base/java/security/Security.html", + "FlightRecorderMXBean": "jdk.management.jfr/jdk/management/jfr/FlightRecorderMXBean.html", + "MBeanServerConnection": "java.management/javax/management/MBeanServerConnection.html", + "SimpleFileServer": "jdk.httpserver/com/sun/net/httpserver/SimpleFileServer", + + "Lookup": "java.base/java/lang/invoke/MethodHandles.Lookup.html", + "MethodType": "java.base/java/lang/invoke/MethodType.html", + "MethodHandles": "java.base/java/lang/invoke/MethodHandles.html", + "MethodHandles.Lookup.findVirtual(Class,String,MethodType)": "java.base/java/lang/invoke/MethodHandles.Lookup.html#findVirtual(java.lang.Class,java.lang.String,java.lang.invoke.MethodType)", + "MethodHandles.Lookup.findStatic(Class,String,MethodType)": "java.base/java/lang/invoke/MethodHandles.Lookup.html#findStatic(java.lang.Class,java.lang.String,java.lang.invoke.MethodType)", + "MethodHandles.Lookup.findConstructor(Class,MethodType)": "java.base/java/lang/invoke/MethodHandles.Lookup.html#findConstructor(java.lang.Class,java.lang.invoke.MethodType)", + "MethodHandles.Lookup.findGetter(Class,String,Class)": "java.base/java/lang/invoke/MethodHandles.Lookup.html#findGetter(java.lang.Class,java.lang.String,java.lang.Class)", + "MethodHandles.Lookup.findSetter(Class,String,Class)": "java.base/java/lang/invoke/MethodHandles.Lookup.html#findSetter(java.lang.Class,java.lang.String,java.lang.Class)", + "MethodHandles.Lookup.findStaticGetter(Class,String,Class)": "java.base/java/lang/invoke/MethodHandles.Lookup.html#findStaticGetter(java.lang.Class,java.lang.String,java.lang.Class)", + "MethodHandles.Lookup.findStaticSetter(Class,String,Class)": "java.base/java/lang/invoke/MethodHandles.Lookup.html#findStaticSetter(java.lang.Class,java.lang.String,java.lang.Class)", + "MethodHandles.Lookup.findVarHandle(Class,String,Class)": "java.base/java/lang/invoke/MethodHandles.Lookup.html#findVarHandle(java.lang.Class,java.lang.String,java.lang.Class)", + "MethodHandles.Lookup.findStaticVarHandle(Class,String,Class)": "java.base/java/lang/invoke/MethodHandles.Lookup.html#findStaticVarHandle(java.lang.Class,java.lang.String,java.lang.Class)", + "MethodHandles.Lookup.unreflect(Method)": "java.base/java/lang/invoke/MethodHandles.Lookup.html#unreflect(java.lang.reflect.Method)", + "MethodHandles.publicLookup()": "java.base/java/lang/invoke/MethodHandles.html#publicLookup()", + "MethodHandles.tryFinally(MethodHandle,MethodHandle)": "java.base/java/lang/invoke/MethodHandles.html#tryFinally(java.lang.invoke.MethodHandle,java.lang.invoke.MethodHandle)", + "MethodHandles.permuteArguments(MethodHandle,MethodType,int...)": "java.base/java/lang/invoke/MethodHandles.html#permuteArguments(java.lang.invoke.MethodHandle,java.lang.invoke.MethodType,int...)", + "MethodHandles.insertArguments(MethodHandle,int,Object...)": "java.base/java/lang/invoke/MethodHandles.html#insertArguments(java.lang.invoke.MethodHandle,int,java.lang.Object...)", + "MethodHandles.filterArguments(MethodHandle,int,MethodHandle...)": "java.base/java/lang/invoke/MethodHandles.html#filterArguments(java.lang.invoke.MethodHandle,int,java.lang.invoke.MethodHandle...)", + "MethodHandles.foldArguments(MethodHandle,int,MethodHandle)": "java.base/java/lang/invoke/MethodHandles.html#foldArguments(java.lang.invoke.MethodHandle,int,java.lang.invoke.MethodHandle)", + "MethodHandles.reflectAs(Class,MethodHandle)": "java.base/java/lang/invoke/MethodHandles.html#reflectAs(java.lang.Class,java.lang.invoke.MethodHandle)", + "MethodHandles.arrayConstructor(Class)": "java.base/java/lang/invoke/MethodHandles.html#arrayConstructor(java.lang.Class)", + "MethodHandles.arrayElementSetter(Class)": "java.base/java/lang/invoke/MethodHandles.html#arrayElementSetter(java.lang.Class)", + "MethodHandles.arrayElementGetter(Class)": "java.base/java/lang/invoke/MethodHandles.html#arrayElementGetter(java.lang.Class)", + "MethodHandles.catchException(MethodHandle,Class,MethodHandle)": "java.base/java/lang/invoke/MethodHandles.html#catchException(java.lang.invoke.MethodHandle,java.lang.Class,java.lang.invoke.MethodHandle)", + "MethodHandles.arrayLength(Class)": "java.base/java/lang/invoke/MethodHandles.html#arrayLength(java.lang.Class)", + "MethodHandle.invoke(Object...)": "java.base/java/lang/invoke/MethodHandle.html#invoke(java.lang.Object...)", + "MethodHandle.invokeExact(Object...)": "java.base/java/lang/invoke/MethodHandle.html#invokeExact(java.lang.Object...)", + "MethodHandle.invokeWithArguments(Object...)": "java.base/java/lang/invoke/MethodHandle.html#invokeWithArguments(java.lang.Object...)", + "MethodHandle.asType(MethodType)": "java.base/java/lang/invoke/MethodHandle.html#asType(java.lang.invoke.MethodType)", + "VarHandle": "java.base/java/lang/invoke/VarHandle.html", + "WrongMethodTypeException": "java.base/java/lang/invoke/WrongMethodTypeException.html", + + "ReflectPermission": "java.base/java/lang/reflect/ReflectPermission.html", + + "java.lang.reflect": "java.base/java/lang/reflect/package-summary.html", + + "Class": "java.base/java/lang/Class.html", + "Class.getFields()": "java.base/java/lang/Class.html#getFields()", + "Class.getInterfaces()": "java.base/java/lang/Class.html#getInterfaces()", + "Class.getMethods()": "java.base/java/lang/Class.html#getMethods()", + "Class.getSimpleName()": "java.base/java/lang/Class.html#getSimpleName()", + "Class.getSuperclass()": "java.base/java/lang/Class.html#getSuperclass()", + "Class.isAnnotation()": "java.base/java/lang/Class.html#isAnnotation()", + "Class.isEnum()": "java.base/java/lang/Class.html#isEnum()", + "Class.isInterface()": "java.base/java/lang/Class.html#isInterface()", + "Class.toString()": "java.base/java/lang/Class.html#toString()", + "Class.forName(String)": "java.base/java/lang/Class.html#forName(java.lang.String)", + "Class.getName()": "java.base/java/lang/Class.html#getName()", + "Class.getCanonicalName()": "java.base/java/lang/Class.html#getCanonicalName()", + "Class.getTypeName()": "java.base/java/lang/Class.html#getTypeName()", + "Class.forPrimitiveName()": "java.base/java/lang/Class.html#forPrimitiveName()", + "Class.getClasses()": "java.base/java/lang/Class.html#getClasses()", + "Class.getEnclosingClass()": "java.base/java/lang/Class.html#getEnclosingClass()", + "Class.getDeclaredClasses()": "java.base/java/lang/Class.html#getDeclaredClasses()", + "Class.getDeclaringClass()": "java.base/java/lang/Class.html#getDeclaringClass()", + "Class.getModifiers()": "java.base/java/lang/Class.html#getModifiers()", + "Class.getDeclaredField(String)": "java.base/java/lang/Class.html#getDeclaredField(java.lang.String)", + "Class.getField(String)": "java.base/java/lang/Class.html#getField(java.lang.String)", + "Class.getDeclaredFields()": "java.base/java/lang/Class.html#getDeclaredFields()", + "Class.getDeclaredMethod(String,Class...)": "java.base/java/lang/Class.html#getDeclaredMethod(java.lang.String,java.lang.Class...)", + "Class.getMethod(String,Class...)": "java.base/java/lang/Class.html#getMethod(java.lang.String,java.lang.Class...)", + "Class.getDeclaredMethods()": "java.base/java/lang/Class.html#getDeclaredMethods()", + "Class.getDeclaredConstructor(Class...)": "java.base/java/lang/Class.html#getDeclaredConstructor(java.lang.Class...)", + "Class.getConstructor(Class...)": "java.base/java/lang/Class.html#getConstructor(java.lang.Class...)", + "Class.getDeclaredConstructors()": "java.base/java/lang/Class.html#getDeclaredConstructors()", + "Class.getConstructors()": "java.base/java/lang/Class.html#getConstructors()", + "Class.newInstance()": "java.base/java/lang/Class.html#newInstance()", + "Class.isRecord()": "java.base/java/lang/Class.html#isRecord()", + "Class.getEnumConstants()": "java.base/java/lang/Class.html#getEnumConstants()", + "Class.isArray()": "java.base/java/lang/Class.html#isArray()", + "Class.getComponentType()": "java.base/java/lang/Class.html#getComponentType()", + + "Void": "java.base/java/lang/Void.html", + "Void.TYPE": "java.base/java/lang/Void.html#TYPE", + + "Type": "java.base/java/lang/reflect/Type.html", + "Type.getTypeName()": "java.base/java/lang/reflect/Type.html#getTypeName()", + + "Member": "java.base/java/lang/reflect/Member.html", + "Member.accessFlags()": "java.base/java/lang/reflect/Member.html#accessFlags()", + "Member.getDeclaringClass()": "java.base/java/lang/reflect/Member.html#getDeclaringClass()", + + "Field": "java.base/java/lang/reflect/Field.html", + "Field.getFields()": "java.base/java/lang/reflect/Field.html#getFields()", + "Field.getType()": "java.base/java/lang/reflect/Field.html#getType()", + "Field.getGenericType()": "java.base/java/lang/reflect/Field.html#getGenericType()", + "Field.getModifiers()": "java.base/java/lang/reflect/Field.html#getModifiers()", + "Field.accessFlags()": "java.base/java/lang/reflect/Field.html#accessFlags()", + "Field.get(Object)": "java.base/java/lang/reflect/Field.html#get(java.lang.Object)", + "Field.set(Object,Object)": "java.base/java/lang/reflect/Field.html#set(java.lang.Object,java.lang.Object)", + "Field.setInt(Object,int)": "java.base/java/lang/reflect/Field.html#setInt(java.lang.Object,int)", + "Field.getInt(Object)": "java.base/java/lang/reflect/Field.html#getInt(java.lang.Object)", + "Field.setAccessible()": "java.base/java/lang/reflect/Field.html#setAccessible()", + "Field.isEnumConstant()": "java.base/java/lang/reflect/Field.html#isEnumConstant()", + + "Method": "java.base/java/lang/reflect/Method.html", + "Method.invoke(Object,Object...)": "java.base/java/lang/reflect/Method.html#invoke(java.lang.Object,java.lang.Object...)", + "Method.invoke()": "java.base/java/lang/reflect/Method.html#invoke()", + "Method.getReturnType()": "java.base/java/lang/reflect/Method.html#getReturnType()", + "Method.getGenericReturnType()": "java.base/java/lang/reflect/Method.html#getGenericReturnType()", + "Method.getGenericExceptionTypes()": "java.base/java/lang/reflect/Method.html#getGenericExceptionTypes()", + "Method.getModifiers()": "java.base/java/lang/reflect/Method.html#getModifiers()", + "Method.setAccessible(boolean)": "java.base/java/lang/reflect/Method.html#setAccessible(boolean)", + + "Constructor": "java.base/java/lang/reflect/Constructor.html", + "Constructor.newInstance()": "java.base/java/lang/reflect/Constructor.html#newInstance()", + "Constructor.getParameterTypes()": "java.base/java/lang/reflect/Constructor.html#getParameterTypes()", + "Constructor.getGenericParameterTypes()": "java.base/java/lang/reflect/Constructor.html#getGenericParameterTypes()", + + "RecordComponent": "java.base/java/lang/reflect/RecordComponent.html", + "RecordComponent.getDeclaringRecord()": "java.base/java/lang/reflect/RecordComponent.html#getDeclaringRecord()", + "RecordComponent.getAccessor()": "java.base/java/lang/reflect/RecordComponent.html#getAccessor()", + "RecordComponent.getName()": "java.base/java/lang/reflect/RecordComponent.html#getName()", + "RecordComponent.getType()": "java.base/java/lang/reflect/RecordComponent.html#getType()", + "RecordComponent.getGenericType()": "java.base/java/lang/reflect/RecordComponent.html#getGenericType()", + + "Array": "java.base/java/lang/reflect/Array.html", + "Array.newInstance()": "java.base/java/lang/reflect/Array.html#newInstance()", + "Array.newInstance(Class,int)": "java.base/java/lang/reflect/Array.html#newInstance(java.lang.Class,int)", + "Array.getLength(Object)": "java.base/java/lang/reflect/Array.html#getLength(java.lang.Object)", + "Array.set(Object,int,Object)": "java.base/java/lang/reflect/Array.html#set(java.lang.Object,int,java.lang.Object)", + "Array.get(Object,int)": "java.base/java/lang/reflect/Array.html#set(java.lang.Object,int)", + "Array.setDouble(Object,int,double)": "java.base/java/lang/reflect/Array.html#setDouble(java.lang.Object,int,double)", + "Array.getDouble(Object,int)": "java.base/java/lang/reflect/Array.html#getDouble(java.lang.Object,int)", + + "AnnotatedElement": "java.base/java/lang/reflect/AnnotatedElement.html", + "AnnotatedElement.getDeclaredAnnotations()": "java.base/java/lang/reflect/AnnotatedElement.html#getDeclaredAnnotations()", + "AnnotatedElement.getAnnotations()": "java.base/java/lang/reflect/AnnotatedElement.html#getAnnotations()", + "AnnotatedElement.isAnnotationPresent(Class)": "java.base/java/lang/reflect/AnnotatedElement.html#isAnnotationPresent(java.lang.Class)", + "AnnotatedElement.getAnnotation(Class)": "java.base/java/lang/reflect/AnnotatedElement.html#getAnnotation(java.lang.Class)", + "AnnotatedElement.getDeclaredAnnotation(Class)": "java.base/java/lang/reflect/AnnotatedElement.html#getDeclaredAnnotation(java.lang.Class)", + "AnnotatedElement.getAnnotationsByType(Class)": "java.base/java/lang/reflect/AnnotatedElement.html#getAnnotationsByType(java.lang.Class)", + + "AnnotatedType": "java.base/java/lang/reflect/AnnotatedType.html", + + "Proxy": "java.base/java/lang/reflect/Proxy.html", + + "Executable": "java.base/java/lang/reflect/Executable.html", + "Executable.getParameters()": "java.base/java/lang/reflect/Executable.html#getParameters()", + + "AccessFlag": "java.base/java/lang/reflect/AccessFlag.html", + + "Modifier": "java.base/java/lang/reflect/Modifier.html", + + "ClassNotFoundException": "java.base/java/lang/ClassNotFoundException.html", + "InstantiationException": "java.base/java/lang/InstantiationException.html", + "InvocationTargetException": "java.base/java/lang/reflect/InvocationTargetException.html", + "InvocationTargetException.getTargetException()": "java.base/java/lang/reflect/InvocationTargetException.html#getTargetException()", + + "jdk.jshell": "jdk.jshell/module-summary.html", + + "jdeps-man": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/docs/specs/man/jdeps.html#options-to-filter-classes-to-be-analyzed", + "jlink-man": "https://docs.oracle.com/en/java/javase/@@CURRENT_RELEASE@@/docs/specs/man/jlink.html" } \ No newline at end of file diff --git a/app/data/javafxdoc.json b/app/data/javafxdoc.json index 091e54c..dfc5f19 100644 --- a/app/data/javafxdoc.json +++ b/app/data/javafxdoc.json @@ -1,8 +1,8 @@ { - "current_release": "19", + "current_release": "23", + "release_uuid": "343fae14109c42b09c0437fc90a10d4b", - "javafx-documentation": "https://openjfx.io/javadoc/@@CURRENT_RELEASE@@/", - "javafxdoc_root": "https://openjfx.io/javadoc/@@CURRENT_RELEASE@@/", + "javafxdoc_root": "https://download.java.net/java/GA/javafx@@CURRENT_RELEASE@@/@@RELEASE_UUID@@/docs/api/", "Application": "javafx.graphics/javafx/application/Application.html", @@ -53,6 +53,28 @@ "SortedList": "javafx.base/javafx/collections/transformation/SortedList.html", "FXMLLoader": "javafx.fxml/javafx/fxml/FXMLLoader.html", - "Initializable": "javafx.fxml/javafx/fxml/Initializable.html" - + "Initializable": "javafx.fxml/javafx/fxml/Initializable.html", + "AnimationPackageSummary": "javafx.graphics/javafx/animation/package-summary.html", + "WritableValue": "javafx.base/javafx/beans/value/WritableValue.html", + "Animation": "javafx.graphics/javafx/animation/Animation.html", + "Duration": "javafx.base/javafx/util/Duration.html", + "Node": "javafx.graphics/javafx/scene/Node.html", + "FadeTransition": "javafx.graphics/javafx/animation/FadeTransition.html", + "FillTransition": "javafx.graphics/javafx/animation/FillTransition.html", + "PathTransition": "javafx.graphics/javafx/animation/PathTransition.html", + "ScaleTransition": "javafx.graphics/javafx/animation/ScaleTransition.html", + "StrokeTransition": "javafx.graphics/javafx/animation/StrokeTransition.html", + "TranslateTransition": "javafx.graphics/javafx/animation/TranslateTransition.html", + "Timeline": "javafx.graphics/javafx/animation/Timeline.html", + "KeyFrame": "javafx.graphics/javafx/animation/KeyFrame.html", + "KeyValue": "javafx.graphics/javafx/animation/KeyValue.html", + "Interpolator": "javafx.graphics/javafx/animation/Interpolator.html", + "Interpolator.DISCRETE": "javafx.graphics/javafx/animation/Interpolator.html#DISCRETE", + "Interpolator.LINEAR": "javafx.graphics/javafx/animation/Interpolator.html#LINEAR", + "Interpolator.EASE_IN": "javafx.graphics/javafx/animation/Interpolator.html#EASE_IN", + "Interpolator.EASE_OUT": "javafx.graphics/javafx/animation/Interpolator.html#EASE_OUT", + "Interpolator.EASE_BOTH": "javafx.graphics/javafx/animation/Interpolator.html#EASE_BOTH", + "Interpolator.SPLINE": "javafx.graphics/javafx/animation/Interpolator.html#SPLINE(double,double,double,double)", + "Interpolator.TANGENT": "javafx.graphics/javafx/animation/Interpolator.html#TANGENT(javafx.util.Duration,double,javafx.util.Duration,double)", + "AnimationTimer": "javafx.graphics/javafx/animation/AnimationTimer.html" } \ No newline at end of file diff --git a/app/data/jep.json b/app/data/jep.json new file mode 100644 index 0000000..80bcff7 --- /dev/null +++ b/app/data/jep.json @@ -0,0 +1,73 @@ +{ + "root": "https://openjdk.org/jeps/", + + "1": "JDK Enhancement-Proposal & Roadmap Process", + "11": "Incubator Modules", + "12": "Preview Features", + + "110": "HTTP/2 Client (Incubator)", + + "220": "Modular Run-Time Images", + "225": "Javadoc Search", + "286": "Local-Variable Type Inference", + + "310": "Application Class-Data Sharing", + "321": "HTTP Client", + "325": "Switch Expressions (Preview)", + "326": "Raw String Literals (Preview)", + "328": "Flight Recorder", + "333": "ZGC: A Scalable Low-Latency Garbage Collector (Experimental)", + "345": "NUMA-Aware Memory Allocation for G1", + "346": "Promptly Return Unused Committed Memory from G1", + "349": "JFR Event Streaming", + "354": "Switch Expressions (Second Preview)", + "357": "Migrate from Mercurial to Git", + "358": "Helpful NullPointerExceptions", + "361": "Switch Expressions", + "363": "Remove the Concurrent Mark Sweep (CMS) Garbage Collector", + "369": "Migrate to GitHub", + "372": "Remove the Nashorn JavaScript Engine", + "374": "Disable and Deprecate Biased Locking", + "376": "ZGC: Concurrent Thread-Stack Processing", + "377": "ZGC: A Scalable Low-Latency Garbage Collector (Production)", + "384": "Records (Second Preview)", + "387": "Elastic Metaspace", + "391": "macOS/AArch64 Port", + "395": "Records", + "397": "Sealed Classes (Second Preview)", + "398": "Deprecate the Applet for Removal", + + "400": "UTF-8 by Default", + "407": "Remove RMI Activation", + "408": "Simple Web Server", + "409": "Sealed Classes", + "411": "Deprecate the Security Manager for Removal", + "413": "Code Snippets in Java API Documentation", + "415": "Context-Specific Deserialization Filters", + "416": "Reimplement Core Reflection with Method Handle", + "418": "Internet-Address Resolution API", + "421": "Deprecate Finalization for Removal", + "445": { + "title": "Implicitly Declared Classes and Instance Main Methods (Second Preview)", + "status": "preview", + "version": "22" + }, + "460": { + "title": "Vector API (Seventh Incubator)", + "status": "incubator", + "version": "22" + }, + "463": { + "title": "Implicitly Declared Classes and Instance Main Methods (Second Preview)", + "status": "preview", + "version": "22" + }, + + "481": { + "title": "Scoped Values (Third Preview)", + "status": "preview", + "version": "22" + }, + + "8300604": "JEP draft: Preview Features: A Look Back, and A Look Ahead" +} \ No newline at end of file diff --git a/app/pages/future/innovation/index.md b/app/pages/future/innovation/index.md index e86051e..8825b54 100644 --- a/app/pages/future/innovation/index.md +++ b/app/pages/future/innovation/index.md @@ -7,11 +7,11 @@ subheader_select: innovation ## Amber -The goal of Project Amber is to explore and incubate smaller, productivity-oriented Java language features that have been accepted as candidate JEPs under the [OpenJDK JEP process](https://openjdk.java.net/jeps/1). This Project is sponsored by the [Compiler Group](https://openjdk.java.net/groups/compiler/). +The goal of Project Amber is to explore and incubate smaller, productivity-oriented Java language features that have been accepted as candidate JEPs under [JDK Enhancement-Proposal & Roadmap Process](jep:1). This Project is sponsored by the [Compiler Group](https://openjdk.org/groups/compiler/). -Most Project Amber features go through at least one round of Preview before becoming an official part of Java SE. See [JEP 12](https://openjdk.java.net/jeps/12) for an explanation of the Preview process, and [our tutorial](id:new_features.using_preview) on how to use preview features. For a given feature, there are separate JEPs for each round of preview and for final standardization. +Most Project Amber features go through at least one round of Preview before becoming an official part of Java SE. See [Preview Features](jep:12) for an explanation of the Preview process, and [our tutorial](id:new_features.using_preview) on how to use preview features. For a given feature, there are separate JEPs for each round of preview and for final standardization. -Learn more at Project Amber's [Wiki](https://openjdk.java.net/projects/amber/), as well as Inside.java's [Amber page](https://inside.java/tag/amber). +Learn more at Project Amber's [Wiki](https://openjdk.org/projects/amber/), as well as Inside.java's [Amber page](https://inside.java/tag/amber). ## Loom @@ -23,7 +23,7 @@ Project Loom is to intended to explore, incubate and deliver Java VM features an This OpenJDK project is sponsored by the HotSpot Group. -Learn more at Project Loom's [Wiki](https://wiki.openjdk.java.net/display/loom/Main), as well as Inside.java's [Loom page](https://inside.java/tag/loom). +Learn more at Project Loom's [Wiki](https://wiki.openjdk.org/display/loom/Main), as well as Inside.java's [Loom page](https://inside.java/tag/loom). ## Panama @@ -43,7 +43,7 @@ To this end, Project Panama will include most or all of these components: * tooling or wrapper interposition for safety * exploratory work with difficult-to-integrate native libraries -Learn more at Project Panama's [Wiki](https://openjdk.java.net/projects/panama/), as well as Inside.java's [Panama page](https://inside.java/tag/panama). +Learn more at Project Panama's [Wiki](https://openjdk.org/projects/panama/), as well as Inside.java's [Panama page](https://inside.java/tag/panama). ## Valhalla @@ -58,7 +58,7 @@ The three main goals are: A number of people describe Valhalla recently as being "primarily about performance". While it is understandable why people might come to that conclusion -- many of the motivations for Valhalla are, in fact, rooted in performance considerations -- this characterization misses something very important. Yes, performance is an important part of the story -- but so are safety, abstraction, encapsulation, expressiveness, maintainability, and compatible library evolution. -Learn more at the Valhalla Project [Wiki](https://wiki.openjdk.java.net/display/valhalla/Main), as well as Inside.java's [Valhalla page](https://inside.java/tag/valhalla). +Learn more at the Valhalla Project [Wiki](https://wiki.openjdk.org/display/valhalla/Main), as well as Inside.java's [Valhalla page](https://inside.java/tag/valhalla). ## ZGC @@ -81,5 +81,5 @@ At a glance, ZGC is: At its core, ZGC is a concurrent garbage collector, meaning all heavy lifting work is done while Java threads continue to execute. This greatly limits the impact garbage collection will have on your application's response time. -Learn more at the ZGC [Wiki](https://wiki.openjdk.java.net/display/zgc/Main), as well as Inside.java's [GC page](https://inside.java/tag/gc). +Learn more at the ZGC [Wiki](https://wiki.openjdk.org/display/zgc/Main), as well as Inside.java's [GC page](https://inside.java/tag/gc). diff --git a/app/pages/learn/01_tutorial/01_your-first-java-app/02_building-with-intellij-idea.md b/app/pages/learn/01_tutorial/01_your-first-java-app/02_building-with-intellij-idea.md new file mode 100644 index 0000000..18d4958 --- /dev/null +++ b/app/pages/learn/01_tutorial/01_your-first-java-app/02_building-with-intellij-idea.md @@ -0,0 +1,292 @@ +--- +id: first_app.intellij-idea +title: Building a Java application in IntelliJ IDEA +slug: learn/intellij-idea +type: tutorial +category: start +layout: learn/tutorial.html +subheader_select: tutorials +main_css_id: learn +more_learning: + youtube: + - H_XxH66lm3U + - 70_B2DyM8mU +toc: +- Overview {overview} +- Installing IntelliJ IDEA {install} +- Creating a new project {new} +- Writing and editing code {edit} +- Running your application {run} +- Testing {test} +- Debugging {debug} +- Refactoring code {refactor} +- Documenting code {document} +- Searching and navigating {navigation} +- Summary {summary} +description: "Learn how to code, run, test, debug and document a Java application in IntelliJ IDEA." +last_update: 2024-04-22 +author: ["MaritvanDijk"] +--- + +  +## Overview + +An IDE (Integrated Development Environment) allows you to quickly create applications by combining a source-code editor with the ability to compile and run your code, as well as integration with build, test and debug tools, version control systems, and so on. Finally, an IDE will let you search and navigate your codebase in ways your file system won’t. + +One of the [most widely used integrated development environments (IDEs)](https://www.jetbrains.com/lp/devecosystem-2023/java/#java_ide) for Java is IntelliJ IDEA. Its user-friendly interface, rich feature set, and vast ecosystem make it an ideal environment for beginners to learn and grow as developers. In this tutorial you’ll learn how to use some of its features to simplify your development process and accelerate your learning curve with Java programming. + +  +## Installing IntelliJ IDEA + +To install IntelliJ IDEA, download the version you want to use from the [IntelliJ IDEA website](https://www.jetbrains.com/idea/) and follow the instructions. +Note that IntelliJ IDEA is available in two editions: +- **_IntelliJ IDEA Community Edition_** - free and open-source. It provides all the basic features for Java development. +- **_IntelliJ IDEA Ultimate_** - commercial, distributed with a 30-day trial period. It provides additional tools and features for web and enterprise development. + +For this tutorial, you can download the Community Edition. For more information on installing IntelliJ IDEA on your OS, see [the documentation](https://www.jetbrains.com/help/idea/installation-guide.html#standalone). + +When you launch IntelliJ IDEA for the first time, you’ll see the **Welcome** screen. From here, you can create a new project, open an existing project, or get a project from a version control system (like GitHub). + +[![Welcome screen](/assets/images/intellij-idea/welcome-screen.png)](/assets/images/intellij-idea/welcome-screen.png) + +To start working with Java, you will need to install a JDK. You can do this yourself, as described in [Getting Started with Java](https://dev.java/learn/getting-started/#setting-up-jdk), or you can do so in IntelliJ IDEA when creating a new project, without having to switch from your IDE and other tools (such as your browser, file system, etc.) to download and configure a JDK. + +  +## Creating a new project + +We can create a new project from the **Welcome** screen, or we can go to **File | New | Project** in the main menu. + +[![New Project menu](/assets/images/intellij-idea/new-project-menu.png)](/assets/images/intellij-idea/new-project-menu.png) + +In the **New Project** wizard, make sure that **Java** is selected on the left-hand side, and give your project a name (for example, `java-demo`). +Next, we'll select a **Build system**. IntelliJ IDEA supports both Maven and Gradle; the most used build systems for Java. A build tool, like Maven or Gradle, helps you to build your project, and manage any dependencies (like additional libraries) that you want to use in your Java code. Using a build tool will also make it easier to share your application and build it on a different machine. If you don't want to use either, you can use the IntelliJ build system. In this tutorial, let’s create a Maven project. + +[![New Project](/assets/images/intellij-idea/new-project.png)](/assets/images/intellij-idea/new-project.png) + +To develop a Java application, we’ll need a JDK. If the necessary JDK is already defined in IntelliJ IDEA, select it from the **JDK** list. + +If the JDK is installed on your computer, but not defined in the IDE, select the option **Add JDK** from the list and specify the path to the JDK home directory (for example, `/Library/Java/JavaVirtualMachines/jdk-21.0.2.jdk`). + +If you don't have the necessary JDK on your computer, select **Download JDK**. In the **Download JDK** popup, specify the JDK vendor (for example, Oracle OpenJDK) and version, change the installation path if required, and click **Download**. + +[![Download JDK popup](/assets/images/intellij-idea/download-jdk-popup.png)](/assets/images/intellij-idea/download-jdk-popup.png) + +If you select **Add sample code**, a `Main` class which prints out “Hello World” will be added to your project. Leave it unchecked, so we can add our own later. + +Once you’re satisfied with your input in the **New Project** popup, click **Create**. + +IntelliJ IDEA will create a project for you, with a basic `pom.xml` and a default directory structure for a Maven project with the source folder defined. The `pom.xml` is a file that contains information about the project and configuration details used by Maven to build the project. For more information, see [the Maven documentation](https://maven.apache.org/guides/introduction/introduction-to-the-pom.html). + +[![Project](/assets/images/intellij-idea/project.png)](/assets/images/intellij-idea/project.png) + +We can see the project structure in the [Project tool window](https://www.jetbrains.com/help/idea/project-tool-window.html) on the left. The `.idea` folder contains your project configuration. The `src` folder contains your code. When you expand that folder, you'll see that IntelliJ IDEA has created a `main` folder for your Java code and a `test` folder for your tests. + +Let’s add some code by creating a new class. +* In the **Project** tool window on the left, select the directory `src/main/java`. +* To add a new Java class, right-click the **Project** tool window to open the context menu and select **New | Java class**. +* Name this class `HelloWorld`. + +[![New Java class](/assets/images/intellij-idea/new-java-class.png)](/assets/images/intellij-idea/new-java-class.png) + +--- +**IDE TIP** + +You can add a new Java file using the shortcut **⌘N** (on macOS) or **Alt+Insert** (on Windows/Linux). + +--- + +  +## Writing and editing code + +The entrypoint to execute your `HelloWorld` Java program is the main method. Add the main method by typing: +```java +public static void main(String[] args) { + +} +``` +I recommend that you type the code, rather than pasting, as that will help you get more familiar with the syntax. + +To keep things simple, let's make our program print `Hello World!` to the console and move the cursor to a new line, by adding `System.out.println("Hello World!");` to the method body: + +```java +public static void main(String[] args) { + System.out.println("Hello World!"); +} +``` + +As you start typing, you’ll notice that IntelliJ IDEA gives you [code completion](https://www.jetbrains.com/help/idea/auto-completing-code.html). It will help you complete the names of classes, methods, fields, and keywords, and other types of completion. Use the arrow keys to select the option you want from the list, and the **Return** (on macOS) or **Enter** (on Windows/linux) key to apply your selection. + +[![HelloWorld](/assets/images/intellij-idea/hello-world.gif)](/assets/images/intellij-idea/hello-world.gif) + +IntelliJ IDEA will show you if you’ve typed or selected something that doesn’t compile, or if it sees any other problems. If you press **Alt+Enter** it will offer options to fix the problem. You can use **F2** to move to the next problem, and **Shift+F2** to go to the previous problem. IntelliJ IDEA will help you make sure that your syntax is correct and your code can be compiled, by offering suggestions that are context-sensitive. + +[![Suggestions](/assets/images/intellij-idea/alt-enter.png)](/assets/images/intellij-idea/alt-enter.png) + +To speed up development, we can also [generate code](https://www.jetbrains.com/help/idea/generating-code.html). IntelliJ IDEA can generate constructors, getters and setters, `toString()`, `equals()` and `hashCode()` methods, and more. + +[![Generate code](/assets/images/intellij-idea/generate-code.png)](/assets/images/intellij-idea/generate-code.png) + +IntelliJ IDEA will manage the formatting of your code as you write it. If needed, you can explicitly reformat the code, using the shortcut **⌘⌥L** (on macOS) or **Ctrl+Alt+L** (on Windows/Linux). + +  +## Running your application + +A major benefit of using an IDE is that you can directly run your code without having to first manually compile it on the command line. + +You can run the `HelloWorld` application directly from the editor, by clicking the green Run button in the gutter near the class declaration, or using the shortcut **⌃⇧R** (on macOS) or **Ctrl+Shift+F10** (on Windows/Linux). + +Alternatively, we can run our application using the green Run button in the top right corner, or using the shortcut **⌃R** (on macOS) or **Ctrl+F10** (on Windows/Linux) to run the latest file. + +[![Run](/assets/images/intellij-idea/run.png)](/assets/images/intellij-idea/run.png) + +If we want to pass arguments to our application, we can do so in our [Run Configurations](https://www.jetbrains.com/help/idea/run-debug-configuration.html). + +To edit your run configurations, select the configuration in the run/debug configuration switcher, by clicking the down arrow next to the current configuration or the three dots to the right of the run configuration, and select **Edit Configurations**. + +[![Edit Configurations](/assets/images/intellij-idea/edit-configurations.png)](/assets/images/intellij-idea/edit-configurations.png) + +The popup **Run/Debug Configurations** appears, and there you can modify JVM options, add program arguments, and many more. + +[![Run / Debug Configuration](/assets/images/intellij-idea/run-config.png)](/assets/images/intellij-idea/run-config.png) + +  +## Testing + +Testing your code helps you to verify that the code does what you expect it to do. You can run your application and test it yourself, or add automated tests that can verify your code for you. Thinking about what to test and how, can help you to break a problem up into smaller pieces. This will help you get a better solution faster! + +For example, let's say we have a `Calculator` class containing the following method that calculates the average of a list of values, and we want to make sure the average is calculated correctly: +```java +public class Calculator { + + public static double average(int[] numbers) { + int sum = 0; + for (int number : numbers) { + sum += number; + } + double avg = (double) sum / numbers.length; + return avg; + } +} +``` +IntelliJ IDEA makes it easy to add tests to your code. You can navigate to the test for a particular class using the shortcut **⇧⌘T** on macOS or **Ctrl+Shift+T** on Windows/Linux. If no test class exists yet, IntelliJ IDEA will create one for you. This class will be created in the `src/test/java` directory. +We can select a **Testing library** in the **Create test** popup. + +[![Create test](/assets/images/intellij-idea/create-test.png)](/assets/images/intellij-idea/create-test.png) + +IntelliJ IDEA supports multiple testing libraries, including [JUnit 5](https://junit.org/junit5/), which is the [most used testing library for Java developers](https://www.jetbrains.com/lp/devecosystem-2023/java/#java_unittesting). If JUnit 5 is not part of your project yet, IntelliJ IDEA will note “JUnit5 library not found in the module.” Click **Fix** to have IntelliJ IDEA fix this for you. + +Note that the JUnit 5 dependency `junit-jupiter` is added to the `pom.xml` in the `` section. +To make sure the dependencies work correctly in your project, **Load Maven Changes** by clicking the popup in the top right corner, or using the shortcut **⇧⌘I** (on macOS) or **Ctrl+Shift+O** (on Windows/Linux). + +[![JUnit5 dependencies](/assets/images/intellij-idea/junit5-dependencies.png)](/assets/images/intellij-idea/junit5-dependencies.png) + +Go back to the test file to add tests. We can let IntelliJ IDEA help us generate our test for us. In the test class, we can use **Generate** (**⌘N** on macOS or **Alt+Insert** on Windows/Linux) and select **Test Method** to add a test. Give the test a name that explains the intended behavior, and add the relevant test code. + +For example, let's make sure that the method `average()` correctly calculates the average for an array of positive numbers, and returns `0` for an empty array. You might want to add additional tests for different scenarios, such as an array of negative numbers, a mix of positive and negative numbers, etc. +```java +import org.junit.jupiter.api.Test; +import static org.junit.jupiter.api.Assertions.assertEquals; + +public class CalculatorTest { + + @Test + void shouldCalculateAverageOfPositiveNumbers() { + int[] numbers = {1, 2, 3, 4, 5}; + + double actualAverage = Calculator.average(numbers); + + double expectedAverage = 3.0; + assertEquals(expectedAverage, actualAverage); + } + + @Test + void shouldReturnZeroAverageForEmptyArray() { + int[] numbers = {}; + + double actualAverage = Calculator.average(numbers); + + double expectedAverage = 0; + assertEquals(expectedAverage, actualAverage); + } +} +``` +In our test class, we can select **Run All Tests** (**⌃⇧R** on macOS or **Ctrl+Shift+F10** on Windows/Linux). + +In our example, we see that the second test fails. We expected to get the value `0` as the average of an empty array, but got `NaN` (not a number) instead. Let's find out why, using the debugger. + +  +## Debugging + +We might want to see how our code runs, either to help us understand how it works and/or when we need to fix a bug or failing test, like the one above. We can run our code through the [debugger](https://www.jetbrains.com/help/idea/debugging-code.html) to see the state of our variables at different times, and the call stack - the order in which methods are called when the program executes. To do so, we must first add a [breakpoint](https://www.jetbrains.com/help/idea/using-breakpoints.html) to the code. + +To add a breakpoint, click the gutter at the line of code where you want execution to stop. Alternatively, place the caret at the line and press **⌘F8** (on macOS) or **Ctrl+F8** (on Windows/Linux). We can run our test or application using the **Debug** option; either by right-clicking the **Run** button in the gutter and selecting the **Debug** option from the list, or by selecting the **Debug** button at the top right. + +Execution will stop at the breakpoint, so we can investigate the state of our application. We can see the current values of variables and objects. We can evaluate an expression to see its current value and look at more details. We can even change the expressions to evaluate different results. We can continue execution by either stepping into a method to see what happens inside a called method (using the shortcut **F7**, or the corresponding button in the **Debug** tool window) or stepping over a line to go to the next line even if a method is called (using the shortcut **F8**, or the corresponding button in the **Debug** tool window), depending on what we’re interested in. Finally, we can resume the program to finish the execution of the test. + +Let's debug the failing test from the previous section. In the code, place a breakpoint on line 4. Run the failing test through the debugger. Step over the code until you get to line 8, and observe the values of the variables. When we get to line 8, select `sum / numbers.length`, right-click to open the context menu and select **Evaluate Expression**. Press **Enter** to evaluate the selected expression. We see that `sum / numbers.length` results in a `java.lang.ArithmeticException: / by zero`. The empty array has a length of `0` and Java does not allow dividing by zero. +When we evaluate `(double) sum / numbers.length` we get the result `NaN`. We expected `0`, so our test fails. + +[![Debugging](/assets/images/intellij-idea/debug.gif)](/assets/images/intellij-idea/debug.gif) + +As we didn't consider this scenario in our initial implementation, we can fix this by changing our method to return `0` when an empty array is given as input: +```java +public class Calculator { + + public static double average(int[] numbers) { + if (numbers.length == 0) { + return 0; + } + int sum = 0; + for (int number : numbers) { + sum += number; + } + double avg = (double) sum / numbers.length; + return avg; + } +} +``` +Now, when we run our tests, we see that they pass. + +For more information on debugging, see [Debugging in Java](https://dev.java/learn/debugging/). + +  +## Refactoring code + +While working with our code, we may want to make small improvements without changing the functionality. We can use [refactoring](https://www.jetbrains.com/help/idea/refactoring-source-code.html) to reshape the code. + +* We can rename classes, variables and methods using **Refactor | Rename** (**⇧F6** on macOS, or **Shift+F6** on Windows/Linux). +* We can inline variables (**⌘⌥N** on macOS, or **Ctrl+Alt+N** on Windows/Linux), or extract variables (**⌘⌥V** on macOS, or **Ctrl+Alt+V** on Windows/Linux) as needed. +* We can break long methods into smaller parts by extracting a method (**⌘⌥M** on macOS, or **Ctrl+Alt+M** on Windows/Linux) and giving it a meaningful name. + +All these options help us refactor our code to a more familiar style, or to use new idioms and language features. + +Pull up the refactoring menu to see what is possible, using the shortcut **⌃T** (on macOS) or **Ctrl+Alt+Shift+T** (on Windows/Linux). + +[![Refactoring](/assets/images/intellij-idea/refactor.gif)](/assets/images/intellij-idea/refactor.gif) + +  +## Documenting code + +We can add documentation to our code. IntelliJ IDEA provides completion for documentation comments, which is enabled by default. Type `/**` before a declaration and press **Enter**. IntelliJ IDEA auto-completes the documentation comment for you. + +IntelliJ IDEA provides a way for you to easily understand and read Javadoc comments by selecting _Reader Mode_. **Toggle Rendered View** in the editor using **^⌥Q** (on macOS) or **Ctrl+Alt+Q** (on Windows/Linux). Right-click the icon in the gutter to select **Render All Doc Comments** if you want all comments to show in reader mode. + +  +## Searching and navigating + +IntelliJ IDEA also helps us by providing ways to navigate around our codebase, for example, by going backwards and forwards between files, finding usages and declarations, finding interfaces and their implementations, viewing recently opened files and location, or even opening a window by name. + +One popular way to search is [Search Everywhere](https://www.jetbrains.com/help/idea/searching-everywhere.html) (using **Shift** twice). Search everywhere allows you to search your project files and directories, as well as your project settings and IntelliJ IDEA settings. + +[![Search everywhere](/assets/images/intellij-idea/search-everywhere.png)](/assets/images/intellij-idea/search-everywhere.png) + +Another popular way to search is [Find in Files](https://www.jetbrains.com/help/idea/finding-and-replacing-text-in-project.html#find_in_project). Open **Find in Files** from the main menu using **Edit | Find | Find in Files**, or by using the shortcut **⌘⇧F** (on macOS) or **Ctrl+Shift+F** (on Windows/Linux). You can narrow down the results from **In Project** to **Module**, **Directory**, or **Scope**. + +[![Find in Files](/assets/images/intellij-idea/find-in-files.png)](/assets/images/intellij-idea/find-in-files.png) + +  +## Summary + +In this article, we’ve seen how IntelliJ IDEA can help you with code suggestions and completion while writing code, running your application, adding tests and using the debugger to help figure out how code is run, refactoring code, and more. + +IntelliJ IDEA continues to improve and evolve, adding new features and offering new integration. You can sharpen your coding skills by taking a look at the [documentation](https://www.jetbrains.com/help/idea/getting-started.html), [blog](https://blog.jetbrains.com/idea/), [YouTube channel](https://www.youtube.com/intellijidea), or [guide](https://www.jetbrains.com/guide/java/). diff --git a/app/pages/learn/01_tutorial/01_your-first-java-app/03_building-with-eclipse.md b/app/pages/learn/01_tutorial/01_your-first-java-app/03_building-with-eclipse.md new file mode 100644 index 0000000..e510d68 --- /dev/null +++ b/app/pages/learn/01_tutorial/01_your-first-java-app/03_building-with-eclipse.md @@ -0,0 +1,326 @@ +--- +id: first_app.eclipse +title: Building a Java Application in the Eclipse IDE +slug: learn/eclipse +type: tutorial +category: start +layout: learn/tutorial.html +subheader_select: tutorials +main_css_id: learn +toc: +- Introduction and Installation {intro} +- Creating a Java Project {creating} +- Content Assist {content_assist} +- Running Your Program {run} +- Dealing With Compilation Errors and Warnings {errors} +- Debugging {debugging} +- Generating Code {generating} +- Refactoring {refactoring} +- Summary {summary} +description: "Installing and getting started with the Eclipse IDE for developing Java applications" +last_update: 2024-04-15 +author: ["DanielSchmid"] +--- +  +## Introduction and Installation + +The Eclipse IDE (or Eclipse for short) is a commonly used application that provides tooling that helps developers write, run and debug Java code. This article describes how to get started with Eclipse for developing Java applications. + +The easiest way to install Eclipse is to download and run the Eclipse installer from [this site](https://www.eclipse.org/downloads/packages/installer). This provides multiple options for packages to install. In most cases, `Eclipse IDE for Java Developers` is a good installation for Java development. + +[![Eclipse Installer](/assets/images/eclipse/install.png)](/assets/images/eclipse/install.png) + +After installing Eclipse, you can select a workspace. The workspace is the directory where most projects are located. + +[![Workspace selection](/assets/images/eclipse/workspace_selection.png)](/assets/images/eclipse/workspace_selection.png) + +Upon selecting a workspace, it will show a Welcome screen presenting you with mutliple options. For example, there is an option to start an interactive tutorial that shows you how to create a simple Hello-World application. + +[![Workspace selection](/assets/images/eclipse/welcome.png)](/assets/images/eclipse/welcome.png) + +This article will show you how to create Java projects manually so you can close this Welcome screen by clicking on the `Hide` button on the top right of the Welcome tab. + +  +## Creating a Java Project + +After installing Eclipse you should have an empty workspace. In order to create a new Java project, click on the `File` toolbar in the top left corner of the Eclipse window and select `New` > `Java Project`. + +[![File > New > Java Project](/assets/images/eclipse/file_create_project.png)](/assets/images/eclipse/file_create_project.png) + +This will then open up a dialog window that allows you to configure your project. You will need to enter a name next to `Project name:` at the top. For example, you can choose the name `HelloWorld`. In the `Module` section at the bottom, disable the option `Create module-info.java file`. You can configure a custom Java installation (commonly referred to as the *JDK* or Java Development Kit) in the `JRE` box. + +[![Java project creation dialog](/assets/images/eclipse/create_java_project.gif)](/assets/images/eclipse/create_java_project.gif) + +This creates a Java project that is shown on the left side of the Eclipse window. When expanding this project, there should be a folder named `src`. Java classes can be created inside this directory by right-clicking on it and selecting `New` > `Class`. + +[![New > Class](/assets/images/eclipse/create_class.png)](/assets/images/eclipse/create_class.png) + +This opens a dialog similar to the project creation dialog. It allows specifying various options about the class you want to create. For now, you will need to enter a class name like `HelloWorld`. If you want to, you can also configure a package which can be used to group multiple classes together. + +[![Java class creation dialog](/assets/images/eclipse/java_class_creation.png)](/assets/images/eclipse/java_class_creation.png) + +  +## Content Assist + +Eclipse can help you write Java code by automatically completing parts of it. When pressing the key combination `Ctrl`+`Space` (or `⌘`+`Space` on macOS or `Alt`+`/` on Chinese systems) while editing Java code, Eclipse automatically suggests ways to complete the code. These suggestions can be confirmed by pressing `Enter` or double-clicking on the suggestions. + +For example, typing `main` in a class followed by pressing `Ctrl`+`Space` suggests adding a main method. + +[![Content assist suggesting a main method](/assets/images/eclipse/content_assist_main.png)](/assets/images/eclipse/content_assist_main.png) + +Inside methods, Eclipse can suggest changing `sysout` to a `System.out.println();` statement. + +[![Content assist suggesting a System.out statement](/assets/images/eclipse/content_assist_sysout.png)](/assets/images/eclipse/content_assist_sysout.png) + +Furthermore, it can complete class and method names. + +[![Content assist completing the class name String](/assets/images/eclipse/content_assist_suggest_class.png)](/assets/images/eclipse/content_assist_suggest_class.png) + +[![Content assist completing the method String#length](/assets/images/eclipse/content_assist_suggest_method.png)](/assets/images/eclipse/content_assist_suggest_method.png) + + +  +## Running Your Program + +In order to run a Java application, you first need to have a class with a `main` method. You can right-click the class in the package explorer or right-click in the editor where you are writing the code for the class and select `Run as` > `Java application`. + +[![Run As > Java application in the editor](/assets/images/eclipse/run_as_editor.png)](/assets/images/eclipse/run_as_editor.png) + +[![Run As > Java application in the editor](/assets/images/eclipse/run_as_package_explorer.png)](/assets/images/eclipse/run_as_package_explorer.png) + +Alternatively, you can run the application using the Run [![Run button](/assets/images/eclipse/run_button.png)](/assets/images/eclipse/run_button.png) button in the toolbar. [![Run button in toolbar](/assets/images/eclipse/run_buttons_toolbar.png)](/assets/images/eclipse/run_buttons_toolbar.png) + +When running the program, Eclipse should show the output of the program in the `Console` view. + +[![Program with output in console](/assets/images/eclipse/console_output.png)](/assets/images/eclipse/console_output.png) + +  +## Dealing with Compilation Errors and Warnings + +When Eclipse detects a compilation error, the relevant lines are underlined in red. When hovering over the line with the error or the error icon to the left of the said line, Eclipse provides information about what went wrong and also suggests Quick Fixes which can fix the error. However, in many cases, there are multiple ways to get rid of the error. You need to carefully check whether the suggestions are actually matching what you want to do. After all, IDEs cannot predict your intent. + +[![Compilation error due to calling a non-existing method](/assets/images/eclipse/compilation_error.png)](/assets/images/eclipse/compilation_error.png) + +Furthermore, Eclipse shows a list of errors in the `Problems` view. If this view is not displayed, it can be shown using the menu `Window` > `Show View` > `Problems`. + +[![opening Problems view](/assets/images/eclipse/open_problems_view.png)](/assets/images/eclipse/open_problems_view.png) + +[![Problems view showing an error](/assets/images/eclipse/problems_view.png)](/assets/images/eclipse/problems_view.png) + +As with Errors, Eclipse can also detect code that compiles but likely contains some issues or is pointless. In this case, Eclipse will display a warning. + +[![Warning due to unused variable](/assets/images/eclipse/warning.png)](/assets/images/eclipse/warning.png) + +[![Problems view showing a warning](/assets/images/eclipse/problems_view_warning.png)](/assets/images/eclipse/problems_view_warning.png) + +  +## Debugging + +When a program doesn't do what you expect it to do, you might want to debug it. The process of debugging is explained in [this article](id:debugging). Eclipse provides a lot of functionality making it easy to debug Java applications. + +In order to debug an application, you need to set a breakpoint. When the program gets to executing the line with the breakpoint, it will temporarily stop ("suspend"), allow you to inspect its current state and step through the program. To set a breakpoint, you need to double-click on the area to the left of the line you want to suspend the program at. After doing that, a blue dot should appear there. + +[![A breakpoint next to source code](/assets/images/eclipse/breakpoint.png)](/assets/images/eclipse/breakpoint.png) + +When running a program normally, it will ignore all breakpoints. For debugging, you need to run the program in debug mode. This can be done by clicking on the green button with the bug icon [![The debug button](/assets/images/eclipse/debug_button.png)](/assets/images/eclipse/debug_button.png) next to the run button or using `Debug As` > `Java Application`. + +[![The debug button next to run buttons](/assets/images/eclipse/debug_button_in_toolbar.png)](/assets/images/eclipse/debug_button_in_toolbar.png) + +When the program execution gets to a breakpoint in debug mode, Eclipse will ask you to switch to the Debug perspective. This perspective gives you more information about the program you are currently debugging so you likely want to do this and click on the `Switch` button. + +[![Eclipse asking to switch to the Debug perspective](/assets/images/eclipse/debug_perspective_switch.png)](/assets/images/eclipse/debug_perspective_switch.png) + +Upon opening the debug perspective, you should still see your code in the middle. However, there should be one line with a green background next to the breakpoint. This indicates the next line the program would execute. On the right side, you should see a `Variables` view containing a list of variables and their current values. + +[![The debug perspective](/assets/images/eclipse/debug_perspective.png)](/assets/images/eclipse/debug_perspective.png) + +While the program is suspended, you can tell it how to continue executing using buttons in the toolbar at the top. +[![Buttons for controlling execution flows in the toolbar](/assets/images/eclipse/debug_toolbar_buttons.png)](/assets/images/eclipse/debug_toolbar_buttons.png) +You can execute one line using `Step Over` [![Step Over button](/assets/images/eclipse/debug_step_over.png)](/assets/images/eclipse/debug_step_over.png) (`F6`), go into a method using `Step Into` [![Step Into button](/assets/images/eclipse/debug_step_into.png)](/assets/images/eclipse/debug_step_into.png) (`F5`) or continue executing the program until the next breakpoint with `Resume` [![Resume button](/assets/images/eclipse/debug_resume.png)](/assets/images/eclipse/debug_resume.png) (`F8`). + +  +## Generating Code + +Sometimes you might need to write repetitive code that doesn't contain much business logic and can be generated using information from existing code. An example of this is getters/setters or `equals`/`hashCode`/`toString` methods which typically just need to access some fields. While it is often preferable to use [records](/learn/records), Eclipse allows comes with functionality to generate these pieces of repetitive code. + +In order to do this, you first need to create a class with some fields you want to generate these methods for. In this example, we will create a `Person` class that stores the first name, last name and age of a person. +```java +public class Person { + private String firstName; + private String lastName; + private int age; + //we want to generate code here + +} +``` + +When right-clicking in that class, there is an option called `Source` providing various ways to generate code. Here, we can select `Generate Getters and Setters...` in order to generate accessor methods for the fields in the `Person` class. + +[![Generate Getters and Setters](/assets/images/eclipse/context_generate_getters_setters.png)](/assets/images/eclipse/context_generate_getters_setters.png) + +This option should open up a new window allowing us to configure which fields we want to generate accessors for. In order to create accessors for all fields, use the `Select All` button. and click `Generate` on the bottom right. + +[![Generate Getters and Setters](/assets/images/eclipse/getter_setter_modal.png)](/assets/images/eclipse/getter_setter_modal.png) + +After doing this, the class should look as follows: +```java +public class Person { + private String firstName; + private String lastName; + private int age; + //we want to generate code here + public String getFirstName() { + return firstName; + } + public void setFirstName(String firstName) { + this.firstName = firstName; + } + public String getLastName() { + return lastName; + } + public void setLastName(String lastName) { + this.lastName = lastName; + } + public int getAge() { + return age; + } + public void setAge(int age) { + this.age = age; + } + +} +``` + +Similarly, it is possible to generate the `hashCode` and `equals` methods using the menu `Source` > `Generate hashCode() and equals()...`. + +[![Generate hashCode and equals](/assets/images/eclipse/context_generate_hashcode_equals.png)](/assets/images/eclipse/generate_hashcode_equals.png) + +This also opens a window which allows to select the fields to include in the `hashCode` and `equals` methods. +[![Selecting fields to use in hashCode and equals](/assets/images/eclipse/hashcode_equals_modal.png)](/assets/images/eclipse/hashcode_equals_modal.png) + +After clicking `Generate`, Eclipse automatically adds these methods to the class. +```java +import java.util.Objects; + +public class Person { + private String firstName; + private String lastName; + private int age; + //we want to generate code here + public String getFirstName() { + return firstName; + } + public void setFirstName(String firstName) { + this.firstName = firstName; + } + public String getLastName() { + return lastName; + } + public void setLastName(String lastName) { + this.lastName = lastName; + } + public int getAge() { + return age; + } + public void setAge(int age) { + this.age = age; + } + @Override + public int hashCode() { + return Objects.hash(age, firstName, lastName); + } + @Override + public boolean equals(Object obj) { + if (this == obj) + return true; + if (obj == null) + return false; + if (getClass() != obj.getClass()) + return false; + Person other = (Person) obj; + return age == other.age && Objects.equals(firstName, other.firstName) + && Objects.equals(lastName, other.lastName); + } + +} +``` + +Another method that is often generated is `toString()` which returns a `String` representation of the object. +To generate that method, select `Generate toString()...` in the `Source` menu. + +[![Generate toString](/assets/images/eclipse/context_tostring.png)](/assets/images/eclipse/context_tostring.png) + +As before, this opens a window allowing to specify options on how exactly the code should be generated. + +[![Options for toString](/assets/images/eclipse/tostring_options.png)](/assets/images/eclipse/tostring_options.png) + +Using the `Generate` button, Eclipse generates the `toString` method as it did with the other methods before. +```java +import java.util.Objects; + +public class Person { + private String firstName; + private String lastName; + private int age; + //we want to generate code here + public String getFirstName() { + return firstName; + } + public void setFirstName(String firstName) { + this.firstName = firstName; + } + public String getLastName() { + return lastName; + } + public void setLastName(String lastName) { + this.lastName = lastName; + } + public int getAge() { + return age; + } + public void setAge(int age) { + this.age = age; + } + @Override + public int hashCode() { + return Objects.hash(age, firstName, lastName); + } + @Override + public boolean equals(Object obj) { + if (this == obj) + return true; + if (obj == null) + return false; + if (getClass() != obj.getClass()) + return false; + Person other = (Person) obj; + return age == other.age && Objects.equals(firstName, other.firstName) + && Objects.equals(lastName, other.lastName); + } + @Override + public String toString() { + return "Person [firstName=" + firstName + ", lastName=" + lastName + ", age=" + age + "]"; + } + +} +``` + + +  +## Refactoring + +When working on Java applications, it is often necessary to change existing code in various ways while preserving functionality. Eclipse supports developers doing that by providing various refactoring options. An example of that is renaming class, methods or fields. This can be done by clicking on a class, method or variable name, right-clicking and selecting `Refactor` > `Rename`. + +[![Rename context menu](/assets/images/eclipse/context_rename.png)](/assets/images/eclipse/context_rename.png) + +It is then possible to change to name to something different and confirming it using the `Enter` key. This also updates all references to the renamed element. + +[![Renaming a class name](/assets/images/eclipse/rename_box.png)](/assets/images/eclipse/rename_box.png) + +[![Renaming a class name](/assets/images/eclipse/rename_different_text.png)](/assets/images/eclipse/rename_different_text.png) + + +  +## Summary + +As you can see, the Eclipse IDE provides a lot of tools that help developers write Java applications. While this article shows some, Eclipse comes with many more features that can be especially useful when working on bigger applications. If you are interested in reading more, check out the [Java Development user guide](https://help.eclipse.org/latest/index.jsp?nav=%2F1). \ No newline at end of file diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/02_basics/01_creating-variables.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/02_basics/01_creating-variables.md index 0bdefcb..f6416c7 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/02_basics/01_creating-variables.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/02_basics/01_creating-variables.md @@ -44,6 +44,6 @@ Having said that, the remainder of this tutorial uses the following general guid Every programming language has its own set of rules and conventions for the kinds of names that you're allowed to use, and the Java programming language is no different. The rules and conventions for naming your variables can be summarized as follows: -- Variable names are case-sensitive. A variable's name can be any legal identifier — an unlimited-length sequence of Unicode letters and digits, beginning with a letter, the dollar sign "$", or the underscore character "_". The convention, however, is to always begin your variable names with a letter, not "$" or "_". Additionally, the dollar sign character, by convention, is never used at all. You may find some situations where auto-generated names will contain the dollar sign, but your variable names should always avoid using it. A similar convention exists for the underscore character; while it's technically legal to begin your variable's name with "_", this practice is discouraged. White space is not permitted. +- Variable names are case-sensitive. A variable's name can be any legal identifier — an unlimited-length sequence of Unicode letters and digits, beginning with a letter, the dollar sign `$`, or the underscore character `_`. The convention, however, is to always begin your variable names with a letter, not `$` or `_`. Additionally, the dollar sign character, by convention, is never used at all. You may find some situations where auto-generated names will contain the dollar sign, but your variable names should always avoid using it. A similar convention exists for the underscore character; while it's technically legal to begin your variable's name with `_`, this practice is discouraged. White space is not permitted. - Subsequent characters may be letters, digits, dollar signs, or underscore characters. Conventions (and common sense) apply to this rule as well. When choosing a name for your variables, use full words instead of cryptic abbreviations. Doing so will make your code easier to read and understand. In many cases it will also make your code self-documenting; fields named cadence, speed, and gear, for example, are much more intuitive than abbreviated versions, such as s, c, and g. Also keep in mind that the name you choose must not be a keyword or reserved word. - If the name you choose consists of only one word, spell that word in all lowercase letters. If it consists of more than one word, capitalize the first letter of each subsequent word. The names `gearRatio` and `currentGear` are prime examples of this convention. If your variable stores a constant value, such as static final int NUM_GEARS = 6, the convention changes slightly, capitalizing every letter and separating subsequent words with the underscore character. By convention, the underscore character is never used elsewhere. diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/00_refactoring.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/00_refactoring.md index c7eb872..c6e4be4 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/00_refactoring.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/00_refactoring.md @@ -21,4 +21,7 @@ In this series we cover the following conversions from the imperative to the fun |------------------------------------------------------|-----------------|------------------------------| | [Converting Simple Loops](id:refactoring.simple.loops) | `for()` | `range()` or `rangeClosed()` | | [Converting Loops with Steps](id:refactoring.loops.withsteps) | `for(...i = i + ...)` | `iterate()` with `takeWhile()` | +| [Converting foreach with if](id:refactoring.foreach.withif) | `foreach(...) { if... }` | `stream()` with `filter()` | +| [Converting Iteration with transformation](id:refactoring.iteration.withtransformation) | `foreach(...) { ...transformation... }` | `stream()` with `map()` | +| [Converting to Streams](id:refactoring.to.streams) | `File read operation` | `Files.lines()` | diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/01_converting_simple_loops.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/01_converting_simple_loops.md index 604334f..3988370 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/01_converting_simple_loops.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/01_converting_simple_loops.md @@ -23,7 +23,7 @@ The older versions of Java supported the Object-Oriented paradigm mixed with the Imperative style is where we tell what to do and also how to do it. Functional style is declarative in nature, where we tell what to do and delegate the how or the details to the underlying libraries. Imperative style code may be easier to write since most of us are very familiar with it. However, the code becomes verbose, complex, and hard to read. Functional style may be hard at first, mainly because most programmers are less familiar with it. In general, it's easier to read, understand, and change. With practice, it becomes easier to write as well. -In this tutorial series we will take a look at a number of common imperative style code and find a mapping or an equivalent functional style code that we can use instead. As you work with your code based, when you're ready to fix a bug or make an enhancement, you may find it useful to refactor some of the imperative style code to the functional style. You can use this tutorial as a guide to find the imperative to functional style mappings for some common situations. +In this [tutorial series](id:refactoring) we will take a look at a number of common imperative style code and find a mapping or an equivalent functional style code that we can use instead. As you work with your code based, when you're ready to fix a bug or make an enhancement, you may find it useful to refactor some of the imperative style code to the functional style. You can use this tutorial as a guide to find the imperative to functional style mappings for some common situations. In this tutorial we'll focus on simple loops. diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/02_converting_loops_with_steps.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/02_converting_loops_with_steps.md index 9872e18..687c068 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/02_converting_loops_with_steps.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/02_converting_loops_with_steps.md @@ -20,7 +20,7 @@ author: ["VenkatSubramaniam"]   ## Iterating with Steps -In the previous article in this series we looked at converting simple loops written in the imperative style to the functional style. In this article we'll see how to take on loops that are a bit more complex—when we have to step over some values in an interval. +In the previous article in this [tutorial series](id:refactoring) we looked at converting simple loops written in the imperative style to the functional style. In this article we'll see how to take on loops that are a bit more complex—when we have to step over some values in an interval. When looping over a range of values, one at a time, the `range()` method of `IntStream` came in handy to implement in the functional style. This method returns a stream that will generate one value at a time for values within the specified range. At first thought, to skip some values we may be tempted to use the `filter()` method on the stream. However, there's a simpler solution, the `iterate()` method of `IntStream`. diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/03_converting_foreach_with_if.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/03_converting_foreach_with_if.md new file mode 100644 index 0000000..3dcff3d --- /dev/null +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/03_converting_foreach_with_if.md @@ -0,0 +1,97 @@ +--- +id: refactoring.foreach.withif +title: Converting foreach with if +slug: learn/refactoring-to-functional-style/foreachwithif +type: tutorial-group +group: refactoring-to-functional-style +layout: learn/tutorial-group.html +subheader_select: tutorials +main_css_id: learn +toc: +- Iterating with foreach {foreach} +- From Imperative to Functional Style {imperativetofunctional} +- Picking elements with if {picking} +- Mappings {mappings} +description: "Converting Imperative Iteration using foreach with if to Functional Style." +last_update: 2023-07-06 +author: ["VenkatSubramaniam"] +--- + +  +## Iterating with foreach + +In the previous articles in this [tutorial series](id:refactoring) we looked at converting loops written in the imperative style to the functional style. In this article we'll see how to convert an imperative style iteration using `foreach` to the functional style. In addition, we'll also see how to pick select elements using `if` transforms to the functional style. + +Java 5 introduced the very popular `foreach` syntax. For example, to iterate over a collection of `String`s representing names, we'd write something like `for(String name: names)`. Under the hood, the `foreach` is converted, at the bytecode level, to use an `Iterator`—while the iterator tells us there is another element, fetch the next element for processing. In other words, the `foreach` is a nice concise syntax sugar for iteration with a `while` loop over the elements provided by an `Iterator`. We can convert a `foreach` into the functional style quite easily. Let's see how. + +  +## From Imperative to Functional Style + +Here's an example of iteration, using the `foreach`, over a collection of names: + +```java +List names = List.of("Jack", "Paula", "Kate", "Peter"); + +for(String name: names) { + System.out.println(name); +} +``` + +Each step through the iteration, the `name` variable is bound to a new value, as the iteration advances from one element to the next in the given collection. Converting the imperative style `foreach` to the functional style is a straight up use of the `forEach` internal iterator method. It is called an internal iterator because the advancing to the next element is handled internally and automatically instead of externally or explicitly. + +Let's refactor the loop to use functional style. + +```java +List names = List.of("Jack", "Paula", "Kate", "Peter"); + +names.forEach(name -> System.out.println(name)); +``` + +That was pretty straightforward, the `for` loop turned into a call to the `forEach()` method on the collection. Each step through the iteration, the lambda provided to the `forEach()` as an argument is invoked with the next element in the collection. + +A slightly variation of this iteration, using `stream()`, is shown next. + +```java +List names = List.of("Jack", "Paula", "Kate", "Peter"); + +names.stream() + .forEach(name -> System.out.println(name)); +``` +The `forEach()` method is available both on a `Collection` and on a `Stream`. Functions like `filter()`, which we'll use soon, are available only on a `Stream` and not on the `Collection`. This is by design in order to provide efficiency when multiple intermediate operations may precede the terminal operation like `forEach()`, `findFirst()`, etc. + +  +## Picking select elements with if + +Suppose, in the middle of the iteration, we want to pick some values from the collection based on some condition. For example, what if we want to print only names of length 4? In the imperative style we could do the following: + +```java +List names = List.of("Jack", "Paula", "Kate", "Peter"); + +for(String name: names) { + if(name.length() == 4) { + System.out.println(name); + } +} +``` + +For the functional style, the `filter` method of `Stream` becomes a direct replacement of the imperative style `if`. The `filter` method will allow an element in the collection to pass through to the next stage in the functional pipeline if the predicate, passed in as a lambda, to the `filter()` method evaluates to `true`; otherwise, the value is discarded from further processing. + +Let's convert the previous code to functional style: + +```java +List names = List.of("Jack", "Paula", "Kate", "Peter"); + +names.stream() + .filter(name -> name.length() == 4) + .forEach(name -> System.out.println(name)); +``` + +The `filter()` method acts like a gate, it opens to let some elements pass through and closes to reject or discard some elements, as the iteration moves forward. + +We saw in the previous articles the functional style equivalent for the traditional `for` loops. In this article we saw how the imperative style `foreach` of Java 5 transforms into an elegant syntax in the functional style. Furthermore, the `if` condition within a loop of the imperative style translates to a call to the `filter()` method of the `Stream` API. + +  +## Mappings + +Anywhere you see a `foreach` loop, use the `forEach()` method directly on the collection. If the body of the `foreach` has a `if` statement to selectively pick some value, then use the `stream()` API with the call to the `filter()` method. + diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/04_converting_foreach_with_transformation.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/04_converting_foreach_with_transformation.md new file mode 100644 index 0000000..844cc4b --- /dev/null +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/04_converting_foreach_with_transformation.md @@ -0,0 +1,116 @@ +--- +id: refactoring.iteration.withtransformation +title: Converting Iteration with transformation +slug: learn/refactoring-to-functional-style/iteartionwithtransformation +type: tutorial-group +group: refactoring-to-functional-style +layout: learn/tutorial-group.html +subheader_select: tutorials +main_css_id: learn +toc: +- Transforming while Iterating {transforming} +- From Imperative to Functional Style {imperativetofunctional} +- Picking Elements to Transform {picking} +- Mappings {mappings} +description: "Converting Imperative Iteration with transformation to Functional Style." +last_update: 2024-01-08 +author: ["VenkatSubramaniam"] +--- + +  +## Transforming while Iterating + +In the previous articles in this [tutorial series](id:refactoring) we looked at converting loops with `if` or conditional statements in the imperative style to the functional style. In this article we'll see how to convert an imperative style iteration that transforms data to the functional style. In addition, we'll also refactor code that mixes transforming data with code that picks select elements before the transformation. + +Anytime we are transforming data in an imperative style loop, we can use the `map()` function in the functional style. Let's see how. + + +  +## From Imperative to Functional Style + +Here's an example of an iteration, using the `foreach`, that transforms to uppercase a collection of names: + +```java +List names = List.of("Jack", "Paula", "Kate", "Peter"); + +for(String name: names) { + System.out.println(name.toUpperCase()); +} +``` + +Each step through the iteration, the `name` variable is bound to a new value. As the iteration advances from one element to the next in the given collection, each name is transformed to uppercase using the `toUpperCase()` function and the resulting value is printed. We have already seen, in the previous article, how to convert the imperative style `foreach` to the functional style—using the `stream()` internal iteration. If we merely apply what we have seen before, the resulting functional style code would be rather unwieldy, with the lambda passed to `forEach` performing both transformation and printing, like so: + +```java +List names = List.of("Jack", "Paula", "Kate", "Peter"); + +names.forEach(name -> System.out.println(name.toUpperCase())); //Don't do this +``` + +Even though the above functional style code will produce the same results as the imperative style code, the lambda passed to the `forEach()` function is not cohesive, hard to read, and hard to change. + +Before refactoring the imperative style code above to the function style, we should first refactor the imperative style to yet another imperative style implementation to make each line more cohesive, like so: + +```java +List names = List.of("Jack", "Paula", "Kate", "Peter"); + +for(String name: names) { + String nameInUpperCase = name.toUpperCase(); + System.out.println(nameInUpperCase); +} +``` + +From the previous articles in this series, we know that the `for` can turn into a `stream()` and the printing of the value can be done from within the `forEach()`. That leaves us with the transformation, the call to the `toUpperCase()` function. Such transformations can be done using the `map()` operation on the `stream()`. + +```java +List names = List.of("Jack", "Paula", "Kate", "Peter"); + +names.stream() + .map(name -> name.toUpperCase()) + .forEach(nameInUpperCase -> System.out.println(nameInUpperCase)); +``` +The `map()` operation transforms the data to a different value based on the function invoked from within the lambda expression that's passed to `map()`. In this example, each name is transformed to its uppercase value. The transformed value is then printed out from within the lambda expression passed to `forEach()`. + +We can make the code a bit more concise by using method references instead of lambda expressions, like so: + +```java +List names = List.of("Jack", "Paula", "Kate", "Peter"); + +names.stream() + .map(String::toUpperCase) + .forEach(System.out::println); +``` + +Use the `map()` function to transform data while iterating over a collection of data. + +  +## Picking Elements to Transform + +Suppose, in the middle of the iteration, we want to pick some values from the collection based on some condition and apply a transformation only on those elements. For example, what if we want to transform and print only names of length 4? In the imperative style we could do the following: + +```java +List names = List.of("Jack", "Paula", "Kate", "Peter"); + +for(String name: names) { + if(name.length() == 4) { + System.out.println(name.toUpperCase()); + } +} +``` + +We already know that the imperative style `if` can be refactored to the `filter()` function in the functional style. We can perform the transformation, using `map()`, after the `filter()` operation, like so: + +```java +List names = List.of("Jack", "Paula", "Kate", "Peter"); + +names.stream() + .filter(name -> name.length() == 4) + .map(String::toUpperCase) + .forEach(System.out::println); +``` + +The `filter()` function discards data that's not desired and passes on only the values we like to use. The `map()` function transforms the values it sees after the filter. + +  +## Mappings + +Anywhere you see transformation of data within a for loop, use the `map()` function to perform the transformation in the functional style. In addition, if the body of the loop has a `if` statement to selectively some value for transformation, then use the `stream()` API with the call to the `filter()` method before using the `map()` method. diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/05_converting_to_streams.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/05_converting_to_streams.md new file mode 100644 index 0000000..6cf4944 --- /dev/null +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/03_refactoring_to_functional_style/05_converting_to_streams.md @@ -0,0 +1,103 @@ +--- +id: refactoring.to.streams +title: Converting Data Sources to Streams +slug: learn/refactoring-to-functional-style/convertingtostreams +type: tutorial-group +group: refactoring-to-functional-style +layout: learn/tutorial-group.html +subheader_select: tutorials +main_css_id: learn +toc: +- Thinking in Streams {streams} +- From Imperative to Functional Style {imperativetofunctional} +- Mappings {mappings} +description: "Converting Data Sources to Streams." +last_update: 2024-03-25 +author: ["VenkatSubramaniam"] +--- + +  +## Thinking in Streams + +In the previous articles in this [tutorial series](id:refactoring) we looked at converting loops written in the imperative style to the functional style. In this article we'll look at viewing the source of data, through the functional eyes, as a stream of data and convert the iteration to use the Streams API. + +We saw how we can use `filter()` and `map()` functions to select and transform data, respectively. We can perform these operations in the middle of the functional pipeline. In the examples in the previous articles we used functions like `range()` and `rangeClosed()` to create a stream of values in a range of numbers. That worked nicely when we want to iterate over a known range of values, but, often we may want to work with data that comes from external resources, like from a file, for example. If we are able to work with the external resource as a stream, then we can readily apply the operations of the functional pipeline. In this article we'll take a look at an example that illustrates that idea. + +  +## From Imperative to Functional Style + +Suppose we want to iterate over a file and count the number of lines with one or more occurrences of a word. Here's an all too familiear imperative style code to accomplish that task: + +```java +//Sample.java +import java.nio.file.*; + +public class Sample { + public static void main(String[] args) { + try { + final var filePath = "./Sample.java"; + final var wordOfInterest = "public"; + + try (var reader = Files.newBufferedReader(Path.of(filePath))) { + String line = ""; + long count = 0; + + while((line = reader.readLine()) != null) { + if(line.contains(wordOfInterest)) { + count++; + } + } + + System.out.println(String.format("Found %d lines with the word %s", count, wordOfInterest)); + } + } catch(Exception ex) { + System.out.println("ERROR: " + ex.getMessage()); + } + } +} + +``` + +In order to make it easy to work with this example, we look for the number of lines with the word "public" in the same source file as the code resides. You may change the value of the `filePath` to refer to a different file and/or the value of the `wordOfInterest` to something else if you like. + + +There are two major parts in this example. We use the `BufferedReader` returned by the `newBufferedReader()` method to access the contents of the file we're interested in looking into. Then, in the `while` loop we check each line to see if it contains the desired word and, if so, increment the `count` to indicate we found another line with the word. Let's examine the two parts, with the second one first. + +Looking closely at the loop, from our discussions in the previous articles, we can recognize that the presence of `if` is a sign that we may use the `filter()` operation if we can write the code as a functional pipeline. Once we filter out or select the lines with the desired word, we can count the number of lines, using the `count()` method of stream. You're most likely curious and bursting to ask, "but, where's the Stream?" To answer that question, let's take a look at the first part of the code. + +The data, that is the lines of text, is coming from the file whose path is provided in the variable `filePath`. We're reading the data using the `BufferedReader`'s `readLine()` method and the imperative style to iterate over each line of text. In order to use the functional pipeline, with the operations like `filter()` we need a `Stream` of data. Hence the question, "is it possible to get a Stream of data for the contents in a file?" + +The answer, thankfully, is a resounding yes. The developers behind the JDK and the Java language did not merely introduce the capability to do functional programming and say "good luck." They took the pains to enhance the JDK to add functions so we, as programmers, can make good use of the functional capabilities of Java for our routine tasks. + +An easy way to turn the contents of a file into a stream of data is using the `lines()` method of the `Files` class that is part of the `java.nio.file` package. Let's refactor the previous imperative style code to the functional style, with the help of the `lines()` method that gives us the `Stream` over the contents of a file, like so: + +```java +//Sample.java +import java.nio.file.*; + +public class Sample { + public static void main(String[] args) { + try { + final var filePath = "./Sample.java"; + final var wordOfInterest = "public"; + + try(var stream = Files.lines(Path.of(filePath))) { + long count = stream.filter(line -> line.contains(wordOfInterest)) + .count(); + + System.out.println(String.format("Found %d lines with the word %s", count, wordOfInterest)); + } + } catch(Exception ex) { + System.out.println("ERROR: " + ex.getMessage()); + } + } +} + +``` + +Not only does the `lines()` method provide a stream of data over the contents of a file, it remove so much of the cruft around reading the lines. Instead of the external iterator where we fetched one line at a time, the stream makes it possible to use the internal iterator where we can focus on what to do for each line of text as it emerges in the stream's pipeline. + +  +## Mappings + +Whenever you're working with a collection of data from an external resource, ask if there is a way to get a stream of data over the contents of that resource. The chances are that you may find a function for that within the JDK or a third-party library. Once we get a stream, we can use the highly effective functional operators like `filter()`, `map()`, etc. to fluently iterate over the collection of data that's part of the resource. diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md index 9007550..129676c 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md @@ -17,7 +17,7 @@ toc: - Precautions {precautions} - Conclusion {conclusion} description: "Working with enums." -last_update: 2023-09-29 +last_update: 2024-07-08 author: ["DanielSchmid"] ---   @@ -32,7 +32,7 @@ No instances of the enum can be created outside of enum constants. ```java public enum DayOfWeek { - // enum constant are listed here: + // enum constants are listed here: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY } ``` @@ -71,11 +71,12 @@ switch (someDay) { } ``` -With [Switch Expressions](id:lang.classes-objects.switch-expression), +With [switch expressions](id:lang.classes-objects.switch-expression), the compiler can check whether all values of the enum are handled. If any possible value is missing in a switch expression, there will be a compiler error. -This is referred to as Exhaustiveness and can also be achieved with regular classes -through [Sealed Classes](https://openjdk.org/jeps/409). +This is referred to as exhaustiveness checking and can also be achieved with regular classes +through [sealed classes](https://openjdk.org/jeps/409) and [pattern matching](/learn/pattern-matching/#switch). + ```java DayOfWeek someDay = DayOfWeek.FRIDAY; @@ -99,7 +100,8 @@ Arguments to the constructor are passed in parenthesis after the declaration of ```java public enum DayOfWeek { - MONDAY("MON"), TUESDAY("TUE"), WEDNESDAY("WED"), THURSDAY("THU"), FRIDAY("FRI"), SATURDAY("SAT"), SUNDAY("SUN"); + MONDAY("MON"), TUESDAY("TUE"), WEDNESDAY("WED"), THURSDAY("THU"), FRIDAY("FRI"), + SATURDAY("SAT"), SUNDAY("SUN"); private final String abbreviation; @@ -140,9 +142,9 @@ This allows for comparing instances of enums as well as sorting or searching. ```java public void compareDayOfWeek(DayOfWeek dayOfWeek){ int comparison = dayOfWeek.compareTo(DayOfWeek.WEDNESDAY); - if ( comparison < 0) { + if (comparison < 0) { System.out.println("It's before the middle of the work week."); - } else if(comparison > 0){ + } else if (comparison > 0) { System.out.println("It's after the middle of the work week."); } else { System.out.println("It's the middle of the work week."); @@ -210,6 +212,6 @@ and reading these configuration files in the program in cases like this.   ## Conclusion -Enums provide a simple and safe way of representing a fixed set of constants while keeping most of the flexibilities of classes. They are another special type of class that can be used to write code that is elegant, readable, and maintainable, and work well with other newer modern features like [Switch Expressions](id:lang.classes-objects.switch-expression). +Enums provide a simple and safe way of representing a fixed set of constants while keeping most of the flexibilities of classes. They are a special type of class that can be used to write code that is elegant, readable, maintainable and works well with other modern Java features like [switch expressions](id:lang.classes-objects.switch-expression). Another special class is the Record class introduced in Java 19. Visit our [records tutorial](id:lang.records) to learn more. -To learn more, visit the javadoc [`java.lang.Enum`](javadoc:Enum). \ No newline at end of file +To learn more about enums, visit the [`java.lang.Enum`](javadoc:Enum) javadoc. \ No newline at end of file diff --git a/app/pages/learn/01_tutorial/04_mastering-the-api/02_invoke/00_methodhandle.md b/app/pages/learn/01_tutorial/04_mastering-the-api/02_invoke/00_methodhandle.md new file mode 100644 index 0000000..ba849ae --- /dev/null +++ b/app/pages/learn/01_tutorial/04_mastering-the-api/02_invoke/00_methodhandle.md @@ -0,0 +1,625 @@ +--- +id: api.invoke +title: "Introduction to Method Handles" +slug: learn/introduction_to_method_handles +type: tutorial +category: api +category_order: 1 +layout: learn/tutorial.html +subheader_select: tutorials +main_css_id: learn +description: "Method handles, how they are different from the Reflection API, and the tooling they provide." +author: ["NataliiaDziubenko"] +toc: + - What are method handles {intro} + - Access checking {access} + - Method handle lookup {lookup} + - Method type {methodtype} + - Method handle invocation {invocation} + - Accessing fields {fields} + - Working with arrays {arrays} + - Exception handling {exceptions} + - Method handle transformations {transformations} + - Method Handles vs Reflection API {vsreflection} + - Conversion between Reflection API and method handles {unreflect} + - Conclusion {conclusion} +last_update: 2024-05-30 +--- + +  +## What are method handles +Method handles are a low-level mechanism used for method lookup and invocation. They are often compared to reflection, +because both the Reflection API and method handles provide a means to invoke methods, constructors, and access fields. + +What exactly is a method handle? It's a directly invocable reference to an underlying method, constructor, or field. +The Method Handle API allows manipulations on top of a simple pointer to the method that allows us to insert or reorder the +arguments, transform the return values, etc. + +Let's take a closer look at what method handles can provide and how we can effectively use them. + +  +## Access checking +The access checking for method handle invocations is done differently compared to the Reflection API. With reflection, +each call results in access checks for the caller. For method handles, the access is only checked when the method handle +is created. + +It is important to keep in mind that if the method handle is created within a context where it can access non-public +members, when passed outside, it can still access those non-public members. As a result, non-public members can +potentially be accessed from code where they shouldn't be accessible. It's a developer's responsibility to keep such +method handles private to their context. Alternatively, the method handle can be created with access limitations right +away using the appropriate lookup object. + +  +## Method handle lookup +To create a method handle we first need to create a [`Lookup`](javadoc:Lookup) object, which acts as a factory for +creating method handles. Depending on how the lookup object itself or the method handles are going to be used, we can +decide whether we should limit its access level. + +For example, if we create a method handle pointing to a private method and that method handle is accessible from the outside, +then the private method is as well. Normally we would like to avoid that. One way is to make the lookup object and method handle +`private` too. Another option is to create the lookup object using the [`MethodHandles.publicLookup`](javadoc:MethodHandles.publicLookup()) +method, so it will only be able to search for public members in public classes within packages that are exported unconditionally: + +```java +MethodHandles.Lookup publicLookup = MethodHandles.publicLookup(); +``` + +If we are going to keep the lookup object and the method handles private, it's safe to give them access to any members, +including private and protected ones: + +```java +MethodHandles.Lookup lookup = MethodHandles.lookup(); +``` + +  +## Method type +To look up a method handle we also need to provide the type information of the method or field. The method +type information is represented as [`MethodType`](javadoc:MethodType) object. To instantiate a `MethodType`, +we have to provide the return type as the first parameter followed by all the argument types: + +```java +MethodType methodType = MethodType.methodType(int.class /* the method returns integer */, + String.class /* and accepts a single String argument*/); +``` + +Having the `Lookup` and the `MethodType` instances, we can look up the method handle. For instance methods, we should +use [`Lookup.findVirtual`](javadoc:MethodHandles.Lookup.findVirtual(Class,String,MethodType)), and for static methods +[`Lookup.findStatic`](javadoc:MethodHandles.Lookup.findStatic(Class,String,MethodType)). Both of these methods accept the +following arguments: a `Class` where the method is located, a method name represented as a `String`, and a `MethodType` +instance. + +In the example below, we are using `Lookup.findVirtual` method to look up an instance method +[`String.replace`](javadoc:String.replace(char,char)), which accepts two `char` arguments and returns a `String`: + +```java +MethodHandles.Lookup lookup = MethodHandles.lookup(); +MethodType replaceMethodType = MethodType.methodType(String.class, char.class, char.class); +MethodHandle replaceMethodHandle = lookup.findVirtual(String.class, "replace", replaceMethodType); +``` + +In the next example, we are using `Lookup.findStatic` to look up a static method +[`String.valueOf`](javadoc:String.valueOf(Object)), which accepts an `Object` and returns a `String`: + +```java +MethodType valueOfMethodType = MethodType.methodType(String.class, Object.class); +MethodHandle valueOfMethodHandle = lookup.findStatic(String.class, "valueOf", valueOfMethodType); +``` + +Similarly, we could use [`Lookup.findConstructor`](javadoc:MethodHandles.Lookup.findConstructor(Class,MethodType)) +method to look up a method handle pointing to any constructor. + +Finally, when we have obtained a method handle, we can invoke the underlying method. + +  +## Method handle invocation +The invocation can also be done in multiple ways. + +All the methods that facilitate invocation eventually funnel down to a single method that is called in the end: +[`MethodHandle.invokeExact`](javadoc:MethodHandle.invokeExact(Object...)). As the method name suggests, the arguments +provided to `invokeExact` method must strictly match the method handle's type. + +For example, if we invoke a `String.replace` method, the arguments must strictly +correspond to a `String` return type and two `char` arguments: + +```java +MethodType replaceMethodType = MethodType.methodType(String.class, char.class, char.class); +MethodHandle replaceMethodHandle = lookup.findVirtual(String.class, "replace", replaceMethodType); +String result = (String) replaceMethodHandle.invokeExact("dummy", 'd', 'm'); +``` + +[`MethodHandle.invoke`](javadoc:MethodHandle.invoke(Object...)) is more permissive. It attempts to obtain a new method +handle with adjusted types that would strictly match the types of provided arguments. After that, it will be able to +invoke the adjusted method handle using `invokeExact`. + +```java +String result = (String) replaceMethodHandle.invoke((Object)"dummy", (Object)'d', (Object)'m'); // would fail with `invokeExact` +``` + +One other alternative to invoke a method handle is to use [`MethodHandle.invokeWithArguments`](javadoc:MethodHandle.invokeWithArguments(Object...)). +The result of this method invocation is equivalent to `invoke`, with the only difference being that all the arguments can be +provided as an array or list of objects. + +One interesting feature of this method is that if the number of provided arguments exceeds the expected number, all the +leftover arguments will be squashed into the last argument, which will be treated as an array. + +  +## Accessing fields +It is possible to create method handles that have read or write access to fields. For instance fields, this is +facilitated by the [`findGetter`](javadoc:MethodHandles.Lookup.findGetter(Class,String,Class)) and +[`findSetter`](javadoc:MethodHandles.Lookup.findSetter(Class,String,Class)) methods, and for static fields, by the +[`findStaticGetter`](javadoc:MethodHandles.Lookup.findStaticGetter(Class,String,Class)) and +[`findStaticSetter`](javadoc:MethodHandles.Lookup.findStaticSetter(Class,String,Class)) methods. We don't need to provide +a `MethodType` instance; instead, we should provide a single type, which is the type of the field. + +For example, if we have a static field `magic` in our `Example` class: + +```java +private static String magic = "initial value static field"; +``` + +Given that we have created a `Lookup` object: + +```java +MethodHandles.Lookup lookup = MethodHandles.lookup(); +``` + +We can simply create both setter and getter method handles and invoke them separately: + +```java +MethodHandle setterStaticMethodHandle = lookup.findStaticSetter(Example.class, "magic", String.class); +MethodHandle getterStaticMethodHandle = lookup.findStaticGetter(Example.class, "magic", String.class); + +setterStaticMethodHandle.invoke("new value static field"); +String staticFieldResult = (String) getterStaticMethodHandle.invoke(); // staticFieldResult == `new value static field` +``` + +Here is an instance field `abc` of class `Example`: + +```java +private String abc = "initial value"; +``` + +We can similarly create method handles for reading and writing to the instance field: + +```java +MethodHandle setterMethodHandle = lookup.findSetter(Example.class, "abc", String.class); +MethodHandle getterMethodHandle = lookup.findGetter(Example.class, "abc", String.class); +``` + +To use setter and getter method handles with an instance field, we must first obtain an instance of the class where the +field belongs: + +```java +Example example = new Example(); +``` + +Afterward, we must provide an instance of `Example` for invocation of our setter and getter: + +```java +setterMethodHandle.invoke(example, "new value"); +String result = (String) getterMethodHandle.invoke(example); // result == `new value` +``` + +Although it is possible to read and write field values using method handles, it's not common practice. For fields, +it's more suitable to use [`VarHandle`](javadoc:VarHandle)s instead, which can be created using +[`findVarHandle`](javadoc:MethodHandles.Lookup.findVarHandle(Class,String,Class)) and +[`findStaticVarHandle`](javadoc:MethodHandles.Lookup.findStaticVarHandle(Class,String,Class)) +methods. + +  +## Working with arrays +The [`MethodHandles`](javadoc:MethodHandles) class contains methods that provide a number of preset method handles. +These include method handles that allow array manipulations. Creating these method handles doesn't require access checking, +so the lookup object is not necessary. + +Let's create an array of Strings containing 5 elements using [`arrayConstructor`](javadoc:MethodHandles.arrayConstructor(Class)): + +```java +MethodHandle arrayConstructor = MethodHandles.arrayConstructor(String[].class); +String[] arr = (String[]) arrayConstructor.invoke(5); +``` + +To modify a single element, we can use [`arrayElementSetter`](javadoc:MethodHandles.arrayElementSetter(Class)), to which +we provide the reference to the target array, the index of an element, and the new value: + +```java +MethodHandle elementSetter = MethodHandles.arrayElementSetter(String[].class); +elementSetter.invoke(arr, 4, "test"); +``` + +To read the value of a single element, we should use [`arrayElementGetter`](javadoc:MethodHandles.arrayElementGetter(Class)) +method handle, to which we provide the reference to an array and the element index: + +```java +MethodHandle elementGetter = MethodHandles.arrayElementGetter(String[].class); +String element = (String) elementGetter.invoke(arr, 4); // element == "test" +``` + +We could also use the method handle provided by [`arrayLength`](javadoc:MethodHandles.arrayLength(Class)) to get the array +length as integer: + +```java +MethodHandle arrayLength = MethodHandles.arrayLength(String[].class); +int length = (int) arrayLength.invoke(arr); // length == 5 +``` + +  +## Exception handling +Both `invokeExact` and `invoke` throw [`Throwable`](javadoc:Throwable), so there is no limitation to what an underlying +method can throw. The method that invokes a method handle must either explicitly throw a `Throwable` or catch it. + +There are certain methods in the `MethodHandles` API that can make exception handling easier. Let's take a look at +several examples. + +### `catch` wrapper +The [`MethodHandles.catchException`](javadoc:MethodHandles.catchException(MethodHandle,Class,MethodHandle)) method can +wrap a given method handle inside a provided exception handler method handle. + +Say, we have a method `problematicMethod` that performs some business logic, and a method `exceptionHandler` that handles +a particular [`IllegalArgumentException`](javadoc:IllegalArgumentException). The exception handler method must +return the same type as the original method. The first argument it accepts is a `Throwable` that we're interested in, +after which follow the rest of the arguments that we've originally accepted: + +```java +public static int problematicMethod(String argument) throws IllegalArgumentException { + if ("invalid".equals(argument)) { + throw new IllegalArgumentException(); + } + return 1; +} + +public static int exceptionHandler(IllegalArgumentException e, String argument) { + // log exception + return 0; +} +``` + +We can look up the method handles for both these methods and wrap `problematicMethod` inside an `exceptionHandler`. The +resulting `MethodHandle` will handle the `IllegalArgumentException` properly on invocation, continuing to throw any +other exceptions if they arise. + +```java +MethodHandles.Lookup lookup = MethodHandles.lookup(); +MethodHandle methodHandle = lookup.findStatic(Example.class, "problematicMethod", MethodType.methodType(int.class, String.class)); +MethodHandle handler = lookup.findStatic(Example.class, "exceptionHandler", + MethodType.methodType(int.class, IllegalArgumentException.class, String.class)); +MethodHandle wrapped = MethodHandles.catchException(methodHandle, IllegalArgumentException.class, handler); + +System.out.println(wrapped.invoke("valid")); // outputs "1" +System.out.println(wrapped.invoke("invalid")); // outputs "0" +``` + +### `finally` wrapper +The [`MethodHandles.tryFinally`](javadoc:MethodHandles.tryFinally(MethodHandle,MethodHandle)) method works similarly, +but instead of an exception handler, it wraps a target method adding a try-finally block. + +Let's say we have a separate method `cleanupMethod` containing cleanup logic. The return type of this method must be the +same as the target method's return type. It must accept a `Throwable` followed by the resulting value coming from the +target method, followed by all the arguments. + +```java +public static int cleanupMethod(Throwable e, int result, String argument) { + System.out.println("inside finally block"); + return result; +} +``` + +We can wrap the method handle from previous example inside the try-finally block as follows: + +```java +MethodHandle cleanupMethod = lookup.findStatic(Example.class, "cleanupMethod", + MethodType.methodType(int.class, Throwable.class, int.class, String.class)); + +MethodHandle wrappedWithFinally = MethodHandles.tryFinally(methodHandle, cleanupMethod); + +System.out.println(wrappedWithFinally.invoke("valid")); // outputs "inside finally block" and "1" +System.out.println(wrappedWithFinally.invoke("invalid")); // outputs "inside finally block" and throws java.lang.IllegalArgumentException +``` + +  +## Method handle transformations +As seen from previous examples, method handles can encapsulate more behavior than simply pointing to an underlying +method. We can obtain **adapter** method handles, which wrap target method handles to add certain behaviors such as +argument reordering, pre-inserting, or filtering of the return values. + +Let's take a look at a couple of such transformations. + +### Type transformation +A method handle's type can be adapted to a new type using the [`asType`](javadoc:MethodHandle.asType(MethodType)) method. +If such type conversion is impossible, we will get a [`WrongMethodTypeException`](javadoc:WrongMethodTypeException). +Remember, when we apply transformations, we actually have two method handles, where the original method handle is wrapped +into some extra logic. In this case, the wrapper will take in the arguments and try to convert them to match the original +method handle's arguments. Once the original method handle does its job and returns a result, the wrapper will attempt to +cast this result to the given type. + +Assume we have a `test` method that accepts an `Object` and returns a `String`. We can adapt such a method to accept a +more specific argument type, such as `String`: + +```java +MethodHandle targetMethodHandle = lookup.findStatic(Example.class, "test", + MethodType.methodType(String.class, Object.class)); +MethodHandle adapter = targetMethodHandle.asType( + MethodType.methodType(String.class, String.class)); +String originalResult = (String) targetMethodHandle.invoke(111); // works +String adapterResult = (String) adapter.invoke("aaaaaa"); // works +adapterResult = (String) adapter.invoke(111); // fails +``` + +In fact, each time we use `invoke` on a `MethodHandle`, the first thing that happens is an `asType` call. `invoke` +accepts and returns `Object`s, which are then attempted to be converted to more specific types. These specific types are +derived from our code, i.e., the exact values that we pass as arguments and the type that we cast our return value to. +Once the types are successfully converted, the `invokeExact` method is then called for these specific types. + +### Permute arguments +To obtain an adapter method handle with reordered arguments, we can use +[`MethodHandles.permuteArguments`](javadoc:MethodHandles.permuteArguments(MethodHandle,MethodType,int...)). + +For example, let's create a `test` method that accepts a bunch of arguments of different types: + +```java +public static void test(int v1, String v2, long v3, boolean v4) { + System.out.println(v1 + v2 + v3 + v4); +} +``` + +And look up a method handle for it: + +```java +MethodHandle targetMethodHandle = lookup.findStatic(Example.class, "test", + MethodType.methodType(void.class, int.class, String.class, long.class, boolean.class)); +``` + +The `permuteArguments` method accepts: +- Target method handle, in our case the one pointing to `test` method; +- New `MethodType` with all the arguments reordered in desired way; +- An index array designating the new order of the arguments. + +```java +MethodHandle reversedArguments = MethodHandles.permuteArguments(targetMethodHandle, + MethodType.methodType(void.class, boolean.class, long.class, String.class, int.class), 3, 2, 1, 0); +reversedArguments.invoke(false, 1L, "str", 123); // outputs: "123str1false" +``` + +### Insert arguments +The [`MethodHandles.insertArguments`](javadoc:MethodHandles.insertArguments(MethodHandle,int,Object...)) method provides +a `MethodHandle` with one or more bound arguments. + +For example, let's look again at the method handle from previous example: + +```java +MethodHandle targetMethodHandle = lookup.findStatic(Example.class, "test", + MethodType.methodType(void.class, int.class, String.class, long.class, boolean.class)); +``` + +We can easily obtain an adapter `MethodHandle` with `String` and `long` arguments bound in advance: + +```java +MethodHandle boundArguments = MethodHandles.insertArguments(targetMethodHandle, 1, "new", 3L); +``` + +To invoke the resulting adapter method handle, we only need to provide the arguments that are not pre-filled: + +```java +boundArguments.invoke(1, true); // outputs: "1new3true" +``` + +If we try to pass the arguments that are already prefilled, we will fail with a `WrongMethodTypeException`. + +### Filter arguments +We can use [`MethodHandles.filterArguments`](javadoc:MethodHandles.filterArguments(MethodHandle,int,MethodHandle...)) +to apply transformations to arguments before invocation of the target method handle. To make it work, we have to provide: + +- The target method handle; +- The position of the first argument to transform; +- Method handles for the transformations of each argument. + +If certain arguments don't require transformation, we can skip them by passing `null`. It's also possible to skip the +rest of the arguments entirely if we only need to transform a subset of them. + +Let's reuse the method handle from the previous section and filter some of its arguments before invocation. + +```java +MethodHandle targetMethodHandle = lookup.findStatic(Example.class, "test", + MethodType.methodType(void.class, int.class, String.class, long.class, boolean.class)); +``` + +Then we create a method that transforms any `boolean` value by negating it: + +```java +private static boolean negate(boolean original) { + return !original; +} +``` + +and also construct a method that increments any given integer value: + +```java +private static int increment(int original) { + return ++original; +} +``` + +We can obtain method handles for these transformation methods: + +```java +MethodHandle negate = lookup.findStatic(Example.class, "negate", MethodType.methodType(boolean.class, boolean.class)); +MethodHandle increment = lookup.findStatic(Example.class, "increment", MethodType.methodType(int.class, int.class)); +``` + +and use them to get a new method handle having filtered the arguments: + +```java +// applies filter 'increment' to argument at index 0, 'negate' to the last argument, +// and passes the result to 'targetMethodHandle' +MethodHandle withFilters = MethodHandles.filterArguments(targetMethodHandle, 0, increment, null, null, negate); +withFilters.invoke(3, "abc", 5L, false); // outputs "4abc5true" +``` + +### Fold arguments +When we want to perform pre-processing of one or more arguments before the invocation of a `MethodHandle`, we +can use [`MethodHandles.foldArguments`](javadoc:MethodHandles.foldArguments(MethodHandle,int,MethodHandle)) and provide +it with the method handle of any combiner method which will accept arguments starting at any preferred position. + +Let's assume that we have a `target` method: + +```java +private static void target(int ignored, int sum, int a, int b) { + System.out.printf("%d + %d equals %d and %d is ignored%n", a, b, sum, ignored); +} +``` + +Using `foldArguments` we can pre-process a subset of its arguments and insert the resulting value as another +argument and proceed to the execution of the `target` method. + +In our example, we have arguments `int a, int b` at the end. We can pre-process any amount of arguments, but they all +must be at the end. Let's say, we would like to calculate a sum of these two values `a` and `b`, so let's create a method +for that: + +```java +private static int sum(int a, int b) { + return a + b; +} +``` + +Where will the resulting value go exactly? It will be inserted into one of the arguments of our `target` method. It must +be the argument right before the arguments that we are going to fold, so in our example argument `int sum`. The argument +reserved for the folding result can't be at any other position. If the `target` method needs to accept more arguments not +related to this folding logic, they all must go first. + +Let's create the method handles and see how we should combine them together: + +```java +MethodHandle targetMethodHandle = lookup.findStatic(Example.class, "target", + MethodType.methodType(void.class, int.class, int.class, int.class, int.class)); +MethodHandle combinerMethodHandle = lookup.findStatic(Example.class, "sum", + MethodType.methodType(int.class, int.class, int.class)); +MethodHandle preProcessedArguments = MethodHandles.foldArguments(targetMethodHandle, 1, combinerMethodHandle); +``` + +The `foldArguments` method accepts: +- `MethodHandle` *target*: The target method handle, in our case the one pointing to the `target` method. +- `int` *pos*: An integer specifying the starting position of arguments related to folding. In our case, the `sum` argument is located at position `1`, so we passed `1`. If we skip this argument, `pos` will default to `0`. +- `MethodHandle` *combiner*: The combiner method handle, in our case the one pointing to the `sum` method. + +At the end, we can invoke the resulting method handle and pass all the arguments except `sum` which is going to be +pre-calculated: + +```java +preProcessedArguments.invokeExact(10000, 1, 2); // outputs: "1 + 2 equals 3 and 10000 is ignored" +``` + +It is possible that the combiner method processes values but doesn't return anything. In this case, there is no need +for a result placeholder in the `target` method argument list. + +### Filter return value +Similarly to arguments, we can use an adapter that will apply transformations to the return value. + +Let's imagine a situation where we have a method that returns a `String`, and we would like to channel any returned +value from this method into another method that replaces character `d` with `m` and uppercases the resulting value. + +Here's the method handle for the `getSomeString` method which always returns the value `"dummy"`: + +```java +MethodHandle getSomeString = lookup.findStatic(Example.class, "getSomeString", MethodType.methodType(String.class)); +``` + +Here's the `resultTransform` method that performs transformations: + +```java +private static String resultTransform(String value) { + return value.replace('d', 'm').toUpperCase(); +} +``` + +Here is the method handle for our transformer method: + +```java +MethodHandle resultTransform = lookup.findStatic(Example.class, "resultTransform", MethodType.methodType(String.class, String.class)); +``` + +Finally, this is the combination of the two method handles where the result returned by the `getSomeString` method is +then provided to the `resultTransform` method and modified accordingly: + +```java +MethodHandle getSomeUppercaseString = MethodHandles.filterReturnValue(getSomeString, resultTransform); +System.out.println(getSomeUppercaseString.invoke()); // outputs: "MUMMY" +``` + +  +## Method Handles vs Reflection API +Method handles were introduced in [JDK7](https://docs.oracle.com/javase/7/docs/index.html) as a tool to assist +compiler and language runtime developers. They were never meant to replace reflection. + +[The Reflection API](id:api.reflection) offers something +that method handles cannot, which is listing the class members and inspecting their properties. Method handles, on the +other hand, can be transformed and manipulated in a way that is not possible with the Reflection API. + +When it comes to method invocation, there are differences related to access checking and security considerations. The +Reflection API performs access checking against every caller, on every call, while for method handles, access is +checked only during construction. This makes invocation through method handles faster than through reflection. +However, certain precautions have to be taken so the method handle is not passed to the code where it shouldn't be +accessible. + +You can learn more about Reflection in [this tutorial](id:api.reflection). + +  +## Conversion between Reflection API and method handles +The `Lookup` object can be used to convert Reflection API objects to behaviorally equivalent method handles, which +provide more direct and efficient access to the underlying class members. + +To create a method handle pointing to a given [`Method`](javadoc:Method) (given that the lookup class has permission to do so), we can +use `unreflect`. + +Let's say we have a `test` method in our `Example` class which accepts a `String` argument and returns a `String`. Using +the Reflection API, we can obtain a `Method` object: + +```java +Method method = Example.class.getMethod("test", String.class); +``` + +With the help of the lookup object, we can [`unreflect`](javadoc:MethodHandles.Lookup.unreflect(Method)) the `Method` +object to obtain a `MethodHandle`: + +```java +MethodHandles.Lookup lookup = MethodHandles.lookup(); +MethodHandle methodHandle = lookup.unreflect(method); +String result = (String) methodHandle.invoke("something"); +``` + +Similarly, given a [`Field`](javadoc:Field) object, we can obtain getter and setter method handles: + +```java +Field field = Example.class.getField("magic"); +MethodHandle setterMethodHandle = lookup.unreflectSetter(field); +MethodHandle getterMethodHandle = lookup.unreflectGetter(field); +setterMethodHandle.invoke("something"); +String result = (String) getterMethodHandle.invoke(); // result == "something" +``` + +Conversion from `MethodHandle` to a [`Member`](javadoc:Member) is also possible, with the condition that no transformations +have been performed to the given `MethodHandle`. + +Let's say we have a method handle pointing directly to a method. We can use the +[`MethodHandles.reflectAs`](javadoc:MethodHandles.reflectAs(Class,MethodHandle)) method to obtain the `Method` object: + +```java +Method method = MethodHandles.reflectAs(Method.class, methodHandle); +``` + +It works similarly for the `Field` object: + +```java +Field field = MethodHandles.reflectAs(Field.class, getterMethodHandle); // same result is achieved by reflecting `setterMethodHandle` +``` + +  +## Conclusion +In this tutorial, we have looked into the method handle mechanism and learned how to efficiently use it. We now know that method handles provide a means for efficient method invocation, but this mechanism is not meant to replace the +Reflection API. + +Method handles offer a performance advantage for method invocation due to a different access checking approach. However, +since access is checked only on method handle creation, method handles should be passed around with caution. + +Unlike the Reflection API, method handles don't provide any tooling for listing class members and inspecting their properties. +On the other hand, the Method Handle API allows us to wrap direct pointers to methods and fields into more complex +logic, such as argument and return value manipulations. \ No newline at end of file diff --git a/app/pages/learn/01_tutorial/04_mastering-the-api/02_modern_io/01_modern_io.md b/app/pages/learn/01_tutorial/04_mastering-the-api/02_modern_io/01_modern_io.md new file mode 100644 index 0000000..5bd0496 --- /dev/null +++ b/app/pages/learn/01_tutorial/04_mastering-the-api/02_modern_io/01_modern_io.md @@ -0,0 +1,274 @@ +--- +id: api.modernio +title: "Common I/O Tasks in Modern Java" +type: tutorial +category: api +category_order: 2 +layout: learn/tutorial.html +subheader_select: tutorials +main_css_id: learn +toc: + - Introduction {introduction} + - Reading Text Files {reading-text-files} + - Writing Text Files {writing-text-files} + - The Files API {the-files-api} + - Conclusion {conclusion} +last_update: 2024-04-24 +description: "This article focuses on tasks that application programmers are likely to encounter, particularly in web applications, such as reading and writing text files, reading text, images, JSON from the web, and more." +author: ["CayHorstmann"] +--- + + +  +## Introduction + +This article focuses on tasks that application programmers are likely to encounter, particularly in web applications, such as: + +* Reading and writing text files +* Reading text, images, JSON from the web +* Visiting files in a directory +* Reading a ZIP file +* Creating a temporary file or directory + +The Java API supports many other tasks, which are explained in detail in the [Java I/O API tutorial](id:api.javaio.overview). + +This article focuses on API improvements since Java 8. In particular: + +* UTF-8 is the default for I/O since Java 18 (since [UTF-8 by Default](jep:400)) +* The [`java.nio.file.Files`](javadoc:Files) class, which first appeared in Java 7, added useful methods in Java 8, 11, and 12 +* [`java.io.InputStream`](javadoc:InputStream) gained useful methods in Java 9, 11, and 12 +* The [`java.io.File`](javadoc:File) and [`java.io.BufferedReader`](javadoc:BufferedReader) classes are now thoroughly obsolete, even though they appear frequently in web searches and AI chats. + +  +## Reading Text Files + +You can read a text file into a string like this: + +```java +String content = Files.readString(path); +``` + +Here, `path` is an instance of [`java.nio.Path`](javadoc:Path), obtained like this: + +```java +var path = Path.of("/usr/share/dict/words"); +``` + +Before Java 18, you were strongly encouraged to specify the character encoding with any file operations that read or write strings. Nowadays, by far the most common character encoding is UTF-8, but for backwards compatibility, Java used the "platform encoding", which can be a legacy encoding on Windows. To ensure portability, text I/O operations needed parameters [`StandardCharsets.UTF_8`](javadoc:StandardCharsets.UTF_8). This is no longer necessary. + +If you want the file as a sequence of lines, call + +```java +List lines = Files.readAllLines(path); +``` + +If the file is large, process the lines lazily as a [`Stream`](javadoc:Stream): + +```java +try (Stream lines = Files.lines(path)) { + . . . +} +``` + +Also use [`Files.lines`](javadoc:Files.lines(Path)) if you can naturally process lines with stream operations (such as [`map`](javadoc:Stream.map(Function)), [`filter`](javadoc:Stream.filter(Predicate))). Note that the stream returned by [`Files.lines`](javadoc:Files.lines(Path)) needs to be closed. To ensure that this happens, use a _try-with-resources_ statement, as in the preceding code snippet. + +There is no longer a good reason to use the [`readLine`](javadoc:BufferedReader.readLine()) method of [`java.io.BufferedReader`](javadoc:BufferedReader). + +To split your input into something else than lines, use a [`java.util.Scanner`](javadoc:Scanner). For example, here is how you can read words, separated by non-letters: + +```java +Stream tokens = new Scanner(path).useDelimiter("\\PL+").tokens(); +``` + +The [`Scanner`](javadoc:Scanner) class also has methods for reading numbers, but it is generally simpler to read the input as one string per line, or a single string, and then parse it. + +Be careful when parsing numbers from text files, since their format may be locale-dependent. For example, the input `100.000` is 100.0 in the US locale but 100000.0 in the German locale. Use [`java.text.NumberFormat`](javadoc:NumberFormat) for locale-specific parsing. Alternatively, you may be able to use [`Integer.parseInt`](javadoc:Integer.parseInt(String))/[`Double.parseDouble`](javadoc:Double.parseDouble(String)). + +  +## Writing Text Files + +You can write a string to a text file with a single call: + +```java +String content = . . .; +Files.writeString(path, content); +``` + +If you have a list of lines rather than a single string, use: + +```java +List lines = . . .; +Files.write(path, lines); +``` + +For more general output, use a [`PrintWriter`](javadoc:PrintWriter) if you want to use the [`printf`](javadoc:PrintWriter.printf()) method: + +```java +var writer = new PrintWriter(path.toFile()); +writer.printf(locale, "Hello, %s, next year you'll be %d years old!%n", name, age + 1); +``` + +Note that [`printf`](javadoc:PrintWriter.printf()) is locale-specific. When writing numbers, be sure to write them in the appropriate format. Instead of using [`printf`](javadoc:PrintWriter.printf()), consider [`java.text.NumberFormat`](javadoc:NumberFormat) or [`Integer.toString`](javadoc:Integer.toString())/[`Double.toString`](javadoc:Double.toString(double)). + +Weirdly enough, as of Java 21, there is no [`PrintWriter`](javadoc:PrintWriter) constructor with a [`Path`](javadoc:Path) parameter. + +If you don't use [`printf`](javadoc:PrintWriter.printf()), you can use the [`BufferedWriter`](javadoc:BufferedWriter) class and write strings with the [`write`](javadoc:BufferedWriter.write(int)) method. + +```java +var writer = Files.newBufferedWriter(path); +writer.write(line); // Does not write a line separator +writer.newLine(); +``` + +Remember to close the `writer` when you are done. + +  +## Reading From an Input Stream + +Perhaps the most common reason to use a stream is to read something from a web site. + +If you need to set request headers or read response headers, use the [`HttpClient`](javadoc:HttpClient): + +```java +HttpClient client = HttpClient.newBuilder().build(); +HttpRequest request = HttpRequest.newBuilder() + .uri(URI.create("https://horstmann.com/index.html")) + .GET() + .build(); +HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); +String result = response.body(); +``` + +That is overkill if all you want is the data. Instead, use: + +```java +InputStream in = new URI("https://horstmann.com/index.html").toURL().openStream(); +``` + +Then read the data into a byte array and optionally turn them into a string: + +```java +byte[] bytes = in.readAllBytes(); +String result = new String(bytes); +``` + +Or transfer the data to an output stream: + +```java +OutputStream out = Files.newOutputStream(path); +in.transferTo(out); +``` + +Note that no loop is required if you simply want to read all bytes of an input stream. + +But do you really need an input stream? Many APIs give you the option to read from a file or URL. + +Your favorite JSON library is likely to have methods for reading from a file or URL. For example, with [Jackson jr](https://github.com/FasterXML/jackson-jr): + +```java +URL url = new URI("https://dog.ceo/api/breeds/image/random").toURL(); +Map result = JSON.std.mapFrom(url); +``` + +Here is how to read the dog image from the preceding call: + +```java +URL url = new URI(result.get("message").toString()).toURL(); +BufferedImage img = javax.imageio.ImageIO.read(url); +``` + +This is better than passing an input stream to the [`read`](javadoc:ImageIO.read(URL)) method, because the library can use additional information from the URL to determine the image type. + +  +## The Files API + +The [`java.nio.file.Files`](javadoc:Files) class provides a comprehensive set of file operations, such as creating, copying, moving, and deleting files and directories. The [File System Basics](id:api.javaio.file_sytem.intro) tutorial provides a thorough description. In this section, I highlight a few common tasks. + +### Traversing Entries in Directories and Subdirectories + +For most situations you can use one of two methods. The [`Files.list`](javadoc:Files.list(Path)) method visits all entries (files, subdirectories, symbolic links) of a directory. + +```java +try (Stream entries = Files.list(pathToDirectory)) { + . . . +} +``` + +Use a _try-with-resources_ statement to ensure that the stream object, which keeps track of the iteration, will be closed. + +If you also want to visit the entries of descendant directories, instead use the method [`Files.walk`](javadoc:Files.walk(Path)) + +```java +Stream entries = Files.walk(pathToDirectory); +``` + +Then simply use stream methods to home in on the entries that you are interested in, and to collect the results: + +```java +try (Stream entries = Files.walk(pathToDirectory)) { + List htmlFiles = entries.filter(p -> p.toString().endsWith("html")).toList(); + . . . +} +``` + +Here are the other methods for traversing directory entries: + +* An overloaded version of [`Files.walk`](javadoc:Files.walk(Path,depth)) lets you limit the depth of the traversed tree. +* Two [`Files.walkFileTree`](javadoc:Files.walkFileTree(Path)) methods provide more control over the iteration process, by notifying a [`FileVisitor`](javadoc:FileVisitor) when a directory is visited for the first and last time. This can be occasionally useful, in particularly for emptying and deleting a tree of directories. See the tutorial [Walking the File Tree](id:api.javaio.file_sytem.walking_tree) for details. Unless you need this control, use the simpler [`Files.walk`](javadoc:Files.walk(Path)) method. +* The [`Files.find`](javadoc:Files.find(Path)) method is just like [`Files.walk`](javadoc:Files.walk(Path)), but you provide a filter that inspects each path and its [`BasicFileAttributes`](javadoc:BasicFileAttributes). This is slightly more efficient than reading the attributes separately for each file. +* Two [`Files.newDirectoryStream(Path)`](javadoc:Files.newDirectoryStream(Path)) methods yields [`DirectoryStream`](javadoc:DirectoryStream) instances, which can be used in enhanced `for` loops. There is no advantage over using [`Files.list`](javadoc:Files.list(Path)). +* The legacy [`File.list`](javadoc:File.list()) or [`File.listFiles`](javadoc:File.listFiles()) methods return file names or [`File`](javadoc:File) objects. These are now obsolete. + +### Working with ZIP Files + +Ever since Java 1.1, the [`ZipInputStream`](javadoc:ZipInputStream) and [`ZipOutputStream`](javadoc:ZipOutputStream) classes provide an API for processing ZIP files. But the API is a bit clunky. Java 8 introduced a much nicer *ZIP file system*: + +```java +try (FileSystem fs = FileSystems.newFileSystem(pathToZipFile)) { + . . . +} +``` + +The _try-with-resources_ statement ensures that the [`close`](javadoc:AutoCloseable.close()) method is called after the ZIP file operations. That method updates the ZIP file to reflect any changes in the file system. + +You can then use the methods of the [`Files`](javadoc:Files) class. Here we get a list of all files in the ZIP file: + +```java +try (Stream entries = Files.walk(fs.getPath("/"))) { + List filesInZip = entries.filter(Files::isRegularFile).toList(); +} +``` + +To read the file contents, just use [`Files.readString`](javadoc:Files.readString(Path)) or [`Files.readAllBytes`](javadoc:Files.readAllBytes(Path)): + +```java +String contents = Files.readString(fs.getPath("/LICENSE")); +``` + +You can remove files with [`Files.delete`](javadoc:Files.delete()). To add or replace files, simply use [`Files.writeString`](javadoc:Files.writeString()) or [`Files.write`](javadoc:Files.write()). + +### Creating Temporary Files and Directories + +Fairly often, I need to collect user input, produce files, and run an external process. Then I use temporary files, which are gone after the next reboot, or a temporary directory that I erase after the process has completed. + +I use the two methods [`Files.createTempFile`](javadoc:Files.createTempFile(String,String,FileAttribute)) and [`Files.createTempDirectory`](javadoc:Files.createTempDirectory(Path,String,FileAttribute...)) for that. + +```java +Path filePath = Files.createTempFile("myapp", ".txt"); +Path dirPath = Files.createTempDirectory("myapp"); +``` + +This creates a temporary file or directory in a suitable location (`/tmp` in Linux) with the given prefix and, for a file, suffix. + +  +## Conclusion + +Web searches and AI chats can suggest needlessly complex code for common I/O operations. There are often better alternatives: + +1. You don't need a loop to read or write strings or byte arrays. +2. You may not even need a stream, reader or writer. +3. Become familiar with the [`Files`](javadoc:Files) methods for creating, copying, moving, and deleting files and directories. +4. Use [`Files.list`](javadoc:Files.list(Path)) or [`Files.walk`](javadoc:Files.walk(Path)) to traverse directory entries. +5. Use a ZIP file system for processing ZIP files. +6. Stay away from the legacy [`File`](javadoc:File) class. + diff --git a/app/pages/learn/01_tutorial/07_rich_client_apps/02_introduction-javafx-animation.md b/app/pages/learn/01_tutorial/07_rich_client_apps/02_introduction-javafx-animation.md new file mode 100644 index 0000000..b147235 --- /dev/null +++ b/app/pages/learn/01_tutorial/07_rich_client_apps/02_introduction-javafx-animation.md @@ -0,0 +1,315 @@ +--- +id: javafx.animation +title: Introduction to JavaFX animations +slug: learn/javafx-animations +type: tutorial +group: rich-client-apps +category: javafx +category_order: 2 +layout: learn/tutorial.html +subheader_select: tutorials +main_css_id: learn +description: "Learn to create advanced JavaFX animations" +last_update: 2024-05-31 +author: ["ConnorSchweighöfer"] +--- +
+ +The [javafx.animation](javafxdoc:AnimationPackageSummary) package offers a simple framework for creating animations and transitions in a JavaFX application. +It operates on the principle of [`WritableValue`](javafxdoc:WritableValue), which is used across JavaFX. `WritableValue` is an interface that wraps a value that can be read and set. +It is commonly used for storing properties in JavaFX UI elements, like `width` or `height` in the [`Rectangle`](javafxdoc:Rectangle) shape. +It additionally provides a variety of built-in transitions for common effects, support for parallel and sequential transitions, and the ability to handle events upon animation completion. + +This article goes through all types of animations, starting with `Animation` and its subclasses `Transition` and `Timeline`, before representing a lower level animation with `AnimationTimer`. +While `Transition` provides a simpler and more user-friendly way to create animations, `Timeline` offers greater flexibility and is suitable for more complex animations. +In contrast, `AnimationTimer` is designed for frame-by-frame updates and does not make use of `WritableValue`. + +## Animation + +The abstract class [`Animation`](javafxdoc:Animation) provides the core functionality for `Transition` and `Timeline` animations and can't be extended directly. + +An `Animation` consists of multiple properties: +- The `targetFramerate` is the maximum framerate (frames per second) at which this `Animation` will run. +- The `currentTime` is the current point in time in the `Animation` as a [`Duration`](javafx:Duration). +- The `rate` defines the direction and speed at which the `Animation` is expected to be played. It supports both positive and negative numbers. +- The `cycleCount` defines the number of cycles of this `Animation`. It can't be changed while running and must be positive. +- The `cycleDuration` is the `Duration` of one cycle of this `Animation`. It is the time it takes to play from start to end of the `Animation` **at the default rate of 1.0**. +- The `totalDuration` indicates the total duration of this `Animation`, including repeats. It is the result of `cycleDuration * cycleCount` or possibly `Duration.INDEFINITE`. +- The `delay` is the `Duration` that delays the `Animation` when starting. +- The `autoReverse` property specifies whether the `Animation` will play in reverse direction on alternating cycles. +- The `onFinished` event handler is used to define additional behavior when the `Animation` finished. +- The `status` represents the current state of the `Animation`, possible states are `PAUSED`, `RUNNING` and `STOPPED`. + +Additionally, it provides several useful methods, like `play()`, `playFrom(String cuePoint)`, `pause()`, `stop()` and more to control the animations flow. +A quick look into [its documentation](javafxdoc:Animation) provides a great overview of its functionalities. + +## Transition +The [`Transition`](javafxdoc:Transition) abstract class serves as the foundational class for all transitions, presenting a common form of `Animation`. +JavaFX provides a variety of built-in transitions for common [`Node`](javafxdoc:Node) and [`Shape`](javafxdoc:Shape) properties. + +### Fade Transition +The [`FadeTransition`](javafxdoc:FadeTransition) creates a fade effect. +This is done by updating the `opacity` property of the `Node` at regular intervals. + +![FadeTransition](/assets/images/javafx/animation/transition/fade-example.gif) +```java +Circle circle = new Circle(150, 150, 20, Color.GREEN); + +FadeTransition transition = new FadeTransition(Duration.seconds(5), circle); +transition.setFromValue(1.0); +transition.setToValue(0); +transition.setInterpolator(Interpolator.LINEAR); + +transition.play(); +``` +(For a complete guide on setting up a JavaFX application, refer to this article: [JavaFX Application Basic Structure By Example](id:javafx.fundamentals.structure)) + +### Fill Transition +The [`FillTransition`](javafxdoc:FillTransition) creates an animation, that changes the filling of a shape. +This is done by updating the `fill` property of the `Shape` at regular intervals. + +![FillTransition](/assets/images/javafx/animation/transition/fill-example.gif) +```java +Circle circle = new Circle(150, 150, 20, Color.GREEN); + +FillTransition transition = new FillTransition(Duration.seconds(5), circle); +transition.setFromValue(Color.GREEN); +transition.setToValue(Color.BLACK); +transition.setInterpolator(Interpolator.LINEAR); + +transition.play(); +``` + +### Translate Transition +The [`TranslateTransition`](javafxdoc:TranslateTransition) creates a move/translate animation from one position to another in a straight line. +This is done by updating the `translateX`, `translateY` and `translateZ` properties of the `Node` at regular intervals. + +![TranslateTransition](/assets/images/javafx/animation/transition/translate-example.gif) +```java +Circle circle = new Circle(50, 50, 10, Color.GREEN); + +TranslateTransition transition = new TranslateTransition(Duration.seconds(5), circle); +transition.setToX(200); +transition.setToY(200); +transition.setInterpolator(Interpolator.LINEAR); + +transition.play(); +``` + +### Path Transition +The [`PathTransition`](javafxdoc:PathTransition) creates a move animation using a complex predefined path specified by a sequence of shapes. +The translation along the path is done by updating the `translateX` and `translateY` properties of the `Node`, and the `rotate` variable will get updated if `orientation` is set to `OrientationType.ORTHOGONAL_TO_TANGENT`, at regular intervals. + +![PathTransition](/assets/images/javafx/animation/transition/path-example.gif) +```java +Circle circle = new Circle(50, 50, 10, Color.GREEN); + +Path path = new Path(); +path.getElements().add(new MoveTo(50, 50)); // starting point +path.getElements().add(new LineTo(250, 250)); + +PathTransition transition = new PathTransition(Duration.seconds(5), path, circle); +transition.setInterpolator(Interpolator.LINEAR); + +transition.play(); +``` + +### Rotate Transition +The [`RotateTransition`](javafxdoc:RotateTransition) creates a rotation animation. +This is done by updating the `rotate` property of the `Node` at regular intervals. +The angle value is specified in degrees. + +![RotateTransition](/assets/images/javafx/animation/transition/rotate-example.gif) +```java +Rectangle rectangle = new Rectangle(125, 125, 50, 50); +rectangle.setFill(Color.GREEN); + +RotateTransition transition = new RotateTransition(Duration.seconds(5), rectangle); +transition.setFromAngle(0); +transition.setToAngle(360); +transition.setInterpolator(Interpolator.LINEAR); + +transition.play(); +``` + +### Scale Transition +The [`ScaleTransition`](javafxdoc:ScaleTransition) creates a scale animation, that changes the size of a node. +This is done by updating the `scaleX`, `scaleY` and `scaleZ` properties of the `Node` at regular intervals. + +![ScaleTransition](/assets/images/javafx/animation/transition/scale-example.gif) +```java +Circle circle = new Circle(150, 150, 50, Color.GREEN); + +ScaleTransition transition = new ScaleTransition(Duration.seconds(5), circle); +transition.setToX(0.1); +transition.setToY(0.1); +transition.setInterpolator(Interpolator.LINEAR); + +transition.play(); +``` + +### Stroke Transition +The [`StrokeTransition`](javafxdoc:StrokeTransition) creates an animation, that changes the stroke color of a shape. +This is done by updating the `stroke` property of the `Shape` at regular intervals. + +![StrokeTransition](/assets/images/javafx/animation/transition/stroke-example.gif) +```java +Circle circle = new Circle(150, 150, 50, Color.GREEN); +circle.setStrokeWidth(5); + +StrokeTransition transition = new StrokeTransition(Duration.seconds(5), circle); +transition.setFromValue(Color.GREEN); +transition.setToValue(Color.BLACK); +transition.setInterpolator(Interpolator.LINEAR); + +transition.play(); +``` + +### Sequential Transition +The [`SequentialTransition`](javafxdoc:SequentialTransition) plays a series of animations in sequential order. +It is not recommended to contain an `Animation` that is not the last one with `Duration.INDEFINITE` as this will block all later animations in the sequence. + +### Pause Transition +The [`PauseTransition`](javafxdoc:PauseTransition) creates a pause for a specified `duration`. +This behavior is useful to create a delay in a `SequentialTransition` in which no properties change. + +![PauseTransition](/assets/images/javafx/animation/transition/pause-example.gif) +```java +Circle circle = new Circle(150, 150, 20, Color.GREEN); +circle.setStrokeWidth(5); + +ScaleTransition smaller = new ScaleTransition(Duration.seconds(1.5)); +smaller.setToX(0.25); +smaller.setToY(0.25); +smaller.setInterpolator(Interpolator.LINEAR); + +ScaleTransition larger = new ScaleTransition(Duration.seconds(1.5)); +larger.setToX(1); +larger.setToY(1); +larger.setInterpolator(Interpolator.LINEAR); + +SequentialTransition transition = new SequentialTransition( + circle, + smaller, + new PauseTransition(Duration.seconds(2)), + larger +); +transition.play(); +``` +Note that this code only sets a `Node` on the `SequentialTransition`, which is the parent transition here, and not on the individual child transitions. +They will implicitly use their parent transition's `Node`. + +### Parallel Transition +The [`ParallelTransition`](javafxdoc:ParallelTransition) plays a group of animations in parallel. + +![ParallelTransition](/assets/images/javafx/animation/transition/parallel-example.gif) +```java +Rectangle rectangle = new Rectangle(50, 50, 10, 10); +rectangle.setFill(Color.GREEN); + +TranslateTransition translate = new TranslateTransition(Duration.seconds(5)); +translate.setToX(200); +translate.setToY(200); +translate.setInterpolator(Interpolator.LINEAR); + +RotateTransition rotate = new RotateTransition(Duration.seconds(5)); +rotate.setFromAngle(0); +rotate.setToAngle(360); +rotate.setInterpolator(Interpolator.LINEAR); + +ParallelTransition transition = new ParallelTransition(rectangle, translate, rotate); +transition.play(); +``` + +## Timeline +A [`Timeline`](javafxdoc:Timeline) is used to define a free form `Animation` on any `WritableValue`. It is helpful if none of the built-in transitions operate on the required properties. +It consists of a sequential series of `KeyFrame`s, each of which encapsulates a moment in time. Collectively they specify how target properties evolve over the entire duration. + +> **Warning:** A running `Timeline` is being referenced from the FX runtime. In an infinite timeline, +> the objects with animated properties would not be garbage collected, which might result in a memory leak. +> Therefore, ensure you stop the timeline instance when it is no longer needed. + +### KeyFrame +A [`KeyFrame`](javafxdoc:KeyFrame) represents a specific moment in an animation sequence (**Cue Point**) and comprises a collection of `KeyValue` instances that change over the given `Duration`. +A KeyFrame can have a name which then can be used to identify this `KeyFrame` in an animation, for example for starting from this specific `KeyFrame` using `playFrom(String cuePoint)`. +It is also possible to provide an `onFinished` implementation, which will be invoked when hitting this cue point. + +### KeyValue +A [`KeyValue`](javafxdoc:KeyValue) establishes a mapping between a `WritableValue` and a target value of type `T`. This is used to define the change of a value. +An `Interpolator` can be additionally defined to set the rate of change for this value. The `KeyValue` class is immutable. + +### Example +This example of `Timeline` creates a `Circle` which moves 200px in x direction over the duration of 5 seconds: + +![TimelineExample](/assets/images/javafx/animation/timeline-example.gif) +```java +Circle circle = new Circle(50, 150, 10, Color.GREEN); + +KeyValue x = new KeyValue(circle.translateXProperty(), 200); +KeyFrame frame = new KeyFrame(Duration.seconds(5), x); +Timeline timeline = new Timeline(frame); + +timeline.play(); +``` + +## Interpolator +The [`Interpolator`](javafxdoc:Interpolator) abstract class defines the rate of change at which values change over time, influencing the smoothness of animations. +There are several built-in implementations for common interpolation techniques. + +**Note:** By default, all transitions, excluding `ParallelTransition` and `SequentialTransition`, utilize the `Interpolator#EASE_BOTH`. + +Here is a visualization of the `Interpolator` using the example from [`Timeline`](#example): + +### Discrete +The [`Interpolator.DISCRETE`](javafxdoc:Interpolator.DISCRETE) interpolator creates a **sudden** transition between values without any intermediate steps. + +![Discrete](/assets/images/javafx/animation/interpolator/discrete-example.gif) + +```java +Circle circle = new Circle(50, 150, 10, Color.GREEN); + +KeyValue x = new KeyValue(circle.translateXProperty(), 200, Interpolator.DISCRETE); +KeyFrame frame = new KeyFrame(Duration.seconds(5), x); +Timeline timeline = new Timeline(frame); + +timeline.play(); +``` +### Linear +The [`Interpolator.LINEAR`](javafxdoc:Interpolator.LINEAR) interpolator produces a **constant** rate of change between values over time. + +![Linear](/assets/images/javafx/animation/interpolator/linear-example.gif) + +### Ease In +The [`Interpolator.EASE_IN`](javafxdoc:Interpolator.EASE_IN) interpolator starts the animation slowly and accelerates as it progresses. + +![EaseIn](/assets/images/javafx/animation/interpolator/ease-in-example.gif) + +### Ease Out +The [`Interpolator.EASE_OUT`](javafxdoc:Interpolator.EASE_OUT) interpolator starts quickly and slows down as it progresses. + +![EaseOut](/assets/images/javafx/animation/interpolator/ease-out-example.gif) + +### Ease Both +The [`Interpolator.EASE_BOTH`](javafxdoc:Interpolator.EASE_BOTH) interpolator starts slowly, accelerates in the middle and slows down towards the end. +It combines the characteristics of `EASE_IN` and `EASE_OUT`. + +![EaseBoth](/assets/images/javafx/animation/interpolator/ease-both-example.gif) + +Additionally, there are two static factory methods for [`Interpolator.SPLINE`](javafxdoc:Interpolator.SPLINE) and [`Interpolator.TANGENT`](javafxdoc:Interpolator.TANGENT) interpolation. + +## Animation Timer + +The [`AnimationTimer`](javafxdoc:AnimationTimer) abstract class provides the lowest level option to create an animation. +The `handle(long now)` method gets called in each frame while it is active. The timestamp `now` is the time of the current frame in nanoseconds and will be the same for all `AnimationTimer`s called during that frame. +Additionally, the `AnimationTimer` adds `start()` and `stop()` methods to handle the lifetime of the animation. + +**Note:** The `handle` method will be called in the **JavaFX Application Thread**, so it should avoid long-running and blocking operations. +To maintain a smooth frame rate of 30 frames per second, the whole JavaFX application ideally allocates no more than 33 milliseconds per frame. + + +## Conclusion +In this tutorial, you've explored the `javafx.animation` package and learned how to create dynamic animations within JavaFX applications. +We started by understanding the base `Animation` class, and then moved on to `Transition` and `Timeline` classes, which provide different ways +to create and control animations. Additionally, you have learnt how to control the progression of an animation via several `Interpolator` examples. +Finally, we covered the `AnimationTimer` class, which allows for animations with precise frame-by-frame updates. With these tools, you are now +equipped to create rich animations in your JavaFX applications. diff --git a/app/pages/learn/01_tutorial/08_more-resources/01_java-certification-overview.md b/app/pages/learn/01_tutorial/08_more-resources/01_java-certification-overview.md index 5c98d12..e4a0140 100644 --- a/app/pages/learn/01_tutorial/08_more-resources/01_java-certification-overview.md +++ b/app/pages/learn/01_tutorial/08_more-resources/01_java-certification-overview.md @@ -74,6 +74,6 @@ Your study materials will give your more details on what you specifically need t   ## How to study? -If you subscribe to Oracle University, there is a [24 hour video class](https://mylearn.oracle.com/ou/learning-path/become-a-java-se-17-developer/99487y). If not, there are two books: [Wiley's Sybex imprint](https://www.amazon.com/Oracle-Certified-Professional-Developer-Certification/dp/111986464X) (disclosure: I wrote this) and [McGraw-Hill's Oracle imprint](https://www.amazon.com/Certified-Professional-Developer-1Z0-829-Programmers/dp/0137993641). +If you subscribe to Oracle University, there is a [24 hour video class](https://mylearn.oracle.com/ou/learning-path/become-a-java-se-17-developer/99487y). If not, there are two books: [Wiley's Sybex imprint](https://www.amazon.com/Oracle-Certified-Professional-Developer-Certification/dp/111986464X) (disclosure: I wrote this) and [Pearson/Oracle Press](https://www.amazon.com/Certified-Professional-Developer-1Z0-829-Programmers/dp/0137993641). Regardless of which option you chose to study, I recommend the [Enthuware mock exams](https://enthuware.com/java-certification-mock-exams/oracle-certified-professional/ocp-java-17-exam-1z0-829). They are only $10 and you get 20 mock exams! Excellent practice after you study to get ready. The OCP forum at [CodeRanch](https://coderanch.com/f/24/java-programmer-OCPJP) is also a great place to ask questions as you prepare for your certification. diff --git a/app/pages/learn/01_tutorial/08_more-resources/02_debugging.md b/app/pages/learn/01_tutorial/08_more-resources/02_debugging.md new file mode 100644 index 0000000..3fd908f --- /dev/null +++ b/app/pages/learn/01_tutorial/08_more-resources/02_debugging.md @@ -0,0 +1,138 @@ +--- +id: debugging +title: Debugging in Java +slug: learn/debugging +type: tutorial +category: resources +layout: learn/tutorial.html +subheader_select: tutorials +main_css_id: learn +toc: +- What is debugging? {intro} +- Why not println? {println} +- Why not unit testing? {unit} +- What is a breakpoint? {breakpoint} +- How can debuggers be used? {usage} +- Debugger basics {basic} +- Advanced techniques {advanced} +- Documentation {docs} +description: "Learning how to use a debugger" +last_update: 2023-11-05 +author: ["JeanneBoyarsky"] +--- + +  +## What is debugging? + +We all write perfect code that works on the first attempt, right? Ha! Just kidding. We often have to find and fix errors in our code. This process is called debugging. + +You might be wondering why it is called "debugging". The term became popular in the 1940s after Admiral Grace Hopper found a moth inside a computer (remember computers were giant back then so an actual insect could get in.) While you won't have to deal with animals in your code, we will have to deal with errors and problems that we refer to as bugs. You may also hear them called defects although that's usually after you've committed the code. Regardless of the name of the issue, you still have to find that problem and that's debugging! + +A debugger is a tool in your IDE (integrated development environment) that lets you see the values of different variables at different points in the program. It's like a really powerful magnifying glass. While a few details vary between Eclipse/IntelliJ/NetBeans/VS Code, the concepts are the same. + +When you run your code, you can choose to launch it in regular/run mode or debug mode. This allows you to deicde when you want to debug. + +  +## Why not Println? + +When first learning how to code, we often write code like this to see what is going on: + +```java +System.out.println(numCats); +``` + +There's nothing wrong with using `println` (as long as you don't commit it). However, it can quickly get unmanagable in a more complicated program especally if you have multiple things to keep track of or a lot of loops. It can also be hard to find when there is a lot of logging in the application. (I used the stars and my initials to mitigate that, but still can get past the point where `println` is useful.) + +```java +System.out.println("*** JB i=%s numCats=%s numDogs=%s".formatted(i, numCats, numDogs)); +``` + +Even if `println()` does meet your needs at the moment, it won't forever. Learning how to use a debugger helps avoid the problem that you use println just because it is all you know. + +  +## Why not unit testing? + +Unit testing is writing code to test small pieces of code at the click of a button. Nothing is wrong with unit testing. Unit tests are great. They document expected behavior. They tell you if an unexpected value is returned. They help you understand the behavior of the code. And sometimes they can even give you big clues about what is wrong with the code. However, they don't tell you what is happening inside the broken code when it isn't returning the right value. For that, you use a debugger with the unit test to see what is going on inside the method. And once you fix your code, unit tests can help catch new bugs from being introduced! + +```java +@Test +void magic() { + assertEquals(42, target.magic(), "magic number incorrect"); +} +``` + +  +## What is a breakpoint? + +I've (improperly) implemented the magic method. It's supposed to multiply six times seven and get 42. However, that's not what happens. After (not) much investigation, I am baffled and realize I want to know what the values of `part1` and `part2` are on line 5. + +That's what a breakpoint is for. It lets me tell the debugger to pause the program there and let me poke around. How do I set a breakpoint you ask? In the left bar near your code, you can double click (or right click and chose to turn on the breakpoint.) A little circle will appear showing the breakpoint I set. + +```java +public class Answer { + public int magic() { + int part1 = 3 + 2; // BUG! + int part2 = 7; + return part1 * part2; + } +} +``` + +It is important to run the program in debug mode for the breakpoints to take effect. (Remember, if you don't run in debug mode, all breakpoints are ignored.) When the debugger stops on line 5, I see that `part2` is the seven that I expected. However `part1` is five, not six. I found the bug! Thanks to the debugger allowing me to set a breakpoint. + +  +## How can debuggers be used? + +There are a number of reasons why you might want to use a debugger. Three of the most common are: + +1. Fixing broken code - The debugger allows you to see the values of variables as the code runs. This allows you to see where it stops behaving as expected. +2. Understanding unfamiliar code - Watching the values of each variable as the code runs can help you understand it better. +3. Tracing the path of the code - When stopping at a breakpoint, the debugger shows what classes/methods were called in order to get there. You can even click on them to see what the variables in scope at those points are. + +  +## Debugger Basics + +There are four basic debugger commands to control the flow of execution once the debugger stops at your first breakpoint. For each of these commands, we will use the `Flow` class as an example. + +```java +public class Flow { + public static void main(String args[]) { + System.out.println(debugging()); + } + + public static int debugging() { + int num = investigate(); + num++; + return num; + } + + public static int investigate() { + int found = 5; + return found; + } +} +``` + +1. Step into - Tells the program to execute, but only to the first line of the method call. Suppose I have a breakpoint on line 7. When I tell the debugger to "step into", it goes to line 13. +2. Step over - Tells the program to execute but not stop in any methods. If I have a breakpoint on line 7 and tell the debugger to "step over", the debugger will then be on line 8. Choosing "step over" again will bring the debugger to line 9. +3. Step out/return - Tells the program to run to the end of the method and go back to the caller. If I have a breakpoint on line 13 and choose "step out" or "step return", the debugger will be on line 7 with the result from the method call. (Step out and step return are the same thing. Different IDEs use different names.) +4. Resume - Tells the program to keep going until it hits another breakpoint or completes. + +  +## Advanced Techniques + +Debuggers have many advanced techniques. Three common ones are: + +1. Conditional breakpoint - Normally, the debugger stops where you asked for a breakpoint. If you are in a loop or have a clue what values trigger the problem, you don't want that. A conditional breakpoint allows you to add a bit of Java code to your breakpoint so it will only stop when that condition is true. This approach avoids having to hit resume a lot of times until you get to the value you care about. +2. Evaluation - Once you get to your breakpoint, you can write Java code to determine the state of affairs. For example, you can call methods on the available variables. +3. Changing data - You can manually change the value of a variable in the debugger and let the code continue to run. It will use your new, updated value instead of the original one. This lets you explore the impact of a potential fix. + +  +## Documentation + +Now that you know the concepts of using a debugger, it is time to look at the documentation for your IDE! Pay attention to the keyboard shortcuts and where each button is located. + +1. [Eclipse](https://www.eclipse.org/community/eclipse_newsletter/2017/june/article1.php) +2. [IntelliJ](https://www.jetbrains.com/help/idea/debugging-your-first-java-application.html) +3. [NetBeans](https://netbeans.apache.org/tutorial/main/kb/docs/java/debug-visual/) +4. [VS Code](https://code.visualstudio.com/docs/java/java-debugging) \ No newline at end of file diff --git a/gulpfile.js b/gulpfile.js index b70b57a..81d9800 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -27,6 +27,7 @@ for (const author of authorsArray) { var javadoc = require('./app/data/javadoc.json') var javafxdoc = require('./app/data/javafxdoc.json') +var jep = require('./app/data/jep.json') function getAuthorID(name) { @@ -226,9 +227,9 @@ function pages() { if (href.includes("javafxdoc:")) { let javafxdoc_id = href.match(/javafxdoc:([\w\.\-(),]+)/) if (javafxdoc_id != null) { - processedHref = processDocLink(javafxdoc["javafxdoc_root"] + javafxdoc[javafxdoc_id[1]]); + processedHref = processJavaFxDocLink(javafxdoc["javafxdoc_root"] + javafxdoc[javafxdoc_id[1]]); if (processedHref.includes("undefined")) { - console.log("Javadoc " + javafxdoc_id[1] + " resolved to undefined"); + console.log("JavaFX Javadoc " + javafxdoc_id[1] + " resolved to undefined"); } return `${text}`; } @@ -251,7 +252,37 @@ function pages() { } } + if (href.includes("jep:")) { + let jep_id = href.match(/jep:([\d]+)/); + if (jep_id != null) { + if (jep[jep_id[1]] == undefined) { + console.log("JEP " + jep_id[1] + " is not defined"); + } else { + processedHref = jep["root"] + jep_id[1]; + let anchor = href.match(/#[\w|-]+/); + if (anchor) { + processedHref = processedHref + anchor; + } + if (jep[jep_id[1]]["status"] == "preview" && jep[jep_id[1]]["version"] != javadoc["current_release"]) { + console.log( + "Current release is " + javadoc["current_release"] + ", JEP " + jep_id[1] + + " is a preview of " + jep[jep_id[1]]["version"] + " and still referenced"); + } + if (jep[jep_id[1]]["status"] == "incubator" && jep[jep_id[1]]["version"] != javadoc["current_release"]) { + console.log( + "Current release is " + javadoc["current_release"] + ", JEP " + jep_id[1] + + " is an incubator of " + jep[jep_id[1]]["version"] + " and still referenced"); + } + if (jep[jep_id[1]]["title"]) { + text = "JEP " + jep_id[1] + ": " + jep[jep_id[1]]["title"]; + } else { + text = "JEP " + jep_id[1] + ": " + jep[jep_id[1]]; + } + return `${text}`; + } + } + } if (title) { link = `${text}`; @@ -402,6 +433,10 @@ function processDocLink(link) { return link.replace("@@CURRENT_RELEASE@@", javadoc[`current_release`]); } +function processJavaFxDocLink(link) { + return link.replace("@@CURRENT_RELEASE@@", javafxdoc[`current_release`]).replace("@@RELEASE_UUID@@", javafxdoc[`release_uuid`]); +} + function is_tutorial(file) { return file.fm.type == "tutorial" || file.fm.type == "tutorial-group"; @@ -415,10 +450,10 @@ function serve(done) { } }); - watch("app/**/*.md", {}, series(build)); - watch("app/**/*.html", {}, series(build)); - watch("app/scss/*.scss", {}, series(build)); - watch("site/**/", {}, browserSync.reload()); + watch("app/**/*.md", {interval: 1000, usePolling: true}, series(build)); + watch("app/**/*.html", {interval: 1000, usePolling: true}, series(build)); + watch("app/scss/*.scss", {interval: 1000, usePolling: true}, series(build)); + watch("site/**/", {interval: 1000, usePolling: true}, browserSync.reload()); done(); }