//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

= Java Server Pages

Jetty supports JSP via the `{ee-all}-jsp` modules, which are based on Apache Jasper:

[source,subs=attributes+]
----
include::{jetty-home}/modules/ee10-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 `$JETTY_HOME/etc/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:

[,xml]
----
<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`:

[,xml]
----
<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.
====
