Developing Client Proxy Classes and Web Services

Developing Client Proxy Classes and Web ServicesThis section describes how to develop client proxy classes and Web services. The following topics arecovered:

Generate a Client Proxy Class

Customize a Generated Client Proxy Class

Use the Generated Client Proxy Classes

Generate log4j Log Statements

Generate a Client Proxy ClassYou can use the Natural Business Services Eclipse plug-in to create proxy classes in Java. Client proxyclasses provide access to business services running in Natural. The generated classes are plain Javaclasses. Typically, proxy classes have properties and methods that map to their Natural counterparts.

Note:This procedure differs, based on whether the target Java Virtual Machine (VM) is original or enhanced.

During generation, the wizard creates a folder called .nbsMetadata containing the specifications for theJava class. This allows the specifications to be associated with a project rather than a workspace. Themetadata can be stored in CVS, as well as exported with the project.

Note:A Java project must currently exist. For information, refer to the Eclipse documentation.

This section covers the following topics:

Java Original

Java Enhanced

Deploy the Client Proxy Class as a Web Service Class

Java Original

This section describes how to generate a client proxy class for Java Virtual Machine (VM) version 1.4.

Note:For information on setting the VM version, see Preferences for Java Classes.

To generate a client proxy class for Java original:

1. Open the context menu for a business service in the NBS Repositories view.

1

Developing Client Proxy Classes and Web ServicesDeveloping Client Proxy Classes and Web Services

2. Select Create class.

The Configure generated class panel is displayed. For example:

This panel displays the default configuration settings for the class to be generated. Optionally, youcan:

2

Java OriginalDeveloping Client Proxy Classes and Web Services

Task Procedure

Change the project folder Select a new root source folder in Project folder.

Change the package name Select a new package in Package name.

Change the scope of the classSelect the class scope from Class scope. By default, public isthe class scope.

Rename the class Enter a new name in Class name.

Create a class that can be runin the JUnit testing framework

Select Generate JUnit test class. This test class will containdefault tests for each method used by your business service. Thename of the file used to store the test is displayed in Test file name.

Create additional Web servicedeployment files and classes

Select Generate Web service class and enter the Web serviceclass name and .aar file name. For more information, see Deploythe Client Proxy Class as a Web Service Class.

Rename the Web service Enter a new name in Web service name.

Refresh metadata from the server

Select Retrieve metadata from server.

3. Select Next.

The wizard downloads metadata from the service repository on the server and displays the Ready to generate panel. For example:

3

Developing Client Proxy Classes and Web ServicesJava Original

Use this panel to customize the methods and data parameters your class will support. The Methodstab allows you to customize how class methods will be generated based on your existing business servicemethods.

4. Select the Data tab.

For example:

4

Java OriginalDeveloping Client Proxy Classes and Web Services

The Data tab allows you to customize how Get and Set methods for your business service propertieswill be generated.

5. Select Finish to generate the client proxy class.

Java Enhanced

This section describes how to generate a client proxy class that takes advantage the enhanced features ofJava Virtual Machine (VM) version 5. These features include:

5

Developing Client Proxy Classes and Web ServicesJava Enhanced

Try/Catch statements that throw exceptions for server errors when calling business service methodsfor a class

Method definitions that include the correct input/output parameters based on the style of businessservice

Note:For information on setting the VM version, see Preferences for Java Classes.

To generate a client proxy class for Java enhanced:

1. Open the context menu for a business service in the NBS Repositories view.

2. Select Create class.

The Configure generated class panel is displayed. For example:

6

Java EnhancedDeveloping Client Proxy Classes and Web Services

This panel displays the default configuration settings for the class to be generated. Optionally, youcan:

7


Task Procedure

Change the project folder Select a new root source folder in Project folder.

Change the package name Select a new package in Package name.

Change the scope of the classSelect the class scope from Class scope. By default, public isthe class scope.

Rename the class Enter a new name in Class name.

Copy the field structure asdefined in the PDAs generatedfor the business servicesubprograms

De-select Auto detect class design. If this option is selected,the wizard will determine which model to use when generatingthe subprograms on the server and design an object classhierarchy that is appropriate for the model. For example, thegenerated Get method will accept the primary key as input andreturn an object that includes all fields.

