PowerBuilder Authors: Chris Pollach, Yeshim Deniz, Jayaram Krishnaswamy, Kevin Benedict, Avi Rosenthal

Related Topics: PowerBuilder

PowerBuilder: Article

PowerBuilder does JSP!

PowerBuilder does JSP!

PowerBuilder 9 will introduce faithful PB developers to the ability to build and use JavaServer Pages (JSPs) in their PowerBuilder Web applications. This is a giant step forward in Sybase's continuing march toward industry-leading openness. All of PowerBuilder's capabilities, including the graphical development environment, the system tree, powerful SCC integration, rich Web Targets and object models, wizards for rapid development, and integrated EAServer development, can now be applied to JSP Web Target development.

Why JSP?
JavaServer Pages are part of the J2EE 1.2 Specification. What is a JSP? Simply put, JSPs are a powerful way of incorporating dynamic content into a Web page. You, as a developer, insert simple tags into an ordinary HTML page and place Java code within the tags that will execute on the server. Thus the powerful and widely used Java language is directly available within your Web pages. You can instantiate classes, invoke JavaBeans and Enterprise JavaBeans (EJBs), access application server components, utilize databases, and execute logic and flow control within your Web page. In short, JSPs give you a powerful page server capability with dynamic server-side scripting.

Wait a minute! "Page server capability with dynamic server-side scripting?" This sounds like Dynamo. That's true. JSPs provide capabilities that are very similar to those of Dynamo. Why use JSPs then? JSPs operate within the J2EE environment. JSPs also use Java as their language, rather than YAPL (Yet Another Programming Language) such as DynaScript. At the moment, the choice is yours whether to use JSP or Dynamo as your page server. However, Dynamo has not been enhanced significantly for some time. And, since Sybase has added support for JSP and seems to be focused on that technology for Web applications, it would be hard to justify developing new applications based on PowerDynamo.

JSPs - How Do They Work?
JSPs run in a "JSP container" that communicates with your Web server. The JSP container receives a request, executes server-side code within the page, and formats a response that's sent back to the server, and, ultimately, to the requesting client (browser). Remember, the Java code embedded in a JSP is executed on the server before the page is returned to the client. What's returned to the client is straight HTML, composed, controlled, and formatted by way of the server-side Java code. Internally, JSPs are servlets that run within the JSP container. The simplest of JSPs is nothing more than an HTML page.

JSP Containers: EAServer and Tomcat
PowerBuilder 9 will allow you to create JSPs and directly deploy them as a Web application to either Tomcat or EAServer JSP containers. Choosing the JSP container is part of the deployment descriptor that you associate with your JSP target. You'll see how all of this fits together later in this article.

What's in a JSP?
First, a JSP contains static marked-up text (HTML). In addition, you can place scripting elements (denoted by special tags), standard tags (such as <jsp:useBean >) that allow you to perform common actions, and custom tags as defined in the custom tag libraries (taglibs) that you associate with the JSP.

Now the Disclaimer
This article is based on PowerBuilder 9 beta 3. Some of the capabilities are incomplete, and I expect quite a few changes in configuration and usage by the time the product is released for general availability.

Five Steps to JSP Enlightenment
What follows is a five-step program for getting familiar with JSP development in PowerBuilder. I'll use EAServer as both the Web server and the JSP container. Check the documentation that comes with PowerBuilder and EAServer for details on using other Web servers and for setting up Tomcat. Please note that the code for these examples can be found at the PBDJ Web site at www.sys-con.com/pbdj/sourcec.cfm.

Step 1: Setting Things Up - EAServer and PB
You'll need Windows NT4, SP6a, or Windows 2000 to use PowerBuilder 9. Win9x will not be supported. Also plan on using a fast machine with lots of memory (I like 1GHz or better and 512MB minimum).

Beta 3 of PowerBuilder 9 expands into two images, CD1 and CD2. The first "CD" is the common install for PB9 and related components, and the second is for EAServer Developer 4.1.2. Before you begin installation though, you'll need to have Internet Explorer version 6 on your system. PowerBuilder 9 Web Targets require IE6. You can upgrade to IE6 free of charge from the Microsoft Web site.

Once you have IE6 set up, install EAServer 4.1.2 from the second CD image. JSP targets will not deploy correctly to earlier versions of EAServer.

Note: You should do a complete uninstall, including a sweep through your registry to remove references to earlier versions of EAServer.

Next, install PowerBuilder and related products from the CD1 image. Be sure to include Web Targets in your installation. If you don't see them as an option, check that you have completed the installation of IE6, including any required system restarts. After the installation is complete, restart the system, then check your CLASSPATH and PATH environment variables.

