גישה לשירותים בחבילה מדור קודם ל-Java 11 ומעלה

בדף הזה מוסבר איך להתקין ולהשתמש בשירותים הכלולים בגרסה הנתמכת האחרונה של Java בסביבה הרגילה של App Engine. האפליקציה יכולה לגשת לשירותים הכלולים באמצעות App Engine API JAR.

לפני שמתחילים

התקנת קובץ ה-JAR של App Engine API

כדי להשתמש בשירותים מדור קודם שצורפו לאפליקציית Java העדכנית הנתמכת, צריך להשתמש בקובץ appengine-web.xml כדי להגדיר את האפליקציה (במקום בקובץ app.yaml).

בדוגמה הבאה מוסבר איך להוסיף הגדרות תצורה בקובץ appengine-web.xml לגרסאות שונות של Java. כדי להשתמש בגרסה הנתמכת האחרונה בהגדרת ברירת המחדל, צריך לעדכן את רכיבי ה-servlet של האפליקציה ואת התלות שלה כך שיכללו את מרחב השמות Jakarta. מידע נוסף על אפשרויות התצורה זמין במאמר שדרוג אפליקציה קיימת.

מוסיפים את ההגדרות הבאות לקובץ appengine-web.xml בהתאם לגרסת Java: בדוגמה הזו, האפליקציה יכולה להשתמש רק בשירותים המצורפים Datastore ו-Memcache:

Java 25 (EE 11) 

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
      <runtime>java25</runtime>
      <system-properties>
        <property name="appengine.use.EE11" value="true"/>
      </system-properties>
      <app-engine-bundled-services>
        <api>datastore_v3</api>
        <api>memcache</api>
        <!-- LIST YOUR SERVICES -->
      </app-engine-bundled-services>
  </appengine-web-app>

Java 21 (EE 10) 

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
      <runtime>java21</runtime>
      <system-properties>
        <property name="appengine.use.EE10" value="true"/>
      </system-properties>
      <app-engine-bundled-services>
        <api>datastore_v3</api>
        <api>memcache</api>
        <!-- LIST YOUR SERVICES -->
      </app-engine-bundled-services>
  </appengine-web-app>

Java 17 (EE 8) 

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
      <runtime>java17</runtime>
      <system-properties>
        <property name="appengine.use.EE8" value="true"/>
      </system-properties>
      <app-engine-bundled-services>
        <api>datastore_v3</api>
        <api>memcache</api>
        <!-- LIST YOUR SERVICES -->
      </app-engine-bundled-services>
  </appengine-web-app>

כדי לציין את השירותים הקודמים בחבילה כתלות, מוסיפים את השורות הבאות לקובץ pom.xml:

 <dependency>
    <groupId>com.google.appengine</groupId>
    <artifactId>appengine-api-1.0-sdk</artifactId>
    <version>2.0.31</version> <!-- or later-->
  </dependency>

אם האפליקציה משתמשת בקובץ web.xml, צריך להגדיר את הרכיב <app-engine-bundled-service>. הגדרות התצורה של app_engine_bundled_services מפורטות במאמר web.xml.

<app-engine-bundled-services>
  <api>memcache</api>
  <api>datastore_v3</api>
  <api>modules</api>
  <api>search</api>
  <api><!-- LIST YOUR SERVICES --></api>
</app-engine-bundled-services>

כדי לפרוס את אפליקציית Java 25, מריצים את הפקודה mvn appengine:deploy או את הפקודה gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml באפליקציית אינטרנט שעברה קומפילציה והכנה לפריסה.

נקודת כניסה שמוגדרת כברירת מחדל ל-Java 25

אפליקציות Java 25 נהנות מהגדרות משתמש נוספות כשמפעילים את ה-JVM לאפליקציות אינטרנט.

נקודת הכניסה שמשמשת לאתחול ה-JVM כברירת מחדל נוצרת על ידי App Engine buildpacks. בעצם, זה שווה להגדרה של נקודת הכניסה הזו בקובץ appengine-web.xml. לדוגמה:

java --add-opens java.base/java.lang=ALL-UNNAMED  --add-opens java.base/java.nio.charset=ALL-UNNAMED -showversion -Xms32M -Xmx204M -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:+PrintCommandLineFlags -Dclasspath.runtimebase=/base/java_runtime -Djava.class.path=/base/java_runtime/runtime-main.jar -Djava.library.path=/base/java_runtime: com/google/apphosting/runtime/JavaRuntimeMainWithDefaults --fixed_application_path=/workspace /base/java_runtime

