Changes in Edge for Private Cloud 4.54.00

Overview of changes

Edge for Private Cloud 4.54.00 introduces multiple changes that enhance the security posture of the platform and updates platform components to run with Java 21. Two of the sections below cover these changes:

• Java Callout policy changes
• TLS and cipher suite changes

In addition to these changes, review the dedicated Change detection tool guide. This utility has been made available to identify changes to proxies, shared flows, or other artifacts in your cluster that may cause disruption as a result of this upgrade.

Java Callout policy changes

In Edge for Private Cloud 4.54.00, core platform components—including the Message Processor, Management Server, and Router—are updated to run on Java 21 LTS. Java 21 modernizes the Java Platform, which includes removing legacy Java EE and CORBA modules (JEP 320), removing legacy internal utility classes, and enforcing strong modular encapsulation (JEP 403).

Because of these changes, API proxies with custom JavaCallout policies or custom resource JARs (stored at the proxy, environment, or organization level) may experience disruption upon upgrading to version 4.54.00.

Categories of changes that may impact Java Callouts

1. Permanently removed Java EE and CORBA modules (JEP 320): Modules previously built into the Java 8 runtime (including JAXB javax.xml.bind.*, JAF javax.activation.*, JAX-WS javax.xml.ws.*, and CORBA org.omg.*) were removed from Java SE. Callouts referencing these packages without bundling standalone replacements fail at runtime with NoClassDefFoundError.
2. Removed internal utility classes: Legacy internal helpers such as sun.misc.BASE64Encoder and sun.misc.BASE64Decoder were removed. Callouts calling these classes fail with NoClassDefFoundError.
3. Strong encapsulation of Java internals (JEP 403): Internal packages in java.base (such as sun.security.*, sun.reflect.*, and com.sun.*) cannot be accessed reflectively from custom callouts. Reflective calls fail at runtime with InaccessibleObjectException.
4. Method signature alterations and removals in surviving Java classes: In certain Java modules, the class remains present in Java 21, but specific constructors or method signatures have been removed, deprecated, or altered (such as specific DOM parsing methods in org.w3c.dom.Document and related XML parsing classes).

   Tool detection: The change detection tool flags references to these classes under the METHOD_SIGNATURE_MODIFICATION category with MEDIUM Impact Certainty, prompting developers to inspect the source code of their callouts for modified method invocations.

Remediation strategies

Before upgrading, ensure that your Java Callout policies and custom JAR resources are compatible with the Java 21 runtime. Using the change detection tool will help you identify affected API proxies, shared flows, and environment or organization JAR resources across your cluster.

The remediation strategies described in this section are general guides and are not mutually exclusive. Depending on your operational requirements, you can combine strategies—for example, modernizing callout source code using Strategy 2 and deploying the updated proxy revisions using Strategy 3B to achieve zero downtime during Message Processor upgrades.

Strategies 3A, 3B and 3C are three ways of carrying out the same operational approach: upgrading the node and redeploying the proxy at different times, without changing the proxy bundle. Choose one or a combination of these based on your API availability requirements.

Review the following decision guide to select the most appropriate approach for your deployment:

Decision guide for Java Callout mitigations:

Strategy 1: Dual-compatible proxy through bundled JARs (Test before upgrade for zero downtime)

When to use: Use this strategy when:

• A dual-compatible standalone replacement library is available: A replacement JAR exists that implements the required functionality and can be bundled directly into your API proxy without requiring source code modifications.
• You want your existing API proxies and Java Callouts to work seamlessly on both your current version (for example, Edge for Private Cloud 4.53.01) and the upgraded version (Edge for Private Cloud 4.54.00).
• You want to test and verify all changes in your staging and production environments before upgrading your Edge for Private Cloud cluster, ensuring zero unexpected issues and zero downtime in live traffic.
• You want to avoid rewriting or refactoring your Java Callout business logic.

How it works: In Java 8, certain libraries (such as JAXB javax.xml.bind.* or Activation javax.activation.*) were built directly into the Java 8 runtime. Because of this, developers did not need to include extra JAR files inside their proxy bundles. In Java 21, these libraries were removed from the Java runtime.

