This is an automated email from the ASF dual-hosted git repository.
paulk pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/groovy.git
The following commit(s) were added to refs/heads/master by this push:
new 9f49c7a322 minor refactor: expand slightly
9f49c7a322 is described below
commit 9f49c7a322a899055462698df359e3afb799c75f
Author: Paul King <[email protected]>
AuthorDate: Thu Jan 9 18:29:27 2025 +1000
minor refactor: expand slightly
---
.../src/spec/doc/servlet-userguide.adoc | 50 ++++++++++++++++------
1 file changed, 38 insertions(+), 12 deletions(-)
diff --git a/subprojects/groovy-servlet/src/spec/doc/servlet-userguide.adoc
b/subprojects/groovy-servlet/src/spec/doc/servlet-userguide.adoc
index d759a1268b..d6534fb7ce 100644
--- a/subprojects/groovy-servlet/src/spec/doc/servlet-userguide.adoc
+++ b/subprojects/groovy-servlet/src/spec/doc/servlet-userguide.adoc
@@ -21,15 +21,25 @@
= Servlet support
-You can write (Java) Servlets in Groovy (called Groovlets).
+The `groovy-servlet` module supports the following features:
+
+* A `GroovyServlet` class let you use Groovy scripts as Servlets (called
_Groovylets_).
+* A `TemplateServlet` class which supports running Groovy's template engines
to generate servlet content. A typical use case is to write Groovy Server Pages
(GSPs) which are similar to Java Server Pages (JSPs) but embed Groovy code
+rather than Java code.
+* An `AbstractHttpServlet` class for defining traditional Servlets.
+* Helper classes like `ServletBinding` and `ServletCategory` which let you
access some of the features offered by the `groovy-servlet` module in
additional contexts.
+
+From Groovy 5, `groovy-servlet` supports Jakarta EE Servlet specifications.
Javax EE servlet specifications are supported in version before Groovy 5 or
with Groovy 5 by using the `javax` classifier when specifying your dependency.
-There is also a `GroovyServlet`.
+== Groovlets
+
+You can write (Java) Servlets in Groovy (called Groovlets).
-This feature will automatically compile your .groovy source files, turn them
into bytecode, load the Class and cache it until you change the source file.
+This is supported by the `GroovyServlet` class. It will automatically compile
your `.groovy` source files, turn them into bytecode, load the Class and cache
it until you change the source file.
Here's a simple example to show you the kind of things you can do from a
Groovlet.
-Notice the use of implicit variables to access the session, output and
request. Also notice that this is more like a script as it does not have a
class wrapper.
+Notice the use of implicit variables to access the `session`, `output` and
`request`. Also notice that this is more like a script as the code isn't
wrapped with a class definition.
[source,groovy]
----
@@ -65,11 +75,11 @@ The following variables are ready for use in Groovlets:
1. The session variable is only set, if there was already a session object.
See the `if (session == null)` checks in the examples above.
2. These variables cannot be re-assigned inside a `Groovlet`. They are bound
on first access, allowing to e.g. calling methods on the `response` object
before using `out`.
-== Setting up groovlets
+== Setting up Groovlets
-Add the following to your `web.xml`:
+The traditional configuration approach for declaring new servlets is to add
them to your Servlet engine configuration, e.g. you might add the following to
your `web.xml`:
[source,xml]
---------------------------------------------------------------------------------------------------
+------------------------------------------------------------------------------
<servlet>
<servlet-name>Groovy</servlet-name>
<servlet-class>groovy.servlet.GroovyServlet</servlet-class>
@@ -79,16 +89,32 @@ Add the following to your `web.xml`:
<servlet-name>Groovy</servlet-name>
<url-pattern>*.groovy</url-pattern>
</servlet-mapping>
---------------------------------------------------------------------------------------------------
+------------------------------------------------------------------------------
Then put the required groovy jar files into `WEB-INF/lib`.
Now put the .groovy files in, say, the root directory (i.e. where you would
put your html files). The `GroovyServlet` takes care of compiling the .groovy
files.
-So for example using tomcat you could edit `tomcat/conf/server.xml` like this:
+So for example using https://tomcat.apache.org/[Apache Tomcat] you could edit
`tomcat/conf/server.xml` like this:
[source,xml]
---------------------------------------------------------------------------------------------------
-<Context path="/groovy" docBase="c:/groovy-servlet"/>
---------------------------------------------------------------------------------------------------
+------------------------------------------------------------------------------
+<Context path="/groovy" docBase="/path_to_servlet_base"/>
+------------------------------------------------------------------------------
Then access it with http://localhost:8080/groovy/hello.groovy
+
+Some Servlet engines let you define Servlets programmatically, e.g. here is
how you might use https://jetty.org/[Jetty] with Groovlets enabled:
+
+[source,groovy]
+----
+import groovy.servlet.GroovyServlet
+import org.eclipse.jetty.server.Server
+import org.eclipse.jetty.ee9.servlet.ServletContextHandler
+
+var server = new Server(8080)
+var handler = new ServletContextHandler(server, '/',
ServletContextHandler.SESSIONS)
+handler.baseResourceAsString = 'path_to_servlet_base'
+handler.addServlet(GroovyServlet, '*.groovy')
+server.start()
+server.join()
+----