אנחנו לא ממליצים לשנות את נקודת הכניסה הזו שמוגדרת כברירת מחדל, כי הגדרות הזיכרון מחושבות על סמך סוג המופע (F1,‏ F2,‏ F4) והזיכרון שזמין.

כברירת מחדל, אנחנו משתמשים ב---add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED כדי לפתוח כמה ממשקי JDK API שנדרשים.

תכונות של נקודות כניסה

אפשר להתאים אישית את נקודת הכניסה לגרסאות Java מהדור השני באמצעות משתני סביבה שהוגדרו על ידי המשתמש והתווספו לקובץ ההגדרות appengine-web.xml.

בטבלה הבאה מפורטים משתני הסביבה שאפשר להשתמש בהם כדי להפעיל, להשבית או להגדיר תכונות, וערכי ברירת המחדל אם הם לא מוגדרים:

משתנה סביבה תיאור סוג ברירת מחדל
CPROF_ENABLE Stackdriver Profiler בוליאני false
GAE_MEMORY_MB זיכרון זמין size הוגדר על ידי App Engine או /proc/meminfo-400M
HEAP_SIZE_RATIO זיכרון עבור הערימה אחוז 80
HEAP_SIZE_MB הערימה הזמינה size ‫${HEAP_SIZE_RATIO}% מתוך ${GAE_MEMORY_MB}
JAVA_HEAP_OPTS ארגומנטים של ערימה (heap) ב-JVM ארגומנטים של JVM -Xms${HEAP_SIZE_MB}M -Xmx${HEAP_SIZE_MB}M
JAVA_GC_OPTS ארגומנטים של JVM GC ארגומנטים של JVM -XX:+UseG1GC plus configuration
JAVA_USER_OPTS ארגומנטים אחרים של JVM ארגומנטים של JVM
JAVA_OPTS ארגומנטים של JVM ארגומנטים של JVM מידע נוסף מופיע בהמשך

אם לא מגדירים במפורש, ברירת המחדל של JAVA_OPTS היא:

   JAVA_OPTS:=-showversion \
              $JAVA_HEAP_OPTS \
              $JAVA_GC_OPTS \
              $JAVA_USER_OPTS

אם CPROF_ENABLE הוא true, נקודת הכניסה שמוגדרת כברירת מחדל מוסיפה את PROFILER_AGENT באופן הבא:

-agentpath:/opt/cprof/profiler_java_agent.so=--logtostderr

לדוגמה, אם קוד האפליקציה שלכם צריך עוד דגלים של -add-opens, אתם יכולים להשתמש במשתנה הסביבה JAVA_USER_OPTS שמוגדר בקובץ appengine-web.xml:

    <env-variables>
       <env-var name="JAVA_USER_OPTS" value="--add-opens java.base/java.util=ALL-UNNAMED" />
     </env-variables>

שיקולים לגבי מיגרציה

אם אתם עוברים ל-Java runtime מהדור השני והאפליקציה שלכם משתמשת בשירותים קודמים שצורפו לחבילה, כדאי שתכירו את הנקודות הבאות:

  • כדי לבדוק את היכולות של שירותים מקובצים מדור קודם באפליקציית Java מהדור השני, אפשר להשתמש בשרת פיתוח מקומי.
  • בשונה מסביבת זמן הריצה של Java 8, סביבות זמן הריצה של Java מהדור השני כוללות את JVM כחלק מזיכרון המופע. אם מופיעות שגיאות שקשורות לזיכרון ביומנים, כדאי להגדיל את גודל מחלקת המופעים בקובץ appengine-web.xml.
  • אם האפליקציה מנסה לקרוא ל-API שלא מופעל בסביבות זמן הריצה של Java מהדור השני, היא תקבל שגיאת com.google.apphosting.api.ApiProxy$FeatureNotEnabledException.
  • כל האפליקציות נחשבות בטוחות לשימוש עם שרשורים בסביבות זמן הריצה של Java מהדור השני. צריך להסיר את הרכיב threadsafe בקובץ app.yaml או appengine-web.xml כשמעבירים מ-Java 8 לזמן הריצה העדכני של Java.

דוגמה (Datastore)

דוגמה לשימוש ב-Firestore במצב Datastore (Datastore) מופיעה בדוגמת הקוד ב-GitHub של שירותים מאוגדים מדור קודם ל-Java 11.