Changes for Eclipse compatibility, related README update
Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/b63e4488 Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/b63e4488 Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/b63e4488 Branch: refs/heads/3 Commit: b63e44880f65d50f5088fb2877b871151d0da959 Parents: 5c65373 Author: ddekany <[email protected]> Authored: Wed Sep 6 17:41:59 2017 +0200 Committer: ddekany <[email protected]> Committed: Wed Sep 6 17:41:59 2017 +0200 ---------------------------------------------------------------------- README.md | 63 ++++---- build.gradle | 8 +- freemarker-servlet/build.gradle | 18 +-- .../servlet/DummyMockServletContext.java | 142 ++++++++++++++++++- 4 files changed, 192 insertions(+), 39 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/b63e4488/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index 2380c2b..db0c623 100644 --- a/README.md +++ b/README.md @@ -142,24 +142,25 @@ IDE setup ### Eclipse -Last tested Eclipse Neon.1. +Last tested Eclipse Oxygen (4.7.0) +- First, build the project with Gradle if you haven't yet (see earlier how). - Start Eclipse -- You may prefer to start a new workspace (File -> "Switch workspace"), but - it's optional. +- Start a new workspace (File -> "Switch workspace") - Window -> Preferences - General -> Workspace, set the text file encoding to "UTF-8". (Or, you can set the same later on project level instead.) - - General -> Editors, set: + - General -> Editors -> Text Editors, set: - Insert space for tabs - Show print margin, 120 columns - Java -> Code Style -> Formatter -> Import... - Select src\ide-settings\Eclipse\Formatter-profile-FreeMarker.xml - inside the FreeMarker project directory. - This profile uses space-only indentation policy and 120 character line - width, and formatting rules that are pretty much standard in modern Java. + Select `src\ide-settings\Eclipse\Formatter-profile-FreeMarker.xml` + inside the FreeMarker project directory. That select "FreeMarker" as the + "Active profile". + (This profile uses space-only indentation policy and 120 character line + width, and formatting rules that are pretty much standard in modern Java.) - Java -> Code Style -> Organize imports - The order is this (the Eclipse default): java, javax, org, com. + Order: java, javax, org, com. Number of imports required for .*: 99 Number of static imports needed for .*: 1 - Java -> Installed JRE-s: @@ -168,29 +169,37 @@ Last tested Eclipse Neon.1. - Java -> Compiler -> Javadoc: "Malformed Javadoc comments": Error "Only consider members as visible": Private - "Validate tag argunebts": true + "Validate tag arguments": true "Missing tag descriptions": Validate @return tags "Missing Javadoc tags": Ignore "Missing Javadoc comments": Ignore -- Project -> Properties -> Java Compiler -> Errors/Warnings: - Check in "Enable project specific settings", then set "Forbidden reference - (access rules)" from "Error" to "Warning". -- At Project -> Properties -> Java Code Style -> Formatter, check in "Enable - project specific settings", and then select "FreeMarker" as active profile. -- At Project -> Properties -> Java Editor -> Save Actions, check "Enable project - specific settings", then "Perform the selected actions on save", and have - only "Organize imports" and "Additional actions" checked (the list for the - last should contain "Add missing @Override annotations", - "Add missing @Override annotations to implementations of interface methods", - "Add missing @Deprecated annotations", and "Remove unnecessary cast"). -- Right click on the root project -> Run As -> JUnit Test [TODO: Try this] - It should run without problems (all green). + - Java -> Compiler -> Errors/Warnings: + Set "Forbidden reference (access rules)" from "Error" to "Warning". + - Java -> Editor -> Save Actions: + Check "Perform the selected actions on save", and under that have only + "Organize imports" and "Additional actions" checked. The list for the + last should contain + "Add missing @Override annotations", + "Add missing @Override annotations to implementations of interface methods", + "Add missing @Deprecated annotations", and + "Remove unnecessary cast". +- File -> Import... -> Gradle / Existing Gradle Project + Import the FreeMarker project directory. Everything can remain at its default. +- Now Eclipse will automatically build the broject in the backround. There shouldn't + be any errors. +- You may right-click on a all the project in the project tree, and chose + "Run as..." -> "JUnit test". Not all projects contains tests though (notably, + freemarker-core tests are in separate projects). +- To run all the tests at once, you must use Gradle. To do that from under Eclipse, + go to "Run" -> "Run Configurations...", then right click on "Gradle Project" in the + tree, then "New". The "Gradle task" (and the "Name") should be `test`, and the + "Working directory" `${workspace_loc:/freemarker}`. - It's highly recommened to use the Eclipse FindBugs plugin. - - Install it from Eclipse Marketplace (3.0.1 as of this writing) + - Install it from Eclipse Marketplace (3.0.2 as of this writing) - Window -> Preferences -> Java -> FindBugs: Set all bug marker ranks from Warning to Error. (For false alarms we add @SuppressFBWarnings(value = "...", justification = "...") annotations.) - - Project -> Properties -> FindBugs -> [x] Run Automatically + - Fro each project: Project -> Properties -> FindBugs -> [x] Run Automatically - There should 0 errors. But sometimes the plugin fails to take the @SuppressFBWarnings annotations into account; then use Project -> Clean. @@ -198,7 +207,7 @@ Last tested Eclipse Neon.1. Last tested on IntelliJ IDEA Community 2017.1.5. -- First build the project with Gradle if you haven't yet (see earlier how) +- First, build the project with Gradle if you haven't yet (see earlier how). - "New..." -> "Project from existing source" - Point to the root project `incubator-freemarker`) directory - On the next screen, select "Import project from external model" and "Gradle" @@ -224,7 +233,7 @@ Last tested on IntelliJ IDEA Community 2017.1.5. go back to "Copyrigth" in the tree, and set "Default project copyright" to "ASL2". - Testing your setup: - You may do "Bulild"/"Build project" (Ctrl+F9) to see if everyting compiles now. - - You may ran the `test` task of the root project with Gradle to see that everything works as + - You may run the `test` task of the root project with Gradle to see that everything works as expected. To do that from IntelliJ, create a run configuration: "Run" \ "Run Configurations..." \ "+" \ "Gradle" then: - Set "Name" to `All tests` for example http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/b63e4488/build.gradle ---------------------------------------------------------------------- diff --git a/build.gradle b/build.gradle index d94794f..15e20be 100644 --- a/build.gradle +++ b/build.gradle @@ -215,9 +215,11 @@ subprojects { compile "org.slf4j:slf4j-api:$slf4jVersion" // All subprojects might use Findbugs annotations: compileOnly libraries.findbugs - - // Test libraries and utilities might come handy during testing: - testCompile project(":freemarker-test-utils") + // We don't add test dependencies to freemarker-core, as Eclipse sees that as circular dependency: + if (path != ':freemarker-core') { + // Test libraries and utilities might come handy during testing: + testCompile project(":freemarker-test-utils") + } } // Like Maven's Enforcer plugin, make the build fail if certain libraries get in. (The problem with the http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/b63e4488/freemarker-servlet/build.gradle ---------------------------------------------------------------------- diff --git a/freemarker-servlet/build.gradle b/freemarker-servlet/build.gradle index 2f28100..2d0aa3b 100644 --- a/freemarker-servlet/build.gradle +++ b/freemarker-servlet/build.gradle @@ -28,18 +28,20 @@ inAggregateJavadoc = true dependencies { compile project(":freemarker-core") - def geronimoServletSpec3Version = "1.0" - def geronimoJspSpec22Version = "1.2" - def geronimoELSpec22Version = "1.0.4" - - compileOnly "org.apache.geronimo.specs:geronimo-servlet_3.0_spec:${geronimoServletSpec3Version}" - compileOnly "org.apache.geronimo.specs:geronimo-jsp_2.2_spec:${geronimoJspSpec22Version}" - compileOnly "org.apache.geronimo.specs:geronimo-el_2.2_spec:${geronimoELSpec22Version}" + // Because of the limitations of Eclipse dependency handling, we have to use the dependency artifacts from + // Jetty ${jettyVersion} here, which is the Jetty version used for the tests. When the jettyVersion changes, run + // `gradlew freemarker-servlet:dependencies` and copy-paste the exact versions to here: + compileOnly "org.eclipse.jetty.orbit:javax.servlet:3.0.0.v201112011016" + compileOnly "org.eclipse.jetty.orbit:javax.servlet.jsp:2.2.0.v201112011158" + compileOnly "org.eclipse.jetty.orbit:javax.el:2.2.0.v201108011116" // ------------------------------------------------------------------------ // For tests - def jettyVersion = "7.6.16.v20140903" + // When changing this, the non-test org.eclipse.jetty.orbit dependencies must be updated as well! Thus, it must use + // exactly the same Servlet/JSP-related specification versions as the minimal requirements of FreeMarker. + def jettyVersion = "8.1.22.v20160922" + testCompile "org.eclipse.jetty:jetty-server:$jettyVersion" testCompile "org.eclipse.jetty:jetty-webapp:$jettyVersion" testCompile "org.eclipse.jetty:jetty-jsp:$jettyVersion" http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/b63e4488/freemarker-servlet/src/test/java/org/apache/freemarker/servlet/DummyMockServletContext.java ---------------------------------------------------------------------- diff --git a/freemarker-servlet/src/test/java/org/apache/freemarker/servlet/DummyMockServletContext.java b/freemarker-servlet/src/test/java/org/apache/freemarker/servlet/DummyMockServletContext.java index 9ad670a..7f508c0 100644 --- a/freemarker-servlet/src/test/java/org/apache/freemarker/servlet/DummyMockServletContext.java +++ b/freemarker-servlet/src/test/java/org/apache/freemarker/servlet/DummyMockServletContext.java @@ -22,12 +22,21 @@ import java.io.InputStream; import java.net.MalformedURLException; import java.net.URL; import java.util.Enumeration; +import java.util.EventListener; +import java.util.Map; import java.util.Set; +import javax.servlet.Filter; +import javax.servlet.FilterRegistration; import javax.servlet.RequestDispatcher; import javax.servlet.Servlet; import javax.servlet.ServletContext; import javax.servlet.ServletException; +import javax.servlet.ServletRegistration; +import javax.servlet.ServletRegistration.Dynamic; +import javax.servlet.SessionCookieConfig; +import javax.servlet.SessionTrackingMode; +import javax.servlet.descriptor.JspConfigDescriptor; public class DummyMockServletContext implements ServletContext { @@ -153,5 +162,136 @@ public class DummyMockServletContext implements ServletContext { @Override public void setAttribute(String arg0, Object arg1) { } - + + @Override + public boolean setInitParameter(String name, String value) { + return false; + } + + @Override + public Dynamic addServlet(String servletName, String className) + throws IllegalArgumentException, IllegalStateException { + return null; + } + + @Override + public Dynamic addServlet(String servletName, Servlet servlet) + throws IllegalArgumentException, IllegalStateException { + return null; + } + + @Override + public Dynamic addServlet(String servletName, Class<? extends Servlet> clazz) + throws IllegalArgumentException, IllegalStateException { + return null; + } + + @Override + public <T extends Servlet> T createServlet(Class<T> clazz) throws ServletException { + return null; + } + + @Override + public ServletRegistration getServletRegistration(String servletName) { + return null; + } + + @Override + public Map<String, ? extends ServletRegistration> getServletRegistrations() { + return null; + } + + @Override + public javax.servlet.FilterRegistration.Dynamic addFilter(String filterName, String className) + throws IllegalArgumentException, IllegalStateException { + return null; + } + + @Override + public javax.servlet.FilterRegistration.Dynamic addFilter(String filterName, Filter filter) + throws IllegalArgumentException, IllegalStateException { + return null; + } + + @Override + public javax.servlet.FilterRegistration.Dynamic addFilter(String filterName, Class<? extends Filter> filterClass) + throws IllegalArgumentException, IllegalStateException { + return null; + } + + @Override + public <T extends Filter> T createFilter(Class<T> clazz) throws ServletException { + return null; + } + + @Override + public FilterRegistration getFilterRegistration(String filterName) { + return null; + } + + @Override + public Map<String, ? extends FilterRegistration> getFilterRegistrations() { + return null; + } + + @Override + public void addListener(Class<? extends EventListener> listenerClass) { + } + + @Override + public void addListener(String className) { + } + + @Override + public <T extends EventListener> void addListener(T t) { + } + + @Override + public <T extends EventListener> T createListener(Class<T> clazz) throws ServletException { + return null; + } + + @Override + public void declareRoles(String... roleNames) { + } + + @Override + public SessionCookieConfig getSessionCookieConfig() { + return null; + } + + @Override + public void setSessionTrackingModes(Set<SessionTrackingMode> sessionTrackingModes) { + } + + @Override + public Set<SessionTrackingMode> getDefaultSessionTrackingModes() { + return null; + } + + @Override + public int getEffectiveMajorVersion() throws UnsupportedOperationException { + return 3; + } + + @Override + public int getEffectiveMinorVersion() throws UnsupportedOperationException { + return 0; + } + + @Override + public Set<SessionTrackingMode> getEffectiveSessionTrackingModes() { + return null; + } + + @Override + public ClassLoader getClassLoader() { + return null; + } + + @Override + public JspConfigDescriptor getJspConfigDescriptor() { + return null; + } + } \ No newline at end of file
