Merge branch 'release/v1.3.0' into public-main

.gitignore

@@ -2,6 +2,7 @@
 .idea/*.iml
 .idea/modules
 .idea/.gitignore
+.idea/codeStyles
 build
 .gradle
 .gradle.properties

CHANGELOG.md

@@ -0,0 +1,14 @@
+# R2Z Changelog
+
+All notable changes to the R2Z will be documented in this file.
+
+## `1.3.0 (2023-02-22)`
+
+* Deprecation: This library is deprecated since 1.3.0
+
+
+* Feature: GitHub issue #3: Zowe Kotlin SDK: Java-like Kotlin API ([56788c1a](https://github.com/zowe/zowe-explorer-intellij/commit/56788c1a))
+* Feature: Implement ZosUssFile (copying methods - from uss to dsn and to uss folder) ([2bb0b257](https://github.com/zowe/zowe-explorer-intellij/commit/2bb0b257))
+
+
+* Bugfix: GitHub issue #9: Error Creating Connection ([bbc16d72](https://github.com/zowe/zowe-client-kotlin-sdk/commit/bbc16d72))

README.md

@@ -1,3 +1,5 @@
+# WARNING: THIS REPOSITORY IS MARKED AS 'DEPRECATED' AND WON'T BE MAINTAINED. CONSIDER SWITCHING TO ZOWE CLIENT KOTLIN SDK WITH THE SIMILAR APPROACH TO WORK WITH Z/OSMF REST API ([link](https://github.com/zowe/zowe-client-kotlin-sdk))
+
 ## zOSMF Retrofit Library
 This library covert zOSMF Rest API with kotlin object oriented code using Retrofit. r2z will allow you to send http requests to your zOSMF.
 
@@ -42,6 +44,14 @@ if (response.isSuccessful){
 ```
 Please note that in order to create API stub, you have to specify that the response should be converted by gson. And that's how you can easily use r2z.
 
+## Documentation with Dokka
+
+To build Dokka documentattion, run:
+```
+./gradlew dokkaHtml
+```
+Docs will be added to *build/dokka/html*
+
 ## How to run tests
 
 ### Unit tests

build.gradle

@@ -1,8 +1,12 @@
 // Copyright © 2020 IBA Group, a.s. All rights reserved. Use of this source code is governed by Eclipse Public License – v 2.0 that can be found at: https://www.eclipse.org/legal/epl-2.0/
+import org.jetbrains.dokka.gradle.DokkaTask
+import org.jetbrains.kotlin.config.LanguageVersion
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
   id 'java'
   id 'org.jetbrains.kotlin.jvm' version '1.6.21'
+  id 'org.jetbrains.dokka' version '1.7.20'
 }
 
 apply plugin: 'java'
@@ -26,29 +30,43 @@ repositories {
 dependencies {
   implementation "org.jetbrains.kotlin:kotlin-stdlib"
   implementation "org.jetbrains.kotlin:kotlin-reflect:1.6.21"
-  testImplementation 'org.junit.jupiter:junit-jupiter-api:5.8.2'
+  testImplementation 'org.junit.jupiter:junit-jupiter-api:5.9.2'
   testImplementation 'com.squareup.okhttp3:mockwebserver:4.10.0'
   testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine'
   implementation 'com.squareup.retrofit2:retrofit:2.9.0',
                  'com.squareup.retrofit2:converter-gson:2.9.0',
                  'com.squareup.retrofit2:converter-scalars:2.9.0',
                  'com.google.code.gson:gson:2.10',
                  'com.starxg:java-keytar:1.0.0',
-                 'org.yaml:snakeyaml:1.29',
-                 'org.junit.jupiter:junit-jupiter-api:5.8.2'
+                 'org.yaml:snakeyaml:1.33'
 }
 
 test {
   useJUnitPlatform()
 }
 
-tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).all {
+tasks.withType(KotlinCompile).all {
   kotlinOptions {
     jvmTarget = JavaVersion.VERSION_11.toString()
-    languageVersion = org.jetbrains.kotlin.config.LanguageVersion.LATEST_STABLE.versionString
+    languageVersion = LanguageVersion.LATEST_STABLE.versionString
   }
 }
 
+tasks.withType(DokkaTask.class) {
+  String dokkaBaseConfiguration = """
+    {
+      "footerMessage": "(c) 2022 IBA Group",
+      "templatesDir": "${file("dokka/templates").getAbsolutePath().replace('\\', '/')}",
+      "customAssets": ["${file("dokka/assets/zowe-icon.png").getAbsolutePath().replace('\\', '/')}"],
+      "customStyleSheets": ["${file("dokka/assets/logo-styles.css").getAbsolutePath().replace('\\', '/')}"]
+    }
+    """
+  pluginsMapConfiguration.set(
+          // fully qualified plugin name to json configuration
+          ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration]
+  )
+}
+
 task sourceJar(type: Jar) {
   classifier "sources"
   from sourceSets.main.allSource

dokka/assets/logo-styles.css

@@ -0,0 +1,15 @@
+.library-name a {
+  position: relative;
+  margin-left: 55px;
+}
+
+.library-name a::before {
+  content: '';
+  background: url("../images/zowe-icon.png") center no-repeat;
+  background-size: contain;
+  position: absolute;
+  width: 50px;
+  height: 50px;
+  top: -18px;
+  left: -55px;
+}

dokka/templates/includes/footer.ftl

@@ -0,0 +1,15 @@
+<#macro display>
+  <div class="footer">
+    <span class="go-to-top-icon">
+      <a href="#content" id="go-to-top-link"></a>
+    </span>
+    <span>${footerMessage}</span>
+    <span class="pull-right">
+      <span>Generated by </span>
+      <a href="https://github.com/Kotlin/dokka">
+        <span>dokka</span>
+        <span class="padded-icon"></span>
+      </a>
+    </span>
+  </div>
+</#macro>

dokka/templates/includes/header.ftl

@@ -0,0 +1,25 @@
+<#import "source_set_selector.ftl" as source_set_selector>
+<#macro display>
+<div class="navigation-wrapper" id="navigation-wrapper">
+  <div id="leftToggler"><span class="icon-toggler"></span></div>
+  <div class="library-name">
+    <@template_cmd name="pathToRoot">
+      <a href="${pathToRoot}index.html">
+        <@template_cmd name="projectName">
+          <span>Zowe Client Kotlin SDK</span>
+        </@template_cmd>
+      </a>
+    </@template_cmd>
+  </div>
+  <div>
+    <#-- This can be handled by the versioning plugin -->
+    <@version/>
+  </div>
+  <div class="pull-right d-flex">
+    <@source_set_selector.display/>
+    <a href="https://for-mainframe.github.io/" style="font-weight: 500; display: flex; align-items: center;">Other Docs</a>
+    <button id="theme-toggle-button"><span id="theme-toggle"></span></button>
+    <div id="searchBar"></div>
+  </div>
+</div>
+</#macro>

dokka/templates/includes/page_metadata.ftl

@@ -0,0 +1,6 @@
+<#macro display>
+    <title>${pageName} - Zowe Client Kotlin SDK Documentation</title>
+    <@template_cmd name="pathToRoot">
+    <link href="${pathToRoot}images/zowe-icon.png" rel="icon" type="image/png">
+    </@template_cmd>
+</#macro>

gradle.properties

@@ -10,4 +10,4 @@ signing.keyId=FADC1195
 signing.password=key_pass
 signing.secretKeyRingFile=path/to/secret/key
 
-projectVersion=1.2.3
+projectVersion=1.3.0-rc.11

src/intTest/kotlin/common/TsoApiTest.kt

@@ -19,7 +19,7 @@ class TsoApiTest: BaseTest() {
       authorizationToken = BASIC_AUTH_TOKEN,
       proc = "IKJACCNT",
       chset = "697",
-      cpage = TsoCodePage.IBM_1047,
+      cpage = "1047",
       rows = 204,
       cols = 160,
       rsize = 50000,

src/main/kotlin/eu/ibagroup/r2z/ConsoleAPI.kt

@@ -0,0 +1,25 @@
+// Copyright © 2020 IBA Group, a.s. All rights reserved. Use of this source code is governed by Eclipse Public License – v 2.0 that can be found at: https://www.eclipse.org/legal/epl-2.0/
+
+package eu.ibagroup.r2z
+
+import eu.ibagroup.r2z.annotations.AvailableSince
+import eu.ibagroup.r2z.annotations.ZVersion
+import retrofit2.Call
+
+import retrofit2.http.Body
+import retrofit2.http.Header
+import retrofit2.http.PUT
+import retrofit2.http.Path
+
+interface ConsoleAPI {
+
+  @AvailableSince(ZVersion.ZOS_2_1)
+  @PUT("/zosmf/restconsoles/consoles/{consolename}")
+  fun issueCommand(
+    @Header("Authorization") authorizationToken: String,
+    @Header("Content-type") contentType: ContentType = ContentType.APP_JSON,
+    @Path("consolename") consoleName: String,
+    @Body body: IssueRequestBody
+    ): Call<IssueResponse>
+
+}

src/main/kotlin/eu/ibagroup/r2z/DataAPI.kt

@@ -259,9 +259,12 @@ interface DataAPI {
 
   /**
    * Copy from - to
-   * SEQ -> SEQ
-   * PDS MEMBER -> SEQ (overwrites content)
-   * PDS MEMBER or MEMBERS -> PDS (adds or replaces)
+   *
+   * **SEQ** -> **SEQ**
+   *
+   * **PDS MEMBER** -> **SEQ** (overwrites content)
+   *
+   * **PDS MEMBER or MEMBERS** -> **PDS** (adds or replaces)
    */
   @AvailableSince(ZVersion.ZOS_2_1)
   @PUT("/zosmf/restfiles/ds/{to-data-set-name}")
