This article is intended to demonstrate one way of creating a service from a COBOL paragraph.
The examples presented here are intentionally simplified in order to show techniques rather than all the complexity that may be involved with different data types, additional dependencies, etc.
The goal of this article is to guide you on how to place a java based facade around the 'GET-RECORD' paragraph and then call the original logic, via the facade from a new java class.
The objective being demonstrated is to be able to make use of existing logic as a new service when you intent to continue to maintain that code in its original language.
Future articles will show you how to take that facade and deploy it in a serverless environment, calling it as a scalable service.
This article assumes you have a working Eclipse and Heirloom environment, appropriate licenses, and have completed the Heirloom online training to ensure you are familiar with the Heirloom SDK.
It also assumes you have a working postgres database with the account demo records and an automatically generated view in it. If you do not, you can use our example read only database specified in the config files and sample code attached to this article.
If you have already completed the refactoring example here you can skip the steps to create an example project if you still have that workspace and project.
Steps to create an example project
1. Right-click in the Project Explorer to create a new COBOL project in Eclipse:
2. Name the project 'ACCTONE':
3. The 'Default Project' project type is fine, so just click 'Finish':
4. Right click the project and choose 'Properties' from the context menu:
5. Select 'COBOL Compiler Settings' on the left and choose 'Parsing' in the Category drop-down on the right:
6. Change the 'Dead Code Analysis' option to 'Comment generated Code' and click 'Apply and Close' and then 'Yes' to allow a full build to happen:
7. Copy the COPYBOOKS (ACCTREC.cpy and R-ACCTREC.cpy) attached to this article into the copylib folder. You may either drag and drop the COPYBOOK files from your download folder into the copylib folder in Eclipse, or copy it from your download folder, right-click the copylib folder in Eclipse and paste it from the context menu:
8. Copy the resource (postgresql-9.4.1209.jar) attached to this article into the resources folder. Copy it from your download folder, right-click the resources folder in Eclipse and paste it from the context menu:
9. Right click the postgresql-9.4.1209.jar and choose 'Build Path->Add to build path' in the context menu:
10. Copy the resource (cblconfig) attached to this article into the resources folder. Copy it from your download folder, right-click the resources folder in Eclipse and paste it from the context menu. cblconfig is used to tell the Heirloom Framework it should expect to find the ACCTFIL file as a VDB table named 'acctfil'. if your table is a different name, edit the file and rename the table:
11. Copy the resource (deploy_settings) attached to this article into the resources folder. Copy it from your download folder, right-click the resources folder in Eclipse and paste it from the context menu:
12. Double click the deploy_settings file to open it in the editor, modify the URL,user, and password for the connection to your database, then save the file using the 'File->Save' menu option:
13. Copy the COBOL program (ACCTONE.cbl) attached to this article into the cobol_source folder. You may either drag and drop the COBOL file from your download folder into the cobol_source folder in Eclipse, or copy it from your download folder, right-click the cobol_source folder in Eclipse and paste it from the context menu.
Ensure you have 'Build Automatically' turned on for your project as this will create Java code in the intermediate_java_code folder. If it was not turned on, turn it on in the Project menu:
14. Double click the ACCTONE.cbl program to open it in the editor, then right click anywhere in the code and choose 'Run As->COBOL Application' from the context menu:
15. The application expects a record number as input so enter the record number 10023 in the console window and press enter:
16. The results from the program should look like this (your values may be different):
17. You will note by studying the code that the input value is used in GET-RECORD to read the record from the database. The Main paragraph calls GET-RECORD to retrieve the data and then displays it. Once the program executes successfully you are ready to facade the GET-RECORD paragraph and call it from new code.
Facading the GET-RECORD paragraph
The following steps show you how to use the Heirloom facade wizard to wrap the existing code with a facade. It should be noted that this is one method of doing this. The code produced could also be written by hand and in several ways. The advantage of the facade wizard is that it will produce boilerplate code that knows how to invoke the underlying code, set up a transaction environment if required, and read a properties file to set up any required prerequisites like SQL connections since the code will be running from a pure java starting state.
18. Select the GET-RECORD paragraph name in ACCTONE.CBL:
19. Right click the selection and choose 'Facade Factory':
20. Enter 'getBalance' as the class name and click 'Next':
21. Select 'WS-PARM' as the input field,click the single '>' chevron and then click 'Next':
22. Select 'R-PAY-1-BALANCE OF R-PAY1 OF..' as the output field, click the single '>' chevron and then click 'Next':
23. Click 'Finish' to create the getBalance.java in java_source and getBalance.properties in 'workdir':
The wizard creates a default properties file for you but you'll need to move it to the correct folder, and modify it for your specific database settings.
24. Open the getBalance.properties file by double clicking it:
25. Replace the contents of the wizard with the contents of the file 'example.properties' attached to this article:
26. Open the getBalance.java class by double clicking it and scroll to the end of the code:
27. Replace the 'facade' in the path of the properties file with 'workdir' then save the code:
Calling the facade from new Java code
The following steps show you how to call the facade from Java. Once this is done you'll see how easy it is to can take the facade, the original code it calls, and your property (configuration) file and deploy that in any service that needs to call it. Future articles show how to do this as an orchestrated Lambda service in AWS.
28. Copy the getBalanceTest.java attached to this article into the java_source folder. Copy it from your download folder, right-click the java_source folder in Eclipse and paste it from the context menu:
29. Double click the file 'getBalanceTest.java' to open it in the editor window:
30. Right click anywhere in the code and choose 'Run As->Java Application' from the context menu:
31. The results from the program should look like this (your values may be different):
32. By modifying the input parameter (10021) you can Save and then rerun the program to see different account balances:
Examination of the facade code
Remember the facade code is just an example. You could write this code yourself once you understand the techniques involved, or provide your own factory to produce these for many paragraphs and services.
If you examine the facade code (getBalance.java) you'll see that it has a private object representing the original code class (acctone) called pgmInstance :
It will use this object to instantiate that class , set inputs and call the underlying code. It will also use it retrieve outputs as we'll see further below:
When the facade class is instantiated it loads the properties from your getBalance.properties class to make them available to the Heirloom environment. This is one way of picking up properties - there are many ways to set them and make them available:
The facade will then create a new instance of the acctone class and if required set up a transaction environment for the Heirloom framework to use. This is what the constructor looks like:
There are two methods created based on the inputs and outputs you selected when running the Facade Factory wizard:
setInputParams takes a list of variables and sets the variables of the pgmInstance class to them. These are typically working storage or linkage items but this is simply java object assignment so you could modify this method to pass anything you wish to the acctone class.
The getOutputs method takes each of the outputs you specified and puts them into a map, using the name of the output as the key. This method could be changed to make those map keys more end-developer friendly, turned into getters and setters instead of a Map or several other methods. The Map is provided as a simple example to show how the outputs are returned.
Finally the invokeService method calls the method in the acctone class that represents the PARAGRAPH the facade was built for, in this case the GET-RECORD paragraph in the MAINLINE section:
Examination of the test program code
If you study getBalanceTest.java you'll see it uses standard java techniques to instantiate the facade class, call it's method to set the input data, and then calls the invokeService() method which runs the original code logic. It then retrieves the output we're interested in from the Map:
It should be noted that this code could call the original underlying code using the same technique - that's ultimately what the facade does. The facade is there to make it easier for end developers to use the original code since it provides a layer of indirection where original variable names and functions can be hidden. It is however only one such method of doing so and should be taken as an example, not the only solution.
Finally this code formats the return balance into a more friendly format than the original COBOL output, and displays it:
This article demonstrates one way of facading an existing paragraph and calling it from new Java code
This technique may be used when you intend to continue to maintain and develop the code logic in its original COBOL form, but also wish to be able to deploy parts of the code as micro or macro services.
As such, it demonstrates the flexibility and agility of the Heirloom Framework in allowing targeted, progressive reuse of existing application logic in new applications and processes.
Other methods include refactoring the original Java code produced by the compiler or rewriting the module entirely as a new service. Those examples are outside the scope of this article but provide their own advantages and disadvantages. The choice of them and this example will depend on the usage and requirements of each module and logic being targeted for a rewrite.