To make your proxy "dual-compatible" across Edge for Private Cloud 4.53.x and 4.54.00:

1. Identify the missing library required by your callout (for example, JAXB or Activation).
2. Acquire the standalone open-source replacement JAR (for example, jakarta.xml.bind-api-2.3.3.jar and jaxb-runtime-2.3.8.jar).
3. Either place the replacement JAR directly into the proxy bundle under apiproxy/resources/java/, or upload it to the proxy revision using the proxy-level Resource Files API, or upload it as a resource file at the environment level or organization level. For more information on managing resource files, see the Apigee Resource files documentation.
4. Deploy and test before the upgrade: Message Processors in both Edge for Private Cloud 4.53.x and 4.54.00 load classes from these bundled JARs. You can deploy this updated proxy bundle and test it with synthetic traffic in your current Edge for Private Cloud 4.53.x cluster now.
5. Enable external allowed package loading on Message Processors (Required for 4.54.00): By default in Edge for Private Cloud 4.54.00, loading removed Java packages (such as javax.xml.bind.* and javax.activation.*) from external or bundled resource JARs is disabled (conf_system_java.21.enable.external.allowed.packages=false), so bundling the JARs alone will not work by default. You must enable this property in /opt/apigee/customer/application/message-processor.properties using code with config (CwC) (you can configure this property prior to upgrading the Message Processor node, or set it after upgrading and restart the Message Processor):

   conf_system_java.21.enable.external.allowed.packages=true

6. Zero live traffic issues post-upgrade: When your cluster is subsequently upgraded to Edge for Private Cloud 4.54.00 with conf_system_java.21.enable.external.allowed.packages=true enabled, the Message Processor already has the required JAR available and loads the classes from the bundled resource file without any failure (NoClassDefFoundError), ensuring a smooth, zero-downtime upgrade.

Code example: Order XML validation and parsing callout

Consider a typical Apigee Java Callout that extracts and validates incoming XML orders using JAXB (JAXBContext and Unmarshaller).

• Before the fix (Fails in Edge for Private Cloud 4.54.00): In Edge for Private Cloud 4.53.x, the proxy bundle contains only the callout JAR, relying on built-in Java 8 runtime libraries for JAXB:

  apiproxy/
    resources/
      java/
        OrderXmlParserCallout.jar   <-- No JAXB JAR bundled

  The Java Callout implementation:

  package com.example.callout;
  
  // other required imports
  import java.io.StringReader;
  import javax.xml.bind.JAXBContext;
  import javax.xml.bind.Unmarshaller;
  
  public class OrderXmlParserCallout implements Execution {
      @Override
      public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
          try {
              String requestXml = messageContext.getMessage().getContent();
              JAXBContext jaxbContext = JAXBContext.newInstance(Order.class);
              Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
              Order order = (Order) unmarshaller.unmarshal(new StringReader(requestXml));
              messageContext.setVariable("order_id", order.getId());
              return ExecutionResult.SUCCESS;
          } catch (Exception e) { }
      }
  }

  The failure: In Edge for Private Cloud 4.53.x, this executes without issue. Once the node is upgraded to Edge for Private Cloud 4.54.00, this proxy immediately fails during request processing:

  java.lang.NoClassDefFoundError: javax/xml/bind/JAXBContext
          at com.example.callout.OrderXmlParserCallout.execute(OrderXmlParserCallout.java:20)

