This is an automated email from the ASF dual-hosted git repository.
jochen pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-fileupload.git
The following commit(s) were added to refs/heads/master by this push:
new 537b7f0 Updating the using document to reflect the support for
Jakarta Servlet API.
new c101fc2 Merge branch 'master' of
https://gitbox.apache.org/repos/asf/commons-fileupload
537b7f0 is described below
commit 537b7f0ba98f08f284d90bdf9be700deb9414414
Author: Jochen Wiedmann <jochen.wiedm...@gmail.com>
AuthorDate: Mon May 4 21:38:15 2020 +0200
Updating the using document to reflect the support for Jakarta Servlet API.
---
.../fileupload2/jaksrvlt/JakSrvltFileCleaner.java | 89 ++++++++++++++++
src/site/apt/migration.apt.vm | 116 +++++++++++++++++++++
src/site/site.xml | 23 ++--
src/site/xdoc/using.xml | 24 ++++-
4 files changed, 240 insertions(+), 12 deletions(-)
diff --git
a/src/main/java/org/apache/commons/fileupload2/jaksrvlt/JakSrvltFileCleaner.java
b/src/main/java/org/apache/commons/fileupload2/jaksrvlt/JakSrvltFileCleaner.java
new file mode 100644
index 0000000..1aeb6a5
--- /dev/null
+++
b/src/main/java/org/apache/commons/fileupload2/jaksrvlt/JakSrvltFileCleaner.java
@@ -0,0 +1,89 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.fileupload2.jaksrvlt;
+
+
+import org.apache.commons.io.FileCleaningTracker;
+
+import jakarta.servlet.ServletContext;
+import jakarta.servlet.ServletContextEvent;
+import jakarta.servlet.ServletContextListener;
+
+/**
+ * A servlet context listener, which ensures that the
+ * {@link FileCleaningTracker}'s reaper thread is terminated,
+ * when the web application is destroyed.
+ */
+public class JakSrvltFileCleaner implements ServletContextListener {
+
+ /**
+ * Attribute name, which is used for storing an instance of
+ * {@link FileCleaningTracker} in the web application.
+ */
+ public static final String FILE_CLEANING_TRACKER_ATTRIBUTE
+ = JakSrvltFileCleaner.class.getName() + ".FileCleaningTracker";
+
+ /**
+ * Returns the instance of {@link FileCleaningTracker}, which is
+ * associated with the given {@link ServletContext}.
+ *
+ * @param pServletContext The servlet context to query
+ * @return The contexts tracker
+ */
+ public static FileCleaningTracker
+ getFileCleaningTracker(ServletContext pServletContext) {
+ return (FileCleaningTracker)
+ pServletContext.getAttribute(FILE_CLEANING_TRACKER_ATTRIBUTE);
+ }
+
+ /**
+ * Sets the instance of {@link FileCleaningTracker}, which is
+ * associated with the given {@link ServletContext}.
+ *
+ * @param pServletContext The servlet context to modify
+ * @param pTracker The tracker to set
+ */
+ public static void setFileCleaningTracker(ServletContext pServletContext,
+ FileCleaningTracker pTracker) {
+ pServletContext.setAttribute(FILE_CLEANING_TRACKER_ATTRIBUTE,
pTracker);
+ }
+
+ /**
+ * Called when the web application is initialized. Does
+ * nothing.
+ *
+ * @param sce The servlet context, used for calling
+ * {@link #setFileCleaningTracker(ServletContext, FileCleaningTracker)}.
+ */
+ @Override
+ public void contextInitialized(ServletContextEvent sce) {
+ setFileCleaningTracker(sce.getServletContext(),
+ new FileCleaningTracker());
+ }
+
+ /**
+ * Called when the web application is being destroyed.
+ * Calls {@link FileCleaningTracker#exitWhenFinished()}.
+ *
+ * @param sce The servlet context, used for calling
+ * {@link #getFileCleaningTracker(ServletContext)}.
+ */
+ @Override
+ public void contextDestroyed(ServletContextEvent sce) {
+ getFileCleaningTracker(sce.getServletContext()).exitWhenFinished();
+ }
+}
diff --git a/src/site/apt/migration.apt.vm b/src/site/apt/migration.apt.vm
new file mode 100644
index 0000000..d443e1f
--- /dev/null
+++ b/src/site/apt/migration.apt.vm
@@ -0,0 +1,116 @@
+~~
+~~ Licensed to the Apache Software Foundation (ASF) under one or more
+~~ contributor license agreements. See the NOTICE file distributed with
+~~ this work for additional information regarding copyright ownership.
+~~ The ASF licenses this file to You under the Apache License, Version 2.0
+~~ (the "License"); you may not use this file except in compliance with
+~~ the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing, software
+~~ distributed under the License is distributed on an "AS IS" BASIS,
+~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+~~ See the License for the specific language governing permissions and
+~~ limitations under the License.
+~~
+ ---------
+ Migration
+ ---------
+
+Migration
+
+ This document provides advice for migration between versions of Commons
FileUpload, and between versions
+ of the underlying Servlet API.
+
+# Migrating to Commons FileUpload 2
+
+ Commons Fileupload is the first version, that drops compatibility to
previous versions. This means, that
+ you need to adapt your projects as follows:
+
+ 1. Upgrade your Java version to 8, or later.
+
+ 2. In your dependency declaration, change the groupId to
org.apache.commons, the artifactId to
+ commons-fileupload2, and the version number to ${project.version}.
+
+ 2. Change namespace org.apache.commons.fileupload to
org.apache.commons.fileupload2.
+
+ Example: Change
+
++-------------------------------------------
+ import org.apache.commons.fileupload.servlet.ServletFileUpload;
++-------------------------------------------
+
+ to
+
++-------------------------------------------
+ import org.apache.commons.fileupload2.servlet.ServletFileUpload;
++-------------------------------------------
+
+# Migrating to Jakarta Servlet API, Version 5, or later.
+
+ Most existing projects, that are using Commons Fileupload, are based on the
Java Servlet API, version
+ two, or later. In Jakarta EE 9, this is going to be replaced with the
Jakarta Servlet API, version 5.
+ Basically, this means, that user code is supposed to use the
<<jakarta.servlet>> package, rather than
+ the <<javax.servlet>> package.
+
+ For applications, that are using Commons Fileupload, this means, that you
need to
+
+ 1. Upgrade Commons Fileupload to version 2, or later.
+
+ 2. Replace the classes from <<org.apache.commons.fileupload.servlet>>, or
+ <<org.apache.commons.filupload2.servlet>> with the corresponding
+ classes from <<org.apache.commons.fileupload2.jaksrvlt>>. Namely, replace
+
+*-------------------------------------------------------------
*----------------------------------------------------------------*
+| <<Old class name>> | <<New class
name>> |
+*-------------------------------------------------------------
*----------------------------------------------------------------*
+| org.apache.commons.fileupload.servlet.ServletFileUpload |
org.apache.commons.fileupload2.jaksrvlt.JakSrvltFileUpload |
+| org.apache.commons.fileupload2.servlet.ServletFileUpload |
|
+*-------------------------------------------------------------
*----------------------------------------------------------------*
+| org.apache.commons.fileupload.servlet.ServletRequestContext |
org.apache.commons.fileupload2.jaksrvlt.JakSrvltRequestContext |
+| org.apache.commons.fileupload2.servlet.ServletRequestContext |
|
+*--------------------------------------------------------------*----------------------------------------------------------------*
+| org.apache.commons.fileupload2.servlet.FileCleanerCleanup |
org.apache.commons.fileupload2.jaksrvlt.JakSrvltFileCleaner |
+*--------------------------------------------------------------*----------------------------------------------------------------*
+
+## Example
+
+The following example demonstrates, how to use Commons Fileupload with the
Java Servlet API, version 5:
+
++-------------------------------------------
+ import java.io.IOException;
+ import java.util.List;
+
+ import org.apache.commons.fileupload2.FileItem;
+ import org.apache.commons.fileupload2.FileItemFactory;
+ import org.apache.commons.fileupload2.FileUpload;
+ import org.apache.commons.fileupload2.FileUploadException;
+ import org.apache.commons.fileupload2.disk.DiskFileItemFactory;
+ import org.apache.commons.fileupload2.jaksrvlt.JakSrvltFileUpload;
+ import org.apache.commons.fileupload2.jaksrvlt.JakSrvltRequestContext;
+
+ import jakarta.servlet.ServletException;
+ import jakarta.servlet.http.HttpServlet;
+ import jakarta.servlet.http.HttpServletRequest;
+ import jakarta.servlet.http.HttpServletResponse;
+ public class SampleServlet extends HttpServlet {
+ private static final long serialVersionUID = -8899322882932916888L;
+
+ @Override
+ protected void doPost(HttpServletRequest req, HttpServletResponse
resp) throws ServletException, IOException {
+ if (JakSrvltFileUpload.isMultipartContent(req)) {
+ final FileItemFactory fileItemfactory = new
DiskFileItemFactory();
+ final FileUpload fileUpload = new
JakSrvltFileUpload(fileItemfactory);
+ final List<FileItem> items;
+ try {
+ items = fileUpload.parseRequest(new
JakSrvltRequestContext(req));
+ } catch (FileUploadException e) {
+ throw new ServletException(e);
+ }
+ // Process the uploaded file items here...
+ }
+ }
+ }
+
++-------------------------------------------
diff --git a/src/site/site.xml b/src/site/site.xml
index 90a956f..0f1dc17 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -26,17 +26,18 @@
<body>
<menu name="Commons FileUpload">
- <item name="Overview" href="/index.html" />
- <item name="User guide" href="/using.html" />
- <item name="Streaming API" href="/streaming.html" />
- <item name="FAQ" href="/faq.html" />
- <item name="Javadoc (Latest release)"
href="/javadocs/api-release/index.html" />
- <item name="Download" href="/download_fileupload.cgi" />
- <item name="Security Reports" href="/security-reports.html"/>
- <item name="Mailing lists" href="/mail-lists.html" />
- <item name="Issue Tracking" href="/issue-tracking.html" />
- <item name="Team" href="/team-list.html" />
- <item name="Source repository" href="/scm.html" />
+ <item name="Overview" href="./index.html" />
+ <item name="User guide" href="./using.html" />
+ <item name="Migration" href="./migration.html"/>
+ <item name="Streaming API" href="./streaming.html" />
+ <item name="FAQ" href="./faq.html" />
+ <item name="Javadoc (Latest release)"
href="./javadocs/api-release/index.html" />
+ <item name="Download" href="./download_fileupload.cgi" />
+ <item name="Security Reports" href="./security-reports.html"/>
+ <item name="Mailing lists" href="./mail-lists.html" />
+ <item name="Issue Tracking" href="./issue-tracking.html" />
+ <item name="Team" href="./team-list.html" />
+ <item name="Source repository" href="./scm.html" />
</menu>
</body>
diff --git a/src/site/xdoc/using.xml b/src/site/xdoc/using.xml
index 8d1f0b4..1ff5529 100644
--- a/src/site/xdoc/using.xml
+++ b/src/site/xdoc/using.xml
@@ -84,7 +84,7 @@
</p>
</section>
- <section name="Servlets and Portlets">
+ <section name="Servlets, Jakarta Servlets, and Portlets">
<p>
Starting with version 1.1, FileUpload supports file upload requests in
both servlet and portlet environments. The usage is almost identical in
@@ -104,6 +104,28 @@
substitute the <code>ActionRequest</code> class.
</li>
</ul>
+ <p>Version 2 of FileUpload introduces support for the Jakarta Servlet
API 5.
+ (This API is the successor to the classic servlet environment, which
+ basically renames the <code>javax.servlet</code> package to
+ <code>jakarta.servlet</code>). If you are building a Jakarta Servlet
application,
+ keep the following in mind, as you read this document:</p>
+ <ul>
+ <li>
+ Where you see references to the <code>ServletFileUpload</code>
class,
+ substitute the <code>JakSrvltFileUpload</code> class.
+ </li>
+ <li>
+ Likewise, references to the <code>FileCleanerCleanup</code> class
should
+ be substituted with the <code>JakSrvltFileCleaner</code> class.
+ </li>
+ <li>
+ Where you see references to the <code>HttpServletRequest</code>
class
+ (as in javax.servlet.http.HttpServletRequest), then substitute the
+ <code>jakarta.servlet.http.HttpServletRequest</code> class. For
well
+ written code, this should be as simple as changing a single import
+ statement.
+ </li>
+ </ul>
</section>
<section name="Parsing the request">
