Separate approaches

Author: VladislavAtanasov95

docs-java/environments/kyma.mdx

@@ -659,7 +659,20 @@ Apply the YAML with `kubectl apply -n` into the namespace of your application po
 
 ### Executing Requests
 
-In your application you can now configure a destination to execute requests:
+The SAP Cloud SDK offers two distinct approaches for executing requests through the Transparent Proxy in Kyma. Choose the approach that best fits your application's architecture and requirements.
+
+## Approach 1: TransparentProxyDestination Builder (Recommended)
+
+The **TransparentProxyDestination Builder** approach provides explicit, fine-grained control over individual destination configurations. This is the recommended approach for most use cases as it offers maximum flexibility and clear configuration management.
+
+### When to Use This Approach
+
+- You need specific control over individual destination configurations
+- You want to set custom headers or properties per destination
+- You prefer explicit destination management
+- You need different configurations for different destinations
+
+### Implementation Examples
 
 <Tabs 
   groupId="dynamic-dest"
@@ -670,6 +683,10 @@ In your application you can now configure a destination to execute requests:
   ]}>
 <TabItem value="single">
 
+**For Concrete SAP Destinations:**
+
+Use this when connecting to a specific, pre-configured destination with a dedicated Destination Custom Resource.
+
 ```java
 TransparentProxyDestination destination = TransparentProxyDestination
     .destination(<destination-custom-resource-name>.<destination-custom-resource-namespace>)
@@ -684,6 +701,10 @@ List<SalesArea> execute = new DefaultSalesAreaService().getAllSalesArea() // exa
 </TabItem>
 <TabItem value="gateway">
 
+**For Dynamic Destination Gateway:**
+
+Use this when you need to connect to arbitrary destinations dynamically using a Gateway Destination Custom Resource.
+
 ```java
 TransparentProxyDestination destination = TransparentProxyDestination
     .gateway("my-destination", <destination-custom-resource-name>.<destination-custom-resource-namespace>)
@@ -701,11 +722,53 @@ List<SalesArea> execute = new DefaultSalesAreaService().getAllSalesArea() // exa
 `<destination-custom-resource-namespace>` can be omitted if the destination custom resource is created in the same namespace as the application workload.
 :::
 
-The code above shows an example how you can then use the `destination` object to perform an OData request against the system.
+## Approach 2: Transparent Proxy Loader
+
+The **Transparent Proxy Loader** approach provides centralized proxy configuration where **all destination requests** are automatically routed through a single registered gateway without requiring explicit destination builders.
+
+### When to Use This Approach
+
+- You want all destinations to automatically route through a single transparent proxy gateway
+- You prefer a centralized, "set-it-and-forget-it" configuration approach
+- You have many destinations that should all use the same proxy configuration
+- You want to minimize code changes when migrating from traditional destination access
+
+### Implementation Examples
+
+**Step 1: Register the Transparent Proxy (typically during application startup):**
+
+```java
+// Register with default port 80
+TransparentProxy.register("<destination-gateway-host>");
+
+// OR register with custom port
+TransparentProxy.register("http://<destination-gateway-host>", 8080);
+```
+
+**Step 2: Use destinations normally - they will automatically route through the registered proxy:**
+
+```java
+// All subsequent destination requests will be routed through the registered gateway
+// No explicit TransparentProxyDestination creation needed
+Destination destination = DestinationAccessor.getDestination("my-destination");
+
+List<SalesArea> execute = new DefaultSalesAreaService().getAllSalesArea() // example OData request
+        .execute(destination);
+```
+
+## Choosing Between the Two Approaches
+
+| Aspect                       | TransparentProxyDestination Builder          | Transparent Proxy Loader                 |
+| ---------------------------- | -------------------------------------------- | ---------------------------------------- |
+| **Control Level**            | Fine-grained, per-destination control        | Centralized, all-destinations control    |
+| **Configuration Complexity** | Higher - explicit per destination            | Lower - one-time registration            |
+| **Flexibility**              | High - different configs per destination     | Lower - same config for all destinations |
+| **Migration Effort**         | Medium - explicit destination changes needed | Low - minimal code changes               |
+| **Use Case**                 | Varied destination requirements              | Uniform destination handling             |
+| **Recommended For**          | Most applications, complex scenarios         | Simple proxy setups, migration scenarios |
 
 :::tip Connecting to Cloud systems
-The above approach is not limited to destinations of proxy type `ON_PREMISE`.
-`INTERNET` destinations are equally supported.
+Both approaches support destinations of any proxy type including `ON_PREMISE` and `INTERNET` destinations.
 :::
 
 ### Troubleshooting