• After the fix (Dual-compatible across Edge for Private Cloud 4.53.x and 4.54.00): You do not need to rewrite or recompile your Java Callout code. You can directly make your proxy dual-compatible by providing the standalone JARs:
  1. Directly bundle or upload the standalone JARs: Obtain the standalone JAXB libraries (jakarta.xml.bind-api-2.3.3.jar and jaxb-runtime-2.3.8.jar) and place them inside your proxy bundle under apiproxy/resources/java/:

     apiproxy/
       resources/
         java/
           OrderXmlParserCallout.jar
           jakarta.xml.bind-api-2.3.3.jar
           jaxb-runtime-2.3.8.jar

     Alternatively, upload jakarta.xml.bind-api-2.3.3.jar and jaxb-runtime-2.3.8.jar as resource files using the proxy-level Resource Files API, or at the environment level or organization level so all proxies at the same scope can share them without bundling them into each individual proxy bundle.

     If you build your proxy bundle from source using Maven, declare these dependencies in your pom.xml so they are packaged automatically during your build.

  2. Deploy and test on your current 4.53.x cluster: Deploy the updated proxy bundle to your existing Edge for Private Cloud 4.53.x environment and send test calls. Because Edge for Private Cloud 4.53.x Message Processors load classes from these bundled JARs, you can verify that the callout continues to function identically.
  3. Enable external allowed package loading via CwC: Because loading external allowed packages is disabled by default in Edge for Private Cloud 4.54.00 (conf_system_java.21.enable.external.allowed.packages=false), enable it on each Message Processor node in /opt/apigee/customer/application/message-processor.properties using code with config (CwC):

     conf_system_java.21.enable.external.allowed.packages=true

  4. Zero live traffic issues post-upgrade: Once validated in your 4.53.x environment and configured with the CwC property, your proxy is fully prepared. When you upgrade your cluster to Edge for Private Cloud 4.54.00, the Message Processor loads the bundled JAXB classes, ensuring zero errors and zero live traffic disruption.

Strategy 2: Alternative implementation (Code and dependency modernization)

When to use: Recommended for active codebases where proxy source code is readily maintained. This is the cleanest long-term approach for Java 21 compliance. Rollout note: Because deploying modernized proxy revisions requires Message Processor coordination, pair this strategy with Strategy 3A (during a planned maintenance window) or Strategy 3B (to achieve zero downtime with parallel Message Processors).

How it works: Replace removed Java internal classes with official standard Java SE APIs or open-source standalone equivalents, and package required third-party dependencies directly within your proxy bundle resource files or POM.

Code examples:

Example 1: Method and code modernization (Replacing removed internal utilities)

In Java 8, callouts frequently used internal utility classes such as sun.misc.BASE64Encoder. In modern Java, these classes were removed, but the standard java.util.Base64 API provides direct replacements without requiring external dependency JARs:

• Before (Legacy Java 8 implementation):

  // Incompatible in Edge for Private Cloud 4.54.00: sun.misc package removed
  import sun.misc.BASE64Encoder;
  // other required imports
  
  public class Base64EncodeCallout implements Execution {
      @Override
      public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
          BASE64Encoder encoder = new BASE64Encoder();
          String encoded = encoder.encode("ApigeePayload".getBytes());
          messageContext.setVariable("encoded_data", encoded);
          return ExecutionResult.SUCCESS;
      }
  }

• After (Java 21-compliant implementation):

  // Fully compatible with Java 21: uses standard Java SE java.util.Base64 (no external JARs needed)
  import java.util.Base64;
  // other required imports
  
  public class Base64EncodeCallout implements Execution {
      @Override
      public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
          String encoded = Base64.getEncoder().encodeToString("ApigeePayload".getBytes());
          messageContext.setVariable("encoded_data", encoded);
          return ExecutionResult.SUCCESS;
      }
  }

Example 2: Import-level refactoring with bundled library (JAXB Namespace Prefix Mapper)

In Java 8, API proxies customizing XML namespace prefixes commonly extended Sun's internal JAXB mapper com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper. In Java 21, internal Sun packages are removed and inaccessible.

The standalone open-source library (org.glassfish.jaxb:jaxb-runtime) provides the identical class under com.sun.xml.bind.marshaller.NamespacePrefixMapper. All method signatures, parameters, and return types are identical—the code change is strictly at the import statement:

• Before (Legacy Java 8 implementation):

  // In Java 8: Relied on internal Sun class in Java 8 runtime
  import com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper;
  public class CustomNamespaceMapper extends NamespacePrefixMapper {
      @Override
      public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) {
          if ("http://schemas.example.com/orders".equals(namespaceUri)) {
              return "ord";
          }
          return suggestion;
      }
  }

