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 7f5b0d9 Adding minimal documentation for the org.apache.commons.fileupload2 package. 7f5b0d9 is described below commit 7f5b0d9a50b4b929bbec4fbac98b22957a603648 Author: Jochen Wiedmann <jochen.wiedm...@gmail.com> AuthorDate: Mon May 4 21:38:15 2020 +0200 Adding minimal documentation for the org.apache.commons.fileupload2 package. --- .../fileupload2/jaksrvlt/JakSrvltFileCleaner.java | 89 ++++++++++++++++ src/site/apt/migration.apt.vm | 116 +++++++++++++++++++++ src/site/site.xml | 23 ++-- 3 files changed, 217 insertions(+), 11 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>