Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OF-2717: Rework Jetty 12 plugin documentation #2602

Merged
merged 2 commits into from
Jan 3, 2025
Merged

OF-2717: Rework Jetty 12 plugin documentation #2602

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
af22936
OF-2717: Rework Jetty 12 plugin documentation
guusdk Nov 13, 2024
de537f9
OF-2717: Additional content for Plugin-to-Jetty12 upgrade guide
guusdk Nov 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
257 changes: 257 additions & 0 deletions documentation/plugin-dev-jetty12.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,257 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Plugin Development: Openfire 5.0.0's Jetty 12 upgrade</title>
<link type="text/css" rel="stylesheet" href="style.css">
<style>
dl {
display: unset;
}
dt {
margin-left: 4em;
}
dd {
margin-left: 6em;
margin-bottom: 1.5em;
}
</style>
</head>
<body>

<article>

<header>
<img src="images/header_logo.gif" alt="Openfire Logo" />
<h1>Plugin Development: Openfire 5.0.0's Jetty 12 upgrade</h1>
</header>

<section id="intro">
<h2>Overview</h2>
<p>
In Openfire 5.0.0, the embedded webserver (Jetty) was upgraded to version 12. Many plugins that are developed
against older versions of Openfire are known to be compatible, and will continue to work. That, however, is not
the case for <em>all</em> plugins. This guide describes the most common issues.
</p>
<p>
Note that many of the problems are caused by relatively simple package changes. Quite often, a class with the
same (or very similar) name than the one that's no longer available can be found in another Java package.
</p>
<p>
New in Jetty 12 is that the Servlet layer has been separated away from the Jetty Core layer. The Servlet layer
has been moved to the new Environments concept introduced with Jetty 12. Openfire 5.0.0 is using the Jakarta EE8
environment, which retains the <code>javax.servlet</code> packages known from earlier versions. The associated
Jetty GroupId is <code>org.eclipse.jetty.ee8</code>, which is commonly used as a (part of) a Jetty java package
name.
</p>
</section>

<section id="maven">
<h2>Update parent POM and Admin Console page (JSP) compilation</h2>
<p>
Most Openfire plugins inherit from the parent pom provided by the <code>org.igniterealtime.org:plugins</code>
artifact. For version 5.0.0, this updates that Maven plugin used for compilation of the JSP pages that make up
the admin console. Be sure to modify the Maven plugin that's defined in your <code>pom.xml</code> when you
update parent plugin version to 5.0.0 (or later). The required changes are illustrated in the examples below.
</p>

<div style="overflow: hidden;">
<fieldset style="float: left;">
<legend>Partial Plugin pom.xml content for older versions of Openfire</legend>
<pre><code>&lt;project&gt;
&lt;parent&gt;
&lt;artifactId&gt;plugins&lt;/artifactId&gt;
&lt;groupId&gt;org.igniterealtime.openfire&lt;/groupId&gt;
&lt;version&gt;4.9.2&lt;/version&gt;
&lt;/parent&gt;

&lt;build&gt;
&lt;plugins&gt;
&lt;!-- Compiles the Openfire Admin Console JSP pages. --&gt;
&lt;plugin&gt;
&lt;groupId&gt;org.eclipse.jetty&lt;/groupId&gt;
&lt;artifactId&gt;jetty-jspc-maven-plugin&lt;/artifactId&gt;
&lt;/plugin&gt;
&lt;/plugins&gt;
&lt;/build&gt;
&lt;/project&gt;</code></pre>
</fieldset>

<fieldset style="float: left;">
<legend>Partial Plugin pom.xml content after updating to Openfire 5.0.0</legend>
<pre><code>&lt;project&gt;
&lt;parent&gt;
&lt;artifactId&gt;plugins&lt;/artifactId&gt;
&lt;groupId&gt;org.igniterealtime.openfire&lt;/groupId&gt;
&lt;version&gt;5.0.0&lt;/version&gt;
&lt;/parent&gt;