• After (Java 21-compliant implementation):

  // In Java 21: Identical methods and logic; ONLY the import statement changes (".internal." removed)
  import com.sun.xml.bind.marshaller.NamespacePrefixMapper;
  public class CustomNamespaceMapper extends NamespacePrefixMapper {
      @Override
      public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) {
          if ("http://schemas.example.com/orders".equals(namespaceUri)) {
              return "ord";
          }
          return suggestion;
      }
  }

• Bundled dependency configuration (pom.xml): To supply this class at runtime, bundle the standalone JAXB libraries inside apiproxy/resources/java/ or declare them in your pom.xml:

  <dependencies>
      <!-- Standalone JAXB API for Java 21 -->
      <dependency>
          <groupId>jakarta.xml.bind</groupId>
          <artifactId>jakarta.xml.bind-api</artifactId>
          <version>2.3.3</version>
      </dependency>
      <!-- Standalone JAXB Runtime providing com.sun.xml.bind.marshaller.NamespacePrefixMapper -->
      <dependency>
          <groupId>org.glassfish.jaxb</groupId>
          <artifactId>jaxb-runtime</artifactId>
          <version>2.3.8</version>
      </dependency>
  </dependencies>

Strategy 3A: Planned maintenance downtime (In-place redeployment)

When to use: Recommended for environments with scheduled operational maintenance windows where a brief service interruption is acceptable.

Procedure:

1. Coordinate a scheduled maintenance window with API consumers.
2. Upgrade your Edge for Private Cloud components to version 4.54.00 following the Upgrade paths guide.
3. Deploy the pre-compiled, 4.54.00-compatible revision of your API proxy using the New Edge UI or the Apigee Management API (Deployments).
4. Verify callout execution by sending synthetic test requests to the Message Processors and inspecting logs using the Trace tool.
5. Close the maintenance window and reopen public traffic.

Strategy 3B: Create new environment (Zero-downtime migration)

When to use: Recommended for mission-critical production environments requiring zero downtime. Use this when your Java Callout cannot be updated to work across Java 8 and Java 21 simultaneously.

How it works: This strategy involves procuring one or more new environments so that you can wire Message Processor nodes of different versions to it. Subsequently deploy Java 8-compatible proxies to the environment wired with 4.53.X Message Processors and Java 21-compatible proxies to the environment wired with 4.54.00 Message Processors. Then use a load balancer or other routing techniques to route traffic to the Java 21-compatible proxy only.

For this strategy, understanding how organizations, environments, and Message Processors interact is key to a zero-downtime cutover (for more information, see Apigee Edge organization structure):

• An Apigee Organization is a top-level administrative boundary containing multiple environments (for example, prod, test).
• An API proxy revision is deployed to a specific environment. Only the Message Processors explicitly bound to that environment load and execute the proxy revision.

+------------------------------------------------------------------------+
|                          Apigee Organization                           |
|                                                                        |
|  Existing Environment (prod)            Temporary Env (prod-migration) |
|  +--------------------------------+     +----------------------------+ |
|  | Current 4.53.01 MP Nodes       |     | New 4.54.00 MP Nodes       | |
|  |               |                |     |              |             | |
|  | Proxy Rev N (4.53.01)          |     | Proxy Rev N+1 (Modernized) | |
|  +--------------------------------+     +----------------------------+ |
+------------------------------------------------------------------------+
                   ^                                    ^
                   | Step 1: Normal Live                | Step 2: Canary
                   |         Traffic (prod)             | Step 3: Complete
          +------------------------------------------------------+
          |       Upstream Load Balancer / Ingress Router        |
          +------------------------------------------------------+

Procedure:

