Merge pull request #425 from zowe/examples

Refactor IssueUss class

Author: frankgiordano

README.md

@@ -92,7 +92,7 @@ zowe.client.sdk.zostso.methods
 
 zowe.client.sdk.zosuss.method  
 
-    IssueUss   
+    UssCmd   
           
 ## TeamConfig Package  
 

src/main/java/zowe/client/sdk/zostso/methods/TsoCmd.java

@@ -209,7 +209,7 @@ private void stopTso(final String sessionId) throws ZosmfRequestException {
     }
 
     /**
-     * Transform the JSON response payload for its tso message types
+     * Transform the JSON response payload for its TSO message types
      *
      * @param tsoData JsonNode object
      * @author Frank Giordano

src/main/java/zowe/client/sdk/zosuss/README.md

@@ -10,32 +10,33 @@ API located in the method package.
 package zowe.client.sdk.examples.zosuss;
 
 import zowe.client.sdk.core.SshConnection;
-import zowe.client.sdk.zosuss.exception.IssueUssException;
-import zowe.client.sdk.zosuss.method.IssueUss;
+import zowe.client.sdk.zosuss.exception.UssCmdException;
+import zowe.client.sdk.zosuss.method.UssCmd;
+import zowe.client.sdk.zosuss.method.UssSshCmd;
 
 /**
- * Class example to test uss command functionality via IssueUss class.
+ * Class example to test USS command functionality via UssCmd class.
  *
  * @author Frank Giordano
  * @version 5.0
  */