&lt;build&gt;
&lt;plugins&gt;
&lt;!-- Compiles the Openfire Admin Console JSP pages. --&gt;
&lt;plugin&gt;
&lt;groupId&gt;org.eclipse.jetty.ee8&lt;/groupId&gt;
&lt;artifactId&gt;jetty-ee8-jspc-maven-plugin&lt;/artifactId&gt;
&lt;/plugin&gt;
&lt;/plugins&gt;
&lt;/build&gt;
&lt;/project&gt;</code></pre>
</fieldset>
</div>
</section>

<section id="context">

<h2>New WebAppContext</h2>
<p>
When a plugin uses a <code>org.eclipse.jetty.webapp.WebAppContext</code> that is registered with Openfire's
embedded webserver that serves public content through <code>org.jivesoftware.openfire.http.HttpBindManager.addJettyHandler(org.eclipse.jetty.server.Handler)</code>
then migration to <code>org.eclipse.jetty.ee8.webapp.WebAppContext</code> may cause runtime class cast errors.
</p>
<p>
Two solutions are available in Openfire 5.0.0:
</p>
<ol>
<li>In Openfire 5.0.0, an overloaded method <code>org.jivesoftware.openfire.http.HttpBindManager#addJettyHandler(org.eclipse.jetty.ee8.nested.ContextHandler)</code> was added. This can be used directly with your <code>org.eclipse.jetty.ee8.webapp.WebAppContext</code> instance.</li>
<li>The original method <code>org.jivesoftware.openfire.http.HttpBindManager#addJettyHandler(org.eclipse.jetty.server.Handler)</code> can be invoked with the 'core' context handler that can be obtained through <code>org.eclipse.jetty.ee8.nested.ContextHandler#get</code></li>
</ol>
<p>
By virtue of the new overloaded method described in the first option, it's likely that your implementation needs little change to register the context handler.
</p>

</section>

<section id="knownerrors">

<h2>Known Error Details and Potential Solutions</h2>
<p>
This section provides further details on the errors observed and offers suggestions for addressing them.
</p>

<section id="blankpages">
<h3>Partially blank Admin Console pages</h3>

<p>
When a plugin-provided admin console page is mostly blank, then there might have been a problem during compilation of the JSP file that makes up the page.
</p>
<p>
If this problem occurs in relation to the upgrade to Openfire 5.0.0, then <a href="#maven">check the Maven configuration</a> of your plugin. Ensure that both
</p>
<ul>
<li>the 'parent' pom that's being used is version 5.0.0 (or later)</li>
<li>the old JSPC compiler plugin has been replaced by the new one (note that both the groupId and artifactId have changed).</li>
</ul>
</section>

<section id="verify-error">
<h3>java.lang.VerifyError: Bad type on operand stack</h3>

