This change introduces major updates to the App Engine Java SDK, including:

- Support for Jetty 12.1 and Jakarta EE 11 via a new `java25` runtime option.
- A major version bump to `3.0.0` due to compilation target changes and API refactoring.
- Refactoring of generic Jakarta EE API packages from `ee10` to `jakarta`.

**Release 3.0.0**
The project version is bumped to `3.0.0-SNAPSHOT`, and the base compilation target is raised from Java 8 to Java 17. This major version increment reflects breaking API package changes and the new baseline Java version.

**Jetty 12.1 and Jakarta EE 11 Support**
- Adds build configurations, SDK classes (`Jetty121EE8Sdk`, `Jetty121EE11Sdk`), and runtime handlers (`EE11AppVersionHandlerFactory`) to support Jetty 12.1 with both EE8 and EE11 applications.
- Introduces a new `java25` runtime option in `appengine-web.xml`, which defaults to using Jetty 12.1 with EE11 support.
- Jetty 12.0 continues to support EE8 and EE10 for `java17` and `java21` runtimes.

**API Refactoring: `ee10` to `jakarta`**
To better reflect that common servlet APIs are part of Jakarta EE rather than a specific version like EE10, packages named `ee10` have been refactored. The existing `ee10` classes are now deprecated with `@Deprecated(since = "3.0.0")` and point to their replacements in new `jakarta` packages via `{@link}` tags in Javadoc.

This includes:
- `com.google.appengine.api.blobstore.ee10.*` -> `c.g.a.api.blobstore.jakarta.*`
- `com.google.appengine.api.mail.ee10.*` -> `c.g.a.api.mail.jakarta.*`
- `com.google.appengine.api.taskqueue.ee10.*` -> `c.g.a.api.taskqueue.jakarta.*`
- `com.google.appengine.api.utils.ee10.*` -> `c.g.a.api.utils.jakarta.*`
- `c.g.apphosting.utils.remoteapi.EE10RemoteApiServlet` -> `c.g.apphosting.utils.remoteapi.JakartaRemoteApiServlet`
- `c.g.apphosting.utils.servlet.ee10.*` -> `c.g.apphosting.utils.servlet.jakarta.*`

**Breaking Change:**
Applications using classes from the `ee10` packages listed above must update their imports to use the corresponding `jakarta` packages when upgrading to SDK 3.0.0.

**Other Changes:**
- Test infrastructure updated to handle new Jetty/EE versions.
- Demo applications added/updated for Jakarta EE compatibility.

PiperOrigin-RevId: 806498954
Change-Id: I894364e865eb6735b365563e956a3e043632766c

Author: ludoch

api/pom.xml

@@ -21,7 +21,7 @@
   <parent>
     <groupId>com.google.appengine</groupId>
     <artifactId>parent</artifactId>
-    <version>2.0.40-SNAPSHOT</version>
+    <version>3.0.0-SNAPSHOT</version>
   </parent>
   <properties>
     <maven.deploy.skip>true</maven.deploy.skip>

api/src/main/java/com/google/appengine/api/blobstore/ee10/BlobstoreService.java

@@ -29,10 +29,10 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * {@code BlobstoreService} allows you to manage the creation and
- * serving of large, immutable blobs to users.
- *
+ * @deprecated as of version 3.0, use {@link
+ *     com.google.appengine.api.blobstore.jakarta.BlobstoreService} instead.
  */
