Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy

## Using the Integration Kit for VisualAge Introduction The VisualAge workspace Running WebLogic Server Running WebLogic Examples Compiling the examples Setting server properties Command-line arguments Cloudscape database Debugging EJB tools Generate EJB jar Configure EJB package Configure tools Tools usage Setting classpath Working with servlets Working with applets Using WebLogic JMS Installing service packs Exporting code to a production WebLogic Server Frequently asked questions ## Introduction IBM VisualAge™* for Java, Version 3.02 (Professional or Enterprise Edition), is an integrated, visual environment that supports the complete cycle of Java program development. With the Integration Kit for VisualAge, you can develop and debug your WebLogic Server applications from within VisualAge. This document describes how to use the Integration Kit for VisualAge with WebLogic Server. Note This document describes the Beta version of the Integration Kit, for WebLogic Server 5.1. The Beta kit was released on June 9, 2000. The released version of WebLogic Server 5.1 does not include the software described here. You can download the beta Integration Kit from the BEA download site. ## The VisualAge workspace All activity in VisualAge for Java is organized around a workspace, which contains the Java programs that you are developing. The workspace also contains all the packages, classes, and interfaces that are found in the standard Java class libraries, and other libraries that your classes may need. The Integration Kit for VisualAge adds to your workspace the classes required to run WebLogic Server. As you develop and debug your applications you will add classes and projects to your workspace. While the server classes are loaded from the VisualAge workspace, the weblogic.system.home property is set to the installation directory of your WebLogic distribution. Therefore, WebLogic Server reads its properties from the weblogic.properties file, just as it does when you run it outside of VisualAge. ## Running WebLogic Server To start WebLogic Server, double-click on the "WebLogic Server" project in the All Projects pane of on the Projects tab. This opens a separate window containing just the WebLogic Server project. Within the WebLogic Server window, click on the Run button, or right-click on the "WebLogic Server" and select Run Main in the Run submenu. While the server is running, a dialog is displayed that can be used to shut down the server. If you are using the Cloudscape database, it is important to use the shutdown dialog to stop the server, and not just terminate the server process in the VisualAge Console window. The evaluation version of Cloudscape is a single-user license, and the shutdown dialog terminates the Cloudscape connection properly so you can restart the server. If you terminate the server process, you will need to exit and restart VisualAge before using Cloudscape again. ## Running WebLogic Examples The "WebLogic Examples" project contains example code illustrating how to use many of the capabilities of WebLogic Server. In addition to the Java code in the VisualAge project, some of the examples also require configuring server settings in order to run properly, and some have command-line arguments which you can modify. For instructions about how to run each example, refer to the WebLogic Examples documentation. These documents describe how to build and run the examples from the command line. Most of the instructions also apply to running the examples within VisualAge, but there are a few differences to keep in mind. ### Compiling the examples Code is automatically compiled in the VisualAge workspace. Because of this, you can ignore the instructions concerning compiling. ### Setting server properties For most examples, there are properties to configure in the weblogic.properties file. As noted in The VisualAge workspace, WebLogic Server reads its properties from the weblogic.properties file in the WebLogic home directory. If the server is running in VisualAge when you change the properties, you must stop the server and restart it after setting the example properties. ### Command-line arguments Some examples have required or optional command-line arguments, which are described in the example documentation. Wherever possible, the examples have arguments set to default values so they will run with a typical server setup, but you may wish to change the arguments to try out different capabilities of an example. To set command-line arguments in VisualAge: Select the main class for the example. Choose Properties from the Selected menu in the workspace window. Choose the Program tab in the properties window, and enter the arguments in the Command Line Arguments text field. Press OK. ### Cloudscape database The Cloudscape all-Java database cannot be used reliably in VisualAge 3.02. We have observed VisualAge crashes when Cloudscape is used as the JMS database, and this may occur in other situations as well. We are working with IBM to resolve the problem, but for this beta we do not recommend using Cloudscape. Most of the examples use the 'demoPool' database connection pool, which uses a pre-configured Cloudscape database installed with WebLogic Server. To run these examples in VisualAge, you must create the example tables in another database, such as Oracle or DB2, and change the demoPool configuration in weblogic.properties to use that database. WebLogic Server includes a Data-Definition Language (DDL) file for the examples database, and a Schema tool you can use to execute the DDL command file against a database. For instructions, see the examples.utils documentation. To execute utils.Schema, your CLASSPATH must contain the weblogic/classes directory. Here is the syntax for the utils.Schema command:
      java utils.Schema url JDBC_driver [options] DDL_file
  url The database connection URL. This is a colon-separated URL as defined by the JDBC specification. JDBC_driver The full package name of the JDBC Driver class. options If the database requires a username and password, you supply them with options, like this:
        -u username -p password
