From 4186d2c81db3ee3d5aab2a6ef19e024e7d20f051 Mon Sep 17 00:00:00 2001 From: Matthias Kurz Date: Wed, 2 Jun 2021 09:50:37 +0200 Subject: [PATCH] Remove play-enhancer from docs, project is dead --- documentation/build.sbt | 2 - .../release24/migration24/Migration24.md | 2 +- .../manual/working/commonGuide/build/Build.md | 1 - .../working/commonGuide/build/PlayEnhancer.md | 52 ------------------- .../commonGuide/build/code/enhancer.sbt | 22 -------- .../working/commonGuide/build/index.toc | 1 - .../working/javaGuide/main/forms/JavaForms.md | 2 - .../working/javaGuide/main/tests/JavaTest.md | 2 - documentation/project/plugins.sbt | 3 -- 9 files changed, 1 insertion(+), 86 deletions(-) delete mode 100644 documentation/manual/working/commonGuide/build/PlayEnhancer.md delete mode 100644 documentation/manual/working/commonGuide/build/code/enhancer.sbt diff --git a/documentation/build.sbt b/documentation/build.sbt index de80bdcad19..618d76e48f5 100644 --- a/documentation/build.sbt +++ b/documentation/build.sbt @@ -4,7 +4,6 @@ import com.typesafe.play.docs.sbtplugin.Imports._ import com.typesafe.play.docs.sbtplugin._ -import com.typesafe.play.sbt.enhancer.PlayEnhancer import play.core.PlayVersion import playbuild.JavaVersion import playbuild.CrossJava @@ -16,7 +15,6 @@ val DocsApplication = config("docs").hide lazy val main = Project("Play-Documentation", file(".")) .enablePlugins(PlayDocsPlugin, SbtTwirl) - .disablePlugins(PlayEnhancer) .settings( // Avoid the use of deprecated APIs in the docs scalacOptions ++= Seq("-deprecation"), diff --git a/documentation/manual/releases/release24/migration24/Migration24.md b/documentation/manual/releases/release24/migration24/Migration24.md index 8f71196aa49..1ccb2dcc41f 100644 --- a/documentation/manual/releases/release24/migration24/Migration24.md +++ b/documentation/manual/releases/release24/migration24/Migration24.md @@ -116,7 +116,7 @@ Additionally, Ebean has been upgraded to 4.5.x, which pulls in a few of the feat ### Bytecode enhancement -[[Play's bytecode enhancement|PlayEnhancer]], which generates getters and setters for Java properties, has been pulled out of the core of Play into a separately managed project that can have its own lifecycle. To enable it, add the following to your `project/plugins.sbt` file: +Play's bytecode enhancement, which generates getters and setters for Java properties, has been pulled out of the core of Play into a separately managed project that can have its own lifecycle. To enable it, add the following to your `project/plugins.sbt` file: ```scala addSbtPlugin("com.typesafe.sbt" % "sbt-play-enhancer" % "1.1.0") diff --git a/documentation/manual/working/commonGuide/build/Build.md b/documentation/manual/working/commonGuide/build/Build.md index 30fcb93d056..3f05ec9fcdb 100644 --- a/documentation/manual/working/commonGuide/build/Build.md +++ b/documentation/manual/working/commonGuide/build/Build.md @@ -7,7 +7,6 @@ This section gives details about Play's build system. - [[About sbt settings|sbtSettings]] - [[Manage application dependencies|sbtDependencies]] - [[Working with sub-projects|sbtSubProjects]] -- [[Play enhancer|PlayEnhancer]] - [[Aggregating reverse routers|AggregatingReverseRouters]] - [[Improving Compilation Times|CompilationSpeed]] - [[Cookbook|sbtCookbook]] diff --git a/documentation/manual/working/commonGuide/build/PlayEnhancer.md b/documentation/manual/working/commonGuide/build/PlayEnhancer.md deleted file mode 100644 index b1ce87bdacc..00000000000 --- a/documentation/manual/working/commonGuide/build/PlayEnhancer.md +++ /dev/null @@ -1,52 +0,0 @@ - -# Play enhancer - -The [Play enhancer](https://github.com/playframework/play-enhancer) is an sbt plugin that generates getters and setters for Java beans, and rewrites the code that accesses those fields to use the getters and setters. - -## Motivation - -One common criticism of Java is that simple things require a lot of boilerplate code. One of the biggest examples of this is encapsulating fields - it is considered good practice to encapsulate the access and mutation of fields in methods, as this allows future changes such as validation and generation of the data. In Java, this means making all your fields private, and then writing getters and setters for each field, a typical overhead of 6 lines of code per field. - -Furthermore, many libraries, particularly libraries that use reflection to access properties of objects such as ORMs, require classes to be implemented in this way, with getters and setters for each field. - -The Play enhancer provides a convenient alternative to manually implementing getters and setters. It implements some post processing on the compiled byte code for your classes, this is commonly referred to as byte code enhancement. For every public field in your classes, Play will automatically generate a getter and setter, and then will rewrite the code that uses these fields to use the getters and setters instead. - -### Drawbacks - -Using byte code enhancement to generating getters and setters is not without its drawbacks however. Here are a few: - -* Byte code enhancement is opaque, you can't see the getters and setters that are generated, so when things go wrong, it can be hard to debug and understand what is happening. Byte code enhancement is ofter described as being "magic" for this reason. -* Byte code enhancement can interfere with the operation of some tooling, such as IDEs, as they will be unaware of the eventual byte code that gets used. This can cause problems such as tests failing when run in an IDE because they depend on byte code enhancement, but the IDE isn't running the byte code enhancer when it compiles your source files. -* Existing Java developers that are new to your codebase will not expect getters and setters to be generated, this can cause confusion. - -Whether you use the Play enhancer or not in your projects is up to you, if you do decide to use it the most important thing is that you understand what the enhancer does, and what the drawbacks may be. - -## Setting up - -To enable the byte code enhancer, simply add the following line to your `project/plugins.sbt` file: - -@[plugins.sbt](code/enhancer.sbt) - -The Play enhancer should be enabled for all your projects. If you want to disable the Play enhancer for a particular project, you can do that like so in your `build.sbt` file: - -@[disable-project](code/enhancer.sbt) - -In some situations, it may not be possible to disable the enhancer plugin, an example of this is using Play's ebean plugin, which requires the enhancer to ensure that getters and setters are generated before it does its byte code enhancement. If you don't want to generate getters and setters in that case, you can use the `playEnhancerEnabled` setting: - -@[disable-enhancement](code/enhancer.sbt) - -## Operation - -The enhancer looks for all fields on Java classes that: - -* are public -* are non static -* are non final - -For each of those fields, it will generate a getter and a setter if they don't already exist. If you wish to provide a custom getter or setter for a field, this can be done by just writing it, the Play enhancer will simply skip the generation of the getter or setter if it already exists. - -## Configuration - -If you want to control exactly which files get byte code enhanced, this can be done by configuring the `sources` task scoped to the `playEnhancerGenerateAccessors` and `playEnhancerRewriteAccessors` tasks. For example, to only enhance the java sources in the models package, you might do this: - -@[select-generate](code/enhancer.sbt) diff --git a/documentation/manual/working/commonGuide/build/code/enhancer.sbt b/documentation/manual/working/commonGuide/build/code/enhancer.sbt deleted file mode 100644 index 79d4b196915..00000000000 --- a/documentation/manual/working/commonGuide/build/code/enhancer.sbt +++ /dev/null @@ -1,22 +0,0 @@ -// -// Copyright (C) Lightbend Inc. -// - -//#plugins.sbt -addSbtPlugin("com.typesafe.sbt" % "sbt-play-enhancer" % "1.2.2") -//#plugins.sbt - -//#disable-project -lazy val nonEnhancedProject = (project in file("non-enhanced")) - .disablePlugins(PlayEnhancer) -//#disable-project - -//#disable-enhancement -playEnhancerEnabled := false -//#disable-enhancement - -//#select-generate -sources in (Compile, playEnhancerGenerateAccessors) := { - ((javaSource in Compile).value / "models" ** "*.java").get -} -//#select-generate diff --git a/documentation/manual/working/commonGuide/build/index.toc b/documentation/manual/working/commonGuide/build/index.toc index ddbf473975f..d6b28f3e14e 100644 --- a/documentation/manual/working/commonGuide/build/index.toc +++ b/documentation/manual/working/commonGuide/build/index.toc @@ -3,7 +3,6 @@ BuildOverview:Overview of the build system sbtSettings:About sbt settings sbtDependencies:Manage application dependencies sbtSubProjects:Working with sub-projects -PlayEnhancer:Play enhancer AggregatingReverseRouters:Aggregating reverse routers CompilationSpeed:Improving Compilation Times sbtCookbook:Cookbook diff --git a/documentation/manual/working/javaGuide/main/forms/JavaForms.md b/documentation/manual/working/javaGuide/main/forms/JavaForms.md index 0efa018e284..a66de089e17 100644 --- a/documentation/manual/working/javaGuide/main/forms/JavaForms.md +++ b/documentation/manual/working/javaGuide/main/forms/JavaForms.md @@ -1,8 +1,6 @@ # Handling form submission -Before you start with Play forms, read the documentation on the [[Play enhancer|PlayEnhancer]]. The Play enhancer generates accessors for fields in Java classes for you, so that you don't have to generate them yourself. You may decide to use this as a convenience. All the examples below show manually writing accessors for your classes. - ## Enabling/Disabling the forms module By default, Play includes the Java forms module (`play-java-forms`) when enabling the `PlayJava` sbt plugin, so there is nothing to enable if you already have `enablePlugins(PlayJava)` on your project. diff --git a/documentation/manual/working/javaGuide/main/tests/JavaTest.md b/documentation/manual/working/javaGuide/main/tests/JavaTest.md index 7962c5b6709..38a0ad6f3bf 100644 --- a/documentation/manual/working/javaGuide/main/tests/JavaTest.md +++ b/documentation/manual/working/javaGuide/main/tests/JavaTest.md @@ -80,8 +80,6 @@ In this way, the `UserService.isAdmin` method can be tested by mocking the `User @[test-model-test](code/javaguide/tests/ModelTest.java) -> **Note:** Applications using Ebean ORM may be written to rely on Play's automatic getter/setter generation. If this is your case, check how [[Play enhancer sbt plugin|PlayEnhancer]] works. - ## Unit testing controllers You can test your controllers using Play's [test helpers](api/java/play/test/Helpers.html) to extract useful properties. diff --git a/documentation/project/plugins.sbt b/documentation/project/plugins.sbt index 75409e6c4cb..676fee926be 100644 --- a/documentation/project/plugins.sbt +++ b/documentation/project/plugins.sbt @@ -10,9 +10,6 @@ lazy val playDocsPlugin = ProjectRef(Path.fileProperty("user.dir").getParentFile // Required for Production.md addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.14.5") -// Required for PlayEnhancer.md -addSbtPlugin("com.typesafe.sbt" % "sbt-play-enhancer" % "1.2.2") - // Add headers to example sources addSbtPlugin("de.heikoseeberger" % "sbt-header" % "5.2.0") addSbtPlugin("com.lightbend.sbt" % "sbt-java-formatter" % "0.5.1")