The wizard recognizes subprograms generated by theObject-Maint-Subp, Object-Browse-Subp, andObject-Browse-Select-Subp models.

Create a class that can be runin the JUnit testing framework

Select Generate JUnit test class. This test class will containdefault tests for each method used by your business service. Thename of the file used to store the test is displayed in Test file name.

Create additional Web servicedeployment files and classes

Select Generate Web service class and enter the Web serviceclass name in Service class name. For more information, see Deploy the Client Proxy Class as a Web Service Class.

Rename the Web service Enter a new name in Web service name.

Refresh metadata from serverSelect Retrieve metadata from server.

3. Select Next.

The wizard downloads metadata from the service repository on the server and displays the Customize Generated Class panel. For example:

8


Use this panel to design how each method will work when generating Java classes for services thatwere not generated by Natural Construct models.

4. Expand a method listed in Methods.

5. Open the context menu for Parameters.

For example:

9


6. Select Add Parameter.

The parameter settings are displayed. For example:

10


Use this panel to add a parameter to the method and bind it to an existing field in the service.Optionally, you can:

Task Procedure

Provide an index value for theNatural field

Type the value in Index.

Bind the parameter to an inner class

Select Class and specify the class.

Select the return value for a method

Select the method (for example, Add) and specify the returnsettings. For information, see Select Return Value for a Method.

7. Type the name of the parameter in Name.

11


8. Select the Natural field in Bind to field.

9. Select Finish to generate your classes and files.

The new class is displayed in the program editor view.

Select Return Value for a Method

To select the return value for a method:

1. Select a method listed in Methods.

Information about the method is displayed. For example:

12


This panel displays the name of the method on the client and on the server, as well as the scope(public or private) and description of the method. Optionally, you can:

Task Procedure

Change the name of the method

Type a new name in Name.

Change the scope of the method

Select the new scope in Scope.

Remove the option to verifythe result

De-select Check result.

Change the description of the method

Type a new description in Description.

13


2. Select one of the following binding options for the return value:

Bind to field

To bind the return value to a field, select the field and, optionally, provide an index value.

Bind to class

To bind the return value to an inner class, select the class.

For example, if you select Bind to field and OUTPUT-DATA.#RESULT, the Add method changes from:

public void Add() throws BusinessServiceException

to:

public double Add(double firstNum, double secondNum) throws BusinessServiceException

Deploy the Client Proxy Class as a Web Service Class

When generating a client proxy class, one of the wizard options generates a class and descriptor files todeploy the client proxy class as a Web service class. Web service deployment is handled by the WS-Stackplug-in. For information about this plug-in, refer to http://rndcvweb.eur.ad.sag/Projects/WSS/Kits/.

Note:To deploy the client proxy class as a Web service class, Generate Web service class must be selected onthe Configure Generated Class panel.

This section covers the following topics:

Add CentraSite Associations Deploy to an Internal Axis Server Deploy to an External Application Server Override the Generated Connection Settings

Add CentraSite Associations

The WS-Stack plug-in will not add an association between a Web service being added to CentraSite andthe NBS repository metadata in CentraSite. You must add each association manually.

To add associations to CentraSite:

1. Open the context menu for the .aar file in the Package Explorer view.

2. Select Business Services > Add CentraSite association.

The CentraSite Connection window is displayed. For example:

14

Deploy the Client Proxy Class as a Web Service ClassDeveloping Client Proxy Classes and Web Services

Use this window to add up to two associations between a Web service and the NBS repositorymetadata to CentraSite. These associations are:

Association Description

Service uses business serviceAssociation between the Web service and its correspondingNBS business service metadata (for example,CalculatorClassWS Uses DEMO.Calculator.v1.1.1).

Business service has parent domain

Association between the NBS business service metadata and itscorresponding NBS domain metadata (for example,DEMO.Calculator.v1.1.1 HasParent DEMO).

3. Confirm the connection details.

4. Type the CentraSite password in Password.

15

Developing Client Proxy Classes and Web ServicesDeploy the Client Proxy Class as a Web Service Class

5. Select the associations you want to add.

6. Select Finish.

The selected associations are added to CentraSite.

Deploy to an Internal Axis Server