You can also include the -verbose option, which causes utils.Schema to echo the SQL commands as they are executed. DDL_file The full pathname of a text file containing the SQL commands to execute. Lines beginning with pound signs (#) are comments. An SQL command can span several lines and is terminated with a semicolon (;). Here is a utils.Schema command to create the examples database tables in an Oracle server named DEMO, with the username "scott" and password "tiger":
    $ java utils.Schema jdbc:weblogic:oracle:DEMO \
       weblogic.jdbc.oci.Driver -u scott -p tiger -verbose \
       "/IBMVJava/ide/project_resources/WebLogic Examples/demoOracle.ddl"
Note: You must include the double quotes around the path of the DDL file because of the space in the WebLogic Examples directory name. To use JMS, you also need to create the JMS message database tables. The weblogic/classes/jms/ddl directory contains JMS DDL files for various databases. You can copy and edit one of these files if you want to use a different database. Here is a utils.Schema command to create the JMS tables in an Oracle server named DEMO, with the username "scott" and password "tiger":
    $ java utils.Schema jdbc:weblogic:oracle:DEMO \
      weblogic.jdbc.oci.Driver -u scott -p tiger -verbose \
      /weblogic/classes/weblogic/jms/ddl/jms_oracle.ddl
Some additional instructions for initializing the database may be included in the instructions for specific WebLogic Examples. ## Debugging You can debug server-side and client-side code by following these steps: Create a VisualAge project. To use the VisualAge debugger, any server-side classes must be in a VisualAge project. You can either create the project in VisualAge, or if the code already exists, you can import it into VisualAge. It is acceptable for client-side and server-side code to be in the same project. If the object you have developed is a server-side object, add the project to the Project Path field of the Classpath for the Server class. Expand the WebLogic Server project, then the weblogic.integration.visualage.server package. Right-click on the Server class and select Properties. On the Class Path tab, click on Edit for the Project Path field. Select the checkbox for your project, and click OK. Edit weblogic.properties as required. When running WebLogic Server from within VisualAge, classes are loaded from the VisualAge workspace, but the weblogic.properties file is read from the WebLogic home directory. Run the server. You can set breakpoints in server-side code and then trace the code when it is invoked from a client. You may choose to run the client from within or outside of VisualAge, whichever is more convenient. Note that external client calls may time out if the server is stopped at a breakpoint for too long. In addition, the VisualAge class loader allows you to modify and continue debugging server-side code without restarting WebLogic Server, as long as you only change the content the object methods. Changes to an object's interface will require restarting the server. ## EJB tools When developing EJBs, there are a number of steps that must be performed to convert your source code into a Bean that can be deployed by WebLogic Server. The Integration Kit includes tools that help build and manage your EJB projects from within the VisualAge IDE. The EJB tools, which are available from the Selected\Tools\WebLogic Tools menu, are: ### Generate EJB jar This tool generates an EJB jar file from the selected EJB package. If it is the first time that you have built the package, you will be prompted for an output jar file name. If you need to change these attributes later, use the Configure EJB package tool. In order to use these tools, the project resources directory for the package (IBMVJava\ide\project_resources\<project name>\<package path>) must contain any XML deployment descriptors required for the package. ### Configure EJB package This tool allows you to associate a new jar file name with the selected EJB package. ### Configure tools This tool associates the EJB tools with the root directory of the WebLogic distribution. This is necessary because the EJB tools depend on classes in the WebLogic distribution that have not been imported into the VisualAge workspace. This tool was run as part of the installation process and does not need to be re-run unless you move the location of the WebLogic distribution. ### Tool usage To use these tools, click on an EJB package or project. Then select the menus Selected, Tools, WebLogic Tools, then the appropriate tool. To deploy an EJB in the server, you must add the generated jar file to the deploy statement in the weblogic.properties file. Any of the WebLogic EJB examples can be built with these tools by selecting the individual EJB example package in the WebLogic Examples project. See Using WebLogic Enterprise Java Beans for more information on deploying EJBs. While debugging an EJB, you may change the content of the Bean methods without rebuilding the jar. Changes to the EJB's interfaces (remote interface or home interface) or the addition of a new EJB jar file require the use of the Generate EJB jar tool and restarting the server. The following are a few notes to keep in mind while using the EJB tools: EJB projects must be structured like the EJB examples. In other words, they must contain an XML deployment descriptor. To use the Generate EJB jar tool, users of the Enterprise Edition of VisualAge for Java will first need to create an open edition of the EJB package. To do this, select the package and choose the menus Selected, Manage, Create Open Edition. While it is possible to debug and modify an EJB without rebuilding the jar file, you must rebuild the jar before attempting to deploy the EJB in a server running outside of VisualAge. ## Setting classpath In VisualAge for Java, you can set classpath at the workspace level and at the class level. If you specify a workspace level classpath, every class in the workspace will reference these classes when compiling or running. This classpath is also needed to find resource files your classes use. During the installation process for the Integration Kit for VisualAge, you added the WebLogic Server Classes, WebLogic Support Libraries, and WebLogic Java Enterprise Libraries to the workspace level classpath. This was done because most of these classes are required by the examples included with the Integration Kit. To modify this classpath: Select Options on the Window menu. In the Options dialog, select Resources. Click on Edit next to the Workspace classpath field. In addition, you may also set classpath at the class level. These classes are appended to the workspace level classpath for the given class. To set the classpath for a class: Right-click on the class and select Properties from the class's pop-up menu. Click the Classpath tab in the Properties notebook. Click on Edit next to the Project path field. ## Working with servlets To run and debug servlet projects in VisualAge, you must add a path for the directory where VisualAge stores the servlet classes to the servlet classpath property in the weblogic.properties file.
    weblogic.httpd.servlet.classpath=\
       VisualAgeHome/ide/project_resources/projectName
where: VisualAgeHome Directory where VisualAge is installed projectName name of servlet project For example, to debug the servlets in the WebLogic Examples project, you would set the servlet classpath to:
    weblogic.httpd.servlet.classpath=\
       C:/IBMVJava/ide/project_resources/Weblogic Examples
4. Note that the example above assumes that you have installed VisualAge into the default location. You can include more than one project in the servlet classpath, and of course, you may also include directories to packages that are not in the VisualAge workspace. However, you will not be able to debug the servlets that are not in the VisualAge workspace. ## Working with applets There are two ways you can run applets with WebLogic Server in VisualAge: Run the applet with the VisualAge Applet Viewer. This will also allow you to debug the applet. Run the applet in a browser. You will not be able to debug the applet code in this case, because the applet is running in the browser VM, not the VisualAge VM. However using this method will allow you to test the applet in its HTML context. To run the applet with the VisualAge Applet Viewer: Select the applet class If the applet requires parameters that are normally specified in the HTML page, choose Properties from the Selected menu. Then add the parameters to the Parameter field on the Applet tab. Select OK. From the Selected menu, choose Run. Then choose In Applet Viewer. To run the applet in a browser: Export the applet classes from to the /serverclasses directory of the WebLogic distribution as described in by following the instruction in Exporting code from VisualAge to a production WebLogic Server. Copy the HTML file that tests the applet to the WebLogic Server's document root. The document root directory is where the WebLogic Server searches for public HTML files. By default it is set to the /myserver/public_html directory in your WebLogic installation directory. Run the server. In the web browser, request the URL:
         http://localhost:7001/appletTest.html
where appletTest is the name of the HTML file that tests the applet. ## Installing service packs Service packs are occasionally released for WebLogic Server to provide a safe, easy and convenient way for users to incorporate resolved issues into their current release. For more information, see our FAQ on service packs. To install a service pack into your Integration Kit for VisualAge, follow these steps: Extract the service pack zip file into a temporary directory. Select WebLogic Server Classes project in the All Projects pane of on the Projects tab. From the File menu, select Import. Select Jar file as the import source and select Next. Next to the Filename field, select Browse and select the service pack jar that you had previously extracted into a temporary directory. Under the 'What type of file do you want to import?' section, choose .class and resource. Select Finish. VisualAge will ask you, if want to create an edition of classes that are replaced by the service pack. Choose Yes To All. In order to keep track of the service packs that you have installed, you will want to version all of the classes that you have just installed with an appropriate name. Select the Show Edition Names button at the top of the VisualAge IDE. Select each of the classes that have just been installed as part of the service pack. You can select multiple classes by holding down the Ctrl key. To locate all of the classes that have been replaced, refer to the service pack documentation. The documentation includes a list of all of the classes included in the service pack. From the Selected menu, choose Managed, then Version. Select One Name. In the corresponding field, enter a name that is representative of the service pack that you have just installed, such as "451sp1". Select OK. ## Exporting code to a production WebLogic Server When you have finished developing your WebLogic application in VisualAge, you will need to export it to the filesystem to use it in a production system. EJB jar files are exported as part of the development process, so they do not need to be exported, but other code is only compiled within the VisualAge workspace during development. Setting your development environment describes the three directories where classes are located for WebLogic applications. They are: /weblogic/myserver/clientclasses -- for classes required by client applications /weblogic/myserver/serverclasses -- for classes required by server-side objects /weblogic/myserver/servletclasses -- for servlet classes where weblogic is the directory in which WebLogic is installed. Classes and resources from your WebLogic project in VisualAge should be exported to the appropriate directories. Classes that are shared between the client and server should be exported to both /clientclasses and /serverclasses. To export a class or package: Select the class or package. Choose Export from the Selected menu. Select Directory as the Export destination and hit Next. Enter the appropriate directory in the Directory field. Make sure that Class is checked under the 'What do you want to export?' section. Select Finish. ## Frequently asked questions Using EJB dynamic deployment Using a native Performance pack "Could not delete jar" message Using Cloudscape database Using EJB tools in the JDK 1.2 Early Adopters version ### Using EJB dynamic deployment Can I use the new dynamic EJB deployment while debugging server-side code in VisualAge? Not currently. Dynamic deployment uses classloaders in ways which are incompatible with the debugger classloader in VisualAge. However, the debugger will reload modified classes at runtime, so you can do much of the work of developing and debugging server applications without restarting the server. ### Using native I/O Why does my log file contain the following message?
    <SocketMuxer> Wed Apr 26 17:10:00 PDT 2000:<E>
       <Performance Pack> Unable to load performance pack, using Java I/O.
The WebLogic Server Native I/O Performance Pack currently cannot be used when running the server in VisualAge. This option is enabled by default in the server properties. To avoid receiving this error message, you should turn it off by setting:
    weblogic.system.nativeIO.enable=false
in your weblogic.properties file. ### "Could not delete jar" message When I restart the server, why do I get messages like "Could not delete tmp_deployments/zzz.jar"? These messages are harmless. They happen because VisualAge handles stopping and starting processes differently than a command-line Java VM, so certain files are kept open until you exit VisualAge. ### Using EJB tools in the JDK 1.2 Early Adopters version When I try to run the EJB tools in the JDK 1.2 Early Adopters version of VisualAge, I get an exception. Why? There are problems with the tools environment in this version of VisualAge. According to IBM, the tools environment will be fixed when the JDK 1.2 version goes from Early Adopters to GA, probably in VisualAge 3.5. Until then, you can debug WebLogic applications in the JDK 1.2 version, but you cannot use the tools in VisualAge. ### Using Cloudscape database When I use the Cloudscape database in VisualAge, VisualAge dies with no error message. This is a known problem. We are working with IBM to resolve it, but do not have a fix yet. The work around is to use a different database when running WebLogic in VisualAge, as described in the Cloudscape database section. * VisualAge is a trademark of International Business Machines Corporation.

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher. Last updated 4/26/2000