Document: Jakarta EE 10: Support Jakarta Pages 3.1

[pnicolucci]

Please describe the problem you are having with the documentation. Is information missing, inaccurate, or unclear? Tell us about the context where you encountered the problem so we can understand how to address it.

OpenLiberty/open-liberty#18737

[volosied]

Pages 3.1 Changes

Finding Unknown Identifiers

• A new option has been added to find unknown Expression Language identifiers. When enabled, a PropertyNotFoundException will occur if an unknown identifier is found. This option can be enabled via page directive, tag directive, or as a jsp-property-group in the web.xml. See configurations sections for examples. More can be read in the Pages 3.1 specification, section 3.3.4 here.

New Expression Language Resolvers & Import Changes

• Expression Language Resolvers were updated to improve handling of imports and unresolved variables. ScopedAttributeELResolver was refactored to create a ImportELResolver. This new import resolver allows any class or static imports (via the import attribute) to be available to the Expression Language environment. Previously, imports were only available to the scripting environment. If an expression used an import class, it would resolve to an empty string. The other new resolver is NotFoundELResolver, which always resolves a variable when the other ones do not.
• Lastly, default/implicit imports for the scripting environment now also apply to the expression language environment. These default imports are java.lang.*, jakarta.servlet.*, jakarta.servlet.jsp.*, and jakarta.servlet.http.*.

Tags 3.0 Changes

Namespaces

• The Tag URIs have changed to use the new jakarta.tags.* pattern. Support for the previous http://xmlns.jcp.org/jsp/jstl/* was kept for backwards compatibility, applications should transition to these new URIs. Tag documentation can be found here.

 <%@ taglib prefix="c" uri="jakarta.tags.core" %> 
 <%@ taglib prefix="x" uri="jakarta.tags.xml" %> 
 <%@ taglib prefix="fmt" uri="jakarta.tags.fmt" %> 
 <%@ taglib prefix="fn" uri="jakarta.tags.functions" %>" 
 <%@ taglib prefix="sql" uri="jakarta.tags.sql" %> 

Deprecations

• The isThreadSafe directive has been deprecated due to the removal of the SingleThreadModel interface in the Servlet 6.0 API. A workaround has been implemented, but there may be significant performance impact. Use of the isThreadSafe directive in Pages 3.1 is discouraged.
• The jsp:plugin, jsp:params, and jsp:fallback actions have been deprecated and are no longer operational since current browsers no longer support the elements generated by the jsp:plugin and related actions.

Removed APIs

• None

Configuration

• New Directive for Pages and Tags:
  <%@ page errorOnELNotFound="true" %>

• New JSP Property Group in the web.xml:

   <jsp-property-group>
     <url-pattern>*.jsp</url-pattern>
     <error-on-el-not-found>true</error-on-el-not-found>
   </jsp-property-group>
  

• To use the Pages 3.1 (and, by extension, Tags 3.0) feature, add pages-3.1 to your server.xml:

     <featureManager>
         <feature>pages-3.1</feature>
     </featureManager>
  

[volosied]

I'm leaving out a few changes listed under each specification since no implementation / behavior changes occurred :

• Tags: https://jakarta.ee/specifications/tags/3.0/
• For example:

[Issue #156](https://github.com/eclipse-ee4j/jstl-api/issues/156) Update Jakarta Tags to Java 11
[Issue #157](https://github.com/eclipse-ee4j/jstl-api/issues/157) Add JPMS Module Info Class
[Issue #149](https://github.com/eclipse-ee4j/jstl-api/issues/149) Remove dependency on XML Binding from the API pom
Some documentation updates

• Pages: https://jakarta.ee/specifications/pages/3.1/
• And ...
  [42](https://github.com/eclipse-ee4j/jsp-api/issues/42) Clarify the meaning of ‘scope’ in the context of scripting variables associated with custom actions

[dmuelle]

Hi @volosied are the changes to Tags the same that would be relevant to #5836
"Document: Jakarta EE 10: Support Jakarta Standard Tag Library 3.0" If so, I can close that issue and we can track both updates here. Unless we need to separate issues. Thanks

[volosied]

@dmuelle You're correct, and I've closed the Tags issue. Thanks

[dmuelle]

Hi @volosied - what is the function of the new directive and JSP property group errorOnELNotFound? What capability do these provide or what is the significance for the developer? Thanks

[dmuelle]

Also, is there a Liberty feature that corresponds to Jakarta Tags?

[volosied]

@dmuelle If errorOnELNotFound is enabled and the page uses an unknown identifier (in essence, a variable which hasn't been defined) then the JSP/Pages engine will throw PropertyNotFoundException. The specification issue for can be found here: https://github.com/jakartaee/pages/issues/40. This option would be used during the development phase and likely not in production. Previously, unknown identifiers were rendered as empty strings (""), and where difficult to identify.

There is no separate Jakarta Tags feature. It is only enabled via Pages 3.1.

[dmuelle]

Hi @volosied- the draft for these updates is now available for review on the Differences between Jakarta EE 10.0 and 9.1 page:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/jakarta-ee10-diff.html#pages

Let me know if any further edits are needed. If not, you can sign off by adding the Technical reviewed label to this issue and the doc will publish in the same release as EE 10. Thanks!

[volosied]

Hi, I noticed New Expression Language Resolvers & Import Changes were not added to Pages Doc linked above (not sure if on purpose or accident). I would recommend adding them.

[dmuelle]

thanks for catching that, fixed in #5973

[chirp1]

This issue also addresses the Tag 3.0 epic at OpenLiberty/open-liberty#18744 . Approving this epic. The Pages 3.1 epic was approved previously in #18737.

[dmuelle]

@ramkumar-k-9286 this is ready for peer review

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/jakarta-ee10-diff.html#pages

[ramkumar-k-9286]

Peer Review

This release adds a new option to find unknown Expression Language identifiers.
->
This version includes a feature to detect unknown Expression Language identifiers.

This release adds a new option to find unknown Expression Language identifiers. When this option is enabled, a PropertyNotFoundException occurs if an unknown identifier is found.
->
is it PropertyNotFound exception?

To enable this option byn using a JSP Property Group in the web.xml file, set the error-on-el-not-found element to true, as shown in the following example.
->
To enable this option by using a JSP Property Group in the web.xml file, set the error-on-el-not-found element to true, as shown in the following example.

Although support for the previous http://xmlns.jcp.org/jsp/jstl/* pattern is maintained for backwards compatibility
->
Although support for the previous http://xmlns.jcp.org/jsp/jstl/* pattern is maintained for compatibility with an earlier version, ( Acrolinx corrected)

URIs or IRI?

The jsp:plugin, jsp:params, and jsp:fallback actions are deprecated and are not operational because current browsers no longer support the elements that are generated by the jsp:plugin and related actions.
-> ( Acrolinx - Sentence long)
The jsp:plugin, jsp:params, and jsp:fallback actions are deprecated and non-operational due to the lack of support for the generated elements by current browsers.

[dmuelle]

Thanks for reviewing @ramkumar-k-9286 - all suggestions incorporated except

• did not substitute "feature" for "option" as feature has a special meaning in Liberty context

• PropertyNotFoundException is correct and did not want to say "PropertyNotFoundException exception"

• URIs or IRI?- URI is correct- what is IRI?

  • @dmuelle sorry. Typo error - I meant URIs or URI?