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

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

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

אפשר לעיין ברשימת ממשקי API של שירותים מהדור הקודם שאפשר להפעיל בגרסה הנתמכת האחרונה של Java.
כדי להציג את הדף הזה, האפליקציה צריכה לפעול בגרסת Java נתמכת. כדי להעביר את האפליקציה מסביבת ההרצה מהדור הראשון לסביבת ההרצה מהדור השני, אפשר לעיין במאמר העברה מ-Java 8 לסביבת ההרצה העדכנית של Java ובקטע שיקולים להעברה.
אם אתם משתמשים בחבילת שירותים מדור קודם ורוצים לשדרג ל-Java 25, תוכלו לקרוא את המאמר שדרוג של אפליקציה קיימת כדי לקבל מידע נוסף על אפשרויות ההגדרה.

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

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

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

מוסיפים את ההגדרות הבאות לקובץ appengine-web.xml בהתאם לגרסת Java:

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-apis>true</app-engine-apis>
  </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-apis>true</app-engine-apis>
  </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-apis>true</app-engine-apis>
  </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-apis> ולהגדיר אותו לערך true:

  <app-engine-apis>true</app-engine-apis>

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

נקודת כניסה (entrypoint) שמוגדרת כברירת מחדל ל-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 כדי לפתוח חלק מממשקי ה-API של JDK שנדרשים.

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

אפשר להתאים אישית את נקודת הכניסה לגרסאות 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 מהדור השני והאפליקציה שלכם משתמשת בשירותים קודמים בחבילה, כדאי שתכירו את הנקודות הבאות:

כדי לבדוק את היכולות של שירותים מקובצים מדור קודם באפליקציית 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.

גישה לחבילות שירותים מדור קודם ל-Java 11 ומעלה קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.