docs-java/features/connectivity/008-transparent-proxy.mdx

@@ -53,11 +53,14 @@ It uses this destination to forward the request to the target system or to the C
 Consequently, your app does not interact with SAP Destination service or Connectivity service.
 This means your application do not require bindings to these two services, everything is handled by the Transparent Proxy.
 
-## Creating Transparent Proxy Destinations
+## Approach 1: TransparentProxyDestination Builder
 
-The `TransparentProxyDestination` class provides two types of builders for different use cases:
+The `TransparentProxyDestination` class provides explicit destination builders for direct control over transparent proxy connections.
+This approach gives you fine-grained control over individual destination configurations and is recommended for most use cases.
 
-### 1. Destination
+### Creating Destinations
+
+#### Concrete SAP Destination
 
 Allows you to connect to a concrete SAP destination.
 Setting generic headers is allowed but dynamic properties like destination name or fragments is not.
@@ -76,7 +79,7 @@ TransparentProxyDestination destination = TransparentProxyDestination
 `<destination-custom-resource-namespace>` can be omitted if the destination custom resource is created in the same namespace as the application workload.
 :::
 
-### 2. Gateway
+#### Dynamic Destination Gateway
 
 Allows you to connect to arbitrary SAP destinations you have access to.
 As a prerequisite, you have to create a Gateway Destination Custom Resource inside the Kubernetes cluster.
@@ -89,25 +92,26 @@ TransparentProxyDestination destination = TransparentProxyDestination
     .build();
 ```
 
-## Tenant Configuration
+### Configuration Options
+
+#### Tenant Configuration
 
 The SAP Cloud SDK automatically sets the current tenant as tenant ID on a **per-request** basis.
 
 In case a fixed tenant should be used, you can manually set it as follows:
 
-### Destination
+**For Concrete Destinations:**
 
+```java
 // Using a fixed tenant ID (automatically set by SAP Cloud SDK if not specified)
 // alternatively, .tenantSubdomain("..") can be used, but only one of the two options may be set
-
-```java
 TransparentProxyDestination destination = TransparentProxyDestination
     .destination(<destination-custom-resource-name>.<destination-custom-resource-namespace>)
     .tenantId("my-tenant-id")
     .build();
 ```
 
-### Gateway
+**For Gateway Destinations:**
 
 ```java
 // Using a fixed tenant ID (automatically set by SAP Cloud SDK if not specified)
@@ -118,13 +122,13 @@ TransparentProxyDestination destination = TransparentProxyDestination
     .build();
 ```
 
-## Authorization Header Configuration
+#### Authorization Header Configuration
 
 The SAP Cloud SDK automatically sets the current user's authorization token in the `Authorization` header on a **per-request** basis.
 
 In case a fixed authorization token should be used, you can manually set it as follows:
 
-### Destination
+**For Concrete Destinations:**
 
 ```java
 TransparentProxyDestination destination = TransparentProxyDestination
@@ -133,7 +137,7 @@ TransparentProxyDestination destination = TransparentProxyDestination
     .build();
 ```
 
-### Gateway
+**For Gateway Destinations:**
 
 ```java
 TransparentProxyDestination destination = TransparentProxyDestination
@@ -144,18 +148,18 @@ TransparentProxyDestination destination = TransparentProxyDestination
 
 **Note**: When you manually set authorization, it will override the SAP Cloud SDK automatic token handling.
 
-## Migration from Traditional Destinations
+### Migration from Traditional Destinations
 
 Migrating from traditional destination configurations:
 
-### Before (Traditional Destination)
+#### Before (Traditional Destination)
 
 ```java
 Destination destination = DestinationAccessor.getDestination("my-destination");
 HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);
 ```
 
-### After (Transparent Proxy - Gateway)
+#### After (Transparent Proxy - Gateway)
 
 ```java
 TransparentProxyDestination destination = TransparentProxyDestination
@@ -164,7 +168,7 @@ TransparentProxyDestination destination = TransparentProxyDestination
 HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);
 ```
 
-### After (Transparent Proxy - Destination)
+#### After (Transparent Proxy - Concrete Destination)
 
 ```java
 TransparentProxyDestination destination = TransparentProxyDestination