@@ -275,10 +278,14 @@ interface DataAPI {
 
   /**
    * Volser for uncatalogued datasets
+   *
    * Copy from - to
-   * SEQ -> SEQ
-   * PDS MEMBER -> SEQ
-   * PDS MEMBER or MEMBERS -> PDS
+   *
+   * **SEQ** -> **SEQ**
+   *
+   * **PDS MEMBER** -> **SEQ**
+   *
+   * **PDS MEMBER** or **MEMBERS** -> **PDS**
    */
   @AvailableSince(ZVersion.ZOS_2_1)
   @PUT("/zosmf/restfiles/ds/-({to-volser})/{to-data-set-name}")
@@ -292,8 +299,9 @@ interface DataAPI {
   ): Call<Void>
 
   /**
-   * SEQ -> PDS MEMBER
-   * PDS MEMBER -> PDS MEMBER
+   * **SEQ** -> **PDS MEMBER**
+   *
+   * **PDS MEMBER** -> **PDS MEMBER**
    */
   @AvailableSince(ZVersion.ZOS_2_1)
   @PUT("/zosmf/restfiles/ds/{to-data-set-name}({member-name})")
@@ -307,9 +315,11 @@ interface DataAPI {
   ): Call<Void>
 
   /**
-   * Volser for uncatalogued datasets
-   * SEQ -> PDS MEMBER
-   * PDS MEMBER -> PDS MEMBER
+   * Volser for uncatalogued
+   *
+   * **SEQ** -> **PDS MEMBER**
+   *
+   * **PDS MEMBER** -> **PDS MEMBER**
    */
   @AvailableSince(ZVersion.ZOS_2_1)
   @PUT("/zosmf/restfiles/ds/-({to-volser})/{to-data-set-name}({member-name})")
@@ -324,7 +334,7 @@ interface DataAPI {
   ): Call<Void>
 
   /**
-   * USS FILE -> SEQ (truncates contents)
+   * **USS FILE** -> **SEQ** (truncates contents)
    */
   @AvailableSince(ZVersion.ZOS_2_1)
   @PUT("/zosmf/restfiles/ds/{to-data-set-name}")
@@ -337,7 +347,7 @@ interface DataAPI {
   ): Call<Void>
 
   /**
-   * USS FILE -> PDS MEMBER
+   * **USS FILE** -> **PDS MEMBER**
    */
   @AvailableSince(ZVersion.ZOS_2_1)
   @PUT("/zosmf/restfiles/ds/{to-data-set-name}({member-name})")
@@ -461,13 +471,15 @@ interface DataAPI {
     @Header("Authorization") authorizationToken: String,
     @Header("X-IBM-BPXK-AUTOCVT") xIBMBpxkAutoCvt: XIBMBpxkAutoCvt? = null,
     @Body body: CopyDataUSS.CopyFromFileOrDir,
-    @Path("filepath-name") filePath: FilePath,
+    @Path("filepath-name", encoded = true) filePath: FilePath,
   ): Call<Void>
 
   /**
-   * SEQ -> USS FILE
-   * PDS MEMBER -> USS FILE
-   * PDS -> USS DIR doesn't work
+   * **SEQ** -> **USS FILE**
+   *
+   * **PDS MEMBER** -> **USS FILE**
+   *
+   * **WARNING:** PDS -> USS DIR doesn't work
    */
   @AvailableSince(ZVersion.ZOS_2_1)
   @PUT("/zosmf/restfiles/fs/{filepath-name}")

src/main/kotlin/eu/ibagroup/r2z/InfoAPI.kt

@@ -11,10 +11,10 @@ interface InfoAPI {
 
   /**
    * An API function to get an information of the system where z/OSMF is currently running
-   * @return a wrapped instance of InfoResponse
+   * @return a wrapped instance of [InfoResponse]
    */
   @AvailableSince(ZVersion.ZOS_2_1)
   @GET("zosmf/info")
   fun getSystemInfo() : Call<InfoResponse>
 
-}
+}