CLASSPATH is an important consideration for the proper operation of EAServer and PB JSP targets. Earlier versions of JDK, PowerBuilder, PowerJ, EAServer, and other products will have left a hodgepodge of folders and .jar and .zip files in your CLASSPATH. Edit CLASSPATH carefully to remove all references to earlier versions of software. JDK 1.3 is necessary for proper deployment and execution of your JSPs, so make sure your CLASSPATH references are for JDK 1.3.

Note: If you intend to use only PB and EAServer on your machine, you can remove CLASSPATH entirely. Both EAServer and PowerBuilder maintain their own CLASSPATH exclusive of the system CLASSPATH. Also be sure to resolve any duplications, errors, or conflicts between the SYSTEM and USER environment variables.

Your PATH variable must also be accorded some TLC. Once again, edit it carefully since applications seem to regard PATH as their own folder motel: "Folders check in, but they don't check out!" Remove obsolete references and conflicts and add the following to your PATH:

  • %JAVA_HOME%\jre\bin\classic
  • %JDK_LATEST%\bin
  • %JDK_LATEST%\dll
You'll also need to remove any references to Adaptive Server Anywhere 7.0.3. EAServer Developer 4.1.2 inserts this into your PATH, but it interferes with PB Web Target deployment.

JAVA_HOME needs to be present as a system or user environment variable. It should point to the root of your JDK 1.3 installation (such as C:\Program Files\Sybase\Shared\Sun\jdk\jdk1.3). Set JDK_LATEST to point to the same location.

After you've configured your CLASSPATH, PATH, and other environment variables, restart the system. This will reestablish your PATH and unload any remnants of JDK that may have been using your prior CLASSPATH.

Start EAServer and observe the screen as it's loading. You should see that EAServer is using JDK 1.3 and there are no startup errors. EAServer is ready when it says "Accepting Connections."

Finally, you'll need to configure PowerBuilder with profiles for the database and EAServer. First, establish a database profile for EAS Demo DB V4. The ODBC DSN for this database should already be present on your system. If it isn't, create it. Next, create an EAServer Profile for your machine. Choose "Tools | EAServer Profile..." from the menu and click the "Add" button. Figure 1 shows the PowerBuilder dialog for the "Edit EAServer Profile." Enter your machine name for the Profile Name and Server Name, use "jagadmin" for the Login Name, and 9000 for the port. The default password for "jagadmin" is blank. Once you've created the necessary profiles, you're (finally) ready to create, deploy, and test a JSP.

Step 2: A Simple JSP
Now the fun begins. Start by creating a new workspace for this tutorial. I called mine "p3_pbdj". As we work through this tutorial, we'll create several targets within this workspace. The first target we'll create is a JSP Web Target.

A Web Target is used in PowerBuilder to create a Web application. A Web application is a collection of files that can be deployed to a server and executed from a client browser. The unit of deployment for a Web application is a WAR file (Web application ARchive). Even though PB will deploy directly to your JSP container and application server, it will still create and use a WAR file as the mechanism.

Right-click on the workspace and select "New...". The PowerBuilder "New" dialog will appear with the "Target" tab selected. Choose "JSP Target" and click "OK". This will start the JSP Target wizard. Work through the JSP Target wizard, making the following choices:

  • Call the JSP Target "p3_jsp".
  • Accept the defaults for deployment configuration.
  • Select "I am using the default Object Model".
  • Choose "EAServer" from the Web server list.
  • Select your machine's EAServer profile from the EAServer profiles (do not check "Automatically Shut Down and Restart Server When Deploying".
  • Choose "Deploy All or Nothing" and incremental rebuild. These are the default selections for file deployment.
  • Accept the defaults for local copy folder and WAR Filename.

    Within the system tree you'll now see your JSP target. Click on the "+" sign to expand it. You'll see two folders, META-INF and WEB-INF, that are part of the structure of a Web application. Under the WEB-INF folder will be a file called "web.xml" that contains much of the deployment and configuration information for the Web application. Don't edit this file directly; however, examine it to see how the information is organized.

    Now that you have a JSP target, it's time to create your first JSP. The simplest JSP is made up of ordinary HTML. And the simplest HTML is a straightforward "Hello World" page. Start the New Web Page wizard. First, right-click on the target, then select "New" from the RMB menu. This will display the New dialog with the "Web" tab selected. Select Web Page from the dialog and click "OK". Work through the wizard, filling in the dialogs as follows:

  • Enter "Hello World" as the title.
  • Remove the space in the file name between "Hello" and "World" and change all characters to lowercase, resulting in "helloworld.jsp".
  • Leave the entry for stylesheet blank.
  • Leave the entry for background image blank and accept the default (white) for the background color.
  • Check "Header Based on Title" and leave "Date Created Footer" unchecked.
  • Click "Finish" to create your new JSP, then save the file.

    Note that you can switch among the page, source, and preview views, just like you did with HTML Web Targets in PowerBuilder 8. You can also right-click on the page and source views and select "Browse with..." to view your page in a browser. However, to see your JSP served up by the EAServer Web server, you'll need to deploy the Web application. Right-click on the target and select "Deploy". You should end up with something like Figure 2 in the output view at the bottom of your PB screen.

    Notice that you can see two lines that signify possible errors or warnings. The first is after the target is built. It should show the target name followed by "0 error(s), 0 warning(s)." At the very bottom of the output view is the second line that gives the results of the deployment step. This line should show the target name, followed by "Deployed - 0 error(s), 0 warning(s)." If you see any errors or warnings, check your code and configuration for possible problems. As a bit of a head start, here are a couple of likely problems and their solutions:

  • "Error: JDK not set up correctly": This error can usually be resolved by making sure that the PATH entries correctly point to JDK 1.3. See the previous section on setup.
  • "Error: Deployment JAR initialization failed": There are two fixes for this problem: (1) make sure the environment variable %JAVA_HOME% is defined and pointing at the JDK 1.3 root folder. Add %JAVA_HOME%\jre\bin\classic to your PATH variable; (2) make sure that the easclient.jar file in your EAServer\java\bin folder is dated July, 2002, or later.

    Note: Sybase has indicated that they will have PowerBuilder 9 beta 4 and higher install its own JDK that will be used only by PowerBuilder. This will help eliminate the two errors listed.

    Now open your browser and navigate to the new JSP. It can be found in the Web app with the name given to your target, so your URL will look something like http://Server3:8080/p3_jsp/helloworld.jsp.

    Don't be too impatient. The first time you request your JSP, EAServer will need to load it (and a raft of other Java classes) and compile it. The second time you call this page, it will return almost immediately.

    Bring up Jaguar Manager and connect to your server. Expand the tree to your server and "Installed Web Applications". You should see "p3_jsp" as one of the applications; click on it. Notice that no components show for this Web application. Where's your JSP? The answer is the previously mentioned "web.xml". This file needs to have an entry for each JSP as a servlet tag. Remember, JSPs are treated like servlets in the Web application. To get the JSPs to show up in Jaguar Manager, do the following before you deploy from PB (see Figure 3):

  • Open the properties sheet for the Web target (right-click on the target and select "Properties").
  • Click on the "Deploy" tab.
  • Edit the deployment configuration.
  • Under "JSP Options", click on "Servlets".
  • On this dialog, under "Servlets for JSP", click the "New" button.
  • Add the name for the component (i.e., the JSP name without ".jsp").
  • Drop down the select box underneath this and choose "JSP Filename".
  • Type the JSP file name in the edit box next to this.
  • Click "OK".

    Step 3: Using the Object Model and Flow Control
    Here's a simple example that uses a form to pass a username and password to a second JSP. The second JSP uses the object model to get the parameter values from the request. Then a simple test (username = password) is performed to authenticate the user and respond with an appropriate message. First, build the Login page:

  • Use the New Web Page wizard to create a page called login.jsp. Include a "header based on title".
  • Add a form to the page (you can drag and drop from the system tree, or type into the source view). The action for the form should be "dologin.jsp" and the method should be "POST".
  • Place two inputs into the form, one for username and one for password.
  • Place a submit button into the form, with text of "Login".
  • Save login.jsp.

    Your page view should look like Figure 4, and the resulting code is shown in Listing 1. Note that we're still working with plain HTML. We'll insert Java into our next page to authenticate the user and decide which message to send back.

    Next, create the page to perform the authentication. Use the New Web Page wizard to create a page called "dologin.jsp". Now we need to add Java code to the page to extract the passed parameters, test them, and return a message to the user. First add the declarations:

  • From the page view, right-click in the script area and select "New Script | Server | JSP | <%! ... %>" from the menu. The "<%! ... %>" tag is used for declarations.
  • Enter the declarations as shown in the script area. This will create two string variables, one for the username and one for the password. Remember that Java is case sensitive; "String" is different from "string".

    String user;
    String pwd;

  • Enter these two lines in the script area of dologin.jsp.
  • Right-click in the script area and select "New Script | Server | JSP | <% ... %>" from the menu. The "<% ... %>" tag is used for writing code.
  • Insert the code in Listing 2 in the script area. You can type it or drag from the "Language" tab in the system tree - you'll find "request" under "Server | JSP Implicit Objects".

    The script stops after the opening bracket of the "if" statement, which is intentional. We'll insert simple HTML inline with the Java we're using for flow control.

  • Switch to the source view. Immediately after the closing tag following the "if" statement, insert the code in Listing 3.

    You've added some text that will display in the browser, an HTML tag to break to the next line, and more Java - this time using the <%= ... %> tags - to evaluate (and display) the value of the variable user. Then more flow control, a bit more text, a tiny bit more Java to end the "if" block, and you're done. The point here is the free mix between HTML and Java within the page. What is ultimately sent back to the browser is only the HTML that's selected by the enclosing Java - one message (login accepted) if username and password are equal, a different one (login rejected) if they're not.

    It's important to remember that the JSPs that you are working on are essentially the user interface part of your application. Significant business logic should always be placed in components, JavaBeans, or EJBs. Don't let the simplicity and ease of working with JSPs lull you into bad coding habits.

    Finally, deploy and test your JSPs. Request the login.jsp page from your browser, then fill in a username and password and click the "Login" button to submit the form. If you typed the same thing for username and password, you should get back a page that says your login was accepted. If you typed different things, your login will be rejected.

    If you get an error message indicating a server problem, examine the logs found in the EAServer\bin folder: httprequest.log, httpservlet.log, and jaguar.log. The messages in these log files seem cryptic, but they will help you discover what is causing your error.

    Step 4: Now for Something Completely Different - Calling a PowerBuilder Component from a JSP
    Of course, you'll eventually need to execute some business logic that you've deployed as a component into EAServer. Here's one way to do that:

  • In your workspace, create a new target (called names) for an EAServer component. Call the package "p3_pbdj", the PowerBuilder object "n_names_impl", and the component "n_names".
  • Add a function called "getname" to n_names_impl that returns your name as a string.
  • Save the component and deploy it to EAServer.
  • Create a new JSP in your JSP target called getname.
  • In the source view, enter the code from Listing 4. (Be sure to change the server name from Server3 to whatever your EAServer machine is named.) This code will connect to EAServer, instantiate your component, and call the getname function - returning your name and displaying it in the response.
  • Save and deploy the JSP.

    When you request getname.jsp from your browser, your name should be displayed on the returned page. Again, if you see errors instead, review the log files to determine the cause of the errors.

    Step 5: Using the HTML DataWindow in Your JSPs
    Our last step shows how to use JSPs to access HTML DataWindows. This is a very simplistic example, but it shows the basics. You'll be creating a DataWindow and building a JSP to access it.

  • Create a new application target for your DataWindow.
  • Build a DataWindow (just a few columns) against the "EAS Demo DB V4" database. For my example I used the customer table. Save it in the PBL for your new application target.
  • Create a new JSP page in your JSP target and call it html_dw.jsp.
  • Use the DataWindow Design Time Control (DTC) for this example. Select "Insert | Form Field | DataWindow..." from the menu, or simply use the toolbar button. Follow through the wizard and fill in the tabs according to the next bullets
  • In the DataWindow tab, select "library" for "Source for HTML Generation". Under "DataWindow - Source File" browse to the library containing the DataWindow you just made. Check "Generate absolute path in script" and select your new DataWindow.
  • In the connection tab, select EASDemo DB V4.
  • Accept the defaults from the other tabs and click "OK".
  • The page view for your JSP should look similar to Figure 5. Review the source code to see the implementation.
  • Save and deploy the JSP.

    Browse to the html_dw.jsp page. If all went well, the DataWindow and associated data will be displayed within your browser. If you see errors, consult the logs.

    Note: PowerBuilder 9 includes a custom tag library (taglib) that you can use instead of the DTC to add an HTML DataWindow to your JSP.

    PowerBuilder 9 now includes a rich and powerful capability for authoring JavaServer Pages. This allows you to build dynamic data-driven Web applications and deploy them to J2EE 1.2 servers such as Tomcat and EAServer. In this article, I've shown how to create simple JSPs, and how to use the capabilities of the JSP object model to access implicit objects. We've used Java to control the response that's sent to the user and used Java code to access EAServer components and HTML DataWindows. Not bad for a day's work.

  • More Stories By Millard F. Brown

    Millard F. Brown is vice president of Power3, LLC, a company providing consulting and training services for the enterprise. He has beend developing PowerBuilder applications since PowerBuilder 2 and is the co-author of two new PowerBuilder 9 books: PowerBuilder 9: Advanced Client/Server Development and PowerBuilder 9: Internet and Distributed Application Development.

    Comments (0)

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.