After creating business services locally, or downloading them from an existing server installation, you can create Java clients and/or Web services for the services. This section covers the following topics:
Using the Generate Java Client wizard, you can develop Java client applications that access Natural Business Services server components via dynamic RPC. The wizard creates Java clients from Natural Business Services objects in a NaturalONE project and then generates the Java client interface objects used by the Java client to access the server components.
To generate a Java client:
Open the context menu for the business service in the Navigator view (i.e., the BusinessServiceName.bsrv file).
Select .
The Configure Generated Class panel is displayed. For example:
Using this panel, you can:
| Task | Procedure |
|---|---|
| Generate a Web service file (file with a .aar extension). | Select Generate Web Service (.aar) file. The Web service file will be created when the class is generated. |
| Deploy the generated Web service to a WS-Stack runtime environment. | See Deploy a Generated Web Service. |
| Suppress the generation of a JUnit test file containing test functions that correspond to each method in the business service. | Deselect Generate JUnit test
file.
Note: |
| Redesign the interface for Natural subprograms, such as changing the default IDL directions or selecting which portions of a redefined field to use. | See Redesign the Interface. |
Type the name of the source folder in Source folder or select to browse for a folder.
If you select a project as the source folder, the wizard will automatically create and use <projectname>/Java/src as the source folder. In addition, the wizard will set the output/compilation folder to the bin folder corresponding to the source. For example, if the source folder is set to Java/src, then the output/compilation folder will be set to Java/bin.
Note:
The folder must currently exist.
Type the name of the package in Package name or select to browse for a package.
The package does not have to currently exist.
Select to generate the Java class.
The class and associated files are displayed in the Navigator view. For example:
In this example, the following items were generated in the Calculator node:
| Item Generated | Description |
|---|---|
| Calculator node in src | Java package. |
| CalculatorData.java | Java class containing the PDA for the business service, which is mapped to Java. This class has the same name as the business service and a suffix of "Data". |
| CalculatorService.java | Java class containing the code that communicates with the business service, as well as the Add method. This class has the same name as the business service and a suffix of "Service". |
| CalculatorServiceTest.java | JUnit class with the same name as the
CalculatorService.java class
and a suffix of "Test". For more information, see
Test the Java
Class.
Note: |
| nbs.properties file | A .properties file for the business service. For more information, see Set the nbs.properties File to Run a Dynamic RPC Java Class. |
| log4j-1.2.15.jar file in lib | Library containing the logging functionality. |
| wrappercore.jar file in lib | Library containing the helper classes and functionality for the generated Java class. |
The business service class is displayed in the editor view. For example:
To display the JUnit class, select the CalculatorServiceTest.java tab. For example:
Note:
This file is only generated when the Generate JUnit test
file option is selected.
To display the properties file for the business service, select the nbs.properties tab. For example:
This section covers the following topics:
This section describes how to deploy a generated Web service to a WS-Stack runtime environment.
Note:
To use this option, you must first select Generate Web
Service (.aar) file on the Configure Generated
Class panel.
To deploy a generated Web service:
Select Deploy the generated Web Service.
Select .
The Deploy NaturalONE Web Service panel is displayed. For example:
This panel displays the default parameters for the WS-Stack runtime environment running in the default Tomcat servlet engine. The default user credentials are also displayed (these can be changed at first logon).
Confirm the name and location of the WS-Stack runtime environment.
Confirm the user credentials.
Select .
For more information on deploying a Web service or changing logon credentials, refer to the Web Services Stack documentation.
This section describes how to redesign the interface generated for a Java client.
To redesign the interface:
Select Redesign the interfaces on the Configure Generated Class panel.
Select .
The Design Interface for Natural Subprogram panel is displayed. For example:
The upper left pane on this panel displays the parameters for the Natural subprogram and allows you to select operations (for example, Map to In, Map to Out, Map to InOut, or Suppress). The upper right pane displays the IDL directions that will be inserted as top-level parameters (level 1) in the interface definition for the Natural subprogram. The bottom pane is used for reference purposes; it displays the Natural subprogram source and its PDA sources, each in a separate tab.
Tip:
To reserve more space for viewing the upper panes, you can close
the bottom pane when it is not needed.
Using this panel, you can:
| Task | Procedure |
|---|---|
| Define the direction of parameters in the interface. | See Define the Direction of Parameters. |
| Select which portions of redefined fields in the PDA to use. | See Select Portions of Redefined Fields. |
| Hide or suppress unneeded parameters in the interface. | See Suppress Parameters. |
Select .
If you selected multiple Natural subprograms, you can now redesign the next interface. The current and total number of subprograms designed so far is indicated in the title (for example, 2/3).
Note:
For more information about using this panel, refer to the
EntireX documentation.
This section describes how to change the default IDL directions for the generated Java client.
To define the direction of parameters:
Expand the INPUT-OUTPUT and OUTPUT nodes in the upper left pane of the Design Interface for Natural Subprogram panel.
For example:
Note:
Natural parameters that are mapped in the interface are marked
with a green circle.
Open the context menu for the first level 1 parameter you want to define.
Select one of the following options:
Map to In
Map to Out
Map to InOut (the default direction, if no other direction is specified)
The operation is reflected in the IDL Library pane.
Continue defining level 1 parameters as desired.
Select .
This section describes how to select which parameters redefined in the Natural PDA are used in the interface.
To define which portions of a redefined field to use:
Expand the INPUT-OUTPUT and OUTPUT nodes in the upper left pane of the Design Interface for Natural Subprogram panel.
For example:
Redefined fields are identified by the
icon.
Open the context menu for the REDEFINE base parameter or any REDEFINE path.
Select .
Select .
This section describes how to suppress unnecessary parameters, which creates a less cluttered IDL client interface and minimizes the amount of data transferred at runtime.
To suppress parameters in the interface:
Open the context menu for the parameter in the upper left pane.
Select .
Select .
Natural parameters suppressed in the interface are displayed in italic type.
You can set the nbs.properties file to run a dynamic RPC Java class. The settings to run the Java class are loaded by the NBSSettings class. This class will try to find the nbs.properties file using the following search order:
nbs_properties Java system property pointing to the file
nbs_properties environment variable pointing to the file
class loader for NBSSettings
class loader for context for current thread
The entries in the nbs.properties file are:
| Setting | Description | Default |
|---|---|---|
| broker.id | Broker connection ID. | localhost:1971 |
| broker.service | Broker service endpoint. | RPC/SRV1/CALLNAT |
| user.id | User ID to use with Broker. | GUEST |
| password | Password to use with Broker. | blank/empty string |
For example:
broker.id=BKR13003:4010 broker.service=RPC/NBS53DEV/CALLNAT user.id=PWRUSR password=
Note:
If the generated code will be used in AXIS2, you must copy the
nbs.properties file to the
<WebApp>/classes folder.
 |