-public class IssueUssExp {
+public class UssCmdExp {
 
     /**
-     * The main method defines SSH connection and showcases executing a USS command via IssueUss class.
+     * The main method defines ssh connection and showcases executing a USS command via UssCmd class.
      *
      * @param args for main not used
      * @author Frank Giordano
      */
     public static void main(String[] args) {
         int portNum = 0; // replace with valid value
         SshConnection conn = new SshConnection("xxx", portNum, "xxx", "xxx");
-        IssueUss issueUss = new IssueUss(conn);
+        UssCmd ussCmd = new UssCmd(conn);
         // 10000 is the timeout value in milliseconds
         try {
             // value "frank" should display
-            System.out.println(issueUss.issueCommand("mkdir test;cd test;touch frank;ls", 10000));
-        } catch (IssueUssException e) {
+            System.out.println(ussCmd.issueCommand("mkdir test;cd test;touch frank;ls", 10000));
+        } catch (UssCmdException e) {
             throw new RuntimeException(e);
         }
     }

src/main/java/zowe/client/sdk/zosuss/exception/IssueUssException.java renamed to src/main/java/zowe/client/sdk/zosuss/exception/UssCmdException.java

@@ -15,16 +15,16 @@
  * @author Frank Giordano
  * @version 5.0
  */
-public class IssueUssException extends Exception {
+public class UssCmdException extends Exception {
 
     /**
-     * IssueCommandException constructor for message value
+     * UssCmdException constructor for message value
      *
      * @param message error message
      * @param err     original throwable exception
      * @author Frank Giordano
      */
-    public IssueUssException(final String message, Throwable err) {
+    public UssCmdException(final String message, Throwable err) {
         super(message, err);
     }
 

src/main/java/zowe/client/sdk/zosuss/method/IssueUss.java renamed to src/main/java/zowe/client/sdk/zosuss/method/UssCmd.java

@@ -13,35 +13,32 @@
 import com.jcraft.jsch.JSch;
 import com.jcraft.jsch.JSchException;
 import com.jcraft.jsch.Session;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 import zowe.client.sdk.core.SshConnection;
 import zowe.client.sdk.utility.ValidateUtils;
 import zowe.client.sdk.utility.timer.WaitUtil;
-import zowe.client.sdk.zosuss.exception.IssueUssException;
+import zowe.client.sdk.zosuss.exception.UssCmdException;
 
 import java.io.ByteArrayOutputStream;
 import java.io.IOException;
+import java.io.OutputStream;
 import java.util.Properties;
 
 /**
- * IssueUss Class provides a way to execute USS commands via SSH connection
+ * UssCmd Class provides a way to execute USS commands via ssh connection
  *
  * @author Frank Giordano
  * @version 5.0
  */
-public class IssueUss {
-
-    private static final Logger LOG = LoggerFactory.getLogger(IssueUss.class);
+public class UssCmd {
 
     private final SshConnection connection;
 
     /**
-     * Shell constructor
+     * UssCmd constructor
      *
      * @param connection SshConnection object
      */
-    public IssueUss(final SshConnection connection) {
+    public UssCmd(final SshConnection connection) {
         ValidateUtils.checkSshConnection(connection);
         this.connection = connection;
     }
@@ -52,43 +49,73 @@ public IssueUss(final SshConnection connection) {
      * @param command string value contains one or more USS commands
      * @param timeout int value in milliseconds for timeout duration on session connection
      * @return string output value
-     * @throws IssueUssException SSH Unix System Services error request
+     * @throws UssCmdException ssh Unix System Services error request
      * @author Frank Giordano
      */
-    public String issueCommand(final String command, final int timeout) throws IssueUssException {
-        Session session = null;
-        ChannelExec channel = null;
+    public String issueCommand(final String command, final int timeout) throws UssCmdException {
+        try (final ByteArrayOutputStream responseStream = new ByteArrayOutputStream();
+             final ManagedSession session = new ManagedSession(connection, timeout);
+             final ManagedChannel channel = new ManagedChannel(session.get(), command, responseStream)) {
+
+            // Wait for channel execution to complete
+            while (channel.get().isConnected()) {
+                WaitUtil.wait(1000);
+            }
+
+            return responseStream.toString();
+        } catch (IOException | JSchException e) {
+            throw new UssCmdException(e.getMessage(), e);
+        }
+    }
 
-        try (final ByteArrayOutputStream responseStream = new ByteArrayOutputStream()) {
-            session = new JSch().getSession(connection.getUser(), connection.getHost(), connection.getPort());
+    /**
+     * AutoCloseable wrapper for JSch Session
+     */
+    static class ManagedSession implements AutoCloseable {
+        private final Session session;
+
+        ManagedSession(SshConnection connection, int timeout) throws JSchException {
+            this.session = new JSch().getSession(connection.getUser(), connection.getHost(), connection.getPort());
             session.setPassword(connection.getPassword());
             final Properties config = new Properties();
             config.put("StrictHostKeyChecking", "no");
             config.put("PreferredAuthentications", "password");
             session.setConfig(config);
             session.connect(timeout);
+        }
 
-            channel = (ChannelExec) session.openChannel("exec");
+        Session get() {
+            return session;
+        }
+
+        @Override
+        public void close() {
+            if (session != null && session.isConnected()) {
+                session.disconnect();
+            }
+        }
+    }
+
+    /**
+     * AutoCloseable wrapper for JSch ChannelExec
+     */
+    static class ManagedChannel implements AutoCloseable {
+        private final ChannelExec channel;
+
+        ManagedChannel(Session session, String command, OutputStream responseStream) throws JSchException {
+            this.channel = (ChannelExec) session.openChannel("exec");
             channel.setCommand(command);
             channel.setOutputStream(responseStream);
             channel.connect();
+        }
 
-            while (channel.isConnected()) {
-                WaitUtil.wait(1000);
-            }
+        ChannelExec get() {
+            return channel;
+        }
 
-            return responseStream.toString();
-        } catch (IOException e) {
-            LOG.debug("IOException error {}", String.valueOf(e));
-            throw new IssueUssException(e.getMessage(), e);
-        } catch (JSchException e) {
-            LOG.debug("JSchException error {}", String.valueOf(e));
-            throw new IssueUssException(e.getMessage(), e);
-        } finally {
-            if (session != null) {
-                session.disconnect();
-            }
-            if (channel != null) {
+        @Override
+        public void close() {
+            if (channel != null && channel.isConnected()) {
                 channel.disconnect();
             }
         }

src/main/javadoc/serialized-form.html

@@ -97,7 +97,7 @@ <h2 title="Package">Package&nbsp;<a href="zowe/client/sdk/zosuss/exception/packa
 <ul class="block-list">
 <li>
 <section class="serialized-class-details" id="zowe.client.sdk.zosuss.exception.IssueUssException">
-<h3>Exception&nbsp;<a href="zowe/client/sdk/zosuss/exception/IssueUssException.html" title="class in zowe.client.sdk.zosuss.exception">zowe.client.sdk.zosuss.exception.IssueUssException</a></h3>
+<h3>Exception&nbsp;<a href="zowe/client/sdk/zosuss/exception/IssueUssException.html" title="class in zowe.client.sdk.zosuss.exception">zowe.client.sdk.zosuss.exception.UssCmdException</a></h3>
 <div class="type-signature">class IssueUssException extends <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Exception.html" title="class or interface in java.lang" class="external-link">Exception</a> implements <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/io/Serializable.html" title="class or interface in java.io" class="external-link">Serializable</a></div>
 </section>
 </li>

src/main/javadoc/zowe/client/sdk/zosuss/exception/IssueUssException.html

@@ -70,7 +70,7 @@ <h1 title="Class IssueUssException" class="title">Class IssueUssException</h1>
 <div class="inheritance" title="Inheritance Tree"><a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">java.lang.Object</a>
 <div class="inheritance"><a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Throwable.html" title="class or interface in java.lang" class="external-link">java.lang.Throwable</a>
 <div class="inheritance"><a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Exception.html" title="class or interface in java.lang" class="external-link">java.lang.Exception</a>
-<div class="inheritance">zowe.client.sdk.zosuss.exception.IssueUssException</div>
+<div class="inheritance">zowe.client.sdk.zosuss.exception.UssCmdException</div>
 </div>
 </div>
 </div>

src/main/javadoc/zowe/client/sdk/zosuss/method/IssueUss.html

@@ -72,7 +72,7 @@
 <h1 title="Class IssueUss" class="title">Class IssueUss</h1>
 </div>
 <div class="inheritance" title="Inheritance Tree"><a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">java.lang.Object</a>
-<div class="inheritance">zowe.client.sdk.zosuss.method.IssueUss</div>
+<div class="inheritance">zowe.client.sdk.zosuss.method.UssCmd</div>
 </div>
 <section class="class-description" id="class-description">
 <hr>

src/test/java/zowe/client/sdk/zosuss/UssCmdExceptionTest.java

@@ -0,0 +1,58 @@
+/*
+ * This program and the accompanying materials are made available under the terms of the
+ * Eclipse Public License v2.0 which accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-v20.html
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *
+ * Copyright Contributors to the Zowe Project.
+ */
+package zowe.client.sdk.zosuss;
+
+import org.junit.jupiter.api.Test;
+import zowe.client.sdk.zosuss.exception.UssCmdException;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Class containing unit tests for UssCmdException.
+ *
+ * @author Frank Giordano
+ * @version 5.0
+ */
+public class UssCmdExceptionTest {
+
+    @Test
+    public void tstMessageIsStoredCorrectly() {
+        UssCmdException ex = new UssCmdException("Test error", null);
+        assertEquals("Test error", ex.getMessage());
+    }
+
+    @Test
+    public void tstCauseIsStoredCorrectly() {
+        Throwable cause = new RuntimeException("Root cause");
+        UssCmdException ex = new UssCmdException("Wrapper message", cause);
+
+        assertEquals("Wrapper message", ex.getMessage());
+        assertSame(cause, ex.getCause());
+    }
+
+    @Test
+    public void tstToStringContainsClassNameAndMessage() {
+        UssCmdException ex = new UssCmdException("Something went wrong", null);
+        String toStringValue = ex.toString();
+
+        assertTrue(toStringValue.contains("UssCmdException"));
+        assertTrue(toStringValue.contains("Something went wrong"));
+    }
+
+    @Test
+    public void tstExceptionWithNullMessage() {
+        Throwable cause = new IllegalArgumentException("Bad arg");
+        UssCmdException ex = new UssCmdException(null, cause);
+
+        assertNull(ex.getMessage());
+        assertSame(cause, ex.getCause());
+    }
+
+}

src/test/java/zowe/client/sdk/zosuss/method/UssCmdTest.java

@@ -0,0 +1,89 @@
+/*
+ * This program and the accompanying materials are made available under the terms of the
+ * Eclipse Public License v2.0 which accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-v20.html
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *
+ * Copyright Contributors to the Zowe Project.
+ */
+package zowe.client.sdk.zosuss.method;
+
+import com.jcraft.jsch.ChannelExec;
+import com.jcraft.jsch.JSchException;
+import com.jcraft.jsch.Session;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.MockedConstruction;
+import org.mockito.Mockito;
+import zowe.client.sdk.core.SshConnection;
+import zowe.client.sdk.zosuss.exception.UssCmdException;
+
+import java.io.OutputStream;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * Class containing unit tests for UssCmd.
+ *
+ * @author Frank Giordano
+ * @version 5.0
+ */
+public class UssCmdTest {
+
+    private SshConnection mockConnection;
+
+    @BeforeEach
+    public void setup() {
+        mockConnection = mock(SshConnection.class);
+        when(mockConnection.getUser()).thenReturn("testuser");
+        when(mockConnection.getHost()).thenReturn("localhost");
+        when(mockConnection.getPort()).thenReturn(22);
+        when(mockConnection.getPassword()).thenReturn("testpass");
+    }
+
+    @Test
+    public void tstIssueCommandReturnsOutputSuccess() throws Exception {
+        // Mock JSch Session and ChannelExec
+        Session mockSession = mock(Session.class);
+        ChannelExec mockChannel = mock(ChannelExec.class);
+
+        // Simulate channel disconnect after one loop
+        when(mockChannel.isConnected()).thenReturn(true, false);
+        when(mockSession.openChannel("exec")).thenReturn(mockChannel);
+
+        try (MockedConstruction<UssCmd.ManagedSession> ignored1 = Mockito.mockConstruction(UssCmd.ManagedSession.class,
+                (mock, context) -> when(mock.get()).thenReturn(mockSession));
+             MockedConstruction<UssCmd.ManagedChannel> ignored2 = Mockito.mockConstruction(UssCmd.ManagedChannel.class,
+                     (mock, context) -> {
+                         // Grab the real OutputStream passed in constructor
+                         OutputStream os = (OutputStream) context.arguments().get(2);
+                         os.write("mock output".getBytes());
+                         when(mock.get()).thenReturn(mockChannel);
+                     })) {
+
+            UssCmd cmd = new UssCmd(mockConnection);
+            String result = cmd.issueCommand("echo test", 1000);
+
+            assertEquals("mock output", result);
+        }
+    }
+
+    @Test
+    public void tstIssueCommandThrowsExceptionOnJSchError() throws Exception {
+        Session mockSession = mock(Session.class);
+        when(mockSession.openChannel("exec")).thenThrow(new JSchException("SSH error"));
+
+        try (MockedConstruction<UssCmd.ManagedSession> ignored1 = Mockito.mockConstruction(UssCmd.ManagedSession.class,
+                (mock, context) -> when(mock.get()).thenReturn(mockSession))) {
+
+            UssCmd cmd = new UssCmd(mockConnection);
+
+            assertThrows(UssCmdException.class, () -> cmd.issueCommand("bad cmd", 1000));
+        }
+    }
+
+}