The Borland Enterprise Server is available in three "Editions":
Each Edition builds upon the tools and services of its predecessor. The most basic is the Web Edition; the most versatile is the AppServer Edition. If desired, you can upgrade from one Edition to another. This release note is applicable to all of these Editions.
Note: For additional information specific to the VisiBroker Edition and VisiBroker standalone, see the release notes appropriate to the respective platforms.
This section contains important information concerning the following areas:
For information on how to install Borland Enterprise Server, please refer to the Installation Guide. If you are upgrading, see Upgrading from previous versions.
Important note for JBuilder8 users: JBuilder 8 Enterprise includes and works with BES 5.1.1. In addition, BES 5.2 is certified to be used with JBuilder8 for application development. To use JB8 with BES 5.2, users must apply a patch to JBuilder8, as described in: JB8 patch required with BES 5.2.
The following table describes the two "install types":
| Borland Enterprise Server Complete | Installs a BES server and all components required to run any Edition. |
| Borland VisiBroker Standalone | Installs a self-contained VisiBroker installation - just the VisiBroker ORB or VisiBroker Management Console without any J2EE components. |
Note: The Borland VisiBroker Standalone installation is not to be confused with BES VisiBroker Edition. The former is an install type, the latter licensing purchased for BES. Both install types are available with all BES Editions.
If you have a previous installation of Borland AppServer or Borland Enterprise Server installed, do not install on top it. Remove the previous version or install Borland Enterprise Server in a separate directory.
Before installing, ensure that you have read and complied with the all platform requirements, including J2SE. See the Platform information section for detailed requirements.
Borland Enterprise Server licensing technology governs the level of features available. You can upgrade your license at any time. For example, you can upgrade from one edition to another, from an evaluation to development license, or to a runtime license. You can manage your server's license using the Borland Enterprise Server Management Console.
A fully licensed installation on UNIX may emit the following licensing error
message when using tools like idl2cpp or VBJ.
There is no valid license to run this product or component. Please make sure that a license enabling this product or component is installed correctly and it has not yet expired.
These tools require access to appropriate environment variables. Prior to running
these tools, use the vbroker.csh (for C-Shell) or vbroker.sh
(for Bourne and KornShell, bash) scripts in the installation's bin directory
to set up the appropriate environment variables. Building the examples requires
invoking a number of these tools; if you wish to compile the examples on UNIX
or Linux, you must invoke the setup scripts first. This behavior is as designed.
When an appropriate license is presented to the Borland Enterprise Server, client license Serial Numbers and Activation Keys are generated automatically. You can find the Serial Number and Activation Key in the file:
<your_install_root>/var/servers/<server_name>/adm/client.license
To run the Borland Enterprise Server, navigate to its bin subdirectory
and type ias. In Windows, choose Start|Programs|Borland Enterprise
Server. Refer to the Borland Enterprise Server User's Guide in the online Help Topics for more detailed information.
To use the Java-based Management Console, navigate to your installation's bin
directory and type Console. The Management Console allows you to browse,
control, and configure the server, as well as deploy applications to it. In
Windows, choose Start|Programs|Borland Enterprise Server|Management Console.
Refer to the Borland Enterprise Server User's Guide in the online Help Topics for more detailed information.
When the Management Console starts, a Login dialog appears. All servers are installed
with a default user named admin. The password for this user is
admin as well.
By default, security is disabled for the user domain on Partitions in the Borland Enterprise Server. To enable security on a Partition:
The following features have been introduced in Borland Enterprise Server 5.2.
Applications can now be run on either JDK 1.4 or JDK 1.3.1. The BES installer will always install both JDKs, but prompts the user to select the default JDK for new partitions. You can change the partition JDK using the Partition properties dialog in the BES Management Console. For more information, see the BES "User's Guide" in the online Help Topics.
Note: IBM AIX does not support running applications on JDK 1.4.
Application archives can now be hosted by a Partition by providing a local filesystem path to the Partition. The Management Console has a new Partition tree node, "Hosted Modules", that is used to manage these application archives.
This feature is in addition to the existing ability to remotely deploy application archives to a Partition. These application archives continue to be managed under the Partition tree node "Deployed Modules".
See "Deployed Modules" in the BES User's Guide in the online Help Topics for details.
Unpacked application archives are archives that appear on disk as a directory structure containing the unpacked, un-jared archive. To host an unpacked application archive, provide its top-level directory as a "Hosted Modules" filesystem path.
This feature is supported for all archive types except EARs. See "Deployed Modules" in the BES User's Guide in the online Help Topics for details.
Partitions whose complete footprint resides at some user-supplied local filesystem path can now be managed.
See "Explicitly-Pathed Partitions" in the BES User's Guide for details.
User code to be invoked at various points in a Partition's lifecycle can be deployed
to a Partition. This user code is deployed in a library together with a META-INF/module-borland.xml
descriptor that defines the code to be invoked.
See "Using Partition Lifecycle Interceptors" in the BES Developer's Guide in the online Help Topics for details, and the example in: <install_dir>/examples/partition_interceptors.
java.sql.ResultSet. This
is a Borland extension of the EJB 2.0 specs.ejb.eagerLoad property. When set, the PM will fetch
all data (in the same order as that in the select statement) from the ResultSet
into the entity bean as soon as the results return from the database. This
is useful to tune performance in some situations as also a workaround for
JDBC drivers that require that data be fetched from the ResultSet in the same order as that in the select statement.long
for dates and java.sql.Date for java.util.Date.This feature, available in both the Management Console and the DDEditor, displays EJB and resource references within a selected module. At present, this is a read-only display. It appears as a new tab in the DDEditor and the Management Console when a module is selected. In the future, this display will be editable.
In scenarios where browser access to the web container is by way of the Apache web server, this feature enables you to give your web container access to all the browser-supplied SSL information (as if the Apache web server is not between the browser and the web container). With this SSL information, your web container can do certificate-based authorization. In addition, the web container can also propagate the certificate-based security context down the chain to the EJB container.
See the "Enabling certificate passthrough to Tomcat" in the BES Developer's Guide in the online Help Topics for details.
This command causes the Partition to perform a thread dump into its own event log, providing diagnostic information about the threads running in a Partition. It is accessed by way of the Partition's right-click menu.
This wizard, accessed by right-clicking on a stateless session bean in the Management Console, directs you through the process of creating a custom web service wrapping the selected bean. When complete, the web service is automatically generated and deployed to the server.
This feature displays each classloader in the Partition and the classes it hosts. It is available as a new tab on the Partition display in the Management Console.
Starting with BES 5.2, the stub code for Remote interfaces have been enhanced to copy the arguments when it is determined that the caller and calee have different classloaders. In previous versions of BES scenarios like a servlet calling an EJB across module boundaries led to a ClassCastException. The only solution was to repackage the WAR and EJB JAR into the same EAR. The user now has the option to not do that and the scenario will work as is. However, it is still recommended to use the EAR solution where possible as that is the better performing option since the pass by reference optimization can be preserved.
Of course for local interfaces we cannot do something like this since the semantics must be pass-by-ref. So calls across EJB Local interfaces will still show a classloder issue.
It is now possible to use the iastool on a WAR or an EAR to precompile all the
JSPs within that archive. A new option compilejsp is added to iastool for this
purpose.
See "iastool command-line utility" in the BES User's Guide in the online Help Topics for details.
It is now possible to specify the <web-deploy-path> for all
web applications using the default web-borland.xml file. The default
web-borland.xml file can be found in:
<install_dir>\var\servers\<server_name>\adm\properties\Partitions\<Partition_name>\tomcat\conf
Please note that the default values are utilized when a web application does not
specify a value for <web-deploy-path> element.
The Apache Tomcat base used by the Web Container is has been upgraded to Tomcat version 4.1.15.
The Apache web server component has been upgraded to version 2.0.43.
VisiSecure for java will now allow user to plug-in their own Authentication Mechanisms, Authorization Services, Trust Services, JSSE services and Login Modules
The following fixes were made in 5.2 in response to reported problems in previous releases. Each fix is preceded by its bug number.
37226: VisiConnect: Error verifying a Resource Adapter with a deep connection factory hierarchy.
36102: Web Container: Access to pages that are not in security constraint uses anonymous for an authenticated client
36100: When security is turned off the web container should not require BSSRealm to be unconfigured.
36099: Make BSSRealm the default security realm for the web container.
35979: IiopConnector doesn't honor address param specified in server.xml
35029: Missing error documents in apache configuration
34090: OutOfMemory error when running app using Security for extended time
34089: Cannot write to a non-existent resource_vault file if not using the default
34087: Cannot use use-caller-identity in a RAR to handle container-managed sign-on
34084: Deploying a RAR which employs security throws exception
30615: Thread leak when accessing EJBs with security is on.
30566: Cannot deploy a Local Connector to the serial jndi context handler.
36356: (JDBC 2.0) Datasource property readOnly is not being honoured
35392: (CMP 2.0) byte[] persistent field in CMP entity beans in BES 5.1
35300: (CMP 2.0) BES: Problems with Exclusive commit option mode
35197: (Verify) Verification too strict for mismatched throws clause when throwing runtime exceptions
34865: (JMS) using java:comp/ names in client code does not work properly for JMS objects
34715: (JMS) Container does not free up Sonic connections when onMessage in an MDB throws EJBException
34666: (MDB) XA connections opened for the MDB does not get the start() call
34605: (CMP 2.0) Self Join Fix produced with 30596 only works with JDatastore
34571: (JDBC) set reuseStatements to FALSE is not working with JDBC1.x drivers
34529: (CMP 2.0) SQLException when accessing EJB2.0 Entitybeans from Microsoft's JDBC driver.
34404: (JTA) XAException with errorCode -8 when using external OTS
34206: (JMS) BES-SonicMQ/JMS connection handling, not releasing resources
34112: (Verify) RemoteExceptions for BusinessInterfaces and localInterfaces
34103: (Naming) ctx.lookup throwing ArrayIndexOutOfBoundsException instead instead of throwing NamingException [FIXED]
33964: (CMP 2.0) IllegalStateException with 2 Entity CMP in 'Exclusive' mode
33944: (CMP 2.0) Setting the OptimisticConcurrencyBehavior to VerifyAllFields does not verify all the entity's fields
33808: (CMP 2.0) BES EJB CMP Mapping failure
33749: (JMS) BES 5.1 Oracle XA Problem - SonicMQ Memory Issue
33404: Readme.html in BES51 for Bank example does not reflect the changes made in BES51
30737: (CMP 2.0) Cascade delete bug in our EJB CMP implementation
30682: (JDBC) BES 5.0.1 XA bug with full 2PC
30254: (EJBContainer/SFSB) java.lang.OutOfMemoryError: unable to create new native thread
33974: Apache core dumps on exit on AIX
The following are issues you may encounter when migrating from earlier versions of BES to BES 5.2.
/servlet/* : The older release
of the web container had a default servlet mapping to map /servlet/*
url patterns to a servlet named invoker. This mapping posed a
security risk and thus has been removed. The web applications that depend
on this implicit mapping will now throw a "page not found" error to the web
client. The solution is to explicitly create a new individual mapping for
your servlets or add the following generic mapping to your web application's
web.xml.
<servlet-mapping>
<servlet-name>invoker</servlet-name>
<url-pattern>/servlet/*</url-pattern>
</servlet-mapping>
doStartTag() (instead of constructor) and all cleanup in doEndTag().enablePooling=false
for a JSP servlet in the default web.xml. The default web.xml
is present in the directory <install_dir>\var\servers\<server_name>\adm\properties\Partitions\<Partition_name>\tomcat\conf.deploy.wsdd with additional parameters <parameter name="className" value="your_ejb_remote_interface_class_name"/>If the BES 5.1-based web service is run on BES 5.2 without performing these changes, you get an exception similar to the following on the client side:
[java] Tried to invoke method public abstract java.lang.String
com.borland.examples.webservices.ejb.Animal.talk(java.lang.String) throws
java.rmi.RemoteException with arguments java.lang.String. The arguments
do not match the signature.
Depending on system resource usage, the NFILE parameter may be too small to support
the number of open files the installation requires.
We recommend a value of at least 3000. Please see the HP-UX system documentation for information
about configuring and rebuilding the HP-UX kernel.
Although AIX is not certified to run applications on JDK 1.4, JDK 1.4 is still required to support a full BES installation, as it is used for internal tooling.
In the case of a VisiBroker standalone installation, no tooling is installed that requires JDK 1.4, but the installer still requires the user to enter a path to JDK 1.4. As a workaround for the VisiBroker standalone install on AIX only, it is permissible to enter the path to JDK 1.3.1 in place of JDK 1.4.
There is a known issue in the Linux C libraries affecting Java applications
which call System.exit(x). This is the recommended practice for GUI
applications. iastool and Console both use this method to
exit the VM. This problem is resolved in a later version of the C libraries.
Please see http://java.sun.com/j2se/1.4.1/relnotes.html
for more information. The suggested workaround is to edit the makefile
to ignore the failing command. Since the necessary work has been accomplished
by the time the tool exits, this is not a serious problem.
A packaging error has caused the jdsnativeio.dll to be omitted
from the BES 5.2 CD. This DLL permits the use of native I/O to improve JDS
performance when the -DJDATASTORE_FILEIO=native system property
is set. This DLL will be available soon as a download from the Borland web
site. In the meantime, please contact Technical Support for this DLL. In the
absence of the DLL, please be sure NOT to set the -DJDATASTORE_FILEIO=native
system property, as it will cause fatal errors.
When running the Management Console, DDEditor, or other GUIs under JDK 1.4 (the default JDK for all tools in BES 5.2) on Windows systems using ATI Radeon video drivers, exiting the GUI can sometimes result in the "blue screen of death". On these systems, please add the following parameters:
vmparam -Dsun.java2d.ddoffscreen=false vmparam -Dsun.java2d.noddraw vmparam -Dsun.java2d.d3d=false vmparam -Dsun.java2d.ddoffscreen=false
to the following files, all in <install_dir>/bin :
jdk.config ddeditor.config vbconsole.config beshelp.config jdsserver.config jdsexplorer.config sonicmqexplorer.config
When running the BES Server on Linux, the Management Console and iastool are
sometimes unable to discover that server when run from a different system.
This is because the default Linux hosts file has only the loopback
entry (127.0.0.1). In order to correct this, you must add an
entry for the local host. For example, on a machine named mylinux
that is called mylinux.work.mydomain.com at 172.1.1.1,
the following must be added to the hosts file and must be the first
entry in that file:
172.1.1.1 mylinux.work.mydomain.com mylinux
mod_iiop cannot run seteuid/setegid on HP-UX
The HP-UX dynamic loader dld.sl does not respect the LD_PRELOAD
environment variable for seteuid/setegid programs. This is a documented behavior. This
affects the Borland Enterprise Server's ability to start and/ or control an instance of the Apache Web Server
running on a privilged port and using mod_iiop. Please see the
Unix FAQ for detailed information about configuring the Apache Web Server to listen on privileged ports on HP-UX.
To compile and run the Web Services examples on HP-UX, use the supported HP-UX 1.4 JDK, rather than the HP-UX 1.3 JDK.
Starting BES and then logging off the system causes Apache to exit.
beshelp does not run from command line on AIX.
By default, the standalone help viewer for the BES online Help Topics (beshelp),
does not run from the command line on AIX. Alternately, you can run the
Help from the Management Console, Help menu command. To run beshelp from the command line on AIX, edit the <install_dir>/bin/beshelp.config file and change the following entries:
vmtype to jvmdefaultvmparam -Xms24m and vmparam -Xmx128m.When hosting an exploded EAR, the EJB JARs, client JARs, RARs, and DARs will be deleted when the Partition is stopped. Only WARs and LIB JARs will be unaffected. We recommend you only host exploded WARs. However, if you wish to host exploded EARs with the above archive types, those archives can be set to be "read-only" to prevent this deletion as a workaround.
The BES Management Console provides a web container configuration dialog,
permitting the editing of the web container's configuration file, server.xml. In recent releases, three tabbed views were available: one to edit server.xml
directly, and two more to offer more convenient access to
frequently-configured properties. Unfortunately, it has been necessary
to remove these two tabs, since they provoked authentication code that
resulted in the removal of unknown, but legal, attributes from server.xml elements. A significantly
enhanced web server/web container configuration experience is planned for
the next major release.
iaschangeowner documentation is inaccurate
Extensive changes to iaschangeowner have not been documented. Current
usage and help information is available from the tool itself:
./iaschangeowner -h
In order to use BES 5.2 as the application server in a JBuilder8 project,
a patch must be applied to JBuilder8. The patch (jb8_bes_001.jar)
can be found:
<cdroot>/JBuilder<install_dir>/etc.In both folders, the JAR is accompanied by a readme.html file
that explains how to install the patch.
The patch causes JBuilder8 to use required libraries from the BES installation (<bes install root>/lib)
rather then from the JBuilder8 installation (<jb8 install
root>/lib/bes) for deployment and stub generation functions. It does
not
cause JBuilder8 to use the DDEditor from the BES installation. With or
without the patch, the DDEditor function that appears in JBuilder8 is
the 5.1.1 DDEditor.
Note: With the patch installed, JB8 will support BES 5.1, 5.1.1 and 5.2. If you need to use JB8 with BES 5.0.2, do not apply the patch.
When deploying/debugging a project using JBuilder8 and BES 5.2, JBuilder will create its own Partition (named "JBuilder") in the BES server. This Partition is configured using a default configuration that is identical to that used in the Standard Partition. If these Partitions are running at the same time, port conflicts will occur.
Before using JBuilder, do the following:
Such port conflicts can also occur with other Partitions that have been created with default parameters.
When using the Start using Server or Debug using Server commands, JBuilder8 will:
This can be quite slow. In the large majority of cases, you can avoid this
behavior by using the Deploy options for <archivename> command (right-click archive in JB8), and selecting the Redeploy command. This will cause a hot
deploy to occur, which will not stop the Partition. It does launch another
tracker window at the bottom of JBuilder. Once the redeploy is complete, you
may close this window.
In a JBuilder project, when you configure the BES Server in the Tools | Configure
Servers dialog, you must set the JDK in the Custom tab to point to the desired
JDK. This setting defaults to <install_dir>/jdk, which
does not contain a JDK. You must browse to and select either <install_dir>/jdk/jdk1.3.1 or <install_dir>/jdk/jdk1.4.1.
As noted above, you must configure your BES 5.2 Server in JBuilder to select either JDK 1.3.1 or JDK 1.4.1. However, this does NOT configure the JBuilder Partition to run that JDK. By default, the JBuilder Partition will be configured to use the default JDK that was selected when you installed BES. You may change this two ways:
-javahome <path_to_desired_JDK>. This will override
the actual configuration of the JBuilder Partition when run from JBuilder.-javahome parameter described above.Once you have configured BES 5.2 in JBuilder, if you subsequently open an existing project that uses BES, you must refresh the project properties related to BES. This is required only once per project. To refresh the properties:
When configuring a project that uses BES (or any other server), JBuilder attempts to ensure that the JDK setting for the project is the same as the JDK setting for the server. This synchronization is done when the Project | Project Properties dialog is dismissed. To be sure that the Project JDK is set correctly, re-open this dialog after dismissing it.
<name> 5.0.2-5.1.x also support BES 5.2
The following entities in JBuilder 8, though named 5.0.2-5.1.x, support BES 5.2:
onMessage() method can cause infinite redeliveries of the same JMS message
Currently there is no way to limit the number of retries.
There is a known issue with the use of the resource vault file in VisiConnect. If an attempt to use run-as roles with a RAR in VisiConnect is made without providing a resource vault, VisiConnect will need to be cycled before being able to read in a subsequently provided resource vault using the same Security Context (username/password or credential). It is highly recommended to deploy the required resource vault file(s) for VisiConnect prior to executing deployed Resource Adapters with dependencies on that file(s).
The BES Management Console provides a configuration dialog for the SonicMQ
service. In this dialog, you may configure the Admin Broker port (on the Settings
tab). This setting changes only the port that the BES service manager will
use to communicate to SonicMQ. After changing this, you must also configure
the SonicMQ server's port either by editing the <install_dir>/SonicMQ/broker.ini
file, or using the SonicMQ explorer, available in the BES Management Console
| Tools menu.
To upgrade from Borland Enterprise Server 5.0, 5.0.1 or 5.0.2, do not install on top of the previous installation. Install in a separate directory or uninstall your previous version first. You may then redeploy your applications to Borland Enterprise Server 5.2.
Important: Borland Enterprise Server 5.2 is not interoperable with the 5.0.0 version due to fixes for bugs relating to compliance to specifications. Therefore, all installations of the 5.0.0 version that interact with later versions must be upgraded.
To upgrade from Borland AppServer 4.5, do not install on top of the previous installation. Install in a separate directory or uninstall your previous version first. You may then migrate your applications from BAS 4.5 to Borland Enterprise Server 5.2.
The Borland VisiBroker Object Request Broker (ORB) now combines the Java and C++ packages into a single installation. It has been necessary to synchronize some of the features and behaviors of the Java and C++ ORBs as a result. This section details the changes in the GateKeeper, the VisiBroker ORB in general, and the Naming Service utility (VisiNaming™).
Important: For information on minimum hardware requirements, certified operating systems, JDKs, and compilers, please refer to the Product
Platforms Page:
For AppServer edition, refer to http://techpubs.borland.com/am/bes/platforms/52xplatformase.htm.
For Visibroker edition, refer to http://techpubs.borland.com/am/bes/platforms/52xplatformvbe.htm
For Web edition, refer to
http://techpubs.borland.com/am/bes/platforms/52xplatformweb.htm
The following sections detail the J2SE requirements for Borland Enterpise Server. The J2SE versions referenced below are the only versions certified for use with Borland Enterprise Server.
It is vitally important that you read the Release Notes and/or Readme that accompany the version of Java you use with Borland Enterprise Server. In particular, pay special attention to the sections that detail Operating System patches that must be applied. Failure to do this WILL lead to unpredictable Java VM crashes.
J2SE 1.3.1_06 and 1.4.1_01 are installed as part of the Borland Enterprise Server on Windows and Linux. You can read the Release Notes on Sun's web site.
J2SE 1.3.1_06 and 1.4.1_01 are installed as part of the Borland Enterprise Server on Solaris. You can read the Release Notes on Sun's web site.
The Borland Enterprise Server is not certified to run with any IBM 1.4 JDK for AIX.
HP-UX Required Patch Level: Please refer to http://www.hp.com/products1/unix/java/java2/sdkrte1_3/infolibrary/sdk_rnotes_1-3-1-07.html#socket. The patches listed on this page are required for this version of BES, although they are listed by HP as merely recommended. Please ensure that your system conforms to this patch level.
HP-UX kernels are typically underconfigured for real-world applications,
and must be re-tuned. HP-UX 11.0 is configured by default to allocate only
64 threads to any particular process. The typical symptom of this configuration
problem is that ias and other process emit errors regarding memory
problems or errors regarding an inability to allocate additional threads.
This can be corrected by reconfiguring the kernel using the SAM
utility. We recommend a minimum configuration of 512 threads per process.
You should test your application under load to the verify this meets your
requirements.
HP provides the tool HPJconfig to help configure your kernel for a variety of java
applications. The tool can be downloaded from HP's web site.
Most scripts in this release use the KornShell, which must be installed on your
system. The pdksh package, which is distributed with Red Hat Linux, is known to
work but is not installed by default. To install this file, use this command:
rpm -i package-file
Important: For information on minimum hardware requirements, certified operating systems, JDKs, and compilers, please refer to the Product Platforms Page.
J2SE 1.4.1 is installed as part of the Borland Enterprise Server on Windows and Linux on IA64. You can read the Release Notes on Sun's web site.
Security for VisiBroker C++ is not available.
To install the web download you must have JDK 1.4.1 installed and its bin directory in your path. At a DOS prompt type:
java -cp BES_52_Windows_IA64.jar install
You must install the x86-compat-libs package in order for all BES 5.2 components to function properly.
Security for VisiBroker C++ is not available.
To install the web download you must have JDK 1.4.1 installed and its bin directory in your path. From a shell type:
java -cp BES_52_Linux_IA64.jar install
SSL is not available with the Apache web server that is included with the product. For SSL support with Apache, you may download HP's Web Server Suite product here.
Due to a bug in JDK 1.4.1.01 you must set the following property in bin/console.config and bin/ddeditor.config in order for the GUI programs to work properly if using JDK 1.4.1.01:
vmprop java.util.prefs.systemRoot=$var(installRoot)/tmp
Security for VisiBroker C++ is not available.