Warning: For security reasons, it is recommended that the password not be set in the nbs.properties file. It is much more secure to set the Broker credentials programmatically. |
Both the user.id and password properties
can use a Java class suffix (for example, package.MyService), which allows the
client to use different user IDs and passwords for different services and/or
groups of services. For example:
user.id.package.name.MyService=USERIDA password.package.name.MyService-PWDA user.id.package.name=USERIDB password.package.name=PWDB user.id=PWRUSR password=
When the MyService Web service in the
package.name Java package is invoked, the USERIDA
user ID and PWDA will be used. When any other service within the
package.name Java package is invoked, the USERIDB
user ID and PWDB password will be used. All other services will
use the PWRUSR user ID and no password.
The generated Java classes support log4j logging statements for advanced diagnostics at runtime. If logging is being used, there is the potential for data to be visible in the log files produced in the runtime environment. To avoid this problem, configure the com.softwareag.naturalone.gen.dynamicrpc.core logger file to only display warnings and above. For example:
log4j.logger.com.softwareag.naturalone.gen.dynamicrpc.core=WARN
When you select Generate JUnit test file on the Configure Generated Class panel before generating the class, a JUnit class is also generated. This class contains test functions that correspond to each method in the business service. For example:
@Test
public void testAdd() throws Exception {
Calculator service = createService();
CalculatorData data = new CalculatorData();
//TODO populate data
CalculatorData result = service.add(data);
Assert.assertNotNull("Result is null", result);
//TODO check result
}
//TODO comments have been added in the source to indicate where additional information is added for the test. By default, the test succeeds if no errors occur during the call to the business service and if data is returned.
Data can be added before the service method is invoked. For example:
//TODO populate data data.getCalcInput_data().set_first_num(new BigDecimal(2)); data.getCalcInput_data().set_second_num(new BigDecimal(2));
In addition, an assert clause can be included to verify that the result is correct. For example:
//TODO check result Assert.assertEquals(new BigDecimal(4), result.getCalcOutput_data().get_result());
Tests can be invoked using standard Eclipse JUnit functionality (i.e., run as Junit test). The environment for the test is contained in this function in the test file. For example:
private Broker createBroker() throws BrokerException {
String userID = "GUEST";
String password = "";
Broker broker =
new Broker(Demotest.DEFAULT_BROKERID, userID,
Demotest.DEFAULT_SERVER);
broker.logon(password);
return broker;
}
After generating a Java class, you can write an application that uses the class to invoke a business service. Use the following code as a template for writing the application; read the comments for additional information:
// Create the EntireX Broker object
Broker b = new Broker("localhost:1971","GUEST");
// Create the service class.
Calculator calcservice = new Calculator(b, "RPC/SRV1/CALLNAT");
// Create the service data class
CalculatorData calcdata = new CalculatorData();
// Set input values for the call
calcdata.getCalcInput_data().set_first_num(new BigDecimal(2));
calcdata.getCalcInput_data().set_second_num(new BigDecimal(2));
calcdata.getCalcInput_data().set_function("Add");
// Invoke a service method, passing in the data class
// make sure to catch any errors that might happen.
CalculatorData calcresult = null;
try {
calcresult = calcservice.add(calcdata);
} catch (DataException e) {
e.printStackTrace();
} catch (BrokerException e) {
e.printStackTrace();
} catch (ServiceException e) {
e.printStackTrace();
}
// Examine the result
System.out.println("Result is:"
+ calcresult.getCalcOutput_data().get_result());
Using the Generate Java Client wizard, you can generate a Web service from business service object in a NaturalONE project. The generated Web service objects are WS-Stack Web service archive files (files with a .aar extension) and can be deployed in a Web services Stack runtime environment and registered in CentraSite. Web service client applications can then access these Web services and expose business logic implemented by the Natural server components.
To generate a Web service:
Open the context menu for the business service in the Navigator view (i.e., the BusinessServiceName.bsrv file).
Select .
The Configure Generated Class panel is displayed. For example:
Using this panel, you can:
| Task | Procedure |
|---|---|
| Change the source folder in which to generate the Java class. | Type the name of the source folder in Source folder or select to browse for an existing project. The folder must currently exist. |
| Change the name of the Java package or select another package. | Type the name of the Java package in Package name or select to browse for an existing package. The package does not have to currently exist. |
| Suppress the deployment of the generated Web service to a WS-Stack runtime environment. | Deselect Deploy the generated Web Service. |
| Register the Web service after it has been generated and deployed. | Select Register the generated and
deployed Web Service.
Note: |
| Suppress the generation of a JUnit test file containing test functions that correspond to each method in the business service. | Deselect Generate JUnit test
file.
Note: |
Select .
The Deploy NaturalONE Web Service panel is displayed. For a description of this panel, see Deploy a Generated Web Service.
Select to generate the Java class for the Web service.
All generated services extend "com.softwareag.naturalone.gen.dynamicrpc.core.AbstractService". The default constructor for the generated service determines which Broker credentials to use based on the following rules:
When WS-Security is turned on and the credentials are passed in the SOAP header, they will be used in the call to Broker.
In all other cases, the settings in the nbs.properties file will be used. For information, see Set the nbs.properties File to Run a Dynamic RPC Java Class.
To configure a Web service to use WS-Security:
Open the context menu for a business service in the Navigator view.
Select .
The Configure Generated Class panel is displayed. For example:
Deselect Deploy the generated Web Service.
Select .
The generated Web service files are displayed in the Navigator view. For example:
Open the generated .aar file in the editor view.
Select the Services tab.
Select Enable WS-Security in the Modules section.
The settings in the Security section are displayed. For example:
Select the following settings.
no Binding
User Name Token (in the Token Assertions group).
Save the changes to the .aar file.
Open the context menu for the .aar file.
Select .
The Deploy Your Web Services panel is displayed. For a description of this panel, see Deploy a Generated Web Service.
On the client, the following SOAP header must be included with the correct credentials specified:
<soapenv12:Envelope xmlns:soapenv12="http://www.w3.org/2003/05/soap-envelope">
<soapenv12:Header>
<wsse:Security xmlns:soapenc12="http://www.w3.org/2003/05/soap-encoding"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
>
<wsse:UsernameToken>
<wsse:Username>MyUser</wsse:Username>
<wsse:Password>MyPassword</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv12:Header>
<soapenv12:Body>
Note:
Since user credentials will be included in the SOAP header, it is
highly recommended that you use HTTPS. For instructions on how to configure
AXIS2 to use HTTPS, refer to the AXIS2 documentation.