Introduction

This guide serves as a reference for the examples included with WebLogic Server. The examples are included with your WebLogic installation in your SAMPLES_HOME\server directory. Within this directory we have separated out our source files from the domain just as you might in a real world scenario.

The SAMPLES_HOME\server\src directory contains all the source files for the WebLogic Server Examples, including the Pet Store Application. Included with each WebLogic Server example is a package-summary.html file. This file contains all the information you will need to run that particular example, from building, to configuring, to running--and anything else you may need to know along the way.

The SAMPLES_HOME\server\config directory contains your examples domain; it contains your applications and the XML configuration files that define how your applications and WebLogic Server will behave, as well as startup and environment scripts.

The SAMPLES_HOME\server\stage directory contains client and server classes required by the examples, Pet Store, and PointBase.

The SAMPLES_HOME\server\eval directory contains PointBase, a demonstration database that the examples are configured to use. It also contains the PointBase documentation and scripts that start, stop, and open the console for the PointBase database.

The sections below detail the general steps that you will have to take in order to run the examples. They also include tips, such as changing the port WebLogic listens on, running the examples from a new directory, and troubleshooting notes. If you are looking for further information or help on how the examples are set up, read on. If you are comfortable with WebLogic Server, go right to the overview-summary page that is in your SAMPLES_HOME\samples\server\src\examples directory. This page has links to all the WebLogic examples.

Basic Steps for Using the Examples

These instructions describe the general tasks that need to be accomplished in order to run the WebLogic examples. The package-summary.html file for each example has all the documentation you need; this is a summary of the general steps you will take. Further along in this document it is explained in detail what exactly you are doing, and why.

Setting Up Your Environment     More Info

Before you can build and run the examples, you need to properly set up your development environment. This includes specifying the location of a JDK, determining where client and server classes are placed, setting the CLASSPATH, and having certain tools available. We have included a script that will properly set all these values :

1. Open a command window.
2. Move to the examples configuration directory: cd %SAMPLES_HOME%\server\config\examples.
3. Enter one of the following commands:
   • setExamplesEnv.cmd - on Windows/CMD shell
   • . setExamplesEnv.sh - on UNIX Bourne shell

Building an Example     More Info

Some examples run right from a browser when you boot up the server. These are the 'out-of-the-box' examples and will pop up in a window when you start the examples domain with WebLogic Server. As in the real development world, the rest of the WebLogic examples start off as java source files. They must be compiled into class files, or 'built', first. We provide ant scripts in XML files; running these scripts will build the corresponding example. Here are the general steps:

