[Destinations] Cross Level Destination Support (#890)

Author: MatKuhr

cloudplatform/connectivity-destination-service/src/main/java/com/sap/cloud/sdk/cloudplatform/connectivity/DestinationService.java

@@ -51,11 +51,10 @@
 @SuppressWarnings( "PMD.TooManyStaticImports" )
 public class DestinationService implements DestinationLoader
 {
-    private static final String PATH_DEFAULT = "/destinations/";
-
-    private static final String PATH_SERVICE_INSTANCE = "/instanceDestinations";
-
-    private static final String PATH_SUBACCOUNT = "/subaccountDestinations";
+    private static final String PATH_DEFAULT = "/v1/destinations/";
+    private static final String PATH_V2 = "/v2/destinations/";
+    private static final String PATH_SERVICE_INSTANCE = "/v1/instanceDestinations";
+    private static final String PATH_SUBACCOUNT = "/v1/subaccountDestinations";
 
     static final TimeLimiterConfiguration DEFAULT_TIME_LIMITER =
         TimeLimiterConfiguration.of().timeoutDuration(Duration.ofSeconds(6));
@@ -128,7 +127,13 @@ Destination loadAndParseDestination( final String destName, final DestinationOpt
         throws DestinationAccessException,
             DestinationNotFoundException
     {
-        final String servicePath = PATH_DEFAULT + destName;
+        final String servicePath =
+            DestinationServiceOptionsAugmenter
+                .getCrossLevelScope(options)
+                .map(DestinationServiceOptionsAugmenter.CrossLevelScope::getSuffix)
+                .map(s -> PATH_V2 + destName + s)
+                .getOrElse(PATH_DEFAULT + destName);
+
         final Function<DestinationRetrievalStrategy, DestinationServiceV1Response> destinationRetriever =
             strategy -> resilientCall(() -> retrieveDestination(strategy, servicePath), singleDestResilience);
 
@@ -199,9 +204,9 @@ public Collection<DestinationProperties> getAllDestinationProperties()
      * In case there exists a destination with the same name on service instance and on sub-account level, the
      * destination at service instance level takes precedence.
      *
-     * @return A list of destination properties.
      * @param retrievalStrategy
      *            Strategy for loading destinations in a multi-tenant application.
+     * @return A list of destination properties.
      * @since 5.12.0
      */
     @Nonnull
@@ -648,9 +653,8 @@ public static void disableExpiration()
          * <strong>Caution:</strong> Using this operation will lead to a re-creation of the destination cache. As a
          * consequence, all existing cache entries will be lost.
          *
-         * @deprecated since 5.2.0. Change detection mode is enabled by default
-         *
          * @since 4.7.0
+         * @deprecated since 5.2.0. Change detection mode is enabled by default
          */
         @Deprecated
         public static void enableChangeDetection()

cloudplatform/connectivity-destination-service/src/main/java/com/sap/cloud/sdk/cloudplatform/connectivity/DestinationServiceAdapter.java

@@ -37,7 +37,7 @@
 @Slf4j
 class DestinationServiceAdapter
 {
-    private static final String SERVICE_PATH = "destination-configuration/v1";
+    private static final String SERVICE_PATH = "destination-configuration";
 
     @Nonnull
     @Getter( AccessLevel.PACKAGE )

cloudplatform/connectivity-destination-service/src/main/java/com/sap/cloud/sdk/cloudplatform/connectivity/DestinationServiceOptionsAugmenter.java

@@ -5,8 +5,11 @@
 
 import javax.annotation.Nonnull;
 
+import com.google.common.annotations.Beta;
+
 import io.vavr.control.Option;
 import lombok.NoArgsConstructor;
+import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
 /**
@@ -20,6 +23,7 @@ public class DestinationServiceOptionsAugmenter implements DestinationOptionsAug
     static final String DESTINATION_TOKEN_EXCHANGE_STRATEGY_KEY = "scp.cf.destinationTokenExchangeStrategy";
     static final String X_REFRESH_TOKEN_KEY = "x-refresh-token";
     static final String X_FRAGMENT_KEY = "X-fragment-name";
+    static final String CROSS_LEVEL_SETTING = "crossLevelSetting";
 
     private final Map<String, Object> parameters = new HashMap<>();
 
@@ -105,6 +109,65 @@ public DestinationServiceOptionsAugmenter fragmentName( @Nonnull final String fr
         return this;
     }
 
+    /**
+     * Enable <a href=
+     * "https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/referring-resources-using-rest-api">cross-level
+     * consumption of destinations</a>. <strong>Note: This is an experimental feature and may not function for all
+     * destination types.</strong>
+     *
+     * @param scope
+     *            Set the scope where to look up the destination. This scope is only applied to the destination itself.
+     *            The scopes for fragments or destination chain references have to be set separately.
+     * @return The same augmenter that called this method.
+     * @since 5.22.0
+     */
+    @Beta
+    @Nonnull
+    public DestinationServiceOptionsAugmenter crossLevelConsumption( @Nonnull final CrossLevelScope scope )
+    {
+        parameters.put(CROSS_LEVEL_SETTING, scope);
+        return this;
+    }
+
+    /**
+     * Enable cross-level consumption of destinations.
+     *
+     * @since 5.22.0
+     */
+    @Beta
+    @RequiredArgsConstructor
+    public enum CrossLevelScope
+    {
+        /**
+         * Use the destination from the current subaccount.
+         */
+        SUBACCOUNT("subaccount"),
+        /**
+         * Use the destination from the provider subaccount. Behaves identical to {@link #SUBACCOUNT}, if the current
+         * tenant is the provider tenant, or the strategy {@link DestinationServiceRetrievalStrategy#ALWAYS_PROVIDER} is
+         * used.
+         */
+        PROVIDER_SUBACCOUNT("provider_subaccount"),
+        /**
+         * Use the destination from the destination service instance for the current tenant.
+         */
+        INSTANCE("instance"),
+        /**
+         * Use the destination from the destination service instance for the provider tenant. Behaves identical to
+         * {@link #INSTANCE}, if the current tenant is the provider tenant, or the strategy
+         * {@link DestinationServiceRetrievalStrategy#ALWAYS_PROVIDER} is used.
+         */
+        PROVIDER_INSTANCE("provider_instance");
+
+        private final String identifier;
+
+        @Nonnull
+        String getSuffix()
+        {
+            return "@" + identifier;
+        }
+    }
+
     @Override
     public void augmentBuilder( @Nonnull final DestinationOptions.Builder builder )
     {
@@ -127,9 +190,9 @@ public static Option<DestinationServiceRetrievalStrategy> getRetrievalStrategy(
     {
         final Option<Object> strategy = options.get(DESTINATION_RETRIEVAL_STRATEGY_KEY);
 
-        if( strategy.isDefined() && strategy.get() instanceof String ) {
+        if( strategy.isDefined() && strategy.get() instanceof String str ) {
             return Option
-                .of(DestinationServiceRetrievalStrategy.ofIdentifier((String) strategy.get()))
+                .of(DestinationServiceRetrievalStrategy.ofIdentifier(str))
                 .onEmpty(() -> log.warn("Unsupported destination retrieval strategy: {}", strategy.get()));
         }
 
@@ -150,9 +213,9 @@ public static Option<DestinationServiceTokenExchangeStrategy> getTokenExchangeSt
     {
         final Option<Object> strategy = options.get(DESTINATION_TOKEN_EXCHANGE_STRATEGY_KEY);
 
-        if( strategy.isDefined() && strategy.get() instanceof String ) {
+        if( strategy.isDefined() && strategy.get() instanceof String str ) {
             return Option
-                .of(DestinationServiceTokenExchangeStrategy.ofIdentifier((String) strategy.get()))
+                .of(DestinationServiceTokenExchangeStrategy.ofIdentifier(str))
                 .onEmpty(() -> log.warn("Unsupported token exchange strategy: {}", strategy.get()));
         }
 
@@ -170,4 +233,13 @@ static Option<String> getFragmentName( @Nonnull final DestinationOptions options
     {
         return options.get(X_FRAGMENT_KEY).filter(String.class::isInstance).map(String.class::cast);
     }
+
+    @Nonnull
+    static Option<CrossLevelScope> getCrossLevelScope( @Nonnull final DestinationOptions options )
+    {
+        return options
+            .get(CROSS_LEVEL_SETTING)
+            .filter(CrossLevelScope.class::isInstance)
+            .map(CrossLevelScope.class::cast);
+    }
 }

cloudplatform/connectivity-destination-service/src/test/java/com/sap/cloud/sdk/cloudplatform/connectivity/DestinationServiceAdapterTest.java

@@ -79,7 +79,7 @@ class DestinationServiceAdapterTest
     private static final String PROVIDER_TENANT_ID = "provider-tenant-id";
 
     private static final String XSUAA_URL = "/xsuaa/oauth/token";
-    private static final String DESTINATION_SERVICE_URL = "/destination-service/destination-configuration/v1/";
+    private static final String DESTINATION_SERVICE_URL = "/destination-service/destination-configuration/";
     private static final String DESTINATION_RESPONSE = "{ response }";
 
     private static final String GRANT_TYPE_JWT_BEARER = "urn:ietf:params:oauth:grant-type:jwt-bearer";

cloudplatform/connectivity-destination-service/src/test/java/com/sap/cloud/sdk/cloudplatform/connectivity/DestinationServiceAuthenticationTest.java

@@ -40,7 +40,7 @@ class DestinationServiceAuthenticationTest
     private static final String BASIC_AUTH = "Zm9vOmJhcg==";
     private static final String DESTINATION_NAME = "CXT-HTTP-OAUTH";
 
-    private static final String SERVICE_PATH_DESTINATION = "/destinations/" + DESTINATION_NAME;
+    private static final String SERVICE_PATH_DESTINATION = "/v1/destinations/" + DESTINATION_NAME;
 
     @SuppressWarnings( "deprecation" )
     private static final DestinationOptions DESTINATION_RETRIEVAL_LOOKUP_EXCHANGE =