WebLogic Server Examples Guide
Contents
- Introduction
- Downloading Additional Examples
- Basic Steps for Using the Examples
- The Examples Web Application
- More About Setting Up Your Environment
- Setting Up Your Environment for Type 2 Drivers
- More About Building Examples and examples.properties
- The Examples Database
- Examples Passwords and Server Start Up
- Running Examples from Another Directory
- Running the Examples Server Using the JRockit JVM
- Using Development or Production Mode To Run Examples
- Setting up WebLogic Clusters for the Examples
- Troubleshooting
Introduction
This guide is a reference for the examples * that are packaged with WebLogic Server. Other examples are available in the BEA dev2dev Code Library.
Here is an example of what to set in .bash_profile to enable WLS environment variables:
# .bash_profile BEA_HOME=/usr/local/bea WL_HOME=$BEA_HOME/weblogic81 SAMPLES_HOME=$WL_HOME/samples export BEA_HOME WL_HOME SAMPLES_HOME
All source files are located under...
$SAMPLES_HOME/server/examples/src
The examples domain, which contains compiled and packaged sample applications, XML configuration files, and startup and environment scripts, can be found under...
$SAMPLES_HOME/domains/examples
Client and server classes required by the examples and PointBase, as well as documentation and scripts to start, stop, and open the console for the PointBase database, can be found under...
$WL_HOME/common/eval
The overview-summary page...
$SAMPLES_HOME/samples/server/examples/src/overview-summary.html
...has links to all the WebLogic examples.
Links to running examples can be found at:
http://www.setgetweb.com:7001/examplesWebApp/index.jsp *
Downloading Additional Examples
The BEA dev2dev Code Library provides many free code files for use with your BEA software. These examples include both BEA-certified and non-certified examples created by fellow developers. The examples are distributed as .zip files that you can unzip into an existing WebLogic Server samples directory structure. After unzipping a downloaded file, you build and run the new examples in the same manner as you would an installed WebLogic Server example.
Basic Steps for Using the Examples
These instructions describe the main tasks for running 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. The More Info links explain 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 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. A script is included that will set all these values :
- Open a command window.
- Move to the examples configuration directory: cd $SAMPLES_HOME/domains/examples.
- 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 'out-of-the-box' examples pop up in a window when you start the examples domain with WebLogic Server. The other WebLogic examples start off as Java source files that must be compiled into class files. Your WebLogic Server installation includes ant scripts in XML files; running these scripts will build the corresponding example. Here are the general steps:
- Move to the directory of the example you want to use:
cd SAMPLES_HOME/server/examples/src/examples/directoryName
- If the package-summary.html file for your example instructs you to do so, edit the examples.properties file at SAMPLES_HOME/server/examples/src. The Ant task uses this file to set system properties.
- Enter ant to run the build script in the build.xml file, which resides in your examples directory. (If your example's instructions indicate a different Ant target or build command, follow the documentation).
Starting the Examples Server
Start the examples server as follows.
On Windows:
- On the taskbar, click Start.
- Choose...
Programs | BEA WebLogic Platform 8.1 | Examples | WebLogic Server Examples | Launch WebLogic Server Examples.
Or ...
- In a command shell window, go to...
SAMPLES_HOME/domains/examples
- Enter startExamplesServer.cmd
On UNIX Bourne shell:
- cd $SAMPLES_HOME/domains/examples
- sh ./startExamplesServer.sh
NOTE: By default, the examples server uses the port 7001 to listen for incoming connections. The MedRec server also uses the same listen port by default, which means that you cannot run both domains at the same time without changing one of the listen ports. If you want to run both domains at the same time, use the WebLogic Server Administration Console to change the listen port of the examples server to something other than 7001, then restart it. You will now be able to start the MedRec server using its default listen port at the same that you run the examples server.
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:
- Start the examples server.
- Open a browser and point it to HTTP://localhost:7001/console.
- 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 command executes 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. The example's package-summary.html contains 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. Many such examples are included in one Web Application called examplesWebApp, located in...
$SAMPLES_HOME/server/examples/build/examplesWebApp
Where required, each example contains specific instruction on using the examplesWebApp.
Follow these steps if you wish to verify that the examplesWebApp has been deployed:
- Start the WebLogic Server Administration Console.
- Go to:
Deployments | Web Applications | Modules | examplesWebApp | Targets
- Verify that the examplesServer target is checked.
- If the examplesServer is not targeted, mark the checkbox next to examplesServer and click 'Apply.'
More About Setting Up Your Environment
The setExamplesEnv script at SAMPLES_HOME/domains/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. 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
- EXAMPLES_CONFIG - location of examples Weblogic Server instance
- EXAMPLE_HOME - root of examples source
- EXAMPLES_BUILD - root location where example applications are deployed and where client and server classes are compiled
- 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, 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/domains/examples
or
SAMPLES_HOME/server/examples/build.
If you are modifying the examples on your own, you can run the setExamplesEnv script and use these variables when you develop, so you do not have to reset them each time.
The syntax for using environment variables varies by platform. If, for example, you are using the CLIENT_CLASSES variable:
On Windows enter: %CLIENT_CLASSES%
On UNIX platforms enter: $client.classes.dir
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. Because 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 varies 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/jdkXXX/lib/tools.jar
- WL_HOME/server/lib/weblogic_sp.jar
- WL_HOME/server/lib/weblogic.jar
- WL_HOME/server/lib/ojdbc14.jar
- WL_HOME/server/lib/webservices.jar
- WL_HOME/server/lib/ejbgen.jar
- SAMPLES_HOME/samples/server/examples/build/clientclasses
- SAMPLES_HOME/samples/server/examples/build/serverclasses
- SAMPLES_HOME/samples/server/examples/build/examplesWebApp/WEB-INF/classes
- WL_HOME/common/eval/pointbase/lib/pbclient44.jar
- WL_HOME/common/eval/pointbase/lib/pbserver44.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/examples/src.
By default, when you download WebLogic Server, the examples.properties file looks like this:
#############################################
# This file contains property settings for #
# use in Examples' ant build scripts. #
#############################################
### General locations ###
bea.home=C:/bea
wl.home=C:/bea/weblogic81
samples.home=C:/bea/weblogic81/samples
### WebLogic configuration ###
-- Configure per your WLS installation.
port=7001
wls.username=weblogic
wls.password=weblogic
wls.server.name=examplesServer
### Examples src and domain directory locations ###
-- Configure per your Examples source location.
examples.home.dir=C:/bea/weblogic81/samples/server/examples
examples.domain.dir=C:/bea/weblogic81/samples/domains/examples
-- Examples locations.
examples.src.dir=${examples.home.dir}/src
examples.build.dir=${examples.home.dir}/build
apps.dir=${examples.domain.dir}/applications
client.classes.dir=${examples.build.dir}/clientclasses
common.dir=${examples.build.dir}/common
ex.webapp.dir=${examples.build.dir}/examplesWebApp
ex.webapp.webinf.dir=${ex.webapp.dir}/WEB-INF
ex.webapp.classes.dir=${ex.webapp.webinf.dir}/classes
main.webapp.dir=${examples.build.dir}/mainWebApp
server.classes.dir=${examples.build.dir}/serverclasses
-- Example specific locations
xml.registry=${examples.domain.dir}/xml/registries/examplesXMLRegistry
### Examples classpath ###
ex.classpath=${client.classes.dir};${java.class.path}
### Ant evaluted o/s ###
win.os="Windows XP,Windows 2000,Windows NT,Windows 98,Windows 95"
unix.os="HP-UX,Solaris,SunOS,AIX,Linux"
### Database properties ##
-- These user defined properties are available to automate
-- table setup for those examples that use an Oracle database.
db.host=samples
db.port=1521
sid=samples
db.user=scott
db.password=tiger
# (Optional) Used only for Weblogic OCI JDBC driver
db.server=samples
### Compile options ###
-- See Ant documentation for more information on build.compiler.
compiler=modern
debug=yes
deprecation=yes
debug=false
Use a text editor to edit examples.properties if necessary--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.4. PointBase Server is a pure Java relational database management system (RDBMS) that is included with WebLogic Server. It allows you to run code examples with a functional database server. For more information on PointBase and the examples, see the PointBase page. You can also run the examples with Oracle as the database; for instructions on how to do so, see the database setup page.
Examples Passwords and Server Startup
The examples domain uses weblogic/weblogic as its username/password combination. The username/password combination is encrypted in the boot.properties file in the examples server domain directory.
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 actually starts the server and sets the following parameters:
-Dweblogic.management.username=%WLS_USER%
-Dweblogic.management.password=%WLS_PW%
If you ever need to change your username/password for the examples domain, you will have to change the values in the startExamplesServer script.
In the default configuration, the server starts up without prompting for a password. To re-enable start-up security, 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 want to develop in a directory of your own choosing. It is also a best practice; keeping your domains in a separate location apart from your WebLogic installation helps keep potential conflicts to a minimum, and means you will not have multiple developers altering files that are inside WebLogic Server'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. 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. To do so, modify the examples.properties, startExamplesServer, and setExamplesEnv files:
- In a directory outside the WebLogic Server product directory, make a new directory for example source files. For clarity, it is assumed in this procedure that the directory is called /myexamples_home.
- Using the Configuration Wizard create a new examples domain located in the /myexamples_home directory. Follow these guidelines when using the Configuration Wizard:
- In the "Select a Configuration Template" window, select "Weblogic Server Examples Domain".
- In the "Create WebLogic Configuration" window, click the "Browse" button at the bottom and browse to the /myexamples_home directory. Enter /myexamples_home/domains in the "Location" text field, and click OK. Ensure that when you create the new examples domain, its location is /myexamples_home/domains/examples.
- Use the defaults for all other wizard windows.
- Move to the /myexamples_home/domains/examples directory.
- Edit the startExamplesServer and setExamplesEnv
scripts, and set the SAMPLES_HOME variable to /myexamples_home, as shown in the following excerpt of the startExamplesServer file:
@rem *************************************************************************
@rem PointBase and examples domain specific configuration
set SAMPLES_HOME=/myexamples_home
set EXAMPLES_CONFIG=$SAMPLES_HOME/domains/examples
set EXAMPLES_HOME=$SAMPLES_HOME/server/examples
set EXAMPLES_BUILD=%EXAMPLES_HOME%/build
set APPLICATIONS=%EXAMPLES_CONFIG%/applications
set CLIENT_CLASSES=%EXAMPLES_BUILD%/clientclasses
set SERVER_CLASSES=%EXAMPLES_BUILD%/serverclasses
set COMMON_CLASSES=%EXAMPLES_BUILD%/common
set EX_WEBAPP_CLASSES=%EXAMPLES_BUILD%/examplesWebApp/WEB-INF/classes - Under the /myexamples_home directory, create a server sub-directory.
- Copy the installed examples directory, SAMPLES_HOME/server/examples, and its contents to /myexamples_home/server.
- Edit the examples.properties file in the /myexamples_home/server/examples/src directory to change the value of the samples.home, examples.home.dir, and examples.domain.dir variables (shown in blue):
#############################################
# This file contains property settings for #
# use in Examples' ant build scripts. #
#############################################
### General locations ###
bea.home=C:/bea_new
wl.home=C:/bea_new/weblogic81
samples.home=C:/myexamples_home
### WebLogic configuration ###
-- Configure per your WLS installation.
port=7001
wls.username=weblogic
wls.password=weblogic
wls.server.name=examplesServer
### Examples src and domain directory locations ###
-- Configure per your Examples source location.
examples.home.dir=C:/myexamples_home/server/examples
examples.domain.dir=C:/myexamples_home/domains/examples
-- Examples locations.
examples.src.dir=${examples.home.dir}/src
examples.build.dir=${examples.home.dir}/build
apps.dir=${examples.domain.dir}/applications
client.classes.dir=${examples.build.dir}/clientclasses
common.dir=${examples.build.dir}/common
ex.webapp.dir=${examples.build.dir}/examplesWebApp
ex.webapp.webinf.dir=${ex.webapp.dir}/WEB-INF
ex.webapp.classes.dir=${ex.webapp.webinf.dir}/classes
main.webapp.dir=${examples.build.dir}/mainWebApp
server.classes.dir=${examples.build.dir}/serverclasses
-- Example specific locations
xml.registry=${examples.domain.dir}/xml/registries/examplesXMLRegistry
### Examples classpath ###
ex.classpath=${client.classes.dir};${java.class.path}
### Ant evaluted o/s ###
win.os="Windows XP,Windows 2000,Windows NT,Windows 98,Windows 95"
unix.os="HP-UX,Solaris,SunOS,AIX,Linux"
### Database properties ##
-- These user defined properties are available to automate
-- table setup for those examples that use an Oracle database.
db.host=samples
db.port=1521
sid=samples
db.user=scott
db.password=tiger
# (Optional) Used only for Weblogic OCI JDBC driver
db.server=samples
### Compile options ###
-- See Ant documentation for more information on build.compiler.
compiler=modern
debug=yes
deprecation=yes
debug=false
Now you can run the examples from the /myexamples_home directory. Build and run the examples according to the instructions in the example's documentation that you wish to run.
Running the Examples Server Using the JRockit JVM
The setExamplesEnv script calls another script, WL_HOME/common/bin/commEnv, to set the default JVM used in your environment. If you want to run the examples server using the JRockit JVM, edit the commEnv script:
-
Open the WL_HOME/common/bin/commEnv.cmd or
WL_HOME/common/bin/commEnv.sh (for Unix platforms)
script in a text editor. Look for lines similar to:
if [ "$1" != "USE_CURRENT_JAVA_HOME" ]; then # Set up JAVA HOME JAVA_HOME="C:/bea/jdk141_02" # Set up JAVA VENDOR, possible values are #BEA, HP, IBM, Sun ... JAVA_VENDOR=Sun # PRODUCTION_MODE, default to the development mode PRODUCTION_MODE="" fi
-
Change the JAVA_HOME and JAVA_VENDOR
variables to specify the JRockit JVM, as in:
if [ "$1" != "USE_CURRENT_JAVA_HOME" ]; then # Set up JAVA HOME JAVA_HOME="C:/bea/jrockit81_141_02" # Set up JAVA VENDOR, possible values are #BEA, HP, IBM, Sun ... JAVA_VENDOR=BEA # PRODUCTION_MODE, default to the development mode PRODUCTION_MODE="" fi
- Set your environment according to the instructions in Basic Steps for Using the Examples.
Using Development or Production Mode To Run Examples
You can run the WebLogic Server examples in either Production or Development mode. In Development mode, applications stored in a domain are dynamically deployed, that is, deployed automatically when you start the server; in Production mode, this is not the case and deploy an application manually. For instructions on deploying applications, see the Deployment page. By default, when you start the examples server, the examples domain is in development mode.
To change a domain's mode:
- Use a text editor to open the start script for your domain:
SAMPLES_HOME/domains/examples/startExamplesServer.
The filename extensions vary for Windows and UNIX. - Edit the line that begins set STARTMODE= to add the value True or False. It looks like this:
@rem Set Production Mode. When this is set to true, the server starts up in
@rem production mode. When set to false, the server starts up in development
@rem mode. If it is not set, it will default to false.
set STARTMODE=
True is for production mode, and false or no value is for development mode.
Clustering
Some examples demonstrate how to use WebLogic Server in clusters. You can also run any example in a clustered environment. For information on clusters and how to set them up, read the Examples Cluster Guide and the general WebLogic Clustering Documentation.
Troubleshooting
-
The server starts with the error
java.net.BindException - Address already in use.
You can continue safely with this error. It means that the PointBase database has already been started by another process. If you see this error, simply disregard it.
- Receive a Page cannot be displayed or a
Error 404 - Not found error when attempting to
access the server with a browser.
This can happen if your browser is set up to access all URLs through a proxy server. If the machine running WebLogic Server is not registered with the proxy server, you will receive a URL failure from your browser. To fix this, you can configure your browser to not use the proxy server, or to not use the proxy server to access an address that begins with the name of the machine running WebLogic Server.