1. Move to the directory of the example you want to use: cd SAMPLES_HOME\server\src\examples\directoryName.
2. If the package-summary.html file for your example instructs you to do so, edit the examples.properties file at SAMPLES_HOME\server\src. The Ant task uses this file to set system properties.
3. There will be a build.xml file inside your examples directory, this is the script that builds the example. Enter ant to build the example; it will run the script in the build.xml file. (if your example's instructions indicate a different Ant target or build command, please follow the documentation).

Starting the Examples Server     

The following are ways in which to start the examples server. On Windows:

1. On the taskbar, click Start.
2. Choose Programs.
3. Choose BEA WebLogic Platform 7.0.
4. Choose WebLogic Server 7.0.
5. Choose Server Tour and Examples.
6. Choose Launch Examples Server.

Or ...

1. Use a command shell and go to the SAMPLES_HOME\server\config\examples directory.
2. Type: startExamplesServer.cmd

On UNIX Bourne shell:

1. cd $SAMPLES_HOME/server/config/examples
2. sh startExamplesServer.sh

Starting the WebLogic Server Console

You often need to use the WebLogic Server Console to set up an example before you run it.

To start the Console:

1. Start the examples server.
2. Open a browser and point it to HTTP://localhost:7001/console.
3. Enter weblogic for both the system name and password.

Running the Examples

The build scripts included with each example contain a run command. To run an example, go to the directory where the example is located and type:

ant run

This will execute the run target that starts the example; to view the command, go into the build.xml file and look for the section with the target called 'run.' This command may use variables; in some cases you may need to edit the build.xml before you run the script. If you are having problems with an example, it is a good idea to check the run target. You may need to set a port, parameter, or some other information that is unique to your setup. Also, some examples require that you modify this command, if, for instance, there are multiple ways to run the example. In all of the above cases, the example's package-summary.html will contain instructions telling you how to modify the command.

The Examples Web Application

If an example uses servlets, JSP files, or applets, you can deploy it as a Web application. We have taken many of these examples and put them into one Web Application called examplesWebApp, located in the SAMPLES_HOME\server\stage\examples\examplesWebApp directory. Each example that requires it contains specific instruction on using the examplesWebApp.

Follow these steps if you wish to verify that the examplesWebApp has been deployed:

1. Start the WebLogic Server Administration Console.
2. Expand the Deployments node in the left pane.
3. Expand the Web Applications node in the left pane.
4. Select the examplesWebApp node.
5. Select the Targets tab in the right pane.
6. Verify that the examplesServer target appears in the Chosen column.
7. If the examplesServer appears in the Available column and you wish to have the examplesWebApp deployed, click on the right arrow to move the examplesWebApp into the Chosen column and click 'Apply.'

More About Setting Up Your Environment

The setExamplesEnv script at SAMPLES_HOME\server\config\examples sets certain environment variables in your development shell, the command window from which you build and run the examples. It also sets the CLASSPATH properly. When you develop in Java, you need a controlled development environment to avoid class conflicts and other problems that can be difficult to diagnose.

setExamplesEnv sets these variables that refer to specific locations:

• SAMPLES_HOME - where the examples were installed
• APPLICATIONS - application archives created when you build the examples
• CLIENT_CLASSES - classes that the examples client applications require
• SERVER_CLASSES - classes that the examples server-side classes require
• COMMON_CLASSES - utility classes used by the examples, Pet Store, and PointBase
• EX_WEBAPP_CLASSES - classes required by the Examples Web Application used by the WebLogic Examples server

These variables point to directory locations in SAMPLES_HOME\server\config\examples
or SAMPLES_HOME\server\stage\examples.

If you are modifying the examples on your own, you can run the setExamplesEnv script and then use the above variables when you develop. This saves you the time of having to set these items every time you need them.

The syntax for using environment variables varies by platform. If you were using the CLIENT_CLASSES variable: On Windows, you enter, for example: %CLIENT_CLASSES%

On UNIX systems, enter $CLIENT_CLASSES

The setExamplesEnv script also sets the CLASSPATH variable in your development shell to include certain classes that you need as you build and run the examples. Since these classes could be anywhere on your system or network, you need to specify where to find the classes you are trying to run. The contents of your CLASSPATH will vary depending on the system you are running and how your directories are organized. Running the setExamplesEnv script sets the CLASSPATH correctly for you when you are using the WebLogic Examples. Specifically, here are the jar files and directories that setExamplesEnv puts in your CLASSPATH:

• BEA_HOME\jdk131\lib\tools.jar
• WL_HOME\server\lib\weblogic_sp.jar
• WL_HOME\server\lib\weblogic.jar
• SAMPLES_HOME\stage\examples\clientclasses
• SAMPLES_HOME\stage\examples\serverclasses
• SAMPLES_HOME\stage\examples\applications\examplesWebApp\WEB-INF\classes
• SAMPLES_HOME\server\eval\pointbase\client\lib\pbclient41ev.jar
• SAMPLES_HOME\server\eval\pointbase\server\libpbserver42ev.jar

When you run setExamplesEnv, it overwrites anything that is currently in CLASSPATH. If you want to run other Java applications or tools from within your development shell, you must edit the set CLASSPATH command in the setExamplesEnv script to include any classes those applications may require.

Setting Your Environment for Type 2 JDBC Drivers

Using a WebLogic Type 2 JDBC driver as a client requires an additional entry to your PATH variable. For instructions on setting PATH, see Installing WebLogic jDriver for Oracle.

If you want to use a Type 2 JDBC driver in a three-tier architecture, also modify the PATH variable you use to start WebLogic Server. The WebLogic Server Examples Database Guide has instructions for setting up an Oracle database for the examples.

More About Building Examples and the examples.properties file

Each example has an Ant task that builds the example. Each Ant task is named build.xml and is located in the example's source code directory.

The Ant task uses the examples.properties file to set system properties when it runs. The examples.properties file is located at SAMPLES_HOME/server/src.

By default, when you download WebLogic Server, the examples.properties file looks like this:

choose classic, modern, jikes, or jvc
JAVAC=modern
WL_HOME=C:/bea/weblogic700
BEA_HOME=C:/bea
SAMPLES_HOME=C:/bea/weblogic700/samples
CLIENT_CLASSES=C:/bea/weblogic700/samples/server/stage/examples/clientclasses
SERVER_CLASSES=C:/bea/weblogic700/samples/server/stage/examples/serverclasses
EX_WEBAPP_CLASSES=C:/bea/weblogic700/samples/server/stage/examples/examplesWebApp/WEB-INF/classes
APPLICATIONS=C:/bea/weblogic700/samples/server/config/examples/applications
CLASSPATH=java.class.path
XMLRegistry=C:/bea/weblogic700/samples/server/config/examples/xml/registries/examplesXMLRegistry
PORT=7001

# Database properties
# These user defined properties are available to automate
# table setup for those examples that use an Oracle database.

DBSERVER=
DBPORT=
SID=
USER=
PASSWORD=

You can use a text editor to edit examples.properties if you need to. For example, if you have changed a directory location in your WebLogic home directory, are running the examples using an Oracle database, or have set your WebLogic Server to listen on a port other than 7001.

If you changed the port number when you installed WebLogic Server, rather than accepting the default port of 7001, you will need to edit the examples.properties file to change it there as well.

The Examples Database

The examples use a demonstration database: Pointbase 4.2. PointBase Server is a pure Java relational database management system (RDBMS) that is included with WebLogic Server. Its purpose is to allow you to run code examples with a functional database server. For more information on PointBase and the examples see our PointBase page. The examples can also be run with Oracle as the database; for instructions on how to do so, see the database setup page.

Examples Passwords and Server Startup

The examples and PetStore domains use weblogic/weblogic as their username/password combination. The startExamplesServer scripts set these values as:

set WLS_USER=weblogic
set WLS_PW=weblogic

This script sets some additional values for initial server startup, and then calls the startWebLogic script located in your WL_HOME\server\bin directory. This script is what actually starts the server. In there the following parameters are set:

-Dweblogic.management.username=%WLS_USER%
-Dweblogic.management.password=%WLS_PW%

If you ever need to change your username/password for the examples and Pet Store domains, you will have to change the values in the examples startExampleServer script.

In the default configuration the server will start up without prompting for a password. If you wish to reenable start-up security, simply remove the username/password values from the startWebLogic script; the server will then prompt for a username/password when you start it.

Running Examples from Another Directory

You may want to install, build, and run the examples from a location other than where they were installed. This is useful if several developers are working with one WebLogic Server installation, or if you simply want to become accustomed to developing in a directory of your own choosing. It is also a best practice; keeping your domains in a separate location apart from you WebLogic installation helps keep potential conflicts to a minimum, and means you won't have multiple developers altering files that are inside WebLogic's own directories.

These instructions show you an example of how to set up your own directory structure to build and run examples from a location you choose using Windows Explorer. The general idea behind these steps are two-fold; you must copy the directory structure with the source files of the examples to your own location and also inform WebLogic Server where your new domain resides. WebLogic will know where your new domain is located as long as you modify the following files as instructed below: examples.properties, startExamplesServer, and config.xml files.