Add jsp documentation to operations guide.
Signed-off-by: Jan Bartel <janb@webtide.com>
This commit is contained in:
Jan Bartel
parent
aedba8e782
commit
2f5e4330ef
|
|
@ -35,3 +35,4 @@ include::xml/chapter.adoc[]
|
|||
include::sessions/chapter.adoc[]
|
||||
include::quickstart/chapter.adoc[]
|
||||
include::annotations/chapter.adoc[]
|
||||
include::jsp/chapter.adoc[]
|
||||
|
|
@ -33,6 +33,7 @@ If you know Eclipse Jetty already, jump to a feature:
|
|||
* xref:og-protocols-http2[HTTP/2 Support]
|
||||
* xref:og-quickstart[Faster Web Application Deployment]
|
||||
* xref:og-annotations[Annotations]
|
||||
* xref:og-jsp[JSP]
|
||||
|
||||
TODO
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,215 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under
|
||||
// the terms of the Eclipse Public License 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0
|
||||
//
|
||||
// This Source Code may also be made available under the following
|
||||
// Secondary Licenses when the conditions for such availability set
|
||||
// forth in the Eclipse Public License, v. 2.0 are satisfied:
|
||||
// the Apache License v2.0 which is available at
|
||||
// https://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[og-jsp]]
|
||||
=== Java Server Pages
|
||||
|
||||
Jetty supports JSP via the `jsp` module, which is based on Apache Jasper:
|
||||
|
||||
----
|
||||
include::{JETTY_HOME}/modules/jsp.mod[]
|
||||
----
|
||||
|
||||
Logging has been bridged to Jetty logging, so you can enable logging for the `org.apache.jasper` package, subpackages and classes as usual.
|
||||
|
||||
===== Configuration of the JSP servlet
|
||||
|
||||
The `org.eclipse.jetty.jsp.JettyJspServlet` is the servlet responsible for serving jsps.
|
||||
|
||||
It is configured as the default jsp servlet in the link:{JETTY_HOME}/etc/webdefault.xml[webdefault.xml] file.
|
||||
Notice that Jetty identifies the jsp servlet by the presence of the `id=jsp` attribute in the `<servlet>` declaration.
|
||||
|
||||
That file maps the `org.eclipse.jetty.jsp.JettyJspServlet` to the following partial urls:
|
||||
|
||||
* `+*.jsp+`
|
||||
* `+*.jspf+`
|
||||
* `+*.jspx+`
|
||||
* `+*.xsp+`
|
||||
* `+*.JSP+`
|
||||
* `+*.JSPF+`
|
||||
* `+*.JSPX+`
|
||||
* `+*.XSP+`
|
||||
|
||||
You can change to a different servlet, change or add ``<init-param>``s or add extra ``<servlet-mapping>``s in your `web.xml` file.
|
||||
|
||||
Here's an example of adding an `<init-param>` to augment the definitions from the standard `webdefault.xml` file:
|
||||
|
||||
[source,xml,subs=verbatim]
|
||||
----
|
||||
<servlet id="jsp"> <1>
|
||||
<servlet-name>jsp</servlet-name> <2>
|
||||
<init-param>
|
||||
<param-name>keepgenerated</param-name> <3>
|
||||
<param-value>true</param-value> <4>
|
||||
</init-param>
|
||||
</servlet>
|
||||
----
|
||||
<1> This identifies this servlet as the jsp servlet to Jetty.
|
||||
<2> This identifies this declaration as augmenting the already-defined servlet called `jsp`.
|
||||
<3> This init param controls whether the jsp servlet retains the `+*.java+` files generated during jsp compilation.
|
||||
<4> This sets the value of the init param
|
||||
|
||||
Another element you might consider adding to the default setup is `async-supported`:
|
||||
|
||||
[source,xml,subs=verbatim]
|
||||
----
|
||||
<servlet id="jsp"> <1>
|
||||
<servlet-name>jsp</servlet-name> <2>
|
||||
<async-supported>true</async-supported> <3>
|
||||
</servlet>
|
||||
----
|
||||
<1> This identifies this servlet as the jsp servlet to Jetty.
|
||||
<2> This identifies this declaration as augmenting the already-defined servlet called `jsp`.
|
||||
<3> By default, the jsp servlet does not support async.
|
||||
|
||||
There are many configuration parameters for the Apache Jasper jsp servlet, here are some of them:
|
||||
|
||||
.Jsp Servlet Parameters
|
||||
[cols=",,,",options="header",]
|
||||
|=======================================================================
|
||||
|init param |Description |Default |`webdefault.xml`
|
||||
|
||||
|checkInterval |If non-zero and `development` is `false`, background jsp recompilation is enabled. This value is the interval in seconds between background recompile checks.
|
||||
|0 |–
|
||||
|classpath |The classpath is dynamically generated if the context has a URL classloader. The `org.apache.catalina.jsp_classpath`
|
||||
context attribute is used to add to the classpath, but if this is not set, this `classpath` configuration item is added to the classpath instead.` |- |–
|
||||
|
||||
|classdebuginfo |Include debugging info in class file. |TRUE |–
|
||||
|
||||
|compilerClassName |If not set, defaults to the Eclipse jdt compiler. |- |–
|
||||
|
||||
|compiler |Used if the Eclipse jdt compiler cannot be found on the
|
||||
classpath. It is the classname of a compiler that Ant should invoke. |–
|
||||
|–
|
||||
|
||||
|compilerTargetVM |Target vm to compile for. |1.8 |1.8
|
||||
|
||||
|compilerSourceVM |Sets source compliance level for the jdt compiler.
|
||||
|1.8 |1.8
|
||||
|
||||
|development |If `true` recompilation checks occur at the frequency governed by `modificationTestInterval`. |TRUE |–
|
||||
|
||||
|displaySourceFragment |Should a source fragment be included in
|
||||
exception messages |TRUE |–
|
||||
|
||||
|dumpSmap |Dump SMAP JSR45 info to a file. |FALSE |–
|
||||
|
||||
|enablePooling |Determines whether tag handler pooling is enabled. |TRUE |–
|
||||
|
||||
|engineOptionsClass |Allows specifying the Options class used to
|
||||
configure Jasper. If not present, the default EmbeddedServletOptions
|
||||
will be used. |- |–
|
||||
|
||||
|errorOnUseBeanInvalidClassAttribute |Should Jasper issue an error when
|
||||
the value of the class attribute in an useBean action is not a valid
|
||||
bean class |TRUE |–
|
||||
|
||||
|fork |Only relevant if you use Ant to compile jsps: by default Jetty will use the Eclipse jdt compiler.|TRUE |-
|
||||
|
||||
|genStrAsCharArray |Option for generating Strings as char arrays. |FALSE |–
|
||||
|
||||
|ieClassId |The class-id value to be sent to Internet Explorer when
|
||||
using <jsp:plugin> tags. |clsid:8AD9C840-044E-11D1-B3E9-00805F499D93 |–
|
||||
|
||||
|javaEncoding |Pass through the encoding to use for the compilation.
|
||||
|UTF8 |–
|
||||
|
||||
|jspIdleTimeout |The amount of time in seconds a JSP can be idle before
|
||||
it is unloaded. A value of zero or less indicates never unload. |-1 |–
|
||||
|
||||
|keepgenerated |Do you want to keep the generated Java files around?
|
||||
|TRUE |–
|
||||
|
||||
|mappedFile |Support for mapped Files. Generates a servlet that has a
|
||||
print statement per line of the JSP file |TRUE |–
|
||||
|
||||
|maxLoadedJsps |The maximum number of JSPs that will be loaded for a web
|
||||
application. If more than this number of JSPs are loaded, the least
|
||||
recently used JSPs will be unloaded so that the number of JSPs loaded at
|
||||
any one time does not exceed this limit. A value of zero or less
|
||||
indicates no limit. |-1 |–
|
||||
|
||||
|modificationTestInterval |If `development=true`, interval between
|
||||
recompilation checks, triggered by a request. |4 |–
|
||||
|
||||
|quoteAttributeEL | When EL is used in an attribute value on a JSP page, should the rules for quoting of attributes described in JSP.1.6 be applied to the expression
|
||||
|TRUE |-
|
||||
|
||||
|recompileOnFail |If a JSP compilation fails should the
|
||||
modificationTestInterval be ignored and the next access trigger a
|
||||
re-compilation attempt? Used in development mode only and is disabled by
|
||||
default as compilation may be expensive and could lead to excessive
|
||||
resource usage. |FALSE |–
|
||||
|
||||
|scratchDir |Directory where servlets are generated. The default is the value of the context attribute `javax.servlet.context.tempdir`, or the system property `java.io.tmpdir` if the context attribute is not set. |– |–
|
||||
|
||||
|strictQuoteEscaping |Should the quote escaping required by section JSP.1.6 of the JSP specification be applied to scriplet expression.
|
||||
|TRUE|-
|
||||
|
||||
|suppressSmap |Generation of SMAP info for JSR45 debugging. |FALSE |–
|
||||
|
||||
|trimSpaces |Should template text that consists entirely of whitespace be removed from the output (true), replaced with a single space (single) or left unchanged (false)? Note that if a JSP page or tag file specifies a trimDirectiveWhitespaces value of true, that will take precedence over this configuration setting for that page/tag.
|
||||
trimmed? |FALSE |–
|
||||
|
||||
|xpoweredBy |Generate an X-Powered-By response header. |FALSE |FALSE
|
||||
|
||||
|=======================================================================
|
||||
|
||||
|
||||
NOTE:: If the value you set doesn't take effect, try using all lower case instead of camel case, or capitalizing only some of the words in the name, as Jasper is inconsistent in its parameter naming strategy.
|
||||
|
||||
|
||||
=== JavaServer Pages Standard Tag Libraries
|
||||
|
||||
The JavaServer Pages Standlard Tag Library (JSTL) is part of the Jetty distribution, and is available via the `jstl` module:
|
||||
|
||||
----
|
||||
include::{JETTY_HOME}/modules/jstl.mod[]
|
||||
----
|
||||
|
||||
When enabled, Jetty will make the JSTL tags available for your webapps.
|
||||
|
||||
=== JavaServer Faces Taglibs
|
||||
|
||||
If you want to use JSF with your webapp, you should copy the relevant jars from your implementation of choice into your `$jetty.base` directory, ideally into `$jetty.base/lib/ext`.
|
||||
If that directory does not exist, enable the `ext` module, which will create the directory and ensure all jars within it are put onto the container classpath.
|
||||
|
||||
|
||||
Then you will need to tell Jetty which of those jars contains the `+*.tld+` files.
|
||||
To accomplish that, you need to specify either the name of the file or a pattern that matches the name/s of the file/s as the `org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern` context attribute.
|
||||
You will need to preserve the existing value of the attribute, and add in your extra pattern.
|
||||
|
||||
Here's an example of using a context xml file to add in a pattern to match files starting with `jsf-`, which contain the `+*.tld+` files:
|
||||
|
||||
[source,xml,subs=verbatim]
|
||||
----
|
||||
<?xml version="1.0"?>
|
||||
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
|
||||
|
||||
<Configure class="org.eclipse.jetty.webapp.WebAppContext"> <1>
|
||||
<Call name="setAttribute"> <2>
|
||||
<Arg>org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern</Arg> <3>
|
||||
<Arg.*/jetty-servlet-api-[^/]*\.jar$|.*/javax.servlet.jsp.jstl-.*\.jar$|.*/org.apache.taglibs.taglibs-standard-impl-.*\.jar$|.*/jsf-[^/]*\.jar$></Arg> <4>
|
||||
</Call>
|
||||
</Configure>
|
||||
----
|
||||
<1> Configures a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<2> Specifies a context attribute.
|
||||
<3> Specifies the name of the context attribute.
|
||||
<4> Adds the additional pattern `+.*/jsf-[^/]*\.jar$+` to those already existing.
|
||||
|
||||
Loading…
Reference in New Issue