Q. How do I provide user credentials for starting a server?
A. When you create a domain, the Configuration Wizard prompts you to provide the username
and password for an initial administrative user. If you create the domain in development mode,
the wizard saves the username and encrypted password in a boot identity file. A WebLogic Server
instance can refer to a boot identity file during its startup process. If a server instance does not
find such a file, it prompts you to enter credentials.
If you create a domain in production mode, or if you want to change user credentials in an existing
boot identity file, you can create a new boot identity file. WebLogic Server does not support
copying a boot identity file from one server root directory to another. For information on creating
and using boot identity files, see “Boot Identity Files” in Administration Console Online Help.
Q. Can I start a Managed Server if the Administration Server is unavailable?
FAQs: Administration and Configuration
A. By default, if a Managed Server is unable to connect to the specified Administration Server
during startup, it can retrieve its configuration by reading a configuration file and other files
directly. You cannot change the server’s configuration until the Administration Server is
available. A Managed Server that starts in this way is running in Managed Server Independence
mode. For more information, see “Starting a Managed Server When the Administration Server Is
Not Accessible” in Configuring and Managing WebLogic Server.
Q. What is the easiest way to set the classpath?
WebLogic Server installs the following script that you can use to set the classpath that a server
WL_HOME\server\bin\setWLSEnv.cmd (on Windows)
WL_HOME/server/bin/setWLSEnv.sh (on UNIX)
where WL_HOME is the directory in which you installed WebLogic Server. For more information,
see “Setting the Classpath” in the WebLogic Server Command Reference.
Q. How do I edit the config.xml file?
A. The persistent configuration for a domain of WebLogic Servers and clusters is stored in an
XML configuration file (config.xml). You can modify this file in the following ways:
Use the Administration Console. See “Using the Administration Console” in the
Administration Console Online Help.
If you want to create scripts that automate domain management, use the weblogic.Admin
utility. See “weblogic.Admin Command-Line Reference” in the WebLogic Server
If you want to create Java-based management applications, use the Java Management
Extensions (JMX) Application Programming Interface (API). See the Programming
WebLogic Management Services with JMX guide.
If you want to edit the config.xml file directly (not recommended), see the BEA
WebLogic Server Configuration Reference.
Q. Is there a quick way to create and start a remote Managed Server?
A. The recommended approach is to use the Domain Configuration Wizard, as described in
"Setting Up and Starting Managed Servers on a Remote Machine" in Creating WebLogic
Configurations Using the Configuration Wizard at
For a streamlined approach, follow the instructions at “Starting Managed Servers From a
WebLogic Server Script” in the Administration Console Online Help.
Q. The Tree View pane of the WebLogic Console is not visible in my browser. How do I enable
A. Enable the Sun Java Plug-In from the control panel.
FAQs: Administration and Configuration
Q. What are the alternatives to using applets?
A. BEA supports the use of server-side applications with HTTP servlets and Java Server Pages
(JSPs) as part of the J2EE platform. We recommend that before you develop new applications,
consider using either servlets or JSPs. A well-designed series of interactive Web pages using
servlets and Java Server Pages (JSPs) generally yield a faster and more reliable Web site.If you
are currently using applets, you may find that most can be converted to Java applications using
Java Web Start and you can continue using WebLogic Server. For information, go to Sun's Java
Web Start site.
For more information, see Using Applets With WebLogic Server at
Q. Can I use a “native” two-tier driver for a browser applet?
A. No. Within an unsigned applet, you cannot load native libraries over the wire, access the local
file system, or connect to any host except the host from which you loaded the applet. The applet
security manager enforces these restrictions on applets as protection against applets being able to
do unsavory things to unsuspecting users.
If you are trying to use jDriver for Oracle from an applet, then you are violating the first
restriction. Your applet will fail when it attempts to load the native (non-Java layer) library that
allows jDriver for Oracle to make calls into the non-Java Oracle client libraries. If you look at the
exception that is generated, you will see that your applet fails in
java.lang.System.loadLibrary, because the security manager determined that you were
attempting to load a local library and halted the applet.
You can, however, use the WebLogic JTS or Pool driver for JDBC connectivity in applets. When
you use one of these WebLogic multitier JDBC drivers, you need one copy of WebLogic jDriver
for Oracle (or any other two-tier JDBC driver) for the connection between the WebLogic Server
and the DBMS.
Q. Why doesn’t my browser applet connect to the database?
Problem: I’m using a WebLogic multitier driver in an applet as an interface to a DBMS. If I run
the class using the Sun Appletviewer on my local machine, I have no problems. But when I try
to run the applet in a Netscape browser, it will not connect.
A. If Appletviewer works and Netscape does not, it is an indication that you are violating a
Netscape security restriction. In this case, the violation is that an applet cannot open a socket to
a machine other than the one from which it loaded the applet. To solve this problem, you will
have to serve your applet code from the same machine that hosts the DBMS.
In addition, the IP naming format you use in the applet CODEBASE and the constructor for the
T3Client must match. That is, you can’t use dot-notation in one place and a domain name in the
Q. Why does my applet work with Appletviewer, but not with a browser?
Problem: I tried to run two of the applets in the examples directory of the distribution. I installed
the WebLogic classes on my local machine (NT server) and on another machine (a Windows 95
client). I am not using any browsers, just trying to run the applets with Appletviewer. The applets
work fine when I run Appletviewer from the NT server, but do not work at all from the Windows
A. There are two possible problems: Either the CODEBASE tag is not properly set in the applet
HTML file, or the class files are not properly loaded on the HTTP server.
The applet works on the NT server because you installed the WebLogic distribution on your NT
server. Even if the applet cannot successfully load the necessary classes from the HTTP server,
it does find them in your local CLASSPATH. But when you try to run it from the Windows 95 client,
the applet must load the classes over the wire from the HTTP server, and if you haven’t installed
them correctly, it will fail.
Q. What’s causing ClassFormatErrors with my applet?
Problem: I downloaded your distribution and copied the classes to my HTTP server
DocumentRoot. I created an applet that I ran successfully from my Netscape server. I placed it in
the server directory /webz/ns-home/classes/applets/myapp.class and called it with the
Then I set my attributes in the Administration Console to listen on port 7001, and I started the
WebLogic Server on the HTTP machine so I could use my applet with WebLogic JDBC, like this:
When I changed the CODEBASE tag to point to the WebLogic Server, I started getting
A. There are several problems with your setup. The most obvious have to do with your
1. The CODEBASE tag in your applet should point to your HTTP server, not to WebLogic Server.
2. The directory path referenced in your CODEBASE tag is not an absolute directory path on the
HTTP server; it is a configured path that originates from the HTTP Document Root. You
are using the absolute path in your CODEBASE tag. If your class “myapp” is in the “applets”
package, then the correct CODEBASE for your setup would be:
In addition, if you are getting a ClassFormatError, it signals a problem with your HTTP server
configuration. It could be that you haven’t loaded the WebLogic or applet classes in the correct
directory on the HTTP server, or you are specifying the CODEBASE or the CODE incorrectly in your
Remember, too, that if you installed the WebLogic distribution on the machine from which you
are running the applet, your applet will first look for the WebLogic classes in your local
CLASSPATH, which may obscure the fact that you haven’t properly installed the classes for
serving from the HTTP server. To test your HTTP configuration properly, you need to
temporarily rename the WebLogic classes in your local CLASSPATH or try your applet from
Q. How do stubs work in a WebLogic Server cluster?
A. Clients that connect to a WebLogic Server cluster and look up a clustered object obtain a
replica-aware stub for the object. This stub contains the list of available server instances that host
implementations of the object. The stub also contains the load balancing logic for distributing the
load among its host servers.
Q. What happens when a failure occurs and the stub cannot connect to a WebLogic Server
A. When the failure occurs, the stub removes the failed server instance from its list. If there are
no servers left in its list, the stubb uses DNS again to find a running server and obtain a current
list of running instances. Also, the stub periodically refreshes its list of available server instances
in the cluster; this allows the stub to take advantage of new servers as they are added to the cluster.
Q. How does a server know when another server is unavailable?
A. WebLogic Server uses two mechanisms to determine if a given server instance is unavailable.
Each WebLogic Server instance in a cluster uses multicast to broadcast regular “heartbeat”
messages that advertise its availability. By monitoring heartbeat messages, server instances in a
cluster determine when a server instance has failed. The other server instances will drop a server
instance from the cluster, if they do not receive three consecutive heartbeats from that server
WebLogic Server also monitors socket errors to determine the availability of a server instance.
For example, if server instance A has an open socket to server instance B, and the socket
unexpectedly closes, server A assumes that server B is offline.
Q. How are notifications made when a server is added to a cluster?
A. The WebLogic Server cluster broadcasts the availability of a new server instance each time
a new instance joins the cluster. Cluster-aware stubs also periodically update their list of
available server instances.
Q. How do clients learn about new WebLogic Server instances?
A. Once a client has done a JNDI lookup and begins using an object reference, it finds out about
new server instances only after the cluster-aware stub has updated its list of available servers.
Q. How do clients handle DNS requests to failed servers?
A. If a server fails and DNS continues to send requests to the unavailable machine, this can waste
bandwidth. For a Java client application, this problem occurs only during startup. WebLogic
Server caches the DNS entries and removes the unavailable ones, to prevent the client from
accessing a failed server twice.
Failed servers can be more of a problem for browser-based clients, because they always use DNS.
To avoid unnecessary DNS requests with browser-based clients, use a third-party load-balancer
such as Resonate, BigIP, Alteon, and LocalDirector. These products mask multiple DNS
addresses as a single address. They also provide more sophisticated load-balancing options than
round-robin, and they keep track of failed servers to avoid routing unnecessary requests.
Q. How many WebLogic Servers can I have on a multi-cpu machine?
A. There are many possible configurations and each has its own advantages and disadvantages.
BEA WebLogic Server has no built-in limit for the number of server instances that can reside in
a cluster. Large, multi-processor servers such as Sun Microsystems, Inc. Sun
therefore, can host very large clusters or multiple clusters.
In most cases, WebLogic Server clusters scale best when deployed with one WebLogic Server
instance for every two CPUs. However, as with all capacity planning, you should test the actual
deployment with your target web applications to determine the optimal number and distribution
of server instances. See Performance Considerations for Multi-CPU Machines for additional
Q. Should I use a separate network for multicast in a cluster?
A. No. Multicast traffic is not heavy enough to require a separate network.
Q. What should I do if my cluster “hangs” or “freezes”?
A. If your WebLogic Server cluster “freezes,” you will need to collect certain diagnostic
information, including thread dumps and Java garbage collection metrics, before contacting BEA
Technical Support. For details, see Generate a Log File.
Q. Where are the examples located?
A. Examples, if installed, are located in the
BEA_HOME\samples\server\examples\src\examples directory, where BEA_HOME refers to
the main WebLogic Platform directory. To invoke a Web page that describes the examples, see
the Start menu on Windows.
Q. Why won’t the examples work?
A. Each example comes with detailed instructions for building the example class files,
configuring the server, and running the example. Make sure that you have completed each of the
FAQs: Code Examples
Usually problems with examples are related to your environment. Here are some troubleshooting
1. If you are using a database, make sure you have run the utility utils.dbping to verify that
your JDBC driver is correctly installed and configured.
2. Run the setEnv script to make sure your CLASSPATH is correctly set in the shell or DOS
window in which you are running the examples.
3. Check the instructions for the examples to make sure you have changed any user-specific
variables in the code before compiling.
4. Verify that you are compiling with the -d option to direct the class files into the proper
directory, as defined in the example instructions.
If the example is an applet, check the CODE and CODEBASE, and make sure WebLogic Server
For more information, see the WebLogic Server Examples Guide located at
BEA_HOME\samples\server\examples\src\examples\examples.html, where BEA_HOME
refers to the main WebLogic Platform directory.
Q. Are the build.cmd and the build.sh scripts still being used?
A. No. They have been replaced by
Q. How do I use ANT?
A. Set up the Examples domain environment by running setExamplesEnv.cmd in Windows or
setExamplesEnv.sh in UNIX. Go into your examples directory and type ANT to build the
build.xml file. If you want to build your own build script, you can pass in the name of the build
script by typing ANT -f myBuild.xml where myBuild is the name of your build script. For
more information, see the Apache website.
Q. Why do I have trouble targeting a PointBase connection pool to a remote server?
A. Open the commEnv.cmd or .sh file in WL_HOME\common\bin and edit the
POINTBASE_CLASSPATH entry by removing the bolded section of the entry shown below:
Q. Why do I get an error if I attempt to start the MedRec Server on a system that uses a proxy to
connect to the Internet?
A. The MedRec Server uses the Struts framework and its attempts to access
jakarta.apache.org on startup result in error messages. The server starts up successfully, but
with error messages. Adding the following options to MedRec Server’s start script resolves the
Q. Can I use the PointBase DBMS included with WebLogic Server for development or
A. PointBase Server is an all-Java DBMS product included in the WebLogic Server distribution
soley in support of WebLogic Server evaluation, either in the form of custom trial applications or
through packaged sample applications provided with WebLogic Server. Non-evaluation
development and/or production use of the PointBase Server requires a separate license be
obtained by the end user directly from PointBase.
FAQs: Code Examples
Q. How can I set deployment order for applications?
A. WebLogic Server 8.1 allows you to select the load order for applications. See the
ApplicationMBean LoadOrder attribute in Application. WebLogic Server deploys server-level
resources (first JDBC and then JMS) before deploying applications. Applications are deployed in
this order: connectors, then EJBs, then Web Applications. If the application is an EAR, the
individual components are loaded in the order in which they are declared in the
application.xml deployment descriptor.
Q. Can I refresh static components of a deployed application without having to redeploy the
A. Yes. You can use weblogic.Deployer to specify a component and target a server, using the
java weblogic.Deployer -adminurl http://admin:7001 -name appname -targets
server1,server2 -deploy jsps/*.jsp
Q. When should I use the -nostage option?
A. Set the staging mode to -nostage (using weblogic.Deployer or the Administration
Console) if you don’t want to copy deployment files but want to deploy an application from its
present location. All target servers must be able to access the same set of deployment files.
Q. When should I use the external_stage option?
A. Set -external_stage using weblogic.Deployer if you want to stage the application
yourself, and prefer to copy it to its target by your own means.
Q. Can I generate deployment descriptor files automatically?
A. Yes, WebLogic Builder automatically generates deployment descriptor files for your J2EE
applications. See WebLogic Builder Online Help.
Q. Can I set the deployment order for application modules? For standalone modules?
A. The Load Order attribute controls the deployment order of standalone modules and
applications relative to other modules and applications of the same type. For example, standalone
EJBs with smaller Load Order values are deployed before those with higher values.
Modules that are deployed as part of an Enterprise Application (EAR file or directory) are
deployed in the order in which they are specified in the application.xml deployment
Q. What is the difference between the WL_HOME/config/examples/applications folder and
the WL_HOME/config/examples/stage folder?
A. The applications folder is intended for applications that are not yet ready for a production
environment. WebLogic Server dynamically deploys the contents of the applications folder.
The stage folder (or a folder that you create for the same purpose) is for storing copies of
deployment files that are ready for deployment in a production environment (deployments that
use the stage or external_stage deployment modes).
Q. How do I turn the auto-deployment feature off?
A. The auto-deployment feature checks the applications folder every three seconds to determine
whether there are any new applications or any changes to existing applications and then
dynamically deploys these changes.
The auto-deployment feature is enabled for servers that run in development mode. To disable
auto-deployment feature, use one of the following methods to place servers in production mode:
In the Administration Console, click the name of the domain in the left pane, then select
the Production Mode checkbox in the right pane.
At the command line, include the following argument when starting the domain’s
Production mode is set for all WebLogic Server instances in a given domain.
Q. Where can I learn more about WebLogic 8.1 deployment?
A. Here: Deployment at http://e-docs.bea.com/wls/docs81/deployment.html.
Q. Why is there no polymorphic-type response from a create() or find() method?
A. The EJB Specification prohibits this behavior, and the weblogic.appc compiler checks for
this behavior and prohibits any polymorphic type of response from a create() or find()
The reason the create() and find() methods are not polymorphic is similar to the reason
constructors are not polymorphic in Java. The derived classes generally do not know or cannot
initialize the base class properly.
Q. Must EJBs be homogeneously deployed across a cluster? Why?
A. Yes. In WebLogic Server 6.0 and later, EJBs must be homogeneously deployed across a
cluster for the following reasons:
To keep clustering EJBs simple
To improve performance by avoiding cross-server calls. If EJBs are not deployed on all
servers, cross-server calls are more likely.
To ensure that every EJB is available locall.y
To ensure that all classes are loaded in an undeployable way. Every server must have
access to each EJB's classes so that it can be bound into the local JNDI tree. If only a
subset of the servers deploys the bean, the other servers will have to load the bean's classes
in their respective system classpaths which makes it impossible to undeploy the beans.
Q. What is the free pool?
A. The free pool is a data structure the EJB container uses to cache anonymous instances of a
given bean type. The free pool improves performance by reusing objects and skipping container
callbacks when it can.
Q. Where can I get a copy of the EJB specification?
A. You can download it from Sun's EJB site. Point your browser to:
Q. Which versions of the EJB specification are supported by WebLogic Server?
A. The following table summarizeds EJB specification support by WebLogic Server version:
Q. How should I set max-beans-in-free-pool for stateless beans?
A. This is explained in “Pooling for Stateless Session EJBs” in Programming WebLogic
Q. How should I set initial-beans-in-free-pool for stateless beans?
A. This is explained in “Pooling for Stateless Session EJBs” in Programming WebLogic
Q. When are stateless EJBs passivated?
A. Stateless ejbs are never passivated. Since stateless ejbs do not have state, there is no need to
passivate them. They are put back into the free pool after each method call so they will be
available to service other requests.
Q. Can I call remove() on a stateless session bean?
A. Yes. Currently, calling remove() on a stateless session bean is a noop.
Q. When are ejbCreate and ejbRemove called on stateless EJBs?
A. When the stateless beans are created and removed by the EJB container. Note that this does
not correspond to calls to create and remove on the stateless home. Depending on your
initial-beans-in-free-pool setting, beans may be created by the container during
deployment at which point they are placed in the free pool. Aside from during deployment, beans
will only be created to service requests when all of the beans in the free pool are in use and the
WebLogic Server Version EJB Version
6.0 1.1 and 2.0 (PFDI)
6.01 1.1 and 2.0
7.0 1.1 and 2.0
8.1 1.1 and 2.0
max-beans-in-free-pool limit has not been met. Stateless beans are removed by the EJB
container during undeployment.
Q. Can you explain passivation / activation?
A. Passivation and activation are a standard part of a stateful session bean’s lifecycle. For details,
see Stateful Session EJB Life Cycle in Programming WebLogic Enterprise JavaBeans.
Q. Why did I get a LockTimedOutException?
A. When you get a LockTimedOutException while invoking a stateful session EJB, one of two
things has occurred:
descriptor and your call timed out while waiting to be processed. The timeout used in this
case is the value
descriptor or its default value of 30 seconds.
You do not have
stateful session bean that is already busy processing another request. In this case, the
second method call will not block and a LockTimedOutException will be thrown
Q. What is the difference between the NRU and LRU cache?
A. NRU cache works by avoiding passivation as much as possible. Stateful session instances are
only passivated when there is memory pressure (your # of beans in the cache approaches the
max-beans-in-cache size). This is the 'NRU' option in the weblogic-ejb-jar.xml and the
default behavior. The LRU cache works by passivating a bean after it reached its
idle-timeout-seconds. So if your max-beans-in-cache was 1000 and you only had 10 beans in
memory, it would still write the 10 beans to disk after their timeout period expired. This is the
'LRU' option in weblogic-ejb-jar.xml. This was added to 5.1 and 6.x because there were
some customers that wrote applications depending on the timeout behavior. The was also the
default behavior in 3.1-4.5.
Q. When should I use a Stateful session bean and when should I use a servlet session?
A. The answer to this question is very application-specific and there are situations in which
either approach will work. A stateful session bean provides declaritive transaction and security
checking as well as failover to a secondary in a cluster.
Q. How big should I make the cache for a stateful session bean?
A. The cache for a stateful session bean should usually be equal to the maximum number of
concurrent clients of the bean. This is generally a much larger value than the number of execute
threads in the server, therefore, stateful session beans will use more server resources.
Q. Can an entity bean be a listener for JMS messages?
A. No. Message driven beans should be used to consume JMS messages.
Q. When are CMP fields loaded? Is it always determined by the finders-load-bean setting?
What is the default behavior?
A. Finders-load-bean is true by default. A bean is retrieved via a finder explicitly if you call a
findXXX() method to get the bean and implicitly if you retrieve the bean via a cmr-field getXXX
method. Either of these will result in eager loading of the bean's fields if finders-load-bean is true
for the bean.
If you aren't calling a finder, but just accessing the bean via a reference you obtained in a different
transaction, then fields are always loaded lazily when using 2.0 CMP, i.e. they aren't read from
the DBMS during ejbLoad, but rather when a getXXX() method is called. By default there is a
single field group that contains all the fields if you don't define any field groups. So, calling a
cmp-field getXXX() method loads all of the persistent state of the bean by default.
Q. What's the purpose of the delay-database-insert-until deployment descriptor
A. This setting allows you to specify at what point the database insert occurs when creating a
CMP bean. Non-null foreign key constaints in your database can make creating CMP beans with
relationships tricky. We offer this setting to give developers more flexibility to satisfy those
constraints. Also, this setting is necessary to enable the bulk insert feature that was added in WLS
7.0. To enable the bulk insert feature and to provide yourself the maximum amount of flexibilty
to satisfy any non-null foreign key constraints, we recommend setting the
delay-database-insert-until option to commit. For more information, see Delaying Database
Inserts in Programming WebLogic Enterprise JavaBeans.
Q. Can I map an entity bean to more than one table?
A. In WLS 8.1 it is possible to map an entity bean to multiple tables, however, there are some
restrictions. Namely, each table must contain the same primary key columns. The columns can
have different names in different tables, but they must contain the same values. When a new bean
is created a row will be inserted in each table, and when a bean is removed a row is removed from
each table. The rows in each table are related via their primary key values. The rows mapped to
a particular entity bean will always have the same primary key value. See “Multiple Table
Mapping” in Programming WebLogic Enterprise JavaBeans.
Q. Can I use a join or intermediate table to implement a One-Many relationship?
A. This is currently not supported. One-Many relationships require that the bean on the Many
side of the relationship contain a foreign-key in one of its tables.
Q. Why can't I hold on to a cmr-field (Container Managed Relationship) collection and use it
after the transaction commits?
A. This is prohibited by the EJB 2.0 specification. The reason for disallowing this is that the
DBMS data backing a cmr-field collection can change in unpredictable ways once your
transaction commits. Tracking these changes is difficult and can result in the contents of the
cmr-field collection changing when the application doesn't expect it. The bottom line is that
developers must retrieve and access cmr-field collections within a single transaction.
Q. Can a foreign key column in the database be mapped to both a cmp-field and a cmr-field?
A. Yes, this has been supported since WLS 6.0 SP1. Note that when the cmp-field is a
primary-key field the cmr-field is read-only. In other words, the setXXX method for the cmr-field
cannot be used. The value of the primary-key should be initialized as usual in this case.
Conversely, when the cmp-field is not a primary-key field, then the cmp-field is read-only. The
underlying column is updated via the cmr-field, and the cmp-field just provides a read-only view
of the foreign-key.
Q. Why can't I call the setXXX method for a cmr-field during ejbCreate?
A. This is disallowed by the EJB 2.0 specification because the primary-key of the current bean
isn't necessarily known during ejbCreate and it may be needed depending on how the relationship
is mapped to the underlying DBMS. Cmr-field setters should be called during ejbPostCreate
instead of ejbCreate if relationships need to be setup during creation of a bean.
Q. How can I avoid violating NOT NULL constraints on foreign keys that are mapped to
A. In WLS 7.0 and later, you can set delay-database-insert-until to 'commit' and assign
the cmr-field a value before the current transaction commits. You can also set
delay-database-insert-until to 'ejbPostCreate' and assign the cmr-field a value during
Q. Does WebLogic support auto generating primary keys for entity beans?
A. Yes, this feature was added in WLS 6.1. For more information, see the DTD comments for
Q. Which security principal does an MDB use to connect to JMS?
A. As of WLS 6.1 SP2, an MDB uses the same principle to connect to JMS as it does to process
messages. This is either the principle that is mapped to the run-as role specified for the bean, or
'guest' if no run-as role is provided. Prior to WLS 6.1 SP2, this behavior was not well defined.
Q. How should I obtain my JDBC connection so that it participates in the EJB container's
A. You must get your JDBC connection from a TxDataSource or from the JTS driver. If you get
a JDBC connections from a plain DataSource or directly from the JDBC driver, it will NOT
participate in the EJB container transaction.
TxDataSources are recommended instead of accessing the JTS driver directly. TxDataSources
are the standard mechanism in JDBC 2.0 for connection pooling, and they support 2PC/XA
Q. My transaction aborted, but my database changes did not rollback.
A. See previous question. You must obtain your JDBC connections from a TxDataSource.
Q. Why did my JDBC code throw a rollback SQLException?
A. Your JDBC code may throw the following exception:
"The coordinator has rolled back the transaction.
No further JDBC access is allowed within this transaction."
The WebLogic JTS JDBC driver throws this exception when the current JDBC connection
transaction rolls back prior to or during the JDBC call. This exception indicates that the
transaction in which the JDBC connection was participating was rolled back at some point prior
to or during the JDBC call.
The rollback may have happened in an earlier EJB invoke that was part of the transaction, or the
rollback may have occurred because the transaction timed out. In either case, the transaction will
be rolled back, the connection returned to the pool and the database resources released. In order
to proceed, the JTS JDBC connection must be closed and reopened in a new transaction.
Q. Which platforms are available for WebLogic Server?
A. See the BEA WebLogic Server Supported Configurations page at
Q. I downloaded the WebLogic Server installation file, but the installation program will not run.
What should I do?
A. The installation file may have been corrupted during the download. Run a checksum on the
installation file and check with technical support for the proper values.
Q. Do I need to install WebLogic Server as root on Solaris?
A. No you don't need to be root, depending on directory permissions.
Q. Can I run the Configuration Wizard outside the installer?
FAQs: Instal lation
A. Yes. You can start the Configuration Wizard from the Start menu or using a script in the utils
directory. See Creating Domains and Servers in Configuring and Managing WebLogic Server.
Q. I love the new domain configuration wizard. Can I create my own templates?
A. Support for custom templates for the Configuration Wizard is coming soon. Currently, it is an
undocumented, unsupported feature.
Q. What is a remote JMS provider?
A. A remote JMS provider is a JMS server that is hosted outside a local stand-alone WebLogic
server or outside WebLogic server cluster. The remote JMS server may be a WebLogic or a
non-WebLogic (foreign) JMS server.
Q. What is JNDI?
A. JNDI (Java Naming and Directory Interface) is a J2EE lookup service that maps names to
services and resources. JNDI provides a directory of advertised resources that exist on a particular
stand-alone (unclustered) WebLogic server, or within a WebLogic server cluster. Examples of
such resources include JMS connection factories, JMS destinations, JDBC (database) data
sources, and application EJBs.
A client connecting to any WebLogic server in a WebLogic cluster can transparently reference
any JNDI advertised service or resource hosted on any WebLogic server within the cluster. The
client doesn't require explicit knowledge of which particular WebLogic server in the cluster hosts
a desired resource.
Q. What is a JMS connection factory?
A. A JMS connection factory is a named entity resource stored in JNDI. Applications, message
driven beans (MDBs), and messaging bridges lookup a JMS connection factory in JNDI and use
it to create JMS connections. JMS connections are used in turn to create JMS sessions, producers,
and consumers that can send or receive messages.
FAQs: Integrating Remote JMS Providers
Q. What is a JMS connection-id?
A. JMS connection-ids are used to name JMS client connections. Durable subscribers require
named connections, otherwise connections are typically unnamed. Note that within a clustered
set of servers or stand-alone server, only one JMS client connection may use a particular named
connection at a time. An attempt to create new connection with the same name as an existing
connection will fail.
Q. What is the difference between a JMS topic and a JMS queue?
A. JMS queues deliver a message to one consumer, while JMS topics deliver a copy of each
message to each consumer.
Q. What is a topic subscription?
A. A topic subscription can be thought of as an internal queue of messages waiting to be
delivered to a particular subscriber. This internal queue accumulates copies of each message
published to the topic after the subscription was created. Conversely, it does not accumulate
messages that were sent before the subscription was created. Subscriptions are not sharable, only
one subscriber may subscribe to a particular subscription at a time.
Q. What is a non-durable topic subscriber?
A. A non-durable subscriber creates unnamed subscriptions that exist only for the life of the JMS
client. Messages in a non-durable subscription are never persisted—even when the message's
publisher specifies a persistent quality of service (QOS). Shutting down a JMS server terminates
all non-durable subscriptions.
Q. What is a durable subscriber?
A. A durable subscriber creates named subscriptions that continue to exist even after the durable
subscriber exits or the server reboots. A durable subscriber connects to its subscription by
specifying topic-name, connection-id, and subscriber-id. Together, the connection-id and
subscriber-id uniquely name the subscriber’s subscription within a cluster. A copy of each
persistent message published to a topic is persisted to each of the topic's durable subscriptions. In
the event of a server crash and restart, durable subscriptions and their unconsumed persistent
messages are recovered.
Q. What is a transaction?
A. A transaction is a set of distinct application operations that must be treated as an atomic unit.
To maintain consistency, all operations in a transaction must either all succeed or all fail. See
“Introducing Transactions” in Programming WebLogic JTA.
Q. Why are transactions important for integration?
A. Integration applications often use transactions to assure data consistency. For example, to
assure that a message is forwarded exactly-once, a single transaction is often used to encompass
the two operations of receiving the message from its source destination and sending to the target
destination. Transactions are also often used to ensure atomicity of updating a database and
performing a messaging operation.
Q. What is a JTA/XA/global transaction?
A. In J2EE, the terms JTA transaction, XA transaction, user transaction, and global transaction
are often used interchangeably to refer to a single global transaction. Such a transaction may
include operations on multiple different XA capable resources and even different resource types.
A JTA transaction is always associated with the current thread, and may be passed from server to
server as one application calls another. A common example of an XA transaction is one that
includes both a WebLogic JMS operation and a JDBC (database) operation.
Q. What is a local transaction?
A. A JMS local transaction is a transacion in which only a single resource or service may
participate. A JMS local transaction is associated with a particular JMS session where the
destinations of a single vendor participate. Unlike XA transactions, a database operation can not
participate in a JMS local transaction.
Q. How does JMS provide local transactions?
A. Local transactions are enabled by a JMS specific API called transacted sessions. For
vendors other than WebLogic JMS, the scope of a transacted session is typically limited to a
single JMS server. In WebLogic JMS, multiple JMS operations on multiple destinations within
an entire cluster can participate in a single transacted session's transaction. In other words, it is
scoped to a WebLogic cluster and no remote JMS provider to the JMS session's cluster can
participate in a transaction. See the WebLogic JMS Performance Guide white-paper available on
the JMS topic page.
Q. Are JMS local transactions useful for integration purposes?
A. Local transactions are generally not useful for integration purposes as they are limited in
scope to a single resource, typically a messaging or database server.
Q. What is Automatic Transaction Enlistment?
A. Operations on resources such as database servers or messaging servers participate in a J2EE
JTA transaction provided that:
FAQs: Integrating Remote JMS Providers
the resource is XA transaction capable
the resource has been enlisted with the current transaction
the client library used to access the resource is transaction aware (XA enabled).
Automatic participation of operations on an XA capable resource in a transaction is technically
referred to as automatic enlistment.
WebLogic clients using XA enabled WebLogic APIs automatically enlist operation in the
current thread's JTA transaction. Examples of XA enabled WebLogic clients include
WebLogic JMS XA enabled (or user transaction enabled) connection factories, and JDBC
connection pool data sources that are global transaction enabled.
Foreign (non-WebLogic) JMS clients do not automatically enlist in the current JTA
transaction. Such clients must either go through an extra step of programmatically enlisting
in the current transaction, or use WebLogic provided features that wrap the foreign JMS
client and automatically enlist when the foreign JMS client is accessed via wrapper APIs.
JMS features that provide automatic enlistment for foreign vendors are:
JMS resource-reference pools
To determine if a non-WebLogic vendor's JMS connection factory is XA capable, check the
vendor documentation. Remember, support for transacted sessions (local transactions) does not
imply support for global/XA transactions.
Q. What does a JMS client do to communicate with a remote JMS provider?
A. To communicate with any JMS provider, a JMS client must perform the following steps:
a. Look up a JMS connection factory object and a JMS destination object using JNDI
b. Create a JMS connection using the connection factory object
c. Create message consumers or producers using the JMS connection and JMS destination
Q. What information do I need to set up communications with a remote JMS provider?
A. You will need the following information to set up communications with a remote JMS
The destination type—whether the remote JMS destination is a queue or a topic.
The JNDI name of the remote JMS destination.
For durable topic subscribers—the connection-id and subscriber-id names that uniquely
identify them. Message Driven EJBs provide default values for these values based on the
For non-WebLogic remote JMS providers
– Initial Context Factory Class Name— the java class name of the remote JMS Provider's
JNDI lookup service.
– The file location of the java jars containing the remote JMS provider's JMS client and
JNDI client libraries. Ensure that these jars are specified in the local JVM's classpath.
The URL of the remote provider's JNDI service. For WebLogic servers, the URL is
normally in the form t3://hostaddress:port. If you are tunneling over HTTP, begin
the URL with http rather than t3. No URL is required for server application code that
accesses a WebLogic JMS server that resides on the same WebLogic server or WebLogic
cluster as the application.
The JNDI name of the remote provider's JMS connection factory. This connection factory
must exist on the remote provider, not the local provider.
If the JMS application requires transactions, the connection factory must be XA capable.
WebLogic documentation refers to XA capable factories as user transactions enabled.
By default, WebLogic servers automatically provide three non-configurable connection
– weblogic.jms.ConnectionFactory—a non-XA capable factory.
– weblogic.jms.XAConnectionFactory—an XA-capable factory
– weblogic.jms.MessageDrivenBeanConnectionFactory—an XA-capable factory
for message driven EJBs.
Additional WebLogic JMS connection factories must be explicitly configured.
Q. What if a foreign JMS provider JNDI service has limited functionality?
A. The preferred method for locating JMS provider connection factories and destinations is to
use a standard J2EE JNDI lookup. Occasionally a non-WebLogic JMS provider's JNDI service
FAQs: Integrating Remote JMS Providers
is hard to use or unreliable. The solution is to create a startup class or load-on-start servlet that
runs on a WebLogic server that does the following:
– Uses the foreign provider's proprietary (non-JNDI) APIs to locate connection factories
and JMS destinations.
– Registers the JMS destinations and JMS connection factories in WebLogic JNDI.
For sample code, see “Creating Foreign JNDI Objects in a Startup Class” in Using Foreign
JMS Providers with WebLogic Server white-paper available from the JMS topic page.
Q. How can I pool JMS resources?
A. Remote and local JMS resources, such as client connections and sessions, are often pooled
to improve performance. Message driven EJBs automatically pool their internal JMS consumers.
JMS consumers and producers accessed through resource-references are also automatically
pooled. For more information on resource pooling, including information on writing a custom
pool, see the WebLogic JMS Performance Guide white-paper available on the JMS topic page.
Q. What version interoperability does WebLogic provide?
A. All WebLogic server releases 6.1 and higher interoperate freely between releases. For
example, a WebLogic 8.1 JMS client can send messages directly to a 6.1 JMS server and vice
WebLogic server releases 6.1 and higher.
Q. What tools are available for integrating with remote JMS providers?
A. The following table summarizes the tools available for integrating with remote JMS
Method Automatic Enlistment JMS Resource Pooling
Direct use of the remote
provider’s JMS client
Yes for a WebLogic
server provider. Other
providers must perform
No. Can be done
Messaging Bridge Yes N/A
Q. How do I receive messages from a remote a JMS provider from within an EJB or Servlet?
A. Use a message driven EJB. Synchronous receives are not recommended because they idle a
server side thread while the receiver blocks waiting for a message. See What is a Message Driven
EJB (MDB)? and When should I use a MDB?
Q. How do I send messages to a remote JMS provider from within an EJB or Servlet?
A. Use a resource reference. It provides pooling and automatic enlistment. See What are JMS
resource references? and What advantages do JMS resource references provide? In limited cases
where wrappers are not sufficient, you can write your own pooling code. See the WebLogic JMS
Performance Guide white-paper available on the JMS topic page.
If the target destination is remote, consider adding a local destination and messaging bridge to
implement a store-and-forward high availability design. See What is a messaging bridge? and
When should I use a messaging bridge?.
Another best practice is to use foreign JMS server definitions. Foreign JMS server definitions
allow an application's JMS resources to be administratively changed and avoid the problem of
hard-coding URLs into application code. In addition, foreign JMS server definitions are required
to enable resource references to reference remote JMS providers. See What are Foreign JMS
Server Definitions? and When is it best to use a Foreign JMS Server Definition?.
Q. How do I communicate with remote JMS providers from a client?
A. If the destination is not provided by WebLogic Server, and there is a need to include
operations on the destination in a global transaction, use a server proxy to encapsulate JMS
operations on the foreign vendor in an EJB. Applications running on WebLogic server have
facilities to enlist non-WebLogic JMS providers that are transaction (XA) capable with the
current transaction. See How do I receive messages from a remote a JMS provider from within
an EJB or Servlet? and How do I send messages to a remote JMS provider from within an EJB
Foreign JMS Server
No. To get automatic
enlistment, use in conjuction
with a JMS resource
reference or MDB.
No. To get resource pooling, use
in conjunction with a JMS
resource reference or MDB.
JMS Resource Reference Yes Yes
Message Driven EJBs Yes Yes
Method Automatic Enlistment JMS Resource Pooling
FAQs: Integrating Remote JMS Providers
If you need store-and-forward capability, consider sending to local destinations and using
messaging bridges to forward the message to the foreign destination. See What is a messaging
bridge? and When should I use a messaging bridge?.
Another option is to simply use the remote vendor’s JNDI and JMS API directly or configuring
foreign JMS providers to avoid hard-coding references to them. You will need to add the foreign
provider's class libraries to the client's class-path.
Q. How can I tune WebLogic JMS interoperability features?
A. For information on tuning message driven EJBs and the
the WebLogic JMS Performance Guide white-paper available on the JMS topic page.
Q. What are Foreign JMS Server Definitions?
A. Foreign JMS server definitions are an administratively configured symbolic link between a
JNDI object in a remote JNDI directory, such as a JMS connection factory or destination object,
and a JNDI name in the JNDI name space for a stand-alone WebLogic Server or a WebLogic
cluster. They can be configured using the Administration console, standard JMX MBean APIs,
or programmatically using scripting. See “Simple Access to Remote or Foreign JMS Providers”
in the Administration Console Online Help.
Q. When is it best to use a Foreign JMS Server Definition?
A. For this release, a Foreign JMS Server definition conveniently moves JMS JNDI parameters
into one central place. You can share one definition between EJBs, servlets, and messaging
bridges. You can change a definition without recompiling or changing deployment descriptors.
They are especially useful for:
Any message driven EJB (MDB) where it is desirable to administer standard JMS
communication properties via configuration rather than hard code them into the
application's EJB deployment descriptors. This applies even if the MDB's source
destination isn't remote.
Any MDB that has a destination remote to the cluster. This simplifies deployment
descriptor configuration and enhances administrative control.
Any EJB or servlet that sends or receives from a remote destination.
Enabling resource references to refer to remote JMS providers. See What are JMS resource
references? and How do I use resource references with non-transactional messaging?.
Q. What are JMS resource references?
A. Resource references are specified by servlet and EJB application developers and packaged
with an application. They are easy-to-use and provide a level of indirection that lets applications
reference JNDI names defined in an EJB descriptor rather than hard-coding JNDI names directly
into application source code.
JMS resource-references provide two additional features:
Automatic pooling of JMS resources when those resources are closed by the application.
Automatic enlistment of JMS resources with the current transaction, even for
non-WebLogic JMS providers.
Inside an EJB or a servlet application code, use JMS resource references by including
resource-ref elements in the deployment descriptors and then use JNDI a context to look them up
using the syntax java:comp/env/jms/
Resource references provide no functionality outside of application code, and therefore are not
useful for configuring a message driven EJB’s source destination or a messaging bridge's source
or target destinations.
For WebLogic documentation on JMS resource-reference pooling, see “Using JMS with EJBs
and Servlets” in Programming WebLogic JMS.
Q. What advantages do JMS resource references provide?
A. JMS resource references provide the following advantages:
They ensure portability of servlet and EJB applications: they can be used to change an
application's JMS resource without recompiling the application's source code.
They provide automatic pooling of JMS Connection, Session, and MessageProducer
They provide automatic transaction enlistment for non-WebLogic JMS providers. This
requires XA support in the JMS provider. If resource references aren't used, then enlisting a
non-WebLogic JMS provider with the current transaction requires extra programmatic
Q. How do I use resource references with foreign JMS providers?
A. To enable resource references to reference remote JMS providers, they must be used in
conjunction with a foreign JMS definition. This is because resources references do not provide a
place to specify a URL or initial context factory. See What are Foreign JMS Server Definitions?.
FAQs: Integrating Remote JMS Providers
Q. How do I use resource references with non-transactional messaging?
A. For non-transactional cases, do not use a global transaction (XA) capable connection factory.
This will impact messaging performance. If you do, the resource reference will automatically
begin and commit an internal transaction for each messaging operation. See What is a
Q. What is a messaging bridge?
A. Messaging bridges are administratively configured services that run on a WebLogic server.
They automatically forward messages from a configured source JMS destination to a configured
target JMS destination. These destinations can be on different servers than the bridge and can
even be foreign (non-WebLogic) destinations. Each bridge destination is configured using the
four common properties of a remote provider:
The initial context factory.
The connection URL.
The connection factory JNDI name.
The destination JNDI name.
Messaging bridges can be configured to use transactions to ensure exactly-once message
forwarding from any XA capable (global transaction capable) JMS provider to another.
Q. When should I use a messaging bridge?
A. Typically, messaging bridges are used to provide store-and-forward high availability design
requirements. A messaging bridge is configured to consume from a sender's local destination and
forward it to the sender's actual target remote destination. This provides high availability because
the sender is still able to send messages to its local destination even when the target remote
destination is unreachable. When a remote destination is not reachable, the local destination
automatically begins to store messages until the bridge is able to forward them to the target
destination when the target becomes available again.
Q. When should I avoid using a messaging bridge?
A. Other methods are preferred in the following situations:
Receiving from a remote destination—use a message driven EJB or implement a client
Sending messages to a local destination—send directly to the local destination.
Environment with low tolerance for message latency. Messaging Bridges increase latency
and may lower throughput. Messaging bridges increase latency for messages as they
introduce an extra destination in the message path and may lower throughput because they
forward messages using a single thread.
Q. What is a Message Driven EJB (MDB)?
A. Message Driven EJBs are EJB containers that internally use standard JMS APIs to
asynchronously receive messages from local, remote, or even foreign JMS destinations and then
call application code to process the messages. MDBs have the following characteristics:
Automatically connects to a source destination and automatically retries connecting if the
remote destination is inaccessible.
Support automatic enlistment of the received messages in container managed transactions,
even when the JMS provider is not WebLogic.
Automatically pool their internal JMS connections, sessions, and consumers.
A MDB's source destination, URL, and connection factory are configured in the EJB and
WebLogic descriptors which are packaged as part of an application.
The messaging processing application logic is contained in a single method callback
AMDB is a full-fledged EJB that supports transactions, security, JDBC, and other typical
For more information, see “Message-Driven EJBs” in Programming WebLogic Enterprise
Q. When should I use a MDB?
A. MDBs are the preferred mechanism for WebLogic server applications that receive and
process JMS messages.
Q. Do I need to use a
A. Configure MDBs to directly consume from their source destination rather than insert a
messaging bridge between them. MDBs automatically retry connecting to their source
destination if the source destination is inaccessible, so there is no need to insert a messaging
bridge in the message path to provide higher availability. Introducing a messaging bridge may
have a performance impact. See When should I avoid using a messaging bridge?.
FAQs: Integrating Remote JMS Providers
Q. What is the best way to configure a MDB?
A. The following section provides tips for configuring a MDB:
To configure MDB concurrency and thread pools, use the max-beans-in-free-pool and
dispatch-policy descriptor fields. WebLogic may create fewer concurrent instances than
max-beans-in-free-pool depending on the number of available server threads in the
MDB's thread pool.
Use foreign JMS server definitions when configuring a MDB to consume from a remote
JMS provider. Although WebLogic MDB descriptors can be configured to directly refer to
remote destinations, this information is packaged with the application and is not
dynamically editable. You should configure a foreign JMS server definition and then
configure the MDB to reference the foreign definition instead. Please note that some
documentation refers to foreign JMS server definitions as wrappers. See What are Foreign
JMS Server Definitions?.
Use care when configuring a MDB for container managed transactions. A MDB supports
container managed XA transactions when a MDB’s descriptor files have
transaction-type of Container and a trans-attribute of Required and the JMS
connection factory is XA enabled. Failure to follow these steps will result in the MDB
being non-transactional. The default WebLogic setting for a MDB connection factory is
XA enabled. The MDB automatically begins a transaction and automatically enlists the
received message in the transaction.
Q. What additional resources document JMS interoperability?
A. For general information on WebLogic JMS see the JMS topic page.
The slide presentation "Integrating Foreign JMS Providers with BEA WebLogic Server
(from eWorld 2003)" contains sample JMS integration configuration and code.
The "Using Foreign JMS Providers with WebLogic Server" white-paper provides helpful
sections including, "Creating Foreign JNDI Objects in a Startup Class", "Configuring JMS
Providers", and "Sample Code".
The "WebLogic JMS Performance Guide" white-paper.
Q. Can you help me debug my program?
A. If the problem you are having is not directly related to our software, we suggest that you use
a Java development tool that helps you with debugging, and that you invest in some books or
training to help you learn Java. There are many ways to build debugging into your program, and
getting good training in Java programming is a good start to understanding how to do this.
Q. Where can I get help learning Java?
A. There are a lot of books and online references to Java. A good starting place is at the JavaSoft
website documentation index at http://www.javasoft.com/docs/index.html, which has links to
white papers and the Java Tutorial. You can find books on Java at any of the major online book
Q. Where do I get the JDK?
A. WebLogic 8.1 bundles JDK 1.4. See our Platform support page for information about
specific JDKs that we have tested and certified for use with WebLogic software.
Once you determine which version of the JDK you will be using, go to the JavaSoft website at
http://www.javasoft.com/products/. Many platform vendors provide an optimized version of the
JDK for their computers.
Q. How do I set up my CLASSPATH?
A. Setting up your CLASSPATH correctly depends on what you are trying to do. The most
common tasks are described below:
Starting WebLogic Server. See Setting the Classpath Option in the “Starting and
Stopping WebLogic Servers” section of Administration Console Online Help. In addition,
your WebLogic distribution includes shell scripts that you can use to start the server. These
scripts, which are located in the domain directories under the config directory of your
WebLogic Server distribution, automatically set up the CLASSPATH variable in the shell
before starting the server.
Compiling Application Classes or Using WebLogic Server Utilities. See Setting the
Classpath for Compiling in the Developing WebLogic Server Components section of
Developing WebLogic Server Applications.
Working With WebLogic Server Code Examples. See the WebLogic Server Examples
Guide located at samples/server/examples/src/examples/examples.html in your
WebLogic Server distribution.