1. Create a temporary environment: Create a new environment (for example, prod-migration) within your organization (following Setting up virtual hosts and environments) with a dedicated virtual host and port.
2. Provision 4.54.00 Message Processor nodes: Install Edge for Private Cloud 4.54.00 on new or temporary VM instances and bind these nodes to prod-migration (see Adding a Message Processor).
3. Identify affected proxies and create updated revisions: Identify API proxies using Java Callouts (using the change detection tool) and create a new revision of each affected proxy with Edge for Private Cloud 4.54.00-compatible Java Callouts (applying Strategy 1 or Strategy 2).
4. Deploy modernized proxy revisions to the temporary environment: Deploy the updated, compatible proxy revisions exclusively to prod-migration.
5. Verify and shift traffic: Execute synthetic verification tests against the new virtual host. Once verified, configure your external load balancer (F5, NGINX) to redirect client traffic from prod to prod-migration.
6. Upgrade original nodes and switch back: Undeploy the legacy proxies from prod. Upgrade the original Message Processor nodes to 4.54.00 following the Upgrade paths guide. Deploy the modernized proxy revisions to prod, redirect load balancer traffic back to prod, and verify operation.
7. Decommission temporary environment: Undeploy proxies from prod-migration, remove the temporary Message Processor nodes, and delete the temporary environment.

Strategy 3C: Node-level external-lib placement (Shared fallback libraries)

When to use: Recommended when you have multiple API proxies relying on Java classes that were removed in Java 21, and recompiling or re-packaging each individual proxy bundle before the upgrade is operationally unfeasible.

How it works: In Edge for Private Cloud 4.54.00, Message Processors provide a mechanism to load missing Java classes from a dedicated node directory: $APIGEE_ROOT/data/edge-message-processor/external-lib.

When this mechanism is enabled, the Message Processor checks this directory for missing classes before falling back to default resolution. You can provide the missing classes by sourcing them from third-party library JARs or by bundling the required classes into a JAR and placing it in external-lib.

Procedure:

1. Create the external library directory on each Message Processor node:

   mkdir -p /opt/apigee/data/edge-message-processor/external-lib

