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 2.0 (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.
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 the classes required to run
WebLogic Server to your workspace. As you develop and debug your applications
you will add classes and projects to your workspace. Note that 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, the server will read its properties from the
weblogic.properties file in the
WebLogic home directory, just as it does when you run it outside of
VisualAge.
Running WebLogic Server
To run WebLogic Server, double-click on the
WebLogic Server project
in the All Projects pane of on the Projects
tab. This will open 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.
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,
most 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 will be properties to configure in the
weblogic.properties file.
As noted in The VisualAge workspace,
the server will read 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 will need to 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 installed in VisualAge have arguments set to
default values so the example 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
Because of an incompatibility in VisualAge 2.0, the Cloudscape all-Java
database cannot be used in Visual
Age. Most of the examples use the 'demoPool' database connection pool, which is configured to
use a pre-configured Cloudscape database that is installed with WebLogic. In order to run these
examples in VisualAge, you will need to 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 includes a Data-Definition Language (DDL) file for the examples database, and a
Schema tool to create a database from a DDL file.
For additional 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.
In order to use JMS, you will 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 Visual
Age, 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 check box 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 EJBeans, 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 a deployment descriptor text file, a jar
manifest file, and output jar file name. There should not be any spaces
in the jar file name or in the directory names in the path of the jar file.
If you need to change these attributes
later, use the Configure EJB package tool. In order to use
these tools, the EJB project must include a
text deployment descriptor and a jar-file manifest.
Configure EJB package
This tool allows you to associate a new
deployment descriptor, jar manifest file, and output jar file name with the selected
EJB package. There should not be any spaces
in the jar file name or in the directory names in the path of the jar file.
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 EJBeans.
While debugging an EJBean, you may change the content of the Bean methods
without rebuilding the jar. Changes to the EJBean'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 have a text
deployment descriptor and a manifest for the EJB jar file. In addition, the
manifest must use the default name for the serialized deployment descriptor,
as generated by the WebLogic deployment tools, that is
beanNameDD.ser where
beanName is the name of the
EJBean.
- 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 EJBean without
rebuilding the jar file, you must rebuild the jar before
attempting to deploy the EJBean 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.
I 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.
Using Weblogic JMS
JMS stores persistent messages in a database, accessed through a JDBC connection pool,
which you define in the weblogic.properties file. If you do not use persistent messages,
you do not need to assign a connection pool for JMS.
Because of an incompatibility in VisualAge 2.0, the Cloudscape all-Java
database that is shipped with WebLogic cannot be used in Visual Age. For instructions
on how to set up the JMS message table in another database see
Cloudscape.
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 Type 2 JDBC drivers
When I use a Type 2 JDBC driver, such as the Oracle driver
shipped with WebLogic, I get strange errors such as "LDA not set", or
the VisualAge IDE crashes.
You need to download and install the "JNI fix for caching method
ID's" from the
VisualAge
Developer Domain, as described in the
Before you begin section.
Using Cloudscape database
When I use the Cloudscape database in VisualAge, I get a
java.lang.VirtualMachineError in FileDescriptor.sync.
This is a known problem. According to IBM, this problem will be
fixed in VisualAge 3.0, but there will not be a fix for VisualAge
2.0. The work around is to use a different database when running
WebLogic in VisualAge.
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 socket muxer
Why does my log file contain the following message?
<SocketMuxer> Unable to load native socket muxer, using Java muxer
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.
* VisualAge is a trademark of International
Business Machines Corporation.