@@ -173,48 +177,17 @@ TransparentProxyDestination destination = TransparentProxyDestination
 HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);
 ```
 
-## Troubleshooting
-
-### Common Issues
-
-1. **Missing destination name for gateway**: Ensure the destination name is provided as the first parameter to `.gateway(<destination-name>, <destination-custom-resource-name>.<destination-custom-resource-namespace>)`
-2. **Tenant context not available**: Verify tenant information is properly set in the request context
-3. **Authentication failures**: Check that authentication headers and parameters are correctly configured
-4. **Network connectivity**: Verify that the Transparent Proxy is accessible from your environment
-
-### Evaluating Transparent Proxy Headers
-
-When using proxy servers it can be difficult to troubleshoot issues as it is often not obvious where exactly the error occurred.
-For example, with the Transparent Proxy errors might occur on the target system (e.g. OData service), the Destination Service or the Transparent Proxy itself.
+## Approach 2: Transparent Proxy Loader
 
-To make troubleshooting easier the Transparent Proxy adds additional response headers to provide more information about where an error occurred.
-For the above example of executing OData requests you can access the response headers as follows:
-
-```java
-try {
-    // execute OData request
-} catch (ODataResponseException e) {
-    System.out.println(e.getHttpCode());
-    // the Transparent Proxy will attach additional response headers in case an error occurred
-    System.out.println(e.getHttpHeaders());
-}
-```
-
-#### List of headers added by the Transparent Proxy
-
-- `X-Error-Origin` - the source of the error
-- `X-Proxy-Server` - the proxy server (Transparent Proxy)
-- `X-Error-Message` - thorough error message
-- `X-Error-Internal-Code` - set only when the source of the error is the XSUAA or Destination service.
-  The value is the HTTP code returned from one of these services.
-- `X-Request-Id` is sent with the response in all requests, both successful and failed
+The `TransparentProxy` class provides a `DestinationLoader` that enables routing **all destination traffic** through a single registered gateway host.
+This approach provides centralized proxy configuration where all destination requests are automatically routed through the configured gateway without requiring explicit destination builders.
 
-For more information, see [Troubleshooting](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/transparent-proxy-troubleshooting)
+### When to Use This Approach
 
-## Transparent Proxy Loader
+Use the Transparent Proxy Loader when:
 
-The `TransparentProxy` class is a `DestinationLoader` that enables routing all destination traffic through a single registered gateway host.
-This provides a centralized approach to proxy configuration where all destination requests are automatically routed through the configured gateway.
+- You want all destinations to automatically route through a single transparent proxy gateway
+- You prefer a centralized configuration approach
 
 ### Registration Methods
 
@@ -253,6 +226,44 @@ TransparentProxy.register("<destination-gateway-host>", 8080);
 Destination destination = DestinationAccessor.getDestination("my-destination");
 ```
 
+## Troubleshooting
+
+### Common Issues
+
+1. **Missing destination name for gateway**: Ensure the destination name is provided as the first parameter to `.gateway(<destination-name>, <destination-custom-resource-name>.<destination-custom-resource-namespace>)`
+2. **Tenant context not available**: Verify tenant information is properly set in the request context
+3. **Authentication failures**: Check that authentication headers and parameters are correctly configured
+4. **Network connectivity**: Verify that the Transparent Proxy is accessible from your environment
+
+### Evaluating Transparent Proxy Headers
+
+When using proxy servers it can be difficult to troubleshoot issues as it is often not obvious where exactly the error occurred.
+For example, with the Transparent Proxy errors might occur on the target system (e.g. OData service), the Destination Service or the Transparent Proxy itself.
+
+To make troubleshooting easier the Transparent Proxy adds additional response headers to provide more information about where an error occurred.
+For the above example of executing OData requests you can access the response headers as follows:
+
+```java
+try {
+    // execute OData request
+} catch (ODataResponseException e) {
+    System.out.println(e.getHttpCode());
+    // the Transparent Proxy will attach additional response headers in case an error occurred
+    System.out.println(e.getHttpHeaders());
+}
+```
+
+#### List of headers added by the Transparent Proxy
+
+- `X-Error-Origin` - the source of the error
+- `X-Proxy-Server` - the proxy server (Transparent Proxy)
+- `X-Error-Message` - thorough error message
+- `X-Error-Internal-Code` - set only when the source of the error is the XSUAA or Destination service.
+  The value is the HTTP code returned from one of these services.
+- `X-Request-Id` is sent with the response in all requests, both successful and failed
+
+For more information, see [Troubleshooting](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/transparent-proxy-troubleshooting)
+
 ## Related Documentation
 
 - [HTTP Client](http-client) - For using destinations with HTTP clients