The Web service can be deployed to an internal Axis server. The internal server will use your PC name asthe web server name.

To deploy to an internal Axis server:

1. Open the context menu for the .aar file in the Package Explorer view.

2. Select Business Services > Internal Axis Deploy.

The deployed service is displayed in the Internal Web Browser view. For example:

16

Deploy the Client Proxy Class as a Web Service ClassDeveloping Client Proxy Classes and Web Services

Deploy to an External Application Server

The Web service can be deployed to an external application server. This functionality is handled by theWS-Stack plug-in. For information, refer to http://rndcvweb.eur.ad.sag/Projects/WSS/Kits/.

Before you can deploy the Web service, you must prepare the application server.

To prepare the application server for Web service deployment:

Copy the NBSAxis2.war file to the ..\tomcat\webapps\Axis2 Install folder.

Note:While deploying a Web service, the wizard can generate debug log statements. For information, see Generate log4J Log Statements.

Tip:After making changes (such as changing the Java runtime version used by your classes and thenredeploying the class), you may have to restart the application server.

Tip:If an error occurs while deploying a service to an external application server, ensure that the Java versionrunning on the server is correct. To determine which version is running, open the context menu for yourJava project and select Properties. View the Java Build Path and verify the JRE system library setting.

17

Developing Client Proxy Classes and Web ServicesDeploy the Client Proxy Class as a Web Service Class

Override the Generated Connection Settings

When deploying a client proxy class as a Web service class, the Java Class wizard creates two files: the.aar file and the NBSConfigWS class. This class is responsible for creating the dispatcher and setting thecredentials used to communicate with the server. If desired, you can override the connection settingsgenerated into the NBSConfigWS class by overwriting the settings in the NBSAxis.properties file (locatedin C:\Documents and Settings\All Users\Application Data\Software AG\Natural Business Services\Configuration).

Customize a Generated Client Proxy ClassAfter generating a client proxy class, you can customize the code that was generated for a method or fieldused by the class. However, regeneration will overwrite your changes unless you place the followingannotation immediately preceding the customized code:

@NBSPreserve("")

The annotation preserves the code for that method or field only.

Note:Although providing a comment about the customization is optional, you must include the commentindicators (i.e., the brackets and quotation marks).

Use the Generated Client Proxy ClassesThis section describes the contents of the generated client proxy classes, how to execute the methods of aclient proxy, and how to use the Natural Business Services runtime client dispatcher. The following topicsare covered:

Contents of a Generated Client Proxy Class

Execute Methods of a Client Proxy Class

Use the Natural Business Services Runtime Client Dispatcher

Contents of a Generated Client Proxy Class

Generated client proxy classes have the following contents:

Init Method Methods Data

Init Method

This method contains a parameter called IRemoteCaller, which communicates with the server (it is alsocalled a client dispatcher). You must create an instance of a class that supports the IRemoteCallerinterface. Use the NBS runtime and ServiceFactory contained in the dispatchclient package to do this. Forexample:

18

Customize a Generated Client Proxy ClassDeveloping Client Proxy Classes and Web Services

import com.softwareag.nbs.bshelper.*;import com.softwareag.nbs.dispatchclient.*;

Config.getDispatchClientConfig("c:/eclipse/plugins/com.softwareag.nbs.ui_5.3.1/DispatchClient.config");IRemoteCaller dispatcher = ServiceFactory.createDispatcher("Default Broker");dispatcher.setUserID("GUEST");dispatcher.setPassword("");dispatcher.logon(); CalculatorClass bs = new CalculatorClass();bs.init(dispatcher);

Note:Although calling the dispatcher.logoff() method is not mandatory, it is recommended. Callingthe logoff method is important, especially with SPoD connections, as it releases server connections soonerrather than waiting for them to be released during garbage collection. Calling the logon method ismandatory.

When using the ServiceFactory to create an instance of IRemoteCaller, you must pass in the name of aconnection ID. For example:

IRemoteCaller dispatcher = ServiceFactory.createDispatcher("My Connection");

This is the name you specified when creating new connections in the NBS Repositories view. You mustalso load the configuration file using the getDispatchClientConfig method of the Config object. Forexample:

Config.getDispatchClientConfig("c:/My NBS Files/DispatchClient.config");

