Merge pull request #3 from harveymmaunders/java-rest-template

Java rest template

client-samples/java/rest/.gitignore

@@ -0,0 +1,4 @@
+build
+install
+.gradle/
+.idea/

client-samples/java/rest/README.md

@@ -0,0 +1,64 @@
+# Java REST Client Example Project
+This project is a starting template for integrating with REST APIs on the API Platform.
+
+## Retrofit
+This example app uses plain Java, with no larger frameworks such as Spring Boot. It uses the retrofit library, which configures API calls as an interface. Please see the [HelloWorldRestService interface](./src/main/java/com/ms/infra/example/application/servies/HelloWorldRestService.java) for an example. You can find the Retrofit docs [here](https://square.github.io/retrofit/).
+
+Below are the example services we have configured:
+
+| Service         | Description                                                                                                                     |
+| --------------- |---------------------------------------------------------------------------------------------------------------------------------|
+| getServices     | Calls a GET request on the `services` endpoint.                                                                                 |
+| getStatus       | Calls a GET request on the `status` endpoint, showing how to use a void response body, path and query parameters, and a header. |
+
+The `ExampleApplication.java` file shows how to use the MsRetrofitWrapper and makes a GET request to the `services` endpoint.
+
+## Running the Java Client application
+It is important to ensure that the Java SDK is installed and the `JAVA_HOME` environment variable has been set.
+This can be checked by performing the following:
+
+* Windows cmd: `echo %JAVA_HOME%`
+* Mac/Linux terminal: `echo $JAVA_HOME`
+
+If the result is empty, you will need to download and configure Java on your machine.
+
+Once the Java SDK is installed and the `JAVA_HOME` environment variable has been set it is possible to run the application.
+Type in the appropriate command to launch the application
+
+* Windows: `gradlew.bat bootRun`
+* Mac/Linux: `./gradlew bootRun`
+curl -X GET -v --header "Authorization: Bearer $ACCESS_TOKEN" --header 'Accept: application/json' https://api.morganstanley.com/hello/services'
+
+## Create DER Encoded File
+For this example the RSA Private key that was generated, `private_key.pem`, is not in a format that Java will understand and needs to be converted to a binary encoding.
+The [PKCS8](https://en.wikipedia.org/wiki/PKCS_8) format is a standardized way to store a private key information.
+To convert the `private_key.pem` to PKCS8 use the following command
+
+```shell
+openssl pkcs8 -topk8 -inform PEM -outform DER -in private_key.pem -out private_key.der -nocrypt
+```
+The `der` output format is a just an encoding format, to find out more check <https://en.wikipedia.org/wiki/X.690#DER_encoding>
+
+Now that we have the file private key in a usable format we can use the Java Client to test the connection to Morgan Stanley's API offering.
+
+## Configuring the Java Client
+
+### Properties
+Make these changes to the `META-INF/microprofile-config.properties` resource file
+
+| Property Name                     | Description                                                                             | Required |
+|-----------------------------------|-----------------------------------------------------------------------------------------|----------|
+| `morgan-stanley-oauth2-token-uri` | Morgan Stanley OAuth2 token endpoint URL                                                | True     |
+| `client-app-id`                   | The client id that will be sent to you from your Morgan Stanley contact                 | True     |
+| `client-app-scope`                | The scope/s that will be sent to from your Morgan Stanley contact                       | True     |
+| `private-key-file`                | The path to the private_key.der that has been created                                   | True     |
+| `public-certificate-file`         | The path to the public_key.cer that was created and sent to your Morgan Stanley contact | True     |
+| `proxy-host`                      | Optional proxy host                                                                     | False    |
+| `proxy-port`                      | Optional proxy port                                                                     | False    |
+
+# Legal
+
+Morgan Stanley makes this available to you under the Apache License, Version 2.0 (the "License"). You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+See the NOTICE file distributed with this work for additional information regarding copyright ownership.
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and limitations under the License.

client-samples/java/rest/build.gradle.kts

@@ -0,0 +1,58 @@
+plugins {
+    id("java")
+    id("com.gradleup.shadow") version "8.3.5"
+}
+
+group = "example.application"
+version = "1.0-SNAPSHOT"
+
+dependencies {
+    implementation(group="com.google.guava", name="guava", version="${property("googleGuavaVersion")}")
+    implementation(group="com.microsoft.azure", name="msal4j", version="${property("microsoftAzureMsal4jVersion")}")
+
+    // okhttp/retrofit
+    implementation(group="com.squareup.okhttp3", name="logging-interceptor", version="${property("squareupOkhttp3Version")}")
+    implementation(group="com.squareup.okhttp3", name="okhttp", version="${property("squareupOkhttp3Version")}")
+    implementation(group="com.squareup.retrofit2", name="converter-jackson", version="${property("squareupRetrofit2Version")}")
+    implementation(group="com.squareup.retrofit2", name="retrofit", version="${property("squareupRetrofit2Version")}")
+
+    // slf4j
+    implementation(group="org.slf4j", name="slf4j-api", version="${property("slf4jVersion")}")
+    implementation(group="org.slf4j", name="slf4j-simple", version="${property("slf4jVersion")}")
+
+    // microprofile
+    implementation(group="org.eclipse.microprofile", name="microprofile", version="${property("eclipseMicroprofileVersion")}")
+    implementation(group="org.eclipse.microprofile.config", name="microprofile-config-api", version="${property("eclipseMicroprofileConfigVersion")}")
+    implementation(group="io.smallrye.config", name="smallrye-config", version="${property("smallRyeConfigVersion")}")
+    implementation(group="org.osgi", name="org.osgi.annotation.bundle", version= "${property("osgiAnnotationBundleVersion")}")
+    implementation(group="jakarta.annotation", name="jakarta.annotation-api", version="${property("jakartaAnnotationVersion")}")
+
+    // testing
+    testImplementation(group="com.squareup.okhttp3", name="mockwebserver", version="${property("squareupOkhttp3MockwebserverVersion")}")
+    testImplementation(group="org.junit.jupiter", name="junit-jupiter", version="${property("junitJupiterVersion")}")
+    testImplementation(group="org.mockito", name="mockito-core", version="${property("mockitoCoreVersion")}")
+}
+
+repositories {
+    mavenCentral()
+}
+
+tasks {
+    build {
+        dependsOn(shadowJar) // required to build a fat jar
+    }
+    jar {
+        manifest {
+            attributes(mapOf("Main-Class" to "com.ms.infra.example.application.ExampleApplication"))
+        }
+    }
+    test {
+        minHeapSize = "128m" // initial heap size
+        maxHeapSize = "512m" // maximum heap size
+        useJUnitPlatform()
+    }
+    wrapper {
+        gradleVersion = "8.3"
+        distributionType = Wrapper.DistributionType.ALL
+    }
+}

client-samples/java/rest/gradle.properties

@@ -0,0 +1,13 @@
+googleGuavaVersion=33.3.1-jre
+microsoftAzureMsal4jVersion=1.17.3
+squareupOkhttp3Version=4.11.0
+squareupRetrofit2Version=2.11.0
+slf4jVersion=2.0.16
+eclipseMicroprofileVersion=6.0
+eclipseMicroprofileConfigVersion=3.1
+smallRyeConfigVersion=3.9.1
+osgiAnnotationBundleVersion=2.0.0
+jakartaAnnotationVersion=3.0.0
+squareupOkhttp3MockwebserverVersion=4.12.0
+junitJupiterVersion=5.11.3
+mockitoCoreVersion=5.14.2

client-samples/java/rest/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.3-all.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists