Deploying PowerBuilder Components to JBoss

 

The PowerBuilder Application Server Plugin (PASP) is a new product offering from Sybase. It's currently in beta as part of the EAServer 6.0 beta; however, when released it will be distributed as a separate product. The PASP allows PowerBuilder developers to deploy PowerBuilder components to third-party application servers (JBoss, WebSphere, WebLogic, etc.), much the same as they can with EAServer today. This is of particular importance in companies that have already standardized on a non-EAServer application server.

Another important feature of the new product is the proxy server. When PowerBuilder components are deployed to third-party application servers, they are given an EJB wrapper, the same way that they are wrapped when they're deployed to EAServer. That wrapper allows other components and other clients to access the components as if they were EJBs. A PowerBuilder client that wants to interact with an EJB must do so by configuring a local JVM and using the EJBConnection class to communicate with the component. PowerBuilder clients talking to EAServer don't have to do so to talk to PowerBuilder components because EAServer allows the PowerBuilder clients to talk directly to the PB components. The proxy server allows PowerBuilder clients to do the same thing with PowerBuilder deployed.

The method used to configure each application server that you want to deploy to is highly dependant on the target application server. As a result, we are doing a series of articles on setting up each different application server. This particular article looks at deploying a sample component that provides simple database access to JBoss.

Note: This article was originally written late in the beta for the product, therefore the actual implementation is subject to change before the product is officially released, and some of this information may become dated.

Install JBoss
If you don't already have it, JBoss can be downloaded from www.jboss.com/products/jbossas/downloads .

Note the location where you have installed it because you'll use that information during the configuration step. For this particular walkthrough, I've installed JBoss in the following location:

C:\Program Files\jboss-4.0.3

Install PASP
By default, the PASP is installed in the following directory:

C:\Program Files\Sybase\EAServer6\pb-server

There are three subdirectories of that directory that are of the most interest with regard to configuring and troubleshooting the PASP. The "bin" subdirectory contains a number of batch files that are used to configure the PASP. The "config" subdirectory contains a number of XML files that contain the actual configuration details for the server. Finally, the "logs" subdirectory contains the log files for the server (and, if used, the proxy server) that are useful for troubleshooting.

Set Environmental Variables
PATH
The system path needs to be updated to include the lib directory underneath the PASP installation directory. For example:

c:\Program Files\Sybase\EAServer6\pb-server\lib

It also needs to include the directory where the PB runtime files are located. For example:

C:\Program Files\Sybase\Shared\PowerBuilder

CLASSPATH
The system environmental CLASSPATH parameter has to be updated to include the pbserver.jar file. For example:

C:\Program Files\Sybase\PBServer\lib\pb-server.jar

JAGUAR
Create this environmental variable and set it to the directory where the PASP is installed. For example:

C:\Program Files\Sybase\EAServer6\pb-server

JAGSSL
Create this environmental variable and set it to TRUE.

PB_SERVER_HOME
This environmental variable is optional. It does make running a number of the batch files used for configuring and administering the server easier to use. If this variable is used, it should also point to the installation directory for the PASP.

C:\Program Files\Sybase\EAServer6\pb-server

Set the Admin Password
The first step to setting up PASP is to run the setup-admin-password.bat batch file in the bin directory of the PASP home. Do that from a command prompt in the bin subdirectory, because the batch file will prompt you for password information when it runs (see Figure 1 ). Note that the password must be at least six (6) characters long and include at least one (1) numeric character. That information is not provided as part of the prompt, and a failure to provide a password that meets that criteria does not return specific error information indicating what the problem is.

Edit the Configuration XML File
There is one configuration file (pb-server.xml) that is used to configure the plug-in as well as a separate configuration XML file for each of the different application servers in the config subdirectory. The one for JBoss is called pb-server-jboss.xml. We will need to modify both of those to indicate the host name that the server is operating on.

PB-SERVER.XML
In this configuration file, we are going to edit the iiopListeners entry so that the PASP knows which host name and port to listen on for deployment requests. Since I'm running the server locally and accessing it locally, I'm going to use "localhost" for the host name.

<property name="iiopListeners" value="iiop://localhost:9000"/>

PB-SERVER-JBOSS.XML
The initial change is to indicate the host name for the java.naming.provider.url. As above, I'm going to use "localhost" for the host name, so I'm modifying the following entry in the pb-server-jboss.xml file:

<property name="ejb-client:java.naming.provider.url" value="jnp://localhost:1099"/>

 

Run the Configuration Batch File
The next step is to run the configure.bat batch file. That batch file takes a number of parameters. The two we are interested in at this time are:

1. The name of the XML file to use to configure the specific server (e.g., pb-server-jboss.xml)
2. The physical location of the third-party application server home directory (e.g., C:\Program Files\jboss-4.0.3), prefixed by -Djboss.home=. If the home directory contains any spaces (as in this case), the entire parameter needs to be embedded in quotes:

configure.bat pb-server-jbos.xml "-Djboss.home=C:\Program Files\jboss-4.0.3"

The configuration script has to be rerun whenever you want to update the server configuration. For example, in a later step we will be defining an ASA datasource. You may want to consider creating an additional batch file with the configure.bat batch file parameters hard coded to save typing and reduce typing errors. I have a configure-jboss.bat file that contains the single line above that I simply run whenever I want to update the server configuration.

(RE)START THE APPLICATION SERVER
If the application server was already running, it will need to be shut down and restarted. Whether it was running or not, an additional command-line parameter needs to be passed to the application server to define the "pb.server.home" value. JBoss has a run.bat file in its own bin directory that is used to start the server. You would pass this new parameter to that file as follows:

run.bat "-Dpb.server.home=%PB_SERVER_HOME%"

If you didn't define the optional PB_SERVER_HOME environmental variable, you would need to pass the actual directory reference. Here again you may want to create a batch file with the parameters hard coded, so you can use that any time you need to restart JBoss.

Assuming that the plug-in was installed correctly, you should see it start up and begin listening for IIOP connections in the JBoss startup log (see Figure 2 ).

Create the Sample Component
Now we're ready to create a component. First create a simple component to test out the server. If you create a component and deploy it as MyComp in a package called pbtest, there is a script provided with the PASP that will examine its methods and call each of them in order. For example, we can create a component (choose EAServer component from the New dialog) with a method called "helloworld" that simply returns the string "Hello World".

From the PowerBuilder IDE you created a connection to JBoss just as if it was EAServer. The only difference is that you would use "admin@system" and the password you used earlier for the login name and password, rather than jagadmin as you would for EAServer (see Figure 3 ). You created the profile first because one of the last steps in the EAServer component wizards is to select the profile that you are going to deploy the component to.

Now use the File->New->PB Object->EAServer Component Wizard to create a new component called MyComp. Note that case is important for the component name and package name as deployed to EAServer (see Figure 4 and Figure 5 ). You can accept the default options on the remaining pages of the wizard.

Note that the "Expose EAServer Component as a Web Service" page of the Wizard will have no effect in JBoss. Those options work specifically with the Web Services Toolkit that's bundled with EAServer. If you wish to expose the component as a Web service, use something like (www.jboss.org/wiki/wiki.jsp?page=JBossWS).

Once the shell component is generated, open it in the user object painter, create a method called "helloworld", and add the following script to it:

Return "Hello World"

You can now save the component and use the project that was generated by the wizard to deploy it to JBoss.

Test the Sample Component
The pb-server-test.bat file, also located in the "bin" directory PASP home can now be run to test out the deployed component. If all is well, you should see output similar to Figure 6 . Congratulations! You just created, deployed, and called your first PowerBuilder component to JBoss!

Create a Real Component
Now that we know the plug-in is working correctly, it's time to build a more realistic component. The first thing we're going to do is create a DataWindow object to retrieve data from the ASA sample database that comes with PowerBuilder. In particular, create a DataWindow called "d_dept_emp" that retrieves the employees for a particular department using the following SQL statement:

SELECT "employee"."emp_id",
         "employee"."manager_id",
		 "employee"."emp_fname",
		 "employee"."emp_lname",
         "employee"."dept_id",
		 "employee"."street",
		 "employee"."city",
		 "employee"."state",
		 "employee"."zip_code",
		 "employee"."phone",
		 "employee"."status",
		 "employee"."ss_number",
		 "employee"."salary",
		 "employee"."start_date",
		 "employee"."termination_date",
		 "employee"."birth_date",
		 "employee"."bene_health_ins",
		 "employee"."bene_life_ins",
		 "employee"."bene_day_care",
		 "employee"."sex"
	FROM "employee"
	WHERE "employee"."dept_id" = :dept_id

Create a retrieval argument for the DataWindow object called dept_id of type number. The actually layout of the columns in the DataWindow object is of no importance; you can accept the default. Note, however, that the XML Export definition is important. Modify it according to Figure 7 , where emp_fullname is a DataWindow Expression.

Use the EAServer Component Wizard again to create a component called "PluginDemo" to be deployed to a package of your choice. For this walkthrough, I'm using a package called "TeamSybase". Create a getemployees methods on that component that takes an argument called dept_id of type integer and returns a string, then add code according to Listing 1 . (The function throws the "myexp" exception, where myexp is an unscripted standard user object inherited from the PowerBuilder exception class.)

 

Basically, this component obtains a connection to the database and then uses a DataStore and the m_dept_emp DataWindow object to retrieve the employee records for the selected department. Finally, it returns that data in an XML-formatted string using the XML export template we defined earlier. The one item that may seem unusual to you in that script, if you haven't worked with EAServer components before, is the following:

my_trans.DBParm = "CacheName='ASADS'"

That is, we aren't providing any connection information within the component. We're just pointing to a connection cache entry that is defined in the server and using the transaction the server hands us. First, however, we'll need to create that entry. We'll do that in a moment, but for now go ahead and deploy the component to the server using the project created by the wizard.

In practice, you can return a wide variety of data from your component. I've chosen to return XML from this component because I'm anticipating that we will want to use it as the basis for a Web service, and I prefer to return XML from Web services.

Create the Connection Cache Entry
The way you define a connection cache in JBoss is to create an XML file that defines it and then put that file in the "server\default\deploy" directory under the JBoss home. To create a connection cache entry for the ASA sample database, create a file as follows:

<datasources>
    <local-tx-datasource>
      <jndi-name>ASADS</jndi-name>
      <connection-url>jdbc:sybase:Tds:localhost:2638</connection-url>
      <driver-class>com.sybase.jdbc2.jdbc.SybDriver</driver-class>
      <user-name>dba</user-name>
      <password>sql</password>
    </local-tx-datasource>
</datasources>

Call it asads.xml and copy it to the "server\default\deploy" and JBoss will automatically install it. You also need to deploy the jconn2.jar file (the ASA driver) and the pbjdbc12XXX.jar (where XXX is the version number of PowerBuilder you're using, e.g., 100 for PowerBuilder 10.0) to the "server\default\lib" directory under the JBoss home.

The jndi-name entry is the alias with which we'll refer to this connection. The connection-url points to the database server. In this particular instance, we are pointing to an ASA database that is listening for connections on port 2638 (the default port ASA uses) on the local machine (localhost). The driver class is the class file used for the connection from the jconn2.jar file. Of course, the user name and password entries are the user name and password the connection cache will use to connect to the server. In a production environment, you would not use the database owner (for ASA, "dba") as the login account.

Remember that unlike PowerBuilder connecting through an ODBC connection, the application server connecting through a JDBC connection will not be able to auto-start the database. You'll want to make sure the database is working before accessing the component.

You'll also need to reconfigure the PASP so it knows about the connection cache entry. To do so, open the pb-server-jboss.xml file and look for the existing "setProperties dataSource" entries. Add another one for ASA as follows:

<setProperties dataSource="ASADS">
      <property name="proxyFor" value="java:ASADS"/>
</setProperties>

Save the file and rerun the configuration batch file to update the PASP configuration. You will also need to shutdown and restart JBoss after the PASP configuration change.

Start the Proxy Server
If you are going to use the Proxy Server to allow your PowerBuilder clients to call the component without having to configure a local JVM, now would be as good a time as any to start up the proxy server. Do that through the start-server.bat file located in the PASP "bin" directory, passing it a command-line argument of "pb-server-proxy":

start-server.bat pb-server-proxy

You should see the Proxy Server start up and begin listening for IIOP connections (see Figure 8 ).

Create a PowerBuilder Client
The first thing we need to do is create proxies for the objects that we're going to be calling. Use the File->New->Project->EAServer Proxy Wizard to create the project(s) we'll use to create the proxies (see Figure 9 ).

When you get to the "Choose EAServer Profile" page, select the profile for the JBoss server. The next page of the wizard will show you the components that are available in the server (see Figure 10 ). We want to do a simple "hello world" type test before we call the database component. Select both the pbtest and PluginDemo components. The pb-server-test.bat file we ran earlier connected directly to the PASP and not through the Proxy Server, so this additional test will help make sure that we can connect through the Proxy Server as well. Once the projects are created, "deploy" them to create the proxy objects for the two components.

To do the simple "hello world" test, add a command button on the main form of the client application and add the code from Listing 2. A few notes are in order concerning this code. For the driver property of the connection object use "jaguar", just as if you were connecting to EAServer. For the location property of the connection, make sure that the location begins with "iiop://". The PowerBuilder online documentation infers that this is optional, but it doesn't appear to be. The remainder of the location property should refer to the server where the PASP is running and the port number that the proxy server is listening on. The default is 2000 and is one of the settings that is adjusted through the pb-server.xml file. The application property is optional and specifies the default package for the components that will be accessed. In the CreateInstance call, we pass in an instance of the proxy and indicate the package name/component name we are attempting to work with.

If everything is working, clicking on the command button will result in the component returning "Hello World" to the client application. Once that's working, we're ready to create a client for the database component. For simplicity we're going to use the same d_dept_emp DataWindow in our client application as we did for the server component. In practice, we could use any DataWindow that had an Import XML template capable of dealing with the data that we're going to be receiving from the component. Then, we'll add a DataWindow control that references the d_dept_emp DataWindow object and another command button to our main window in the client that contains the code from Listing 3. The only significant difference between this code and the "Hello World" sample is a bit more error handling and the importing of returning XML into the DataWindow. Click on this command button and you should see the DataWindow populate with data. Once again, congratulations!

If for some reason you don't want to use the proxy server, you can connect from a PowerBuilder client directly to the PASP. To do so requires the configuration of a JavaVM on the client machine. In addition, use the EJB Client Proxy Wizard rather than the EAServer Proxy Wizard to create the project used to create the proxies. Rather than browsing through the deployed components, you would access the JAR file that was created during the deploy that contains the EJB stubs for the component, and indicate the remote interface and home interface class names for the component (ejb.components.<package>.<component> and ejb.components.<package>.<component>Home) (see Figure 11 ). It also requires that you add the pbejbclientXXX.PBD to the library search path of the client where XXX is the version of PowerBuilder you are using (10.0 is 100).

You would then use code similar to Listing 4 to access the database component. Note that you are using the ejbconnection class rather than the connection class to communicate with the server. The ejbconnection class also requires that you create the JavaVM class and set its classpath. At a minimum, the classpath would need to include the JBoss client classes, which are contained in the jboss-j233.jar and jbossall-client.jar files. You also need to set the INITIAL_CONTEXT_FACTORY and PROVIDER_URL properties for the ejbconnection. Those values can be obtained from the pb-server-jboss.xml file. The use of the ebjconnection requires that you first perform a lookup on the ejbconnection object to obtain the component home and then create the component proxy using the createjavainstance method of the JavaVM class and the Create method of the generated home interface proxy.

Conclusion
The PowerBuilder Plugin for Application Servers provides a long-needed option for sites that want to deploy PowerBuilder components to application servers but were unable to use EAServer. In a later issue we'll look at it in depth, explore more of its capabilities, and discuss working with it and other application servers.