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
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
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.