+@Deprecated(since = "3.0.0")
 public interface BlobstoreService {
   public static final int MAX_BLOB_FETCH_SIZE = (1 << 20) - (1 << 15);  // 1MB - 16K;
 

api/src/main/java/com/google/appengine/api/blobstore/ee10/BlobstoreServiceFactory.java

@@ -17,7 +17,11 @@
 package com.google.appengine.api.blobstore.ee10;
 
 
-/** Creates {@link BlobstoreService} implementations for java EE 10. */
+/**
+ * @deprecated as of version 3.0, use {@link
+ *     com.google.appengine.api.blobstore.jakarta.BlobstoreServiceFactory} instead.
+ */
+@Deprecated(since = "3.0.0")
 public final class BlobstoreServiceFactory {
 
   /** Creates a {@code BlobstoreService} for java EE 10. */

api/src/main/java/com/google/appengine/api/blobstore/ee10/BlobstoreServiceImpl.java

@@ -50,10 +50,10 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * {@code BlobstoreServiceImpl} is an implementation of {@link BlobstoreService} that makes API
- * calls to {@link ApiProxy}.
- *
+ * @deprecated as of version 3.0, use {@link
+ *     com.google.appengine.api.blobstore.jakarta.BlobstoreServiceImpl} instead.
  */
+@Deprecated(since = "3.0.0")
 class BlobstoreServiceImpl implements BlobstoreService {
   static final String PACKAGE = "blobstore";
   static final String SERVE_HEADER = "X-AppEngine-BlobKey";

api/src/main/java/com/google/appengine/api/blobstore/jakarta/BlobstoreService.java

@@ -0,0 +1,243 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * Licensed 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
+ *
+ *     https://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 com.google.appengine.api.blobstore.jakarta;
+
+import com.google.appengine.api.blobstore.BlobInfo;
+import com.google.appengine.api.blobstore.BlobKey;
+import com.google.appengine.api.blobstore.ByteRange;
+import com.google.appengine.api.blobstore.FileInfo;
+import com.google.appengine.api.blobstore.UploadOptions;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import java.io.IOException;
+import java.util.List;
+import java.util.Map;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * {@code BlobstoreService} allows you to manage the creation and
+ * serving of large, immutable blobs to users.
+ *
+ */
+public interface BlobstoreService {
+  public static final int MAX_BLOB_FETCH_SIZE = (1 << 20) - (1 << 15);  // 1MB - 16K;
+
+  /**
+   * Create an absolute URL that can be used by a user to
+   * asynchronously upload a large blob.  Upon completion of the
+   * upload, a callback is made to the specified URL.
+   *
+   * @param successPath A relative URL which will be invoked
+   * after the user successfully uploads a blob. Must start with a "/",
+   * and must be URL-encoded.
+   *
+   * @throws IllegalArgumentException If successPath was not valid.
+   * @throws BlobstoreFailureException If an error occurred while
+   * communicating with the blobstore.
+   */
+  String createUploadUrl(String successPath);
+
+  /**
+   * Create an absolute URL that can be used by a user to
+   * asynchronously upload a large blob.  Upon completion of the
+   * upload, a callback is made to the specified URL.
+   *
+   * @param successPath A relative URL which will be invoked
+   * after the user successfully uploads a blob. Must start with a "/".
+   * @param uploadOptions Specific options applicable only for this
+   * upload URL.
+   *
+   * @throws IllegalArgumentException If successPath was not valid.
+   * @throws BlobstoreFailureException If an error occurred while
+   * communicating with the blobstore.
+   */
+  String createUploadUrl(String successPath, UploadOptions uploadOptions);
+
+  /**
+   * Arrange for the specified blob to be served as the response
+   * content for the current request.  {@code response} should be
+   * uncommitted before invoking this method, and should be assumed to
+   * be committed after invoking it.  Any content written before
+   * calling this method will be ignored.  You may, however, append
+   * custom headers before or after calling this method.
+   *
+   * <p>Range header will be automatically translated from the Content-Range
+   * header in the response.
+   *
+   * @param blobKey Blob-key to serve in response.
+   * @param response HTTP response object.
+   *
+   * @throws IOException If an I/O error occurred.
+   * @throws IllegalStateException If {@code response} was already committed.
+   */
+  void serve(BlobKey blobKey, HttpServletResponse response) throws IOException;
+
+  /**
+   * Arrange for the specified blob to be served as the response
+   * content for the current request.  {@code response} should be
+   * uncommitted before invoking this method, and should be assumed to
+   * be committed after invoking it.  Any content written before
+   * calling this method will be ignored.  You may, however, append
+   * custom headers before or after calling this method.
+   *
+   * <p>This method will set the App Engine blob range header to serve a
+   * byte range of that blob.
+   *
+   * @param blobKey Blob-key to serve in response.
+   * @param byteRange Byte range to serve in response.
+   * @param response HTTP response object.
+   *
+   * @throws IOException If an I/O error occurred.
+   * @throws IllegalStateException If {@code response} was already committed.
+   */
+  void serve(BlobKey blobKey, @Nullable ByteRange byteRange, HttpServletResponse response)
+      throws IOException;
+
+  /**
+   * Arrange for the specified blob to be served as the response
+   * content for the current request.  {@code response} should be
+   * uncommitted before invoking this method, and should be assumed to
+   * be committed after invoking it.  Any content written before
+   * calling this method will be ignored.  You may, however, append
+   * custom headers before or after calling this method.
+   *
+   * <p>This method will set the App Engine blob range header to the content
+   * specified.
+   *
+   * @param blobKey Blob-key to serve in response.
+   * @param rangeHeader Content for range header to serve.
+   * @param response HTTP response object.
+   *
+   * @throws IOException If an I/O error occurred.
+   * @throws IllegalStateException If {@code response} was already committed.
+   */
+  void serve(BlobKey blobKey, String rangeHeader, HttpServletResponse response)
+      throws IOException;
+
+  /**
+   * Get byte range from the request.
+   *
+   * @param request HTTP request object.
+   *
+   * @return Byte range as parsed from the HTTP range header.  null if there is no header.
+   *
+   * @throws RangeFormatException Unable to parse header because of invalid format.
+   * @throws UnsupportedRangeFormatException Header is a valid HTTP range header, the specific
+   * form is not supported by app engine.  This includes unit types other than "bytes" and multiple
+   * ranges.
+   */
+  @Nullable ByteRange getByteRange(HttpServletRequest request);
+
+  /**
+   * Permanently deletes the specified blobs.  Deleting unknown blobs is a
+   * no-op.
+   *
+   * @throws BlobstoreFailureException If an error occurred while
+   * communicating with the blobstore.
+   */
+  void delete(BlobKey... blobKeys);
+
+  /**
+   * Returns the {@link BlobKey} for any files that were uploaded, keyed by the
+   * upload form "name" field.
+   * <p>This method should only be called from within a request served by
+   * the destination of a {@code createUploadUrl} call.
+   *
+   * @throws IllegalStateException If not called from a blob upload
+   * callback request.
+   *
+   * @deprecated Use {@link #getUploads} instead. Note that getUploadedBlobs
+   * does not handle cases where blobs have been uploaded using the
+   * multiple="true" attribute of the file input form element.
+   */
+  @Deprecated Map<String, BlobKey> getUploadedBlobs(HttpServletRequest request);
+
+  /**
+   * Returns the {@link BlobKey} for any files that were uploaded, keyed by the
+   * upload form "name" field.
+   * This method should only be called from within a request served by
+   * the destination of a {@link #createUploadUrl} call.
+   *
+   * @throws IllegalStateException If not called from a blob upload
+   * callback request.
+   * @see #getBlobInfos
+   * @see #getFileInfos
+   */
+  Map<String, List<BlobKey>> getUploads(HttpServletRequest request);
+
+  /**
+   * Returns the {@link BlobInfo} for any files that were uploaded, keyed by the
+   * upload form "name" field.
+   * This method should only be called from within a request served by
+   * the destination of a {@link #createUploadUrl} call.
+   *
+   * @throws IllegalStateException If not called from a blob upload
+   * callback request.
+   * @see #getFileInfos
+   * @see #getUploads
+   * @since 1.7.5
+   */
+  Map<String, List<BlobInfo>> getBlobInfos(HttpServletRequest request);
+
+  /**
+   * Returns the {@link FileInfo} for any files that were uploaded, keyed by the
+   * upload form "name" field.
+   * This method should only be called from within a request served by
+   * the destination of a {@link #createUploadUrl} call.
+   *
+   * Prefer this method over {@link #getBlobInfos} or {@link #getUploads} if
+   * uploading files to Cloud Storage, as the FileInfo contains the name of the
+   * created filename in Cloud Storage.
+   *
+   * @throws IllegalStateException If not called from a blob upload
+   * callback request.
+   * @see #getBlobInfos
+   * @see #getUploads
+   * @since 1.7.5
+   */
+  Map<String, List<FileInfo>> getFileInfos(HttpServletRequest request);
+
+  /**
+   * Get fragment from specified blob.
+   *
+   * @param blobKey Blob-key from which to fetch data.
+   * @param startIndex Start index of data to fetch.
+   * @param endIndex End index (inclusive) of data to fetch.
+   * @throws IllegalArgumentException If blob not found, indexes are negative, indexes are inverted
+   *     or fetch size is too large.
+   * @throws SecurityException If the application does not have access to the blob.
+   * @throws BlobstoreFailureException If an error occurred while communicating with the blobstore.
+   */
+  byte[] fetchData(BlobKey blobKey, long startIndex, long endIndex);
+
+  /**
+   * Create a {@link BlobKey} for a Google Storage File.
+   *
+   * <p>The existence of the file represented by filename is not checked, hence a BlobKey can be
+   * created for a file that does not currently exist.
+   *
+   * <p>You can safely persist the {@link BlobKey} generated by this function.
+   *
+   * <p>The created {@link BlobKey} can then be used as a parameter in API methods that can support
+   * objects in Google Storage, for example {@link serve}.
+   *
+   * @param filename The Google Storage filename. The filename must be in the format
+   *     "/gs/bucket_name/object_name".
+   * @throws IllegalArgumentException If the filename does not have the prefix "/gs/".
+   */
+  BlobKey createGsBlobKey(String filename);
+}

api/src/main/java/com/google/appengine/api/blobstore/jakarta/BlobstoreServiceFactory.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * Licensed 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
+ *
+ *     https://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 com.google.appengine.api.blobstore.jakarta;
+
+
+/** Creates {@link BlobstoreService} implementations for java EE 10. */
+public final class BlobstoreServiceFactory {
+
+  /** Creates a {@code BlobstoreService} for java EE 10. */
+  public static BlobstoreService getBlobstoreService() {
+    return new BlobstoreServiceImpl();
+  }
+
+}