Merge branch 'main' into fix-access-level-message-constructors

Author: Jonas-Isr

README.md

@@ -155,8 +155,19 @@ For SAP internal development, you can also use `SNAPSHOT` builds from the [inter
 
 ### _"How to add a custom header to AI Core requests?"_
 
-Create a [HeaderProvider](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/http-destinations#about-headerproviders).
+The AI SDK leverages the destination concept from the SAP Cloud SDK to manage the connection to AI Core.
+This opens up a wide range of possibilities to customize the connection, including adding custom headers.
 
+```java
+var service = new AiCoreService();
+var service = service.withBaseDestination(
+        DefaultHttpDestination.fromDestination(service.getBaseDestination())
+          .header("my-header-key", "my-header-value")
+          .build()
+);
+```
+
+For more information, please refer to the [AI Core connectivity guide](./docs/guides/CONNECTING_TO_AICORE.md) and the [SAP Cloud SDK documentation](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/http-destinations).
 
 ### _"There's a vulnerability warning `CVE-2021-41251`?"_
 

docs/guides/CONNECTING_TO_AICORE.md

@@ -6,6 +6,7 @@
     - [Providing a Service Binding Locally](#providing-a-service-binding-locally)
     - [Using the `AICORE_SERVICE_KEY` Environment Variable](#using-the-aicore_service_key-environment-variable)
 - [Using a Destination from the BTP Destination Service](#using-a-destination-from-the-btp-destination-service)
+- [Creating a Custom Destination](#creating-a-custom-destination)
 
 
 The AI SDK uses the [`Destination` concept of the SAP Cloud SDK](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/destination-service) to connect to AI Core.
@@ -152,4 +153,23 @@ new DeploymentApi(aiCoreService);
 > The `destination` obtained from BTP destination service will expire once the contained OAuth2 token expires.
 > Please run the above code for each request to ensure the destination is up-to-date.
 > Destinations are cached by default, so this does not come with a performance penalty.
-> To learn more, see the [SAP Cloud SDK documentation](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/destination-service).
+> To learn more, see the [SAP Cloud SDK documentation](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/destination-service).
+
+## Creating a Custom Destination
+
+If the above options are not suitable for your use case (e.g. because you are obtaining the credentials in a completely different way), you can also use a custom-built destination:
+
+```java
+var destination = OAuth2DestinationBuilder
+    .forTargetUrl("https://<ai-api-url>")
+    .withTokenEndpoint("https://<xsuaa-url>/oauth/token")
+    .withClient(new ClientCertificate("<cert>", "<key>", "<clientid>"), OnBehalfOf.TECHNICAL_USER_PROVIDER)
+    .build();
+
+AiCoreService aiCoreService = new AiCoreService().withBaseDestination(destination);
+```
+
+The above example assumes you are using a client certificate for authentication and have stored the relevant credentials somewhere.
+You are free to use X509 certificates (also via the Zero Trust Identity Service) or a client secret.
+
+For more details, refer to the [SAP Cloud SDK documentation](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/destination-service).