Add package-info.java files for Blobstore, Mail, and Task Queue APIs to improve javadocs.

PiperOrigin-RevId: 819326545
Change-Id: Ibe29e682310f623d945996d00ef8b07decb32a3a

Author: ludoch

api/src/main/java/com/google/appengine/api/blobstore/ee10/package-info.java

@@ -0,0 +1,24 @@
+/*
+ * 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.
+ */
+
+/**
+/**
+ * @deprecated as of version 3.0, use {@link
+ *     com.google.appengine.api.blobstore.jakarta} instead.
+ */
+@Deprecated(since = "3.0.0")
+
+package com.google.appengine.api.blobstore.ee10;

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

@@ -17,10 +17,10 @@
 package com.google.appengine.api.blobstore.jakarta;
 
 
-/** Creates {@link BlobstoreService} implementations for java EE 10. */
+/** Creates {@link BlobstoreService} implementations for jakarta APIs. */
 public final class BlobstoreServiceFactory {
 
-  /** Creates a {@code BlobstoreService} for java EE 10. */
+  /** Creates a {@code BlobstoreService} for jakarta APIs. */
   public static BlobstoreService getBlobstoreService() {
     return new BlobstoreServiceImpl();
   }

api/src/main/java/com/google/appengine/api/blobstore/jakarta/package-info.java

@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+
+/**
+ * Provides management and persistent storage of large, immutable byte arrays. This allows
+ * applications to accept, save, and later serve files of any size.
+ *
+ * @see com.google.appengine.api.blobstore.BlobstoreService
+ * @see <a href="http://cloud.google.com/appengine/docs/java/blobstore/">The Blobstore Java API in
+ *     the <em>Google App Engine Developer's Guide</em></a>.
+ */
+
+package com.google.appengine.api.blobstore.jakarta;

api/src/main/java/com/google/appengine/api/mail/ee10/package-info.java

@@ -0,0 +1,23 @@
+/*
+ * 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.
+ */
+
+/**
+/**
+ * @deprecated as of version 3.0, use {@link
+ *     com.google.appengine.api.mail.jakarta} instead.
+ */
+@Deprecated(since = "3.0.0")
+package com.google.appengine.api.mail.ee10;

api/src/main/java/com/google/appengine/api/mail/jakarta/package-info.java

@@ -0,0 +1,45 @@
+/*
+ * 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.
+ */
+
+/**
+ * Provides a service to send email messages on behalf of administrators or authenticated users,
+ * also accessible via a <a
+ * href="http://www.oracle.com/technetwork/java/javamail/index.html">JavaMail</a> interface.
+ * Receiving messages is not supported via the JavaMail API but is supported via <a
+ * href="http://cloud.google.com/appengine/docs/java/mail/receiving.html">an HTTP interface</a>.
+ *
+ * <p>This low-level API is intended primarily for framework authors. For application developers we
+ * provide a custom {@code javax.mail.Transport} that allows the standard {@code javax.mail}
+ * interface to be used to send emails. No special configuration is required to send emails via this
+ * interface.
+ *
+ * <p>The {@link com.google.appengine.api.mail.MailService.Message} class represents a message,
+ * including sender and recipient information, and possibly attachments as {@link
+ * com.google.appengine.api.mail.MailService.Attachment} objects. These can be independently created
+ * via their respective constructors.
+ *
+ * <p>Sending a message requires a {@link com.google.appengine.api.mail.MailService} object, created
+ * by the {@link com.google.appengine.api.mail.MailServiceFactory}. Messages are sent
+ * asynchronously, so the {@code MailService} methods will
+ * always succeed immediately. Any errors in the mail message will be returned to the sender's
+ * address as "bounce" messages.
+ *
+ * @see com.google.appengine.api.mail.MailService
+ * @see <a href="http://cloud.google.com/appengine/docs/java/mail/">The Mail Java API in the
+ *     <em>Google App Engine Developer's Guide</em></a>
+ * @see <a href="http://www.oracle.com/technetwork/java/javamail/index.html">JavaMail API</a>
+ */
+package com.google.appengine.api.mail.jakarta;

api/src/main/java/com/google/appengine/api/taskqueue/ee10/package-info.java

@@ -0,0 +1,23 @@
+/*
+ * 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.
+ */
+
+/**
+/**
+ * @deprecated as of version 3.0, use {@link
+ *     com.google.appengine.api.taskqueue.jakarta} instead.
+ */
+@Deprecated(since = "3.0.0")
+package com.google.appengine.api.taskqueue.ee10;

api/src/main/java/com/google/appengine/api/taskqueue/jakarta/DeferredTaskContext.java

@@ -23,11 +23,11 @@
 import java.util.Map;
 
 /**
- * Resources for managing {@link DeferredTask}.
+ * Resources for managing {@link com.google.appengine.api.taskqueue.DeferredTask}.
  *
  */
 public class DeferredTaskContext {
-  /** The content type of a serialized {@link DeferredTask}. */
+  /** The content type of a serialized {@link com.google.appengine.api.taskqueue.DeferredTask}. */
   public static final String RUNNABLE_TASK_CONTENT_TYPE =
       "application/x-binary-app-engine-java-runnable-task";
 

api/src/main/java/com/google/appengine/api/taskqueue/jakarta/package-info.java

@@ -0,0 +1,24 @@
+/*
+ * 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.
+ */
+
+/**
+ * Provides a mechanism to perform work initiated by a user request, outside of that request.
+ *
+ * @see com.google.appengine.api.taskqueue.Queue
+ * @see <a href="http://cloud.google.com/appengine/docs/java/taskqueue/">The Task Queue Java API in
+ *     the <em>Google App Engine Developer's Guide</em></a>.
+ */
+package com.google.appengine.api.taskqueue.jakarta;

api/src/main/java/com/google/apphosting/utils/servlet/jakarta/DeferredTaskServlet.java

@@ -43,7 +43,7 @@
  *    <servlet>
  *      <servlet-name>/_ah/queue/__deferred__</servlet-name>
  *      <servlet-class
- *        >com.google.apphosting.utils.servlet.DeferredTaskServlet</servlet-class>
+ *        >com.google.apphosting.utils.servlet.jakarta.DeferredTaskServlet</servlet-class>
  *    </servlet>
  *
  *    <servlet-mapping>

kokoro/gcp_ubuntu/publish_javadoc.sh

@@ -49,9 +49,9 @@ export NAME=appengine-java11-bundled-services
 export VERSION=11
 
 sudo apt-get update
-sudo apt-get install -y openjdk-17-jdk
-sudo update-java-alternatives --set java-1.17.0-openjdk-amd64
-export JAVA_HOME="$(update-java-alternatives -l | grep "1.17" | head -n 1 | tr -s " " | cut -d " " -f 3)"
+sudo apt-get install -y openjdk-21-jdk
+sudo update-java-alternatives --set java-1.21.0-openjdk-amd64
+export JAVA_HOME="$(update-java-alternatives -l | grep "1.21" | head -n 1 | tr -s " " | cut -d " " -f 3)"
 
 # Make sure `JAVA_HOME` is set.
 echo "JAVA_HOME = $JAVA_HOME"
@@ -68,7 +68,7 @@ cd api
 
 pushd target/docfx-yml
 
-# create metadata for Java11/17
+# create metadata for Java11/17/25
 python3 -m docuploader create-metadata \
  --name appengine-java-gen2-bundled-services \
  --version 2.0.0 \