<fieldset>
<legend>Error found in openfire.log</legend>
<pre><code>java.lang.VerifyError: Bad type on operand stack
Exception Details:
Location:
org/eclipse/jetty/servlet/ServletContextHandler.setGzipHandler(Lorg/eclipse/jetty/server/handler/gzip/GzipHandler;)V @6: invokespecial
Reason:
Type 'org/eclipse/jetty/server/handler/gzip/GzipHandler' (current frame, stack[2]) is not assignable to 'org/eclipse/jetty/server/handler/HandlerWrapper'
Current Frame:
bci: @6
flags: { }
locals: { 'org/eclipse/jetty/servlet/ServletContextHandler', 'org/eclipse/jetty/server/handler/gzip/GzipHandler' }
stack: { 'org/eclipse/jetty/servlet/ServletContextHandler', 'org/eclipse/jetty/server/handler/gzip/GzipHandler', 'org/eclipse/jetty/server/handler/gzip/GzipHandler' }
Bytecode:
0000000: 2a2a b400 352b b700 762a 2bb5 0035 2ab7
0000010: 0018 b1
at org.jivesoftware.openfire.plugin.MonitoringPlugin.loadPublicWeb(MonitoringPlugin.java:279) ~[monitoring-2.6.1.jar:?]
at org.jivesoftware.openfire.plugin.MonitoringPlugin.initializePlugin(MonitoringPlugin.java:186) ~[monitoring-2.6.1.jar:?]
at org.jivesoftware.openfire.container.PluginManager.loadPlugin(PluginManager.java:640) [xmppserver-4.10.0-SNAPSHOT.jar:4.10.0-SNAPSHOT]
at org.jivesoftware.openfire.container.PluginMonitor$MonitorTask$4.call(PluginMonitor.java:380) [xmppserver-4.10.0-SNAPSHOT.jar:4.10.0-SNAPSHOT]
at org.jivesoftware.openfire.container.PluginMonitor$MonitorTask$4.call(PluginMonitor.java:368) [xmppserver-4.10.0-SNAPSHOT.jar:4.10.0-SNAPSHOT]
at java.util.concurrent.FutureTask.run(FutureTask.java:264) [?:?]
at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1136) [?:?]
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:635) [?:?]
at java.lang.Thread.run(Thread.java:840) [?:?]</code></pre>
</fieldset>
<p>Consider using <code>org.eclipse.jetty.server.Handler.Wrapper</code> (<a href="https://javadoc.jetty.org/jetty-12/org/eclipse/jetty/server/Handler.Wrapper.html">javadoc</a>) to replace <code>org.eclipse.jetty.server.handler.HandlerWrapper</code> usage.</p>
</section>

<section id="web-app-context">
<h3>java.lang.NoClassDefFoundError: org/eclipse/jetty/webapp/WebAppContext</h3>
<fieldset>
<legend>Error found in openfire.log</legend>
<pre><code>java.lang.NoClassDefFoundError: org/eclipse/jetty/webapp/WebAppContext
at org.igniterealtime.openfire.plugin.inverse.InversePlugin.initializePlugin(InversePlugin.java:63) ~[inverse-10.1.7.1.jar:?]
at org.jivesoftware.openfire.container.PluginManager.loadPlugin(PluginManager.java:640) [xmppserver-4.10.0-SNAPSHOT.jar:4.10.0-SNAPSHOT]
at org.jivesoftware.openfire.container.PluginMonitor$MonitorTask$4.call(PluginMonitor.java:380) [xmppserver-4.10.0-SNAPSHOT.jar:4.10.0-SNAPSHOT]
at org.jivesoftware.openfire.container.PluginMonitor$MonitorTask$4.call(PluginMonitor.java:368) [xmppserver-4.10.0-SNAPSHOT.jar:4.10.0-SNAPSHOT]
at java.util.concurrent.FutureTask.run(FutureTask.java:264) [?:?]
at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1136) [?:?]
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:635) [?:?]
at java.lang.Thread.run(Thread.java:840) [?:?]
Caused by: java.lang.ClassNotFoundException: org.eclipse.jetty.webapp.WebAppContext
at java.net.URLClassLoader.findClass(URLClassLoader.java:445) ~[?:?]
at java.lang.ClassLoader.loadClass(ClassLoader.java:592) ~[?:?]
at java.lang.ClassLoader.loadClass(ClassLoader.java:525) ~[?:?]
... 8 more</code></pre>
</fieldset>
<p>Consider using the EE8 WebAppContext from <code>org.eclipse.jetty.ee8.webapp.WebAppContext</code> to replace <code>org.eclipse.jetty.webapp.WebAppContext</code> usage.</p>
</section>

