| 1 |
////////////////////////////////////////// |
| 2 |
|
| 3 |
Licensed to the Apache Software Foundation (ASF) under one |
| 4 |
or more contributor license agreements. See the NOTICE file |
| 5 |
distributed with this work for additional information |
| 6 |
regarding copyright ownership. The ASF licenses this file |
| 7 |
to you under the Apache License, Version 2.0 (the |
| 8 |
"License"); you may not use this file except in compliance |
| 9 |
with the License. You may obtain a copy of the License at |
| 10 |
|
| 11 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 12 |
|
| 13 |
Unless required by applicable law or agreed to in writing, |
| 14 |
software distributed under the License is distributed on an |
| 15 |
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 16 |
KIND, either express or implied. See the License for the |
| 17 |
specific language governing permissions and limitations |
| 18 |
under the License. |
| 19 |
|
| 20 |
////////////////////////////////////////// |
| 21 |
|
| 22 |
= Servlet support |
| 23 |
|
| 24 |
You can write (Java) Servlets in Groovy (called Groovlets). |
| 25 |
|
| 26 |
There is also a `GroovyServlet`. |
| 27 |
|
| 28 |
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. |
| 29 |
|
| 30 |
Here's a simple example to show you the kind of things you can do from a Groovlet. |
| 31 |
|
| 32 |
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. |
| 33 |
|
| 34 |
[source,groovy] |
| 35 |
---- |
| 36 |
include::{rootProjectDir}/subprojects/groovy-servlet/src/spec/test/servlet/GroovyServletTest.groovy[tags=example,indent=0] |
| 37 |
---- |
| 38 |
|
| 39 |
Or, do the same thing using MarkupBuilder: |
| 40 |
|
| 41 |
[source,groovy] |
| 42 |
---- |
| 43 |
include::{rootProjectDir}/subprojects/groovy-servlet/src/spec/test/servlet/GroovyServletTest.groovy[tags=example_markup_builder,indent=0] |
| 44 |
---- |
| 45 |
|
| 46 |
== Implicit variables |
| 47 |
|
| 48 |
The following variables are ready for use in Groovlets: |
| 49 |
|
| 50 |
[options="header",cols="1,1,1a"] |
| 51 |
|============================================ |
| 52 |
|variable name|bound to|note |
| 53 |
|request|ServletRequest|- |
| 54 |
|response|ServletResponse|- |
| 55 |
|context|ServletContext|- |
| 56 |
|application|ServletContext|- |
| 57 |
|session|getSession(false)|can be null! see <1> |
| 58 |
|params||a Map object |
| 59 |
|headers||a Map object |
| 60 |
|out|response.getWriter()|see <2> |
| 61 |
|sout|response.getOutputStream()|see <2> |
| 62 |
|html|new MarkupBuilder(out)|see <2> |
| 63 |
|json|new StreamingJsonBuilder(out)|see <2> |
| 64 |
|============================================ |
| 65 |
1. The session variable is only set, if there was already a session object. See the `if (session == null)` checks in the examples above. |
| 66 |
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`. |
| 67 |
|
| 68 |
== Setting up groovylets |
| 69 |
|
| 70 |
Add the following to your `web.xml`: |
| 71 |
[source,xml] |
| 72 |
-------------------------------------------------------------------------------------------------- |
| 73 |
<servlet> |
| 74 |
<servlet-name>Groovy</servlet-name> |
| 75 |
<servlet-class>groovy.servlet.GroovyServlet</servlet-class> |
| 76 |
</servlet> |
| 77 |
|
| 78 |
<servlet-mapping> |
| 79 |
<servlet-name>Groovy</servlet-name> |
| 80 |
<url-pattern>*.groovy</url-pattern> |
| 81 |
</servlet-mapping> |
| 82 |
-------------------------------------------------------------------------------------------------- |
| 83 |
|
| 84 |
Then put the required groovy jar files into `WEB-INF/lib`. |
| 85 |
|
| 86 |
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. |
| 87 |
|
| 88 |
So for example using tomcat you could edit `tomcat/conf/server.xml` like this: |
| 89 |
[source,xml] |
| 90 |
-------------------------------------------------------------------------------------------------- |
| 91 |
<Context path="/groovy" docBase="c:/groovy-servlet"/> |
| 92 |
-------------------------------------------------------------------------------------------------- |
| 93 |
|
| 94 |
Then access it with http://localhost:8080/groovy/hello.groovy |