Phase2 refactor (#4)

* Simplified logic of controllers.
Avoided TSQ object memory leak.
Removed unnecessary imports.
Removed un-thrown exceptions.
Added RootController as a 'usage' convenience landing page.
Aliased REST endpoints for simplicity.
Improved error messages and comments.
Some renames for consistency and simplicity.

* Minor messsage format

* Simplify getMapping URL

* Comments for RootController

Co-authored-by: ivanh <[email protected]>

Author: PhilWakelin

src/main/java/com/ibm/cicsdev/springboot/jcics/Application.java

@@ -14,10 +14,10 @@
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 
 @SpringBootApplication
-public class Application {
-
-	public static void main(String[] args) {
+public class Application 
+{
+	public static void main(String[] args) 
+	{
 		SpringApplication.run(Application.class, args);
 	}
-
 }

src/main/java/com/ibm/cicsdev/springboot/jcics/BrowseTSQController.java

@@ -10,8 +10,6 @@
 
 package com.ibm.cicsdev.springboot.jcics;
 
-import java.io.IOException;
-import java.io.UnsupportedEncodingException;
 import java.util.ArrayList;
 
 import org.springframework.web.bind.annotation.GetMapping;
@@ -23,77 +21,72 @@
 import com.ibm.cics.server.TSQ;
 
 @RestController
-public class BrowseTSQController {
-
+public class BrowseTSQController 
+{
 	/**
 	 * The @GetMapping annotation ensures that HTTP GET requests to the /browseTSQs URL path are
-	 * mapped to the annotated method. 
-	 * @throws IOException 
-	 **/
-	
-	@GetMapping("/browseTSQs")
-	public String browseTSQs(@RequestParam(value = "tsqName", defaultValue = "ANNE") String tsqName) throws IOException {
-
-		// retrieve and store the list of items on the TSQ
-		ArrayList<String> records = new ArrayList<String>();
-
-		// browse the records
-		try {
-			
-			records = browseTSQ(tsqName);
-			
-		} catch ( CicsConditionException e) {
-			
-			// Print the stack trace
+	 * mapped to the annotated method.  
+	 **/	
+	@GetMapping("/browse")
+	public String browseTSQ(@RequestParam(value = "tsq", defaultValue = "ANNE") String tsqName) 
+	{
+		// ArrayList of items in the TSQ
+		ArrayList<String> tsqItems;
+
+		// Populate the records
+		try 
+		{		
+			tsqItems = readTSQ(tsqName);		
+		} 
+		catch ( CicsConditionException e) 
+		{		
+			// Return error details
 			e.printStackTrace();
-
-			// Return useful information to the users when meeting errors
-			return "Oops! Unexpected CICS conditionn exception: "  + e.getMessage() + ". Please check stderr for details.";
+			return "Unexpected CICS condition exception: "  + e.getMessage() + ". Check dfhjvmerr for further details.";
 		}		
 
-		return records.toString();
+		return tsqItems.toString();
 	}
 
+		
 	/**
 	 * A method to browse a CICS TSQ
 	 * 
-	 * @param tsqName, the name of the TSQ to browse @return, an ArrayList of records from the TSQ
+	 * @param tsqName, the name of the TSQ to browse 
+	 * @return, an ArrayList of records from the TSQ
 	 * @throws CicsConditionException
-	 * @throws UnsupportedEncodingException 
 	 */
-	private ArrayList<String> browseTSQ(String tsqName) throws CicsConditionException, UnsupportedEncodingException {
-		// An ArrayList to hold all of the items read from TSQ to be returned to the servlet.
-		ArrayList<String> records = new ArrayList<String>();
+	private ArrayList<String> readTSQ(String tsqName) throws CicsConditionException 
+	{
+		// An ArrayList to hold all of the items read from the TSQ
+		ArrayList<String> tsqItems = new ArrayList<String>();
 
-		// construct a JCICS representation of the TSQ object
-		TSQ tsqQ = new TSQ();
+		// Create a JCICS representation of the TSQ object
+		TSQ tsqQ = new TSQ();			
 		tsqQ.setName(tsqName);
 
-		// the holder object will hold the byte array that is read from the TSQ
+		// Create a holder object to store the byte array representing a tsq item
 		ItemHolder holder = new ItemHolder();
 
-		// initialize loop variables
+		// initialise item position
 		int itemPos = 1;
-		int totalItems = 0;
-		String recordStr = null;
-
-		// read an item and store the total number of items on the queue
-		totalItems = tsqQ.readItem(itemPos, holder);
-
-		// get string from the holder byte[] -  defaults to using EBCDIC encoding of CICS region
-		// then add the record to the ArrayList to be returned
-		recordStr = holder.getStringValue();		
-		records.add(recordStr);
 
-		// iterate over the remaining items and add  to the ArrayList
-		while (itemPos < totalItems) {
-			tsqQ.readNextItem(holder);
-			recordStr = holder.getStringValue();
-			records.add(recordStr);
+		// read the first item into the holder (and get the total number of items on the queue)
+		int totalItems = tsqQ.readItem(itemPos, holder);
+		
+		// add the string representation of the tsq item to the ArrayList
+		// getStringValue() - uses the default EBCDIC encoding of CICS region
+		tsqItems.add(holder.getStringValue());
+
+		// iterate over, and add, the remaining items to the ArrayList
+		while (itemPos < totalItems) 
+		{
+			tsqQ.readNextItem(holder);			
+			tsqItems.add(holder.getStringValue());
 			itemPos++;
 		}
 
-		// return the arraylist containing the records from the TSQ
-		return records;
+		// return the Arraylist containing the records from the TSQ
+		return tsqItems;
 	}
 }

src/main/java/com/ibm/cicsdev/springboot/jcics/DeleteTSQController.java

@@ -8,60 +8,38 @@
 /* restricted by GSA ADP Schedule Contract with IBM Corp                  */
 /*                                                                        */
 
-
 package com.ibm.cicsdev.springboot.jcics;
 
-import java.io.IOException;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 import com.ibm.cics.server.CicsConditionException;
 import com.ibm.cics.server.TSQ;
 
 @RestController
-public class DeleteTSQController {
-
+public class DeleteTSQController 
+{
 	/**
 	 * The @GetMapping annotation ensures that HTTP GET requests are mapped to the annotated method. 
 	 * @throws IOException 
 	 **/
-	@GetMapping("/deleteTSQs")
-	public String deleteTSQs(@RequestParam(value = "tsqName", defaultValue = "ANNE") String tsqName) {
-
-		String response = "";
-
+	@GetMapping("/delete")
+	public String deleteTSQ(@RequestParam(value = "tsq", defaultValue = "ANNE") String tsqName) 
+	{
 		// Delete the TSQ
-		try {
-			response = deleteTSQ(tsqName);
-		} catch ( CicsConditionException e) {
-
-			// Print the stack trace
+		try 
+		{
+			// perform the delete of the TSQ and return success result			
+			TSQ tsqQ = new TSQ();
+			tsqQ.setName(tsqName);
+			tsqQ.delete();
+			return "TSQ " + tsqName + " successfully deleted.";
+		} 
+		catch ( CicsConditionException e) 
+		{
+			// Return error details
 			e.printStackTrace();
-
-			// Return useful information to the user when meeting errors
-			return "Oops! Unexpected CICS condition exception: "  + e.getMessage() + ". Please check stderr for details.";
+			return "Unexpected CICS condition exception: "  + e.getMessage() + ". Check dfhjvmerr for further details.";
 		}		
-
-		return response;
-	}
-
-	/**
-	 * A method to delete a TSQ.
-	 * 
-	 * @param tsqName, the name of the TSQ to be deleted 
-	 * @return, a message describing the outcome of the action
-	 * @throws CicsConditionException
-	 */
-	private String deleteTSQ(String tsqName) throws CicsConditionException {
-
-		// construct the TSQ object
-		TSQ tsqQ = new TSQ();
-		tsqQ.setName(tsqName);
-
-		// perform the delete
-		tsqQ.delete();
-
-		// return the result of the delete action to the calling servlet
-		return "TSQ " + tsqName + " successfully deleted.";
 	}
 }

src/main/java/com/ibm/cicsdev/springboot/jcics/InfoTSQController.java

@@ -0,0 +1,61 @@
+/* Licensed Materials - Property of IBM                                   */
+/*                                                                        */
+/* SAMPLE                                                                 */
+/*                                                                        */
+/* (c) Copyright IBM Corp. 2020 All Rights Reserved                       */
+/*                                                                        */
+/* US Government Users Restricted Rights - Use, duplication or disclosure */
+/* restricted by GSA ADP Schedule Contract with IBM Corp                  */
+/*                                                                        */
+
+package com.ibm.cicsdev.springboot.jcics;
+
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import com.ibm.cics.server.ItemHolder;
+import com.ibm.cics.server.TSQ;
+
+@RestController
+public class InfoTSQController 
+{	
+	/**
+	 * The @GetMapping annotation ensures that HTTP GET requests are mapped to the annotated method. 
+	 * @throws IOException 
+	 **/
+	@GetMapping("/info")
+	public String infoTSQ(@RequestParam(value = "tsq", defaultValue = "ANNE") String tsqName) 
+	{
+		// Create a JCICS representation of the TSQ object		
+		TSQ tsq = new TSQ();
+		tsq.setName(tsqName);
+		
+		// obtain some information about the TSQ
+		String name = "<name>" + tsq.getName() + "</name>";
+		String type = "<type>" + tsq.getType() + "</type>";
+		String lenStr = "<length>" + getTSQLength(tsq) + "</length>";
+
+		return "The current TSQ information is: " + "Name: " + name + ", Type: " + type + ", Length: " + lenStr;			
+	}
+	
+	
+	/**
+	 * A method to get the number of items (length) of the TSQ. 
+	 * @return, the number of items on the TSQ or associated error code.
+	 */
+	public int getTSQLength(TSQ tsq) 
+	{		
+		// Read the first item to get the length of the queue
+		try 
+		{
+			return tsq.readItem(1, new ItemHolder());
+		} 
+		catch (Exception e) 
+		{			
+			e.printStackTrace();
+			return -1;
+		} 		
+	}
+
+}

src/main/java/com/ibm/cicsdev/springboot/jcics/RootController.java

@@ -0,0 +1,19 @@
+package com.ibm.cicsdev.springboot.jcics;
+
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+
+@RestController
+public class RootController 
+{
+    
+        /**
+        * Provide a root URL for usage: information  
+        **/
+        @GetMapping("/")
+        public String root() 
+        {                        
+            return "Spring Boot JCICS REST sample usage: /browse{tsq=name}, /write{tsq=name&item=content}, /info{tsq=name}, /delete{tsq=name}";
+        }    
+}

src/main/java/com/ibm/cicsdev/springboot/jcics/ServletInitializer.java

@@ -13,11 +13,11 @@
 import org.springframework.boot.builder.SpringApplicationBuilder;
 import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;
 
-public class ServletInitializer extends SpringBootServletInitializer {
-
+public class ServletInitializer extends SpringBootServletInitializer 
+{
 	@Override
-	protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
+	protected SpringApplicationBuilder configure(SpringApplicationBuilder application) 
+	{
 		return application.sources(Application.class);
 	}
-
 }