src/main/kotlin/eu/ibagroup/r2z/InfoResponse.kt

@@ -2,8 +2,13 @@
 
 package eu.ibagroup.r2z
 
+import com.google.gson.Gson
+import com.google.gson.TypeAdapter
 import com.google.gson.annotations.Expose
+import com.google.gson.annotations.JsonAdapter
 import com.google.gson.annotations.SerializedName
+import com.google.gson.stream.JsonReader
+import com.google.gson.stream.JsonWriter
 import eu.ibagroup.r2z.annotations.ZVersion
 
 data class InfoResponse (
@@ -24,6 +29,7 @@ data class InfoResponse (
   val zosmfHostname: String = "null",
 
   @SerializedName("plugins")
+  @JsonAdapter(PluginsAdapter::class)
   @Expose
   val plugins: List<Plugin> = emptyList(),
 
@@ -46,4 +52,22 @@ data class InfoResponse (
     "04.28.00" -> ZVersion.ZOS_2_5
     else -> ZVersion.ZOS_2_1
   }
-}
+}
+
+class PluginsAdapter : TypeAdapter<List<Plugin>>() {
+  private val gson = Gson()
+  override fun write(out: JsonWriter?, value: List<Plugin>?) {
+    gson.toJson(value, List::class.java, out)
+  }
+
+  override fun read(reader: JsonReader): List<Plugin> {
+    var result = listOf<Plugin>()
+    runCatching {
+      result = gson.fromJson(reader, List::class.java)
+    }.onFailure {
+      reader.skipValue()
+    }
+    return result
+  }
+
+}