2. Place the required JARs in the directory: Copy the JAR files containing the required classes into /opt/apigee/data/edge-message-processor/external-lib.
3. Set appropriate file permissions: Ensure the apigee service user has read permissions:

   chown -R apigee:apigee /opt/apigee/data/edge-message-processor/external-lib
   chmod 755 /opt/apigee/data/edge-message-processor/external-lib
   chmod 644 /opt/apigee/data/edge-message-processor/external-lib/*.jar

4. Enable external package loading in Message Processor configuration: By default in Edge for Private Cloud 4.54.00, loading external allowed packages is disabled (conf_system_java.21.enable.external.allowed.packages=false). To enable the Message Processor to resolve and load classes from /opt/apigee/data/edge-message-processor/external-lib, you must enable this property in /opt/apigee/customer/application/message-processor.properties using code with config (CwC):

   conf_system_java.21.enable.external.allowed.packages=true

5. Restart the Message Processor:

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Strategy 4: JVM flags (--add-opens / --add-exports — caution and last resort)

When to use: Use this strategy as a last resort for closed-source third-party vendor libraries where source code is unavailable, vendors have not released Java 21 updates, and the JAR strictly depends on reflective access to internal Java packages.

Procedure:

1. Identify the inaccessible package used for reflection: Determine the internal Java module and package accessed reflectively by your third-party library. Note: These reflection errors occur strictly under Java 21 in Edge for Private Cloud 4.54.00 and will not appear in version 4.53.x logs. Check the Message Processor logs (/opt/apigee/var/log/edge-message-processor/system.log) post-upgrade for the InaccessibleObjectException identifying the required module and package:

   java.lang.reflect.InaccessibleObjectException: Unable to make field private final byte[] java.lang.String.value accessible: module java.base does not "opens java.lang" to unnamed module

2. Edit /opt/apigee/customer/application/message-processor.properties using code with config (CwC) (create the file if it does not exist).
3. Append the targeted --add-opens or --add-exports flags to bin_setenv_ext_jvm_opts.

   # Configure targeted JVM module access for closed-source legacy callouts (enclosed in double quotes)
   bin_setenv_ext_jvm_opts="-XX:+UseG1GC -XX:+AlwaysPreTouch --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/sun.misc=ALL-UNNAMED --add-opens java.base/sun.security.util=ALL-UNNAMED --add-opens java.base/sun.security.x509=ALL-UNNAMED"

4. Ensure proper file ownership and permissions:

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
   chmod 644 /opt/apigee/customer/application/message-processor.properties

5. Restart the Message Processor using apigee-service:

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

TLS and cipher suite changes

In Edge for Private Cloud 4.54.00, core platform components—including the Message Processor, Management Server, and Router—are updated to run on Java 21 LTS. This update modernizes cryptographic security by enabling TLS 1.3 by default (JEP 332). Message Processors now negotiate TLS 1.3 as the preferred protocol for outbound backend connections, falling back to TLS 1.2 where the backend does not support it.

Legacy backend requirements and remediation

The Java 21 cryptographic baseline updates the list of protocols and cipher suites disabled by default in jdk.tls.disabledAlgorithms (such as legacy TLS protocols and non-forward-secret static RSA key-exchange suites: TLS_RSA_*). Because you supply your own Java 21 runtime, the exact list of disabled protocols and cipher suites depends on your specific Java 21 implementation.

If your existing API proxies connect to legacy backend infrastructure that requires disabled protocols or static RSA ciphers, review the following actions:

• Modernize backend security (Recommended): Upgrade target servers and load balancers to support TLS 1.2 or TLS 1.3 with modern ECDHE cipher suites. To configure protocols and cipher suites in your API proxies, see Configuring TLS from Edge to the backend and the TLS/SSL TargetEndpoint configuration reference (or Load balancing across backend servers if using TargetServers).
• Re-enable legacy algorithms using CwC (transitional measure during upgrade): If backend upgrades cannot be completed before the platform upgrade, you can temporarily re-enable required algorithms using code with config (CwC):
  1. Check the default jdk.tls.disabledAlgorithms value in your Java 21 installation (for example, in $JAVA_HOME/conf/security/java.security).
  2. Override conf_jvmsecurity_jdk.tls.disabledAlgorithms in /opt/apigee/customer/application/message-processor.properties with that same list of disabled algorithms, removing only the TLS_RSA_* entry (keep all other disabled algorithms intact so remaining protections stay enabled).
  3. Restart the Message Processor using apigee-service. Remove this override once the backend supports ECDHE cipher suites.
• Update a custom cipher suite allowlist: If you have previously overridden conf_http_HTTPTransport.ssl.cipher.suites.whitelist, review it before upgrading. Java 21 no longer supports the static RSA suites (TLS_RSA_*), so an allowlist that contains only those suites leaves the Message Processor with no usable cipher and backend calls fail with no cipher suites in common. Remove the TLS_RSA_* entries and configure modern cipher suites supported by your Java 21 implementation. If you have not overridden this property, the 4.54.00 defaults already carry the supported suites and no change is needed.
• Update internal Router to Message Processor ciphers: If you have previously overridden conf_message-processor-communication_local.http.ssl.ciphers with static RSA suites, update it with modern cipher suites supported by your Java 21 implementation before upgrading, or the Router cannot complete a TLS handshake with the Message Processor. Then restart the Message Processor:

  apigee-service edge-message-processor restart

  See Configuring TLS between a Router and a Message Processor.

For details on configuring TLS between Edge components, see Configuring TLS between a Router and a Message Processor.

Change detection tool

Apigee provides a change detection tool to scan your cluster for deployed API proxies, policies, shared flows, and resource JARs that may be affected by the upgrade to Edge for Private Cloud 4.54.00.

The tool identifies potential upgrade blockers—including Java 21 incompatible libraries, strongly encapsulated internal APIs, legacy policy deprecations, and OpenLDAP RDN limits—and produces actionable reports to help you select appropriate remediation strategies.

For complete prerequisites, download instructions, command-line syntax, and sample reports, see the dedicated Change detection tool guide.