Methods

Each method in the class corresponds to a method in the business service.

Data

Each level 1 field from a PDA used in a business service becomes a Get/Set function of the class. Eachgroup within a PDA becomes a subclass. For example, if the following definition is specified:

01 Group1 02 Group2 03 Field1 (A10)

The following is generated in the client proxy class:

public class Group1 {

public class Group2 {

public String getField1() { return pda_inputData.getString("Field1",_ax); } }}

19

Developing Client Proxy Classes and Web ServicesContents of a Generated Client Proxy Class

Execute Methods of a Client Proxy Class

When executing a method of a client proxy class, use the BusinessServiceResult return value to check forcommunication and/or runtime errors. For example:

BusinessServiceResult bsr = businessSerivce.add(); // Invoke the add method.if (bsr.isSuccess()){ // Success}else{ String s = bsr.getDispatchResult().toString();}

If your business service was generated using code generation patterns, or it uses a standard error messageparameter group, verify whether business service errors or warnings are present. The msg field will alsocontain status messages. For example:

if (bs.getMessage().getReturnCode() == "E"){ String s = bs.getMessage().getMsg(); // Error, warning or status message Int I = bs.getMessage().getMsgNr(); // Error number}

Use the Natural Business Services Runtime Client Dispatcher

The runtime client dispatcher that uses the IRemoteCaller interface has properties and methods you canuse to provide additional functionality.

Set Security

When creating dispatcher objects, you must set the correct user ID and password to be used for remotecalls. For example:

dispatcher.setUserID("GUEST");dispatcher.setPassword("secret");

Use Transactions

You can invoke business services in a transactional context by using the startTransaction , commit , and abort methods. For example:

Service1 sv1 = new Service1Class();Service2 sv2 = new Service2Class();

IRemoteCaller dispatcher = ServiceFactory.createDispatcher("Default Broker");sv1.init(dispatcher);sv2.init(dispatcher);

dispatcher.startTransaction(); // Call methods of sv1 and sv2....// If successful callsdispatcher.commit();...// If an error in a methoddispatcher.abort();

20

Execute Methods of a Client Proxy ClassDeveloping Client Proxy Classes and Web Services

Note:To control transactions, the same dispatcher object must be used for each business service. For moreinformation, see the Java transaction example in the Samples folder. You can copy the Samples folderfrom the installation CD.

Generate log4j Log StatementsWhile creating a Java class and deploying a Web service to an external application server (for example,Apache Tomcat), the wizard can generate debug log statements into each Web service method thatcorresponds to a business service method.

Each Web service request is recorded in a log file with the following information:

Name of the Web service (unique identifier)

User ID (found in DispatchClient.config)

Timestamp indicating when the application server retrieves the Web service (Start of Request)

Timestamp indication when the Web service leaves the application server (End of Request)

Calculated time difference between the two timestamps (Request Elapsed Time)

To enable logging:

1. Edit the log4j.properties file.

This file is located in a subfolder in the \NBSAxis2\WEB-INF\classes folder where your applicationserver is running.

2. Add the following line:

log4j.logger.[package]=DEBUG, CONSOLE

where [package] is the Java package for your project containing the generated Java and Webservice classes. This will log all Web services in this package to the log file.

Tip:You can also include the class name after the package name, for example [package].[classnameWS] , which will enable logging for that class only.

3. Restart your application server.

Entries will be written to log files for standard output.

The log files use the following naming convention:

stdout_[date].log

These files are stored in different locations, depending on the application server you are using. (ForApache Tomcat, they are stored in the Logs subfolder in which Tomcat is installed.)

21

Developing Client Proxy Classes and Web ServicesGenerate log4j Log Statements

For more information, see:

Log4J manual: http://logging.apache.org/log4j/1.2/manual.html

Using Log4J from Tomcat: http://tomcat.apache.org/tomcat-5.5-doc/logging.html

22

Generate log4j Log StatementsDeveloping Client Proxy Classes and Web Services

http://logging.apache.org/log4j/1.2/manual.html

http://tomcat.apache.org/tomcat-5.5-doc/logging.html

Developing Client Proxy Classes and Web Services

Documents

Transcript of Developing Client Proxy Classes and Web Services