<section id="constraint-security-handler">
<h3>java.lang.NoClassDefFoundError: org/eclipse/jetty/security/ConstraintSecurityHandler</h3>
<fieldset>
<legend>Error found in openfire.log</legend>
<pre><code>java.lang.NoClassDefFoundError: org/eclipse/jetty/security/ConstraintSecurityHandler
at java.lang.Class.getDeclaredConstructors0(Native Method) ~[?:?]
at java.lang.Class.privateGetDeclaredConstructors(Class.java:3373) ~[?:?]
at java.lang.Class.getConstructor0(Class.java:3578) ~[?:?]
at java.lang.Class.newInstance(Class.java:626) ~[?:?]
at org.jivesoftware.openfire.container.PluginManager.loadPlugin(PluginManager.java:587) [xmppserver-4.10.0-SNAPSHOT.jar:4.10.0-SNAPSHOT]
at org.jivesoftware.openfire.container.PluginMonitor$MonitorTask$4.call(PluginMonitor.java:380) [xmppserver-4.10.0-SNAPSHOT.jar:4.10.0-SNAPSHOT]
at org.jivesoftware.openfire.container.PluginMonitor$MonitorTask$4.call(PluginMonitor.java:368) [xmppserver-4.10.0-SNAPSHOT.jar:4.10.0-SNAPSHOT]
at java.util.concurrent.FutureTask.run(FutureTask.java:264) [?:?]
at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1136) [?:?]
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:635) [?:?]
at java.lang.Thread.run(Thread.java:840) [?:?]
Caused by: java.lang.ClassNotFoundException: org.eclipse.jetty.security.ConstraintSecurityHandler
at java.net.URLClassLoader.findClass(URLClassLoader.java:445) ~[?:?]
at java.lang.ClassLoader.loadClass(ClassLoader.java:592) ~[?:?]
at java.lang.ClassLoader.loadClass(ClassLoader.java:525) ~[?:?]
... 11 more</code></pre>
</fieldset>
<p>Consider using the EE8 ConstraintSecurityHandler from <code>org.eclipse.jetty.ee8.security.ConstraintSecurityHandler</code> to replace <code>org.eclipse.jetty.security.ConstraintSecurityHandler</code>.</p>
</section>

<section id="jetty-websocket-creator">
<h3>java.lang.NoClassDefFoundError: org/eclipse/jetty/websocket/server/JettyWebSocketCreator</h3>
<fieldset>
<legend>Error found in openfire.log</legend>
<pre><code>java.lang.NoClassDefFoundError: org/eclipse/jetty/websocket/server/JettyWebSocketCreator
at uk.ifsoft.openfire.plugins.pade.PadePlugin.initializePlugin(PadePlugin.java:117) ~[pade-1.8.3.jar:?]
at org.jivesoftware.openfire.container.PluginManager.loadPlugin(PluginManager.java:640) [xmppserver-4.10.0-SNAPSHOT.jar:4.10.0-SNAPSHOT]
at org.jivesoftware.openfire.container.PluginMonitor$MonitorTask$4.call(PluginMonitor.java:380) [xmppserver-4.10.0-SNAPSHOT.jar:4.10.0-SNAPSHOT]
at org.jivesoftware.openfire.container.PluginMonitor$MonitorTask$4.call(PluginMonitor.java:368) [xmppserver-4.10.0-SNAPSHOT.jar:4.10.0-SNAPSHOT]
at java.util.concurrent.FutureTask.run(FutureTask.java:264) [?:?]
at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1136) [?:?]
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:635) [?:?]
at java.lang.Thread.run(Thread.java:840) [?:?]
Caused by: java.lang.ClassNotFoundException: org.eclipse.jetty.websocket.server.JettyWebSocketCreator
at java.net.URLClassLoader.findClass(URLClassLoader.java:445) ~[?:?]
at java.lang.ClassLoader.loadClass(ClassLoader.java:592) ~[?:?]
at java.lang.ClassLoader.loadClass(ClassLoader.java:525) ~[?:?]
... 8 more</code></pre>
</fieldset>
<p>Consider using the EE8 JettyWebSocketServlet from <code>org.eclipse.jetty.ee8.websocket.server.JettyWebSocketServlet</code> to replace <code>org.eclipse.jetty.websocket.server.JettyWebSocketCreator</code>.</p>
</section>
</section>

<footer>
<p>
An active support community for Openfire is available at
<a href="https://discourse.igniterealtime.org">https://discourse.igniterealtime.org</a>.
</p>
</footer>

</article>

</body>
</html>
Loading
Loading