README.mustache

# {{artifactId}}

{{appName}}

- API version: {{appVersion}}

{{{appDescriptionWithNewLines}}}

{{#infoUrl}}
For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
{{/infoUrl}}

This package is part of the STACKIT Java SDK. For additional information, please visit the [GitHub repository](https://{{gitHost}}/{{{gitUserId}}}/{{{gitRepoId}}}) of the SDK.


## Requirements

Building the API client library requires:
1. Java SDK (version 11 to 21 should be supported) installed on your system

## Installation

To install the API client library to your local Maven repository, simply execute:

```shell
./gradlew publishToMavenLocal
```

To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

```shell
# TODO: follow up story
# ./gradlew publishToMavenCentral
```

Refer to the [OSSRH Guide](http://central.sonatype.org/pages/ossrh-guide.html) for more information.

### Maven users

Add this dependency to your project's POM:

```xml
<dependency>
  <groupId>{{{groupId}}}</groupId>
  <artifactId>{{{artifactId}}}</artifactId>
  <version><SDK_VERSION></version>
  <scope>compile</scope>
</dependency>
```

### Gradle users

Add this dependency to your project's build file:

```groovy
  repositories {
    mavenCentral()     // Needed if the '{{{artifactId}}}' jar has been published to maven central.
    mavenLocal()       // Needed if the '{{{artifactId}}}' jar has been published to the local maven repo.
  }

  dependencies {
     implementation "{{{groupId}}}:{{{artifactId}}}:<SDK_VERSION>"
  }
```

### Others

At first generate the JAR by executing:

```shell
mvn clean package
```

Then manually install the following JARs:

- `target/{{{artifactId}}}-<SDK_VERSION>.jar`
- `target/lib/*.jar`

{{#jersey2}}
## Usage

To add a HTTP proxy for the API client, use `ClientConfig`:
```java
{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
import org.glassfish.jersey.apache.connector.ApacheConnectorProvider;
import org.glassfish.jersey.client.ClientConfig;
import org.glassfish.jersey.client.ClientProperties;
import {{{invokerPackage}}}.*;
import {{{package}}}.{{{classname}}};

...

ApiClient defaultClient = Configuration.getDefaultApiClient();
ClientConfig clientConfig = defaultClient.getClientConfig();
clientConfig.connectorProvider(new ApacheConnectorProvider());
clientConfig.property(ClientProperties.PROXY_URI, "http://proxy_url_here");
clientConfig.property(ClientProperties.PROXY_USERNAME, "proxy_username");
clientConfig.property(ClientProperties.PROXY_PASSWORD, "proxy_password");
defaultClient.setClientConfig(clientConfig);

{{{classname}}} apiInstance = new {{{classname}}}(defaultClient);
{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
```

{{/jersey2}}
## Getting Started

See the [{{serviceId}} examples]({{scmUrl}}/tree/main/examples/{{serviceId}}/src/main/java/cloud/stackit/sdk/{{serviceId}}/examples).


## Recommendation

It's recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issues.