After configuring your BlueDragon .NET website, you can remove all access to the Admin UI by removing or renaming admin11.bda or admin20.bda located in the \config folder of the BlueDragon installation. BlueDragon.NET is using admin11.bda if you are using Microsoft .NET Framework 1.1 and using admin20.bda if you are using .NET Framework version 2.0.

Faq ID

233

Product

BlueDragon

Category

Admin Console, Miscellaneous

Question

Can you explain more about the possibility of encrypting and precompiling templates (or "sourceless deployment") in BlueDragon?

Answer

Developers often want to deploy their code without source (sourceless), and while this has long been a problem for ColdFusion developers, BlueDragon has solved this problem since 2003.

Developers familiar with the ColdFusion CFENCODE (or previously named CFCRYPT) utility know that there are ways to revert that back to source code. Many developers have simply given up on the hope of sourceless deployment.

BlueDragon offers sourceless deployment with a feature called Precompiled, Encrypted CFML Templates. Offered in all but the free Server edition, you can create precompiled or encrypted templates from the Admin console or via a command-line utility. (The free Server edition also cannot process precompiled or encrypted templates, but all other BlueDragon editions, including in their trial and developer modes, can run precompiled/encrypted templates.)

The output of the process for each input .cfm (or .cfc) file is a new file with the same extension, but which is not human readable. (See the BlueDragon User Guide for more information.)

Note that you can compile all or just some of your CFML templates.

Additionally, BlueDragon uniquely supports setting an expiration date for your code during the precompilation/encryption process, so your code can be offered as a trial that will expire on the date set. Note that only the code expires, not the BlueDragon engine, so to offer a new set of code without an expiration date (or with a new one), you only need to give the client the new code (there's no need to reinstall BlueDragon).

Finally, note as well that the encrypted templates feature also offers greater security in a couple of different aspects.

If you'd like additional background information on the precompilation or encryption processes, see below.

Background: Page Processing

To understand this unique feature, it's important to understand how BlueDragon processes CFML templates (pages). CFML processing is done by BlueDragon in two steps:

In step one, BlueDragon "parses" the static information in the CFML page (which tags does it contain, what attributes do the tags have, which portions of the page are plain HTML, etc.) and creates a representation of the page as an ordered collection of Java objects.

In step two, the objects created in step one are "rendered" to create the HTML response that's sent to the browser. This is the dynamic, "runtime" step where expressions are evaluated, queries are executed, session and client data is managed, etc.

The parsing step only needs to be done once, the first time a page is requested--the object representation of the page is stored in memory in BlueDragon's "file cache" and the CFML source code isn't needed anymore. For subsequent requests for the page, the object representation is retrieved from cache and rendered directly. Of course, if a page is removed (flushed) from the cache, or the CFML source file is modified, the parsing step has to happen all over again.

Precompiled Templates

Here's where the "Precompiled" part comes in. The Java objects that represent the parsed CFML page can be serialized (converted to a byte
stream) and written to a file. Therefore, a precompiled template is one where the CFML source has been parsed by BlueDragon, converted to a collection of Java objects, and then those Java objects are written
(serialized) back to the file in place of the original CFML source. (Note that the process of precompiling destroys the original CFML source, so make a backup first!).

There are two advantages to precompiled templates:

Because the CFML has already been parsed, BlueDragon can skip that first step and directly render the page. This saves processing time and improves performance, even if the page isn't stored in BlueDragon's file cache.

It provides a level of obfuscation that helps protect your CFML source from prying eyes. It will be difficult (but not impossible) for someone to figure out how to de-serialize the Java objects that represent the CFML page, because those objects are proprietary to BlueDragon and their definition is not publicly available. But, even if someone does figure out how to de-serialize a precompiled template, all they'll get for their efforts is a bunch of Java objects--not your CFML source code.

Encrypted Templates

Additional security for your CFML source code can be provided by creating "Encrypted" precompiled templates. When you create precompiled templates (either from the admin console or via a command-line tool), you have the option of encrypting the resulting serialized objects using industry-standard, commercial-grade encryption algorithms provided by the Java VM (see http://java.sun.com/products/jce/index.jsp for details).

The advantage of encrypting your precompiled templates is that it makes it extremely difficult (almost impossible) for anyone to decrypt the templates and reconstruct your CFML source. The disadvantages of encryption are that it significantly increases the file size, and eliminates the performance advantage of precompiling due to the extra processing required to decrypt the template.

There's more. Any CFML template encrypted using BlueDragon's built-in "default" key can be decrypted and run on any version of BlueDragon. However, you also have the option when creating precompiled, encrypted templates to have BlueDragon generate a unique key for that set of templates. Then, those templates can only be decrypted when that unique key is configured in the BlueDragon admin console. You can choose to create a single unique key and distribute that key to all your customers so they can run your code; or, you can create a unique key for each individual customer. It depends on what level of control and security you need.

What About the Former BDA Approach

Finally, for those of you who were interested in BDAs (BlueDragon Archives), here are the problems we discovered with BDAs, all of which are successfully addressed by Precompiled, Encrypted Templates:

Deployment of BDAs is awkward. There are several issues here:

The BDA only contains the dynamic contents of the application directory structure (".cfm", ".cfc", etc.) and not the static contents (".html", ".gif", ".js", ".css", etc.). This makes deploying an application somewhat disjoint: you have to deploy the original directory structure minus the dynamic content, and then also deploy and configure the BDA.

Some of our customers only want to encrypt certain sub-directories of their application and not the entire application; some want to encrypt only custom tag libraries or CFCs. Again, this makes for a somewhat disjoint deployment using BDAs.

The configuration required for BDAs can be confusing and error-prone for our customers or their customers.

"Default document" processing doesn't work with BDAs. That is, if you configure "index.cfm" as the default document for a directory request (a request ending with "/"), it doesn't work if the index.cfm file is within a BDA.

Microsoft IIS web server has an option to "check that file exists" before handing the request over to BlueDragon for processing, returning a 404 Not Found result to the browser if the file doesn't exist. This doesn't work for BDAs. (Other web servers may have similar options).

With BDAs, it's not possible to update individual files for "patching" an application.

For our customers who are committed to using BDAs, we'll continue to support them as long as you need them (BDA support still exists in BlueDragon 6.1 and 6.2, we're just not going to publicize it anymore).

Precompiling from the Command Line

As mentioned above, it's possible to perform the precompilation from the command line, in addition to the Admin console option. The utility is called simply precompile (bat, exe or sh depending on operating system) and is found within the BlueDragon installation in either the bin directory of the java editions or the precompiler directory in BlueDragon.NET.

Learning More

The precompilation feature is discussed further in the BlueDragon User Guide. In the 6.2.1 edition, it's in section 5.2.3.

We hope you find this new feature interesting and useful. As always, we look forward to your feedback to help us improve this feature and others supported by BlueDragon.

Faq ID

287

Product

BlueDragon

Category

Admin Console, Version differences

Question

Do I need to apply hotfixes if I just downloaded the latest version?

Answer

Between releases of BlueDragon we may roll up several bug fixes into a "hotfix". Such hotfixes are NOT incorporated into the downloadable version of the product, until we come out with a new point release. For instance, for the 6.2 edition, we came out with hotfixes (for all BlueDragon editions) in May and August 2005, and until the next point release (6.2.1), there will be no update to the installer.

If you haven't taken the time to apply those updates, we recommend you do. As the page points out, it's only necessary to apply the latest hotfix (if more than one exists), because the hotfixes are cumulative.

In order to determine whether you need the update, you may need to determine what release of BlueDragon you're currently running. See FAQ #286.

Applying a hotfix is quick and painless. The readme.txt file associated with the hotfix zip file for each edition (and operating system) explains the steps needed to apply the update. It's just a matter of stopping BlueDragon (or the J2EE or .NET server), copying/renaming one or more files as directed (never more than a few), and then restarting and confirming the new release.

Faq ID

307

Product

BlueDragon

Category

Admin Console, Miscellaneous

Question

Do you have any performance tuning recommendations?

Answer

Tuning BlueDragon should generally involve the same practices and techniques used with ColdFusion.

You should carefully consider all the settings in the BlueDragon Admin console. The defaults may require tuning in your environment (such as the default of 3 for each datasource's "maximum connections", or the file cache size of 60, or the "max heap size" of 128k in the Java editions).

Note as well that BlueDragon offers some advantages in performance reporting, over CFMX, in that there are several "runtime state" reports in the BlueDragon Admin console, for both the entire server, each datasource, and the file/template cache. These reports can help identify bottlenecks, as well as help you determine the correct values to enter for the Admin console settings.

Of course, nearly any CFML application will benefit from judicious use of caching, whether query caching (CFQUERY CACHEDWITHIN and CACHEDAFTER and BlueDragon enhancements), page output caching (CFCACHE), partial page caching (BlueDragon's own CFCACHECONTENT). A good primer on CFML caching techniques is Caching in ColdFusion, by Matt Boles at Macromedia. (Note that if you use or are interested in Brandon Purcell's CF_Accelerate tag, we support that as well.)

Finally, as for configuring the environment (OS, web server, DBMS), we don't have any specific performance tuning recommendations for BlueDragon, but again some of the common techniques recommended for ColdFusion would apply. There have been several such resources posted by Macromedia. If you have any questions or concerns regarding the recommendations there and whether they apply to BlueDragon or in your environment, we're happy to discuss them with you.

Additionally, there are some .NET-specific aspects to consider for those running the .NET edition of BlueDragon. The final chapter of the manual, Deploying CFML on ASP.NET, lists several generic .NET resources, including some focused on .NET tuning. We will also be adding more information (there or in a technote) elaborating on such issues of particular interest to CFML developers.

It is indeed possible to do clustering with BlueDragon, and even enable session replication across servers in a cluster with the J2EE and .NET editions. Such clustering support is not enabled by features of BlueDragon but rather by those of the platform on which BlueDragon is installed (in the case of session replication, it's enabled by the underlying J2EE server or .NET framework).

Clustering servers is typically done using hardware or software mechanisms that offer load balancing and fail-over. Such mechanisms have been used with all editions of BlueDragon.

A common limitation with ColdFusion's built-in clustering (and indeed with some other clustering solutions) is that it forces the use of what are called "sticky sessions", meaning that once a user with a given session is on a given machine, they must stay on that machine. This reduces reliability, since if that one machine goes down, the user and their session cannot be "failed over" to another server in the cluster.

With the J2EE and .NET editions of BlueDragon, this issue can be eliminated. The platform on which BD is deployed will control whether clustering and failover works, and if the platform also supports session replication (between servers in the cluster), then CFML sessions created in these editions will benefit from that session replication.

In the BlueDragon Admin console, one can declare that "j2ee sessions" (or ".net sessions" on .net) should be used, which means that BlueDragon does not manage the sessions but instead the underlying platform does.

No other change is required of your CFML code. You continue to set and get session variables the same way you do already.

If you then enable clustering and/or replication of sessions between servers, your CFML sessions will be replicated. (The use of such session replication has been found to fail with ColdFusion MX 6.1 and certain J2EE servers, including WebSphere Network Deployment edition, among others. BlueDragon has been found to support session replication in all environments tested.)

Note that BlueDragon supports persistence of CFC instances to sessions, and those can be replicated as well. (This is possible because BlueDragon supports serialization of ColdFusion Components, where ColdFusion does not.)

Many shops have switched to using Client variables instead to support persistence of a user's data across servers. BlueDragon certainly supports client variables, but note that sessions can be set to timeout in a timeframe of minutes while client variables timeout in a timeframe of days (so people have to build custom solutions to clear out a user's client variables to simulate a timeout). The ability to return to using sessions in such cases can relieve some challenging problems.

To learn more about the mechanisms for session replication supported in a particular J2EE server, see that server's documentation. In .NET, sessions can be persisted to either a database or "state server", as configured in the machine.config or web.cong files with the .NET sessionState directive, as discussed in such resources as:
http://msdn2.microsoft.com/en-us/library/ms178586

Additionally, .NET users should also consider the commercial product, ScaleOut State Server, which offers many improvements over .NET's built-in session State Server mechanisms (and was built by former Microsoft engineers responsible for the state server feature).

Faq ID

304

Product

BlueDragon

Category

Admin Console, Exceptions, Supported Features

Question

Does BlueDragon support the notion of limiting the execution time of CFML pages?

Answer

BlueDragon does not support page execution timeouts in all the same ways developers may expect from their experience with ColdFusion.

First, BlueDragon does not currently support an admin console setting to "Timeout Requests" for all pages.

Second, like CFMX, BlueDragon does not support the use of RequestTimeout as a query string.

The .NET edition of BlueDragon does support the new CFSETTING RequestTimeout attribute, which was introduced in CFMX. If a CFML page on BlueDragon/.Net gets the .NET error, "Request timed out", this can be resolved by adding the CFSETTING tag (or increasing its timeout value) either on the page that's timing out or in the application.cfm (to affect all pages in that application).

Also note that by default, the page timeout for all .NET web pages is 90 seconds. This is imposed by the .NET framework, not BlueDragon. It can be configured in the Web.config (or Machine.config) file by using in the executionTimeout attribute of the <httpRuntime> element. For example:

Finally, the Java editions of BlueDragon do not support the CFSETTING attribute RequestTimeOut attribute. Indeed, they simply ignore it if used. As such, in the Java editions of BlueDragon, there is currently no way to limit execution time for a CFML page.

Faq ID

215

Product

BlueDragon

Category

Admin Console, DataSource, JDBC

Question

How can I add a datasource for a database not listed in the "driver types" drop-down?

Answer

Database access in BlueDragon is based on the standard Java JDBC API (for the Java-based products, Server, Server JX, and J2EE) or ADO.NET (for the .NET edition). It also supports ODBC in all editions, when deployed on Windows.

Depending on the edition of BlueDragon you're using, BlueDragon may provide built-in drivers or you may be able to add support for other databases, if you can obtain and install the needed drivers.

Free Server Edition

The free Server edition allows use of ODBC databases (on Windows) and (on Linux or OS X) either PostgreSQL or MySQL only. See below for issues regarding using ODBC and MySQL databases.

Server JX and J2EE Editions

The other editions, BlueDragon Server JX and BlueDragon/J2EE, are bundled with JDBC drivers for Microsoft SQL Server, Oracle, and PostGresQL databases. See below for issues regarding using ODBC, MySQL and other databases.

.NET Editions

BlueDragon for the Microsoft .NET Framework comes bundled with ADO.NET drivers for Microsoft SQL Server and Oracle. See below for issues regarding using ODBC and MySQL databases.

MySQL: All Editions

Other Databases: Server JX and J2EE Editions

What about other databases, such as DB/2 or DB2, Sybase, Informix, Ingres, SAP DB, Firebird, Pointbase, Cloudscape, etc.?

In order to access a specific vendor's database product on a Java version of BlueDragon, a JDBC driver for that product must be installed in BlueDragon (supported only on the Server JX and J2EE editions). For additional information about JDBC, see:

To add another database driver, install it per the driver's instructions and add the location to the BlueDragon classpath (in the admin console, go to "BlueDragon Server>vm classpath". Restart BlueDragon. Then, to configure the datasource on the "Datasources>Configure" page in the BlueDragon administration console, select "Other". The online help for the next page of the datasource wizard contains instructions on providing the driver class name and database URI for the driver you're adding.

See the online help in the BlueDragon administration console for further details, as well as further discussion in the BlueDragon User's Guide.

Other Databases: .NET Edition

What about other databases not listed in the drop down for adding datasources?

In order to use any databases other than those listed in the Admin Console, you must use an ODBC datasource. See the discussion above about ODBC datasources.

Faq ID

216

Product

BlueDragon

Category

Admin Console, Administration, DataSource

Question

How can I define a MySQL datasource?

Answer

MySQL is supported in all BlueDragon editions, either via JDBC or ODBC.

In the Server JX, J2EE, and .NET editions, an option is offered in the datasource configuration page of the administration console. In all editions, a MySQL datasource can be defined using ODBC.

In all cases, we do not provide the MySQL database drivers with BlueDragon. MySQL AB restricts redistribution of the MySQL drivers with other products, though the database itself is open source. For more information, see the MySQL Licensing Policy for more information.

But installing it is simple enough, whether to use ODBC or JDBC. The following steps describe first using the ODBC and then the JDBC driver.

Steps to using the MySQL ODBC Driver for all BlueDragon editions

After reviewing information on the page, choose the link for the latest stable release.

On the page that follows, scroll down to the download links.

Choose the download appropriate to your platform (choose "pick a mirror", then any listed site, and download using either http or ftp as you prefer).

For Windows users, run the installer and proceed to define an ODBC datasource using the Windows ODBC control panel. For other users, consider using the JDBC driver discussed below, or follow the instructions offered on the MySQL site for installing and using the ODBC driver.

Once an ODBC datasource has been defined, view the "data sources" page in the BlueDragon Admin console and choose the "ODBC Refresh" button below the list of any current datasources. BlueDragon will refresh the list with any ODBC datasources you have defined.

Steps to using the MySQL Driver for Server JX and J2EE editions

After reviewing information on the page, choose the link for the latest stable release.

On the page that follows, scroll down to "Sources and Binaries".

Choose the "download" link. Windows users will likely prefer to choose the zip file format, while Linux, Solaris, Mac and other users may prefer the tar.gz format.

The next steps (to extract the driver from the compressed file) will vary depending on the file type chosen, your operating system, your browser, and your installed support for unzip-type programs. The files within the compressed file (zip or tar.gz file) are stored within it in a directory such as mysql-connector-java-3.0.10-stable (your version of the driver may be slightly different).

You can choose to extract the files from the compressed file to a directory of that same name (mysql-connector-java-3.0.10-stable) on your system. But of all the files within the compressed file, the only one that really matters for use with BlueDragon is the actual driver jar file, which for the 3.0.10 version would be named mysql-connector-java-3.0.10-stable-bin.jar. You may choose to extract just that file, and place it on your file system within the BlueDragon directory as discussed in the following sections.

Configure BlueDragon to recognize the driver

The steps to configure BlueDragon to recognize the MySQL driver will vary from product to product (Server, Server JX, .NET, and J2EE):

In the Server (non-Windows) or Server JX editions, simply save the jar file (from above) as mysql.jar in the lib directory under BlueDragon, such as:

C:\BlueDragon_Server_JX_61\lib\mysql.jar

Then restart BlueDragon.

In the J2EE edition, you can leave the file named as it was on download, but simply place it in the WEB-INF/lib directory of the web application.

It's also possible in the Server JX edition to place the jar file anywhere in the file system and use its original name. Simply go to the "BlueDragon Server>vm classpath" page of the administration console and add the path to the JDBC driver JAR file. Then restart BlueDragon.

After making these changes and restarting BlueDragon, you can then define MySQL datasources using the provided "MySQL" option on the drop-down for driver types in the BlueDragon administration console.
For the .NET edition, follow the steps outlined in the admin console page for adding a MySQL datasource.

We encourage you to review the MySQL licensing policy before using their JDBC driver (or the MySQL database) with BlueDragon, as there are circumstances where they require you to purchase a commercial license or risk having your software "infected" by the GPL:

Password protection:
Password-protect access to the admin pages by configuring
and admin password on the "License & Security" page of the
BlueDragon Admin UI

IP Filtering
Access to the BlueDragon Admin UI can be restricted to particular client computers. To list the ips which will be allowed access, simply add them in a comma-separated list in the BlueDragon Admin UI under License & Security tab. Use the Help button at the top of the License & Security page for specific examples when configuring this option.

Remove the Admin Pages
You can entirely remove the Admin UI by removing or renaming the .bda file for the Admin UI which is located in the config folder of the BlueDragon installation.
For example, with BD .NET this would be a file named either admin11.bda or admin20.bda. BlueDragon.NET uses one other other, depending on which version of the .NET framework (1.1 or 2.0) is being used.
See BD FAQ #332 for info on how to switch .NET framework versions.
With BD JX, the name of the file is just admin.bda

If you choose this option, be aware that you must then manually make any changes to the global or individual BlueDragon.xml file (whose location for a given web site or web app is discussed in the BlueDragon/.NET documentation).

Rename the Admin Console
It is indeed possible to rename the url used to access the BlueDragon Admin console. The default is to append /bluedragon/admin.cfm to the URL for the web site or given virtual directory (or directory configured as a web application, as discussed in the documentation). You can change the path used to call up the Admin console by manually editing the bluedragon.xml.

(Notice that there is no /bluedragon/admin.cfm file in the web application. BlueDragon uses an internal mechanism, driven by configuration within the bluedragon.xml, to control the URL to be used.)

Within the <server> <file> element, there is an <application name="admin"> node:

You can simply change the <context> element to something other than bluedragon, then use that in the URL to call up the Admin console (still adding the /admin.cfm after that when typing the URL in the browser, not by adding it in the XML above).

If you wanted to change the admin console URL for all web apps on the server, apply this change in the global bluedragon.xml admin file.

Finally, if you change the bluedragon.xml file, you must restart the affected web app for the changes to take effect. See the documentation on how to restart web apps.

Faq ID

214

Product

BlueDragon

Category

Admin Console, DataSource

Question

How do I add a datasource for MS Access and other ODBC databases?

Answer

It's certainly possible to use MS Access and other ODBC datasources (on Windows machines), including PostGreSQL, MySQL, and others. Before discussing this, be aware of the difference between adding a datasource (such as a datasource called "mytest" pointing to a MySQL database called "mytest") and adding a database driver (such as the ODBC driver allowing you to use a MySQL or other database). This FAQ discusses both aspects. This is also discussed in the BlueDragon User Guide.

Auto-detection of ODBC Datasources

BlueDragon automatically detects and loads into its administration console any ODBC datasources (such as a "northwind" datasource pointing at the SQL Server "Northwind" database) that you or others may have defined in your environment (whether by way of the Windows "ODBC Data Sources" control panel tool or the ColdFusion 5 Administrator). You can immediately use any such datasources that are already defined when BlueDragon initializes on startup (unless you need to add a username or password).

Adding New ODBC Datasources

If you add datasources using either of those other means after BlueDragon has started, you can simply press the "ODBC refresh" button provided on the datasources page of the BlueDragon administration console. This will refresh the list and detect new ODBC datasources. Again, you may need to add a username or password to the datasource definition before you can use it.

Therefore, to add an MS Access or other ODBC datasource to BlueDragon, add it using the Windows "ODBC Data Sources" control panel tool. This can be accessed from "Administrative Tools" in Windows 2000 and above.

Adding a UserName or Password

The auto-detection mechanism cannot pick up any username or password defined in the ODBC datasource (entered in the Windows Datasource control panel tool). If you intend to rely on the username/password being provided in the datasource definition (rather than providing it on the CFQUERY), you must then re-enter those values in the BlueDragon datasource definition.

Adding New ODBC Drivers

If a driver for the database you wish to use isn't listed in that Windows ODBC Data Sources panel, you can add them by installing them yourself. Many databases will automatically add a new ODBC driver into the windows environment during installation of the database software. Otherwise, you may be able to obtain the database driver via the internet.

For other databases, simply seek the appropriate ODBC driver from any source on the Internet, and follow the instructions above.

Faq ID

286

Product

BlueDragon

Category

Admin Console, Version differences

Question

How do I determine the release of BlueDragon I'm running?

Answer

You can view your current engine revision in any of several ways:

it's displayed at the top of the debugging info displayed on each CFML page (assuming you've enabled it in the BD Admin console)

it's displayed in the Admin console itself, at the bottom of the general>runtime state page

it can be viewed by outputting the variable #server.coldfusion.productversion# in a CFML page (yes, we use the same ColdFusion structure in the Server scope that ColdFusion uses to report this sort of info)

Faq ID

333

Product

BlueDragon

Category

Admin Console, Administration, General Info, Miscellaneous

Question

How do I determine what BlueDragon.NET Admin Console pertains to a particular URL?

Answer

BlueDragon.NET has a separate Admin Console for each IIS web site and web application. This is an incredibly useful feature when you're running disparate applications on one machine because it allows you to configure them entirely separately and differently. It also means that you can trip yourself up if you configure something for one site when you mean to configure it for another. Sometimes it can be difficult to tell what BlueDragon.NET Admin Console applies to a particular URL. Here's an easy way to tell: take the following CFML code, put it in a .cfm file in the directory of interest, and browse to it as you would the directory of interest (NOTE: code in an Application.cfm file may affect the normal processing of this file). It will give you a link to the BlueDragon.NET Admin Console that applies to that URL.

I get a "General SQL Error" trying to use or verify a datasource. Why doesn't it give a more useful error?

Answer

We've noticed that with some JDBC drivers you'll often get a "General SQL Error" the first time you try to verify or use the datasource, and then a more specific error the second time. We think we know why this might be happening and are investigating a solution. In the mean time, if you get a "General SQL Error" when verifying or using a datasource, try verifying it a couple of times (in the admin console) to see if you get a better message the second time.

Faq ID

316

Product

BlueDragon

Category

Admin Console, Administration, Installation, Registration

Question

I want to input my BlueDragon license key. How do I do that?

Answer

Normally this is done using a web browser. In that scenario, you would simply use the browser to access the BD admin pages, and input the key on the Licensing page.

When a BD installation has no license key installed, it will
run in Developer Mode. Note that this will occur if you use
the BD admin pages to remove the key.

When removing a key, you should always do so from a browser that is running on the SAME machine as BlueDragon. To understand why, read on...

When BD is running in Developer Mode, the BD admin pages can
only be accessed from a browser that is running
on the same machine where BD is installed.

This means that it is possible to use a remote browser
to remove a license key, but then that remote browser will be
denied any further access to the BD admin pages. Remote browsers are denied such access for security reasons.

In this case, here is how to enter your license key:

If using BD Server or BD Server JX:

Stop BlueDragon (see below for more details on stopping/starting)

Use a plain text editor to edit the "servers.properties" file so that the value of the "bluedragon.serial" property is your license key. (The file is in the config folder of the BlueDragon installation directory.)

Start BlueDragon

If using BD .NET or BD J2EE:

Stop the BlueDragon web application (see below for more info on starting/stopping)

Use a plain text editor to edit the bluedragon.xml file for your BD installation. (In a J2EE web application this file is located in the web app's WEB-INF\bluedragon directory. In a .NET implementation, the location depends on the installation choice: in a "single virtual directory" installation, it's that virtual directory's bluedragon\config directory. For the other .NET installation choices, the key goes in a special central bluedragon.xml in the bluedragon.net\config directory.)

In that file, you'd need to look under the "<server>" node, then under the "<system>" node. Under there is where you'd need to have a node that looks like this:
<licensekey><YOUR_LICENSE_KEY_GOES_HERE></licensekey>

So for example if your key is "ABC" then you'd have something like this in your bluedragon.xml file:

Stopping/Starting BlueDragon

For more information on stopping and starting the BlueDragon web application as deployed on J2EE or .NET, see FAQ 267 the respective BlueDragon manuals for those products.

Faq ID

288

Product

BlueDragon

Category

Admin Console

Question

I'm having trouble with a datasource in the .NET edition. I've added it, and verified it in the Admin console, yet when I try to use it in my CFML page, I get "The datasource xxx could not be found". (Or I make other admin console changes and they don't seem to take effect.)

Answer

The problem is likely due to the fact that BlueDragon/.NET enables multiple admin consoles, one per web site or virtual directory (because .NET regards each web site or virtual directory as a different "application domain"). The problem is likely that you're adding/verifying the datasource in one admin console (such as that for the web site root), but running your CFML page within a virtual directory or another web site. You must add the datasource (and any admin configuration settings) in the admin console for the web site or virtual directory in which the code is running. For more info on finding the appropriate Admin Console, see FAQ 333.

If you're concerned because you want to add a datasource to all the admin consoles, and don't want to add/update it one-by-one, be aware that BlueDragon/.NET supports a notion of inherited global admin settings, where you edit a central bluedragon.xml with the desired shared settings, and all the web sites and virtual directories inherit from that. See section 3.1.2 of the manual for more information.

For more information, see the manual, "Deploying CFML on ASP.NET Servers", particularly sections 3.1.1 and 9.1.7 (the section numbers are as of the 6.2 release of the docs).

Faq ID

327

Product

BlueDragon

Category

Admin Console, Session Tracking

Question

I'm running on BlueDragon.NET, on IIS 6, and am frequently losing my sessions and/or am frequently being logged out of the BlueDragon Admin console. What gives?

Answer

The problem is not a BlueDragon one but rather a common problem that trips up even ASP.NET developers. If you set up your IIS 6 application pool to enable the "web garden" (or setting the "max number of processes" for that pool to greater than 1), you are in effect creating a cluster of instances.

A problem exists, however, if you enablel .NET sessions in BlueDragon's admin and also have left .NET's session management to its default of storing sessions in memory (inproc). The problem is that, now with web gardens enabled, if a user is moved by IIS and .NET from one process/instance to another, the session on the first won't exist on the second.

The simple solution is to change your .NET session configuration from "inproc" to either "stateserver" or "sqlserver". Again, this is purely a .NET problem with a .NET solution. It was discussed at further length in a BlueDragon blog entry.

Faq ID

399

Product

BlueDragon

Category

Admin Console, General Info

Question

I've configured a Missing Template Handler in IIS7 for BlueDragon but I continue to get a Server Error, 404 error page. How can I configure my custom Missing Template Handler to override the server's custom page?

Answer

In IIS Manager, choose Error Pages, located under the IIS configuration section. Highlight 404 Status Code and choose "Edit Feature Settings" in the far right frame. If Custom Errors is selected, this indicates that the Server will provide the Custom Error page and not BlueDragon. You should choose Details and your Missing Template Handler will be served when a 404 occurs.
If this does not help, see FAQ 374

Faq ID

306

Product

BlueDragon

Category

Admin Console, Security

Question

I've lost my password to open the BlueDragon admin console. How can I recover from this?

Answer

Stop BlueDragon. For BlueDragon JX, stop the BlueDragon JX service using the services control panel. For BlueDragon.NET, stop IIS. For BlueDragon JEE, stop the JEE container.

Edit your "bluedragon.xml" configuration file (whose location is discussed in FAQ 312) and find the <server><system><password> entry. Delete whatever value you find there so that the <password> entry is empty:

Restart BlueDragon. For BlueDragon JX, start the BlueDragon JX service using the services control panel. For BlueDragon.NET, start IIS. For BlueDragon JEE, start the JEE container.

Since there's no password defined, you'll be able to access the BD admin console directly without logging in. Immediately set a new password.

Faq ID

283

Product

BlueDragon

Category

Admin Console, Security

Question

Where do I find the cfml pages for the BlueDragon Admin console?

Answer

There are no BlueDragon Admin cfml pages. The pages are stored in admin.bda located in the \config folder of your BlueDragon Installation directory. If you are running BlueDragon.NET, the file is named admin11.bda and admin20.bda. Your version of .NET determines which adminXX.bda is being used.

Faq ID

266

Product

BlueDragon

Category

Admin Console, Installation

Question

Where do I place files in support of CFXs?

Answer

In the Java versions of BlueDragon, the Java class file supporting the CFX must be either an unbundled .class file or bundled within a .jar archive. For BlueDragon Server or Server JX, the class files can be placed in the /classes directory while JAR files can be placed within the /lib.

For BlueDragon/J2EE, class files can be placed in the /WEB-INF/classes directory, and JAR files can be placed within the /WEB-INF/lib directory.

The location of the bluedragon.xml file, which holds changes made in the BlueDragon admin console, depends on the edition of BlueDragon being used.

In the Server or Server JX editions, it's in the [bluedragonroot]/config/ directory where [bluedragonroot] is the location where BlueDragon was installed (such as C:\BlueDragon_Server_JX_62, or /usr/local/NewAtlanta/BlueDragon).

In the J2EE edition, it's in the WEB-INF/bluedragon/ directory of the BlueDragon web application or WAR file.

In the .NET edition, the location depends on the kind of installation performed and whether multiple applications (web sites, virtual directories, or directories defined in IIS to be an application) have been defined. See the documentation, Deploying CFML on ASP.NET Servers, in the section "BlueDragon.xml Configuration File Location", for more information.

Faq ID

252

Product

BlueDragon

Category

Admin Console, Administration, Web Application

Question

Why aren't my session being shared between CFML and ASP.NET pages?

Answer

The simplest reason would be if you have not enabled ".net sessions" in the BlueDragon admin console's "application>settings" page. Further, be aware that your code may be running in a virtual directory or web site where its own BlueDragon Admin Console settings differ from the global admin console. Use http://yourdomain/yourvd/bluedragon/admin.cfm to look at the Admin Console for the virtual directory. For more info on finding the appropriate Admin Console, see FAQ 333.

Another possible issue could be that your CFML code is using a named application (CFAPPLICATION NAME="xx" SESSIONMANAGEMENT="yes"), in which case you must write code in the ASP.NET page that properly accounts for the use of such a named application (by referring to it as a hashtable in ASP.NET).

Finally, a more subtle explanation could be that CFML and ASP.NET files are being processed by different versions of the .NET framework. For instance, if CFM files are set in the IIS admin console to be mapped to C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\aspnet_isapi.dll, but the ASPX files are set to be mapped to C:\WINDOWS\Microsoft.NET\Framework\v2.0.40607\aspnet_isapi.dll, then these different versions will NOT share session variables.

Again, if your code is running in a virtual directory or its own web site, the configuration of these mappings may be set for that level, so be sure to check carefully.

Faq ID

261

Product

BlueDragon

Category

Admin Console, Known Limitations and Workarounds

Question

Why can't I register my Java CFX tags in BlueDragon .NET?

Answer

The .NET Framework does not support Java classes. Any Java programs must be recompiled using Visual J# (which is part of Visual Studio.NET). As such, BlueDragon/.NET does not support use of Java CFXs without their being recompiled in .NET (using the CFX.NET.dll that is provided with BlueDragon.NET).

See the CFX directory where BlueDragon/.NET is installed for more information on how to compile a CFX (Java or C++) for use with BlueDragon/.NET.

If you have a CFX that you need to run, but you do not have the source code to recompile it, consider that it may be possible that you can find that CFML has evolved (or a BlueDragon enhancement has been made) to offer a workaround. Also, the .NET Framework libraries may offer an alternative solution to the need.

If there is no choice but to recompile the CFX, and the problem is that you do not own the source for the CFX, we may be able to work with the vendor to help them recompile the CFX for use with .NET. Contact us, or have them do so, at this account.

Faq ID

208

Product

BlueDragon

Category

Admin Console, Administration, Known Limitations and Workarounds

Question

Why do the admin pages not display?

Answer

On some Linux systems (especially Debian and SuSE), installations of BlueDragon Server and Server JX may have problems with the display of the BlueDragon Administration Pages (e.g. http://localhost:8081/bluedragon/admin.cfm). This problem is caused by failures to decrypt the admin page CFML templates. The primary symptom of the problem is the return of a page in place of the admin page which contains a stack trace caused by a "java.lang.InternalError: Unexpected exception in IJCE_SecuritySupport.registerTargets()". Also a number of "Netscape security model is no longer supported." messages will appear in "<BD-root>/logs/BlueDragon_Server.log".

Replacement of the installed version of "<BD-root>/jre/lib/ext/cryptix32.jar" with this patched version from the BlueDragon FTP site, will correct the problem.

Faq ID

251

Product

BlueDragon

Category

Admin Console, Supported Features

Question

Why don't I see any output trace information when using CFTRACE?

Answer

One of the new features in BlueDragon 6.2 is support for CFTRACE, as introduced in CFMX. As in CFMX, it can be used such as in <cftrace text="sometext"> which can cause a line such as this to be written to the debugging output:

[CFTRACE ] [[pathtofile] @ line: 1] - sometext

This output will of course be shown only if debugging output is enabled in the BlueDragon admin console. But more than that, there is a specific option in the the admin console (debugging>settings page) labelled "trace points", which must also be checked. If "trace points" is not enabled, CFTRACE tags are ignored.

For those new to CFTRACE, note as well that output can be written to the page itself at the point of the CFTRACE (rather than in the debugging output) by adding INLINE="yes" as an attribute of the CFTRACE. This option also still requires that the debugging output (and trace points) options be enabled.

Note that this means that CFTRACE can be left in a page even in production, since they create no output if debugging is disabled.

Administration

Faq ID

341

Product

BlueDragon

Category

Administration

Question

Can I move the BlueDragon for J2EE Servers work directory outside my application's open directory or EAR/WAR?

Answer

Yes. In order to do this, edit the <param-value> sub-element of the <init-param> element whose <param-name> sub-element's value is BLUEDRAGON_WORKING_DIRECTORY to have an absolute path like the following:

IMPORTANT NOTE: you must not use the same work directory for more than one Bluedragon for J2EE Servers application. If you have more than one BlueDragon for J2EE Servers application, consider using each application's context path as part of the path to its working directory.

NOTE: in addition to BlueDragon for J2EE Servers, this FAQ is applicable to BlueDragon, BEA Weblogic Edition.

Keywords: log, logs, work directory, working directory

Faq ID

352

Product

BlueDragon

Category

Administration, Profiling Servlets

Question

Can I use FusionReactor with BlueDragon?

Answer

Yes.
It is possible to use FusionReactor [FR] with BlueDragon for J2EE Application Servers. Follow the Manual Installation steps given in the FR Installation Guide.

It is also possible to use FR 3.0 with BlueDragon JX 7.1 or higher (not older versions of BDJX). Detailed instructions for that combination follow:
At the time of this writing (August 2008), the FR
Installation Guide is available from the FusionReactor Website.
From there click "FusionReactor" (along the top) and then
"Online Support" (lower right).
Then click the "Documentation" link under the "FREE Online Support" heading.
That is where we found the link to the FR 3.0 Installation Guide

The last section in that guide is entitled "Manually installing FusionReactor".
It contains a subsection entitled "Overview" which you should read, but don't
perform any steps yet.
There are 2 other subsections that deal with Manually installing FR (one for
Windows and one for Unix). Those "manual installation" subsections give the
step-by-step procedure for "hooking" FR into a CFML-Enabled Servlet/JSP Engine.
If you are using BDJX 7.1 then you should follow those steps as they are given
but with the following exceptions/clarifications:

In step #4, the "default web descriptor" for BDJX 7.1 is:
C:\BlueDragon_Server_JX_71\webapps\default\default-app\WEB-INF\web.xml
You'll copy the filter definition from the fusionreactor-web.xml file
into that default web descriptor as follows:

Place your cursor at the start of the last line in that file
(just before </web-app>).

Paste the filter definition right there.

Ensure that the path to the reactor.config file is correct.

In step #5, look over the entire contents of the reactor.config file and make
sure that all references to the FR installation folder are correct (they
must all match where you actually unpacked the FR archive)

In step #6, copy the fusionreactor.jar file to the BDJX 7.1 lib\ext folder.

In step #7, you must edit the OPTIONS line in StartBlueDragon.bat file
so that line now reads (all on one line):
set OPTIONS=-Xrs -XX:+UseParallelGC -Djava.library.path="%PATH%;C:\FusionReactor\etc\lib"OR you could optionally NOT edit the start script at all but rather copy the contents of the C:\FusionReactor\etc\lib folder into a folder that is already listed in the value of the java.library.path JVM System property (navigate to system information - more information on the BDJX Admin UI to see that value).

In our testing we found that FR is very picky about the syntax of the reactor.conf file.
For example, we found that absolute paths needed to use forward slashes / rather than
backslashes \.
For example:
html_path=C\:/FusionReactor/htmlAnd Note that the full colon in the sample above is correctly escaped with a backslash.
This is necessary due to the fact that FR reads the reactor.conf file in as a Java
Properties file.
In our testing, we found that when reactor.conf contained file path syntax errors FR would output
the follow sort of messages to the BlueDragon Server JX.log file:
javax.servlet.ServletException: The value for key crashprotection.logfile was not convertible to its correct type...

NOTE:
FusionReactor does not work with any other edition of BlueDragon, including BlueDragon .NET Standard and BlueDragon .NET Enterprise.

Faq ID

353

Product

BlueDragon

Category

Administration, Profiling Servlets

Question

Can I use SeeFusion with BlueDragon?

Answer

It should be possible to use SeeFusion with BlueDragon for J2EE Application Servers and BlueDragon, BEA WebLogic Edition. However, SeeFusion does not work with any other edition of BlueDragon, including BlueDragon Server, BlueDragon Server JX, BlueDragon .NET Standard and BlueDragon .NET Enterrprise.

Faq ID

258

Product

BlueDragon

Category

Administration, Supported Features

Question

Does BlueDragon support the coldfusion.server.ServiceFactory in CFMX?

Answer

There is an undocumented API for CFMX which provides programmatic access to the Administration of the server, including listing and updating such information as datasources, mappings, schedule tasks, etc. We appreciate that developers want such a solution in BlueDragon.

Still, this ServiceFactory is not only undocumented but has been deprecated in CFMX 7 in favor of a new CFC-based api, we will not be offering any implementation of these identical undocumented ServiceFactory methods.

We had already begun creating a CFC to provide programmatic Admin access even before the CFMX 7 beta began, and we are still debating whether to proceed with and release that, or rewrite to follow CFMX 7's CFC component and method names After resolving this and related matters, we will make the CFC available as soon as possible.

In the meantime, if BlueDragon VAR partners or other customers have a desparate need for this functionality, we have an early version of our own admin api CFC available. Contact sales@newatlanta.com if interested.

Faq ID

253

Product

BlueDragon

Category

Administration

Question

Does BlueDragon work with Windows XP SP2?

Answer

Yes, it does. It's worth noting, however, that among the new security features in XP SP 2 is one that--if set--may make it seem that BlueDragon does not work.

In the new Windows Firewall feature (Start>Control Panel>Security Center>Manage Configuration Settings for Windows Firewall), be sure that the option "Don't Allow Exceptions" is not checked. If it it is checked, then the BlueDragon port will be blocked "silently" and BlueDragon won't work.

Faq ID

285

Product

BlueDragon

Category

Administration

Question

How can I determine if my .NET web application is restarting too often?

Answer

If you find that requests for any page in a .NET web app (whether aspx or cfm) seem to be running slowly for every or many requests, one thing to determine is whether the "app domain" for the ASP.NET pages might be unloading due to some problem. (.NET defines each web site and each virtual directory as a web app, or technically an "application domain".)

There are various reasons that an application may be restarted, as discussed in the BlueDragon manual, "Deploying CFML on ASP.NET Servers", in the section "Automatic Stopping/Restarting of .NET Web Applications".

If some problem of unexpected behavior is causing .NET to unload the web app, then any subsequent request for a page after it's been unloaded will spend time trying to restart the app domain. This could cause a drag on execution of requests.

Fortunately, .NET tracks restarts by way of statistics that can be viewed with Windows Performance Monitor start. You can observe whether restarts are occruring by viewing the PerfMon tool. Open Performance (from Administrative Tools), then switch to "report view" (ctrl+r) (to see numbers, not charts), then "add" (ctrl+i) the appropriate counter. To get that counter, select the computer to be monitored, then for "performance object", choose "ASP.NET v2.0.50727" (assuming you are using the .Net 2.0 framework), and choose "application restarts" and "add".

This will add a counter showing how often all or selected app domains restart. If it's a large number, then you have experienced many restarts since the server itself was started. You could run a small sample application (also provided in the documentation) to force an unload of the app domain, and again you should see the counter go up. (See the related section on the negative impact of application restarts on sessions.)

Note that you can also use PerfMon to set up alerts and logs instead to "watch" any of these counters.

Faq ID

267

Product

BlueDragon

Category

Administration, General Info, Installation

Question

How do I start and stop BlueDragon Server?

Answer

BlueDragon Server and Server JX are just two of four editions of BlueDragon. As standalone editions, they run as a service or daemon that can be stopped/started, as discussed in the FAQ.

If you're a Windows user, you can restart BlueDragon through the Services Control Panel. Or, you can use the StartBlueDragon.bat and StopBlueDragon.bat found in the installation directory's bin folder.

If you're a Linux or MacOsX user, you will find a StartBlueDragon.sh and StopBlueDragon.sh in the BlueDragon installation folder's bin directory. (Use ./StopBlueDragon.sh to run the stop script, for instance.)

For the J2EE edition, you can restart the BlueDragon WebApp as supported by whatever J2EE or servlet engine you're running. For the .NET edition, see the manual, "Deploying CFML on ASP.NET Servers" for more information on starting/stopping a BlueDragon .NET application.

Faq ID

332

Product

BlueDragon

Category

Administration, Web Server Support

Question

How do I switch my .NET framework betweem .NET 1.1 and .NET 2.0?

Answer

Assuming you have both frameworks installed (and rebooted the machine afterwards),
then from the IIS Manager you would open the Properties dialog for the IIS "component" (i.e. "level")
you wish to switch. When I say "component" or "level" I'm referring to the
fact that inside the IIS manager, it is possible to open the Properties dialog
for 3 different "levels".

For ALL websites... the node labeled "Web Sites" (whis is global for all sites)

The node for an indididual website

Or the properties for an individual Virtual Directory (VD) within a specific website

How you installed BD .NET (global in the GAC, for a specific website, or for a specific VD)
will decide for which "level" you should open the Properties Dialog inside the IIS manager.

Once you have the properties dialog up, go to the tab labeled "ASP.NET" and
select (from the drop-down list) the .NET version you want that "level" to use.
Apply the change.
All of this so far is just .NET "stuff" and really has nothing to do with BlueDragon.

If using BlueDragon .NET 6.2.1 then you could immediately go to the tab named "Home Directory" (or "Virtual Directory" if your "level" is a VD) on that same Properties dialog, and click the "Configuration..." button and verify that your .cfm, .cfml, and .cfc mappings there are pointing to the correct version of the .NET framework.
Note that BD 7.0 will not support .NET 1.1, it will only support .NET 2.0. So BD 7.0 won't support this sort of framework version "switching".
Also note that if you installed .NET 2.0 *after* BD .NET 6.2.1 was already installed, then certain BD-related components needed to support .NET 2.0 were not installed (since .NET 2.0 was not present at BD install time).
So you'd need to uninstall BD and then reinstall it with .NET 2.0 being present on the machine before BD could run on .NET 2.0.

Faq ID

247

Product

BlueDragon

Category

Administration, Installation, Security

Question

How does IIS determine which account BlueDragon.NET requests run under?

Answer

The account that BlueDragon.NET requests run under is determined by the following algorithm:

1) If web.config contains an <identity> element with the attribute impersonate set to "true" then BlueDragon.NET will run under the username specified in the <identity> element. If an empty string is specified for the username then BlueDragon.NET will run under the authenticated user for authenticated requests and under the anonymous user for unauthenticated requests.

2) If web.config doesn't contain an <identity> element and machine.config contains an <identity> element with the attribute impersonate set to "true" then BlueDragon.NET will run under the username specified in the <identity> element. If an empty string is specified for the username then BlueDragon.NET will run under the authenticated user for authenticated requests and under the anonymous user for unauthenticated requests.

3) If impersonation is disabled then:

with IIS 5 and earlier, BlueDragon.NET will run under the user specified in the <processModel> element of machine.config. The <processModel> element cannot appear in web.config.

with IIS 6, BlueDragon.NET will run under the application pool identity of the application pool it is configured to run under.

The following ASP.NET code can be used to determine which user ASP.NET requests are running under:

What is the difference between managed CFX tags and unmanaged CFX tags in BlueDragon .NET?

Answer

BlueDragon/.NET does not support unmanaged CFX tags. An unmanaged CFX tag is a C++ CFX compiled with a standard C++ compiler (in other words, have not been compiled to .NET). C++ CFXs can be recompiled to be "managed" using Visual Studio.NET (or more specifically, managed C++).

See the CFX directory where BlueDragon/.Net is installed for more information on how to compile a CFX (Java or C++) for use with BlueDragon/.NET.

If you have a CFX that you need to run, but you do not have the source code to recompile it, consider that it may be possible that you can find that CFML has evolved (or a BlueDragon enhancement has been made) to offer a workaround. Also, the .NET Framework libraries may offer an alternative solution to the need.

If there is no choice but to recompile the CFX, and the problem is that you do not own the source for the CFX, we may be able to work with the vendor to help them recompile the CFX for use with .NET. Contact us, or have them do so, at this account.

Faq ID

279

Product

BlueDragon

Category

Administration

Question

When I try to run a page using BlueDragon.NET, I get an error stating that "The resource cannot be found" and "The resource you are looking for (or one of its dependencies) could have been removed, had its name changed, or is temporarily unavailable. " But the web site is properly defined and points to the proper docroot. What gives?

Answer

The .NET framework is quite sensitive to the web site doroot being entered in IIS *without* a trailing slash. If you've defined the docroot to be c:\inetpub\wwwroot\, change it to just c:\inetpub\wwwroot.

Faq ID

284

Product

BlueDragon

Category

Administration, General Info

Question

Why can't I find a \config folder after installing BlueDragon.NET?

Answer

The config folder for BlueDragon.NET is not created until the first request. Try requesting index.cfm.

Faq ID

198

Product

BlueDragon

Category

Administration, Installation, Known Limitations and Workarounds, Web Server Support

Question

Why didn't BlueDragon find the IIS installation?

Answer

This a known problem for versions older than BlueDragon 6.0 in which BlueDragon does not find the IIS installation because of a missing "Scripts" virtual directory and associated Windows Registry entry. This will be fixed in an upcoming release of BlueDragon 6.0. This FAQ was written in 2003.

To workaround the problem, create a virtual directory named "Scripts" in the IIS configuration. This virtual directory typically points to the physical directory C:\Inetpub\Scripts. After creating "Scripts", restart IIS. The restart is ABSOLUTELY NECESSARY since it creates a Windows Registry entry that BlueDragon requires. After the restart, restart or reinstall BlueDragon and it should recognize the IIS installation.

Faq ID

197

Product

BlueDragon

Category

Administration, Installation, Known Limitations and Workarounds, Web Server Support

Question

Why doesn't BlueDragon find my Apache installation?

Answer

The solution to this challenge depends on the edition of BlueDragon that you're running.

First, BlueDragon Server (free edition) only supports Apache on Linux. If you're running it on Windows, you will not be presented the opportunity to integrate with Apache, even if you have it installed.

In recent Apache for Windows releases (e.g. 1.3.26), the installer allows a selection between installation for a specific user or as a system service. BlueDragon currently has some difficulty detecting this "specific user"/non-system installation and therefore does not allow the BlueDragon adapter to be installed.

However if the user used to run BlueDragon is changed to the same as used for Apache, BlueDragon will detect Apache and allow adapter installation. This requires that both Apache and BlueDragon be installed first, then the BlueDragon user changed to match that of Apache.

This is done using the following steps.

From the Services control panel, select the "BlueDragon Server" (or "BlueDragon Server JX") service and then the properties icon.

On the properties panel select the "Log On" tab.

Next change the "Log on as:" setting from "Local System account" to "This account" and enter the account name that matches the account used by Apache.

After "Apply"ing the changes, restart the BlueDragon service.

An entry for the Apache server will now appear on the "web server adapter" page of the BlueDragon Administration Console and configuration can be completed.

Finally, if you continue to have challenges integrating with Apache, please see other FAQ entries that refer to Apache.

Faq ID

199

Product

BlueDragon

Category

Administration, Installation, Known Limitations and Workarounds, Web Server Support

Question

Why doesn't BlueDragon operate on the virtual hosts defined in IIS?

Answer

Symptoms of this occuring are that a request for a ".cfm" page will return the raw data which activates the browser "Save As" or "Enter file to save to..." or "File Download" popup. These same symptoms may also occur for requests with the other extensions supported by BlueDragon including ".cfml", ".cfc", and ".jsp".

Prior to and including BlueDragon Server 3.0.1, the "Scripts" virtual directory was required to be defined for each virtual host within IIS. If not defined, the installed BlueDragon filter was not recognized and therefore ".cfm" pages not processed by BlueDragon.

After and including BlueDragon Server 3.0.2, this problem is most likely the result of the removal or replacement of the "Application Mapping" for ".cfm" in the virtual host definition. BlueDragon Server installs "application mappings" to ONLY the Master Properties of an IIS installation. These master properties may be overridden by "application mappings" defined for the specific virtual host.

DataSource

Faq ID

273

Product

BlueDragon

Category

DataSource, Web Services

Question

I'm trying to set up an ASP.NET page to return a Datatable to a CFML page as a web service. I get an error in the ASMX page. What's wrong?

Answer

If you receive any of the following errors .NET errors while trying to create/process a .NET web service (ASMX file), this FAQ applies to you:

System.NotSupportedException: Cannot serialize member System.ComponentModel.MarshalByValueComponent.Site of type System.ComponentModel.ISite because it is an interface.

System.Data.DataRelation cannot be serialized because it does not have a default public constructor.

The document at the url http:///servicename.asmx was not recognized as a known document type.

The problem, of course, is not a CFML (or BlueDragon) error, since it's happening in the ASMX page (the asp.net web service page). It's due to an error in .NET where datatables cannot be returned in web service calls. Since we show examples of passing datatables between CFML and ASP.NET, this problem may become apparentto those doing experimentation with ASP.NET web services.

The good news is that there is a Microsoft Technote explaining the problem. The bad news, again, is that you cannot pass a .NET datatable via a web service, because they are not themselves serializable. You can, however, return a dataset (containing the datatable). The technote shows very clear examples of how to solve the problem.

Their solution will indeed work. You just need to know how to grab a table out of the dataset, in order to process that in CFML.

If you use the example at the technote page, you could use the following CFML to obtain the "Authors" datatable within CFML (and of course, this would work for any code where the dataset contains a table, if you just name the proper table):

Microsoft has not made a 64-bit odbc driver for Access so you can only configure it using the 32-bit odbc manager. If BlueDragon is launched as a 64-bit app then it won't be able to see the 32-bit datasources.
If you have a 64-bit machine and you must use an Access ODBC datasource, the only solution is to install a 32-bit Windows OS on your 64-bit machine and then run BlueDragon's 32-bit installer.

Faq ID

254

Product

BlueDragon

Category

DataSource

Question

Why can't I update an Access database with BlueDragon for the Microsoft .NET Framework?

Answer

When trying to update an Access database using BlueDragon/.NET, you may receive the error: "Operation must use an updateable query". This is a problem not caused by BlueDragon but instead the .NET framework. Indeed, the problem is discussed in the Microsoft Knowledge Base article, http://support.microsoft.com/default.aspx?scid=kb;en-us;316675.

The simplest solution may be to edit the security properties for the MDB file (using Windows Explorer, right-click on the MDB file, choose properties, then the "security" tab). Add the ASP.NET acccount (or "everyone") as a user (choose "add", then "advanced", then "find now", and select "ASPNET" or "everyone"), and give that user "modify" and "write" permissions.

You could also set this security not just at the file (mdb) level but at the directory level, for the directory holding this file (or other files) that you want to edit in a .NET web application (such as BlueDragon/.NET).

If you have opened the file in a currently running instance of BlueDragon or ColdFusion (or Access) before making that change, you'll see that the directory where the MDB is stored will now have an LDB file of the same name. In this case, the change you've made won't take effect until you restart whatever app(s) had opened the file (which will release this LDB lock file and make it disappear). In the case of BlueDragon/.NET, you'd want to restart IIS (or restart the web application, as discussed in the BlueDragon/.NET documentation) to make that LDB file go away.

Once the file is gone, the change to security will take effect and the next refresh of the page doing the database update should work as expected.

Faq ID

314

Product

BlueDragon

Category

DataSource, Security

Question

With BD.NET, can a SQL Server datasource be configured to use a trusted connection (Windows Authentication)?

Answer

Yes this is possible but does require some configuration, due to security restrictions in .NET. Also, the changes required depend on whether IIS and SQL Server are running on the same machine. (You can also work-around this temporarily, which may make sense in some cases, as discussed at the end of this FAQ.)

If IIS and SQL Server are running on the same machine then follow these steps:

- determine which account BD.NET requests run under as described in FAQ #247
- make sure this user has permission to access the SQL Server databases
- when configuring the datasource be sure to set the Server Name field to "127.0.0.1" and the Connection String field to "trusted_connection=true"

If IIS and SQL Server are running on different machines then you will need to use impersonation in IIS in order to use a domain account that can be seen by SQL Server. Refer to the following Microsoft knowledge base article for more information on impersonation:

Be sure also to select an account that would have permissions on the server running IIS to write to the files that the user running .NET would have had, such as the .NET framework temporary directory location (which might be C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files), and the C:\BlueDragon.NET directory. You could consider looking at what what groups have permissions to those directories and assign the selected user to that group.

Once you have IIS configured for impersonation then follow these steps:

- make sure the domain account used for impersonation has permission to access the SQL Server databases
- when configuring the datasource be sure to set the Connection String field to "trusted_connection=true"

Of course, keep in mind that if you're just getting started with configuring BlueDragon in a test environment and want to get things running as quickly as possible, you could also just enter the username and password rather than rely on the Trusted Connection feature (and go change that later before moving to production).

Debugging

Faq ID

375

Product

BlueDragon

Category

Debugging

Question

BlueDragon.NET is not performing as fast as I expected. What are some things I can do to debug this?

Answer

The first thing you need to do is turn on debugging in Bluedragon Admin UI. Choose debug settings and check Debug Output in the first table. Then, choose Page Execution times in the second table. Can the slow-down be isolated to a particular page or function?

If you can isolate the problem to a specific page, try using cftimer tag to narrow down the lag to a specific area in your code.

Are there datasource connection issues? Look in Bluedragon Admin UI under Data & Search->Runtime state. Look at the value for Wait Connections for each DataSource connection pool. If Wait Connections is anything above zero, you need to increase your Max Connections value for that datasource. It is configurable in BlueDragon Admin UI-DataSources->Choose that Datasource and increase the Max Connections value.

Look in bluedragon.log located in your \Web Site x\work folder for the website you are testing. Are there any RunTimeErrors being logged? If yes, open each log (there will be a path logged in bluedragon.log to find the html version of the error) to determine if any of the errors being reported could be slowing things down.

Is your application reloading? See FAQ #285 to determine if this could be causing some problems.

Faq ID

351

Product

BlueDragon

Category

Debugging, Exceptions, General Info

Question

Can I use FusionDebug with BlueDragon?

Answer

No, FusionDebug does not work with BlueDragon.

Faq ID

393

Product

BlueDragon

Category

Debugging

Question

How can I troubleshoot a memory leak involving BlueDragon .NET?

Answer

Startup the Windows Task Manager and go to the "Processes" tab.
Then check the checkbox at the bottom labeled "Show processes from all
users".
Then click the column header for the column named "Name" (to sort the
processes alphabetically by name).
Then look for processes named "w3wp.exe"
At the top of the Task Manager window is a menu from which you may
navigate as follows:
View - Select Columns...
From there you can customize the list of columns to include a column
for the PID.
Note the PID of your w3wp.exe process.
If you have more than 1 w3wp process running you may need to turn off
the App Pool that BD .NET is using and take note of which w3wp PIDs
remain. Then turn it back on and take note of the newly listed w3wp.exe
PID (that would be the one in which BD.NET is running).
Be sure to configure that App Pool to never recycle itself.
Then periodically (every day or so) take note of the memory usage of
that PID.
We've done this before for 8 consecutive days in a non-memory-leaking setup. Data collected during the first 7 days suggested an upward trend, but data on the 8th day confirmed that there was no leak. So you may need to watch this across many days to get the truth for your own system. It just depends on how often the .NET garbage collector runs on your system. The highest value we saw in our trivial test was 86,416 Kilobytes which is tiny and well within acceptable memory usage for an IIS Application Pool

IF you can confirm that the memory *trend* of your PID across many days and or weeks is always up (and definitely not down) then please use this information to obtain a memory dump of the running Application Pool process (use the
PID) and then please send us that dump.
We are happy to analyze it here.

Please know that if the PID memory usage trend is *not* upwards then
analyzing a dump would not be useful.
The process would need to be in a clear state of "heading towards
OutOfMemory" so that the problem could be clearly picked out from the
dump. In fact the more "out of balance" the process is... the better it
would be for analysis purposes.

Another tool that could be used to gather data about a running Application Pool process (w3wp.exe) is the Microsoft Debug Diagnostic Tool v1.1. It can be used to both generate and analyze a dump of most any Windows process.

to the Web.config file of your .NET webapp, or to the Machine.config file.

NOTE:
BD (all configurations, not just .NET) never catches "Throwable"... even if your CFM pages contains a <cfcatch> whose
type = "any".
In that scenario, BD catches BD-defined Exceptions, and java.lang.RuntimeException.
That means that if the Exception or Error is some other one... such as a JVM-specific one (or a .NET framework-specific one), or one that's specific to certain operations such as an XML Parsing Exception, or perhaps one that's thrown by the "Container" such as the .NET Framework or Sun's JVM then cfcatch won't catch it.
The reason is because BD makes calls to the APIs provided by either .NET or the JVM, and those calls may throw errors/exceptions that don't relate to the CF world.
In that case, it's not caught by BD, it bubbles up to the "Container" inside which BD runs.
At that point it's out of BD's hands.
This is why you'd see a "generic" .NET error (or JVM error) in the first place... and also why you'd want to turn customErrors off in the .NET webapp... so that the .NET framework won't hide the true problem from you.

Faq ID

337

Product

BlueDragon

Category

Debugging, General Info

Question

My memory usage is running very high and escalating in BD JX. This is causing my performance to lag. What should I look for?

Answer

This could be caused by a very large number of cached queries. Your cache count may be at the max, which by default is 1000. In BlueDragon Admin Console-Application->Caching you will see a value for Queries in Cache. If this value is at its maximum, you should either edit your bluedragon.xml to increase this value, or you should consider whether your application needs debugging to reduce the number of queries you are caching. If you choose to increase the value of <cachecount>, simply add this element under the <cfquery> element and try changing the size to 2000.
<cachecount>2000</cachecount>
In BlueDragon 7.X versions, you can edit your cache size in BlueDragon Admin ->Application ->Caching. No manual edits to the bluedragon.xml are required for newer version of BlueDragon.

Faq ID

187

Product

BlueDragon, ServletExec

Category

Debugging

Question

What is DBMON and how do I use it ?

Answer

DBMON stands for Debug Monitor.
New Atlanta does not make DBMON.
DBMON is a debugging tool created by Microsoft which has been bundled with Windows installations of ServletExec. It captures and displays program output from programs that are written to do this.
Both ServletExec ISAPI and ServletExec NSAPI on Windows are written to do this, they will send any System.out.println() output to both DBMON and ServletExec.log.
If you are running SE AS (out-of-process version of SE) then you'll find that your System.out.println() output emitted by your Servlets and JSPs is not captured by DBMON. This is because DBMON is a native (non-Java) program, and it cannot capture output that comes from a java program.
Any output that you see in DBMON must have come from a native program.
The only time that you would ever get to see your System.out.println() output emitted by your Servlets and JSPs, captured in DBMON is if you were running a version of ServletExec which runs in-process with the web server (ISAPI or NSAPI), because then the SE Java code can make a native callback to tell the native webserver to output the message to DBMON.
DBMON is discussed in the "Developing Servlets" chapter of the ServletExec User Guide (for example, in the SE 4.2 User Guide this is section 12.4).
If you have program output in DBMON that you need to copy to your clipboard, here is how you do this:

In the upper-left corner of the DBMON window, left-click the C:\ icon once.

From the pulldown menu choose Edit - Mark

Now highlight the DBMON output you wish to put on your clipboard

Hit Enter on your keyboard to place the text on your clipboard

Paste the captured output to an email or text file or wherever you wish.

Note that DBMON will not show you anything if you are accessing the machine remotely via terminal services or possibly other remote access software.
This is a limitation of DBMON.
In this case you would need to examine ServletExec.log to see the messages.
ServletExec.log has the added benefit of timestamps for each entry, DBMON output does not provide timestamps.

Another debugging tool which works similar to DBMON but also works when run remotely is DebugView.
DebugView is freely downloadable from:
www.sysinternals.com

If the above link does not lead you to the DebugView download page, then please be aware that Microsoft appears to be the new owner of DebugView. You might find it here.

Note that in our testing with remote use of DebugView we found that we had to enable Global Win32 from the capture menu in order to see any generated output remotely... and we found that we had to do that twice before that setting would actually "stick".

Faq ID

308

Product

BlueDragon

Category

Debugging, Exceptions

Question

When I run a .NET page, I get a .NET "Configuration Error" stating that "It is an error to use a section registered as allowDefinition='MachineToApplication' beyond application level." What's up with that?

Answer

This error generally indicates that you've got code in a directory that's not been defined to .NET (by way of IIS) to be an "application". Some xml directives in the .NET web.config file cannot be run in a simple directory, and can only be executed in an "application" root (whether a web site root, a virtual directory root, or an application declared in IIS to be an "application").

To solve this problem, declare the directory to be an application. This notion of declaring a directory is discussed further in the manual, Deploying CFML on ASP.NET.

Faq ID

373

Product

BlueDragon, JTurbo, ServletExec

Category

Debugging, General Info, Installation

Question

Where are the Interest List Archives for ServletExec, JTurbo, and/or BlueDragon?

Answer

It is no longer possible to post new messages to the Interest List Archives for any of New Atlanta's products as they have been replaced with the New Atlanta Product Forums. However, it is is still possible to search the Interest List archives for answers to previously asked questions using the links below:

Each of the Interest List archives represent years of details technical information and are an extremely valuable tool in solving various issues that you may encounter.

Exceptions

Faq ID

326

Product

BlueDragon

Category

Exceptions, General Info, Installation

Question

I get NoClassDef and other errors trying to process images on BlueDragon Server or Server JX on Linux systems. What's wrong?

Answer

The problem generally is related to running the Linux system in "headless" mode. See the BlueDragon Server and Server JX Installation Guide, and the section "Graphics Rendering Operations on a Headless Linux System" for more information and a possible solution.

Faq ID

272

Product

BlueDragon

Category

Exceptions, Supported Features, System Requirements

Question

I'm having problems using CFMAIL in the BlueDragon/J2EE edition on some servers, such as Tomcat 5. What does "NoClassDefFoundError" mean?

Answer

If you attempt to use CFMAIL when deployed on Tomcat 5 (and Jetty, it seems), it will fail with a NoClassDefFoundError. The problem is that Tomcat 5 simply doesn't include the necessary javamail (and "beans activation framework") libraries that CFMAIL relies on.

You can obtain these libraries (jars) from http://java.sun.com/products/javamail/, then move the needed mail.jar and activation.jar files into the the WEB-INF/lib directory a your web application (and restart your web application). If you want to solve the problem for all web applications, you need to move it to the appropriate place for the J2EE server/servlet engine you are using.

For Tomcat 5, you can place it into either the $CATALINA_BASE/shared/lib or the jre/lib/ext folder of the JDK location being used by Tomcat (or other J2EE servers).

(Appendix I of the "Deploying CFML on J2EE Servers" manual in the 6.2 documentation set incorrectly states that the mail.jar and activation.jar can be found in the WEB-INF/opt directory of the BlueDragon web app. That is not true.)

Note that the value for maxAllowedContentLength is in bytes.
After you get past this error, you may then get a different http error: Maximum request length exceeded.
You should open web.config and add:
<httpRuntime maxRequestLength="80000" />
as described in BlueDragon FAQ 329. This value is in kilobytes.

Faq ID

345

Product

BlueDragon

Category

Exceptions, General Info

Question

When I try to use a cfchart tag in IIS, I can't get the image to display. How do I resolve this?

Answer

First, check your extension mappings in IIS and make sure that .cfchart is correctly mapped to \BlueDragon installation\bin\isapi\BlueDragon_Adapter.dll. Extensions are mapped in IIS Management\Web Site Properties\Home Directory tab\Configuration button.
Second, highlight .cfchart extension and choose the Edit button. Make sure to UNcheck the option 'Check that File Exists'.

BlueDragon is not working on my Windows 2003 machine. I get "The system cannot find the path specified" error. Would a previous installation of CFMX be a factor in this problem?

Answer

The CFMX installer creates a "WildCard Application Mapping" in IIS 6 (and even leaves it there after an uninstall of CFMX!).
This effectively blocks requests from ever being passed to BlueDragon.
IIS continues to pass requests over to a CFMX installation that's not there anymore (yuck!)
Solution:
Look in your IIS management and remove any wildcard application mappings to ColdFusion.

Here is one way to make that configuration change (with IIS 6 for example):

Right-click on "My Computer" and choose "manage"

In the lower-left corner, expand the "Services and Applications" node

Expand the "Internet Information Services" node

Right-click the "Web Sites" node and open it's Properties

Go to the "Home Directory" tab

Click the "Configuration..." button

At the bottom of that dialog, select and remove any Wildcard mappings.

With the wildcard in place, all requests are still being routed to CFMX "jrun_iis6_wildcard.dll".

Faq ID

292

Product

BlueDragon

Category

General Info

Question

Can I generate an Excel spreadsheet from BlueDragon?

Answer

Yes, it's long been possible to generate Microsoft Excel files from CFML. Excel has a feature that allows an HTML table to be turned into a spreadsheet, so it's simply a matter of using CFML to produce the desired table, then using CFCONTENT to indicate that you're generating a file that should be processed as a spreadsheet. The spreadsheet will open either embedded in the browser or by opening Excel, as determined by the configuration of the user's machine.

Following is an example. Simply copy and paste the CFML below into a CFML page on your server to test, then change to suit your own needs.

(There are more lines than you see in the window below. Use Ctrl-A or your mouse to select all the code, then use Ctrl-C or right-click and choose "copy" to copy it to your clipboard to paste into a CFML page to test on your own server.)

And if you're interested in doing the same thing but without need to name each column (just want to dump all the columns in the CFQUERY), use this code instead to replace the table-generating tags at the very bottom of the example above:

Faq ID

294

Product

BlueDragon

Category

General Info, Known Limitations and Workarounds

Question

Can I generate charts and graphs in BlueDragon?

Answer

Yes, this can be done using the CFCHART tag which was added to BlueDragon 7.0.

Faq ID

291

Product

BlueDragon

Category

General Info, Known Limitations and Workarounds

Question

Can I generate PDFs in BlueDragon?

Answer

Yes, it's possible right now to generate PDFs in BlueDragon, any number of ways. Some are commercial products, though with free trial editions. Others are free but require slightly more work, typically using CFOBJECT to call a Java library.

CF_PDF, a free custom tag which generates PDF. Sample code is included in the comments for the custom tag. Note that its FILE attribute requires a full path to the output file to create.

CFX_PDF, a commercial tag which, while currently protected using CFENCODE, will soon be available using BlueDragon approach to protecting code. Contact Charlie for more information.

FOP, a free Java library for generating PDFs among other things. The link provided is to a CFDJ article on integrating it with CFML. See the "feedback" link at the bottom of the article to find comments made by New Atlanta CTO, Charlie Arehart, on how to integrate that approach in BlueDragon.

iText, a free java library which can be used and called from within BlueDragon CFML pages using CFOBJECT

It may be useful to note, as well, that if you already have a PDF and want to fill it in using the FDF feature of PDF, you can do that from within CFML, as this tip explains (thanks Dale Smith for pointing that out).

Additional FAQs or docs may be developed to expand on the details of using one or more of these alternatives.

Additionally, see FAQ 289 for more information on adding CFMX 7's specific tags for supporting features like PDF generation. But as this FAQ explains, you don't need to wait for that if you need these features now.

Faq ID

311

Product

BlueDragon

Category

General Info, Supported Features

Question

Can I really bundle BlueDragon with my CFML application, to sell it as a solution, with BlueDragon costing me less than the list price?

Answer

Yes, indeed. We do permit you to distribute a CFML application bundled with any edition of BlueDragon for commercial deployment use. While you must obtain a redistribution license from us to this, the amazing thing is that you may not need to pay the full price for BD to do this.

Consider a ColdFusion developer who wants to somehow bundle their CFML app with ColdFusion: they'd traditionally expect to have to pay $1,299, per deployment. If you want to do 100 of these, for some product that you want to sell for $100, or even $1,000, the economics just won't work, because you have to add in the $1,299 for CF. (And if you wanted to deploy on a J2EE server, with CFMX the cost for the Enterprise edition that permits this is $5,999). Now, our pricing page shows that the list price of BlueDragon is already less than CF.

But if you want to bundle (or we call it redistribute) your CFML app using BlueDragon (any edition, from the standalone Server edition to the J2EE edition or even our .NET edition), you may not have to pay anywhere near the full retail price. of BlueDragon

Instead, the payment can be a royalty based on your product's sales price. The percentage is surprisingly low (but obviously if you have a $100 product, it means you won't be paying any more than $100 per license). That's not a typo. Now you're product no longer costs (your price + price of ColdFusion) but instead (your price + a percent of your price, for BD). Of course, if your product price is so high that even the percentage exceeds our list price, then you won't pay any more than the list price.

We figure you're helping sell BD into places we never would--and we restrict the use of BD in this arrangement so it's only to be used to run your app, not any other your customer might want to build.

The bottom line is that we want to help you succeed and build a business based on your CFML skills and applications, where you might previously never have even thought of it.

Protecting Your Code:
Note, as well, that you can protect your code so that your clients cannot look at your CFML source, and it's not just an encoding as the CFCRYPT/CFENCODE utility required. We call it "precompiling" code, and you can apply the protection to some or all of your CFML templates (in case you need to leave some of your code unprotected for the end-users to edit). You can learn more about this at a FAQ of ours,
Can you explain more about the possibility of encrypting and precompiling templates in BlueDragon. This is another way in which those packaging a CFML app can find entirely new markets, or can lower their price because they previously priced it high to protect against loss of their intellectual property.

Expiring Your Code as a Trial: Still another great opportunity for deploying your CFML as a bundled application is that BlueDragon offers something ColdFusion never has. Using the precompiled templates feature discussed above, you can now also set an expiration date for your code. Note that this is not an expiration of the BlueDragon engine, but just of your code. And again, you can expire some or all of your code, as needed.

Faq ID

325

Product

BlueDragon

Category

General Info, Installation

Question

Do I have to pay to evaluate BlueDragon? Does BlueDragon offer trial and free development editions?

Answer

All editions of BlueDragon are available for free evaluation, and for ongoing single-IP development use beyond that evaluation period. There are 4 editions, and this FAQ discusses each.

BlueDragon.NET

The BlueDragon.NET edition starts out as a 30 day trial (from the day of installation) and after 30 days will revert to a single-IP developer edition.

BlueDragon Server JX

The BlueDragon Server JX edition starts out as a 30 day trial (from the day of installation) and after 30 days will revert to a single-IP developer edition.

BlueDragon Server

The BlueDragon Server edition has no trial or developer edition, because it's free for production deployment, subject to licensing restrictions. See the BlueDragon License Agreement for details.

BlueDragon J2EE

The BlueDragon J2EE edition starts out as a single-IP developer edition (because there is no installer, so no means to create a trial license key). Instead, an email will be sent to the downloading user which will offer a 30-day trial license key.

Converting to a Fully Licensed Edition

Finally, note that all editions can be converted to a fully licensed edition simply by obtaining and implementing a valid production license key (using the BlueDragon Admin console). See FAQ 316 for information (and a warning) about updating the current trial/developer license key.

Does BlueDragon Charge for Use on Shared Testing and Development Servers?

Contact BlueDragon Sales to discuss options for testing and shared development servers.

Faq ID

293

Product

BlueDragon

Category

General Info, Version differences

Question

Does BlueDragon/.NET support .NET 2.0? How about SQL Server 2005?

Answer

While .NET 2.0 and SQL Server 2005 are still in beta, they are not supported formally in New Atlanta products. We've tested BD/.NET on .NET 2.0 and while some features work, there are known issues that make it unusable for production. We've not done any testing with SQL Server 2005 and BlueDragon.
When .NET 2.0 and SQL Server 2005 are released by Microsoft for production use (beyond the "Go Live" license option), we'll support them with BD/.NET. Until then, they're not formally supported.

Faq ID

289

Product

BlueDragon

Category

General Info, Version differences

Question

Does New Atlanta plan to support the features in CFMX 7 in BlueDragon?

Answer

Yes, New Atlanta is investigating features to be added for our BlueDragon 7 release, scheduled for later in 2006. Whether and when we implement specific ColdFusion ® MX 7 features will be determined by the reaction of the overall ColdFusion community to the new features and--most importantly--the feedback we get from BlueDragon customers and prospects.

It's worth noting that some features added in CFMX 7 (and 7.01) are things that BlueDragon has long had:

sourceless deployment (we've had it since BlueDragon 3.1, and we've added an expiration date enhancement in 6.2)

deployment on OS X in standalone mode (we've had that since 2003)

standard WAR file deployment, with no post-deployment wizard (since 2002)

Still, we realize people are looking for some of the things CFMX 7 has added which BlueDragon still has not.

Note that many of the features can be made available now on BlueDragon (and indeed ColdFusion MX 6) by way of calls to underlying Java libraries or tools that CFMX 7 merely wraps up into tags. This may permit some to enable the functionality on their own at least until we determine which we will add and when we will add them.

For instance, PDF generation in CFMX 7 is done using the iText java library and related tools, which can be called from within CFML using CFOBJECT. The reporting is done via JasperReports, also callable right now from CFML. (For those interested in Reporting solutions, see FAQ 322).

And the Flash forms feature leverages a subset of Flex (Macromedia's XML-based Flash generator) which has been embedded into CFMX 7. While we won't be embedding Flex into BlueDragon (the licensing costs would be prohibitive), most of the same kind of components can be generated using OpenLaszlo, another XML-based Flash generator that actually predates Flex. That can be used with BlueDragon right now, and we are investigating bundling Laszlo into BlueDragon in the future. Laszlo Release 3 adds still more powerful capabilities that we hope to leverage. See FAQ 290 for more information on integrating BlueDragon and Flash today.

Further, many may not really want *Flash* forms particularly, but just more effective user interfaces (grids, calendars, accordions, and such) without complicated programming and without reliance on Java (as CFFORM does prior to CFMX 7). Many of these interface controls are available in a variety of free and commercial packages, which can be easily integrated into CFML (and those using BlueDragon.NET can leverage ASP.NET's powerful forms features). Also, many of those leverage Ajax functionality, which can certainly integrate with CFML on BlueDragon. Look for more information to come from us on these possibilities. In particular, see this blog entry on a unique option available right now.

As for the Event Gateway, New Atlanta had started work on an equivalent feature and stopped when we heard CFMX 7 would add one. Like other feature, we want to wait and see what the community (and our customers) think of the various approaches Macromedia has followed in adding these features, so that we give our customers the best experience and the greatest value.

As for the application.cfc, that's something that can be simulated using the event handlers of the servlet API (on Servlets 2.3 compliant engines) or via the global.asax file on .NET.

If you wish to express an opinion for features you're interested, you can contact sales@newatlanta.com.

Faq ID

250

Product

BlueDragon

Category

General Info, Installation, System Requirements

Question

How can I determine whether service packs are installed on the .NET Framework?

How can I get the Macromedia Example applications to run with BlueDragon?

Answer

The Macromedia example CFML applications (which come with CF4, 5, and MX) can be used to demonstrate CFML running on BlueDragon. We do not provide these examples, but if you have installed ColdFusion 5 or MX on your machine, and you chose to install the example applications, they can be found at /cfdocs/exampleapps/index.cfm in your web site's document root.

If you do not already have a datasource defined for ExampleApps, create one and point to the database file as appropriate for your operating system. In the case of CF5 on Windows, the cfexamples.mdb can be found in C:\CFusion\database. For CFMX on Windows, it can be found in C:\CFusionMX\db.

The CF 5 examples will for the most part run unchanged.

On CFMX, the examples do require a change to one file to remove reference to the undocumented coldfusion.server.ServiceFactory class which BlueDragon does not support. See /cfdocs/exampleapps/global_vars.cfm, which is included from the exampleapps/application.cfm file. You can comment out all the CFSCRIPT lines following

request.app.dsn = "ExampleApps";

and then ensure just the following lines are not commented:

request.app.ucase = "ucase";
request.app.isAccess = true;

If you're not on Windows, then the values should be:

request.app.ucase = "ucase";
request.app.isAccess = false;

Other than that, most of the examples will run, which is a useful way to demonstrate standard CFML running on BlueDragon. Some of the examples do use tags or functions that are not supported. See the BlueDragon CFML Compatibility Guide for more information on unsupported CFML features.

Faq ID

329

Product

BlueDragon

Category

General Info, Known Limitations and Workarounds, Miscellaneous

Question

How can I upload a file to my .NET webapp (BD-enabled or not) that is larger than 4 Mb?

Answer

In .NET, there is a default limit on the size of any web request of about 4 Mb. This is defined in the Machine.config file. If you need to accomodate larger requests, you can override the setting in your website's own Web.config file by putting this tag inside the "system.web" section, like this (for example):

<configuration>
<system.web>
<httpRuntime maxRequestLength="80000" />
</system.web>
</configuration>
Note, that the number is in Kilobytes, so 80,000 represents 80 Mb.

Faq ID

262

Product

BlueDragon

Category

General Info

Question

How do I enable clustering in BlueDragon .NET ?

Answer

In order for Session scope variables to be shared across the cluster, two things need to be done:

1. ASP.NET needs to be configured to use State Server or SQL Server sessions.
2. BD.NET needs to be configured to use ASP.NET sessions.

Faq ID

398

Product

BlueDragon

Category

General Info, Security

Question

In IIS7, my application pool is running under ApplicationPoolIdentity. How can I give this user file permissions when it doesn't show up as a User?

Answer

You can add the app pool identy from a command prompt like this:
icacls c:\inetpub\wwwroot /grant "IIS APPPOOL\DefaultAppPool":(OI)(CI)(RX)
Then, you can edit the security permissions through Windows Explorer.

Faq ID

305

Product

BlueDragon

Category

General Info, System Requirements, Web Server Support

Question

In the .NET edition of BlueDragon, I find that while I can run my CFML pages, when I try to access the BlueDragon Admin console I get 404 "file not found" errors. What gives?

Answer

The problem here occurs if you manually configure the IIS mapping page to set the file extensions (like CFM and CFC). There is an option there, called "check that file exists", which is enabled by default when you add a new mapping. You must turn that feature off. The BlueDragon admin console pages do not really exist (as explained in the documentation), so enabling this option causes the 404 error.

Faq ID

300

Product

BlueDragon

Category

General Info, Installation, Known Limitations and Workarounds, Product Requirements

Question

Is BlueDragon supported on CentOS?

Answer

Yes, although CentOS is not fully supported. We don't test
on CentOS but understand that it is directly derived from RedHat
Enterprise Linux, which we do support. This choice of platforms may result in some problems which we cannot predict nor possibly resolve.

Faq ID

369

Product

BlueDragon

Category

General Info, Known Limitations and Workarounds

Question

Is it true that Microsoft is retiring its Visual J# product? If there are no future development plans for Visual J#, how will this effect BlueDragon .NET?

Answer

Microsoft is supporting Visual J# through 2017, as stated on their web site:

http://msdn.microsoft.com/en-us/vjsharp/default.aspx

Visual J# and BlueDragon.NET are fully supported on 32-bit and 64-bit editions of Windows Vista and Windows Server 2008 (BlueDragon.NET was one of the first software products to receive Windows Server 2008 logo certification).

Our plans are to re-engineer BlueDragon.NET to remove the requirement for Visual J# prior to the release of the successor to Windows Server 2008.

Faq ID

358

Product

BlueDragon

Category

General Info

Question

The application pool that BD.NET runs under is configured to shutdown under certain conditions. On low traffic sites this causes things like scheduled tasks to not run until the site receives another request. Is there a way around this problem?

Answer

The best solution is to configure the application pool to not shutdown under certain conditions. This is done by right-clicking on the application pool and selecting properties. On the Recycling tab, uncheck the first three check boxes. On the Performance tab, uncheck the Idle timeout check box.

You can also place the following code in the Application_End() method of global.asax so when BD.NET is shutdown it will immediately be brought back up:

Note that the above change will only help with application pool recycles. If the machine is restarted then the site won't come back up until it receives a request. The workaround for this is to create a Windows scheduled task that runs at start up time and sends a request to the site.

Faq ID

297

Product

BlueDragon

Category

General Info

Question

Why can't I get my cfml pages to be served from a shared network drive? I keep getting File Not Found.

Answer

The "File not found" reported by BlueDragon Server is due to its inability to access the CFML templates on the remote share that is configured as the IIS home directory. Just as IIS had to be configured with credentials (an account and password) to access this remote share, so must BlueDragon Server. By default, the BlueDragon Server service is installed to run using the "Local System" account. This account must be changed to one who is authorized to access the remote files using the "Log On" tab of the service's properties. Setting it to the same account as used within IIS is recommended.

Faq ID

377

Product

BlueDragon

Category

General Info, Security

Question

With BD.NET, can the CFLDAP tag be used with SSL?

Answer

The CFLDAP tag can be used with SSL using the following steps:

In the CFLDAP tag, set the port attribute to the value of the LDAP server's SSL port. The default port for SSL with LDAP is 636.

In the CFLDAP tag, set the secure attribute to CFSSL_BASIC.

Install the LDAP server's certificate into your computer's certificate store. This is described at http://technet.microsoft.com/en-us/library/cc725849.aspx.

If you don't install the LDAP server's certificate in your computer's certificate store then you'll receive the following General Runtime Error:

In the CFLDAP tag, set the port attribute to the value of the LDAP server's SSL port. The default port for SSL with LDAP is 636.

In the CFLDAP tag, set the secure attribute to CFSSL_BASIC.

Install the LDAP server's certificate in the database of trusted certificates for the JRE being used by BD JX or BD JEE. This is done from the command line using the following steps:

cd JAVA_HOME/lib/security

if JAVA_HOME/lib/security contains a jssecacerts file then enter the following command. If you are prompted for a keystore password and you don't know what it is then most likely it is still set to the default password 'changeit'.

keytool -import -file ldap_server_cert.cer -keystore jssecacerts

if JAVA_HOME/lib/security doesn't contain a jssecacerts file then enter the following command. If you are prompted for a keystore password and you don't know what it is then most likely it is still set to the default password 'changeit'.

keytool -import -file ldap_server_cert.cer -keystore cacerts

Restart either the BD JX service or the application server that BD JEE is running behind so that BD will pick up the changes made to the database of trusted certificates.

For example, if BD J2EE is running with JDK 1.6 on Windows then the value of JAVA_HOME for the JRE would be: C:\Program Files\Java\jdk1.6.0\jre.

If you don't install the LDAP server's certificate in your JRE's database of trusted certificates then you'll receive the following General Runtime Error:

Why do I get the error, "BlueDragonRunTimeEngine License Manager : This product is not licensed for this request"?

Answer

This error means you're running BlueDragon in developer mode and trying to trying to access a CFML page from other than the machine on which it's installed (or at least, BlueDragon thinks that's the case, more on that in a moment).

BlueDragon is available as a developer edition, which allows you to test it without expiration, but it's limited to accept requests only from the server on which it's installed. (You can request a license key for a 30-day trial that removes that limit, or you can purchase a license. In either case, you can place the license key into the appropriate place offered in the BlueDragon Admin console or BlueDragon.xml file.)

So if you're trying to browse CFML pages and your request is coming from other than the server on which BlueDragon is installed, you can:

browse the pages from the server on which it's installed

use terminal services or SSH, etc., to connect to the server on which it's installed and browse pages from there

or install a trial or production license key

Finally, note that the problem may also be you ARE trying to run it from the server on which it's installed but in your URL you're using something other than 127.0.0.1 or localhost. For instance, if your machine is called "test", you may find that using that in the domain name still fails. Try changing to use either localhost of 127.0.0.1.

Installation

Faq ID

280

Product

BlueDragon, JTurbo, ServletExec

Category

Installation

Question

An InstallAnywhere-based installer (or other program) won't run on my Windows machine. Why?

Answer

First, you should read FAQ #238 to see if it applies in your case. That FAQ was written with JTurbo in mind, however it may very well apply to any InstallAnwhere-based installer running on Windows 2003, so if that's your case you should try that FAQ first (even if you're not using JTurbo).
If it does NOT apply, or it DOES apply but does not cure the problem, then the problem may be due to an operating system feature that's new in Windows 2003 SP1 & Windows XP SP2. That feature is called
Data Execution Prevention (DEP). It serves to prevent viruses and
other malicious code from ever executing.
Programs that Windows deems to be malicious are stopped cold, and not allowed to run at all.
It's possible to configure DEP so that it excludes certain programs, leaving them
alone to do as they wish. To populate the list of applications that DEP will
allow to execute, navigate to:
My Computer / Properties / Advanced / Performance Options
That's where you should add the program(s) you wish DEP to leave alone.
If the program that you add to that list is an installer, then after you successfully
install you may want to consider adding that program's uninstaller to the list also.
That way its uninstaller will be allowed to execute should you or someone else ever need to
uninstall the product.

Here is a more detailed description of how to find the DEP settings plus more information about them:

Open the System Properties dialog:

For a Win XP sp2 machine, one way to bring up this dialog is to go to My Computer and click "View System Information".

For a Win 2003 sp1 machine, one way to bring up this dialog is to go to the Control Panel, and choose System.

Once there, go to the Advanced tab. Click the
button labled "Settings" in the category/group labeled "Performance".
This brings up the "Performance Options" dialog. Go to the "Data Execution Prevention" tab
of that dialog. There are two options for DEP:

Turn on DEP for essential Windows programs and services only

Turn on DEP for all programs and services except those I select

In our experience, having the 1st option selected alleviates all
DEP-related problems from occuring on the machine.
The Win XP Professional Help dialog had this to say about DEP:

Data Execution Prevention (DEP) helps prevent damage from viruses and other security threats that attack by running (executing) malicious code from memory locations that only Windows and other programs should use. This type of threat causes damage by taking over one or more memory locations in use by a program. Then it spreads and harms other programs, files, and even your e-mail contacts.
Unlike a firewall or antivirus program, DEP does not help prevent harmful programs from being installed on your computer. Instead, it monitors your programs to determine if they use system memory safely. To do this, DEP software works alone or with compatible microprocessors to mark some memory locations as "non-executable". If a program tries to run code?malicious or not?from a protected location, DEP closes the program and notifies you.
DEP can take advantage of software and hardware support. To use DEP, your computer must be running Microsoft Windows XP Service Pack 2 (SP2) or later, or Windows Server 2003 Service Pack 1 or later. DEP software alone helps protect against certain types of malicious code attacks but to take full advantage of the protection that DEP can offer, your processor must support "execution protection". This is a hardware-based technology designed to mark memory locations as non-executable.
By default, DEP is only turned on for essential Windows operating system programs and services. To help protect more programs with DEP, select Turn on DEP for all programs and services except those I select.

If none of this helps you then you may find the following information to apply in your case:

Some possible workarounds or ways to try to solve this problem include:

Run the installer on another machine and then copy the installed folders to the target machine. Since JTurbo is really just a set of JARs (often only 1 JAR is needed/used by people... JTurbo.jar) and a set of examples and documenation... this is fine to do.

OR

Try running the installer on the problem machine but either:

uninstall the JVM there first and maybe reinstall a different JVM version before trying to run the installer

OR

try running the installer from the command line as described in section 1.3.1 of the JT 2005 Installation Guide (this involves holding down the control key)
Or perhaps do so by typing the name of the installer on the command line (not double-clicking) and passing the "-i console" option or maybe even the
LAX_DEBUG=true option or maybe even the LAX_VM option as Macrovision describes on their webpage

Faq ID

240

Product

BlueDragon

Category

Installation, Supported Features

Question

Does BlueDragon run on or at least support integration with iSeries systems (formerly known as AS/400's)?

Answer

BlueDragon can both run on and/or integrate with iSeries systems.

First, as far as running CFML on iSeries, you can do that with our J2EE edition. (You can also integrate CFML with iSeries resources using our other editions of BlueDragon, Server and Server JX, as will be discussed later). The J2EE edition runs on any J2EE server or servlet engine. IBM's own WebSphere runs on the iSeries platform (see http://www-1.ibm.com/servers/eserver/iseries/software/websphere/wsappserver/), and there may be other servlet engines/J2EE servers that run on it as well.

Deploying CFML on J2EE is very easy with BlueDragon. Our documentation on the subject, "Deploying CFML on J2EE Application Servers" is available on our web site in the docs page of our self-help area. Also, our CTO, Charlie Arehart, did an article in the April 2004 ColdFusion Developers Journal called, "Making the Case for CFML on J2EE". It's available on the CFDJ site at http://www.sys-con.com/story/?storyid=44481&DE=1.

There is also the possibility to integrate from CFML to iSeries data, applications, and components.

First, as may be obvious, you can connect to databases on iSeries using ODBC or JDBC. This (and connecting to applications) is covered in the Dec 2003 CFDJ article, "MX to iSeries Demystified", available at http://www.sys-con.com/story/?storyid=42109&DE=1. While the author (and the title) suggest it's somehow CFMX-specific, it is not.

As he notes, to connect via ODBC you need the "Client Access for iSeries" tool which is a licensed program from IBM. But you can use it, and he shows how to set up datasources in ODBC and JDBC to connect using that. This would work in BlueDragon as well.

But he also points out the available JTOpen open source driver from IBM, and if you dig into that, you'll learn (at http://www-1.ibm.com/servers/eserver/iseries/toolbox/overview.htm#how) that it can link to more than just databases but also the file system, programs, commands, data queues, printers, jobs, messages, and lots more. The CFDJ article explains how to get and use the tool, and the steps are pretty much the same in BlueDragon.

Still another couple of ways that he doesn't mention are possible, and they're generic to CFML (whether running on BD or CF): you can call Enterprise JavaBeans (running on any J2EE server) using CFOBJECT. Also, you can call a web service on any server using CFINVOKE (and CFOBJECT). These are two generic ways CFML can call any enterprise object on another platform, and they're a powerful possibility for greater enterprise integration. These latter two approaches don't require that you necessarily be running the CFML on the same server as the iSeries.

So as you can see, beyond just running the CFML on iSeries, you may also open tremendous doors of possibility for integrating your CFML with iSeries. We're happy to help you as you explore these possibilities.

Faq ID

196

Product

BlueDragon

Category

Installation, Web Server Support

Question

Does BlueDragon support Apache 2?

Answer

BlueDragon 6.1 and above supports Apache 2. See the system requirements page for more information on hardware/software support.

You may experience some challenges with different point releases of Apache 2, depending on the edition and point release of BlueDragon you're running. For information on known challenges integrating with Apache 2, please search for other FAQ entries referring to "Apache".

Faq ID

339

Product

BlueDragon

Category

Installation, System Requirements, VM Support

Question

How can I install BlueDragon Server or JX onto a MacOS X system that has Java 1.5 installed as the default version?

Answer

Newer shipments of Apple Mac hardware include both Java 1.4 and 1.5 (Java 5), AND have configured the Java 5 version as the default. Since BlueDragon versions prior to 7.0 do not run on Java 5, the installation will fail. To work around this problem, the default Java version must be changed to Java 1.4. There are two methods to accomplish this, both will preserve the Java installations (ie they will not be uninstalled). You need only use one of these procedures to
have your system use Java 1.4.2 as its default Java installation.

Change the Java version via the Runtime Settings:

Open a new finder window in OS X. Navigate to the following location:
"Applications > Utilities > Java > J2SE 5.0"

Open the "Java Preferences" application.

Click the drop down lost beside "Use Version" and select "1.4.2".

Under the "Java Application Runtime Settings" click and hold the "J2SE 1.4.2" listing and drag it to the top of the list, above "J2SE 5.0".

Quit the "Java Preferences" application.

Restart/reboot the system.

Change the symbolic links used to select the default Java version:

Open a new finder window in OS X. Navigate to the following location: "Applications > Utilities"

Open a "Terminal" application.

Enter: 'su root'

Enter the 'root' password

Enter: 'cd /System/Library/Frameworks/JavaVM.framework/Versions'

Enter: 'ls -lsa'

The above command should display the following amongst the contents of the directory: "CurrentJDK -> 1.5.0"

Enter: 'ln -shf 1.4.2 CurrentJDK'

Verify the change by entering: 'ls -lsa'

The following should now be listed: "CurrentJDK -> 1.4.2"

Faq ID

385

Product

BlueDragon

Category

Installation

Question

How do I get the BDJX Linux installer to run on a non Graphical Linux System?

Answer

A non-graphical Linux system is one that lacks an X11 display (or whose DISPLAY variable is not set).
Such a system is sometimes called "Headless" and graphical operations (GUI) will fail on it.
The default installation mode for a BDJX Linux installer is GUI, so running that installer on a
Headless system will give the following sort of error:

java.awt.HeadlessException:
No X11 DISPLAY variable was set, but this program performed an operation which requires it.
at java.awt.GraphicsEnvironment.checkHeadless ...
...
...

The recommended way to get past this issue is to run the installer in console mode. For example:
> BlueDragon_Server_JX_71_383_Linux_x64.sh -i console

For those who would prefer the installer to default to GUI mode on systems where that's possible (already the case), but to also default to console mode on systems where GUI is *not* possible... here is an unsupported way around it:
Run the following script to create a modified copy of the installer:

#!/bin/sh
# This script may be used to alter a BDJX 7.1 Linux installer (built with InstallAnywere 2008 Emterprise)
# so that it will run in console mode by default on a "Headless" Linux system (one with no X11).
# This article
# http://www.mooreds.com/wordpress/archives/000280
# says to search an install script generated by InstallAnywhere (IA) for the word "FAILSAFE"
# comments there explain that "console mode by default on a headless system" is possible simply by
# uncommenting/commenting a few specific lines in the script that is generated by IA.
InstallerName=BlueDragon_Server_JX_71_380_Linux_x64
sed '
/^# FAILSAFE/ {
:unquote
n
/# comment/ b next
s/^#//
t unquote
}
/^# comment/ {
:next
s/^# comment/### comment/
:requote
n
/fi/ b
s/^/###/
b requote
}
:end
' $InstallerName.sh > $InstallerName.sh.mod

Thanks to Benoit Plessis for providing the script above.
Also thanks to Dan Moore for his blog post which pointed the way to this solution.

Note that AWS which corresponds to Apache 1.3.x is not supported by BDJX 7.1.
Also, BD_Instance & BD_User are not needed by BDJX 7.1.
They can be there or not, it makes no difference.

Then simply invoke the installer as usual. It will detect the installer.properties file there and use it to perform a silent installation.

Faq ID

295

Product

BlueDragon

Category

Installation

Question

I'm trying to apply the Hotfix for BlueDragon/.NET, but when I try to drag and drop the dlls, they won't copy. What gives?

Answer

In FAQ 287, we explain when and why to apply the hotfixes. The readme.txt for each hotfix zip (downloadable from the web site) explains how to apply the fixes, and one for the .NET edition explains that for some types of installations you must drag and drop the updated DLLs to the "global assembly cache" (or GAC) located at windows\aseembly directory (and that you can't copy and paste them).

But the hotfixes are in a zip file, and while Windows may permit you to open that zip file to view it as if it is a regular directory, you'll find that when you try to drag the files out of the "directory", it won't work.

The problem is simply that you must first extract the zip file (or copy/paste the files to a regular directory first), and then drag/drop the files from there to the GAC (windows\assembly directory). Don't forget to restart IIS afterward.

Faq ID

340

Product

BlueDragon

Category

Installation

Question

I'm trying to install BlueDragon .NET on a brand new machine and the installer fails when I double click on it.

Answer

Look in C:\Documents and Settings\username\WINDOWS and see if you have a folder named Fonts inside WINDOWS. InstallShield will fail without it. Add the folder (empty) and run the installer.

Faq ID

248

Product

BlueDragon

Category

Installation

Question

I've installed BlueDragon.NET but it doesn't work properly. How can I verify it was installed properly?

Answer

Perform the following steps to verify BlueDragon.NET was installed properly:

For a single virtual directory install, verify the following DLLs were placed in the <installation directory>\bin directory: BlueDragon.dll, BlueDragon.Controls.dll, BlueDragon.Utils.dll and CFX.NET.dll. For all other installs, verify these DLLs were installed to the Global Assembly Cache (GAC). The GAC is located at <Windows directory>\assembly.

For a single virtual directory install, verify a web.config file exists in the <installation directory> directory. This file must contain the following elements (NOTE: To make this FAQ easier to read, some attribute values are shown on multiple lines. When manually entering these elements, the attribute values must be placed on a single line.):

For all other installs, verify machine.config, which is lcoated at <Windows directory>\Microsoft.NET\Framework\<version>\CONFIG, contains the following elements (NOTE: To make this FAQ easier to read, some attribute values are shown on multiple lines. When manually entering these elements, the attribute values must be placed on a single line.):

If web.config or machine.config doesn't contain the proper elements then check <installation directory>\BlueDragonInstaller.log for error messages.

For a single virtual directory install, verify a virtual directory was created in IIS that maps to the <installation directory>.

For the web site or virtual directory you are having problems with, verify it is configured with extension mappings for .cfm, .cfml and .cfc that map to the aspnet_isapi.dll for the version of the .NET Framework you are using. These extension mappings must not have the setting "Check that file exists" enabled.

Faq ID

365

Product

BlueDragon

Category

Installation

Question

If I run a BlueDragon installer and I already have an older version of BlueDragon installed, will I be upgraded without having to uninstall my current BlueDragon?

Answer

That depends on whether you are running BlueDragon .NET or BlueDragon JX. BlueDragon .NET will upgrade without having to uninstall. BlueDragon JX requires that you uninstall your current version before upgrading. Your current configuration setting will be saved in \BlueDragon_Server_JX\bluedragon.xml.save.

Faq ID

219

Product

BlueDragon

Category

Installation, Supported Features

Question

Is the BlueDragon Server edition really free for production deployment?

Essentially, you may use BlueDragon server for production without paying any licensing fee, but if you're interested in bundling BlueDragon with your application or redistributing it any way, or hosting with it, or using it for commercial services in an Application Service Provider (ASP) environment, you must establish a separate licensing agreement. We are very interested in working with customers interested in using BlueDragon in any of those approaches and will work to arrange an agreement that works for your business model. We offer special low-cost bundling pricing and hosting licensing. Contact sales@newatlanta.com to discuss this further.

On OS X, if I manually uninstall BlueDragon, I find I can't reinstall it (says it's already installed and quits)

Answer

There is a hidden file you must also delete. In /usr/local/NewAtlanta, execute the command:

ls -la

If you see a .registry file, delete that and rerun the installer.

Faq ID

383

Product

BlueDragon

Category

Installation, Web Server Support

Question

What can you tell me about how IIS manages its Extension mappings?

Answer

BlueDragon Server JX "hooks into" IIS via Extension Mappings.
For example *.cfm is mapped to C:\BlueDragon_Server_JX_71\bin\isapi\BlueDragon_Adapter.dll
By default, the BDJX installer adds these mappings at the Global level of IIS where they are typcially inherited by all
websites. However it is entirely possible to add these mappings (or any other mappings you wish... even mappings that have
nothing to do with BlueDragon) to the level of a specific website instead of Globally.
Our testing here has revealed an interesting quirk about IIS and how it manages Extension mappings (Script maps) defined within it.
Our testing here has shown that once any change is made to the Extension map at the level of a specific website (adding or removing
any mapping) that the inheritance of global mappings becomes broken for that specific website.
In other words, that website will cease to inherit newly added global mappings.
Here is an example you can try yourself to help drive this point home:

Create a brand new website and take note of its extension map.
Specifically take note of the fact that it inherits all the mappings
that exist in the global map.

Add a new extension mapping at the global level, and then view/refresh the
map at the website level again to confirm that it has inherited that newly added
global mapping.

Make a change to the map at the website level by either adding or
removing a mapping.

Repeat #2 above using some new extension value

View/refresh the map at the website level again to see that it has not
inherited that new global mapping.

Summary:
Once you add or remove any Extension mappings at the level
of a specific website then the Extension map for that site is no longer
inherited from the global map.
Instead that specific site receives its own "copy" of the global
mappings. But from that point forward, the 2 "copies" (the global copy
and the website copy) may very well diverge (broken inheritance).
If you later add a global mapping which does not seem to take effect on requests to that website, then this is why.
In that scenario you must also add that mapping to the website level.

Faq ID

232

Product

BlueDragon

Category

Installation, Known Limitations and Workarounds, Web Application

Question

What do I need to add to run BlueDragon/J2EE on Websphere 4?

Answer

In order to deploy the BlueDragon 6.1 webapp on WebSphere 4.0 you must make two changes (which are not required on WebSphere 5):

In the "WEB-INF/web.xml" file, change the DOCTYPE declaration from this:

This change must be made because WebSphere 4.0 implements the Servlet API 2.2, while all other major J2EE servers (including WebSphere 5.1) implement the newer Servlet API 2.3.

Copy the "crimson.jar" and "jaxp.jar" files from the "WEB-INF/opt" directory to the "WEB-INF/lib" directory. See the README within the "WEB-INF/opt" direcotory for more information.

Faq ID

310

Product

BlueDragon

Category

Installation, Web Application

Question

What is CFEverywhere, and what has it to do with BlueDragon?

Answer

Many CFML developers have longed to create a means for users to be able to download their CFML application, such as on a CD, and click and run it--without need to install a CF server, database engine, web server, etc. CFEverywhere is one attempt to solve that problem, using BlueDragon.

In a series of 2005 ColdFusion Developers Journal articles, authors Phil Cruz and Dick Applebaum coined the term and described the packaging of components needed to bring this dream to reality. They chose to use BlueDragon (and indeed its J2EE edition deployed on the free Jetty servlet engine) as well as the free Derby database. You're free to consider other components.

They explain their choices and the respective benefits in Part 1, where they further describe the ease of implementation of Jetty (don't worry if you're not a J2EE developer) and BlueDragon/J2EE (also very easy on any J2EE server). In Part 2, they explain the use of Derby, and Part 3 expains the final piece of the puzzle, packaging the parts to create a CD installer. All in all, an awesome suite of tools to create a great solution to a common problem. Good going, guys.

One thing the article series doesn't explain is the amazing pricing model we offer for redistributing or bundling BlueDragon with your application. See our FAQ about this.

Finally, Phil has his own area devoted to the topic, http://philcruz.com/cfeverywhere/, where he offers more information and answers to frequent questions. He makes the point that CFeverywhere enables:

Make fully functional demo/trial applications

Make programs that require no installation

Includes a CFML runtime and a database

Utilize the full power of CFML

Create online/offline applications

Faq ID

368

Product

BlueDragon

Category

Installation

Question

When I run my BlueDragon.NET installer on my 32-bit machine, it thinks it's a 64-bit machine. What can I do to make sure the correct dlls are installed on my server?

Answer

The reason this problem occurs is because the BlueDragon installer looks in the Windows registry in order to decide if the OS is 32-bit or 64-bit. It looks for the presence of this Registry key:
HKEY_LOCAL_MACHINE\Software\Wow6432Node\

It appears that that key is present even on a 32-bit OS when the SQL Server Reporting Services are installed. So the installer then installs 64-bit DLLs which is incorrect.

The solution is:
Look in your registry and see if you have the following registry key:
1) HKEY_LOCAL_MACHINE\software\Wow6432Node

If you do, you will need to:
2) rename this registry node to Wow6432Node.save
3) uninstall BlueDragon.NET.
4) Rerun the BlueDragon.Net installer and your 32-bit standard license key should then work.
5) Name the registry node back to Wow6432Node.

This was a problem that has been fixed as of the September 2004 hotfix. If you have downloaded 6.1 from the web site, even since then, you need to apply the hotfixes. The latest ones are always available at:

The README.txt file in each Hotfix package explains the specific installation procedure for that associated BlueDragon version and platform. A ReleaseNotes.txt file is included that describes all of the fixes implemented by the hotfix.

Finally, BlueDragon 6.2 includes this hotfix, of course.

Known Limitations and Workarounds

Faq ID

328

Product

BlueDragon

Category

Known Limitations and Workarounds, Session Tracking

Question

Does BlueDragon have or plan to have support for Application.CFC, introduced in CFMX 7?

Answer

BlueDragon 6.2.1 and before do not have the application.cfc. It is on the list of things planned for BD 7.

In the meantime, it's worth noting that there may be a work-around in the meantime. Both J2EE and .NET offer similar built-in event handling. Macromedia made it easier by way of a CFC, but until then, please note the following resources for whichever platform you run on (J2EE or .NET) to find out more.

BlueDragon on Java/J2EE

On the J2EE platform, session and application listeners (event handlers) were introduced in the Servlets 2.3 spec in 2001, and are discussed in such places as:

Unfortunately, the version of ServletExec that underlies BueDragon Server and Server JX editions is implemented in such a way that you can't leverage that functionality. But if one deploys BD on a J2EE server or Servlet Engine, you can indeed take advantage of it (by writing the Java code mentioned in the articles). All the servlet engines for the past couple years (including ServletExec since 4.1) have supported servlets 2.3. I know this isn't as easy as using the application.cfc, and is of no value for BD Server users, but it's there.

BlueDragon on Microsoft.NET

In the case of BD.NET, again, the .NET framework supports such session and application event handling also. In fact, their approach is much closer to what one may see in the application.cfc model. It's done in the global.asax template, and it has predefined methods that you can implement to handle session start, end, application start, end, etc. Some resources on that are:

Again, you need to write pure asp.net code (VB, C#, J#, etc.) , but it's pretty easy to find lots of example like those above to do most of what one would want.

Faq ID

381

Product

BlueDragon

Category

Known Limitations and Workarounds, Miscellaneous

Question

How can I limit the number of Runtime Error logs that are created and stored in \work\temp\rtelogs folder?

Answer

In bluedragon.xml, under the <system> element, add (example):
<runtimeloggingmax>50</runtimeloggingmax>
Then restart BlueDragon.
If runtimeloggingmax is not present, then BlueDragon defaults to 100. Once the max is reached, the old bderrorXX.html logs are replaced by more current error logs.
This feataure was added in BlueDragon 7.1 final release.

Faq ID

269

Product

BlueDragon

Category

Known Limitations and Workarounds, Miscellaneous

Question

I have installed Windows Media Admin and now I can't get BlueDragon to start. What is wrong?

Answer

Windows Media Admin runs on the same default port 8080 that BlueDragon defaults to. You need to change the port value in BlueDragon.

Faq ID

207

Product

BlueDragon

Category

Known Limitations and Workarounds, Supported Features

Question

I'm having problems using CFMAIL. What's going wrong?

Answer

First, keep in mind that BlueDragon spools mail to a work/cfmail/spool directory in the [BlueDragon-install] directory for Server and Server JX, or in the WEB-INF of a deployed web application in BlueDragon for J2EE. The work directory for the .NET edition will depend on your installation choice, so see the manual, "Deploying CFML on ASP.NET Servers" for more information.

The work/cfmail directory also holds a mail.log which reports information about the mailing process (starting the mailserver process) as well as failures to send email.

As in CF, all undeliverable messages are filed away for your review. In BlueDragon, they're held in the work/cfmail/undelivered folder (each with a filename comprised of a long string of characters and numbers and an extension of .email.)

A common failure would be if the SMTP server used for the CFMAIL could not be reached. That will be logged for each failed message. As for the SMTP server, you can either specify a mail server in the SERVER attribute of CFMAIL or BlueDragon will default to that specified in the BlueDragon Administrator.

If the mail server was just down at the time of the emailing, you could copy the files from the undelivered to the spool directory to have BlueDragon attempt to send them again.

Yet another common problem is if the mail server requires a username and password. This too will cause delivery failures which will be logged for each failed message (though it may report a timeout rather than a specific authentication failure). You can provide this on the CFMAIL tag or in the admin console. Note that you specify it in the admin console by prefacing the name of the mail server (or IP address) with username:password@ (as in, for instance, myname:mypw@myserver.com).

Finally, another common problem is that some mail servers fail to accept mail if the FROM address is different than the domain of the mail server sending the message (called "open relay"). Again, view the cfmail log file to determine if this is a problem.

Faq ID

323

Product

BlueDragon

Category

Known Limitations and Workarounds, Supported Features

Question

I've noticed that BlueDragon does not bundle the Verity search engine as ColdFusion does. Can I do text and query indexing with BlueDragon?

Answer

Yes you can. While BlueDragon does not embed Verity, it does instead embed an alternative text search engine, Lucene. All CFML tags related to this (CFCOLLECTION, CFINDEX, and CFSEARCH) as well as admin interface features for it exist, just as in CF. You can index text files, PDF, Word, database queries, and even can do web site spidering directly from CFINDEX (something CF doesn't offer). BlueDragon also supports cfsearch of multiple languages.

Faq ID

322

Product

BlueDragon

Category

Known Limitations and Workarounds

Question

Is there any reporting solution (such as CFMX 7's CFREPORT and Report Builder) in BlueDragon?

Answer

BlueDragon does not bundle a reporting solution. That said, there are alternatives available (including free ones) that may meet the needs of most seeking a reporting solution.

It's worth clarifying that the reporting solution provided by CFMX 7 does not necessarily serve the needs of all those looking for reporting. Any such solution must please several constituents: the report builder (and is that a developer or an end user?), the report viewer (does it produce the kind of reports they want? and in their desired format?), and the developer (integrating the report with their CFML to populate it with data gathered in a CFML page, if indeed that's even needed.)

Some have found the CFMX 7 solution wanting in one or more areas, and even if we came up with exactly the same solution, we know we would not please all users.

Therefore, reporting is an area where we feel it best to instead point out alternatives for your consideration. Some of them work quite easily and are free for deployment. Some may not integrate directly with CFML, but then for some reporting needs, that may not be as important as simply being able to "provide web-based reports" or create a PDF, excel file, word document, or chart for some given data.

There are many alternatives out there, but 3 we will discuss here (as samples) are: JasperReports (a free java solution), Microsoft's SQL Server Reporting Services (which can be used for reporting against more than just SQL Server), and LGX Report (the latter may not be well known, but it's a very interesting solution for those running on .NET, including BlueDragon.NET). It's worth keeping in mind that even a Java shop might choose to leverage a .NET solution (running separately), or vice-versa.

JasperReports

JasperReports is an open source (and commercially supported) reporting solution for the Java platform. Available from either http://jasperreports.sourceforge.net/ or http://www.jaspersoft.com/, it is both a reporting server and also a report builder. The reporting server is offered as a set of java libraries, which like any java solution can be implemented in the Java versions of BlueDragon (though not BlueDragon.NET, since .NET does not support Java classes unless recompiled using J#). The steps offered at the sites mentioned could be used by a BlueDragon user experienced with integrating Java and CFML. Admittedly, it's not as clean as having them bundled, which is something we could consider. Until then, those with an interest in trying this approach should know that it's available. A Google search on jasperreports will identify many articles and other resources to aid in the use of this tool.

Microsoft SQL Server Reporting Services

SQL Server Reporting Services (http://www.microsoft.com/sql/technologies/reporting/default.mspx) is a free add-on to SQL Server 2000 and a bundled component of SQL Server 2005. Providing both a reporting server and a report builder (including one for developers and one for end users), it is (especially as of the 2005 release) a very complete solution. An important point to keep in mind is that it can be used not only for querying/reporting against SQL Server but many other databases as well, including Oracle, ODBC databases, and more. The licensing is similar to (though separate from) licensing for SQL Server itself. Again, there is no direct integration currently in BlueDragon, but for the need to create reports and serve them over the web, this could provide most of what a developer/organization needs.

.NET 2.0 ReportViewer Control

New in .NET 2.0 is a "ReportViewer Control". Available free both as an add-in to Visual Studio 2005 and also as a redistributable for use on servers running .NET, you can use the control to access reports built with the available Report Designer (also a free add-in to VS) or via SQL Server Reporting Services. (The former approach is called "local" mode while the latter is called "remote" mode report processing.)

The local mode works much like the Report Builder and CFREPORT tag in CFMX 7. A developer lays out the design in the designer which produces an xml file (an .rdlc as opposed to .cfr) which is then referred to in the control (rather than the CFREPORT tag), and data is identified in code on the web page to be passed to the control to produce the report. All this could concievably be done in CFML, since with BlueDragon.NET, it's possible to call upon any .NET object and replicate what an ASP.NET page can do.

LGX Report

LGX Report, from LogiXML (http://www.logixml.com/) is a suite of reporting solutions, including a free "Liberator Edition" (http://www.freereporting.com/). Build entirely on and for .NET, it provides both a reporting server and a report builder. Like the above, it can create outputs in multiple formats and is easy to use. Again, there is no direct integration currently in BlueDragon, but for the need to create reports and serve them over the web, this could provide most of what a developer/organization needs.

As we explore and experiment with these and other reporting solutions, we'll offer more information (either in this FAQ, or a technote, or the docs). We hope this helps folks get started in exploring available options.

Faq ID

246

Product

BlueDragon

Category

Known Limitations and Workarounds

Question

What can I do about my need for COM object support in BlueDragon?

Answer

You may have noticed that BlueDragon does not calling COM objects from CFML in the same manner supported by ColdFusion: <CFOBJECT Type="COM"...> or CreateObject("com",...). This doesn't mean that you can't call COM objects at all, but that if it is possible just that there are extra steps. There may also be alternatives to using COM objects entirely. This FAQ addresses this challenge.

The good news is that there may be several ways to get around this limitation. It may be that CFML now offers equivalent functionality to the old COM object. Or, it may be possible to leverage Java or .NET libraries right from CFML that perform the needed feature. Indeed, the maker of a COM object may now offer a Java or .NET equivalent. If you're using our .NET edition, there is more direct support of COM objects (by way of .NET's own support of them). Finally, there is always the possibility of implementing any of the avalailable COM bridge packages yourself in BlueDragon. Don't let the lack of CFOBJECT Type="com" be a show-stopper. Following are discussions of each of these points.

Perhaps CFML Now Does What You Need

We've often found that the things people used COM objects for have been added to CFML, sometimes as was defined by Macromedia, and sometimes as new features we have added to BlueDragon. So you may simply not need the COM objects anymore. (If your needs are not met by current CFML features, we'll discuss how to get around that as well.)

For instance, one client wanted to perform zip operations (zip/unzip files). Of course, CF has no CFZIP tag, so a COM object (or a CFX) seemed an obvious choice to generations of CFML developers. The good news is that we heard that cry and have added a CFZip tag to CFML in BlueDragon 6.2. This is similar to how in previous releases we added CFIMAGE to do image manipulation (another thing one might look for from a COM object) and CFIMAP to do IMAP-based mail processing. We try to solve the problems that CFML developers need but Macromedia doesn't address.

Another client used COM objects to do authentication against the Windows Active Directory. Again, CFML might seem to have no built-in feature for that (CFLOGIN certainly doesn?t do it). But we pointed out that CFLDAP does indeed offer all that he needed, and BlueDragon does indeed support CFLDAP.

Some have used COM objects to create Excel spreadsheets, but you can create spreadsheets in CFML very easily. See our FAQ 292 for more information.

So sometimes COM objects were a last resort that really may no longer be the only alternative.

Accessing the Functionality via Java or .NET

In other cases, where you had some other use for COM not yet mentioned, you may also be able to enable it by leveraging the underlying platform (Java or .NET, depending on the edition of BlueDragon you're using). Again, often problems have been solved in those frameworks, and it's possible to call Java or .NET objects from within CFML using CFOBJECT, as discussed in our BlueDragon User Guide. There are Java libraries for creating PDFs, creating Excel spreadsheets, creating reports, and much more.

Indeed, it's entirely possible that the maker of your COM object may now offer a Java or .NET equivalent. COM is an older technology, and many vendors have gotten demand for more native alternatives. Ask your vendor, and if they offer one, we can help show you how to call that from within CFML. Indeed, you may find that your CFML calling the COM object would not other than changing from TYPE="com" to TYPE="java" or ".net". At least as long as the object's interface hasn't changed, t's still a process of calling objects and their methods and properties.

Accessing the COM object using BlueDragon.NET

In BlueDragon.NET, you can more directly access COM objects because .NET provides for a mechanism called "runtime callable wrappers". With these, built easily using Visual Studio or the command line .NET utility, tblimp.exe, you end up with a DLL that you can then call from CFOBJECT, and the wrapper acts as a proxy to the COM object. See the section 4.1.3 of the manual, "Integrating CFML with ASP.NET Servers" for examples as well as more information on supporting COM objects from CFML on BlueDragon.NET.

Again, though, it's also possible that the vendor of the COM object you're using may offer a native .NET object and you could call that more directly, as described in the previous section of this FAQ.

Using a COM Bridge

Finally, if you absolutely need COM object support in one of our Java editions and the solutions above don't work, there are available Java-COM bridge products available (some open source, some commercial). Some of the alternatives include:

New Atlanta has not yet tested these with BlueDragon, but since BlueDragon does support CFML-Java integration (see the BlueDragon 6.2.1 User Guide), it should be possible to call the Java objects created by these tools which would point to the intended COM objects.

Summary

So if you currently need COM object support, let us know what you need and we may be able to help you determine if equivalent functionality could be reached via an alternative. We realize that there could be an impact to your code so that changing to use an alternative is less desirable. As we say about BlueDragon's other few differences from CF, if you need the benefits we offer (price, support, options for bundling, protection of source code, more standard deployment on J2EE, the only option for CFML on .NET, and lots more), then making modest changes to work in it may be well worth the effort.

Keep in mind, also, that we're talking about changes that would often be backward-compatible with CF. As discussed above, COM objects used to be the only way to do some things. Changing code to work on BD to get around the lack of COM may be just as valuable to code running on CFMX as on BlueDragon, especially if you have to buy and license those COM objects for multiple servers, and the workarounds allow you to stop relying on the no longer needed COM objects.

Faq ID

43

Product

BlueDragon, ServletExec

Category

Known Limitations and Workarounds, Web Server Support

Question

Why doesn't my servlet which uses HTTP 1.0 keep alives work?

Answer

Keep-alives are used with HTTP 1.0 (only) to provide persistent connections. Keep alives aren't supported by ServletExec (or BlueDragon Server/JX).
With HTTP 1.1 connections are persistent by default, however there are some conditions to this.

Miscellaneous

Faq ID

386

Product

BlueDragon, ServletExec

Category

Miscellaneous

Question

Is there some relationship between my ServletExec Windows Service, and my ServletExec start and stop batch files?

Answer

When you start or stop the ServletExec AS Windows service from the Windows Services Control panel, the Windows Services mechanism simply calls the StartServletExec.bat or the StopServletExec.bat file.

If you start/stop SE by manually using the batch files, the Windows Service Mechanism does not know that you did that. So when manually invoking the batch files... the Windows Service Dialog may tell you that SE is stopped when in truth it is running (or vice versa).

Note:
It is the same with BDJX except the names of the Service and the batch files are different.

Security

Faq ID

268

Product

BlueDragon

Category

Security

Question

Does BlueDragon support SSL?

Answer

BlueDragon does support SSL in BlueDragonJX, BlueDragonJ2EE, and BlueDragon.NET. There is no support for SSL in BlueDragon Free Server whether you are using the built-in webserver or you've attached to IIS or Apache. The Free Server will throw a licensing error if you try to serve cfml pages through https.

Faq ID

406

Product

BlueDragon

Category

Security

Question

Is there a fix for the cfchart security hole in all BlueDragon 7.1.1 products and in BlueDragon.NET 9.0?

Answer

Yes.

If you are not using the cfchart tag then:

for BlueDragon JX and BlueDragon JEE, remove the servlet mapping of *.cfchart to the chartServlet from web.xml. Here are the lines you would remove:

for BlueDragon.NET, remove the BlueDragon-CFCHART handler from web.config for a virtual directory installation and from applicationHost.config for a global installation. Here is the line you would remove:

<add name="BlueDragon-CFCHART" path="*.cfchart" verb="*" ... />

If you are using the cfchart tag then:

for BlueDragon 7.1.1, install patch 18527 which is located at ftp://ftp.newatlanta.com/public/bluedragon/7_1_1/patches/18527/

for BlueDragon.NET 9.0, install patch 2 which is located at ftp://ftp.newatlanta.com/public/bluedragon/9_0/BD_NET_90_final_p2.zip

NOTE: the cfchart tag was added in BlueDragon 7.0 so earlier versions of BlueDragon do not have this vulnerability.

Faq ID

396

Product

BlueDragon

Category

Security

Question

What are the necessary file permissions required to run BlueDragon.NET on Windows 2008?

Answer

When BD.NET is installed on 2008 it gives the following accounts/groups full access to the BD.NET installation directory:

1. The default Application Pool Identity. This is the identity given to an application pool when it is first created. If you end up modifying the application pool to use a different identity then you will need to manually give that identity full access to the BD.NET installation directory.
2. The IIS_WPG group. By default this group contains the "LOCAL SYSTEM", "LOCAL SERVICE","NETWORK SERVICE" and IWAM accounts which will cover most cases.

You will also need to make sure the Application Pool Identity has read/write (execute if needed) access to your application.
More information on the Application Pool Identity:

As of the 6.1 release, BlueDragon supports IIS 6. See the system requirements page for more information on hardware/software support.

Faq ID

299

Product

BlueDragon

Category

Supported Features, Version differences

Question

Does BlueDragon support Java 5 (SDK 1.5)?

Answer

Java 5 (JDK 1.5) will be supported in the J2EE edition of BlueDragon (BD/J2EE), as of the 6.2.1 release, but the Server and JX editions (for Windows and Linux) will continue to bundle JDK 1.4.2, and that's the only version of the JDK we'll support for those editions (it's always been the case that we only support the bundled JDK for Server and JX on Windows/Linux).
BD Server and JX for Mac OS X support the version of the JDK bundled with Mac OS X. This could be either JDK 1.4 or 1.5 depending on the version of Mac OS X.

Faq ID

218

Product

BlueDragon

Category

Supported Features, System Requirements

Question

Does BlueDragon support Linux and other flavors of Unix?

Answer

Yes, BlueDragon runs on both Linux (multiple distros) and other Unix variants, depending on the BlueDragon edition (Server, Server JX, J2EE). See the System Requirements page for more details and the latest specific linux distros supported per the different BlueDragon editions. The following will help as well in understanding our Linux/Unix/OS X support.

First, BlueDragon/J2EE can run on a wide variety of Linux and Unix platforms (and OSX, as well as other operating systems). As long as there's an underlying J2EE server (or Servlet Engine) installed, BlueDragon/J2EE should be able to run on it.

Second, the Server and Server JX editions, on the other hand, are currently provided for Linux, OS X, and Windows, but not for Unix. Further, only Red Hat (RedHat) is currently supported for Linux. The server editions are provided as operating system-specific installers, and they have different requirements for working with or providing a JVM, working with web server adapters, and more.

While we have not tested and do not support them officially, we have had customers who have worked with the startup scripts to get it running on other Linux variants including CentOS, Slackware, Debian, SUSE, Gentoo, Ubuntu and others (a key requirement is to be running the 2.4 kernel).

A common problem when deploying on one of these other distros is that they may require some minor changes for the Apache distribution provided, otherwise BlueDragon may not properly process CFML pages. In such cases, it's often simply a matter of adding a few symbolic links (symlinks). See the manual, "Server and Server JX Installation Guide", and the section on "Apache Web Server Issues".

If you're looking for more information on getting a given distro to work with BlueDragon, first be sure to check the system requirements page offered above for the latest information on supported distros. Second, search the FAQs here for possible specific FAQs on the distro of your choice. Third, post your question to the BlueDragon Forums, as our customers often share with each other their own findings about working with a given distro. For instance, note that one has posted his experiences with getting BlueDragon running on Ubuntu.

Faq ID

212

Product

BlueDragon

Category

Supported Features, System Requirements, Web Server Support

Question

Does BlueDragon support Mac OS X?

Answer

As of the 6.1 release, BlueDragon supports Mac OS X, not just in the J2EE edition but also in the free Server and the Server JX editions (standalone servers, which ColdFusion only added as of CFMX 7.01).

There have been issues with integration of the Apache 2 edition provided with OS X. In such cases, installing a vanilla Apache distribution from the Apache site has resolved that problem.

Faq ID

211

Product

BlueDragon

Category

Supported Features, System Requirements, Web Server Adapter

Question

Does BlueDragon support RedHat 9 or Red Hat Enterprise Linux 2.1?

Answer

As of the 6.1 release, BlueDragon supports RedHat 9 or Red Hat Enterprise Linux 2.1. See the system requirements page for more information on hardware/software support.

Note, however, that there is a known issue with Apache 2.0.40, which is the default version of Apache offered with RedHat 9. Please see Faq 236 for more information and a patch.

Faq ID

209

Product

BlueDragon

Category

Supported Features, System Requirements

Question

Does BlueDragon support Windows 2003 server?

Answer

As of the 6.1 Release, BlueDragon supports Windows 2003 Server.

Faq ID

256

Product

BlueDragon

Category

Supported Features, System Requirements

Question

Does BlueDragon/.NET run on Mono?

Answer

Mono is an open-source implementation of the .NET framework (go-mono.org). It's primarily oriented toward .NET on Linux and OS X, and is backed by Novell and others.
Unfortunately, Mono does not yet implement all the features of .NET. Indeed, it has only certain minimal goals in its current pre-release status. BlueDragon needs features that it does not yet support, so BlueDragon does not currently run on MONO. We will be following its progress.

Faq ID

290

Product

BlueDragon

Category

Supported Features

Question

Is it possible to integrate BlueDragon and Flash?

Answer

Absolutely. There are several ways to integrate BlueDragon and Flash. See the BlueDragon 7.1 User Guide, section 5.2.4, for information on integrating BlueDragon with Flash, Flash Remoting, and other Flash Integration. It's possible, right now, to create Flash clients that call CFML pages (or CFCs) running on BlueDragon, using either calls for name/value pairs, XML, web services, integration via Flash Remoting, or using Flex.

Also, see FAQ 289 for a discussion of our plans to support Flash Forms as enabled in CFMX 7.

Furthermore, there are several alternatives from third parties that provide alternatives to Macromedia solutions like Flex (OpenLaszlo) and Flash Remoting (like FlashOrb/WebOrb), as discussed in those resources above.

Beyond Flash, another alternative for creating enhanced user interfaces is Ajax. It is certainly possible to call CFML pages on BlueDragon using Ajax, and there are several implementations of AJAX api's available. Indeed, a new version of FlashOrb (renamed WebOrb) provides built-in Ajax mechanisms that can be easily added to HTML pages (or CFML pages that generate HTML) and those can interact with CFML pages and CFCs running on BlueDragon. For more, including examples and a free trial, , see http://www.themidnightcoders.com/weborb/aboutWeborb.htm.

Faq ID

235

Product

BlueDragon

Category

Supported Features, XML

Question

What is the underlying XML parser and translator for BlueDragon?

Answer

BlueDragon Server and JX use the versions of Crimson and Xalan built-in to the bundled JDK 1.4.2 for XML processing:

BlueDragon is supported on Windows NT/2000/XP/2003 and Linux. Solaris is supported with BlueDragon J2EE.
Detailed operating system support information can be found on the BlueDragon
System Requirements Page.

Faq ID

170

Product

BlueDragon

Category

Supported Features, Web Server Support

Question

Which web servers does BlueDragon support?

Answer

BlueDragon supports Microsoft IIS, Netscape/iPlanet and Apache web servers.
The free Server edition has some limitations on web server/OS combinations. Detailed web server version support information can be found on the BlueDragon
System Requirements Page.

System Requirements

Faq ID

319

Product

BlueDragon

Category

System Requirements

Question

Can BD.NET 6.2.1 run on 64-bit Windows?

Answer

Yes it can but it must be run in 32-bit mode which hurts performance. Because of this we don't recommend running BD.NET on 64-bit Windows until Microsoft releases a 64-bit version of VJ#. Microsoft is planning to release a 64-bit version of VJ# with Windows Vista.

Make sure the 64-bit version of ASP.NET 2.0 is set to Allowed in the Web Service extension list of IIS.

Faq ID

380

Product

BlueDragon, JTurbo, ServletExec

Category

System Requirements

Question

How can the use of a 64-bit JVM impact my applications?

Answer

Sun Microsystems has published some excellent information regarding JVM heap sizes (and the calling of native code from a JVM) with respect to the bitness of the JVM and the native code.

Web Application

Faq ID

276

Product

BlueDragon

Category

Web Application, Web Server Support

Question

My Bluedragon-enabled .NET Webapp deletes or renames folders on the hard-drive and the performance is slow. Why?

Answer

In any .NET webapp (BD-enabled or not) if you delete or rename a folder within the webapp, the ASP .NET framework will reload the .NET webapp.
This causes Bluedragon (and all code running inside it) to be reloaded, which is clearly a drag on performance.
Currently we know of no way to prevent the ASP .NET framework from reloading a .NET webapp in this manner.
For more details please see section 7.1.2 of BlueDragon_70_Deploying_CFML_on_ASP_NET.pdf entitled "Automatic Stopping/Restarting of .NET Web Applications".

.NET Extensibility is a Windows Feature (on Vista & 2008) that must be enabled/installed/turned-on before BDJX can be hooked into IIS 7.

The BDJX 7.1 Installer (and Admin Console) will attempt to install/enable .NET Extensibility for you if it detects that it is not present when installing an IIS 7 Adapter/Handler.
However in some cases it will be unable to do so.
In that case you must enable .NET Extensibility yourself.

Here is how to turn it on in Vista:

Control Panel - Programs & Features - Turn Windows features on or off - Internet Imformation Services - World Wide Web Services - Application Development Features - .NET Extensibility

Check the checkbox to turn it on. Then try again to install the BDJX 7.1 IIS 7 adapter via the BD Admin Console.

Faq ID

275

Product

BlueDragon, ServletExec

Category

Web Server Support

Question

Now that I've upgraded to Windows 2003/IIS 6, responses take longer to arrive at my browser. What is wrong?

Answer

The first thing to do is to use the info given in FAQ #195 to apply the latest available updates.
If the issue still persists after that then you may need to read the information given in the following Microsoft KB article:
http://support.microsoft.com/default.aspx?scid=kb;EN-US;840875
Both ServletExec and BlueDragon (Server and JX) use WriteClient Sync calls so the workaround to use is the 2nd one given at the above link. To summarize:

create the following DWORD registry value and set it to 1:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\HTTP\Parameters\EnableCopySend

REBOOT THE MACHINE

To provide more details here in this FAQ, we can say this:
At the time of this writing, the link given above to Microsoft's website leads to a webpage that fully explains the issue and lists 2 workarounds.
The workaround that's needed for ServletExec is workaround #2.
At the time of this writing, that workaround was fully described as follows:

Method 2: Add the EnableCopySend registry entry
Use this method only for ISAPIs that perform synchronous send
operations. You can also use this workaround if at least one synchronous ISAPI experiences a network delay. However, this method
does not work in an environment where the majority of the clients use slow links, such as modems.
To apply this workaround, add the EnableCopySend registry entry to the following registry subkey, and then set the registry entry to 1:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\HTTP\Parameters
To do this, follow these steps:
Warning If you use Registry Editor incorrectly, you may cause
serious problems that may require you to reinstall your operating system.
Microsoft cannot guarantee that you can solve problems that result from using Registry Editor incorrectly.
Use Registry Editor at your own risk.
1. Click Start, click Run, type regedit in the Open box, and then click OK.
2. In Registry Editor, locate and then click the following registry subkey:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\HTTP\Parameters
3. On the Edit menu, point to New, and then click DWORD Value.
4. In the right pane of Registry Editor, type EnableCopySend, and then press ENTER.
5. Double-click the EnableCopySendregistry entry. The Edit DWORD Value dialog box appears.
6. Type 1 in the Value data box, and then click OK.
7. Quit Registry Editor.
8. Restart the computer.

Faq ID

378

Product

BlueDragon, ServletExec

Category

Web Server Support

Question

What can you tell me about using IWA with IIS?

Answer

Here is a collection of facts and observations regarding the use of Integrated Windows Authentication (IWA) with
Microsoft's IIS webserver.

IWA will not prompt the client/browser to login whenever that client/browser is running within the same domain as
IIS. In that scenario, the login is automatic and behind-the-scenes (i.e. seamless).
This fact is evidenced by this IIS forum post.

When you have mulitple authN mechanisms enabled for your IIS website (e.g. IWA *and* Basic),
then the IIS webserver will send back a list of all supported (i.e. enabled)
mechanisms to the client, and the client will select the "strongest" one that it supports.
So, if you have IWA *and* Basic enabled, and the client supports IWA, then
IWA will be used (e.g. NTLM or Kerberos). Only if the client doesn't
understand/support IWA would Basic be used. So, "yes", you can have both of
them selected, but if the client supports IWA, then it will attempt to use
IWA. With IWA, you need to supply a domain name as part of the username (e.g. <domainName>\<userName>).

If you are being prompted to login and yet your attempts to login keep failing, perhaps you need to configure
your Internet Explorer [IE] web browser to add the site you're requesting to its security zone as described here.
Essentially what can occur is that IE may decide to not trust certain websites based upon IE's own security settings.
Further details are here.

With IIS 7, Integrated Windows authentication isn't installed by default. As such, you'll need to go to the Add/Remove programs | "Turn Windows Features on or off".
This will bring up a new Server Manager dialog.
Click on the Role named "Web Server" and then in the right pane scroll down to the list of Role Services.
Look in the list of Role Services for the Heading named "Security".
Beneath that heading you should see Role Services named:

Basic Authentication

Windows Authentication

etc...

By default those Role Services are not installed, so go back to the top of the list of Role Services and click
Add Role Services...
From there you can check the checkboxes for the specific Authentication Role Services you wish to add.
After this completes, close the IIS Manger/Server Manger dialog and bring up a brand new one.
That is important.
Now in the brand new dialog click on the name of your website and then click on "Authentication" in that IIS group. You should then see that "Windows Authentication" has been added to the list (it would not have been listed there before). Make sure to enable it, as its default value will be "disabled".
In testing, we found that it was not enough to turn on the IWA authentication within IIS.
We found that we must also turn off Anonymous Access.

With BDJX 7.0.1,371 the value of Auth_user and Remote_user is simply "Administrator",
but with BDJX 7.1.0,373 the values are "<machine name>\Administrator" as in:
WIN-1T1ZLEDWXSK\Administrator

It is possible to perform advanced configuration within Firefox by accessing the following URL in a Firefox browser window:
about:config

Yes it can. Your web service project will need to have references to the BlueDragon and BlueDragon.Controls DLLs. Here's an example of an ASP.NET web service calling a CFC. This example was tested with BD.NET 7.0.1 beta1.

Yes, you can use JTurbo Drivers with Java Applets but your web server and SQL Server must be running on the same machine. This is a limitation of Type 4 drivers since applets are only allowed to connect to the machine which they came from. This problem can be circumvented by having your applets talk to a standalone application running on the same machine as the web server which in turn connects to the SQL Server for performing all JDBC related operations.

ArcIMS Users

Faq ID

193

Product

JTurbo

Category

ArcIMS Users

Question

Can JTurbo be used with ESRI's ArcIMS Internet GIS Mapping Server ?

Answer

Yes.
ArcIMS has a built-in ability to password-protect access to certain GIS mapping services that have been published.
The Authentication can be done by checking a database table of users that you setup.
Here are some details regarding this:

These instructions assume that you already have the following
software components installed:
1. Web Server
2. Servlet/JSP Engine
3. ArcIMS
And they also assume that if your Servlet/JSP Engine is ServletExec,
that you have password protected access to the Main SE Admin UI,
and that you have successfully tested the password protection
feature, and that you have both SE and ArcIMS working together
as required.
If you are using the ArcIMS Servlet Connector running inside
a Servlet/JSP Engine, and you use Microsoft SQL Server and you want
to restrict access to certain ArcIMS mapping services based on
users defined in your SQL Server database then the following information
may be useful to you.
The ArcIMS Servlet Connector is the Java-based conduit by which your
users access your ArcIMS mapping services via the internet.
It is easily possible to configure your ArcIMS Servlet Connector to
authenticate users of your mapping services, prompting them
to login, and denying access to unauthorized users.
In the world of Java, the most common way that Java programs (such as the
ArcIMS Servlet Connector) communicate with a database (such
as MS SQL Server) is via JDBC (Java Database Connectivity).
Specifically, you would need to obtain a JDBC driver that is
capable of communicating with your database.
JTurbo is a JDBC driver for connecting to MS SQL Server.
It is made by New Atlanta Communications and can be downloaded
for free from:
http://www.newatlanta.com/products/jturbo/download.jsp
Detailed information about how to setup ArcIMS for Authentication via a
database and a JDBC driver can be found in the ArcIMS Help web pages which
come with ArcIMS.
For ArcIMS 4.0.1, this information can be found in the following location:
Start - Programs - ArcGIS - ArcIMS - ArcIMS Help
Once viewing the html pages navigate to:
Advanced ArcIMS topics - Restricting user access to services - User
Authentication in the Servlet Connector - Enabling authentication with
a JDBC-based ACL.
The 8 steps given there are very useful and you should read and follow
them. However, do not perform any of those 8 steps until you
first download, install, and learn about the JTurbo driver
from New Atlanta Communications.
You should also download the JTurbo Installation Guide & the JTurbo User
Guide.
Once installed, JTurbo comes with several examples.
There is really only 1 example that you should bother with.
It is the one named:
"StatementExample.java"
The ReadMe.html file in the JTurbo Examples folder tells you how to compile
and run it.
Once you can run that example and you can examine your database to confirm
that it ran successfully, then you are ready for the next step:
Adding the JTurbo.jar file to the classpath of your Servlet/JSP Engine.
How to do this will vary depending upon what brand of Servlet/JSP Engine
you are using, you should consult the documentation that came with
your Servlet/JSP Engine.
If you are using New Atlanta's ServletExec as your Servlet/JSP engine
then you should look at section 2.3 of the SE 4.1 User Guide.
For example if your JTurbo.jar file resides at:
C:\Program Files\New Atlanta\JTurbo\lib
then you would add
C:\Program Files\New Atlanta\JTurbo\lib\JTurbo.jar
to the main SE classpath and then reinitialize ServletExec.
Then you should perform the 8 steps given in the ArcIMS Help.
For step #2 entitled:
"Edit properties in the Esrimap_prop file"
here are example values for the 13 properties
which must be set:
+++++++++++++++
authenticate=True
authMethods=Basic
authenticateWithSessions=True
sessionTimeout=1800
realm=My ArcIMS Resources
useJdbc=True
jdbcDriver=com.newatlanta.jturbo.driver.Driver
jdbcUrl=jdbc:JTurbo://localhost:1433/test_database/sql70=true
jdbcUser=testuser
jdbcPassword=testuser
jdbcPermTable=arcIMS_permissions
jdbcUserTable=arcIMS_users
jdbcUidColumn=userid
+++++++++++++++
Steps #4, 5, 6, & 7 are summarized by the following
example DDL (Data Description Language)
*/
++++++++++++++++++++++++++++++++++++++++++++++++++
/*
1. Setup the User table
The name of this table must be the same as the name you specified in the
Esrimap_prop file for jdbcUserTable.
*/
create table arcIMS_users (userid bigint IDENTITY (1,1) NOT NULL,
username varchar(64) NOT NULL,
password varchar(64))
/*
setup permissions
*/
grant all on arcIMS_users to public
/*
populate the user table
*/
insert into arcIMS_users values ('*', null)
insert into arcIMS_users values ('user1', 'password1')
insert into arcIMS_users values ('user2', 'password2')
insert into arcIMS_users values ('testuser', 'testuser')
/*
2. Setup the permissions table.
The name of this table must be the same as the name you specified in the
Esrimap_prop file for jdbcPermTable.
*/
create table arcIMS_permissions (userid bigint NOT NULL,
service varchar(64) NOT NULL,
active bigint NOT NULL,
expiration datetime,
tclients varchar(1024),
ftags varchar(1024),
roles varchar(1024))
/*
setup permissions
*/
grant all on arcIMS_permissions to public
/*
populate the permissions table
*/
insert into arcIMS_permissions values (4, 'Esri', 1, null, null, null, null)
/*
Now, any user requesting images or data from the ArcIMS map service named "Esri"
will be prompted by their web browser to Authenticate (i.e. enter their
username and password).
Only the user whose userid = 4 (in the arcIMS_users table) will be allowed access.
*/
+++++++++++++++++++++++++++++++++++++++++++++++
If you are having trouble and need to enable debug messages for the JTurbo
JDBC driver, then one way to do this is to create a JSP page or a Servlet
which simply performs the following code when invoked:
java.sql.DriverManager.setLogWriter( new java.io.PrintWriter(System.out) );
Then invoke that JSP or Servlet and then try to access the ArcIMS map service,
which you are trying to password-protect in your browser.

Faq ID

96

Product

JTurbo, ServletExec

Category

ArcIMS Users, Class Loading/Reloading, VM Settings, VM Support, XML

Question

I am trying to compile or to run my Java code but I get NoSuchMethodError or things are behaving as if I am using an incorrect version of a class or JAR file. What is wrong ?

Answer

The problem may be that you have an incorrect version of a JAR file residing in the extensions folder of your JVM installation.
Check places like:

C:\jdk1.2.2\jre\lib\ext

C:\jdk1.3\jre\lib\ext

C:\jdk1.4\jre\lib\ext

JARs placed there get added to the JVMs classpath when the JVM starts up, before other code (such as ServletExec, or such as a -classpath option of the java or javac commands) gets to append/effect the Classpath. This could prevent the correct version of classes from being recognized, in which case you should remove the incorrect JARs in the extensions folder (or at least change their extensions to something other than .jar or .zip

If that does not seem to help (even after a restart of the JVM) then there is a System property you should examine (the one named "sun.boot.class.path").

If you are using SE 5.0 or newer you can view all JVM System properties using the SE Admin UI.

If you are using SE 4.2 or older, then you can view the property of interest using Java code like this:
System.out.println(System.getProperty("sun.boot.class.path"));
It's value will be a list of JARs that your JVM is adding to its classpath automatically. If you see one that is not the correct version or may be conflicting with the one you want to use then remove it, or rename it with an extension other than .zip or .jar so that the JVM won't automatically add it to the classpath.
You may also need to examine other System Properties.
You could run code like the following to output all of them:

If you are a user of ESRI software then you may be seeing an error:
NoSuchMethodError at org.apache.crimson.jaxp.DocumentBuilderImpl
The most common time that ESRI software users see this problem is when they have installed ArcIMS and ServletExec, and they try to deploy a web application (any web application) inside ServletExec.
This problem is caused by conflicting versions of jar files on your machine as described at the beginning of this FAQ. The complete details about this are:
ArcExplorer Java is responsible for placing the older jaxp.jar and
parser.jar files into the extensions folder of the JVM.
Even the version of ArcExplorer Java that comes with ArcIMS 4.0.1 will do this.
The location of the extensions folder will depend on which version of JVM you are using and whether or not you are using JRE or JDK.
You should look in folders such as:

C:\jdk1.2.2\jre\lib\ext

C:\jdk1.3\jre\lib\ext

C:\jdk1.4\jre\lib\ext

or perhaps:

C:\Program Files\JavaSoft\JRE\1.3.1\lib\ext (if using JRE)

for jaxp.jar and parser.jar.
Since ArcExplorer Java needs these JARs (but their presence prevents ServletExec from functioning correctly), here is what you must do:

Find the jaxp and parser JARs in the ...\lib\ext folder

Note the absolute path to that ...\lib\ext folder for step 5 below

Move (not copy) the JARs to another location, such as C:\myJars

Right-click on the shortcut used to start ArcExplorer Java and choose
Properties

In the Target box, insert the following just prior to the first "-X"
argument:
-Djava.ext.dirs="<full path to \lib\ext folder>;C:\myJars"
where <full path to \lib\ext folder> is the absolute path that you noted in step 2 above.

The following is an example (each argument is shown on a separate line for
clarity):
"C:\Program Files\JavaSoft\JRE\1.3.1\bin\javaw.exe"
-Djava.ext.dirs="C:\Program Files\JavaSoft\JRE\1.3.1\lib\ext;C:\myJars"
-Xms24m
-Xmx256m
com.esri.ae.AE

ServletExec already has the correct versions of the classes provided by these JARs.
By removing these files from the ...\lib\ext folder, you allow the JVM that ServletExec starts up to see ServletExec's versions, and so SE should work correctly now.
And by changing the way that ArcExplorer Java starts the JVM (as shown above) you ensure that ArcExplorer Java will continue to function correctly too.
NOTE: simply renaming these files may not be sufficient. They must be removed from the \ext folder, and then the JVM must be stopped and restarted.
Also, do NOT simply delete these JAR files. Because then if you need them again for some reason, they'll be gone. Save them somewhere safe, where you can find them again if needed.

CallableStatement

Faq ID

239

Product

JTurbo

Category

CallableStatement, PreparedStatement, Statement

Question

I'm receiving unexpected or more-than-expected update counts. Why is this happening and what can be done to fix it ?

Answer

If the SQL you are sending to the database via JTurbo is causing database triggers to execute then you should be aware that certain triggers may produce their own update counts which JTurbo will receive and make available to your code via the Statement interface (implemented by JTurbo's Statement, PreparedStatement, or CallableStatement objects).
You can either write your code to handle these update counts properly, or you could modify the SQL of your triggers so that any update counts that they generate will be suppressed.
This could be done in the following manner:
At the beginning of your trigger(s) add the statement:
SET NOCOUNT ON

Also note that Query Analyzer does not report these extra, possibly unwanted update counts. This is because when you send the SQL from query analyzer it is sent as a regular statement... not a PreparedStatement or a CallableStatement. Regular statement rowcounts are returned differently than are trigger rowcounts but PreparedStatement rowcounts and CallableStatement rowcounts are NOT returned differently than are trigger rowcounts. That's why query analyzer is able to ignore the trigger rowcounts. JTurbo could potentially be made to ignore such update counts IF a regular Statement is used, but not if a PreparedStatement or CallableStatement were used. For this reason JTurbo does not attempt to ignore these counts (even if you use a regular Statement). The prefered way to fix this is to modify the SQL in your trigger as mentioned above since some customers may desire these update counts while others may not.

Connection

Faq ID

146

Product

JTurbo

Category

Connection, Security, Supported Features

Question

Can JTurbo Type 4 driver communicate through an encrypted channel ?

Answer

JTurbo uses TCP sockets to communicate with MS SQL Server.
The protocol it uses is a proprietary Microsoft protocol called TDS.

If using JTurbo 2005 or newer:

This is possible via Windows Authentication using NTLM. This feature can be used by:

Setting the new JTurbo property "clientDomain" to the domain in which JTurbo is running.

Setting the JTurbo property "clientHost" to the host on which JTurbo is running.

If using JTurbo 3.x or older:

We know of no way to encrypt this protocol.

Most people put their code that uses JTurbo behind a firewall.
For example, clients (web browsers) talk to a web server via SSL (https), and the web server invokes code which uses JTurbo to connect to an SQL Server installation which is behind that same firewall.

Faq ID

76

Product

JTurbo

Category

Connection, Security, Supported Features

Question

Does JTurbo support Trusted Connections / Windows Authentication ?

Answer

JTurbo 2005 does support Trusted Connections (also called Windows Authentication). Refer to the JTurbo 2005 User Guide for further details on how to configure JTurbo to use Windows Authentication.

Faq ID

230

Product

JTurbo

Category

Connection, Debugging

Question

How can I know whether or not my SQL Server is listening on a TCP/IP port ?

Answer

Go to:
Start - Programs - Microsoft SQL Server - Server Network Utility (in the Microsoft SQL Server 7.0 program group).
On the general property sheet, Add or select TCP/IP under Network libraries. Enter the port number and the proxy address (if nesessary) and click OK.
By default, Microsoft SQL Server uses port 1433.
However, it can be configured to listen on any port number. To make sure that the RDBMS server is listening on the machine name and port number you specified use:
telnet <hostname or ip address> <port number>
If the connection is refused then the hostname or the port number may be incorrect, or possibly your networking is setup to block traffic on that port (a network firewall for example).

Note that with Win2003 the network libraries for SQL 2000 are disabled by default until you apply SP3/SP3a.
This fact is mentioned on a
Google Group Forum
Thanks to Peter Hradecky for locating this information and confirming that it works.

Faq ID

124

Product

JTurbo

Category

Connection, Connection Pooling, DataSource, Debugging

Question

I am getting Communication Link Failure. What does this mean and how can I fix it ?

Answer

Communication Link Failure can occur for a variety of reasons.
Among the first things to check are:

Make certain you are attempting to connect using the correct hostname, port & database (if the username and password is incorrect the error message would say so).

Make certain that your SQL Server is actually up and running.

Check your SQL Server logs and/or Event Viewer to see if SQL Server recycled or went down when this error occured. The logs may provide other clues as to what was going on when this error occured.

When connections in a connection pool get old/stale they can sometimes fail to work with SQL Server complaining about Communication Link Failure or other odd errors. To prevent this, you should periodically clean out stale/unused connections from your pool. If you use JTurbo's Connection Pool implementation, then the ability to do this is already built-in.
For example, with PoolManagerDataSource, the default max idle time is 0 which means that connnections are never removed/evicted from the pool, they just hang around forever.
We recommend that you set this to a number of seconds greater than 0
using code sort of like this:

Once maxIdleTime is > 0, the background thread which cleans up old/stale Connections from the pool (called PropertyCheck Thread) will wake up every 60 seconds by default. This timing can be changed by using code sort of like this:

Here are some other troubleshooting ideas to consider:
You may be running out of sockets/ports on the machine where JTurbo is
being used. Use a windows tool such as netstat (netstat -a) to look at
all of the currently active sockets/ports. Are there many of them?
If you reboot the machine, and then use netstat again are there far less
active sockets/ports in use?
And does that make the problem go away for a while?
If so, periodically use netstat and compare its output with previous
runs of netstat to see if the # of sockets/ports in use is steadily
climbing.
When your system is in this state try running your client code from a
different machine to see if it works or not.
Check your code that is using JTurbo and make sure that you are closing
all Connections, Statements, & ResultSets in a finally block:

If your progam is long-lived (i.e. you start it once and it stays
running for a long time, repeatedly getting connections and using them)
then not closing things as mentioned above is a definite thing to check.
But also consider how such code is getting its Connection objects.
Is your code simply using DriverManager.getConnection() (Not reusing connections but rather getting a brand new one every time it needs one) ?
If so, changing your code to use JTurbo's own built-in connection pooling datasource (PoolManagerDataSource) may be the solution.
After you close a (non-pooled) Connection, the OS does not release the socket immediately.
It goes into a CLOSE_WAIT state for some time period that the OS determines.
Eventually it drops off and its resources (file descriptor) is released
to the OS for reuse. But until then it is using up that descriptor.
An OS only has so many descriptors to give out at any one time and then they are exhausted.
In that scenario switching your code to get its connections from a db
connection pool could be the solution.
Doing that is good regardless as it can greatly improve performance of
an app that keeps needing connections to the db. But even with a db
connection pool you must ensure your code is closing everything.
Doing con.close() on a con that came from a pool does not actually close
it, but rather puts it back in the pool for reuse.

It may also be helpful to understand that "Communication Link Failure" is not coming from JTurbo code. JTurbo is receiving that message from SQL Server. JTurbo is then simply wrapping that message into an SQLException and throwing it. A Communication Link Failure problem can occur when using any database client (not just JTurbo). This article may give further clues. It states (among other things) that:

Communication link failure is a mid-stream failure of the connection from client to SQL Server. This typically points to problems with your networking layer, typically networking hardware.

The "Address already in use: connect" error is caused by client socket starvation on the machine(s) that [your JDBC driver] is running on. By default Windows does not allow you to set up client connections on ports above 5000. After a socket has been closed, the connection stays in a TIME_WAIT state for another 2 minutes, after which the socket is freed and the address can be reused. If more than 4000 connections (1024-5000) have been made before those ports are freed (after 2 min. in TIME_WAIT), then attempts to open a client socket on a port above 5000 will be rejected by the operating system, which will cause Java to throw "Address already in use: connect". This can be fixed by modifying the Windows registry entry that controls this parameter:

1. Start Registry Editor: Start Menu > Run > Type in "regedit"
2. Locate the following key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters
3. Right click on the Parameters folder and select New > DWORD Value
4. Name this new key "MaxUserPort"
4. Double click on the "MaxUserPort" key and change the value data to 65534 and select "Decimal" as the base.
5. Restart the machine.

(For more information see Microsoft Knowledge Base Article 196271)

If you see this problem using JTurbo and you are NOT getting your database connections from a JDBC Connection Pool, then before you mess with the registry as described above you should modify your code to get its connections from a Connection Pool instead (JTurbo's built-in PoolManagerDataSource is an excellent choice for this). See the top of this FAQ for more details about using PoolManagerDataSource. This stands a very high chance of completely correcting the issue.

Faq ID

135

Product

JTurbo

Category

Connection

Question

I am running multiple SQL Server instances and using <host-name>/<instance-name> in my jdbc url to connect. Why doesn't it work ?

Answer

When using JTurbo to connect to a named instance of SQL Server, you cannot use the instance name in the jdbc url. Instead you must use a regular jdbc url and specify the port number of that instance. Here is the form:
jdbc:JTurbo://<hostname>:<port>/<databaseName>/sql70=true/sp=false

Connection Pooling

Faq ID

204

Product

JTurbo

Category

Connection Pooling

Question

How can I tell if a pooled connection is still valid?

Answer

The PoolManagerDataSource can now be configured to test a pooled connection to verify it is still good before returning it. This feature is disabled by default. To enable it you must set the testConnection property to true. If you are creating the PoolManagerDataSource directly then this is done by calling the method setTestConnection( true ).
See the following document for more details.
ftp://ftp.newatlanta.com/public/jturbo/3.0.2/patch/ReadMe.txt
You can also refer to the JTurbo 2005 User Guide for more details.

Faq ID

125

Product

JTurbo

Category

Connection Pooling

Question

Is there a limit to the number of concurrent JDBC Driver Connections that SQL Server will accept ?

Answer

We know of nothing that would limit the number of allowable connections to SQL Server, other than system resources, and any sort of configured limits in SQL Server.

java.sql.DatabaseMetaData.getMaxConnections()
will tell you the maximum number of concurrent connections you can have to your database. At the time this FAQ was written, the JTurbo implementation of that method returns 32767
This is per SQL Server 2000 Books Online "Administrator's Companion" Part 1, Chapter 1.

DataSource

Faq ID

264

Product

JTurbo

Category

DataSource, Distributed Transactions, Transactions

Question

Can the JTurbo distributed transaction datasource (com.newatlanta.jturbo.driver.JTXADataSource) be used with JBoss?

Answer

Yes it can but since the JTurbo distributed transaction datasource doesn't support multiple transactions on a single connection, JBoss must be configured to only use one transaction per connection. This is done by adding the <track-connection-by-tx/> tag to the <xa-datasource> tag. Here's an example:

Use JTurbo's built-in connection pool datasource named PoolManagerDataSource.
JTurbo comes with sample programs and their source code.
One in particular [PoolManagerExample.java] shows how to create and use an instance of PoolManagerDataSource.
Here is the code for a java method to do this:

What are all the data sources provided by JTurbo 3.0 and JTurbo 2005 and how do they differ ?

Answer

The chapter about Using Data Sources in the JTurbo 3.0 and JTurbo 2005 User Guides discuss the 4 types of datasources provided by JTurbo:

com.newatlanta.jturbo.driver.DataSource
This data source is used to obtain a non-pooled connection.

com.newatlanta.jturbo.driver.ConnectionPoolDataSource
This data source will not do the actual connection pooling but will allow the application or application server to do the pooling.

com.newatlanta.jturbo.driver.PoolManagerDataSource
This data source can be used to get a connection which is pooled. This data source should not be used in applications or application servers which perform connection pooling (because the connection it gives you has already come from a pool). See FAQ #389 for more details.

com.newatlanta.jturbo.driver.JTXADataSource
This data source can be used to get a connection which is pooled and which can take part in a distributed transaction.

Whether or not your copy of JTurbo support all 4 of these will depend upon which JDBC specification your JTurbo distribution supports.

Debugging

Faq ID

21

Product

JTurbo, ServletExec

Category

Debugging, JDBC

Question

What can I do to help debug problems with my JDBC code?

Answer

If your JDBC connections are created by using the DriverManger.getConnection() method then:

An application may enable the logging of debug messages to a PrintStream or
PrintWriter for all loaded JDBC drivers (including JTurbo) by using the following
code:
PrintStream printStream = new PrintStream( ... );
DriverManager.setLogStream( printStream );
OR
PrintStream printWriter = new PrintWriter( ... );
DriverManager.setLogWriter( printWriter );
For example, to have the debug messages logged to the console use:

For example, to have the debug messages logged to the console use:
ds.setLogWriter( new PrintWriter( System.out ) );
OR
ds.setLogWriter( new PrintWriter( System.err ) );

Note: the above information can also be found in the DataSource chapter (chapter 2) of the JTurbo 3.x and JTurbo 2005 User Guides

EXAMPLE:
If using a datasource named "daffy" from within a Servlet/JSP engine where the datasource has been configured inside the engine, then here is the code for a JSP you could request to turn the debugging on or off:

I'm getting NoClassDefFoundError when downloading Applets. How can I fix this?

Answer

You need a Java plug-in to make your applets run in the different browsers. Once you have installed the Java plug-in you can make JTurbo work in an Applet with out any problems.

Faq ID

82

Product

JTurbo

Category

Exceptions

Question

I'm receiving java.lang.OutOfMemoryError. How can I fix this?

Answer

OutOfMemoryError [OOM error] can occur when reading large amounts of data from the database because by default, JTurbo will read all the resultset data into memory. Here are some suggestions for working around this problem:

Set the cursor name on the Statement object [setCursorName(String name)], and also set the fetchSize.
There are a few different ways to set the fetchSize:

Use the JTurbo URL flag named fetchSize.

Call Statement.setFetchSize()

Setting the fetchSize will cause the result data to be read in chunks specified by the fetchSize parameter. This is a powerful feature for those who are reading hundreds of thousands of rows from the database and don't want to run out of memory.
Note that the fetchSize is merely a hint to the database and the database is free to ignore it. If you are calling a stored procedure that returns a resultset, setting the fetchSize may not help.
In that scenario you should consider these alternatives:

change your code to directly use a Select statement rather than calling a stored procedure.

consider using the TOP directive in your query "select top 100 from..."

modify your stored procedure so that it only returns a "page" of rows at a time.
In that scenario you'd make repeated stmt.execute() calls, possibly even passing which page you want to the stored procedure.
The first code example given here might be useful.

Increase the max heap size (RAM) available to the JVM.

The start of this FAQ says that JTurbo will read all the resultset data into memory... but in truth (at least with JTurbo 2005 and newer) the default value for fetchSize is 100). What this means is that by default the resultset will initially contain (at most) 100 rows/records. As you loop over the resultset calling next() on it, JTurbo will read in the next "chunk" of 100 rows every 101th call to next(). If your code is accumulating all "chunks" of results into memory then that might be what's causing the OOM error. In other words it is possible that the OOM is not so much due to JTurbo as it is due to how your code is reading the data from JTurbo.
In that scenario, one possible workaround might be for your code to "spool" the resultset data to a file rather than try to accumulate all of it in memory at once.

Make sure you are not using Windows NT based authentication in SQL Server with JTurbo configured to use SQL Server authentication. If SQL Server is configured to use Windows NT based authentication only then you will need to configure JTurbo to use Windows NT based authentication too. Note that JTurbo 3.0 and earlier do not support Windows NT based authentication.

Make sure you SQL Server is running on the port specified in the JTurbo URL. Also make sure SQL Server is running and not stopped. And also check that you have TCP/IP enabled and selected as the SQL Server network library.

Faq ID

86

Product

JTurbo

Category

Exceptions

Question

java.sql.SQLException: The cursor is READ ONLY.

Answer

This exception occurs when you are using SCROLL_TYPE_INSENSITVE and CURSOR_UPDATABLE parameters with the createStatement() method. You cannot use this combination if you want to perform updates, inserts and deletes on the cursor. Another common reason for this exception to occur is absence of the Primary Key in the table in use.

Faq ID

132

Product

JTurbo

Category

Exceptions

Question

When I try to connect to SQL Server from within my Java code I am seeing an exception that looks something like this:<br><code>java.sql.SQLException: Unknown packet subtype 0x0<br>java.lang.Throwable(java.lang.String)<br>java.lang.Exception(java.lang.String)<br>java.sql.SQLException(java.lang.String)<br>java.sql.Connection</code><br> What is wrong ?

Answer

This problem is commonly due to an incorrect SQL Server Configuration. You should try each of the following suggestions
(one at a time, re-testing after each change)
to see if any will fix the problem for you:

Make sure that your SQL server is running on the "default" port of 1433.
If not, you need to specify the correct port number in your jdbc url.
Now re-test to see if that change fixed the problem.

Make sure that your SQL server authentication (SQL-based or Windows-based) matches the authentication being used by JTurbo. Note that JTurbo 3.0 and earlier only support SQL-based authentication
Now re-test to see if that change fixed the problem.

Make sure that your SQL Server is TCP/IP enabled.
Now re-test to see if that change fixed the problem.

Make sure that your user name and password are valid for your SQL Server.Now re-test to see if that change fixed the problem.

The JTurbo 3.0.2 installer won't run on my Windows 2003 machine. How can I workaround this problem ?

Answer

When this problem occurs the JTurbo installer will seem to run fine.
But JTurbo won't truly be installed, since the installation folder will not contain any JTurbo components and JTurbo won't show up in Add/Remove programs.
The default installation location will be incorrect.
It will be of the following "unix-like" form:
C:\usr\local\New_Atlanta\JTurbo
The installer will complete, but will notify you that errors occured during installation (even if you had modified the installation path to be more windows-like).
Here is the workaround to this installer limitation:

Right click on the JTurbo installer file and choose Properties

Select the Compatibility tab

check the checkbox labeled Run this program in compatibility mode for

Choose Windows 2000 from the drop-down list

Hit the Apply button and confirm that the changes were accepted

Hit the OK button and then rerun the installer by double-clicking it (if double-clicking it does not seem to work then try running the installer from a command window by typing its name manually)

Once JTurbo has been installed, you must perform the same modification to the JTurbo uninstaller if you want to be able to uninstall JTurbo at a later time without problems. Using JTurbo 3.0.2 for JDBC 2.1 as an example, the JTurbo uninstaller file would be:
D:\Program Files\New Atlanta\JTurbo\Uninstall\Uninstall JTurbo 3.0.2 for JDBC 2.1.exe
So you would need to perform the above steps on that file too.
That way when you use Add/Remove programs to remove JTurbo, the JTurbo uninstaller that gets invoked will be able to run properly and do all that it needs to do to get JTurbo completely off the machine.
This problem was corrected in JTurbo 2005.

Note: If this faq does not quite apply in your case, or did not get you past the problem, then please see FAQ #280

Faq ID

321

Product

JTurbo

Category

Installation, Version differences

Question

Which version of InstallAnywhere does the JTurbo installer use?

Answer

The JTurbo 2005 Installers were built using InstallAnywhere 7.1 Enterprise

Internationalization

Faq ID

107

Product

JTurbo

Category

Internationalization, Known Limitations and Workarounds

Question

How do character sets work with SQL Server and JTurbo ?

Answer

With SQL Server, a character set is chosen during SQL Server Setup and cannot be changed.
It is usually set to the default character set of the platform
on which SQL Server is running. So for English Operating Systems this would normally be the
ISO Latin-1 (8859_1) character set.
By default, JTurbo will use the default character set of the platform on which JTurbo is
running when working with char, varchar, and text SQL Server data types.
The default charset used by JTurbo can be changed by setting the charset property in your jdbc url
or in your datasource that is used to get the database connection.
Section 1.4.3 of the JTurbo 3.0 and JTurbo 2005 User Guides provide the jdbc url syntax for setting a property.
If you do use the charset property then your application should only use Unicode since JTurbo and
SQL Server will handle the conversions back and forth between Unicode and the specified character set.
More details:
JTurbo's charset property effects how JTurbo treats the unicode strings it receives from SQL Server... not the strings it sends to SQL Server.
JTurbo will always send string data to SQL Server as Unicode (2 bytes per character).
Depending upon the type of your database column and the manner in which you are sending the query to SQL Server, this may potentially force SQL Server to first store the received Unicode string as nvarchar, and then convert it from nvarchar to the column's charset before inserting it into the column.

The only ways to avoid that expensive type-conversion are:

change the type of your column in the database to be one of the 'n' types (nchar, nvarchar, ntext). SQL Server stores such values as Unicode (no conversion needed)

-OR-

use PreparedStatement.setBytes()

Please see JT FAQ #183 for further details about that peformance-related issue.

How do I fetch character data from SQL Server using an encoding that is different from the encoding in which it was stored ?

Answer

Get the String from the ResultSet and then convert the String into its raw bytes.
Then create a new String object from the bytes, specifying the new encoding.
For example:
byte bytes[] = rs.getString( i ).getBytes( "8859_1" );
String s = new String( bytes, "Cp850" );

Faq ID

229

Product

JTurbo

Category

Internationalization

Question

How do I insert and retreive International / non-ASCII characters into SQL Server using JTurbo ?

Answer

Internally, Java stores all strings using the Unicode character set
which uses 2 bytes per character. If your java code uses bytes that are
part of a character set other than Unicode (ex. Cp1252, Shift-JIS, or Big5)
then you will need to convert those bytes to a Unicode string before
passing them to the JTurbo driver. To convert some Cp1252 bytes to a
Unicode string you would do the following:
String unicode = new String(cp1252Bytes, "Cp1252" );
JTurbo will send the characters to SQL Server
as Unicode and SQL Server will convert the characters to the charset it
is using before inserting the data into the database.

When JTurbo retrieves the stored data, it will need to convert the bytes it receives from SQL Server into Unicode. This means you must set the JTurbo
charset connection property to the appropriate value so JTurbo will know
how to convert the bytes to Unicode. FAQ #107 gives more details about this.
The following example shows how the Euro character in the Cp1252
character set would be inserted into and read from SQL Server. Note
that in the Cp1252 character set the Euro character has a value of 128
while in the Unicode character set it has a value of 8364.

If you wish to store unicode data in your database, be certain that the column is one of these types.
When you later fetch the String data, if you don't want to use the Unicode charset then you'll need to convert the String that was fetched into its raw bytes using the appropriate charset name, and then use the bytes to create a new String that is encoded to the charset that your application expects. There is another FAQ which shows how to do this.

This can occur when the SQL Server data type of your table's column is different than the type being used in your query.

For example, say you have a table in your SQL Server database with a column of type char or varchar, and the query in your Java code looks like this:
"SELECT * from mytable where mytext = ?"
If you use pstmt.setString(1, "99"); in your Java code, then JTurbo inserts the parameter and builds the query using 'N' like this:
... where mytext = N'99'
This forces SQL Server to do a conversion from nvarchar to the type of your table's column (char or varchar).
A conversion like this is expensive.
If you use pstmt.setBytes(1, "99".getBytes("8859_1")); in your Java code, then JTurbo inserts the parameter and builds the query like this:
... where mytext = 0x3939
which does not require a type conversion within SQL Server.
The only way that JTurbo's PreparedStatement could avoid prepending the 'N'
would be if it were to first ask SQL Server whether or not the
column type was nchar, nvarchar, or ntext.
Asking this for every sql query it builds could be very expensive.

Our recommendation is that you change your database column type to be one of the 'n' types:

When I retrieve a timestamp that includes milliseconds, why does JTurbo round the milliseconds instead of returning the timestamp that is stored?

Answer

JTurbo is not rounding the milliseconds. The variations in the timestamp's milliseconds is a communications issue between sql and java.

Miscellaneous

Faq ID

75

Product

JTurbo

Category

Miscellaneous

Question

Can I use JTurbo in an IDE or Application Server?

Answer

Yes, JTurbo is known to work with the following IDEs: Metrowerks and Eclipse. JTurbo is also known to work with the following applications servers: WebSphere, WebLogic, ServletExec, JRun and Apache Tomcat.
Visit our Using JTurbo with Third Party Application Servers page for more details.

Faq ID

73

Product

JTurbo

Category

Miscellaneous

Question

How can I access SQL Server from UNIX, Macintosh and LINUX platforms using JTurbo?

Answer

Microsoft SQL Server runs only on Windows NT/2000, with no support for other platforms. JTurbo solves the problem of accessing MS SQL Server from any machine and any platform. If you are able to ping the NT machine from the UNIX, Macintosh or LINUX machine, then you can use JTurbo to connect to the SQL Server running on the NT Machine. All that is needed is to configure the URL passed to DriverManger.getConnection() to point to the NT Machine and the port on which SQL Server is listening.

Faq ID

228

Product

JTurbo

Category

Miscellaneous

Question

How can I obtain and apply existing JTurbo patches ?

Answer

JTurbo patches are freely downloadable via anonymous FTP from the New Atlanta FTP Server:
ftp.newatlanta.com
An FTP client could be used to access this server, or in some cases a web browser can be used. Your ability to access this server using a web browser may depend on whether or not you are behind a firewall and/or how your network is setup (setting the browser to allow passive FTP transfers may help in some cases).
However you choose to access this FTP Server, once there you should browse to the:
/public/jturbo/<version #>/patch/ folder.
So for example, since JTurbo 3.0.2 does have a patch available, it would be obtained from:
ftp://ftp.newatlanta.com/public/jturbo/3.0.2/patch/
The patch folder contains a ReadMe.txt which you should read in order to learn which bugs the patch fixes.
Within the patch folder are subfolders for each JDBC version.
Obtain the appropriate JTurbo.jar for the JTurbo JDBC version that you currently have installed.
Follow the instructions given in the ReadMe.txt to apply the patch.

Note that in the case of JT 3.0.2, there is actually an even newer patch available on the FTP server under the 3.1 folder.
3.1 is a version of JTurbo that was never released publicly.
Here is the story behind that:
Back when 3.0.2 was the current version, it was thought that the next version after that would be called "3.1". During the time that development work was being done on 3.1 (new features mostly) there was at least 1 customer who needed one of those new features right away. So we made it available on our FTP site as a patch for "3.1"... which basically turns your 3.0.2 into 3.1 with the new features that had been added up that point (listed in the 3.1 patch ReadMe.txt file).
At some point after that, it was decided that the next version of JTurbo would be called "JTurbo 2005" (to match SqlServer 2005). And so the remainder of the JTurbo development for that release cycle was done under the "2005" designation. JTurbo 2005 has since been released and is currently the only version of JTurbo that can be downloaded or purchased from the New Atlanta website.

Faq ID

145

Product

JTurbo, ServletExec

Category

Miscellaneous

Question

I sent an email to New Atlanta Support but my email bounced back, or I was told that the email I sent to was incorrect. Why ?

Answer

If you mean that you received an email from autoreply@newatlanta.com then:

New Atlanta has received your email. It did not bounce back.

New Atlanta intends to help you. You have not sent your email to the wrong place.

It just means that the email account that you used to send your question is not named as a technical contact on a valid support contract. We will still help you, just not as quickly as we help those who are named as a technical contact on a valid support contract.

When this occurs, please do not resend your question to New Atlanta. We have received your question and will respond to it. Resending causes delays and confusion.
This is also referred to as an "autoreply".

Faq ID

77

Product

JTurbo

Category

Miscellaneous

Question

What is the format of the JTurbo URL and what are the optional flags available on the URL?

Answer

The syntax for the JTurbo URL is:
jdbc:JTurbo://<server>:<port>/<database>/<property1=value1>/<property2=value2>...
The properties in the JTurbo URL are case-sensitive.
See the JTurbo User Guide for a complete list of properties.

PreparedStatement

Faq ID

155

Product

JTurbo

Category

PreparedStatement

Question

I can't seem to get Batch Updates to work correctly, what is wrong?

Answer

When this problem occurs, only the query that was last added to the batch is executed. And that query is executed once for every time that addBatch() was called. If the query involves inserting a record that has a unique primary key, SQLExceptions can be thrown from trying to insert duplicate ids.
This problem has been fixed in JTurbo 3.0, so feel free to download JTurbo 3.0.

ResultSet

Faq ID

131

Product

JTurbo

Category

ResultSet

Question

I am trying to use JTurbo JDBC Driver to select a column whose SQL Data Type is uniqueidentifier but the value I get when I call getString() on the ResultSet is not correct. What is wrong?

Then the problem is that you need to set the sql70 option flag to true in your JDBC URL

If your java code is instead getting something like:
78bef5d8-1fb0-4223-89bf-c153bd7122fc
(i.e. missing the leading and trailing curly braces, and all lower case)
Then this was a bug in JTurbo and it was fixed in JTurbo 3.0b2

Statement

Faq ID

154

Product

JTurbo

Category

Statement

Question

I got a Statement from a Connection object and then called setMaxRows() on the Statement Object. It works fine, but now every Statement I get from that same Connection Object has the same max row setting so my ResultSets are missing some rows. What is wrong ?

Answer

This problem was fixed in all versions of JTurbo 3.x.
When you call setMaxRows(n) on a Statement Object, JTurbo was sending the following message to SQL Server:
set rowcount n
This causes SQL Server to only return n rows for all queries made using that same Connection
[thus reducing network traffic which is the main idea behind using setMaxRows() in the first place ].
There are a few workarounds to this problem.

Get JTurbo 3.x or newer which corrects this problem

Do not call setMaxRows.
Instead modify your query so that it uses the TOP command like this:
Select top 200 * from myTable

After you call setMaxRows(n), and after you get back the limited ResultSet that you need,
but before you call stmt.close(),
call setMaxRows(0) to set the Statement (and thus the underlying Connection)
back to an unlimited number of rows.

Note: workaround #2 is especially important if you are using Connection Pooling.

Yes, if you are using JTurbo 3.0.2 or greater.
With DBCC commands that return a result set or update count,
they should work just like any other SQL statement.
With DBCC commands that return a message, the following code
can be used to retrieve the message:

Note, that this code won't work with JTurbo 3.0.1
due to bug #586 (which was fixed in JTurbo 3.0.2)

Faq ID

79

Product

JTurbo

Category

Supported Features

Question

Does JTurbo support National Characters like nchar, nvarchar and ntext?

Answer

Yes, JTurbo supports National Characters. With JTurbo 3.0 and earlier, you need to set sql70=true to enable this feature.

Faq ID

72

Product

JTurbo

Category

Supported Features

Question

Does JTurbo support SQL Server 6.5, 7.0, 2000 and 2005?

Answer

JTurbo 3.0 and earlier support SQL Server 6.5, 7.0 and 2000 through the use of the flag sql70 in the JTurbo JDBC URL. This flag should be set to false for SQL server 6.5 and true for SQL server 7.0 and 2000. JTurbo 2005 only supports SQL Server 2000 and 2005.

Faq ID

160

Product

JTurbo

Category

Supported Features

Question

Does JTurbo support the BLOB and CLOB datatypes ?

Answer

Yes. The versions of JTurbo that support these are:

JTurbo 2005 for JDBC 2.1

JTurbo 2005 for JDBC 3.0

JTurbo 3.0 for JDBC 2.1

JTurbo 3.0 for JDBC 3.0

MS SQL Server does not actually have this data type, so JTurbo supports this by doing type conversions. For example you can call:
ResultSet.getBlob(1)
and if column #1 is of type binary, varbinary, or image, then JTurbo will put that binary data into a java.sql.Blob object and return it to you.

Faq ID

80

Product

JTurbo

Category

Supported Features

Question

What about support for other languages and character sets?

Answer

JTurbo supports all languages and character sets that are supported by SQL Server. You can set the desired language and charset parameter through use of the JTurbo URL. For Example the corresponding flags are language=us_english and charset=Cp850.

System Requirements

Faq ID

156

Product

JTurbo

Category

System Requirements

Question

Are JDBC Driver connections limited by the number of CALs on the SQL Server ?

Answer

CAL stands for Client Access License.
As far as we know, Microsoft offers 2 different licensing schemes for SQL Server.
The first they refer to as "processor" licensing.
More can be read about it here:
http://www.microsoft.com/sql/howtobuy/processor.asp
The second they refer to as "CAL" licensing.
More can be read about it here:http://www.microsoft.com/sql/howtobuy/servercal.asp
We cannot speak for Microsoft's position on these various licensing choices, and we do not know in what way (if at all) they enforce CAL licensing.
That would be more a question for Microsoft.
We can say that if you have SQL Server on machine A, and you have your code that uses JTurbo on machine B then machine B is 1 client. So, if using the CAL licensing scheme you would need to purchase at least 1 CAL (for machine B). You could then use JTurbo on machine B to make any number of JDBC Connections to the SQL Server on machine A that you wish.

Transactions

Faq ID

134

Product

JTurbo

Category

Transactions

Question

Does JTurbo support transactions via JTA and JTS?

Answer

In short, yes.
Here is a little more detail:

All versions of JTurbo support the standard, non-distributed kind of transactions that are accomplished by using:
java.sql.Connection.setAutoCommit(false)
and then calling rollback() or commit().

The JDBC 3.0 API is included in J2SE 1.4.
The JDBC 3.0 API adds the setSavepoint() method to the java.sql.Connection Interface.
JTurbo 3.0 and greater supports the JDBC 3.0 specification and so supports the setSavePoint method when used with JVM 1.4 or higher.
The setSavepoint method is another way to accomplish JDBC transactions.The above-mentioned techniques do not involve JTA or JTS.

The JDBC 3.0 Specification also describes support for Distributed Transactions. JTurbo 3.0 supports these because it implements the following interfaces:
javax.sql.XADataSource
javax.sql.XAConnection
javax.transaction.xa.XAResource

In chapter 12 of the JDBC 3.0 Specification entitled:
"Distributed Transactions"
It states:
Transaction management in the JDBC API is designed to fit with the Java Transaction
API TM (JTA TM )
Sun describes JTA using the following language:
JTA specifies standard JavaTM interfaces between a transaction manager and the parties involved in a distributed transaction system: the resource manager, the application server, and the transactional applications.
Sun describes JTS using the following language:
JavaTM Transaction Service (JTS) specifies the implementation of a Transaction Manager which supports the JavaTM Transaction API (JTA)

Version differences

Faq ID

106

Product

JTurbo

Category

Version differences

Question

How can I find out which version of JTurbo I am using and whether or not it is a trial version, an evaluation version, or a fully licensed version?

Answer

For JTurbo 3.x and newer:

It is very easy to tell which version your JTurbo.jar is and whether or not it is a fully-licensed version or one that will timeout.
The JTurbo.jar files for JTurbo 3.0 contain a text file named:
Version.txt which states the exact version of the product.
You can learn whether or not it is a fully licensed one by enabling debug messages on the driver in your code like this:DriverManager.setLogWriter(new PrintWriter(System.out));
The output will state whether or not your JTurbo.jar is fully-licensed.
JTurbo 3.0 will not use the sub-versioning like JTurbo 2.0E and older did, incremental versions of JTurbo will be the more standard:
3.0.1, 3.1 3.2, 4.0, etc...

For JTurbo 1.22, 2.0, and 2.0 Enterprise:

The JTurbo.jar files themselves do not contain any distinct characteristics that would allow a person to examine them and tell the difference. To further compound this problem, each of these versions had various sub-versions that were released.
Here is an example using JTurbo 2.0:
When JTurbo 2.0 came out, each time a bug-fixed version was created it was distributed as JTurbo 2.0 (using a JAR file named JTurbo.jar, just as before).
But this time the bug-fixed JTurbo.jar had a new sub-version.
When customers downloaded any evaluation version of JTurbo it was delivered in the form of a ZIP file. That ZIP file contained JTurbo.jar as well as examples and documentation, and a ReadMe.txt file.
The first line in the ReadMe.txt file would state the sub-version.

The most updated sub-versions are as follows:
JTurbo 1.22 version 5.2
JTurbo 2.0 version 2.4
JTurbo 2.0 Enterprise version 1.9

If you still have the original ZIP you downloaded (from which you extracted the JTurbo.jar file you are trying to examine), then you can look in the ReadMe.txt file to see if you have an older sub-version. If you find that you do have an older sub-version and for some reason you cannot use your free upgrade to JTurbo 3.0, then you should download the most current sub-version from the NewAtlanta website. The easiest way to do this is to login using the email address of the original purchaser and you will be able to download a fully licensed JTurbo.jar which will be the most current sub-version for that version of JTurbo. You would do this directly from the "Account Management" page (no ZIP file).

Faq ID

70

Product

JTurbo

Category

Version differences

Question

What is the difference between the JTurbo Trial Version, Evaluation Version, Development Version, and Deployment/Production Version?

Answer

The Trial version of JTurbo is what you download for free. When you run the JTurbo installer you type in the word "trial" as the license key. The installer then installs the trial version of JTurbo which is limited to 5 concurrent connections, and will timeout after 30 days.

The Evaluation version will still timeout after 30 days, but has no concurrent connection limitation. This makes the Evaluation version suitable for use in stress testing or "real load" evaluations prior to making a purchase decision.
To install it, you would re-run the JTurbo installer that you downloaded for free only this time instead of typing the word "trial" as your license key, you would paste in an evaluation license key that you requested from sales@newatlanta.com.

The Development version of JTurbo never times out and has no concurrent connection limitation. It is licensed for use in development. To install it, you need only purchase a JTurbo development license key and then rerun the JTurbo installer this time pasting in the license key you purchased

The Deployment/Production version of JTurbo never times out and has no concurrent connection limitation. It is licensed for use in production. To install it, you need only purchase a JTurbo deployment license key and then rerun the JTurbo installer, this time pasting in the license key you purchased.

NOTE:
You can upgrade a trial or evaluation version to a development or deployment/production version at any time by purchasing a license.
Please refer to the JTurbo Purchase page for pricing and licensing information.

ServletExec

Admin Console

Faq ID

347

Product

ServletExec

Category

Admin Console, Known Limitations and Workarounds

Question

Does ServletExec 5 support IPv6?

Answer

Not completely. This has been entered into the SE bug tracking database as bug #2714.
IPv6 is enabled by default in both Vista and Longhorn.
Evidence for this is seen in the
C:\Windows\System 32\drivers\etc\hosts file.
You will see an entry of ::1 which resolves to localhost.
You can request http://localhost/servlet/TestServlet to see the value
that's returned by request.getRemoteAddr().
You'll see that that servlet runs just fine.
You'll see that the value for the remoteAddr is displayed in IPv6 format 0:0:0:0:0:0:0:1
If you were to request the SE Admin UI instead, here is what happens:
The SE admin UI compares the remoteAddr value (which is the IP of client/browser) to the configured allowedIPs value to decide if the client should be allowed to access the SE admin UI.
The algorithm that the SE 5 admin UI uses to ensure that remoteAddr meets the
"Allowed IPs" setting is not equipped to handle IPv6 addresses.
So it ends up deciding that the client should not be allowed to login to the admin UI.

One workaround is to use some other hostname besides localhost when accessing the SE admin UI.
For example, 127.0.0.1 will work.
Another workaround is to edit the hosts file, to remove or comment out the ::1 entry. Then localhost would work (after a browser restart).

Another issue that can occur when SE 5 is being used in an IPv6-enabled environment is
that SE's implementation of Request.getRemoteHost() returns an invalid value.

Summary
A servlet or JSP which runs, and does not need those values (the remoteAddr or the remoteHost)
should continue to run just fine.
Even if the client is on an IPv6 machine.
It depends on what you are requesting... whether or not it needs those values to be correct.

Note: SE 6 does support IPv6 completely

Admin Username and Password

Faq ID

114

Product

ServletExec

Category

Admin Username and Password, Administration, Security

Question

How can I restrict access to the main ServletExec Admin UI ?

Answer

With SE 5.x & newer:

The admin UI is deployed as a standard web application (WEB-INF folder, web.xml file). Therefore the available options for restricting access to it include all the declarative security features mandated by the Java Servlet specification. These currently include Form-based authentication (which is the default for that webapp), BASIC authentication, and Client-Cert (SSL) authentication. See the SE User Guide and the Java Servlet Spec for more information about Declarative Security in webapps.

Each page in the SE admin UI (and a webapp's admin UI) uses a unique URL, so you can restrict access to certain admin pages, while leaving other pages less restricted, or totally unrestricted. All without having to write any code (i.e. declaritively)

By default the servletexec webapp defines a Security Constraint named "EntireApplication" which is configured to use Form-based authentication, and to which the following prefix alias patterns are mapped:
"/admin/*"
"/webadmin/*"
But you could modify that security constraint, and/or map different aliases to it. Or you could use the admin UI to add another security constraint, just as you could do for any webapp.

You could also write your own custom authentication filter and deploy it into the servletexec Admin UI webapp, mapping various URL patterns to it. The exampleWebApp that comes with SE shows how a request filter can be used to do BASIC authentication. If you want to do BASIC auth you should just configure the existing Auth Constraint in the servletexec webapp to use BASIC instead of Form-based auth. But the filter example in exampleWebApp is a good place to learn how to write your own filter which could do its own custom authentication however you want it to (i.e. look in your database for usernames, passwords etc...)

With SE 4.x or older:

Your options include:

setting a username & password

restricting which client IP addresses will be allowed

requiring that SSL (https) be used

any combination of the 3 options given above

Note: Don't require SSL unless your webserver actually supports SSL

Restrictions on accessing the main ServletExec Admin UI can only be set if ServletExec 4.x or older has been registered with a license key.
Once this has been done, simply access:
http://<host-name>/servlet/admin
And then go to the page where you entered your license key (the "license & security" page) of the main ServletExec Admin UI.
There you will see text areas and radio buttons where you can:
enter a username (and possibly a password), edit the allowed IP's field, or choose to require SSL.
Note: With ServletExec ISAPI, there will not be a password field.
In this case, the username you enter must be that of a valid Windows user on the machine which SE ISAPI is running. The password used will be the password that is associated with that Windows user.

I used the ServletExec Admin UI to make some configurations but after I restart ServletExec, the settings I entered are gone. What is wrong? Is this normal behavior?

Answer

This FAQ only applies to SE ISAPI. If you are using SE AS this FAQ does NOT apply.

It is not considered normal behavior for ServletExec to forget any of its configuration data (such as License Key, or Session settings, or Configured Servlet settings, etc...) after a restart.
When you enter a setting via the ServletExec Admin UI, and then click the appropriate Submit button, ServletExec attempts to write that information into the appropriate configuration file. For example, when you enter your license key and then click the Register button, SE tries to write that info to:...\ServletExec Data\servletexec.xml (for SE 5.0 and newer)...\ServletExec Data\servers.properties (for SE 4.x and older)
so that the next time ServletExec starts up it can read that info back in from the file and use it. If your instance of ServletExec is forgetting its settings after a restart, most likely this is a file permissions issue in which ServletExec does not have access to write to the appropriate file.
Another indication of this sort of problem would be if you were to enter your license key (or any other configuration change via the ServletExec Admin UI) and then click the appropriate submit button, and saw in your browser a message sort of like this:

When a problem like this occurs most likely you will find IOExceptions in ServletExec.log, and "access is denied" messages. You would also see these messages in DBMON if running ISAPI or NSAPI on windows. This normally happens when ServletExec doesn't have read/write access to the ServletExec Data directory and all of its subdirectories and subcontents. Make sure that ServletExec has permission to read/write to this directory and all of its subdirectories and subcontents.
This problem commonly occurs with SE ISAPI on Windows due to the fact that SE ISAPI runs inside the IIS process and the IIS process runs as different users at different times.

A very quick way to test if this is in fact a file permissions problem is to give the group named
Everyone, Full Control over the ServletExec ISAPI directory and all of its subdirectories and subcontents.
Here is how you do that:

Right click on the appropriate folder

select Properties, and choose the Security tab

Select the group named 'Everyone' (add that group if it is not listed) and then give it Full Control permission (check the checkbox labeled "Full Control")

Click the 'Apply' button

Click the 'Advanced...' button

Select the group named 'Everyone'

Check the radio button that is labeled "Reset permissions on all child objects and enable propagation of inheritable permissions."

Click the 'Apply' button so that the new permission settings will propagate downward

If this solves the problem then you will know if was a file permissions issue. At that time you may go back and use more fine-grained security settings if you wish.
With IIS you would need to make sure that the following user accounts have read/write access to this directory and all of its subdirectories and subcontents:

Beginning with IIS 6 on Windows 2003:

The user specified as the application pool identity for ServletExec. Typically this is the user named "Network Service".
See SE FAQ #7 (step #6) for more information about which user we're talking about)

The ServletExec Admin User Account (SE 4.x and older only)

With versions of IIS, prior to IIS 6:

SYSTEM

IUSR_<server name>

The ServletExec Admin User Account (SE 4.x and older only)

Section 2.7 of the ServletExec Installation Guides for SE 4.1, 4.1.1, 4.2, & 5.0, all discuss this in greater detail.

If this does not work then try setting these permissions on the top level JVM folder and all of its subfolders and subcontents.

Faq ID

1

Product

ServletExec

Category

Admin Username and Password

Question

I've forgotten my admin username and password. How can I reset them?

Answer

If you are using SE 5.x or newer:
The username and password for the servletexec admin webapp were entered during the installation process (the installer asks you for them). So the values should be whatever was entered by the person who peformed the installation.
To learn the username and to clear the password so that you can access the servletexec admin webapp, peform the following steps:

Stop ServletExec using the StopServletExec.bat/.sh file.

Open ...\ServletExecData\security.xml in a plain text editor and locate:

Where <username> will be the username, and <encrypted-password> is the encrypted password. Remove the:
<password>...</password>
node from the file, save the change, and then restart SE. You should then be able to access the ServletExec admin webapp using only the username (no password).
Once you are in, you can then use the admin UI to set a password for that user.

If you are using SE 4.x or older:
You can do this by renaming the servers.properties file which resides in the ServletExec Data directory (you'd rename it to a "Backup" name such as servers.properties.BACKUP for example) and then re-initializing ServletExec (which will cause a new servers.properties file to be created by SE). This file also contains your license key and virtual server configuration data, so you will need to re-enter this data after re-initializing ServletExec.

Note: In either case, the password should consist only of alphanumeric characters (i.e. letters and numbers). Do not use other characters such as underscores, dots, exclamation points, at-symbols, etc. since those characters are not covered by SE's encryption/decryption algorithm. Using them will cause you to receive "Invalid username or password" errors when attempting to login to the Admin UI.

Note: In 1 case the above solutions did not work for a customer. The reason was that they had a setting enabled in their Internet Explorer browser that was causing the browser to NOT send any request parameters to the server. This was causing the j_username and j_password request parameters to NOT be sent to SE when posting the login form and so SE could not authenticate the user. To confirm whether or not this is what's occuring in your case, stop SE and view the ServletExec.log file using a plain text editor. If this is the issue you would see an Error message there stating that the j_security_check request lacked the j_username and j_password parameters. The setting in IE was tools - internet options - content tab - Content Advisor.
The customer's content advisor was enabled. They disabled it, restarted IE and the problem went away.

Faq ID

180

Product

ServletExec

Category

Admin Username and Password

Question

When SE 4.x is used with IIS... Why must the SE Admin User be defined on the machine ? And why must the SE ISAPI filter be configured to use Basic Authentication, why can't it use Integrated Windows Authentication (IWA/NTLM) ?

Answer

Because when IIS recieves a request that has a Username and Password in the Request Header it will first look to make sure that the provided username is that of a valid Windows User on the System and that the provided Password is correct for that Windows User. If so, only then will IIS pass the request on to ServletExec. IIS always behaves this way, regardless of which SE configuration is being used with it (ISAPI or AS).
So this is an extra check that IIS is doing, not ServletExec

Because once the request is passed on to ServletExec, SE will attempt to decrypt the username and password and use it to Authenticate the user.
In the case of SE ISAPI, the username is compared with the configured SE admin username and then some ISAPI callbacks are made to Authenticate the user.
In the case of SE AS, the username and password are compared with the configured SE admin username and password. No ISAPI callbacks are made for this step with SE AS.
In either case, the username and password must have been encrypted using Base64 encoding because that's what SE expects and knows how to decrypt
Since the encryption used by IWA is proprietary to Microsoft, ServletExec has no way to decrypt it. In addition, the password is not available to SE when iWA is used (it's not transmitted).

NOTE:
It IS possible to configure IIS so that ONLY SE ISAPI uses BASIC Authentication, while the rest of your IIS website uses NTLM Authentication.
Just enable NTLM at the global or website level and then access the "Authentication Methods" dialog box for the ServletExec_ISAPI.dll or ServletExec_Adapter.dll file itself, and turn off NTLM at that level. This would be done by viewing the contents of the Virtual folder named "Scripts" (done in IIS not on the hard-drive) and opening the properties dialog of the ServletExec_ISAPI.dll file shown there in the IIS Management console. See FAQ #65 for a few more details.
NOTE:
This is not required for the SE Admin UI used by SE 5.x or higher since with those versions of SE, the SE Admin username and password are not transmitted using BASIC authentication. Form-based declarative security is used by the SE Admin UI instead.
NOTE:
If your webapp uses BASIC authentication & you are using IIS as your web server software, then it does not matter what version of SE you are using. Even with SE 5.x or 6.x, the following would still be true:
Any Container Users (defined on the SE Admin UI) which may gain access to your webapp, must be valid Windows users defined in the Windows OS. And the passwords defined for those Container Users (on the main SE Admin UI) must match the passwords defined in the Operating System for their respective Windows users.

Faq ID

65

Product

ServletExec

Category

Admin Username and Password

Question

With IIS, why does ServletExec keep rejecting my admin username and password when I try to access the admin pages?

Answer

This FAQ applies to a common issue that is often seen with versions of SE prior to 5.0 (i.e. SE 3.x, SE 4.x), and then only when IIS is used as the webserver.
NOTE: If you are using SE 5.x or newer, you won't likely run into this problem at all, and won't likely need to perform the steps given in this FAQ, since those versions of SE use form-based authentication rather than BASIC authentication for password protecting access to the SE admin UI.

First make sure Basic Authentication is enabled as described in Chapter 2 of the ServletExec Installation Guide.
If the username/password dialog box at the browser mentions ServletExec then it is ServletExec that doesn't like the username/password. Otherwise it is Windows NT that doesn't like the username/password. In the latter case make sure the username/password you specified is a valid Windows NT user in the local domain.

If you need to specify a user in a network domain then configure IIS basic authentication to use that network domain instead of the local domain. This can be done by going to the "Authentication Methods" dialog as described in Chapter 2 of the ServletExec Installation Guide and then selecting Edit.

If you have made certain that your website has Basic Authentication enabled (as shown in fig. 6 of Chp.2 of the ServletExec 4.1 Installation Guide), and yet the authentication dialog that is popping up in Internet Explorer browser has a 3rd field labeled "Domain" and does not have the word "ServletExec" anywhere on it,
then you need to disable (uncheck) one of the check boxes shown in that figure.
The checkbox that you must uncheck is called:

NT Challenge Response (for Windows NT)

Integrated Windows Authentication - IWA (for Windows 2000 and above)

This setting is also sometimes referred to as NTLM
Then close all IE browser windows, get a fresh browser window and try to hit http://<servername>/servlet/admin again.
This time the pop-up authentication dialog should only have 2 text areas: one for username, and one for password.
And it should have the words "Realm: ServletExec Admin" somewhere on it. Then it should accept your username and password.

SPECIAL NOTE:
The "Authentication Methods" dialog box for IIS exists at a few different levels...

The Global/Master level, to set Authentication methods for all websites

The website level, to set them differently for each individual IIS website

The DLL level, to set them differently for each individual ISAPI filter

If you do not want NTLM Authentication to be disabled at the global or website level then you may choose to Enable it at either of those levels and then access the "Authentication Methods" dialog box for the ServletExec_ISAPI.dll or ServletExec_Adapter.dll file itself, and turn off NTLM at that level. This would be done by viewing the contents of the Virtual folder named "Scripts" (done in IIS not on the hard-drive) and opening the properties dialog of the ServletExec_ISAPI.dll or ServletExec_Adapter.dll file shown there in the IIS Management console. See FAQ #180 for a few more details.

How can I know with which brand and version of JVM I am running ServletExec ?

Answer

This information can be found on the Virtual Machine - Settings page of the Main ServletExec Admin UI.

Another way to determine this would be to write Servlet or JSP code which outputs the value of:
System.getProperty("java.vm.vendor");
and
System.getProperty("java.vm.version");
And then request that Servlet or JSP to read the output in your browser.
NOTE: If using SE 5.x or higher then this is already done for you... just access the System Properties page of the Main SE Admin UI.

If you are running ServletExec out-of-process (SE AS), you could also look inside your StartServletExec script/batch file to see which version of JVM that script is configured to use.

Faq ID

150

Product

ServletExec

Category

Administration

Question

I am seeing "java.lang.IllegalStateException: the session has been invalidated" in my ServletExec.log file. Why ?

Answer

Most likely you are calling session.invalidate() somewhere in your code.
If you do this and then try to use that invalidated
session object, you can expect java.lang.IllegalStateException to be thrown.
(see the java docs for javax.servlet.http.HttpSession).
ServletExec has a thread that runs in the background which periodically examines all the session objects, calling invalidate() on those that have expired.
Consider removing any calls to session.invalidate() in your code, and allowing SE to manage your sessions
automatically, or perhaps wrapping all such calls in a try-catch block.

If you are not calling session.invalidate() anywhere in your code then this would not be the problem.
In which case we can only say that somehow your session data has gotten into an inconsistent state.
To fix it do this:

stop ServletExec

delete the appropriate sessionSwap folder

start ServletExec

Faq ID

405

Product

ServletExec

Category

Administration, Known Limitations and Workarounds, Miscellaneous

Question

I'm having problems stopping the ServletExec AS 6.0 service on Windows 2008 R2. What could be the problem?

Answer

Most likely you are running into a problem that occurs on certain Windows 2008 R2 machines. You can find the fix with a ReadMe.txt that explains how to install it at:

When I start a ServletExec AS Instance, I get "java.net.BindException: socket already in use". What is wrong?

Answer

An SE AS instance listens on a port. Typcially this is port 8888. It sounds like ServletExec (or something else) is already running and using that port.

If you previously attempted to stop ServletExec, perhaps ServletExec didn't actually stop. Some possible reasons for this include:

No matter which version of SE AS you are using, the most common cause for this is that the StopServletExec batch/script is not configured to use the correct port. So it's not sending the stop message to the port that the SE AS Instance is using. So your instance never receives the stop command. So it just stays up and running. If you then try to start it again, you can expect this Exception. The Windows OS can make this issue harder to detect due to the following facts:

When you start or stop an SE AS Service via the Windows Services Dialog, the Windows Service mechanism simply calls StartServletExec.bat or StopServletExec.bat under the covers, and then says "OK, I'm done... I've called the appropriate batch file... so I'll now report that that service is started or stopped without actually checking if that's truly the case."
If either of those scripts fails to do it's job correctly, then the Windows Services dialog will be lying to you... telling you that the service is stopped when really it's not (or vice-versa).
The Task Manager might be used to confirm this (use it to see if java.exe is still running) of course if you have more than 1 java.exe going on your machine that's not too helpful. You could use your browser to try to request something from SE to confirm whether SE is truly up or truly down.

If you suspect that your StopServletExec script might not be using the correct port, then you could try confirming it by doing this:
Open a DOS command window and cd down to the folder that contains the StopServletExec script for you ASI. Then invoke that script by typing it with the keyboard >StopServletExec.bat
If an error occurs, then you'll see it there in the DOS window.
If you need to configure the stop script to use the correct port then use the -port option (see the SE User Guide for more details about that and other options available in that script).

SE FAQ #186 has a NOTE that gives other scenarios of the Windows Services Dialog lying to you.

If using SE 4.2 or older, perhaps you have entered a username and password for the ServletExec Admin and you didn't edit your StopServletExec batch/script to reflect this information. You will need to specify the username/password in the StopServletExec batch/script file by using:
-admin <username/password>.

Only then will StopServletExec actually stop ServletExec, thus allowing StartServletExec to start it again without issue.
Note: The -admin option is only used with versions of SE AS prior to SE AS 5.0.
For more information about that option, look in the SE AS chapter (for your operating system) in the appropriate SE Installation Guide.
Specifically the section that discusses "StopServletExec".
For example (for Unix) in the SE 4.1.1 Installation Guide, that is table #10 of section 6.6.2.2.
Here are more examples:

For SE AS 4.2 on Windows, look at table #7 in the SE 4.2 Installation Guide, section 5.6.2.1.

For SE AS 4.2 on Unix, look at table #10 in the SE 4.2 Installation Guide, section 6.6.2.1.

But since the ArcIMS Post Installer that comes with ArcIMS 9.x was not designed to run against SE AS with IIS, it does a couple of things wrong. It is very easy to work around this as described below:

There are 2 possible paths for working around this issue:

Perform a simple work around before the ArcIMS Post Installer is run against a new SE AS installation.

-OR-

Perform a slightly more involved (yet straightforward) workaround after the ArcIMS Post Installer has been run against a new SE AS installation.

These manual steps are only needed for SE AS on Windows (not SE AS on Unix).

Option #1 above is simpler than option #2. But regardless of which option you choose, the first few steps are always the same:

Install webserver, & create a simple helloWorld.html and make sure you can request it and it is served properly.
Make sure your can turn it off and back on and that it still works.
In other words, make sure your webserver works before you start to put things "on top" of it.

Install the JDK/SDK.

Install SE 6.0 AS or 5.0.0.13 AS (not 5.0 AS) and make sure it works (/servletexec/admin, /servlet/TestServlet)

turn off the SE AS Instance (ASI)

At this point you must choose an option. Below are steps for performing either option.

Run the ArcIMS Post Installer (see step #1 under Option #2 below).
When it prompts you to supply the "Servlet Engine Directory" point to the se-<instanceName> folder. For example:
C:\Program Files\New Atlanta\ServletExec AS\se-<instanceName>\

After the Post Installer completes, restore the name
of the folder by removing the space you added in step #1 above.
So that you once again have (for example):
C:\Program Files\New Atlanta\ServletExec AS\se-<instanceName>\ServletExecData

Option #2

Run the ArcIMS Post-Installer (this is automatically kicked off at the end of
the ArcIMS installation process, or if ArcIMS
is already installed, you would use Start - Programs - ArcGIS - ArcIMS - Post Installer, to start it.
Follow the wizard to get the ArcIMS Connector Servlet "hooked into" SE and here are some more tips about this:

when it prompts you to supply the "Servlet Engine Directory" point to the folder where your SE AS instance resides (for example):
C:\Program Files\New Atlanta\ServletExec AS\se-<InstanceName>\

when the post installer is done, go look inside the
C:\Program Files\New Atlanta\ServletExec AS\se-<instanceName> folder and notice that you have 2 folders in there with very similar names.
You have one named "ServletExecData" (no space), and you have one named "ServletExec Data" (with a space). The Post Installer
incorrectly created the one with the space.

move what's inside the "ServletExec Data" folder over to the "ServletExecData" folder instead.

delete the (now empty) "ServletExec Data" folder (i.e. the one with the embedded space).

Regardless of which option you used, the last few steps are always the same:

Start your ASI (i.e. your SE AS Instance).

Make sure that you can still successfully request helloWorld.html, /servletexec/admin & /servlet/TestServlet
In other words, make sure that nothing got broken.

Use the ArcIMS diagnostics to test that the ArcIMS Servlet Connector is properly hooked into SE (diagnostic test #1) and also
that the ArcIMS Servlet Connector can properly communicate with the ArcIMS spatial server (diagnostic test #2).
The ArcIMS diagnostics are access via:
Start - Programs - ArcGIS - ArcIMS - ArcIMS Diagnostics

You see... the ArcIMS Post Installer was not designed to be used with SE AS with IIS, so it does a couple of things wrong.
Those things are very easily fixed by just moving a few things around as described above.

Faq ID

362

Product

ServletExec

Category

ArcIMS Users, System Requirements

Question

Can I use ServletExec with ArcIMS on Windows Vista or Windows 2008?

Answer

Yes, but there are some caveats you must understand first:

The first version of ServletExec to support Vista/2008 is SE 6.0.
Versions of SE prior to 6.0 are not supported on Vista/2008.

The first version of ArcIMS to support ServletExec 6.0, and to support Vista/2008 will be
ArcIMS 9.3 (not yet available at the time of this writing).

ArcIMS "hooks into" ServletExec via the ArcIMS Servlet Connector (a Servlet and set of supporting code & resources
that ESRI wrote). Any servlet that runs on SE 5.x should run perfectly fine on SE 6.x. So technically... an ArcIMS
Servlet Connector that runs fine on SE 5.x should also run fine on SE 6.x. However, ESRI may not officially support
that unless the ArcIMS Servlet Connector you are running on SE 6.x is the one that came from ArcIMS 9.3. You'd need to check with ESRI about that.

Faq ID

210

Product

ServletExec

Category

ArcIMS Users

Question

Can SE 5.x be used with ArcIMS 4.0.1 ?

Answer

At the time of this writing, ESRI has not "certified" the use of SE 5.x with ArcIMS 4.0.1. So if you are using ArcIMS 4.0.1 and you wish to use a version of ServletExec which ESRI officially certifies, then you should use SE 4.2 or SE 4.1.1. (NOTE: SE 5.0 will be offically certified by ESRI for use with ArcIMS 9.0)
However, if you choose to use SE 5.x ISAPI or NSAPI (in-process),
it is very likely that it would work just fine for you with ArcIMS 4.0.1. The ArcIMS Servlet Connector is the ESRI component which runs inside of ServletExec and which "connects" SE to ArcIMS. The ArcIMS Servlet Connector is basically just a servlet. Any servlet that runs inside of SE 4.x should run just fine inside of SE 5.x.
The biggest concern is if you wish to use ServletExec 5.x AS (out-of-process) instead of ISAPI or NSAPI (in-process).
If you do choose to try this combination, then the ArcIMS Servlet Connector should still work just fine, but you should not run the ArcIMS 4.0.1 Post Installer to set it up for you. This is because that version of the Post Installer was designed to run against SE 4.x and it will try to edit your web server's configuration files for you (servletexec.properties, obj.conf, httpd.conf), and the edits won't be correct for SE 5.x. Instead you should manually setup your ArcIMS Servlet Connector for use by SE 5.x.

Faq ID

243

Product

ServletExec

Category

ArcIMS Users, Security

Question

How can I "lock-down" ServletExec AS to ensure that it is not accessed or administered by unauthorized means or users ?

Answer

Here is listing of some possible ways to do this:

Password protect access to the SE Admin pages.
This way, anonymous users won't be able to alter your
ServletExec settings. Beginning with SE 5.0 this is setup by
default during the SE installation.

Use the "-allow" option in the ServletExec AS startup script.
That option can be used to specify the address(es) of the web server(s) that
are allowed to communicate with the ServletExec/AS instance.
By default, an SE AS instance will only accept communication from a webserver
that is running on the same machine as the instance.
See the SE Installation Guide for more information about the "-allow" option.

Remove the servletexec web application.
Note: Removing this web application prevents access to the ServleExec Admin UI from any machine.
Therefore, after removing this web application, anytime you wish make SE configuration changes you will be required to edit the ServletExec configuration files by hand with a text editor and then cycle the SE AS instance. In other words, you'll be making your life more difficult so think carefully before you do this.
Also note that the servletexec web application is an auto-deployed webapp. This means that you'll have to do an extra step in order to totally remove/undeploy it (see SE FAQ #242 for more info.).

If you have your own specific webapp to which you are trying to control access, then you should consider utilizing some of the Access Control mechanisms that are available for use in any webapp. These are mechanisms that are defined in the Servlet Specification and they are implemented by ServletExec.
These mechanisms are discussed in the Servlet Specifications & in the ServletExec 5.x (and higher) User Guide.
For example in the SE 5.0 User Guide you should take a look at the following sections:

3.5.6 entitled "Setting Up Roles, Users, and Role Mapping"

3.5.7.4 entitled "Security"

In addition, SE comes with an exampleWebApp which offers several working examples of many things, some of which deal with things such Access Control mechanisms.

Setup a firewall environment using 1 or more firewalls to control the traffic that your SE instance will receive.
This technique is an advanced technique and is discussed in great detail here

Faq ID

364

Product

ServletExec

Category

ArcIMS Users, Installation, Known Limitations and Workarounds, Web Server Support

Question

I'm using IIS 6 (or higher) as my web server software. Should I use SE ISAPI or SE AS?

Answer

You must use SE AS.
As of February 2009, using SE ISAPI with IIS 6 or higher is no longer supported or recommended. The reasons why are given below.

Microsoft introduced some architectural features beginning with IIS 6 which have forced us to recommend using SE AS *instead of* SE ISAPI when using IIS version 6 (or greater).
To better grasp the remainder of this FAQ, it is important that you first get a basic understanding of the architectural differences between SE ISAPI & SE AS.
For that you should read and study the SE configurations page.

So with SE ISAPI, the JVM (and thus SE and all the servlets & JSPs that you deploy inside SE) run inside the IIS process.
So it (i.e. the JVM) is at the "mercy" of IIS and windows.
With SE AS, the JVM runs in its own separate / isolated process... apart from the webserver's process.
So it has a bit more "freedom".

SE AS can often allow a person to side-step several potential limitations that IIS/Windows impose.
SE AS has more moving parts yes... but the tradeoff (in our opinion) is a more flexible, stable setup (when using IIS 6 or higher).

Here are a few specific reasons why we recommend using SE AS over SE ISAPI (when using IIS 6 or higher):

IIS 6 (and higher) has Application Pool(s) which cycle themselves at pre-configured intervals.
For SE ISAPI this means the entire JVM gets shutdown and does not come up again until
a request comes in, which makes that request "run" slowly.
For more details read SE FAQ #270
specifically beginning where it says:

If IIS is configured to shutdown an idle application pool after some period of time ...

This is a large point.
Summary:
Sometimes people want to have more than 1 IIS website, where each website is configured
to run inside its own IIS Application Pool (i.e. Multiple Application Pools).
SE ISAPI can't be used with Multiple Application Pools.
See SE FAQ #270 for more details.
SE AS however could be run from Multiple Application Pools.
Having more than 1 IIS website may or may not be your situation.
The main issue is with having more than 1 IIS Application Pool... even if you have only 1 IIS Website. And it may also be important to understand that some software that you or someone else installs on your IIS box may in fact create additional IIS Application Pools (possibly without you even realizing it). Microsoft Sharepoint is one example as it creates it own Application Pool within IIS.

Details:
The Application Pools Feature of IIS 6 (and newer) can very easily (often
without your knowledge) be utilized in a manner that is unsafe for SE ISAPI.
For gritty details about that please see this SE Interest List Posting #221073
This condition can be worked around when using SE ISAPI, but it can be a bit tricky to do properly,
and if others can administer your IIS then it would be very easy for the problem to be re-introduced
by someone who does not understand the nuances (especially with IIS 7).
SE AS would still be effected by this condition, but it would not create an unsafe/unstable condition.
In other words... SE AS would be far less effected by this condition, and would in fact run just fine.

The same architectural limitation that prevents SE ISAPI from functioning properly in an IIS environment
that uses Multiple Application Pools, would also exist in an IIS environment that uses Multiple Web Gardens.
So ServletExec ISAPI does not support the use of Multiple IIS Web Gardens. The Web Garden value must be set to 1.
No other value. So the ability to configure the Web Garden setting presents a threat to SE ISAPI stability.

As of February 2009 it has been realized that because of how IIS manages even just 1 single Application Pool, that SE ISAPI cannot be used with 100% reliability with IIS 6 or higher. Consider an IIS installation that has only 1 single App Pool (and also whose Web Garden setting is exactly 1)... If/When IIS decides to cycle that App Pool it will first start up a new App Pool to take it's place. That new App Pool will begin to handle new incoming requests while the "old" App Pool actually remains in existence for an unspecified amount of time (while it finishes processing "old" requests). This is how IIS manages a single Application Pool cycling. It may be thought of as a sort of failover or "hand-off". This presents a problem for SE ISAPI (but not for SE AS) since it means that 2 Application Pools (and thus 2 SE ISAPI JVMs) are up and running at the same time (albeit a very brief time). SE ISAPI simply cannot run reliably when it is loaded more than once on the same machine. For this reason the use of SE ISAPI with IIS 6 is absolutely no longer recommended for any reason. Period. Configuring IIS 6 to not cycle its one App Pool, or to run in "IIS 5 Process isolation mode" may be the only ways to use SE ISAPI with IIS 6 reliably. But we do not recommend these options as they represent configurations that may easily be undone, and are not the "natural" (or preferred) way to run IIS 6.

When you use SE ISAPI, IIS/Windows will restrict the amount of RAM you can give to your JVM.
For more details, see SE FAQ #317.

By using AS, you side-step this common issue that often occurs when using ISAPI.
and also side-step less common issues such as the one described by SE FAQ #356
and you can also avoid being impacted by some JVM 1.5.0 bugs that are described by SE FAQ #338
and you also avoid having to configure your IIS 6 to run in IIS 5 Isolation Mode.
This point is fairly uncommon, but using SE AS ensures it won't happen to you.
For more info please see SE Interest List Posting #217844.

If your Windows OS is a 64-bit version, then so is your IIS installation. If you wish
to have your SE 5.x instance use a 64-bit JVM (that would be the sensible thing to do on such a machine)
then for SE 5.x, using SE ISAPI would not be an option. This is because with SE 5.x ISAPI, SE's native
DLL that hooks into IIS is only available in a 32-bit build (unless your CPU is Itanium which is rarely the
case for anyone... most folks 64-bit machines are using AMD or Intel Xeon chips). A 64-bit IIS can be configured
to load a 32-bit DLL (ServletExec_ISAPI.dll), however a 32-bit DLL cannot load a 64-bit process (i.e. a 64-bit
JVM). So in this scenario, the only way to have your ServletExec 5.x run with a 64-bit JVM is if you use SE AS.
For more details, please see SE FAQ #302
And also see SE Interest List Posting #188033.

Note that beginning with SE 6.0, this point is less of an issue since SE 6.0 (both ISAPI and AS)
supports both 32-bit & 64-bit IIS 6 & 7... natively.

ArcIMS Users
If you are wanting to use ArcIMS with SE AS & IIS, then before you run the ArcIMS Post-Installer
please read SE FAQ #346, and also consider the fact that certain advanced ArcIMS setups are only possible with
SE AS (not with SE ISAPI). By this we are referring to the setup described in the PDF
"Deploying ArcIMS Within a Corporate Firewall" whitepaper linked on this page.

Faq ID

303

Product

ServletExec

Category

ArcIMS Users, Installation, Web Server Support

Question

Using "localhost" as the hostname in my request URL does not work.
Why?

Then you may find message #96985 posted in the SE Interest list to be enlightening.
Basically, your browser may be configured in a manner that prevents localhost from working as it should.

Faq ID

394

Product

ServletExec

Category

ArcIMS Users, Installation

Question

What are the steps for switching from ServletExec ISAPI to ServletExec AS?

Answer

Examine and take note of how your current SE ISAPI installation is configured (webapps, classpath, datasources, etc...)
Be sure to save/backup any items that must be migrated to SE AS.

Turn off the IIS Application Pool(s) in which SE ISAPI runs

Use Add/Remove Programs to uninstall SE ISAPI

Install SE AS

Turn on the SE AS Windows Service and make sure it is configured for "Automatic" startup

Turn on the IIS Application Pool(s)

Access http://<hostName>/servletexec/admin to ensure that SE AS is hooked into IIS and working as it should.
This is a good time to configure SE AS (enter your license key, deploy any custom webapps you want, etc.).
Note that ArcIMS users don't need to deploy any apps since the ArcIMS Post Installer will do that for you. For more about that read on...

If using ArcIMS, turn off the SE 5.0 AS Windows Service (leaving IIS up and running if you wish) and then
carefully follow these SE AS + ArcIMS integration steps.

Faq ID

298

Product

ServletExec

Category

ArcIMS Users, General Info, Security

Question

When I try to request my servlet, I get a response in my browser that mentions "failed to get servlet". Why?

Answer

This issue most commonly occurs when you try to request a servlet named "testservlet". The cAsE used in the request URL matters to a Servlet/JSP engine (even when using an operating system that is not CaSe sensitive such as Windows). The actual name of that servlet is "TestServlet" (capital T and capital S). If this was your situation, then edit your request URL accordingly and try the request again.

Here is more information on this common pitfall:
When you request something from ServletExec, that something must first be "visible" to ServletExec. If SE does not know about your servlet, and cannot find your servlet, then you can expect to receive that response in your browser. The same would occur if you requested:

So if you are trying to request a servlet, and you are receiving a response like this, then make sure that you have placed the .class file for that servlet into one of the following locations:

the .../WEB-INF/classes/ folder of your webapp

or into a .jar file in the .../WEB-INF/lib/ folder of your webapp

or in an external library for your webapp

or into the "Legacy" Servlets folder (see the SE User Guide)

or in the main SE classpath.

If you have done this and you still can't get past this problem then make certain that you are using the proper cAsE (upper versus lower case) in your request. With a Servlet/JSP engine, CaSe matters (even on a case-insensitive Operating System such as Windows). For example if the servlet's name is TestServlet, and yet you try to request testservlet (all lower-case) then you can expect SE to tell you that it could not find that servlet.

Note: that if you are using SE with ESRI's ArcIMS product, your particular response may be saying something like this:
javax.servlet.ServletException: RequestDispatcher.forward()/include()
failed to get servlet: com.esri.esrimap.Esrimap

In other words, the servlet that you are likely trying to request is the one named "com.esri.esrimap.Esrimap".
That servlet is the ArcIMS Servlet Connector.
You should run the ArcIMS Post Installer and follow the prompts in order to have your ArcIMS Servlet Connector "hooked into" ServletExec so that SE will then know about and be able to find that servlet. That way when you request that servlet, SE will be able to execute that servlet instead of telling you that it failed to find that servlet.

Can problems occur if I have a class both inside my webapp and also on the main classpath ?

Answer

The potential is there, yes.
The 1st issue is one of confusion for the human (not the JVM).
If you do run into a problem, you might be forced to question which class file
is being used.
Consider removing that confusion to more easily solve the problem by having
your class be in one place or the other... not both.

The 2nd issue has to do with ClassLoaders and how they work in Java.
To illustrate what we mean, we'll use SE bug #463 (which isn't really a bug
in SE at all).
That bug is entitled:
ClassCastException occurs when looking up a configured DataSource via JNDI
Here is a portion of that bug's description, which illustrates one situation where having a class file in both the main
SE classpath and also in a web-app's lib or classes folder can cause problems:

This problem is caused by the fact that a Container-wide DataSource that
has been configured via the ServletExec Admin pages is loaded into the JVM
using the System Classloader. The class file for such a datasource must be
placed onto the main SE classpath. If you have web app code which tries to
cast the DataSource object, *AND* that web app code can find the casting type
within the web app (in the classes folder, or the lib folder of the web app)
then the custom classloader for that web app is used to load the casting type.
An object loaded by classloader A cannot then be cast to an object of the
same type that was loaded by ClassLoader B.

In addition you should also be aware of FAQ #96 which tells of another location that the
JVM might be picking up a class file.

Yet another example of a problem that might be seen in this sort of situation would be if a webapp contained JSTL classes (which are already included with SE). The folllowing sort of error might be seen at runtime:
java.lang.LinkageError: Class javax/servlet/jsp/el/ExpressionEvaluator violates loader constraints
This may be due to version differences between the JSTL classes in the webapp and the JSTL classes that come with SE (which are in the main SE classpath). Or it may have nothing to do with version differences and simply be due to a classloader limitation as described above in this FAQ.

Faq ID

177

Product

ServletExec

Category

Class Loading/Reloading, JSP

Question

How can I put my classes into the classpath ?

Answer

For a web application, you put your .class files into the:...\WEB-INF\classes\ folder
or put them in a JAR file and then place that JAR file into the:...\WEB-INF\lib\ folder.
For classes that you want to be visible container-wide (visible to any code running inside of ServletExec):

For SE AS:
The ...\Program Files\New Atlanta\ServletExec AS\se-<instanceName>\classes\ folder is already added to the main SE classpath so if you like you may simply place your .class files there (in a directory structure that mimicks their package names).
Another option is to edit the StartServletExec batch/script file to include the folder or JAR file in the -classpath option that is passed to the JVM at startup.

SE FAQ #33 may also be helpful.
Here is an example showing how to add H:\myClasses and H:\myJars\a.jar to the Main/Global SE classpath for SE 6.0 AS:

...
set cp=%cp%;%seInstanceHome%\classes
set cp=%cp%;H:\myClasses
set cp=%cp%;H:\myJars\a.jar
...

After saving the edits to the file, stop SE, count to 3 (to give the JVM time to truly stop), and then start SE.
Then navigate to the "classpath" page of the SE Admin UI (in your browser) to confirm that the entries you just added appear in the classpath listed there.

For SE ISAPI, or SE NSAPI:
Add the folder containing the class, or add the absolute path to the JAR file to the Main Classpath on the Main ServletExec Admin UI

In all cases, the .class file must reside in a folder structure that mimicks the package name.
This is a Java thing.
This is discussed in section 4.2.3 of the ServletExec 4.1 User Guide.
The exampleWebApp that comes with ServletExec, has some JSPs which make use of Helper beans that are in packages. Study the exampleWebApp to see how this is done.

NOTE: If you are trying to use a class from your JSP:
A JSP is compiled into a Servlet, and with ServletExec, that servlet is declared to be part of the "pagecompile" package. So if your JSP wants to use a Bean/Helper class then you will need to add a page directive to your JSP, importing the package of the Bean/Helper class.
Note that modifying the Operating System Environment Variable named "CLASSPATH" is not likely to have any effect on the JVM in which ServletExec runs because by default, that JVM is not configured to look at or know about or care about the value of that OS Environment variable.
The only way that variable would be used by SE is if it were mentioned in the Main/Global classpath. For example: set cp=%cp%;%CLASSPATH%

Faq ID

395

Product

ServletExec

Category

Class Loading/Reloading

Question

How can my code find out where classpath items reside?

Answer

.class files are looked for and loaded from various locations
as determined by the classloader. Here is an example of
ways you can see these locations for a particular item or package:

<%@ page import="java.net.URL, java.util.Enumeration" %>
<html>
<head><title>showResourceLocation</title></head>
<p>Finding the first location for a given class or resource (to see which one is being found and used by the classloader):</p>
<%
String itemToFind = "java/lang/String.class"; // setting itemToFind="" will tell you the first place the classloader looks for things.
out.print(this.getClass().getClassLoader().getResource(itemToFind).getPath());
//example output: file:/C:/Program%20Files%20(x86)/Java/jdk1.6.0_16/jre/lib/rt.jar!/java/lang/String.class
%>
<hr>
<p>Finding all locations for a given class or resource:</p>
<%
itemToFind = "META-INF/vfs-providers.xml";
Enumeration<URL> locations = this.getClass().getClassLoader().getResources(itemToFind);
out.println("<ol>");
while (locations.hasMoreElements())
out.println("<li>" +((URL)locations.nextElement()).getPath()+ "</li>");
out.println("</ol>");
%>
<p>
Note: These will be output in a different order than how the
classloader would actually find and load them.
See the javadocs for ClassLoader.getResources() which say
that the parent loader is searched first.
</p>
</html>

This technique can also be used to locate the JAR file that contains a particular package. For example:
itemToFind = "javax/servlet";

Faq ID

244

Product

ServletExec

Category

Class Loading/Reloading

Question

How does ServletExec use various classloaders to find and load class files, and how can this effect my Java Servlet web applications ?

Answer

ClassLoaders in Java operate on a parent-child scheme, which is analogous to Object Oriented concepts as follows:
Children "inherit" from their parents, but parents cannot use the functionality of their childen.
At the top is the JVM's own default, basic System Classloader, which looks in various places for classes.
Places such as:

The JVM's main classpath as defined by the -classpath option

The JVM's boot classpath, JARs in it's extensions folder, or JARs in its endorsed folder.
These are specified by the following JVM system properties (respectively):

Code that's loaded into the JVM by the System classloader can be written to create it's own custom classloader(s),
which can be written to look for class files in other places.
This is what SE does to support Java Servlet Web Applications and JSPs running inside those web applications.
Here is a graphic representation of Classloaders in SE:

Each webapp gets its own custom application classloader which will be used to find classes in the following order:

.class files in WEB-INF/classes

.jar files in WEB-INF/lib

Any classes that reside in any external libraries that have been setup for the webapp

If the custom application classloader still can't find the class, it will ask its parent classloader
(i.e. the Java System Classloader) to find the class.

Each webapp also gets its own custom JSP classloader which will be used to find classes in that webapp's pagecompile folder.

A child classloader can ask it's parent to find (and thus load) a class, but the reverse is not true.

If you have a class 'b' that is visible to a higher-level classloader, and that class implements or extends some other class 'a', then class 'a' must also be visible to that higher-level classloader.
Otherwise the JVM won't be able to load class 'b', because when it tries to do so, it will see that 'b' extends or implements 'a' and won't be able to find 'a'.
You'd likely get a NoClassDefFoundError which mentions class 'a'.
Class 'a' would need to be visible to the same classloader as is class 'b' (or visible to a higher-level classloader).

I do not fully understand all aspects of how ServletExec reloads class files. Can you please explain it in great detail?

Answer

For servlets that ARE part of a Web Application:

With ServletExec, each Web Application uses its own single custom classloader to load servlets into the JVM as they are invoked. Newer versions of Servlets are NOT reloaded automatically (the way that they are outside a Web app, in the "Servlets" folder) however a user can tell ServletExec to throw away that custom loader (thus unloading from the JVM all classes that had been loaded by that custom classloader). This is accomplished by reloading the Web Application from the main SE Admin UI dynamically. Then when the new versions are invoked they get loaded into the JVM. This way the reloading of all classes inside a web application is a controlled, user-defined function.
This is in contrast to some other Servlet/JSP engines which take a "side-effect" approach and automatically (behind the scenes), reload all loaded classes in a web app even if just one of them was changed.

For servlets that are NOT part of a Web Application (a.k.a. Legacy Servlets):

If the servlet DOES reside in the folder that has been designated as the "Servlets" folder (on the configuration page for that ServletExec Virtual Server) then when it is invoked, it gets loaded into the JVM by a ServletExec-controlled Custom Classloader.
If that servlet is then modified/recompiled (thus changing its last-modified timestamp on the hard drive) ServletExec recognizes this the next time it is requested and throws away the custom classloader that was originally used to load it. SE then gets a new Custom classloader to load the new version into the JVM (automatic reload of a servlet). This will only occur for classes in the Servlets folder that actually extend HttpServlet. Most servlet/JSP Engines generally have one special folder that is designated to be the "Servlets" folder. Servlets that reside there get loaded by a custom classloader, which is thrown away when newer servlet class files must be loaded.
However, if you have a servlet that is already loaded in the JVM and that servlet creates instances of other helper objects, and you change the class file for 1 or more helper objects but do not change the class file for the servlet then the servlet will retain the references to the original helper objects for as long as the servlet remains loaded.

If the servlet does NOT reside in the folder that has been designated as the "Servlets" folder then when invoked, it is loaded into the JVM by the System classloader.
ServletExec cannot control this classloader and thus cannot throw it away and get a new one.
For this reason, classes that have been loaded into the JVM by the System classloader, stay in the JVM until the JVM is stopped and restarted (reinitialize ServletExec).

For JSPs:

Regardless of whether a JSP is executing inside the context of a Web Application or outside the context of a Web Application, the newest version of a requested JSP will be used. If you have a JSP that includes another JSP (or uses a helper object or a JavaBean) and you make a change to the included JSP (or the helper object or the JavaBean), you won?t see the change on the next invocation unless you also make a change (touch) the including JSP.

Faq ID

355

Product

ServletExec

Category

Class Loading/Reloading

Question

In what order will ServletExec search for classes & resource files?

Answer

WEB-INF/classes/ (.class files go here)

WEB-INF/lib/ (.jar files go here)

External Libraries (only for apps with SE Extensions enabled)

The main SE classpath (-classpath argument passed to the JVM (this is visible on the Classpath page of the SE admin UI)

The JVM's boot classpath, extensions folder, & endorsed folder
as mentioned here
(check your JVM documentation to learn in what order the JVM searches those locations).

In what scope are my helper class files visible to my Servlets and JSPs ?

Answer

For Servlet or JSP code running inside the context of a Web Application:

ServletExec will first look within the Web Application for the classes it needs. When doing this it will first search for the class in the...\WEB-INF\classes folder. If the class is not found there then SE will look for the class by looking inside the JAR files at...\WEB-INF\lib

If the required class is not found in either of those places, SE will then look to the Main ServletExec Classpath.

For Servlet or JSP Code that is running outside the context of any Web Application (Legacy):

ServletExec will first look in the Servlets folder and then it will search the Main ServletExec Classpath. It will not look in any Web Application for what it needs.

Faq ID

120

Product

ServletExec

Category

Class Loading/Reloading, XML

Question

My code running within ServletExec needs to use an XML library (for parsing an XML file) that is different from the one that comes built into SerlvetExec. How can I do this?

Answer

The answer to this question can be a little complex.
If you are using SE 5.0 (or newer):

The importance of understanding the Ordered Lookup Algorithm used by the various
newInstance() methods:

You need to be aware that the first 2 bullets/steps in that Algorithm
are JVM-wide... meaning for ALL webapps, all code running inside the JVM.
So using either of those first 2 techniques can effect other webapps (even the SE admin UI webapp).
Remember that ServletExec already comes with XML parsing classes. Most folks just let their code use those.
Out-of-the-box, any calls to a newInstance() method will result in the 3rd bullet/step being used.
This is because:

By default, SE does NOT set any of the JVM System Properties mentioned in the first bullet

By default, the JVM does NOT have a file named "jaxp.properties" in the lib folder of the JRE directory

SE 5.0 satisfies the requirements of the 3rd bullet, since:

For DocumentBuilderFactory.newInstance():
The xercesImpl.jar file that comes with SE contains the following file:
/META-INF/services/javax.xml.parsers.DocumentBuilderFactory
which names the DocumentBuilderFactory Implementation to use, whose class file also happens to be in that JAR.

For SAXParserFactory.newInstance():
The xercesImpl.jar file that comes with SE contains the following file:
/META-INF/services/javax.xml.parsers.SAXParserFactory
which names the SAXParserFactory Implementation to use, whose class file also happens to be in that JAR.

For TransformerFactory.newInstance():
The xalan.jar file that comes with SE contains the following file:
/META-INF/services/javax.xml.transform.TransformerFactory
which names the TransformerFactory Implementation to use, whose class file also happens to be in that JAR.

Setting one of these System Properties, or creating a jaxp.properties will cause the 3rd step to NOT be used anymore by any code running in that JVM. If you've done that in order to specify a class that is only inside your webapp (not visible to other webapps) then that may be fine for your own webapp, but may break other webapps if/when they try to use a newInstance() method do to some XML-related work.
If you need your app to use a DocumentBuilderFactory and/or a SAXParserFactory and/or a TransformerFactory that differs
from the one that comes with SE then consider one of these 2 possible options:

Replace the parsing JARs provided by SE (in SE's lib folder) with files of the same name whose versions are what you prefer. Note that with is option, you're changing SE and all code running inside SE to use a parser (brand and/or version)
that has not been tested by New Atlanta and is therefore not guaranteed to work.

Place the XML parsing/transforming/etc... JARs that you prefer your app to use, into the WEB-INF/lib folder of your own webapp. Then create a JAR file that meets the requirement of bullet/step #3 and place it into your WEB-INF/lib folder as well. This way when your app calls newInstance() it should receive the Instance that you prefer, and when other apps call
newInstance() they will receive the Instance that they prefer.

If you are using versions of SE prior to SE 5.0 (or if you just want more gritty details):
Here is some general knowledge to help you grasp the more specific information that will follow:

ServletExec comes with and uses XML parsing classes in order to parse the XML files used for Custom Tag Libraries (TLD files), and also to parse XML files for Web Applications (web.xml).
The first version of ServletExec to include XML parsing classes was SE 3.0.
At that time Sun's Project X parser (xml.jar) was used.
More information about this parser can be viewed under the heading:
What is Java Project X? at:http://java.sun.com/xml/faq.html#other
Beginning with ServletExec 4.0b1 Sun's Project X parser was no longer used. Instead the JAXP API and the JAXP 1.1 classes with its default parser (crimson.jar) were used. This was not done sooner because JAXP 1.1 was still an early access release prior to ServletExec 4.0b1.
JAXP 1.1 supports SAX-2 and DOM level 2.

Regardless of the version of ServletExec, when you are running a version of SE that operates in-process with the web server (ISAPI or NSAPI) certain JAR files (ServletExecXX.jar, and the XML parsing JARs for example) are added to ServletExec's classpath (the Main System Classpath) automatically upon startup. You won't see these JARs listed on the Classpath page of SE's main admin UI, and there is no way for you to prevent ServletExec ISAPI or NSAPI from trying to add these JARs to its Main Classpath. These JARs are found in SerlvetExec's lib folder.
Note: if you are using SE 4.0 and trying to do your own XML parsing in a JSP then be sure to put your parsing code into a JavaBean or some helper class rather than using scriptlets directly in the JSP. This works around a classloader bug that was fixed in SE 4.1. Alternatively, you can simply upgrade to SE 4.1 or higher to avoid this bug altogether.
Now here is some specific information for using your own XML parsing classes. The information varies depending on the version and flavor (in-process or out-of-process) of ServletExec that you have:

If you are running your code within the context of a Web
application, then:

Leave the XML parsing mechanism being used by ServletExec 3.0 or newer, in place.

Add the classes for the parser you want to use, to your web application. For example, put xerces.jar into the lib folder of your web app (Do not add them to the main SE classpath because if your web app code looks outside the web app for xml classes it needs, it will first see the XML parsing JARs being used by SE).

If you are using SE 4.0 or SE 4.1 then:

When you write your code to use xerces.jar, do not call
DocumentBuilderFactory.newInstance().

Instead, find out what the fully qualified class name is for the DocumentBuilderFactory Implementation provided by the parser in your web app, and use the 'new' operator to create an instance of it and use it.

If you are using version 4.1.1 of ServletExec, ServletExec still needs Crimson.jar, but it uses it in such a way that you are free to use
whatever XML parser you wish in your code.
You can use:
DocumentBuilderFactory.newInstance() to obtain an instance of the parser you wish to use, however you must be aware of and fully understand the ORDERED LOOKUP ALGORITHM described by the JavaDocs for that method [and the other related newInstance() methods... see top of this FAQ for more info].

If you are NOT running your code within the context of a Web
Application, but rather in a legacy manner, then:

If your version of SE uses xml.jar (SE 3.0 & SE 3.1) then here is an example of how to get all of ServletExec to use a different parser such as xerces.jar:

Add xerces.jar to the main ServletExec classpath.

Stop ServletExec

remove all the org.* packages from xml.jar leaving all other classes intact.
(these are DOM level 1 packages)
Note:
Everything should still work because the new org.* classes
found in xerces.jar are backward compatible with the parser
code that SE uses.

If you are using version 4.0, or 4.1 of SE (which use crimson.jar) you must use crimson.jar in your code. You cannot change the XML parser that the ServletExec Engine uses since there is a crimson-specific call that ServletExec code is relying upon in order to write web.xml files. If you call DocumentBuilderFactory.newInstance() in your code you will receive a parser instance implemented by crimson. This problem was caused by bug #260 which was fixed in SE 4.1.1. Therefore, upgrading to SE 4.1.1 will get you past it.
Here is more information about this case:
The documentation for:
javax.xml.parsers.DocumentBuilderFactory.newInstance()
in the JavaDocs for JAXP
http://java.sun.com/xml/jaxp/dist/1.1/docs/api
discusses an ordered lookup procedure to determine which DocumentBuilderFactory implementation class will be returned by DocumentBuilderFactory.newInstance().
ServletExec 4.0b1 and newer use the Services API technique described in that JavaDoc (step #3).
Since ServletExec (v.4.1, & v. 4.1.1) code relies on the Crimson implementation for writing out web.xml files, the only workaround (other than upgrading to SE 4.1.1 or higher)for doing your own parsing with a different parser is to run your code inside the context of a Web Application. Doing this is
discussed in step #2 of this FAQ entry.

If you are using version 4.1.1 of ServletExec, ServletExec still needs Crimson.jar, but it uses it in such a way that you are free to use
whatever XML parser you wish in your code.
You can use:
DocumentBuilderFactory.newInstance() to obtain an instance of the parser you wish to use, however you must be aware of and understand the ordered lookup algorithm described by the JavaDocs for that method. You will likely need to set the appropriate System Property in the JVM so that step #1 of that algorithm will be used to locate your XML parser class.

Note that ServletExec 4.2 does not use crimson.jar and does not rely on any crimson-specific calls. ServletExec 4.2 uses standard XML APIs, so any compliant XML parser can be used.

NOTE: If you are using JDK 1.4 (or possibly newer versions too) you should read FAQ #241 also

Faq ID

100

Product

ServletExec

Category

Class Loading/Reloading, JSP

Question

My JSP uses a JavaBean (or some other helper object). When I change the class file of the JavaBean, the JSP does not use the new version of the JavaBean. Why?

Answer

The first time that ServletExec receives a request for a particular JSP, It creates a Servlet representation of that JSP and then compiles it. Then that servlet class is loaded into the JVM and an instance of the Servlet is created to service the request (i.e. send an HTTP response).
Servlets remain in memory (they are persistent) and they are multithreaded, so subsequent requests for the same JSP are serviced by the same servlet instance.
If that servlet instance happens to create instances of other "helper" objects (a JavaBean for example), then the servlet continues to use the original JavaBean reference (i.e. the helper objects are persistent too). Depending upon where the class file for your JavaBean resides you have certain options to get the JSP to load the new version of the JavaBean:

Change the last modified timestamp of the JSP source so that ServletExec will think it has changed. This will cause SE to throw away the currently loaded instance of the servlet, compile the "new" JSP into a new servlet, load an instance of it into the JVM (new reference to the new JavaBean) and invoke it to service the request.

If you are running your JSP inside a Web Application then you could dynamically reload the entire Web Application from the SE Admin UI.

Reinit ServletExec (which stops the JVM effectively unloading all code from the JVM)

If the class file for your JavaBean resides in the Servlets folder then it will be loaded by a Custom Classloader that is owned by ServletExec. This means that options 1, 2, or 3 listed above will work for you. If the class file for your JavaBean does NOT reside in the Servlets folder but instead is in the main ServletExec classpath then it will be loaded by the System Classloader. This means that only option 3 will work for you.
If your JavaBean (and the JSP that uses it) is part of a Web Application then option 2 will work for you.
Essentially, if a class is loaded into the JVM using the System Classloader the only way to unload it and get the new version of the class to be used is to stop the JVM and start it up again.
This is a big reason why Web Applications in ServletExec are so useful since all the code running in a web app is loaded into the JVM by a Single Custom Classloader.

Faq ID

119

Product

ServletExec

Category

Class Loading/Reloading

Question

My web application code loads a JNI DLL. After reloading my application, I get an error saying that the DLL was already loaded by another classloader. What is wrong ?

Answer

When this problem occurs, often the stacktrace will contain:
java.lang.UnsatisfiedLinkError

One example of such a message might be something like:
java.lang.UnsatisfiedLinkError: Native Library C:\weblogic\ecs\bin\ecsVerity.dll already loaded in another classloader

This is a limitation in the JVM. A DLL can only be loaded into a JVM once by a classloader. To work around this, have your DLL loaded by a class that is in the main ServletExec classpath so that it is loaded by the System classloader instead of the web application's custom classloader.
That way you'll be able to reload your web application without running into this problem.
Stopping and restarting the JVM (ServletExec) is another way to workaround this problem.

In the event that the information at the above link is removed, here is an excerpt from that link:

"... two things have to happen in order for the native methods to be accessible from Java.
First the DLL has to be loaded ("dynamically linked") into the JVM process,
then the JVM does some magic under the covers to bind the native methods
with the corresponding Java symbols within the class that declares them.
First time the DLL is loaded works fine. If a different class (well, the
same byte codes loaded via a different class loader) tries to access the
same DLL there are no explicit errors but the native methods remain
unresolved and any attempt to invoke the native methods fail (unsatisfied
link error). I guess what has happened is the DLL is already loaded into the
process and so it is assumed to be already bound to the class. But of course
that was a different class that just happened to have the same name so the
symbols in the new class aren't bound to the methods in the DLL. ..."

Faq ID

101

Product

ServletExec

Category

Class Loading/Reloading

Question

What are all the possible ways that I can get a newer version of my Servlet class file to load without having to stop and restart the Web Server or ServletExec?

Answer

Here are the ways you can get a Servlet Class file that is currently loaded in the JVM to be replaced with a newer version of Class file without having to restart anything:

If your servlet resides in the folder designated as the "Servlets" folder for that ServletExec Virtual Server then the newest version of its Class file would be picked up automatically and used by ServletExec the next time that Servlet was requested. This includes a servlet that is in a JAR or ZIP archive having the same name as the servlet

If your servlet is part of a Web Application (WEB-INF folder, web.xml file, etc...) then you could manually reload the entire web application from the main SE admin UI (SE 3.x or higher).

If your servlet is Configured (on the main ServletExec Admin UI)
AND it is either a Remote Servlet or a Servlet that resides in the designated "Servlets" folder then you could manually Reload it from that admin page in order to get the newest version of the Class file to replace the older one that is still in the JVM.

If you use JSPs, SE will always use the most current version of the JSP that is being requested.
Note: For a Configured servlet whose class file does NOT reside in the designated Servlets folder and is NOT remote, reloading it from the Manage Servlets page of the main SE admin UI does NOT cause its class file to be reloaded into the JVM.
It DOES cause that Servlet's destroy() method to be called, and a new Servlet instance is then created from the originally loaded class file. The init() method is then called on that new Servlet instance.

Faq ID

61

Product

ServletExec

Category

Class Loading/Reloading

Question

Why aren't my classes in the Servlets directory automatically reloaded when they are modified?

Answer

Classes in the Servlets directory are only reloaded when the servlet class which extends HttpServlet is modified. When other classes are modified be sure to also modify the servlet class which extends HttpServlet so that all of them will be reloaded.

Faq ID

62

Product

ServletExec

Category

Class Loading/Reloading

Question

Why aren't my classes which are in the classpath automatically reloaded when they are modified?

Answer

Classes which are in the Main ServletExec classpath cannot be automatically reloaded. The only way to reload these classes is to re-init ServletExec. With IIS you must completely stop IIS and restart IIS in order to re-init ServletExec. The procedure for stopping IIS differs for IIS 3.0 and 4.0:

Completely stop IIS 4.0 by stopping the IIS Admin Service from the Services Control Panel; or, you can completely stop IIS 4.0 by using the stop_iis.bat file, which is located in the ...\Program Files\New Atlanta\ServletExec ISAPI folder.

Completely stop IIS 5.0 by stopping the IIS Admin Service from the Services Control Panel or by using the stop_iis.bat command file, which is located in the ...\Program Files\New Atlanta\ServletExec ISAPI folder; or by using the Restart IIS command from the Internet Services Manager.

Faq ID

91

Product

ServletExec

Category

Class Loading/Reloading

Question

Why does my JAAS (Java Authentication and Authorization Service) code fail to run within a Web Application when it runs fine as a stand-alone Java Application?

Answer

This FAQ was written back when SE 3.0 was the current version of SE. This was back in 2000/2001. The JAAS implementation that was available back then would attempt to explicitly use the System Classloader to load classes into the JVM. But ServletExec uses a single Custom Classloader for each Web Application to load classes from that Web Application into the JVM (which is mandated in section 4.6 of the Servlet 2.2 Specification). Because of this, any code (JAAS or otherwise) that runs in a web application cannot utilize the System Classloader successfully.
So that's why folks had trouble running JAAS code inside a webapplication.
On 8.12.2005 (years later) a customer reported that their JAAS code ran fine in SE 5.0.

... JAAS seems not to be a problem anymore with SE 5.0.
I have been able to configure JAAS and to test my application.
It authenticates users using Windows 2000 Domain.
Documents access authorization verification using java security also
seems to work well.

That customer stated that they were using Sun's JVM 1.4.1_02
and the version of JAAS that comes with that JVM.
They also stated that they had obtained the JAAS implementation from:
http://free.tagish.net/jaas/
At the time this portion of this faq was written (Aug, 2005), the above link showed that
the most recent version of JAAS was version 1.0.3 (released 2.17.2003).

Connection Pooling

Faq ID

206

Product

ServletExec

Category

Connection Pooling

Question

How can I turn off Connection Pooling with SE AS ?

Answer

Firstly, we should point out that when this FAQ says "Connection Pooling" this has absolutely nothing to do with JDBC or any sort of Database or DataSource.
By Connection Pooling we mean a pool of sockets that are created by the SE AS native adapter for use in communicating with a particular SE AS Java Instance.
If you are using SE ISAPI or SE NSAPI then this information does not apply to your configuration in any way whatsoever.
Connection pooling for SE AS between its native adapter and its Java instance is a feature that was added in ServletExec 4.0b1 (5/4/01).
And it is only reusing multiple connections when SE AS is running on Windows with (IIS, iWS, or Apache), or if it is running on Unix with iWS.
If you are using SE AS with Apache on Unix then you should know that Apache on Unix maintains its own pool of server processes (where the SE AS native adapter is loaded into each Apache process). Each Apache Virtual Server has it's own pool of processes. Because of the fact that Apache on Unix works this way, the SE AS native adapter for Apache on Unix uses a connection pool of size = 1.
So the "pooling" is at the Apache "process" level, and the single connection in each pool is reused.
The following information tells how to turn off this connection pool so that no connection is ever re-used:

For all SE AS native adapters except for Apache on Unix:
The SE Installation Guide discusses how to tweak the settings of this connection pool.
For example in the SE 4.2 Installation Guide, section 5.5.3.3 is just one place where this feature and its configurability are discussed.

In summary:
To turn it off you'd need to edit the appropriate configuration file depending on your version of SE, and your webserver brand, to set the following 2 SE native adapter parameters to the given values:

NOTE: If you are using SE 5.x AS or higher, then you'd set those parameters in the webadapter.properties file.

Here are examples of the syntax for setting those parameters for SE 4.x (not 5.x or higher):

If using iWS 4.1 or 6.0, you would edit obj.conf to pass these parameters
to the ServletExecInit function like this (for example):
Init fn="ServletExecInit" <instance-name>.instances="127.0.0.1:8888" <instance-name>.pool-max-idle=0 <instance-name>.pool-increment=1
all one line with a single space between each <instance-name> property

For SE AS with Apache on Unix:
You must edit the mod_servletexec.c file and then rebuilt it using apxs.
Look in the mod_servletexec.c source file to find the following:

You'll need to edit the DEFAULT_POOL_MAX_IDLE value to be zero. To learn how to rebuild the adapter follow the steps given at the bottom of the SE 5.0 patch ReadMe.txt file (even if you aren't using SE 5.0, the concept for rebuilding the adapter is the same)

DataSource

Faq ID

350

Product

ServletExec

Category

DataSource, JDBC, Session Tracking

Question

How do I use the JdbcSessionManager that comes with ServletExec 5.0 and higher?

Answer

Install & setup your database. The most current list of supported databases can be found in
SE FAQ #349

NOTE: This step does NOT involve ServletExec at all.
Obtain a JDBC driver for your database. Most all drivers come with some simple examples in the form of
standalone, command-line, java applications. You need to run some of them to ensure that you can:

connect to the database and do a simple Select query

use one of the driver's javax.sql.DataSource implementations (each "brand" of driver has it's own set
of DataSource implementations and it's own set of jdbc properties that are used to tell the driver/datasource
how to connect to the database, so you'll need to read the documentation that came with your driver and
study the examples that came with your driver and make sure you understand how to use it).
For example: If your JDBC driver is New Atlanta's JTurbo, then an explanation of the various DataSource
implementations it provides can be found in
JT FAQ #123
And if you were using JTurbo, you'd find that it comes with several command-line examples. One of them
is named "DataSourceExample.java" which creates and configures a DataSource object with this code:

The storing & looking up of a Datasource using a JNDI context as described above is useful in a "shared" environment such as
an Application Server (ServletExec for example). When you define a Datasource inside an Application Server, typcially the
Application Server takes care of placing it into a JNDI context, so that all code running inside the app server can get a
reference to the Datasource by simply looking it up.

Once you are comfortable with using your JDBC driver, and you've confirmed that you can do so successfully,
you are ready to use it inside ServletExec. Place the drivers's JAR file into the Main/global classpath of ServletExec.
You can't simply place the driver's JAR file into the WEB-INF/lib folder of your webapp since the next
step requires the driver to be on the Main/global classpath. You'll need to restart SE before global classpath
changes will take effect.

Use the SE Admin UI to add a new DataSource. For this step you should use what you learned when you ran the
standalone Java Application examples. You may also find the chapter about DataSources (in the SE User Guide)
to be useful here. After you've added the datasource, you'll see that ServletExec will introspect the Datasource
implementation class that you specified and display all the possible properties it provides. You should configure
these properties as needed/required for your given DataSource. Again... if you don't know what the property names mean, or what
values they should have then you must read the documentation that came with your driver, and consider studying
any examples that came with your driver (examples which use a DataSource might be good to study) so that you can
see how to use one properly.

ServletExec will take care of storing the Datasource implementation into a JNDI context so
that the JdbcSessionManager code can simply look it up & use it. See the Help pages of the SE admin UI for more information on
configuring a Datasource.

The name you give your datasource can be any name you choose. However, by default the JdbcSessionManager expects the
name of the Datasource to be "JTurbo_SQLServer_DataSource". If you give your datasource any other name, then you'll need
to edit your webapp's copy of the jdbcSessionManager.properties file to reflect the name you used. For this, please see the next step.

Extract a copy of the jdbcSessionManager.properties file out of the ServletExecXX.jar file.
Place the copy into the /WEB-INF/classes folder of your webapp, preserving the folder structure so that you have:
/WEB-INF/classes/com/newatlanta/servletexec/session/jdbcSessionManager.properties.
This file is fully documented & may be used to configure your webapp's use of the JdbcSessionManager.

Use the SE Admin UI to turn on ServletExec Extensions for your webapp.

Open the Admin UI for your specific webapp, and access it's session tracking page. There you'll see that you can
specify the Manager Class Name. Set it to be:
com.newatlanta.servletexec.session.JdbcSessionManager

Reload your webapp, and then go look in your database to confirm that it now has a sessions table.

All webapps that are:

Accessed using the same hostname

-AND-

configured to use the JdbcSessionManager with a Datasource that points to the same database

-AND-

deployed using the same context path

will effectively be sharing sessions.
In this way, you can deploy the same webapp onto multiple instances of SE (duplicate/redundant deployments), and do non-sticky load balancing of the webservers behind which the SE AS instances are running, without any session data loss between the various app deployments.

If problems occur, check ServletExec.log for clues, and consider turning on debugging for the JdbcSessionManager by
editing the jdbcSessionManager.properties file so that jdbc.debug=true

More information about the JdbcSessionManager can be found in the ServletExec User Guide.

Debugging

Faq ID

370

Product

ServletExec

Category

Debugging, JSP

Question

How do I increase the response buffer size?

Answer

The default size of the response buffer for a Servlet or a JSP is 8k.
When it becomes filled, ServletExec will automatically flush it to the client.
The first flush contains the response headers followed by the response body.
Subsequent flushes contain the remainder of the response body.

If necessary, you can increase the size of the buffer by using a page directive [in a JSP]. For example:
<%@page buffer="2000kb"%> would set the buffer size to ~2mb.
Another way to configure the buffer size is to call response.setBufferSize() [in a servlet or JSP].
This will delay the automatic flushing of the response buffer.
Yet another way to accomplish this (for JSPs only... not Servlets) when using SE 6.0.0.1 (or higher) is described in the ReleaseNotes.txt file that comes with that hotfix. Basically, you'd configure the JspServlet in your webapp, passing the "bufferSizeKb" init parameter.
Please read that file for more details.

Here is one possible way to configure you webapp so that it uses an unlimited response buffer size (this would work for both Servlets and JSPs):

create your own subclass of javax.servlet.ServletResponseWrapper which overrides the methods used to write data to the client. For example the getWriter() method would be overridden to return a writer that caches all data. For example the flushBuffer() method would be overridden to flush the cached data out to the wrapped output stream.

Write a class that implements javax.servlet.Filter which:

wraps the response object using your response wrapper class.

calls chain.doFilter() passing the wrapper

flushes the cached response out to the real/unwrapped output stream

Configure that Filter into your webapp so that it will be invoked for relevant requests.

That way when the requested servlet or JSP calls response.getWriter() it will be getting the wrapped/buffered writer and will be writing to it instead of writing to the real writer.

Faq ID

90

Product

ServletExec

Category

Debugging, Miscellaneous

Question

I am getting java.lang.NoClassDefFoundError. What does this mean?

Answer

NoClassDefFoundError is not the same thing as ClassNotFoundException.
A ClassNotFoundException means that the class could not be found by the classloader, usually due to the class not being on the Classpath.
NoClassDefFoundError indicates that the class was found but that something went wrong when the class was loaded into the JVM.
One example of a situation that can result in a NoClassDefFoundError would be a class that uses static intializers (a static class variable, or a static block) which throws an exception. Even if the exception is caught, this Error can be thrown at runtime. The problem may not be seen until the first attempt is made to create an object instance from the class definition. It is at this time (runtime) when the JVM realizes that no class definition exists and throws the error.

Another example of when you might see a NoClassDefFoundError might be if the user under which ServletExec is running, does not have the proper file permissions to both read-in, and execute a given class file.
A problem like this is less common, but when it does occur, it is usually with SE ISAPI (IIS webserver on Windows).
For more details about how to diagnose a file permission issue like that, you
should view FAQ #60 at this site:
http://www.newatlanta.com/do/findFaq?faq_id=60
The problem description given in that FAQ is different from the one in this FAQ, but their solutions may very likely be the same.
We can also say that if this problem occurs when ServletExec is trying to startup, the JVM may not be able to actually startup SE.
In such a case, the error message seen in DBMON may be something like:

Even though the ServletExec JAR file is clearly shown in the Classpath.

Faq ID

127

Product

ServletExec

Category

Debugging, Known Limitations and Workarounds

Question

I am getting java.lang.OutOfMemoryError when running my code inside ServletExec. What are the possible causes of this and how can I fix it?

Answer

There are many possible causes for this problem.
You will have to do some investigating in order to learn the cause in your case. Here is a list of some possible causes:

One possible cause is that your code is actually hitting the limit of available RAM that is available to the JVM. Here are some examples of cases in which this can potentially occur:

you are accumulating data in the Application, or Session scopes across many requests and not cleaning up the data soon enough

you are reading in (or generating) a large file (or a large amount of response data)

you are receiving a very large ResultSet from a database query

your servlet/jsp code acts as a client to some external server/application (the ArcIMS Connector Servlet acting as a client to the ArcIMS Spatial Server would be one example of this) and the client code is receiving a very large response body from the external server. Another example would be if your Servlet/JSP code were acting as a Web Service client and was receiving a large XML response from a Web Service... so large that it exhausts all available RAM.

ServletExec (and your Java servlet/JSP code) runs inside the Java Virtual Machine.
It is the Java Virtual Machine which allocates a finite amount of RAM for itself in which to run (called the Heap Size).
Different versions of JVMs have different default Max Heap size settings.
However it is entirely possible to configure this by passing the appropriate options to the java interpreter upon startup.
SE FAQ #318 explains how one would pass options to the java interpreter in the various configurations of ServletExec.

Another possible cause may have to do with the fact that JSP pages create a Session Object by default. If your site has many JSPs, that do not need to use the session object, then consider using a page directive to disable the creation of the Session Object on those pages. You may also want to consider shortening the lifespan of your sessions, either via the SE admin UI, or programmatically in your code session.setMaxInactiveInterval. You should also consider having your users logout, allowing your code to call session.invalidate() right then so that the session won't hang around until it's expired. Also, if you were to use a stress testing tool that did not maintain the session id cookie on subsequent requests then a session object would be created on every request which would most certainly exhaust the available heap size very quickly.
Creating a brand new session on every single stress test request is not realistic.

Another possible cause is that your Java code is somehow using a resource in such a way that the resource is not being properly released (basically a memory leak). This resource may be obtained via: Your own code, Native calls, or using 3rd party software. Solving this problem can be more difficult, especially if it is due to code that you did not write. Isolating the problem to its simplest, consistently reproducible case is very important. This means you would need to:

Instrument your code, comment out sections while retesting to locate the failure point

Look for patterns (does the problem occur only on certain requests?), etc...

Look in your webserver's access log to see what was being requested at the time of the failure

SE 4.x and higher have some built-in monitoring abilities (Threads, Requests, Sessions) that may provide clues.

Consider using a profiling tool.
Information about profiling tools (such as OptimizeIt) can be found in SE FAQ #57. If you do use OptimizeIt, you need to know the following:

OptimizeIt has 1 wrinkle that we know of.
It's a sort of memory leak which is discussed on the SE Interest List. There may in fact be configurations that can be made to OptimizeIt, to alleviate that issue. But that's a question for the makers of OptimizeIt.

Check your application's usage of sessions and other persistent scopes. Does you application store lots and lots of data into the session scope (or the application scope)? If so is that data cleaned out as soon as it could be [via session.invalidate() or by setting the session lifespan to a lower value]

Faq ID

87

Product

ServletExec

Category

Debugging

Question

I am seeing a problem with a New Atlanta product that only occurs sometimes, or it only occurs with certain code, or in certain configurations, or on certain machines (but not others), how can a solution be found?

Answer

Problems like this, are not easily reproduced by the support staff of New Atlanta Communications.
If New Atlanta cannot reproduce the problem then they cannot diagnose and solve it.

The first thing to do is to look for error messages in any applicable log files. For example if using ServletExec then you would need to look in ServletExec.log, ServletExecNative.log (in-process only), and Servlet.log.
Very often, you can find messages in these logs which may point you to the cause of the problem.

Isolating the problem to its simplest, consistently reproducible test case is paramount.
Ask yourself this question:
"How can I simplify this problem?"
For example, if the problem occurs with code that runs inside an application server, then consider running the code from a command line instead.
Does the problem still occur?
If the problem occurs with your code, consider removing your code from the equation completely (removing it from the Classpath, undeploying any of your web apps, etc...) and try using some of the examples that come with the New Atlanta product.
For example if the product is ServletExec then try using TestServlet or DateServlet or hangman.jsp or the exampleWebApp.
If the product is JTurbo, then try to run some of its simpler examples from a command line.
If doing this reveals that the problem is only occurring when certain code is run, or when code is run in certain ways, then communicate that fact to the support staff of New Atlanta.
If doing this reveals that the problem is only occurring when you run a specific chunk of code then comment out whole sections of that code in order to possibly isolate which block of code might be causing the problem.

Instrument your code,
[adding System.out.println() statements in various locations] in order to begin narrowing in on precisely where the problem occurs, and what key variable values are when the problem occurs.

If the problem involves JDBC code then consider using some JDBC debugging techniques
So that the JDBC layer of your webapplication will output more info, which may help to solve the problem.

Look for patterns in the problem.
Does it occur only when running certain code?
Does the problem occur only when you do certain things?
If using a web server and the problem is occurring on certain requests, then look at the access log file of the HTTP Web Server for a pattern of requests that lead to the problem.

If the problem involves JDBC code, then consider stubbing out all JDBC calls to see if the problem goes away.
If you are using JDBC Connection pooling, try running the code without the pool at all (just getting a fresh connection each time). That at least would help to isolate it.

Are you making native calls from Java?
If so, remove those and see if it alleviates the problem, or yeilds different behavior or different error messages.

Do you have access to any machine/configuration where the problem is not occurring?
If so, then ask yourself this question:
"What is different about the machine where the code works, and the machine where the code does not work"?

Consider trying a separate machine, different JVM version, different hotspot flavor (client vs server), different version of OS, and/or different brand of web server.

NOTE:
In all cases, make a single change and then retest, make another change and then retest, etc...
That way you will know the effect of each single change.
Once you have a solid test case, and you believe that it demonstrates a problem with a New Atlanta product, and the test case is as simplistic as possible and does nothing but consistently reproduce the problem, then send it to the support staff of New Atlanta Communications.
They will attempt to reproduce the problem and diagnose it.
Please do not send large bodies of source code. Please send only those components that are absolutely required for demonstrating and documenting the problem.

Faq ID

51

Product

ServletExec

Category

Debugging

Question

I am seeing the words "Compiled Code" in my error stacktrace. What does it mean?

Answer

This occurs when the JITC is enabled with JDK 1.2.2. Disable it from the Main ServletExec admin UI (ISAPI or NSAPI only) and then reinitialize ServletExec. Then when you duplicate the original problem, you should see line numbers instead of the words "Compiled Code".

Faq ID

366

Product

ServletExec

Category

Debugging, Profiling Servlets, Session Tracking

Question

Is there some way to know how much memory my session data is using up?

What tools/techniques are available for profiling my servlets/JSPs/JVM/IIS?

Answer

This technique takes a "snapshot" of the memory
usage of a currently running JVM:
Here is a simple JSP that outputs some basic information
about the state of the JVM's heap. If you suspect that
your application may be suffering from a memory or resource
leak then manually request this JSP (periodically) to see if
your heap is growing and growing over time, yet never shrinking.
Note that if you are using SE 6.0 or higher then you do not need
to use this JSP since the SE admin UI outputs this information
on the JVM Settings page.

If on Windows, consider using the Windows Task manager to monitor the memory usage and/or the CPU usage of the appropriate java.exe process and/or w3wp.exe process. Details about the Windows Task manager given in BlueDragon FAQ #393 may be adapted for use with ServletExec.

Do a thread dump of the JVM in which your SE AS instance is running at the time the problem is occurring. Here are the general steps for doing that:

stop the SE AS Windows Service

make a backup copy of StartServletExec.bat

edit StartServletExec.bat to remove the -Xrs option (if present)

use the keyboard to invoke StartServletExec.bat

reproduce the problem

use Ctrl-Break to get a thread dump of the JVM when it is in the problem state. For example if the problem is that java.exe goes to 100% CPU when requesting a specific JSP page, then request that page and then do the Ctrl-Break.

When finished, capture the resulting thread dump (shown in the DOS window) to a file. Then restore the -Xrs as it was before and then stop SE running from the batch file (i.e. close the DOS window, or manually invoke StopServletExec.bat). Then start the SE AS instance up as a service so that your application will be up and running for your users.

Study the thread dump

Here is how we were able to configure the JVM 1.6 being used by SE 6.0 AS on Windows to write a dump file to the hard-drive anytime an OutOfMemoryError occurs:

Turn off the SE AS 6.0 instance

Make a backup copy of the StartServletExec.bat file

Open StartServletExec.bat file in a plain text editor and edit it as follows:

Find this line in the file:
set jvmOptions=%jvmOptions% -Djava.naming.factory.initial=com.newatlanta.servletexec.InitialContextFactory
Directly under that line, add these lines:

:: telling the JVM to write a Heap Dump file to the hard-drive when an OutOfMemoryError occurs
set heapDumpsFolder=%seHome%\%seInstanceName%\heapDumps
:: the folder must exist else the JVM won't be able to write the dump file
mkdir "%heapDumpsFolder%"
set jvmOptions=%jvmOptions% -XX:+HeapDumpOnOutOfMemoryError
set jvmOptions=%jvmOptions% -XX:HeapDumpPath="%heapDumpsFolder%"

Save the change.

Start SE by double-clicking the batch file instead of starting it as service. If the DOS window comes up and stays up, and you can access your servlets or the SE admin pages then you know you have not added syntax errors in your StartServletExec.bat.

Turn it off by either double-clicking the StopServletExec.bat file, or by just closing the DOS window.

Now start the SE AS 6.0 instance as a Windows Service (which is how it would typically be running)

Optional: Write a simple servlet that will cause an OutOfMemoryError and request it to confirm that a dump file was written. Note that using a JSP to test that won't likely work since all JSPs catch Throwable by default, so the OOM Error would never make it up to the JVM for a heap dump file to be written. Likewise for a servlet that is running inside a webapp that is configured to catch the java.lang.OutOfMemoryError or java.lang.Error, or java.lang.Throwable (via configured error pages inside the webapp for example)

If you have reason to believe that the problem is NOT on the java side of SE, but is rather on the native side (within IIS for example) then consider using the Microsoft Debug Diagnostic Tool v1.1 to both generate and analyze a dump of the w3wp.exe process.

Try using the Java Interactive Profiler (JIP).
We like it because it is very lightweight and can be "turned on" and "turned off" against a continuously running JVM.
When you download it, for simplicity, be sure to download the non-source ZIP file. For example, at the time of this writing, the link above offers a file named jip-src-1.1.1.zip for download. We are suggesting that you do not download that ZIP, but rather click on the "View All Files" link there and download jip-1.1.1.zip instead. The reason we make this recommendation is because the src distribution contains an example.bat file which does not work without modification (paths are not surrounded with double-quotes, a reference to an ANT class that does not exist, etc...) so having the src distribution could cause unnecessary confusion and frustration. The non-source distro has all you need to use JIP.

After you have downloaded that ZIP, unpack its contents to a new, empty folder.
Then read the readme.html file that is in the "doc" folder.
Use the information there to perform these suggested steps:

Turn off your Application Server (ServletExec, BlueDragonJX, etc...).
If on Windows, turn off the App server from the Services control panel so that it is no longer running as a Windows service (and thus no longer running at all). For ServletExec this would mean turning off the Windows Service whose name is "ServletExec-<instanceName>".
Then use your browser (and/or the list of java.exe processes shown in the Windows Task Manager) to confirm that the Application Server is truly turned off.

Find the batch file (or unix shell script) that is used to start your Application Server. Keep in mind that one batch/shell may simply call another (which may call another and another, etc....). What you are really looking for is the 1 batch/script that is cranking up the java interpreter (java.exe for example).
For ServletExec this is typically StartServletExec.bat.

Once you have found that file, make a backup copy of it.

Now start your Application Server using the batch file and use your browser to make sure that your application works.
If it does, then turn the App Server off via the Stop batch/script file (or by closing the command window in which it had been running) and then make sure the App Server is truly turned off (check this in the same manner that you did earlier).

Now edit that batch/script file to add the 2 JVM options that are discussed in the JIP readme.html file. Here we are talking about -javaagent: and -Dprofile.properties. The locations specified for each of those will depend on where you unpacked the JIP ZIP file.
The profile.properties file that we recommend you point to comes with the JIP ZIP and it's name is "webapp.profile.properties".

For example, to hook JIP into ServletExec 5, where the JIP ZIP has been unpacked to C:\jip\ one might do the following:

locate the -Djava.factory.naming.initial JVM option that is already in StartServletExec.bat.

add the following (including the double-quotes that are shown just before that -D JVM option so that that section of the file looks like this:
"-javaagent:C:\jip\profile\profile.jar" -Dprofile.properties="C:\jip\profile\webapp.profile.properties" -Djava.factory.naming.initial

Save the change and then start your app server (ServletExec for example) by manually invoking the start script/batch file. You should see JIP-related startup messages in the command window. Then make sure your application is working and is accessible from a browser.

When you are ready to turn on JIP, follow the simple steps given in the "Interactive profiling" section of the readme.html file that comes with JIP.
To help you with this step, here are the contents for a batch file that could be used to setup, turn on, and then turn off the profiler. As it is written now, it would need to be placed inside the "client" folder:

set outputFile=c:\jip\profile.txt
call file.bat localhost 15599 "%outputFile%"
echo The next step will be to turn on the profiler...
pause
call start.bat localhost 15599
echo Run your test case, or put things into the state you wish to analyze. Then return here and continue...
pause
call finish.bat localhost 15599
echo JIP has been turned back off, go analyze the output file [%outputFile%].
pause
set outputFile=

This technique takes a "snapshot" of the state of the objects in a currently running JVM:
JDK 1.6 (for both windows & linux) comes with a cool tool (jmap) to
help with debugging out-of-memory issues. This tool is also available in
earlier versions of the JDK for linux only.
Here's what you do to use it (using BlueDragon JX as an *example*):

The best way to debug your servlets is to use SE 5.x AS (or higher) running with it's built-in webserver, running inside the IDE of your choice.
Here are some suggested steps to accomplish this:

Download and install SE 5.x AS (or higher) and during the install select the option to have it run with it's built-in webserver.

Make sure that you can get that running on its own properly by testing it to ensure that it can serve/servletexec/admin and/servlet/TestServlet and
your own servlets.

Then study it's Start Script (StartServletExec.bat or StartServletExec.sh) and use what you see there regarding how it is started, together with the documentation for your IDE to configure your IDE to run the SE AS built-in server within the IDE's JVM.

Once you have it running inside your IDE you can then set breakpoints in your servlet code, make requests from your browser, and then step through your servlet code.

To stop debugging, you may either tell eclipse to "stop debugging" or you may run StopServletExec directly in order to send a stop message to the SE AS built-in webserver that's running inside your IDE so that it will shutdown gracefully.

An SE AS instance that runs behind a commercial-grade webserver such as IIS, Apache, or SJSWS may also be run inside your IDE. It does not have to be an SE AS instance that runs behind SE's built-in webserver. Some useful information about doing that inside the Eclipse IDE is given here

NOTE:
The ServletExec Debugger [SED] was a free, separate product that used to be used for this, but now SE AS (5.x or higher) with it's built-in webserver is what we recommend. SED has been discontinued.
If you still require SED, then SED 4.2 can be obtained from our FTP server.

Exceptions

Faq ID

374

Product

ServletExec

Category

Exceptions, Web Application

Question

Custom Error Pages defined in my webapp are not returned as expected when using IIS 7.

Answer

We've seen this issue first hand (while developing SE 6.0beta), and discussed it at that time in detail with Microsoft Engineers on an IIS 7 Forum.
In the end, New Atlanta decided to let our users be the ones to configure their IIS 7 as desired.
In other words, we decided not to have the SE 6.0 installer try to do anything fancy with IIS 7 to prevent this issue.
Otherwise we'd no doubt have some folks complaining that our installer had broken/changed their IIS 7 error handling behavior, and they would be correct.
We don't see that the IIS 7 Management console offers the ability to set the "passThrough" setting.
So you may simply need to use the AppCmd.exe as the forum post referenced above suggests.
When we used that command on our virtualized Win 2008 we found that it updated our
C:\Windows\System32\inetsrv\config\applicationHost.config file, changing:

<httpErrors>
to be:
<httpErrors existingResponse="PassThrough">

(Note: the closing </httpErrors> tag is not shown in the snippet above)

Here is one example of how the passThrough "flag" might be used in applicationHost.config:

If you don't feel like using AppCmd you could always manually edit the applicationHost.config file directly, or perhaps try using a Web.config file with a similar setting.
If you do manually edit that file, be sure to use a text editor that is running in an "elevated" manner.
For example, don't simply use Notepad, but rather right-click on the Notepad icon and choose "Run As Administrator",
so that it runs with Adminstrator priviledges.
You must do this even if you are logged into Windows as the Administrator.
Otherwise you'll make edits to that file and they will seem to have been saved, when in truth they were not (closing the file and reopening can reveal the truth in that scenario).
That should help you to get your IIS 7 configured to get out of SE's way in regards to Error Pages.

General Info

Faq ID

222

Product

ServletExec

Category

General Info, Version differences

Question

What versions of ServletExec are supported?

Answer

ServletExec 6.0 and 5.0 are the only supported versions.

ServletExec 5.0 will reach End-of-Life on April 30, 2013 and will then be no longer supported. Once ServletExec 5.0 reaches End-of-Life, we will still try to answer any questions you might have about that version. However, if you find a bug in ServletExec 5.0, you would be asked to upgrade to ServletExec 6.0. Patches/Updates/Hotfixes are not issued for versions of ServletExec that have reached their End-of-Life.

HTTP Connections

Faq ID

200

Product

ServletExec

Category

HTTP Connections

Question

Does ServletExec support HTTP/1.1 persistent connections ?

Answer

Yes.
The first version of ServletExec to support this feature was SE 4.0b1.
There are some conditions which must be met in order to take advantage of this feature:

The request must be made using the HTTP 1.1 protocol.
For example:GET /index.jsp HTTP/1.1

The request must not send the request header named Connection with the value of Close.

The response must set the response header named Content-Length
with the appropriate value. This would be done in your servlet code using the setContentLength() method of the Response object. Otherwise ServletExec has no way of knowing how many bytes a dynamically generated response will be and would therefore have to send a response header named Connection with a value of Close thereby telling the client to close the connection.

Note that there is an alternative to the 3rd requirement:
You could use Chunked encoding instead (where each chunk of response data sent to the client has its own sort of content-length information telling how big that response chunk is, and whether or not it is the last chunk). With the Apache webserver, in the absence of the response header named Content-Length, chunked encoding is used by default for sending responses to the client.
With other webserver (IIS and iPlanet) you would need to manage this in your servlet. The complete steps for writing your servlet code so that it sends a chunked response are beyond the scope of this FAQ, however the general idea for doing this is:

set the HTTP 1.1 response header named Transfer-Encoding with a value of chunked

When sending the response body (out.println()), the format of the body must conform to that of a Chunked-body as defined by the HTTP/1.1 Specification.

Note: While it is possible to use chunked encoding in either direction (for both requests and responses) ServletExec does not currently support chunked requests. However there may be a workaround

Faq ID

103

Product

ServletExec

Category

HTTP Connections

Question

I am running ServletExec with Microsoft IIS and it won't process more than 10 connections. How can I increase this ?

Answer

When running on NT Workstation, 2000 Professional, or XP Professional, IIS has a hard-coded limit of 10 concurrent connections. As far as we know it is not possible to increase this. When running on NT Server, 2000 Server or .NET Server, IIS does not have this limitation.
As for ServletExec:
If ServletExec is running in an Unregistered mode then it will only handle 3 requests simultaneously. Concurrent requests beyond this limit will result in an HTML response page that says something like this:
When not registered, ServletExec supports a maximum of 3 concurrent
requests.

Faq ID

4

Product

ServletExec

Category

HTTP Connections

Question

I'm running ServletExec on UNIX and it won't process more than 64 connections. How can I increase this?

Answer

By default UNIX limits the number of file descriptors (used for network sockets) to 64. By using the limit command you can increase this value. See man limit for more details.

Faq ID

5

Product

ServletExec

Category

HTTP Connections

Question

I'm running ServletExec with Microsoft IIS and it won't process more than 256 simultaneous connections. How can I increase this?

Answer

By default, IIS limits the number of connections to 256, multiplied by the number of processors (therefore, a 2-CPU server will support 512 concurrent connections by default). You can increase this value by creating the following registry entry and setting it to a value greater than 256:

You should be careful about what value you set this to since increasing the number of threads will reduce the number of rejected requests but slow down overall performance of your web server software.

Faq ID

3

Product

ServletExec

Category

HTTP Connections

Question

What's the maximum number of connections ServletExec can handle?

Answer

When ServletExec is registered with a license key, it doesn't have a limit on the number of connections it can handle. In this case, the number of connections it can handle will depend upon the system it is running on, the web server it is running behind, network settings, etc...
If ServletExec is not registered, it will only handle 3 concurrent requests.
If you need to stress test ServletExec before you purchase a full license key, you can request a 30-day evaluation key by sending your request to:
sales@newatlanta.com

Installation

Faq ID

16

Product

ServletExec

Category

Installation

Question

Can ServletExec be installed with iPlanet Web Server 4.0 on Unix?

Answer

Yes it can but you must either install iPlanet without Server Java Support(Servlets and JSP) or you must disable this feature. You should disable it from the iPlanet Administration User Interface before installing ServletExec.

On Solaris, if you installed iPlanet with a JRE then you must disable it before installing ServletExec. To do this you can use the iPlanet "uninstall" command or you can rename the JRE directory (/bin/https/jre).

Note that ServletExec 2.2 doesn't work with iPlanet Web Server 4.1.

Faq ID

10

Product

ServletExec

Category

Installation

Question

Can ServletExec be installed with iPlanet Web Server 4.0 on Windows?

Answer

Yes it can but you must either install iPlanet without Server Java Support(Servlets and JSP) or you must disable this feature. You should disable it from the iPlanet Administration User Interface before installing ServletExec. Note that ServletExec 2.2 doesn't work with iPlanet Web Server 4.1 and support for iPlanet FastTrack Server 4.1 was added in ServletExec 3.1.

Faq ID

15

Product

ServletExec

Category

Installation

Question

Can ServletExec be installed with Stronghold?

Answer

Here are the steps to get SE 4.2 AS installed and running with the StrongHold 4 webserver on a Solaris 7 machine:

Setup your StrongHold 4 with a server ID by following the instructions given in the StrongHold 4 installation and admin guide, and make sure it works on both port 80 and port 443.
Note: this step involves obtaining a signed certificate request from a well-known CA and using the StongHold4 utililty "bin/getca" to install that signed certificate.

If you run the SE 4.2 AS installer against StrongHold 4, the installer will fail to complete and will actually delete all the ServletExec files and folders that had been created before the failure.
Note: In our tests, the SE 4.2 installer fails to successfully use StrongHold's apxs script to build mod_servletexec.c due to it not liking the
"-fno-strict-aliasing" parameter specified in StrongHold's apxs script.
For this reason you will first need to run the SE 4.2 AS installer against a regular version of Apache (i.e. a non-StrongHold version of Apache). This will "trick" the installer into creating the SE folders and files that are required for the SE AS 4.2 Java instance. If you do not want the installer to modify the httpd.conf file of this regular Apache version, then choose "no" when the installer asks whether you want it to make manual edits to httpd.conf for you. In this way, the SE adapter module will not be "hooked into" the regular Apache version in any way.

Modify /extra/stronghold4/bin/apxs to remove the "-fno-strict-aliasing" portion from the 3rd variable:

Now the SE 4.2 AS native adapter has been built and "hooked-into" StrongHold 4 and it has been configured to connect with the SE AS 4.2 Java instance that was created during the install against the regular Apache version.

Note: If you use SE 5.x (or higher) then please realize that the httpd.conf edits for SE 4.x (shown above) are different than the edits that would be made for SE 5.x.
To understand the edits that must be made for SE 5.x please see section 6.5.3.2 entitled: "Server Configuration File (httpd.conf)"
in the SE 5.0 Installation Guide. With SE 5, it's only 2 or 3 lines that get added to httpd.conf.

Faq ID

270

Product

ServletExec

Category

Installation

Question

Can you provide some general technical tips regarding the use of ServletExec with IIS 6/7 on Windows 2003/2008/Vista?

Answer

Sure.

First some history... before IIS 6 there was no notion of an IIS Application Pool.
This meant that if you had more than 1 IIS website that you wish to use SE ISAPI then you could not add the ServletExec ISAPI filter to more than 1 IIS website, because SE ISAPI runs in-process with IIS and a JVM cannot be loaded into the same process more than once. You could do that with SE AS (where the JVM runs out-of-process from IIS), but not with SE ISAPI.
The solution is to have the ServletExec ISAPI filter be added to IIS at the "global"/"master" level... instead of at the level of an individual website.
That way the filter is loaded only once for ALL of IIS. This is what the SE ISAPI (and AS) installers for IIS do.
Multiple IIS websites can make use of ServletExec by simply having a Virtual Directory (VD) with the right name, pointing to the right place, with the right permissions (see other FAQs at this site for more details about that VD, especially FAQ #54).

IIS 6 adds a new feature which Microsoft calls Application Pools.
Here are some details on that feature:

It is possible to assign IIS website 'A' to run inside IIS application pool 'A',
and IIS website 'B' to run inside IIS application pool 'B'.
Likewise for Virtual Directories (VD's) defined within a website... VD 'A' can be configured to
run inside app pool 'A', or app pool 'Z', or... etc...)

It is also possible for IIS to be configured to shutdown an idle application pool after some period of time
(20 minutes by default, at the time of this writing).

You should use the information above, together with an understanding of ServletExec architecture when deciding:

Whether to use SE ISAPI or SE AS

Whether to use multiple IIS app pools or a single app pool

Whether to have your IIS app pool(s) cycle themselves after set periods of time and/or inactivity

If using SE ISAPI, all IIS websites that use SE (by defining a Virtual Directory which points to the SE ISAPI DLL) must
be assigned to the same single IIS Application Pool and here is why:
It is possible to assign IIS website 'A' to IIS application pool 'A', and IIS website 'B' to IIS application pool 'B'.
If you did that there would be 2 distinct JVM instances each running SE ISAPI.
Each instance would startup when the first request to their host is received.
Note: The whole website must be assigned to the app pool, not just a VD within it, else you may get 403 Access Forbidden responses for servlet requests).
But just because it's possible, doesn't mean it should be done.
If this were done, only the first SE ISAPI instance that starts up will be able to write to any log files properly:
ServletExecNative.log ServletExec.log Servlet.log (for the default context)
This is because the 1st instance will open the files making them be locked to the 2nd instance (2 instances but one set of log files, config files, etc... for those instances). If one SE ISAPI can't read a configuration file due to it being locked by another SE ISAPI then it will startup in a default state. For example servletexec.xml contains the license key. If an SE ISAPI can't read the key that's in that file due to not being able to read that file at all, then it will startup in an unlicensed state.

Note that this situation could also cause odd problems with configuration files. Another example is if you had defined your own custom SE Virtual Servers (each handles requests that use a specific hostname). In that scenario you'd have more than 1 SE Admin UI Web App that you could access and use to define different settings (each SE VS defines its own set of webapps), but different "instances" of SE should not be writing to the same configuration files (for example application.xml which defines the set of webapps for an "instance" of ServletExec). Using the Admin UI for each of the various SE VS's when SE is "multi-loaded" in this invalid manner would result in configuration file "corruption", and seemingly "lost" settings (lost license key, webapps that mysteriously become undeployed, etc...).

This could also result in log file issues such as ServletExec.log not being rolled over, or rolling onto itself making it impossible to use those files successfully.

So, currently we don't support the use of multiple app pools with SE ISAPI.

If you need to have some servlets running separately from others (meaning in a separate, isolated process from others) then consider using SE AS instead of SE ISAPI. The native component that hooks into IIS for SE AS does not write any log files so there should not be any conflict there. That native component could be loaded into 1 single IIS app pool (most efficient) or could even be loaded into more than 1 IIS app pool (probably uneccessary, see SE FAQ #259 for more details about the performance implications of doing that).

If IIS is configured to shutdown an idle application pool after some period of time (20 minutes by default) then SE will shutdown (as expected). It comes back up just fine the next time a request comes in.
If it's SE ISAPI that you have hooked into IIS, then be aware that shutting down SE means that the whole JVM will shutdown, and all webapp's that are deployed in SE, all servlets will have their destroy() methods called. Upon startup, everything will initialize again, a potentially costly process, and may not be exactly what you had hoped for.
If it's SE AS that you have hooked into IIS, then it's just the native adapter that gets shutdown and restarted when the app pool shuts down and restarts (since that's the only ServletExec component running in that app pool). Basically with SE AS, the portion that snaps into IIS is much more lightweight... the JVM runs in a separate process and the ASI runs inside that JVM, so your JVM and your ASI stay up and running, even after the IIS app pool has been shutdown.

More information about the architectural differences between SE ISAPI and SE AS can be found here, in addition to the ServletExec Installation Guide, and the ServletExec User Guide.

SE Interest List Posting #221073 will also be of great interest if you have multiple Application Pools in your IIS 6 (or IIS 7 or newer) installation.
If for some reason, you must have multiple IIS Application Pools but must also use SE ISAPI and cannot use SE AS then here are some tips for configuring IIS to use SE ISAPI in a safe manner (however this path would not be our first recommendation... using SE AS would be best):

By "safe", we mean... SE ISAPI only being loaded once... by one single IIS Application Pool.

First you'd need to move the SE ISAPI Filter out of the "Global/Master" Level of IIS and place it at the level of the website with which you want to use SE ISAPI. You'd do this for each IIS website that needs to run Servlets or JSPs inside SE ISAPI. Normally this is a huge no-no. And if you just stopped here it still would be. So continue...

This is the tricky part... you must Ensure that ALL areas of ALL websites that have the SE ISAPI Filter added at their level use either:

NO IIS Application Pools at all

-OR-

The exact same single IIS Application Pool (i.e. A "common" App Pool)

This way other websites could make use of other application pools and since the SE ISAPI filter would not be added to those websites and would no longer be added at the Global/Master level of IIS, the SE ISAPI DLL won't be loaded in those other app pools (and that's good).

If you use IIS 7, and create a new website... each new site that you create will (by default) be setup to run inside its own separate application pool. So be aware of this. If your SE ISAPI Filter is at the global level of IIS then this would cause it to be loaded multiple times which will certainly cause problems. In that scenario you'd either need to move the filter down to the website level (as mentioned above) and/or access the properties of that website and remove its "Default Application" or configure it to use a common app pool.

Also be aware that when you create any new Virtual Directory in any IIS website, it is very often not really a simple Virtual Directory but is rather an IIS .NET Application... meaning that it is configured to "execute" inside an IIS App Pool. Look at the properties of all your Virtual Directories to ensure that they are not actually applications configured to use distinct/different application pools. If they collectively make use of even just 2 different app pools AND the SE ISAPI Filter is at the global level of IIS then as soon as a request comes to each distinct App Pool you'll have SE ISAPI loaded twice inside IIS which is very bad.

If you intend to make these configurations in order to run SE ISAPI on an IIS 6 or 7 that has multiple Application Pools, then please be aware: When you make manual changes to the ServletExec ISAPI Filter configuration in IIS [by moving it from the global level to the level of specific website(s)], the SE Uninstaller does not know that you did this. So if/when you or someone else later uninstalls SE ISAPI, the filter will not be removed from IIS. You or that person would have to manually go remove the SE ISAPI Filter from all the places it was manually added in that IIS. Otherwise IIS will keep trying to load that filter and will fail (since the ServletExec_ISAPI.dll file would have been removed). This could prevent IIS from serving any requests at all, essentially breaking IIS until the SE ISAPI Filter is manually removed as needed. So this is just one reason why we don't particularly recommend this path. We recommend using SE AS instead, when you need to use multiple Application Pools in your IIS.

NOTE: The same architectural limitation that prevents SE ISAPI from functioning properly in an IIS environment that uses Multiple Application Pools, would also exist in an IIS environment that uses Multiple Web Gardens. So ServletExec ISAPI does not support the use of Multiple IIS Web Gardens. The Web Garden value must be set to 1. No other value.

iPlanet/SunONE 6.0 webserver is not officially supported by any version of ServletExec.
But if you absolutely must use iWS/SunONE 6.0, then SE 5.x & 4.2 (both NSAPI and AS) will
very likely work just fine with it on Solaris OS or Windows.
Please note that the System Requirements section of the New Atlanta website may say:

iPlanet Web Server (iWS) 4.0 and higher

but that does NOT mean iWS 6.0.
It means iWS 4.x (major version stays the same).

Also note the following facts about Sun's webserver:

Sun's website indicates that Sun's
webserver was callled "iPlanet" for v6.0, v6.0sp1, & v6.0sp2, and that beginning with v6.0sp3, it was no longer
called "iPlanet Web Server" but was instead called "Sun ONE Web Server".

All versions of iPlanet/SunONE 6.0, ship with (and use by default) JVM 1.2.2

If you do not want your SE NSAPI instance to use the iWS 6.0 default JVM (1.2.2) then:
You should edit the iWS script named "start-jvm" (found in the .../https-admsrv/bin/ folder, to change the
NSES_JRE line (likely the 2nd line in that file) so that it points to the JVM you want ServletExec NSAPI to use.
For example, change:
NSES_JRE=/usr/SUNWwbsvr608/bin/https/jre;export NSES_JRE
to be:
NSES_JRE=/usr/java;export NSES_JRE (where /usr/java points to the JVM you want SE NSAPI to use).
Note that this will also be the JVM that iWS 6.0 will use (for it's admin console) so be sure to use a JVM
version that iWS 6.0 supports. At the time of this writing Sun says that iWS 6.0sp1 added support for JVM 1.3.1.
Higher versions of JVM may not be supported by your iWS 6.0 installation, consult Sun's documentation for
more details regarding your specific service pack level of iWS 6.0.

With SunONE 6.1, the manner in which you configure the webserver so that SE NSAPI will use a JVM other than the webserver's default one is different than how it's done for iWS/SunONE 6.0.

If you're using Sun ONE 6.1, then here is some information about the JVM it
comes with and uses by default, and 1 way to change which JVM is used by an
SE NSAPI instance:

SunOne 6.1 webserver comes with JVM 1.4.1_03.
This is specified in: <server-home>/https-<instance-name>/config/server.xml
where the javahome variable may be defined with a value such as this (for example):
/export/home/sunone61/bin/https/jdk/
That version of JVM (and JVM 1.4.0_03 too) has a bug which prevents certain
XML parsing code to work properly. For example, in testing we've seen XML
parsing tags provided in the JSTL fail with errors such as:java.lang.VerifyError: Cannot inherit from final class
This problem can be resolved by editing the SunOne server.xml file to use
/usr/java as the value of javahome, where /usr/java points to JVM 1.4.2 (or
which ever JVM you wish your Sun ONE instance to use).

NOTE: One customer reported that they were able to get SE 4.2 NSAPI working fine with iWS 6.0 (using JDK 1.3.1) on several Solaris boxes, but had problems with the iWS 6.0 failing to startup at all on just one single box (SIGILL). They eventually found the solution themselves and described it as follows:

... If the iPlanet Application Server is installed on the same machine as iPlanet Web Server, an incompatible version of the libsmartheap.so installed by the Application Server will be called by the iWS Web Server during startup. After renaming this .so, the iWS can now be started up without error.

Faq ID

191

Product

ServletExec

Category

Installation, Web Server Support

Question

Does ServletExec support Windows 2003 with IIS 6.0 ?

Answer

Yes.
ServletExec 5.0 (both ISAPI and AS) has been tested with Windows 2003 (and 2003 sp1) and it works fine.
The New Atlanta website ran with SE 5.0.0.13 ISAPI on IIS 6 on Windows 2003sp1 for over 3 years beginning in 2004 and it worked just fine. In early 2008 that site was updated to run SE 6.0 AS on IIS 6 Windows 2003 R2.
Therefore this is officially supported.

If it does not work for you, then please go through each and every step in SE FAQ #7 (for both ISAPI & AS).

Note: In some cases, SE 4.2 may seem to work with IIS 6, however some have reported problems, and as indicated on the System Requirements Page, that combination (SE 4.2 with IIS 6) is not offically supported.

The AS versions of ServletExec determine which JDK or JRE to use based on the java command specified in the StartServletExec run script/batch file that is used to invoke the ServletExec Java application.

If you have SE AS installed and running, but then wish to change the version of JVM that it runs with, do this:

If on Windows, view the Add/Remove programs dialog and take note of the Java items listed there.

Install the JVM you wish to use

If on Windows, refresh the Add/Remove programs dialog and take note of the new Java items listed there.

Stop your SE AS instance

Hand-edit the StartServletExec & StopServletExec scripts (2 files) for your SE AS instance so that they point to the desired JVM.

Note that with StartServletExec you'll also need to ensure that it is pointing to the proper tools.jar file (JDK/SDK only)

Save the changes and then start your SE AS instance.

Use SE FAQ #129 to confirm that your SE AS instance is now
running with the desired JVM version.

(Optional) If nothing else uses the previous JVM version then you may uninstall it.

Faq ID

11

Product

ServletExec

Category

Installation, VM Settings

Question

How does ServletExec/NSAPI on Solaris determine which JDK or JRE to use?

Answer

This FAQ was written with iPlanet 4.x & NES 3.5.1 in mind.
If you are using iPlanet 4.x or NES 3.5.1 as your webserver, and SE NSAPI as your servlet engine, then consider using the information given in this FAQ when configuring your webserver. If you are using iPlanet 6.x, or a version of Sun's webserver that is branded as "SunONE", or "Java System Webserver", then please consider using FAQ #221 instead when configuring your webserver.

The Netscape/NSAPI version of ServletExec determines which JDK or JRE to use based on the value of the LD_LIBRARY_PATH variable in the server start script. If LD_LIBRARY_PATH points to JDK or JRE 1.1 then the JNI_VERSION variable must be set to "1.1" in the start script, otherwise JNI_VERSION must be set to "1.2". Note that with iWS 6.0, on Solaris, it appears that the LD_LIBRARY_PATH value in the iWS instance's start script gets overridden when that start script calls the .../https-admsrv/bin/start-jvm script. See SE FAQ #221 (link given above) to learn how to work around this iWS 6.0 quirk.

Overview:
With SE NSAPI on Solaris, SE's native code (which is "hooked into" iPlanet) will use the LD_LIBRARY_PATH evironment variable that's setup and exported in the iPlanet start script, together with any JVM options that you have configured via the SE admin pages (which get written to VMSettings.pref), to crank up the JVM.

To learn which version of JVM your SE NSAPI on Solaris is using, access SE's admin UI and view the "VM Settings" page. There it will tell you with which version of JVM SE is running.

If you want to change the JVM that SE NSAPI on Solaris uses, then please see section 4.5.2 of the SE Installation Guide where it says:

If you choose to run a different JDK or JRE version than the one available when
ServletExec/NSAPI was originally installed, you may need to modify the start script and
change the various settings of LD_LIBRARY_PATH as needed.

Faq ID

313

Product

ServletExec

Category

Installation, Web Server Support

Question

I am trying to determine the "level" at which the ServletExec Filter is "hooked into" my IIS installation. How do I do that?

Answer

The SE installer will place the SE filter into IIS at the "Global" level of IIS. The only way it would be somewhere else is if you (or someone else) had manually removed it from the global level and then added it at
the level of some individual IIS website. If you feel this may have occured in your case, then it may be worth checking.

The idea is to check both the "Global" or "Master" level for all of IIS. And then to also check the level of each individual website. To check the Global filters do this:

Right-click on My Computer and choose "Manage".
This will bring up the Computer Management dialog.

At the bottom of the left pane you should see a node named "Internet Information Services"

Click the plus sign for that node to expand it.

If using IIS 5.0 or newer, then right-click on the node named "Web Sites" and choose "Properties"

If using IIS 4.0 or older, then right-click on the node for your server, choose "Properties", and then click the
"Edit..." button next to the "Master Properties: WWW Service" value

Now go to the ISAPI Filters tab to see the Global ISAPI Filters.

To check the filters for each individual website do this:

Right-click on My Computer and choose "Manage".
This will bring up the Computer Management dialog.

At the bottom of the left pane you should see a node named "Internet Information Services"

Click the plus sign for that node to expand it.

If using IIS 5.0 or newer, then expand the node named "Web Sites"

If using IIS 4.0 or older, expand the node for your server

At this point you should see your websites listed beneath the node that you just expanded (this may only be
1 website named "default website" or it may be a long list of websites... it depends on how many websites you have)

To check a website, right-click on its name and choose "Properties" then go to the ISAPI Filters tab for that website.

Repeat the previous step for each of your websites (note that FTP and SMTP are NOT websites)

Faq ID

141

Product

ServletExec

Category

Installation, Web Server Support

Question

I am trying to get ServletExec AS to work with the Apache web server that came with my Unix Operating System, or was obtained through my OS vendor, or was bundled with some other software and it won't work. What am I doing wrong?

Answer

The problem is that the Apache web server that comes-with / is-packaged-by / is-bundled-with some vendor's OS or software package is not tested/certified by New Atlanta. Therefore New Atlanta cannot guarantee that it will work.

For example the Apache that comes with Red Hat Linux is not a standard Apache distribution. The Red Hat Linux Installer places components of that Apache in several different folders on the drive in a non-standard manner (in ways that the SE installer may not expect). You should use RPM to completely remove that Apache (or at least turn it off) and then download a regular Apache distribution from
http://www.apache.orgin source code form. To build and install an Apache from it's source you need a GNU C compiler and PERL. See FAQ #14 for more details about that, but typically the specific steps to build Apache are as follows:

rm src/support/apxs is only needed if you are rebuilding a previously built apache

The value of the --prefix parameter (/usr/local/apache in the example above) is where the apache will be installed. You could specify most any location that you wish.

The --enable-module=so part is what enables DSO support within Apache.

They are also in the SE Installation Guide (and probably in the Apache documentation as well.)

Once Apache is installed and working (test that it can serve you a simple helloWorld.html file), follow the SE AS Installation Instructions in the appropriate version of the ServletExec Installation Guide in order to get SE AS running with the standard Apache you just installed.
NOTE: Be sure to build Apache with DSO support before installing ServletExec (as discussed in the ServletExec Installation Guide).

Another example has been seen with HP-UX 11i.
The Apache 1.3.27 that comes from HP's Depot website has been reported to us by one customer as not working with SE 5.0 or SE 4.2.
For HP-UX we recommend that you use an Apache distribution from:http://www.apache.org instead of from HP's Depot.

Yet another example would be an Apache that's bundled with Oracle AppServer.

Faq ID

179

Product

ServletExec

Category

Installation, Web Server Support

Question

I am unable to install SE AS 4.1.1 on Windows with Apache. Why ?

Answer

The SE AS installer on Windows looks at registry entries in order to figure out which version of Apache is installed, where it resides, etc...

If using the Windows installer for SE 4.1.1 AS:
If the installer is complaining that only Apache 1.3.9 - 1.3.23 is officially supported (when in fact up to Apache 1.3.26 is offically supported) then this is a bug in the SE 4.1.1 installer (which has been fixed in the SE 4.2b1 installer).
It can be easily worked around in the following manner:

Start - Run - regedit

In the left pane of the Windows Registry Editor, browse to:
HKEY_LOCAL_MACHINE\SOFTWARE\Apache Group\Apache

Right click on that key and choose New - Key

The name of the new key needs to be "1.3.23" (no quotes)

In the left pane, left-click once on the new key that was just created to open it, showing its contents in the right pane.

In the right-pane, right-click on nothing and choose New - String Value

The name of the new string value should be "ServerRoot" (no quotes)

Right-click on that string value and choose Modify.

In the Value Data field type the absolute path to your Apache 1.3.26 installation. For example:
C:\Program Files\Apache Group\Apache1.3.26\Apache

Hint: you can examine the ServerRoot key of your:
HKEY_LOCAL_MACHINE\SOFTWARE\Apache Group\Apache\1.3.26
key and even copy its ServerRoot key value to your clipboard
to ensure that you setup the 1.3.23 key to be the same as your 1.3.26 key.
Then run the SE 4.1.1 installer.
It should be tricked into thinking that a supported version of Apache is installed and proceed without errors.

Note: You cannot do this with Apache 2.x.
Apache 2.x has a completely different architecture than Apache 1.3.x. Apache 2.x on Windows is not supported by ServletExec 4.x in any manner. It is however possible to run SE 4.2 with Apache 2.x on Unix if you obtain and install the patched SE AS adapter for Apache 2 on Unix. See FAQ #195 for more information.

If using the Windows installer for SE 4.2 AS:
The installer for SE 4.2 AS on windows is hard-coded to support as high as, Apache 1.3.27.
But let's say you want to install it with Apache 1.3.28.
Just do the registry trick described above, only create a dummy key for 1.3.27 instead of 1.3.23. It's the same concept... the installer is hard-coded up to the highest Apache version that was currently available at the time of its release.
Note: You cannot do this with Apache 2.x.
Apache 2.x has a completely different architecture than Apache 1.3.x. Apache 2.x on Windows is not supported by ServletExec 4.x in any manner. It is however possible to run SE 4.2 with Apache 2.x on Unix if you obtain and install the patched SE AS adapter for Apache 2 on Unix. See FAQ #195 for more information.

If using the Windows installer for SE 5.0 AS:
When installing against an newer version of Apache 1.3.x or 2.x, the installer will display a warning but will still allow the install to continue. So with SE 5.0, it should install and work with newer versions of Apache as long as Apache is not modified in a way that breaks ServletExec.

Faq ID

336

Product

ServletExec

Category

Installation

Question

I downloaded a ServletExec installer for Unix/Linux, but it won't run at all. It seem to be corrupted. What's wrong?

Answer

The symptoms of this problem are as follows:

You download and run the SE installer, and the installer starts off OK, outputing some startup messages.

But then the installer exits with output that goes something like this (for example):

Most likely, your browser is corrupting the file.
Most likely, the problem is that your browser is configured to treat files that end in ".sh" as ASCII.
Normally that would be OK, since most files that end in .sh are ASCII.
But the ServletExec installers for Unix/Linux are comprised of both ASCII and Binary data.
Therefore, the entire file should be treated as Binary.

Here are our suggestions:

configure your browser to treat files that end in .sh as Binary, so that when the browser downloads the file, it will do so correctly.

-OR-

Use an FTP client, set to Binary mode, to connect to ftp.newatlanta.com
and download the installer you want from the /public/servletexec/ area.

Faq ID

192

Product

ServletExec

Category

Installation

Question

I need to install ServletExec on my Windows OS as an unattended (silent) installation. How do I do this?

Answer

In order to install ServletExec 6.x or 5.x as a silent/unattended installation, perform the following steps:

Create a response file by running the installer with the following
options:
ServletExec_AS_60.exe /r /f1"C:\temp\setup.iss"

Then run the installer in silent mode by executing:
ServletExec_AS_60.exe /s /f1"C:\temp\setup.iss"

Notes:

There is no space after /f1

The above steps work with SE 6.x and SE 5.x (any configuration).

The path to the .iss file and the name you give to that .iss file may be anything you wish.

In order to install ServletExec 4.x as a silent/unattended installation, perform the following steps:

Launch the ServletExec windows installer so that
the installer data is extracted to disk.

Go to <drive>:\Documents and Settings\<user>\Local Settings\Temp
and look for a folder that was just recently created and contains
a Disk1 subfolder. The Disk1 folder contains a copy of the
extracted installer so copy the Disk1 folder to someplace else.

Cancel the installer. Note that this will delete the extracted
installer data from the Document and Settings folder. That's why
you needed to make a copy of it in the previous step.

Using a DOS window, go to the Disk1 folder and launch Setup.exe
with the -r option. This will record the responses in a file
called Setup.iss and place it in the Windows or WINNT folder.

Move Setup.iss to the same directory as Setup.exe.

Run Setup.exe with the -s option. This will run InstallShield in
silent mode using the responses from Setup.iss. The results of the
install will be logged in Setup.log.

Faq ID

7

Product

ServletExec

Category

Installation

Question

I've installed ServletExec with Microsoft IIS but it doesn't work. What can I do to verify my installation?

Answer

Perform the following steps to verify your installation of ServletExec (either ISAPI or AS) with Microsoft IIS:

If using IIS 7 (2008/Vista) and SE ISAPI then see section 1.2.1.1 of the SE 6.0 User Guide.

If using IIS 6.0, IIS 5.0, or IIS 4.0, you can completely stop IIS by stopping the IIS Admin Service from the Services Control Panel or by using the stop_iis.bat command file (located in the bin folder where ServletExec was installed) or by using the Restart IIS command from the Internet Services Manager.

For SE AS and IIS see section 1.2.2 of either the SE 6.0 User Guide, or the SE 5.0 User Guide.

Verify that a valid JDK or JRE is installed on your machine. If not, then reinstall the JDK or JRE.

Make sure the SE DLL file [ServletExec_ISAPI.dll or ServletExec_Adapter.dll] is installed in the ...\InetPub\Scripts directory.

Follow the steps in Chapter 2 of the Installation Guide to verify ServletExec is configured as an ISAPI filter and that it is has the correct path to ServletExec_ISAPI.dll [or ServletExec_Adapter.dll] If you had previously installed a different servlet engine then verify it is not configured as an ISAPI filter (you can't have two servlet engines installed as ISAPI filters or they'll conflict).
The ServletExec Filter should show with a Green Arrow pointing up.

If using SE ISAPI, then read all of FAQ #60 (especially the last half of that FAQ) and follow the 8 steps given there. FILE PERMISSIONS ARE THE MOST COMMON REASON FOR SE ISAPI INSTALLATION PROBLEMS

If using IIS 6 (Win 2003, SE 5.0 or higher) then you should also check the Web Service Extensions listed in the Internet Service Manager to ensure that ServletExec is listed as a Web Service Extension whose status is "Enabled". Here you should also open the properties of that Extension and view the "Required Files" tab to ensure that the path to the ServletExec DLL file shown there is correct. In other words, make sure that IIS is pointing to a path that actually exists on your hard drive.
If using IIS 7 (Win 2008/Vista) then please read section 2.5.3 of the SE 6.0 Installation Guide.
You should also ensure that the user specified as the application pool identity for ServletExec has read/write permission to BOTH:

The SE installation directory (and all it's subdirectories and subfiles)

The SE DLL file and the folder in which it resides

Here is how to figure out what user were talking about:

In the Internet Service Manager, open the Properies dialog for "Application Pools"

Find the User on the "Identity" tab. In our tests this was the User named "Network Service" in the drop-down list associated with the radio button labeled "predefined"

Then check physical file permissions on the SE installation directory and all its subdirectories and subfiles to ensure that that user has read/write permission

Verify that each IIS web site which needs to use ServletExec has a virtual directory (VD) with the following Execute Permissions:

"Scripts and Executables" if using IIS 5.0 or higher (Win 2k, 2003)

"Execute (including script)" if using IIS 4.0 (Windows NT)

For SE ISAPI, this VD could have any name you wish. Traditionally it is named "Scripts", but could be named "ServletExec" or whatever else you like. If using SE AS, this VD *must* be named "Scripts".
For more details please read section 2.5.3 of the SE 6.0 Installation Guide.
Note: This is not a physical folder on your hard drive.The VD must map to the physical directory which contains SE DLL file (by default this is the ...\InetPub\Scripts\ directory). You can verify that the VD is pointing to the correct physical folder by opening the Microsoft Management Console (also called the Internet Service Manager or the MMC) and selecting the VD in the left pane for each IIS web site. In the right pane you should see ServletExec_ISAPI.dll or ServletExec_Adapter.dll for each IIS website that you want to use SE.

Verify the SYSTEM account, IUSR_xxx account (and if using BASIC authentication... the account that will be assigned to the ServletExec admin pages) has read/write access to all of the files and directories under the ...\InetPub\Scripts\ directory. You may also need to check this for the web.xml files used by your web applications (or .war file(s) if your apps are in .war file form).
In fact you should consider performing the 8 steps given in FAQ #60 using the group named EVERYONE as a test to rule out file permissions as the problem.

For IIS 4.0 only, open the Properties dialog for the VD and verify that the 'Name' parameter under the Application Settings header is not greyed out. If it is greyed out, then select Create, Apply and OK. If you are unable to do this then most likely you have a bad installation of IIS 4.0. Customers who have seen this problem have fixed it by re-installing IIS 4.0 and ServletExec.

Launch the DBMON application that is installed with ServletExec. Restart the IIS admin service. If error messages appear in the DBMON console then send them to support@servletexec.com. Note that you should at least see some ServletExec initialization messages. The only exception to this is if you are using Windows 2003 (formerly called Windows .NET) in which case you won't see any SE startup messages until IIS receives its first request, so in that case you'd need to open your web browser and try requesting one of the following URLs:

Note that DBMON will not show you anything if you are accessing the machine remotely via terminal services or possibly other remote access software. See FAQ #187 for more information about this and a workaround.

If your not running DBMON remotely, then use the Event Viewer to check for web server error events. If you find any then send the data to support@servletexec.com.

If there are no error messages and ServletExec shuts down after the first request then give Everyone Full Control permission to the physical Scripts folder and the SE DLL file. Then, reinitialize ServletExec. If this fixes the problem, you can fine-grain permissions as discussed in section 2.7 of the ServletExec 4.x or 5.x Installation Guide.
Note that if the JVM is able to start up then any messages seen in DBMON may also appear in ServletExec.log with the added benefit of timestamps.

If you have tried all of the things above and yet you are still seeing 1 or more of the following symptoms:

The response you get in your browser after requesting a servlet includes the words ServletExec Initialization Failed

DBMON shows SE shutdown messages at the moment you make a servlet request, showing that SE was shutdown by IIS, abruptly due to the request

then there may be a setting within you IIS that needs to be changed.
To find out, and to set it correctly, you should perform the following steps at both the Global/Master IIS level and also at the individual website level (for each website):

In the IIS manager access the "Home Directory" tab

On that tab click the "Configuration..." button

The checkbox there labeled "Cache ISAPI Applications" should be checked. If it isn't then check/enable it.

Repeat the 3 steps above in all the various locations within the IIS manager [both the Master IIS level and the individual website level(s)]

Then cycle the IIS admin service and try to request a servlet

If you've tried everything above, and still your SE does not work with IIS, then you should review FAQ #280 to see if it applies in your case.
Note that FAQ #280 was written with the installer in mind, but the whole "DEP" concept may still be the culprit that's preventing your IIS (or SE) from running properly after it's been installed.

Special Note to those trying to use SE ISAPI with IIS 6 on Win 2003:

If you have gone through all the steps above, and are certain that everything is as it should be, and yet
your attempts to run a servlet result in the following sort of response in your browser:
"The page cannot be found"
(with HTTP 400 - Bad Request at the bottom of the page)

Then you should consider trying this:

Access the IIS Management Console

Right-click on "Web Sites" and open its Properties dialog

On the "Service" tab of that dialog check "Run WWW service in IIS 5.0 isolation mode"

Save the change, and then stop the IIS admin service

Start your IIS website and try to request a servlet

We recommend that this approach be used as a last resort only, since we've only had 3 customers
report that it was even needed. It is our belief that these steps would only be needed in very
rare cases, and it is our experience that the steps given in the main body of this FAQ
clear up the more common SE ISAPI problems seen by users.

Faq ID

14

Product

ServletExec

Category

Installation

Question

I've installed ServletExec/AS with Apache on UNIX but it doesn't work. What can I do to verify my installation?

Answer

Verify that a valid JDK or JRE is installed on your machine.

Verify the JAVA_HOME environment variable is not set. If it is set then verify it is correctly set to the installation directory of the JDK or JRE you are using.

Verify that Apache 1.3.x or 2.0.x (or 2.2.x if using SE 6.0 or higher) is installed.
And make sure that it is a supported Apache distribution as described in FAQ #141
Also make sure that your Apache was built with DSO support enabled.

The method to use to determine if DSO is installed in an Apache build is to run the command:
<apache-executable> -l
where <apache-executable> may be "Apache.exe" on Windows or "httpd" on some UNIX, etc.
If the result of this command shows something like the following ("mod_so.c" is required):

Verify that you are using a supported C-compiler.
Here's a quote from section 6.2.1 of the SE 5.0 Installation Guide (System Requirements section):

In addition to a JDK 1.3-, or 1.4-compliant VM, these installations require an ANSI C compiler (GNU version 2.8.1 or higher preferred. Vendor-specific C compilers are not supported) and a system-specific dynamic shared object loader.

Your apxs should contain:
my $CFG_CC = q(gcc);NOTmy $CFG_CC = q(cc);
If you don't have GCC installed then get GCC installed, and then execute the steps for rebuilding your APXS (given below in this FAQ)

If the ServletExec installer failed to compile the mod_servletexec.c file then verify the compiler and link-editor specified by $CFG_CC and $CFG_LD_SHLIB in your apxs script are in your PATH. If they are then verify your apxs script doesn't begin with:

#!no-perl-on-this-system

If it does then you need to install PERL on your system and you need to rebuild apxs as described below. If it doesn't then make sure it doesn't look as follows:

If it does then your apxs script needs to be updated. This occurs (often) when Apache is initially configured without shared module support (the default configuration) and then re-configured and rebuilt with shared module support. Since the makefile that creates apxs from apxs.pl depends only on the sources, apxs will not be updated when you re-configure. You should remove apxs from your source tree, remake and reinstall to get a fully configured/operational apxs. Note: you cannot remake and then copy the apxs--it is modified further in the configuration process.

To rebuild apxs from the source execute the following commands:

cd <apache-src-dir>
rm src/support/apxs
make
make install

If your apxs script is correct and you are using the Sun compiler then the problem is mod_servletexec.c contains C++ style comments. To fix this edit your apxs script and add the -xCC option to the definition of $CFG_CFLAGS so that the Sun compiler will accept C++ style comments. Re-install ServletExec after making this change.
See Section 6.2.3.1 of the SE 5.0 Installation Guide for more details

Stop the ServletExec application by invoking the StopServletExec script and stop the web server if they are running.

Verify the httpd.conf file has been updated as described in Chapter 6 of the Installation Guide.

Restart the web server.

Restart the ServletExec application by invoking the StartServletExec script. If error messages appear in the console or in ServletExec.log then send them to support@servletexec.com. Note that you should at least see some ServletExec initialization messages.

Try the following URLs:

/servlet/DateServlet
/servlet/TestServlet

If these don't work then look for error messages in the ServletExec.log file and send them to support@servletexec.com.

Faq ID

9

Product

ServletExec

Category

Installation

Question

I've installed ServletExec/AS with Apache on Windows but it doesn't work. What can I do to verify my installation?

Answer

Perform the following steps to verify your installation of ServletExec/AS with Apache on Windows NT:

Verify that a valid JDK or JRE is installed on your machine. If not, then reinstall the JDK or JRE.

Verify that Apache 1.3.9, 1.3.11, 1.3.12 or 1.3.14 is installed.

Stop the ServletExec application by invoking StopServletExec.bat or by stopping it from the Services Control Panel if it was installed as a service.

Stop the web server.

Verify that httpd.conf has been updated as described in Chapter 5 of the Installation Guide.

Restart the web server.

Restart the ServletExec application by invoking StartServletExec.bat or by starting it from the Services Control Panel if it was installed as a service. If error messages appear in the DOS console or in ServletExec.log then send them to support@servletexec.com. Note that you should at least see some ServletExec initialization messages.

Try the following URLs:

/servlet/admin
/servlet/DateServlet
/servlet/TestServlet

If these don't work then look for error messages in the ServletExec.log file and send them to support@servletexec.com.

Faq ID

8

Product

ServletExec

Category

Installation

Question

I've installed ServletExec/NSAPI with Netscape Enterprise Server (NES)/iPlanet on Windows NT, but it doesn't work. What can I do to verify my installation?

Answer

Perform the following steps to verify your installation of ServletExec/NSAPI for NES/iPlanet on Windows NT:

Verify that a valid JDK or JRE is installed on your machine. If not, then reinstall the JDK or JRE.

and verify that it contains the correct path to the following directory:

'installation directory'\https-'server name'

If you had previously installed other servlet engines then verify they have been uninstalled. This includes any changes that were made to obj.conf for the other servlet engines.

Launch VerifyObjConf.bat, which is located in the following directory:

'installation directory'\https-'server name'

Check the generated Verify.log file for error messages. If there are any then send them to support@servletexec.com.

Stop the web server.

Launch the DBMON application that is installed with ServletExec.

Restart the web server. If error messages appear in the DBMON console, ServletExecNative.log or ServletExec.log then send them to support@servletexec.com. Note that you should at least see some ServletExec initialization messages. If you don't see any messages then use the Event Viewer to check for web server error events. If you find any then send the data to support@servletexec.com.

Try the following URLs:

/servlet/admin
/servlet/DateServlet
/servlet/TestServlet

If these don't work then look for error messages in the DBMON console, ServletExecNative.log and ServletExec.log and send them to support@servletexec.com.

Faq ID

13

Product

ServletExec

Category

Installation

Question

I've installed ServletExec/NSAPI with Netscape/iPlanet on Solaris but it doesn't work. What can I do to verify my installation?

Answer

If you are using Solaris version 2.5.1, verify you have the following patch installed:

ftp://sunsolve.sun.com/pub/patches/104283.readme

ftp://sunsolve.sun.com/pub/patches/104283-04.tar.Z

Also verify that you have the 2 patches installed that solve native thread synchronization problems. Information about these 2 patches can be found at:

http://java.sun.com/products/jdk/1.1/solaris-product-comparison.html

The showrev -p command can be used to list the patches installed on a system.

If you are using Solaris version 2.6, verify you have the following patch installed:

ftp://sunsolve.sun.com/pub/patches/105181.readme

ftp://sunsolve.sun.com/pub/patches/105181-06.tar.Z

The showrev -p command can be used to list the patches installed on a system.

Verify you have the latest production release of the JDK installed along with any patches it requires.

Verify other servlet engines were uninstalled before ServletExec was installed. This includes any changes that were made to obj.conf for the other servlet engines.

Verify MaxProcs is not set to greater than 1 in magnus.conf. ServletExec currently doesn't support more than 1 NES process.

Verify the Java Interpreter has been disabled and all of its directives removed from obj.conf as described in Chapter 4 of the Installation Guide.

Verify the server start script has been modified as described in Chapter 4 of the Installation Guide.

Verify the obj.conf file has been modified as described in Chapter 4 of the Installation Guide.

Verify the JAVA_COMPILER environment variable is not set. If it is, then it will override the ServletExec JITC setting on the VM Settings admin page.

Verify the JAVA_HOME environment variable is not set. If it is, then verify it is correctly set to the installation directory of the JDK or JRE you are using.

Stop the web server.

Restart the web server. Look for error messages in these log files:

.../https-'server name'/logs/errors

ServletExec.log

Send any error message to support@servletexec.com. Note that you should at least see some ServletExec initialization messages.

ServletExec 4.1.1 is the first version of ServletExec that has been successfully tested on Windows XP using IIS.
Newer versions of ServletExec support Windows XP also.
However, there is a Security Options configuration change necessary in order to allow access to the Security tab for setting correct file permissions on the ServletExec ISAPI folder.
From the Control Panel, navigate as follows:

Note that it may be neccessary to view the Control Panel in "classic view" in order to see the Administrative Tools.

Then double-click the Policy named"Network access: Sharing and security model for local accounts."
Change the Security Setting to:"Classic - local users authenticate as themselves."

Now, when you right-click on the ServletExec ISAPI folder, and choose Properties, you should see the Security tab.

Faq ID

194

Product

ServletExec

Category

Installation, Web Server Support

Question

Is ServletExec supported with Apache 2.0.x?

Answer

ServletExec 5.0 officially supports Apache 2.0.x on various Windows and Unix platforms. Please see the System Requirements area of this website for specific Operating Systems and versions.

ServletExec 4.x on Unix also supports Apache 2.0.x with a little extra effort on your part. Here is some background:
Apache 2.0.x uses a completely different architecture/API than Apache 1.3.x

On the Windows operating system, ServletExec 4.2 is not supported with Apache 2.0.x
On a Unix operating system however, SE 4.2 should work with some added effort.
You must:

Run the ServletExec 4.2 AS installer against Apache 1.3.x.(Note: This is the only time that you will run the SE installer)
This is done in order to get an SE AS Java instance installed and running. Turn it and your Apache 1.3.x on, and make sure you can run /servlet/TestServlet.
Now you can shutdown your Apache 1.3.x but leave SE up and running.

Download mod_servletexec2.c and the ReadMe.txt which describes how to install it against Apache 2.0.x(way at the end of the ReadMe).

Edit the httpd.conf file of your Apache 2.0.x so that it contains the neccessary ServletExec-specific directives (discussed in the SE 4.2 Installation Guide, and also present in the httpd.conf of your Apache 1.3.x assuming that you allowed the installer to update httpd.conf for you)

Now startup your Apache 2.0.x and try to access /servlet/TestServlet

Faq ID

400

Product

ServletExec

Category

Installation

Question

My ServletExec AS 6.0 installation on Windows 2003 with IIS 6 is not working, how can I verify my installation?

Answer

Verify you installed ServletExec using the latest installer. The latest installer is ServletExec_AS_60a.exe. If you didn't use the latest installer then un-install ServletExec, download the latest installer from the New Atlanta website and re-install ServletExec using the latest installer.

SE AS 6.0 is installed as 2 components: an adapter for IIS and a ServletExec service which uses java.

When testing ServletExec, you should use a browser running on the same machine as IIS and ServletExec to rule out any network or firewall issues.

To verify IIS is running:

Use a browser to hit an html page in the C:\InetPub\wwwroot directory. If you place a hello.html file in this directory then you can serve it up using a browser on the same machine by entering the URL http://127.0.0.1/hello.html.

To verify the ServletExec service is running properly:

Open the Services control panel and verify the ServletExec-<instance name> service is running. If the ServletExec service fails to start then check the Event Viewer for errors.

If there are no errors and it says it is ready to process requests then it is running properly.

If it contains a java.net.SocketException then some other process might be listening on the port that ServletExec is trying to use. You can determine the port ServletExec is trying to use by finding the line that sets "sePort" in StartServletExec.bat. The default value is port 8888. You can tell if a process is already listening on port 8888 by invoking the command "netstat -a -o -b" and looking for an entry that has a Local Address of 0.0.0.0:8888 and a state of LISTENING. The PID column will give the process ID of the process that is listening on the port and the next line will give the name of the process. If ServletExec is listening on the port then the process name will be [java.exe] since ServletExec is a java application.

If the ServletExec service is not running then there may be a permissions problem. By default the ServletExec service runs under the Local System account. Trying having it run under an administrator account to see if that solves the problem. This can be done by right-clicking on the ServletExec service in the services control panel and selecting Properties. Select the Log On tab and then select this account setting it to an administrator account and password. Select Apply and OK. You'll need to restart the ServletExec service after making this change.

If the ServletExec service failed to start and a ServletExec.log file wasn't generated then check the Java VM being used by ServletExec by following these steps:

Edit StartServletExec.bat to see what jvmHome is being set to. It should be set to something like this "C:\Program Files\Java\jdk1.6.0_14".

From a command prompt, enter the following command with the double quotes: "<jvmHome value>\bin\java" -version.

If the Java VM is installed properly then you should see output like the following: java version "1.6.0_14".

If the Java VM is not installed properly then edit StartServletExec.bat and StopServletExec.bat to point to a properly installed Java VM. If one isn't installed then you'll need to download and install it.

If your Java VM looks good and the ServletExec service still fails without generating a ServletExec.log file then follow these steps:

From a command prompt, invoke the StartServletExec.bat file.

If you receive the following error message then most likely your Java VM is corrupt and you'll need to uninstall and reinstall it: "Exception in thread "main" java.lang.NoClassDefFoundError: ServletExec, Could not find the main class: ServletExec. Program will exit." If you reinstall the Java VM to a different location then you'll need to edit the StartServletExec.bat and StopServletExec.bat files to point to the new location for the Java VM.

For all other error messages, send them to support@newatlanta.com and we'll try to help you figure out what is going wrong.

If all of the previous steps passed then the final step in verifying the ServletExec service is to try to telnet to the service using the following steps:

Open a command prompt window.

Type "telnet 127.0.0.1 8888" and enter. NOTE: replace 8888 with the port ServletExec is using if it isn't using port 8888.

If the window goes blank and you see a blinking cursor at the top of the window then the ServletExec service is running properly. Hit enter twice to break the connection to ServletExec.

If you see "Connecting To 127.0.0.1...Could not open connection to the host, on port 8888: Connect failed" then either the ServletExec service isn't running or a firewall is preventing connections to the port ServletExec is using.

To verify the IIS adapter is installed properly:

Verify ServletExec_Adapter.dll was installed to C:\InetPub\Scripts. If your version of Windows is 32-bit then the size of this DLL should be 296KB. If your version of Windows is 64-bit then the size of the DLL should be 485KB.

If you are on a 64-bit machine then verify the Application Pool is set to run in 64-bit mode (the default). If it has been set to run in 32-bit mode then you'll need to replace the 64-bit ServletExec_Adapter.dll with the 32-bit version in C:\InetPub\Scripts.

Verify in IIS that a Scripts virtual directory exists under the web site you are trying to hit and it maps to C:\InetPub\Scripts. Check its properties to make sure the Execute permissions are set to Scripts and Executables.

Verify ServletExec is listed as a Web Service Extension with a status of Allowed. You should also view the extensions properties and verify Required Files points to C:\InetPub\Scripts\ServletExec_Adapter.dll.

Verify ServletExec_Adapter.dll is listed as an ISAPI filter. This is done by right-clicking on Web Sites in inetmgr and selecting Properties. Select ISAPI Filters tab and verify ServletExec shows up as a filter. Note that the ServletExec filter will have an unknown status and priority until the first servlet or JSP request is processed.

If all of these look correct and the problem still occurs then check the Event Viewer for errors.

You can also check for adapter error messages by using DBMON if you are logged in locally to the server or DebugView if you are logged in remotely using remote desktop. In order to use DebugView you'll need to download and install it from http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx. Here are the steps:

Double-click on DBMON.EXE which can be found in the ServletExec installation directory or launch DebugView. If you are using DebugView then you'll need to set Capture\Capture Global Win32 from the DebugView menus. Note that DBMON and DebugView should not be running at the same time.

Restart the IIS Admin Service from the Services Control Panel.

From a browser, enter the URL http://127.0.0.1/servlet/TestServlet.

If the adapter was loaded properly then you will see messages like the following:

My ServletExec AS 6.0 installation on Windows 2008 with IIS 7 is not working, how can I verify my installation?

Answer

Verify you installed ServletExec using the latest installer. The latest installer is ServletExec_AS_60a.exe. If you didn't use the latest installer then un-install ServletExec, download the latest installer from the New Atlanta website and re-install ServletExec using the latest installer.

Make sure the ISAPI Extensions and ISAPI Filters features are installed. If they are not installed then IIS will never load the installed ServletExec DLL and servlet requests will result in 404 responses. These two Windows features may be enabled as follows:

Control Panel - Programs - Programs & Features - Turn Windows features on or off

Check the checkboxes to enable ISAPI Extensions and ISAPI Filters. You will then at least need to restart the IIS Admin Service, and possible even reboot Windows.

SE AS 6.0 is installed as 2 components: an adapter for IIS and a ServletExec service which uses java.

When testing ServletExec, you should use a browser running on the same machine as IIS and ServletExec to rule out any network or firewall issues.

To verify IIS is running:

Use a browser to hit an html page in the C:\InetPub\wwwroot directory. If you place a hello.html file in this directory then you can serve it up using a browser on the same machine by entering the URL http://127.0.0.1/hello.html.

To verify the ServletExec service is running properly:

Open the Services control panel and verify the ServletExec-<instance name> service is running. If the ServletExec service fails to start then check the Event Viewer for errors.

If there are no errors and it says it is ready to process requests then it is running properly.

If it contains a java.net.SocketException then some other process might be listening on the port that ServletExec is trying to use. You can determine the port ServletExec is trying to use by finding the line that sets "sePort" in StartServletExec.bat. The default value is port 8888. You can tell if a process is already listening on port 8888 by invoking the command "netstat -a -o -b" and looking for an entry that has a Local Address of 0.0.0.0:8888 and a state of LISTENING. The PID column will give the process ID of the process that is listening on the port and the next line will give the name of the process. If ServletExec is listening on the port then the process name will be [java.exe] since ServletExec is a java application.

If the ServletExec service is not running then there may be a permissions problem. By default the ServletExec service runs under the Local System account. Trying having it run under an administrator account to see if that solves the problem. This can be done by right-clicking on the ServletExec service in the services control panel and selecting Properties. Select the Log On tab and then select this account setting it to an administrator account and password. Select Apply and OK. You'll need to restart the ServletExec service after making this change.

If the ServletExec service failed to start and a ServletExec.log file wasn't generated then check the Java VM being used by ServletExec by following these steps:

Edit StartServletExec.bat to see what jvmHome is being set to. It should be set to something like this "C:\Program Files\Java\jdk1.6.0_14".

From a command prompt, enter the following command with the double quotes: "<jvmHome value>\bin\java" -version.

If the Java VM is installed properly then you should see output like the following: java version "1.6.0_14".

If the Java VM is not installed properly then edit StartServletExec.bat and StopServletExec.bat to point to a properly installed Java VM. If one isn't installed then you'll need to download and install it.

If your Java VM looks good and the ServletExec service still fails without generating a ServletExec.log file then follow these steps:

From a command prompt, invoke the StartServletExec.bat file.

If you receive the following error message then most likely your Java VM is corrupt and you'll need to uninstall and reinstall it: "Exception in thread "main" java.lang.NoClassDefFoundError: ServletExec, Could not find the main class: ServletExec. Program will exit." If you reinstall the Java VM to a different location then you'll need to edit the StartServletExec.bat and StopServletExec.bat files to point to the new location for the Java VM.

For all other error messages, send them to support@newatlanta.com and we'll try to help you figure out what is going wrong.

If all of the previous steps passed then the final step in verifying the ServletExec service is to try to telnet to the service using the following steps:

Open a command prompt window.

Type 'telnet 127.0.0.1 8888' and enter. NOTE: replace 8888 with the port ServletExec is using if it isn't using port 8888.

If the window goes blank and you see a blinking cursor at the top of the window then the ServletExec service is running properly. Hit enter twice to break the connection to ServletExec.

If you see "Connecting To 127.0.0.1...Could not open connection to the host, on port 8888: Connect failed" then either the ServletExec service isn't running or a firewall is preventing connections to the port ServletExec is using.

To verify the IIS adapter is installed properly:

Verify ServletExec_Adapter.dll was installed to C:\InetPub\Scripts. If your version of Windows is 32-bit then the size of this DLL should be 296KB. If your version of Windows is 64-bit then the size of the DLL should be 485KB.

If you are on a 64-bit machine then verify the Application Pool is set to run in 64-bit mode (the default). On Advanced Settings page, the "Enable 32-bit Applications" setting should be set to false for the 64-bit DLL.

Verify in IIS that a Scripts virtual directory exists under the web site you are trying to hit and it maps to C:\InetPub\Scripts. Check its properties to make sure the Feature Permissions are set to Read, Script and Execute. You can check this in inetmgr by selecting the Scripts virtual directory and then double-clicking on "Handler Mappings". If ISAPI-dll is disabled then right-click on it and select "Edit Feature Permissions". Select "Execute" and click on OK.

Verify ServletExec is listed as allowed on the ISAPI and CGI Restrictions page and the path to ServletExec_Adapter.dll is correct. You can check this in inetmgr by selecting the server and then double-clicking on "ISAPI and CGI Restrictions".

Verify ServletExec_Adapter.dll is properly configured as an ISAPI filter. This is done by:

Selecting the "Default Web Site" in inetmgr and double-clicking on "ISAPI Filters". Verify ServletExec appears as a filter.

If all of these look correct and the problem still occurs then check the Event Viewer for errors.

You can also check for adapter error messages by using DBMON if you are logged in locally to the server or DebugView if you are logged in remotely using remote desktop. In order to use DebugView you'll need to download and install it from http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx. Here are the steps:

Double-click on DBMON.EXE which can be found in the ServletExec installation directory or launch DebugView by right-clicking on it and selecting "Run as administrator". If you are using DebugView then you'll need to set Capture\Capture Global Win32 from the DebugView menus. Note that DBMON and DebugView should not be running at the same time.

Restart the IIS Admin Service from the Services Control Panel.

From a browser, enter the URL http://127.0.0.1/servlet/TestServlet.

If the adapter was loaded properly then you will see messages like the following:

My ServletExec AS installation is missing the webadapter.properties file, how can I manually create this file?

Answer

You can create this file in the ServletExec AS config directory with the following content. The default location for the ServletExec AS config directory is C:\Program Files\New Atlanta\ServletExec AS\config.

Note that you must replace <instance name> with the name you gave your ServletExec instance at installation time.

You'll need to restart IIS after updating/creating the webadapter.properties file.

# This file contains the configuration properties used by the ServletExec # adapter. These properties are used by the adapter for routing HTTP
# requests from the web server to a ServletExec Application Server (AS)
# instance.
#
# For every incoming request to the web server, the ServletExec adapter # applies the following algorithm to determine if the request should be
# forwarded to a ServletExec AS instance for processing:
#
# 1. Using the host name (plus port) of the incoming HTTP request, find all
# ServletExec AS instances that are configured to process requests for the
# designated host + port as defined by the
# servletexec.<instance name>.hosts properties.
#
# 2. For the ServletExec AS instances identified in step 1, if the incoming
# request URL matches an application context path, forward the request
# to the ServletExec AS instance defined by the
# servletexec.<instance name>.instances properties.
#
# This file can be configured with the following global properties:
#
# servletexec.handlerType -- the type of handler the ServletExec instances # communicate with. The value ".net" indicates a .NET handler while the
# value "native" indicates a C or C++ handler. The default value is "native".
#
# servletexec.aliasCheckInterval -- the minimum number of seconds for the # polling of instances to determine if their web application data has been
# modified. This allows the adapter to be automatically updated when an # instance's web application data is modified. To disable this polling set
# this value to -1.
#
# Each ServletExec AS instance can be configured with the following
# properties, where <instance name> is the unique name of a
# ServletExec AS instance:
#
# servletexec.<instance name>.hosts -- a comma-separated list of IP
# addresses or host names. The value of "all" may be specified to indicate
# that the instance will process requests for all virtual hosts. Other
# examples are: "www.newatlanta.com", "www.abc.com:9090",
# "192.168.200.17", or "192.168.200.43:8000".
#
# servletexec.<instance name>.instances -- the IP address and port
# number of the ServletExec AS instance, used by the adapter for
# forwarding HTTP requests to the instance. Each instance must have a # unique IP address/port number pair; the default is "127.0.0.1:8888".
#
# servletexec.<instance name>.pool-increment -- the number of
# connections that will added to the connection pool when a connection is
# needed and the pool is empty. These connections are used by the
# adapter to communicate with the instance.
#
# servletexec.<instance name>.pool-max-idle -- the maximum number
# of idle connections that can be present in the connection pool. These
# connections are used by the adapter to communicate with the instance.

On Windows, how does ServletExec/ISAPI and ServletExec/NSAPI determine which JDK or JRE to use?

Answer

This information can be found in the ServletExec Installation Guide.
For example in both the SE 5.0 & 4.2 Installation Guides, it can be found in section 2.2.3.1
Here is some of that information:

The very first time that ServletExec ISAPI or NSAPI on Windows starts up it must do so using Sun Microsystem's JVM.
ServletExec determines which JDK or JRE to use by looking at the JavaSoft entries in the Windows registry. It first looks for a JDK/SDK.
If a JDK is not found it then looks for a JRE.
ServletExec looks for a JDK by checking the following registry entries (in the given order):

HKLM\SOFTWARE\JavaSoft\Java Development Kit\CurrentVersion
HKLM\SOFTWARE\JavaSoft\Java Development Kit\<version-number>\JavaHome

ServletExec looks for a JRE by checking the following registry entries:

You can verify that a JDK or JRE is installed on your machine by performing the following steps:

To verify that a JDK is properly installed, use Regedit to check the JavaSoft registry entries. The following registy entry should contain the JDK version number (for example, "1.5", or "1.4", or "1.3"):

HKLM\SOFTWARE\JavaSoft\Java Development Kit\CurrentVersion

The following registy entry should contain the path to the installation directory for the JDK (for example, "C:\j2sdk1.4.0"), where <version-number> is the value from the CurrentVersion registry entry, above:

HKLM\SOFTWARE\JavaSoft\Java Development Kit\<version-number>\JavaHome

To verify that a JRE is installed, check the JavaSoft registry entries. The following registry entry should contain the JRE version number (for example, "1.5", or "1.4", or "1.3"):

HKLM\SOFTWARE\JavaSoft\Java Runtime Environment\CurrentVersion

The following registry entry should contain the path to the installation directory for the JRE (for example, "c:\program files\javasoft\jre"), where <version-number> is the value from the CurrentVersion registry entry, above:

Verify the JAVA_HOME environment variable is not set. If it is set, then verify it is correctly set to the installation directory of the JDK or JRE you are using, based on the JavaSoft registry entries as described above.

Once ServletExec is initialized and running with the Sun JVM for the first time, you can then choose to use the IBM JDK on the VM Settings page of the ServletExec Admin UI. If the IBM JDK is selected then the next time ServletExec is initialized it will look for the IBM JDK or JRE by checking the IBM registry entries in the manner described in the ServletExec Installation Guide. If one isn't found then it will try to find a Sun JDK or JRE.

The last version of ServletExec to support the Microsoft VM was SE 3.1.
If you are using SE 3.1 and the Microsoft VM is selected on the VM Settings admin page of the SE admin UI, then the next time ServletExec is initialized it will look for the Microsoft VM by trying to load C:\WINNT\System32\msjava.dll. If it can't, then it will try to find a Sun JDK or JRE.

Faq ID

271

Product

ServletExec

Category

Installation

Question

What URL must I use to access the main SE Admin pages?

Answer

Version of ServletExec

URL to use

5.0 or higher

http://<hostName>/servletexec/admin

4.2 or older

http://<hostName>/servlet/admin

In addition, if you installed SE on a windows machine then you could just go:
Start - Programs - New Atlanta - ServletExec - ServletExec Admin

The URL to use to access the Main SE admin UI is also documented in the SE User Guide (which comes with your installed version of SE, in the "Documentation" folder).

Faq ID

142

Product

ServletExec

Category

Installation

Question

When I try to run a servlet or a JSP, my browser prompts me to download a file. What is wrong?

Answer

This can occur if running ServletExec with the IIS web server, and the Virtual Directory [VD] (usually named 'Scripts') that is defined in the IIS website and which points to the ServletExec DLL, either does not exist, or does not have the proper permissions.
Note that this is not a physical folder on your hard drive whose permissions are set via Windows Explorer. This is a virtual folder that is defined in the IIS website and therefore viewable and editable via the Microsoft Management Console (a.k.a. Internet Services Manager).

For Windows 2000 the permission must be:
"Scripts and Executables"

For Windows NT the permission must be:
"Execute (including script)"

NOTE: These permission settings are NOT checkboxes. Here is what to do (with IIS 5 or IIS 6 for EXAMPLE):

Right-click on "My Computer" and choose "Manage"

Expand "Services & Applications"

Expand "Web Sites"

Expand your specific website

Right-click on the Virtual Directory and choose "Properties"

Access the "Home Directory" Tab.

Locate the next to lastdrop-down list (it is labeled "Execute Permissions" and configured it as described above.

Save the change and then re-request the servlet or JSP

When this problem occurs, check ServletExecNative.log and/or DBMON for a message indicating that the VD does not have the right permissions. Step #7 of SE FAQ #7 also discusses how to do this, as does the ServletExec Installation Guide.

Note that other symptoms of the VD not existing, or not being configured properly may include:

A response that indicates "System Path is not Found"

A 404-Not Found response coming from IIS

In general... you request something from ServletExec (a servlet or JSP) and the response indicates that it was IIS that tried to serve what was requested and of course... failed in some manner.

If none of the above helps you get past this problem, then try deleting the Virtual Directory from your IIS website and then recreating it with the same name, pointing it to the same place, and giving it the required permission settings.

Faq ID

359

Product

ServletExec

Category

Installation

Question

When using multiple SE AS Instances, response time is very slow. What's wrong?

Answer

This FAQ applies to SE 5.x and higher.
To fully understand and diagnose this issue, it's helpful to first understand
some basics about how the SE AS native adapter (which "hooks into" the web server
software), and SE AS Instance(s) communicate with each other.

The adapter reads in a file named webadapter.properties which tells the adapter about
the various SE AS instances (ASI's) that are available.

The adapter attempts to communicate with each ASI listed in that file in order to learn the rules
for routing requests (which requests should be routed to which ASI's).

Any ASI is that not running, or otherwise unreachable can cause significant response-time delays.

You can alter the behavior of the adapter by using the multiInstanceMode global property, so that the adapter
is less effected by this condition and so the delay is no longer a problem.
Here is some useful information about the aliasCheckInterval global property:

servletexec.aliasCheckInterval

The default value is 10 (measured in seconds).
Setting it to -1 turns it off, so that there is no request-time polling.
An example of using this property in webadapter.properties is:
servletexec.aliasCheckInterval=20
This global property governs how often the adapter will ping/query the SE AS
instances (ASIs) that are defined in that file, to ask them if there are any changes
to the aliases (webapp context paths, uri mappings for security, filters, servlets,
etc...). The adapter stores a local copy of such mappings in what is referred to as
an Alias Cache (1 alias cache per ASI) and periodically attempts to update that
cache (at request time) if warranted.
If an ASI is not running and the adapter tries to ping/query it, there may be a
timeout delay before the socket knows that there is nothing at the
other end to respond to the ping/query. This is usually 1 second, but may differ depending on OS, and other factors. If there are several ASI's that are not running or are otherwise unreachable then the delay is increased proportionally (1 second delay for each ASI that's down). This situation can be avoided by enabling the
multiInstanceMode property (see below).
For additional details about the aliasCheckInterval property, please see
SE FAQ #259

Now you have enough information to better understand the multiInstanceMode global property:
servletexec.multiInstanceMode

The default value is disabled.
An example of using this property in webadapter.properties is:
servletexec.multiInstanceMode=enabled
Enabling multi-instance mode will cause the adapter to:

only ping an unresponsive ASI every aliasCheckInterval seconds (rather than
continually trying to ping it on every request in an attempt to update its
outdated/expired alias cache).

clear the in-memory alias cache for any ASI that becomes unresponsive.
This provides better support for using SE in a failover/clustered environment. It
allows the request to "filter down" to the other ASI's or the webserver itself
rather than giving Failed To Connect to ServletExec messages over and over.
Just be aware that you may get 404 Not Found responses in this case.
To confirm that your adapter is running in multi-instance mode, look for the
presence of the following line in your adapter's startup messages:
This adapter will run with multi-instance optimizations.

And one way to test just how quickly responses are being rendered on the server would be to
request a simple JSP which simulates sending back some data, and times itself too.
For example a JSP that contains only this:

With IIS 7.x (Win 2008 or Vista) how do I ensure the Scripts VD has the proper permissions?

Answer

ServletExec AS requires that a proper VD named Scripts be defined within each IIS website that wishes to use SE. The procedure for giving the Scripts VD "Execute" permission is different with IIS 7.x than it is with IIS 6. A detailed explanation along with screenshots is given in section 2.5.3 of the ServletExec 6.0 Installation Guide.
The information in that section was originally written with SE ISAPI in mind, but it still applies to (and is needed by) SE AS. The main difference is that with SE AS the name of the DLL file is ServletExec_Adapter.dll

Faq ID

259

Product

ServletExec

Category

Installation

Question

With more than 1 instance of SE 5.x AS (or higher) running behind a single
webserver, how does the SE AS native adapter decide which requests should be
routed to which SE AS Java Instance (ASI)?

Answer

Prior to SE 5, this was accomplished by specifying the aliases to be
handled by each ASI in a file that contains the adapter's configurations.
Depending on which webserver you were using, that file was:

servletexec.properties (for IIS)

httpd.conf (for Apache)

obj.conf (for SunONE/iPlanet)

With SE 5 the way that the adapter is configured has been normalized
across the various supported webservers to make ongoing maintenance of a
multi-ASI setup easier, and also to increase webserver uptime.
Beginning with SE 5 AS, the native adapter's configurations go in
webadapter.properties no matter which supported webserver is used.
The adapter first learns about the hostnames and ASI's by reading webadapter.properties.
It then uses that information to open a TCP socket to each ASI and ask each one what it's
webapp context paths (i.e. aliases) are.
So with SE 5.0 the aliases information is no longer recorded in any file for use by the native adapter.
Some general facts about SE 5.x AS to keep in mind while attempting to understand
the remainder of this FAQ:

*Everything* (i.e. all your servlets, JSPs, html files, etc... ALL resources)
will reside (and be executed) within the context of some webapp (WEB-INF folder, web.xml).
That may be the default-app that comes with each ASI or it may be some custom webapp that you have deployed.

There is no "Legacy" (i.e. non-webapp) context anymore (as there was with SE 4.x and older).
Even the SE Admin UI is now in a webapp named "servletexec" whose context path is "/servletexec" by default.

Each ASI that you install will automatically create and auto-deploy
(see the SE User Guide for details on auto-deployment) it's own private copies/versions of the following 2 webapps:

When the SE AS 5 native adapter gets the opportunity to look at a request
and decide *if* the request is meant for an ASI, and if so *which* ASI:
it will use the combination of hostname[:port] PLUS application context path of the request in order to make that decision (this is true for ALL versions of SE AS).
The adapter learns the hostname portion of the routing rules from webadapter.properties.
The Adapter learns the context path (alias) portion of the routing rules by using a socket to speak to the ASI and
ask it "What are all the context paths for all the webapps that you have deployed?"
This "pinging" is configurable via the aliasCheckInterval property in webadapter.properties.

So... if you intend to have more than 1 ASI and you wish to use the EXACT same hostname to access any/all of them then here is what you must do:

Get all your ASI's installed, start each of them once, and then turn each of them off.

Go find the top-level folder for each ASI's servletexec webapp on the hard-drive.
This will be in the auto-deploy folder for each ASI, For example:

Now if you request:
http://<hostname>/servletexec1/admin you'll be accessing the admin UI for instance #1
and if you request:
http://<hostname>/servletexec2/admin you'll be accessing the admin UI for instance #2
Basically since hostame is the same, the context paths must be unique.
The combination of hostname[:port] PLUS context path must be unique in order for the adapter to route the request to the right ASI.

Since ASI #1 is the only ASI that has a webapp whose context path is "/servletexec1" and since ASI #2 is the only
ASI that has a webapp whose context path is "/servletexec2", the adapter knows which ASI should get the request.

Once you can access each individual admin UI, then you can deploy "/myWebapp1" onto one of the ASI's and
deploy "/myWebapp2" onto one of the other ASI's. And there is no need to make edits to any properties file
(easier to maintain) and no need to bounce the webserver (more webserver uptime).

Note: If you were wanting to use a unique hostname for each ASI, then you would NOT need to change the context path of the
servletexec admin UI webapp as step #2 above says. Or more generally, you would NOT need to ensure that context paths
were unique across all ASI's. Instead you would edit webadapter.properties and change the "hosts"
value for every ASI listed there, from "all" to a specific hostname such as www.mydomain1.com or www.mydomain2.com depending on which hostname you want which ASI to handle.
You'd then save the change and bounce the webserver (so that the adapter would read in changes).
This would satisfy the requirement that hostname[:port] PLUS context path be unique, and would allow you to use the exact
same context paths in ASI #1 as are used in ASI #2.

Summary
If you startup your 2nd instance of SE 5.x AS, then it will create and deploy it's own default-app and servletexec webapps.
But you will most likely be unable to access the SE Admin UI webapp for that 2nd instance (or any other webapp deployed inside it) without first configuring the SE AS native adapter and then bouncing your webserver. You configure that adapter by configuring the webadapter.properties file.
This is because most likely your adapter configuration file (webadapter.properties) is currently configured to route ALL requests (no matter what hostname is used) to the 1st instance.
For more details about this, please read the previous sections of this FAQ.
If you wish to use unique hostnames to access each ASI, then here is a guideline for the structure of your webadapter.properties file:

You don't ever have to use .hosts=all if you don't want to.
But if you do use it, then it only makes sense for it to be used in the last group of properties (i.e. the last instance listed in that file).

Also, note that if you wish the webapp named "default-app" which is deployed on each of your ASI's to know which document root to use for each given hostname, then you must make use of the -root parameter in each ASI's Start script.
Good resources for learning about the -root parameter and how to use it include:

If you want your default-app(s) to know about any Virtual Directory mappings that might be defined in your IIS website(s) then you'd need to make use of the -addl parameter in your ASI's Start script, similar to how the -root parameter is used.

UPDATE about the -root and -addl parameters mentioned above:
They are obsolete as of the SE 6.0 September 2009 hotfix. Please see the release notes of that hotfix for more details.

Those using multiple instances of SE AS (5.x or higher) may also find SE FAQ #359 to be of interest.

Internationalization

Faq ID

116

Product

ServletExec

Category

Internationalization, JSP

Question

How can I use ServletExec to send a response to the client using a character set other than English (i.e. International Content / Localized Content) ?

Answer

For servlets

Call response.setContentType( "text/html; charset=utf-8" );

Call PrintWriter writer = response.getWriter();

Pass the writer Unicode characters.

For JSPs

In the JSP page, use a page directive to set the content
type like this (example shown is for Chinese):<%@ page contentType = "text/html;charset=big5" %>

NOTE: This indicates the charset for both the JSP page itself as well as the
content that is sent back to the browser.
This means that you will have to author your JSP page using a text editor
that will allow you to save the JSP with the specified charset.

I'm using a custom client to transmit characters of a less common encoding and the characters are not correct. What's wrong?

Answer

Firstly, you should read of SE FAQ #128 to see if that applies in your case.
If it does not apply, then consider this:

Your custom client (JavaScript or other) might not be URL-Encoding the request parameters before sending them to your Servlet/JSP.
This can cause the parameters to become "munged" on the server-side... often causing them to display as question marks.
For further details please read SE Interest List Posting #221269
(Note that URL-encoding and HTML-encoding are 2 different things.)

Faq ID

128

Product

ServletExec

Category

Internationalization

Question

When I call request.getParameter() I always get a String whose character encoding is ISO-Latin-1. But that is not the correct encoding for the parameters. What can I do?

Answer

Here is a high level explanation of what is happening:
ServletExec receives each request parameter as an array of raw bytes.
Because there is no way for ServletExec to know what character encoding was used for
the request parameters (a META tag will not do the trick), it converts each byte array
into a Java String (16 bit Unicode) using "ISO8859_1" as the character encoding.

If you are using the ServletExec 5.x September 2007 hotfix (or a newer version of ServletExec such as SE 6.0) then you have 2 options:

Use the setCharacterEncoding()
method of the ServletRequest interface (introduced in the Servlet 2.3 Specification).
See that specification and the Servlet 2.3 Javadocs for information regarding correct usage of that method.

-OR-

Pass a System property to the JVM at JVM startup time.
For example to change the default request encoding from 8859_1 to UTF-8:
-Dcom.newatlanta.servletexec.request.url.encoding=UTF-8Then calls to request.getParameter() will return UTF-8 encoded Strings.
NOTE that *both* the parameter names & parameter values will have the same
encoding so in the above example, the String you pass to getParameter() must be encoded using UTF8. NOTE: This feature is tracked via bug #2792

If you are using ServletExec 4.x you should use the setCharacterEncoding()
method of the ServletRequest interface (introduced in the Servlet 2.3 Specification).
See that specification and the Servlet 2.3 Javadocs for information regarding correct usage of that method.

If you are running ServletExec 3.1 or older then here are some possible workarounds:

Edit servers.properties so that it includes the line:
servletexec.request.params.charset=<character-encoding>
For example:
servletexec.request.params.charset=UTF8
Then whenever you call request.getParameter() you'll receive a String whose character encoding is UTF8 instead of the default Latin-1.

After calling request.getParameter(), thus obtaining a String whose character encoding is Latin-1, re-encode the String by:

converting it back into a byte array with:
byte[] bytes = parameterValue.getBytes("ISO8859_1");

creating a new String object from the byte array using whatever character encoding you need:
paramValue = new String(bytes, "<character-encoding>");

If you are using ServletExec 4.0 or newer you should not use the SE 3.1 workaround mentioned directly above.
Although it may actually work, using it with SE 4.x or newer is not recommended.

If this FAQ does not solve your issue, then you may very well benefit from reading SE FAQ #360
Readers of this FAQ may also benefit from reading SE FAQ #116

JDBC

Faq ID

178

Product

ServletExec

Category

JDBC

Question

Does ServletExec support the use of JDBC 2.0 DataSources ?

Answer

Yes.
Simply put the appropriate classes, such as:

jdbc2_0-stdext.jar

the JDBC driver classes for your database

into the appropriate ServletExec classpath and create an instance of the DataSource object and then use it.
If you wish, you may place your DataSource instance into a JNDI context so that your other code running inside of ServletExec can look it up and use it.
Beginning with version 4.0 of ServletExec, the ability to Manage your DataSources from the Main ServletExec Admin UI was added. With that version of ServletExec (and all higher versions), ServletExec provides an initial JNDI context into which your configured datasources will be automatically added.
Your code could then lookup the DataSource using the following syntax:

If your database is MS SQL Server, then you should consider using
New Atlanta's JTurbo JDBC Driver. The versions for JDBC 2.1 and for JDBC 3.0 have Connection Pooling capabilities built right in, ready for use.

Faq ID

22

Product

ServletExec

Category

JDBC

Question

Why can't the JDBC-ODBC bridge find my data source?

Answer

Make sure your data source is configured as a System DSN and not a User DSN.

Faq ID

18

Product

ServletExec

Category

JDBC

Question

Why does ServletExec keep crashing when I use a JDBC driver?

Answer

If you are using a JDBC driver which uses native methods then this may be your problem. You should try to find a pure Java (type 4) JDBC driver for your database.

Faq ID

17

Product

ServletExec

Category

JDBC

Question

Why does ServletExec keep crashing when I use the JDBC-ODBC bridge?

Answer

The JDBC-ODBC bridge contains native code, leaks memory, is not thread-safe, and was never meant to be used in a production environment. You should try to find a pure Java (type 4) JDBC driver for your database.

JSP

Faq ID

315

Product

ServletExec

Category

JSP

Question

All my JSP pages are compiled. How can I now turn off any further JSP compilation?

Answer

If all your JSPs have been requested at least once (causing SE's JSP Engine to compile each one)
and you are now wanting to "lock" them all by preventing any further compilation (even if they
are modified, or new JSPs are added) then here is how to do that:
Use the compiler init parameter with the JspServlet (named "JSP10Servlet" for SE versions prior to SE 5.0).
This means you would need to configure the JspServlet inside your web app. The class it would need to map to is:

com.newatlanta.servletexec.JspServlet (SE 5.x and newer)

com.newatlanta.servletexec.JSP10Servlet (SE 4.x and older)

and its configuration will only "stick" if you give it at least one init parameter (in this case you would use the
compiler init parameter with the value of none).
Note that with every webapp deployed in SE, both:

The servlet named JspServlet (JSP10servlet for SE versions prior to SE 5.0)
AND

The *.jsp suffix alias mapping to it

are already automatically (and implicity) added for you.
This is why you must provide at least one init parameter when you manually configure that servlet in order to override its implicit configuration. It is also why these instructions to do not tell you to map *.jsp to that servlet (since it has already been done for you implicitly).

compare the newly generated stacktrace to the one saved in step #1 (take note of the line numbers given in both stacktraces... look for differences)

If you find that the new trace gives slightly different line numbers then most likely you just need to follow the new trace to figure out what's going wrong in your code.
If you want further details then please read on:

Read section "JSP.11.3" entitled "Buffering" in the JSP 2.1 Specification. Here is a relevant clip from that section:

The JSP container buffers data (if the jsp directive specifies it using the buffer
attribute) as it is sent from the server to the client. Headers are not sent to the client
until the first flush method is invoked. Therefore, it is possible to call methods that
modify the response header, such as setContentType, sendRedirect, or error methods,
up until the flush method is executed and the headers are sent. After that point,
these methods become invalid, as per the Servlet specification.

Often, the error seen when this problem occurs is something like:
java.lang.IllegalStateException: reset() failed - data has already been sent to the client.
With SE 5.x and newer, the general symptoms may be described as follows:
You request a JSP page (which names an error handler) and a certain amount of the response is sent to the browser (possibly enough response such that the response looks fine to the naked eye). But before the request can totally complete *all* of its processing something goes wrong in the JSP (or in a JSP that it includes). The something that goes wrong could be a NullPointerException or really any other sort of Exception (basically a typical programming error). At that point the error handling mechanism kicks in... SE attempts to forward to the configured error handler. You can look in the ServletExec.log file and see if the stacktrace includes any mention of handlePageException or perhaps this message (possibly on multiple lines):

error page could not be sent because some data has already been sent to the client

Basically, once the Headers have been sent to the browser for a
particular response, more headers cannot be sent for that same response (a forward or redirect require new/different response headers).
So attempts to perform a forward or a redirect will fail once the response buffer has been flushed. Often the line numbers given in the stacktrace produced under these conditions are not helpful as they don't report the root cause. Note that
<jsp:include page="..." flush="true"/> will flush the response buffer causing the response headers to be sent to the browser. Therefore, attempts to utilize the JSP error page directive within an included (and flushed) JSP will always fail.

Here is information about how to troubleshoot the underlying problem in this situation:

The default size of the response buffer for a Servlet or a JSP is 8k. When it becomes filled, ServletExec will automatically flush it to the client. If necessary, you can increase the size of the buffer by using a page directive [in a JSP] <%@page buffer="2000kb"%> for example... would set the buffer size to 2mb which may or may not be a large enough buffer to allow the natural error handling mechanism to function as expected, or by calling response.setBufferSize() [in a servlet]. This will delay the automatic flushing of the response buffer. For more information about this see section 6.5 of the Servlet 2.2 Specification (2nd paragraph).
You should also take a look at the JavaDocs for the forward()
method of javax.servlet.RequestDispatcher where it says that java.io.IllegalStateException is thrown if the response was already committed.
Another way to see what the true, underlying problem was, is to wrap your JSP code in a try-catch block, catching Throwable.
Then in the catch block call:t.printStackTrace(System.out); so that the trace will be written to ServletExec.log.

JSP error page processing performs the following basic tasks:

catch any uncaught Exception or Error by catching Throwable

forwarding the request to the named error page (which fails in the manner described above if the response has already been flushed)

If you have a JSP that uses a page directive to name an errorPage, look at the Servlet that was generated from the JSP in a plain text editor. There you will see how Throwable is caught and handlePageException() is called which attempts to perform the forward.

Yet another way to possibly learn what the true, underlying problem was is to use a page directive and set the autoFlush attribute to false.

Faq ID

136

Product

ServletExec

Category

JSP

Question

How can I prevent the JSP Engine of ServletExec from compiling JSPs again after I have restarted ServletExec?

Answer

For ServletExec 3.1 or newer:
Across restarts, ServletExec does maintain a record of the last time a JSP was modified. ServletExec accomplishes this by writing a property file to the hard drive.
The name of the file is jsptimestamps.properties.
Each time SE starts up it compares what's in that file to the JSPs on the hard drive to determine if a JSP will need to be compiled again when requested.
If the JSP is outside a Web App then jsptimestamps.properties gets placed into the Servlets folder.
If the JSP is inside a Web App then jsptimestamps.properties gets placed into:
...\ServletExec Data\<SE Virutal Server Name>\<webApp name>\
The default behavior of JSP10Servlet in SE 3.1 and newer is that the init parameter named "compileAfterRestart" is set to false, which means that after SE restarts, it does NOT recompile JSPs unless the requested JSP has a newer timestamp than it did before the SE restart.
If you wish to prevent this behavior and have your JSPs compiled after every SE restart, then pass the JSP10Servlet the init parameter named
"compileAfterRestart" whose value is "true".

For ServletExec 3.0E or older:
Across restarts, ServletExec does not maintain a record of the last time a JSP was modified. Each time ServletExec initializes, it assumes each
requested JSP is new, and therefore re-compiles each JSP the first time it is
requested. At one point it was possible to pass the JSP10Servlet the init
parameter named "compileAfterRestart" with a value of "false" but that
feature was disabled in SE 2.2 due to unwanted side-effects.
As a result, the only way to prevent ServletExec 3.0E or older from compiling JSPs is to pass the JSP10Servlet an init parameter named "compiler" whose value is "none". Of course this will prevent ServletExec from compiling ANY JSPs at all.

Faq ID

31

Product

ServletExec

Category

JSP

Question

How can prevent my JSP page(s) from creating a session object?

Answer

By default, a JSP page will create a session object when it is requested. If your JSP has no need to use/access the session object, then you can reduce some overhead by adding the following statement to your JSP page(s):

<%@ page session="false" %>

Faq ID

28

Product

ServletExec

Category

JSP

Question

I want to use a compiler other than the default javac compiler from Sun for compiling my JSP pages. How do I do that with ServletExec 3.0 or greater?

Answer

Pass the JSP10Servlet 2 init parameters, one named compiler whose value is the path to the compiler you want to use, and one named compileCommand which is used to give the compiler any extra arguments it may need such as classpath, verbose, etc...

For example to get the example JSP hangman.jsp working with IBMs Jikes compiler on a windows machine you would configure JSP10Servlet to take the following init parameters:

NOTE: The value of ServletExecXX.jar will depend upon which version of ServletExec you are using. For example, with ServletExec version 3.1 the value would be ServletExec31.jar.

NOTE: You must also include all necessary classes in the classpath option that's passed to the alternate Java Compiler via the compileCommand init argument of JSP10Servlet.

Faq ID

151

Product

ServletExec

Category

JSP, Security, Web Application

Question

If I request a JSP page that does not exist I receive a response in my browser which discloses the absolute path to my web server's document root or to the document root of my web application. Isn't this a security risk?

Answer

Perhaps.
If you are concerned by this, then you have a few different choices to resolve it:

If you are using a Web Application then map the 404 status code to whatever resource you wish on the Error Pages mapping page of your web app's admin UI.
This is the best option since it is totally spec.-compliant and therefore portable. Be certain that your "Location" value begins with a slash (/) otherwise the mapping won't work.

Use the errorPage init parameter with the JspServlet (named "JSP10Servlet" for SE versions prior to SE 5.0) so that it will no longer use the default response which discloses the path.
Note that if you are running within a Web Application, this means you would need to configure the JspServlet inside your web app. It would need to map to:

com.newatlanta.servletexec.JspServlet (SE 5.x and newer)

com.newatlanta.servletexec.JSP10Servlet (SE 4.x and older)

and its configuration will only "stick" if you give it at least one init parameter (in this case you would use the errorPage init parameter).
Note that this method will not protect against the case where people invoke the JspServlet (or JSP10Servlet) directly as in:
http://<host-name>/servlet/com.newatlanta.servletexec.JspServlet
since that URI causes the JSP engine to run in its non-configured state (no init parameters). To prevent that, please apply the techniques described in SE FAQ #354.

If you are not using a web application, but are instead using what we term the "Legacy Context", then use the Main ServletExec Admin UI to set a
Global error page that will be used for the entire ServletExec Virtual Server.
This would be done on the "Configure Server" subpage of the "Manage Servers" admin page. This option is only valid for ServletExec 4.2 and older. The Main Admin UI of SE 5.x may present you with the ability to configure a global error page as described above, but doing so will have no effect in SE 5.x (SE 6.x removes this setting on that main admin page).

If you can't use the SE 4.2 admin UI to do this then edit the servers.properties file (inside the ServletExecData folder) and then bounce SE.
For example if the name of the SE Virtual Server is "default" and the error page URI being configured is "/yo.jsp" then this line in that file:
servletexec.default.errorpage=
would be changed to:
servletexec.default.errorpage=/yo.jsp

Faq ID

334

Product

ServletExec

Category

JSP

Question

My JSP pages that use JSTL tags are not working right. What's wrong?

Answer

If you are seeing an error in your ServletExec.log file that looks something like this:
attribute value cannot have a request time expression value
Then you might benefit from reading:
this SE Interest List posting

Faq ID

99

Product

ServletExec

Category

JSP, Miscellaneous

Question

What is a JSP ?

Answer

JSP is an acronym which stands for Java Server Page.
A JSP is essentially an HTML document that has java code or special tags included. A JSP can only be run inside a Servlet/JSP Engine.
When the Engine receives a request for a JSP, the engine will perform the following actions:

Parse the requested .jsp file and convert it into a servlet, saving the result to .java source file.

Compile the generated Servlet into a .class file.

Load the servlet class file into the JVM, instantiate an instance of the servlet and invoke the appropropriate Servlet API methods to service the request (send the response).

This is sometimes caused by a bug in the JITC. Disable the JITC from the ServletExec admin UI and then reinitialize ServletExec to see if this fixes the problem.

Faq ID

139

Product

ServletExec

Category

JSP

Question

When I request a JSP, the response I get mentions a FileNotFoundException what is wrong?

Answer

For example, if you were running SE ISAPI and you had requested
http://localhost/hello.jsp
and the response looked something like:
ServletExec: caught exception - java.io.FileNotFoundException: C:\Program Files\New Atlanta\ServletExec ISAPI\Servlets\pagecompile\_hello_xjsp.java (The system cannot find the path specified)
The problem is that after SE converted hello.jsp into a servlet named _hello.xjsp.java
it was unable to write that .java file to the drive at the location specified in the stacktrace.
Make certain that ServletExec has read and write permission for the Servlets folder and also for the ServletExec Data folder (and all of its subfolders).
In the case of SE ISAPI, read SE FAQ #60, and perform the 8 steps given there.

Faq ID

388

Product

ServletExec

Category

JSP

Question

Where does ServletExec look for TLD files?

Answer

SE looks for TLD files within the structure of the web application as follows (in this order):

Directly under Under WEB-INF or any subfolder under WEB-INF

Inside any JAR file under WEB-INF\lib. Specifically within each JAR in that lib folder it looks for /META-INF/*.tld

Think of a TLD the same as you do a JSP or an image or html file.
Or the web.xml file (probably a better analogy since those are both "descriptors").
It needs to be inside the app structure.
This differs from a .class or .properties file which may either be inside the app or on the main classpath.
Confusion may come (for the humans) with the fact that a .jar file may
contain non-classpath items such as a TLD file. The ability to place a TLD inside a JAR and have it be found is to simplify the act of handing someone your TLD-related code. For example the struts JARs include both Tag Handler code *and* their associated TLDs in 1 simple JAR package (keeping related things all in one place). In that case one could place such a JAR on the main SE classpath instead of inside a webapp so that all apps could share it. However each app would need to include its own copy of the TLD files.

Faq ID

24

Product

ServletExec

Category

JSP

Question

Why are .class files generated in the Servlets/pagecompile directory for the bean classes used by my JSP pages?

Answer

This will occur if the .java files for your bean classes are in the classpath. Remove them from the classpath and this will no longer happen.

Faq ID

23

Product

ServletExec

Category

JSP

Question

Why can't my JSP page find my bean/helper class?

Answer

First of all, make certain that the Bean/Helper class is visible to ServletExec, either by it's location on the hard-drive or by specifying it on the Main ServletExec Classpath:
For web applications, the class could be placed in the...\WEB-INF\classes\ folder
or in a JAR file placed at:...\WEB-INF\lib\

Or you could have the class reside in a "neutral" location (not inside a webapp) and add it to the Main SE Classpath where all webapps (and the Legacy context) can see it.
This would be the only option for JSPs running in the Legacy context (Legacy context is only possible prior to SE 5.0).
If your JSPs are running in the Legacy context, placing your helper classes in the Legacy Servlets folder won't help.

Secondly, you need to understand that a JSP is compiled into a Servlet, and with ServletExec, that servlet is declared to be part of the "pagecompile" package. So if your JSP wants to use a Bean/Helper class then you will need to add a page directive to your JSP, importing the package of the Bean/Helper class.

NOTE:

With JDKs prior to JDK 1.4:
If the bean/helper class is not in a package then you will need to add the following import statement to your JSP:

<%@ page import="<bean class name>" %>

With JDK 1.4 or newer:
Your bean/helper class MUST be part of a package. Otherwise, the java compiler will not compile the generated servlet, and will complain about expecting a '.' character in the name of the imported class.
With JDK 1.4 and newer, the Java compiler is more restrictive in this case.

Faq ID

26

Product

ServletExec

Category

JSP

Question

Why do I receive a ClassCastException when I try to use the JSP 1.0 extends attribute?

Answer

This problem occurs when the class you specified for the extends attribute doesn't implement the interface HttpJspPage. See section 3.2.4 of the JSP 1.0 or 1.1 specification for more details on exactly what requirements your class must meet.

Faq ID

30

Product

ServletExec

Category

JSP

Question

Why does my large JSP page fail to compile?

Answer

Java has a limit of 65535 bytes for a method. To work around this problem place large blocks of HTML in a separate file and include it using the <jsp:include> tag. Note that the include directive cannot be used in this case because it causes the contents of the file to be placed directly in the JSP page.

Faq ID

25

Product

ServletExec

Category

JSP

Question

Why isn't my bean with session scope being stored in the session?

Answer

This problem can occur if the bean tag appears in the JSP page after data has already been sent to the client. In this case the response header will be sent before the session id has been created for the JSP page. To work around this you should place the bean tag near the top of the JSP page or call getSession() near the top of the JSP page.

Known Limitations and Workarounds

Faq ID

55

Product

ServletExec

Category

Known Limitations and Workarounds

Question

After installing ServletExec/NSAPI, when I start up the server it says that ServletExec failed to initialize. What is wrong?

Answer

Using ServletExec 2.2 (and earlier) with JDK 1.2.2_05 on Solaris, you must set the min. heap size to 4Mb. This is done by editing the VMSettings.pref file so that minHeapSize=4000.

Faq ID

40

Product

ServletExec

Category

Known Limitations and Workarounds

Question

Can I invoke a native program from my Java code?

Answer

Yes.
This is typically done using code somewhat like this (for example):
java.lang.Process p = java.lang.Runtime.getRuntime().exec("C:\myNativeProgram.exe")
But there is much more to doing that than most people understand and it does require very careful coding and extensive testing.
A very common issue is when the native program being invoked is passed parameters and/or outputs data. It is not uncommon for code attempting this approach
to encounter hanging of the entire JVM.
The Javadocs for java.lang.Process indicate that using the standard input or output streams can cause deadlock and/or blocking
conditions. In New Atlanta's testing (using a standalone Java program... not ServletExec) it was observed that hanging would occur depending
on the options being passed to the executable being invoked (AppCmd.exe for example).
One way that we've found which works well to avoid hanging issues is to have your code write a batch file that redirects all output to a file. Then use Runtime.exec() to invoke that batch file. Your code may then go read the file that contains the redirected output.
We found this approach especially helpful when invoking native programs that output a lot of data.
java.lang.Process exposes 3 streams.
Any native program being invoked this way may or may not place data on any or all of those streams. Regardless of whether your code needs to use those streams, it
should always clean them up as follows:

Otherwise the JVM in which your code is running could suffer from a Resource leak which could cause erratic behavior and/or hanging or crashing.
Some have asked if it is possible to invoke StartServletExec.bat from their own java code.
While it may be possible to do this using the techniques described above, we do not recommend it.
The techniques described above would be for invoking relatively simple, "short-lived" programs. ServletExec is an Application Server which stays up and running (in the best case) forever. We do not believe that Runtime.exec() would be well-suited for invoking a long-lived program such as ServletExec.
If you wish to run some java code which itself starts up ServletExec (in an attempt to "wrap" ServletExec with your own java program) then here are some tips for doing that, but please understand that we've never tested it so we offer no guarantees:

Startup your Java program specifying the same "JVM options" as those used to startup your SE AS instance.
To understand what is meant by "JVM options" please see the bottom of SE FAQ #318 where it shows:
java [ JVM options ] classname [ program arguments ]

Have your java program mimick what the JVM interpreter (java.exe) does by invoking the static main() method of the classname.
For example, with SE AS the classname is "ServletExec" (no quotes) (you can see this by examining your StartServletExec.bat file),
so your code would simply call ServletExec.main() passing a String array that contains the program arguments.

SE FAQ #2 explains another way to run SE from within a different JVM.
Some very old answers to the "Runtime.exec() hangs what do I do?" question include:

For SE ISAPI:
You need to allow the IIS admin service and the WWW Publishing service to interact with the desktop. You can do this by using the services control panel to edit the properties for these services. By selecting a service and clicking on "Startup" you can check the box: "Allow service to interact with desktop". Note that once your native program is running in this manner, it will need to be closed before you will be able to completely shut down IIS

For SE NSAPI running on Solaris:
You can fix this problem by adding 'CGIWAIPid on' to magnus.conf and by using the reference version of the JDK instead of the production version.

Faq ID

390

Product

ServletExec

Category

Known Limitations and Workarounds

Question

Can ServletExec accept a chunked Request?

Answer

No.
However depending on what is sending the chunked Request, it may be possible to get the same effect. A common case for sending a chunked Request is to start sending a file or byte array to a Servlet running inside SE without first knowing the total size/length of the data being sent.
If it is your own code that is sending the request (via Apache's HttpClient API for example) then here is one possible way to "stream" data of unknown length to your servlet. Have your client code send the data using multiple POST requests (instead of just 1 POST request). These may be thought of as "super chunks".
Each request would need to have a correct Content-Length request header value.
Each request would need to be numbered in a way that the receiving servlet can keep track of the ordering of the "super chunks". The receiving servlet would need to assemble them correctly in order, and would also need a way to know which super chunk is the last one.
We've never tried this. We offer it only as a possible workaround.
SE FAQ #200 gives information about chunked Responses

Faq ID

338

Product

ServletExec

Category

Known Limitations and Workarounds

Question

Does ServletExec ISAPI support the use of Sun's JVM 1.5 ?

Answer

Yes. But we do not recommend that you use any of the following versions of JDK or JRE:

1.5.0_06

1.5.0_07

1.5.0_08

1.5.0_09

We say that, because of a bug that creeped into Sun's JVM, beginning with version 1.5.0_06. Here is the bug report for that JVM bug.
According that bug report, that JVM bug was fixed in 1.5.0_10.
As of 12.14.2006, you can obtain that version of JVM here but Sun likes to change links often so if that link is dead, then try the archive link near the end of this FAQ.

Some workarounds include:

Use SE AS instead of SE ISAPI/NSAPI. SE AS does NOT call AttachCurrentThread() while ISAPI and NSAPI do.

Use a JVM version that does not contain this bug. For example: JVM 1.4.2, or JVM 1.5.0_01, _02, _03, _04, or _05, or _10
You may be able to get these "older" revisions from
here

1.5.0_10 has fixed this issue.

NOTE: New Atlanta's testing showed that this bug occurs no matter whether Hotspot Client or Hotspot Server is used.

I'm receiving a NoClassDefFoundErr but it doesn't indicate which class can't be found. How can I debug this?

Answer

Try enabling Verbose and re-initializing ServletExec. Sometimes the verbose messages will give more information about what class can't be found.

Faq ID

343

Product

ServletExec

Category

Known Limitations and Workarounds

Question

Is the upcoming daylight saving time [DST] changeover in the U.S. an issue for any of the ServletExec releases?

Answer

Short answer: No.

Longer answer:
The DST changes deal with the Java Virtual Machine [JVM], and your own code that you are running inside
that JVM.
If SE is using an older JVM... one with invalid DST representation, then so is the code that you
are running inside SE (i.e. your webapp code).
You would only care about this if the code that runs inside your webapp does things that rely on the DST
representation being correct.
So it really depends upon the code that you are running inside your Web Application (i.e. inside ServletExec).

Take a look here:
http://java.sun.com/developer/technicalArticles/Intl/USDST/
I'd recommend that everyone upgrade their JVM as described at
the link above, and strongly encourage that FAQ #338 be consulted also.
And check the System Requirements for whichever version of SE you
are using to ensure that you upgrade to a JVM that is in fact supported by that SE version.

The problem is that Microsoft Windows service packs, option packs, security patches etc... often effect more than just the operating system.
They often effect (directly or indirectly) other Microsoft software products installed on the machine.
Things such as Internet Explorer web browser, and IIS webserver (and hence any software that may be plugged into IIS).
Exactly how did your service pack effect IIS ?
Do you know ?
We sure don't know... only Microsoft knows this.
Microsoft service packs, option packs, security patches, etc... effect your operating system and other Microsoft software in unknown ways.
ServletExec installs/plugs-into a webserver (like IIS).
A webserver is just software.
Anytime you have 2 or more pieces of software working together, interacting... and you change something about one of the pieces of software, there is the potential that you will break the ability for the 2 or more pieces of software to work together.
That is just the nature of software.
So basically, this seems to us to be a classic:
"everything worked, and then I changed something, and now it doesn't work... what's wrong ?" problem.
For this type of problem, the answer is usually found by asking yourself:
"what did I change?... what is different between the time when it worked and the time that it stopped working ?"
If the answer is that you applied a Microsoft Windows service pack, option pack, or security patch, then it seems to us that it broke your IIS (or it's ability to use currently installed extensions such as SE ISAPI or SE AS).
We've had other customers report problems like this after applying a Microsoft service pack, option pack, or security patch.
They report various problems including:
IIS hangs, servlet/JSP requests hang, IIS won't stop, IIS won't start, etc...
For these customers we have recommended that they completely uninstall ServletExec and then reinstall it. In the case of SE ISAPI this has nearly always cleared up the problem.

The Microsoft IIS Lockdown tool (see SE FAQ #277 for more information) is another common culprit for this sort of problem.
It is our belief (due to customer reports) that running this tool is sure to break ServletExec's ability to function with IIS.
Various problems like the ones listed above can occur after applying this lockdown tool. Here are some details of customer reports related to this:

After applying the IIS Lockdown tool, SE ISAPI (or AS) would start up fine.
The ServletExec admin pages could be accessed (so GET requests to a servlet would still work). But trying to submit any of the forms on the SE Admin UI would fail with a 404 HTTP return code.
No errors would be found in any of ServletExec's log files or in DBMON.
The same behavior would still persist even after giving Everyone Full control over all of SE's folders and files (including ServletExec_ISAPI.dll or ServletExec_Adapter.dll), and even the JDK folders.
We believe the problem had to do with the fact that a POST request to SE's admin servlet typically causes that servlet to try to write changes to the appropriate ServletExec configuration file and the IIS lockdown tool was not allowing SE to write the file.
In fact IIS was somehow trying to be "smart" and disallow ServletExec to complete its task or even to output a stacktrace that might give a clue to the problem.
Based on that customer's problem description, we believe that IIS was somehow taking the request back from SE and quietly returning 404.

We had one customer report that they had a fresh Windows 2000 sp4 / IIS 5.0 installation on a brand new machine.
He said that his entire OS & software installation came from an "image"... meaning that the OS and IIS and
other "baseline" items along with all service packs etc, were copied onto the fresh hard-drive.
He told us that this image already had the IIS Lockdown tool in it.
He said that he was trying to install SE 4.1.1 AS against his IIS on the newly built machine.
He stated that if he installed with JDK 1.4.1, everything worked great, but his requirements would
not allow him to use that JDK. So he rebuilt the machine fresh again from the image, and tried installing
SE 4.1.1 AS with JDK 1.3.1_09. He found that when he did that, the SE installer did not create the
servletexec.properties file and requests for simple servlets such as /servlet/TestServlet would return 500 internal server error.
He was able to have his IIS serve a simple static hello.html file.
Nothing from FAQ #7 would help in any way.
He later got past this problem and here is how (in his words):

Good news. When I was installing JVM 1.3.1 I was installing in the default installation path which was a mistake, I changed this to C:\program files\JVM now SE runs fine.

And here was our email reply to him:

Wow.
Thanks for letting us know that.
Where the JVM resides wouldn't typically matter so as long as your StartServletExec.bat and StopServletExec.bat files point to where it is.
I know that the default location for the JVM is usually something like:
C:\jdk1.3.1
or
C:\j2sdk1.4.2
There must be something special about the root of the "C" drive on that machine. Maybe some special file permission settings that are enforced by the IIS lockdown... something that was not allowing the JVM (and the SE AS instance running inside it) the permissions it needs to do what it must.

Note:
Anytime you run the SE ISAPI or SE AS installer against IIS (whether for the purpose of installing, OR for the purpose of uninstalling), and anytime you use the IIS management console (to view or edit website properties, or virtual directories or anything like that) the IIS Admin service will startup.
So you must keep checking to ensure that the IIS admin service is stopped, before uninstalling, after uninstalling, before installing, and after installing.
Even though you stopped it once, things that you do may cause it to start up again, so during the install or uninstall process be sure to heed the popup dialogs that say "make sure the IIS admin service is stopped before continuing".
Failing to do so, can sometimes cause your system to become hosed in a state where Add/Remove programs indicates that SE is no longer installed, but attempts to reinstall SE by running the SE ISAPI or SE AS installer indicate that it is still installed.
And if you have used the IIS Management Console after stopping the IIS admin service, you'll need to be sure to re-stop the IIS admin service before SE will work (before the SE Metabase filter will get loaded by IIS).
Also... the Services control panel in windows is notorious for showing you the incorrect state of a service.
In other words it will sometimes lie to you and tell you that a service is stopped when really it is running, or vice-versa.
To guard against this, close all services dialogs and open a fresh one each time you want to see if the IIS admin service is running or stopped.
Windows NT is especially buggy in this area (the area of displaying the state of a Windows service). Windows 2000 is more reliable with this, and the refresh button will often force it to tell you the truth, but it can still be buggy at times.

Some programs seem to stop working after you install Windows XP Service Pack 2SUMMARY: After you install Microsoft Windows XP Service Pack 2 (SP2), some programs may seem not to work. By default, Windows Firewall is enabled and blocks unsolicited connections to your computer. This article discusses how to make an exception and enable a program to run by adding it to the list of exceptions. This procedure permits the program to work as it did before the service pack was installed.
INTRODUCTION: To help provide security for your Windows XP SP2-based computer, Windows Firewall blocks unsolicited connections to your computer. However, sometimes you might want to make an exception and permit someone to connect to your computer.
After you install Windows XP SP2, client applications may not successfully receive data from a server. Following are some examples:

An FTP client

Multimedia streaming software

New mail notifications in some e-mail programs

Alternatively, server applications that are running on a Windows XP SP2-based computer may not respond to client requests. Following are some examples:

UPDATE
99.99999% of the time, this issue is due to using SE ISAPI with IIS 6 or higher which is an architecturally unstable, unreliable configuration that is no longer supported. The solution is to use SE AS instead. Please see SE FAQ #364 for details.

The remainder of this FAQ may help to better understand the mechanics of how web.xml gets renamed to web.na.tmp. Please note that changing file permissions in an effort to make this problem go away with SE ISAPI absolutely will not solve the problem. Please keep in mind that the file permissions issue discussed below is due to 2 or more SE ISAPI instances running at the same time. No amount of setting permissions on files will ever address that. SE AS is what addresses that.
http://<hostname>/servlet/TestServlet works when SE is "out-of-the-box" because the webapp named "default-app" gets deployed with "ServletExec Extensions" enabled and with the C:\Program Files\New Atlanta\ServletExec ISAPI\Servlets folder added as an External Library.

If the default-app is undeployed and then redeployed with "ServletExec Extensions" disabled (or with the Servlets folder no longer specified as an external library) then requests for servlets that reside in that Servlets folder (such as TestServlet, or sometimes the ArcIMS connector Servlet) can be expected to return 404 - File Not Found responses. It's easy to enable SE Extensions for any webapp on the main SE admin UI.
It's then possible (and also easy) to access the Admin UI for that particular webapp and add that Servlets folder as an External Library thus making the servlets that reside there visible and "requestable" to that webapp.

The web.na.tmp situation is indicative of a physical file permissions problem.
Manually enabling SE Extensions and adding the Servlets folder as an External Library (as mentioned above) can get things working right but most likely... only until the next restart of the default-app and/or ServletExec.
It won't solve the underlying file permissions problem.
The issue is that anytime SE tries to update any webapp's web.xml file it does so like this:

write the new version of web.xml to a file named web.na.tmp

delete the original web.xml file

rename web.na.tmp to web.xml

This particular file permission problem has been reported on occasion before, and always with SE ISAPI (never SE AS).
Apparently #1 and #2 work fine, but #3 fails.
File permissions where SE ISAPI is allowed to (a) write a file & (b) delete an existing file, but cannot (c) rename the file that was written?
Very odd.

Faq ID

53

Product

ServletExec

Category

Known Limitations and Workarounds

Question

When running ServletExec under Solaris and NES I get a "too many open files..." Error. How do I fix it?

Answer

Update the following kernel parameters:
set rlim_fd_max=4096
set rlim_fd_cur=256

Faq ID

41

Product

ServletExec

Category

Known Limitations and Workarounds, Security

Question

Why am I seeing SecurityExceptions when using ServletExec with JDK 1.2 or higher ?

Answer

JDK 1.2 has a different security scheme from JDK 1.1 so not all of the security settings for the Java VM are available on the ServletExec Security admin page. If you are seeing SecurityExceptions then you should edit the java.policy file to give permission to your servlet to perform the task it is trying to perform. If you want to give permission to your servlets to do everything then add the following to your java.policy file:

grant {
permission java.security.AllPermission;
};

If you are using SE 3.x or 4.x then you may need to use the information given in SE FAQ #111

If you are using SE 2.2 with JRE or JDK 1.2.2, and you are seeing the following stacktrace in your browser when trying to access the SE admin pages:

java.security.AccessControlException: access denied (java.lang.RuntimePermission setContextClassLoader)
at java.security.AccessControlContext.checkPermission(AccessControlContext.java:267)
at java.security.AccessController.checkPermission(AccessController.java:394)
at java.lang.SecurityManager.checkPermission(SecurityManager.java:540)
at java.lang.Thread.setContextClassLoader(Thread.java:1139)
at newatlanta.servletexec.ServletExec.processServletRequest(ServletExec.java)
at newatlanta.servletexec.ServletExec.ProcessRequest(ServletExec.java)
at newatlanta.servletexec.ServletExec.ProcessRequest(ServletExec.java)

See SE FAQ #112 for tips about where you can find your java.policy file.
NOTE: This information is also discussed in the online bug report for SE bug #87 entitled: "Exception is thrown for every request when security manager is set to ServletExec's security manager"

Faq ID

49

Product

ServletExec

Category

Known Limitations and Workarounds

Question

Why are long query strings not received by my servlet when using IE?

Answer

This is a limitation in IE. It limits the URL including the query string to a length of about 2100. Netscape browsers don't have this limitation.

Faq ID

46

Product

ServletExec

Category

Known Limitations and Workarounds, Security

Question

Why can users still access my servlets when they are protected using ServletExec's IIS Security feature?

Answer

When keep alives are used IIS will only authenticate the first request from a browser. To work around this you must disable keep alives for all web sites which are using ServletExec's IIS Security feature.

You need to ensure that the user account under which your code is running has read/write access to the network drive (or share). With ServletExec AS (which runs out-of-process with the webserver) this is fairly simple because with SE AS, the JVM (and thus SE's java code, and thus your java Servlets and JSPs) run inside a process that is separate from the webserver's process. With SE AS, here is how you'd do it:

Install ServletExec AS as a Windows Service.

Specify that the ServletExec AS service run under a User account that you know has access to the network drive.

Start ServletExec running under that user and your servlet should be able to access the drive using the following syntax:

\\machine name\drive's share name\path to file

Note: If you use JDK 1.2 instead of JDK 1.1 then you'll receive better error messages when problems occur while trying to access the network drive.

Note: You'll need to escape the '\' character in your Servlet code like this:

File networkFile = new File("\\\\Machine\\shared\\networkFile");

With versions of ServletExec that run in-process with the web server (a plug-in version such as: SE ISAPI, or SE NSAPI) the entire JVM and thus SE and thus your servlets and JSPs are all running inside the webserver's process. In the case of IIS (SE ISAPI) this presents some complexities since IIS runs as different users at different times (see section 2.7 of the SE Installation Guide entitled "User Accounts for Microsoft IIS"). This means that your Servlets and JSPs will be running as different users at different times. Whether or not your Servlet or JSP will be able to read/write the network drive/share, will depend upon who has read/write permissions to your network drive/share and which user your servlet/JSP is running as at that moment. So in the case of SE ISAPI, use the information given in section 2.7 to decide which users/principles should be given read/write access to your network drive so that your servlets/JSPs running inside SE ISAPI will be able to read/write to your network drive.

Faq ID

48

Product

ServletExec

Category

Known Limitations and Workarounds

Question

Why do CGIs fail to work after installing ServletExec/NSAPI with NES on Solaris?

Answer

For some reason the LD_PRELOAD statements added to the start script by the ServletExec installer can sometimes cause CGIs to no longer work. If this occurs comment out the LD_PRELOAD statements to see if this makes the problem go away.

Faq ID

39

Product

ServletExec

Category

Known Limitations and Workarounds

Question

Why does my servlet hang when calling Runtime.exec() and Process.waitFor() with the Solaris NSAPI version of ServletExec?

Why does NES on Solaris fail to start when I enable Verbose GC on the VM Settings admin page?

Answer

The NSAPI Solaris version of ServletExec currently doesn't work when Verbose GC is enabled with a production version of JDK 1.2. We're investigating a solution to this problem.

Faq ID

37

Product

ServletExec

Category

Known Limitations and Workarounds

Question

Why does NES on Solaris fail to start when I try to use the HotSpot VM with JDK 1.2?

Answer

ServletExec NSAPI currently doesn't work with the HotSpot VM and JDK 1.2 on Solaris. We're investigating a solution to this problem.

Faq ID

42

Product

ServletExec

Category

Known Limitations and Workarounds

Question

Why doesn't my servlet which uses chunked encoding work?

Answer

Perhaps your servlet is not adhering to the rules for using chunked encoding. Further details are given in FAQ #200

Miscellaneous

Faq ID

102

Product

ServletExec

Category

Miscellaneous

Question

Can ServletExec be run in a multi-machine, HTTP Server Cluster?

Answer

Yes, however at this time New Atlanta does not provide a standard solution for keeping the configuration files of the various distinct instances of ServletExec in sync with each other. Here are some specifics of the problem at hand:
If you deploy new Servlets or make other modifications to the ServletExec configuration on machine A, then machine B (separate machine with separately running instance of ServletExec) does not know about these changes.
Even if you were to have both instances of SE (the one on machine A and the one on machine B) share the exact same ServletExec configuration files (on the same hard drive), the in-memory representation of the configuration for SE instance B would not be updated when you accessed the admin UI of SE instance A to make the changes.
At this time we recommend the following approach to work around this architectural reality:

Install ServletExec (must use SE AS) separately on each machine. (this requires a separate ServletExec license for each machine).

Have each SE AS instance share the exact same Configuration files (have just one ServletExec Data folder). This would be done by editing the StartServletExec script for each SE instance to use the same value for the
-home parameter.. Having more than 1 SE AS instance using the exact same configuration files (ServletExecData folder) is no longer recommended. You may deploy copies of the same .war file to each SE AS instance but sharing global configs such as application.xml, servletexec.xml, etc... between 2 or more SE AS instance can cause stability problems when 2 or more instances try to write to those files at the same time. In that scenario the problem may manifest in any of several different ways such as disappearing webapps, disappearing license keys, crashing JVMs, hanging requests, etc... and such problems may not be seen until some time later, making it very difficult to understand the cause.

To synchronize the ServletExec config files between various distinct instances of ServletExec:Let's say that machine A has SE instance A which is the active instance and that machine B has SE instance B which is a passive instance.
Whenever you use the SE admin UI for the active SE instance to make configuration changes, bounce the other SE instances (the ones that are up and running but not being used... "passive").
That will force them to read the new configuration files and thus pickup those changes.. Use the SE Admin UI for each SE AS instance to manually configure the changes you wish to mimick across all instances. For example... deploying identical, private copies of a .war file onto each SE AS instance (each instance gets its own separate copy of the .war file).

To manage the synchronization of your own code between various SE instances, use a Web Application. When you change any code or settings within it, distribute the updated copy of your app to each of the SE AS instances (for example overwrite all the old myWebApp.war files with the new one). Then simply reload it dynamically from all the SE AS admin UIs of all your SE AS instances in the cluster.
You could even write your own code that utilizes the AdminAPI class that is built into ServletExec. In this way your code could perform these kinds of dynamic reloads programatically. A working example of this sort of code can be found at:ftp://ftp.newatlanta.com/public/tools. It is called WebAppReloader.

NOTE: WebAppReloader is only an example of how one might use the AdminAPI of ServletExec, and it is not meant for use in production. Also, the use of ServletExec's AdminAPI is experimental and not officially supported.

To manage session data between the various instances:

Beginning with SE 5.0, it is possible to setup multiple/redundant web applications each using the JdbcSessionManager to store their session data in the same database.
This way webapp A deployed on machine A with context path "/a" could access the session data for the redundant/duplicate webapp B deployed on machine B with the same context path "/a" (assuming the 2 machines are in a cluster or behind a load balancer such that the hostname is the same for all requests). See the Chapter about Customizable Session Management in the SE 5.x User Guide for more information.

Prior to SE 5.0, a passive SE instance that has just been made active will have no knowledge of the session data that was maintained by the previously active instance. This is because by default, session data is only read in from disk by SE upon SE startup. So this solution does not allow the sharing of session data across multiple SE instances. You'd have to do "sticky" load balancing in that case.

Faq ID

94

Product

ServletExec

Category

Miscellaneous, Registration, Version differences

Question

How can I find out exactly which version and hotfix-level (formerly called "patch-level") of ServletExec I am running?

Answer

To check this for the "Java component" of SE, the ServletExecXX.jar file:
Access the ServletExec Admin UI in a browser.

For SE 5.0 and greater, access http://<hostname>/servletexec/admin
and view the SE JAR version at the bottom of the login page.

For SE 4.x and older, access http://<hostname>/servlet/admin
and then click on the first link in the upper left-hand corner
(labeled "help" or "support").
At the top of the page in the right frame, you should see the exact version of ServletExec that is running. Possible values might be: 3.0, 3.0C, 3.0E, 3.1, 4.1, 4.1.1, 4.1.1p27, 4.1.1.28, 4.2, 4.2p20, 4.2.0.21 etc...

If your SE JAR is patched then the version number should be followed by:
pXX
where XX is the patch level. SE 5.0p2 for example.

If your SE JAR is hotfixed then the hotfix number is the number after the last dot:
5.0.0.XX
where XX is the hotfix level. SE 5.0.0.13 for example.

Another way to learn the exact version of the SE JAR you are running is to examine the startup messages in ServletExec.log. The line which states that ServletExec has initialized will give the exact version.

To check this for the "Native component" of SE, (which is a DLL on Windows and is a .so on Unix):

If running on Windows, startup DBMON, then startup your webserver, then use a browser to send a request to your webserver, and view the messages that are output in DBMON. (if using SE ISAPI... not SE AS... then you could choose to view the contents of ServletExecNative.log instead of using DBMON).
For example, with SE AS, the messages might look something like this:

The ServletExec-<webserver-brand/version> Module/Adapter for ServletExec <version/patch-level> is initializing...
...
...
The ServletExec-<webserver-brand/version> Module/Adapter for ServletExec <version/patch-level> has initialized...

With Apache, it is normal to see these messages multiple times per Apache startup.

If running on Unix, you can't use DBMON.exe so you'll need to look for the above-mentioned messages in your webserver's log file. With Apache, you'd first need to set the LogLevel in httpd.conf to be info or debug and the messages would appear in Apache's error.log after Apache startup.

Special Note to ESRI ArcIMS customers who are using SE 5.0 AS with Apache 2.0.x (any platform):
If your SE native adapter reports that it is version 5.0 (no patch number or letter after the 5.0) then you will need to upgrade the native adapter component.
To do this you have 2 choices:

You could uninstall SE 5.0 and then download a fresh SE 5.0 AS installer from the New Atlanta website which would give you an updated adapter that reports that it is SE 5.0c and which fixes:
bug #956: Unable to Post more than 48k to a servlet running behind Apache 2

You could leave your SE 5.0 installed and simply patch the native component by downloading SE 5.0 patch #2 or higher using the instructions given in FAQ #195 on this website, giving you an adapter that reports that it is SE 5.0p1 or higher and which also fixes bug #956 and possibly other native bugs depending on the hotfix/patch level (see the 5.0 hotfix ReleaseNotes.txt or the patch ReadMe.txt for more details).

Faq ID

363

Product

ServletExec

Category

Miscellaneous

Question

How can I get the installer, documentation, or license key for a version of ServletExec that is no longer available on the New Atlanta website?

Answer

Older installers and their related documentation and materials are freely downloadable from the
New Atlanta FTP server
License keys for older versions of ServletExec may be requested by sending email to sales@newatlanta.com

Faq ID

115

Product

ServletExec

Category

Miscellaneous

Question

How can I keep ServletExec AS running even after I logout?

Answer

If using SE AS, be sure to use the -Xrs JVM option when starting ServletExec (in StartServletExec.bat or StartServletExec.sh).
That option tells the JVM to ignore certain Operating System Events/Signals that would otherwise force the JVM to shut itself down. For example logging off of the box.
That JVM option is documented along with all other -X (non standard) JVM options.
That page is also referenced in SE FAQ #182
The SE 6.0 installer generates StartServletExec.bat/.sh file(s) that include
the use of -Xrs, but prior to SE 6.0 (i.e. SE 5.x or older) one must manually add that JVM option.

If running SE AS on Linux/Unix:
ServletExec, like any other executable process in Linux/UNIX, will continue running after a user logout ONLY if that process has been made to be immune to the signal SIGHUP. This is done many ways in Linux/UNIX depending upon the shell used by the user login. For example, the C-shell has a configuration that arranges for all command executed in the background using "&" to be automatically immune to SIGHUP. For the best description, see the man page for "nohup" (the Solaris version is very helpful). One example showing how to logout of an ssh session without causing SE to shut down: $nohup ./StartServletExec &

ServletExec Hotfixes are freely downloadable from the New Atlanta website.
They are also available via anonymous FTP from the New Atlanta FTP Server:
ftp.newatlanta.com
ServletExec patches are only available from the New Atlanta FTP Server:
ftp.newatlanta.com
An FTP client could be used to access this server, or in some cases a web browser can be used. Your ability to access this server using a web browser may depend on whether or not you are behind a firewall and/or how your network is setup (setting the browser to allow passive FTP transfers may help in some cases).
However you choose to access this FTP Server, once there you should browse to the:

Updates have documentation text files which you should read to learn what an update fixes and how to apply an update to your existing SE installation(s).

Each Hotifix ZIP File contains a ReleaseNotes.txt which you should read in order to learn which bugs the hotfix fixes and how to apply the hotfix.

Each patch folder (SE 6.x and newer) contains a ReleaseNotest.txt which you should read in order to learn which patches fix which bugs. Patches are applied in the same manner as hotfixes, so to learn how to apply a patch, please follow the instructions given at the bottom of any hotfix ReleaseNotes.txt (for your given OS + webserver + SE configuration).

Each patches folder (SE 5.x and older) contains a ReadMe.txt which you should read in order to learn which patches fix which bugs, and how to apply the patch.

Many times, an update (i.e. hotfix or patch) will include both Java component(s) (JARs) and also an updated version of an SE native component (DLL, *.so, or *.c), in which case you should update all components.
In any case you'll only need the components that are relevant to your setup/environment/configuration. For example if you are using IIS as your webserver, then you certainly would NOT need ApacheModuleServletExec.dll which is the native component of SE that hooks into the Apache web server on Windows.

You can stay informed of when new hotfixes are released by registering on the ServletExec Forum/Conference
Hotfix releases are always announced in the "Announcements" forum there. If you are registered then you'll receive an email when messages are posted to that forum.

Faq ID

143

Product

ServletExec

Category

Miscellaneous, XML

Question

I am getting java.lang.SecurityException: sealing violation. Why ?

Answer

New Atlanta has never seen this problem here, but has had a handful (2 or 3) of customers report it.
We believe that the problem occurs when you have classes that are part of the same package,
and some of those classes are in one JAR file, and some are in another JAR file
and at least one of the JAR files has been "sealed" as described at:
http://java.sun.com/docs/books/tutorial/ext/security/sealing.html
Here is the text we found at that link (as of 12.18.2001):

Sealing Packages in Extensions
You can optionally seal packages in extension JAR files as an additional
security measure. If a package is sealed, all classes defined in that package
must originate from a single JAR file.
Without sealing, a "hostile" program could create a class and define it to be
a member of one of your extension packages. The hostile software would then
have free access to package-protected members of your extension package.
Sealing packages in extensions is no different than sealing any JAR-packaged
classes. To seal your extension packages, you must add the Sealed header to
the manifest of the JAR file containing your extension. You can seal individual
packages by associating a Sealed header with the packages' Name headers. A
Sealed header not associated with an individual package in the archive signals
that all packages are sealed. Such a "global" Sealed header is overridden by any
Sealed headers associated with individual packages. The value associated with the
Sealed header is either true or false.
Examples:
Let's look at a few sample manifest files. For these examples suppose that the
JAR file contains these packages:
com/myCompany/package_1/
com/myCompany/package_2/
com/myCompany/package_3/
com/myCompany/package_4/
Suppose that you want to seal all the packages. You could do so by simply adding
an archive-level Sealed header to the manifest like this:
Manifest-Version: 1.0
Sealed: true
All packages in any JAR file having this manifest will be sealed.
If you wanted to seal only com.myCompany.package_3, you could do so with
this manifest:
Manifest-Version: 1.0
Name: com/myCompany/package_3/
Sealed: true
In this example the only Sealed header is that associated with the Name header
of package com.myCompany.package_3, so only that package is sealed.
(The Sealed header is associated with the Name header because there are no blank
lines between them.)
For a final example, suppose that you wanted to seal all packages except for
com.myCompany.package_2.
You could accomplish that with a manifest like this:
Manifest-Version: 1.0
Sealed: true
Name: com/myCompany/package_2/
Sealed: false
In this example the archive-level Sealed: true header indicates that all
of the packages in the JAR file are to be sealed. However, the manifest
also has a Sealed: false header associated with package com.myCompany.package_2,
and that header overrides the archive-level sealing for that package.
Therefore this manifest will cause all packages to be sealed except for
com.myCompany.package_2.

One New Atlanta customer saw this problem when using JDK 1.2.2_06. That customer
reported to us that the problem disappeared after they upgraded to JDK 1.2.2_09.
Sun's Bug database reports a bug which seems to fit this problem:
http://developer.java.sun.com/developer/bugParade/bugs/4401293.html
Another customer reported this problem when using SE 4.1 with JDK 1.2.2_06 and
said that upgrading to JDK 1.2.2_09 did not help them (as it did
with the earlier customer).
For this 2nd customer, we suggested that they examine ALL jars that are
getting used by the JVM (which may not show up in the output that tells
you your Classpath). Another FAQ at this site tells how to track down these JARs.
This tip helped that 2nd customer to find the solution.
Here is what they said:

In the directory java.ext.dirs there was an old xml.jar. That causes the problems with the crimson.jar. The class org.w3c.dom.DOMImplementation in the old xml.jar
does not contain the method createDocumentType

crimson.jar is a JAR that comes with SE 4.1 which SE uses to parse XML files (web.xml, .tld files, etc...)
The version of crimson.jar that comes with SE 4.1 is Crimson 1.1 and its manifest file contains "Sealed: true"
SE 4.1.1 comes with crimson 1.1.3 which uses
"Sealed: false"
So upgrading to SE 4.1.1 may be yet another way to solve this problem.

Faq ID

382

Product

ServletExec

Category

Miscellaneous, Web Services, XML

Question

Please describe the various open source or free JARs that ship with SE ServletExec

What are some advantages of using ServletExec 6.0 AS instead of Tomcat 6?

Answer

With SE you get world-class technical support. If you encounter a problem installing or using ServletExec, just send email to support@servletexec.com. 90% of the time we already know the solution to your problem. We can save you time and effort.

Many have asked about the performance differences between SE and Tomcat. We have no comparison benchmark numbers to give you.
The performance you see will depend greatly on many factors including:

Your application (the code you are running inside SE)... how well it was written, what it does and how efficiently it does it.
For example does your app connect to a database? If so how? By creating a brand new connection to the DB on every request? Or does it make use of a connection pool?

The hardware and network on which you are running things.

How you have things configured. For example is your JVM configured to run with the -server option? Have you given your JVM enough RAM to function efficiently?

The tool you are using to stress your application, and what that tool is requesting, and how it requests it. For example... see point #2 of SE FAQ #127.

This is why we always recommend that you perform your own comparison tests, with your own application, in your own environment.
Feel free to search the SE forums for anyone who has shared their own benchmarks. Or to post your own message on forum asking others to give their input on the matter.
No one has ever reported to us that Tomcat is faster than SE. If your testing shows this to a significant degree, please let us know. There may be simple configuration changes you can make to resolve it.

Here is a list of *some* specific technical features of SE 6.0 AS (with latest hotfix applied) which we feel offer advantages over Tomcat. At the time of this writing it is our honest belief that Tomcat 6.0 does not offer these features. If you feel we are incorrect about any of these points, please let us know. We are happy to update this article accordingly:

A web app that contains many large .jar files may suffer from slow startup times (in either Tomcat or SE). However SE provides a Jar Indexing feature that greatly
improves the startup (and reload) time of such an app.

When running Tomcat behind a commercial-grade webserver such as Apache or IIS, one must manually edit a file (uriworkermap.properties) when adding or removing a web app context, and then cycle the websever so that mod_jk will re-read that file and know when to route requests over to Tomcat based on the new alias rules. This results in downtime for your web server. With SE AS this not needed since the part of SE AS that hooks into a commercial-grade webserver will automatically know when you've added or removed a webapp and will adjust it's routing rules accordingly without the need to cycle anything.

ServletExec comes out-of-the-box with a special webapp named "default-app" which integrates very tightly with the external commercial-grade webserver (Apache or IIS). Some examples of this integration include: (1) Allowing the native webserver to serve static content which is potentially much faster than having the servlet/JSP engine do it. (2) Asking the webserver to give the file system location of requested dynamic content (a JSP page for example). This is especially useful if (for example) your IIS website makes use of Virtual Directories and you've placed content there, or if (another example) your Apache is making use of mod_rewrite in order to serve content out of non-document root locations that the servlet/JSP engine would otherwise not know about.

ServletExec offers the ability to configure *any* webapp deployed on it (not just the default-app) to let the webserver serve its static content.

ServletExec offers many additional session-related settings on a per-webapp basis. Normally the only session-related setting that you can set is the session timeout value (it governs the lifespan of all newly created sessions in your app). Enabling "ServletExec Extensions" for your app opens up the ability to configure many additional settings such as
requiring that the session tracking cookie be secure.

Out-of-the-box SE supports Pluggable Session Management including a bundled, ready-to-use custom session manager which stores sessions in a database of your choosing. We call this the JdbcSessionManager and it facilitates running multiple SE AS instances in a failover and/or load-balanced environment (behind multiple instances of IIS and/or Apache). In this way SE may be scaled to a High Availability environment, with no coding, or code changes (just configurations) required on your part.

Faq ID

97

Product

ServletExec

Category

Miscellaneous

Question

What is a Servlet ?

Answer

A servlet is a Java class that extends the functionality of an HTTP Web Server. A Servlet can only be run inside a Servlet container/engine.
When an HTTP request is sent from a web browser to a web server, a servlet can be used to create an HTML response "on-the-fly".
The dynamically created response is then sent to the requesting client/browser by the servlet container.

Faq ID

98

Product

ServletExec

Category

Miscellaneous

Question

What is a Servlet Container or Servlet Engine ?

Answer

A servlet engine is a piece of software that plugs into a web server, such as Microsoft's Internet Information Server (IIS) for example, allowing Java programs (servlets) to quickly process web browser requests and dynamically generate custom .html documents.

Faq ID

249

Product

ServletExec

Category

Miscellaneous

Question

What is the difference between a patch and a hotfix ?

Answer

Functionally, they are the same thing.
They are meant to describe an updated component or collection of components (JARs, DLL's, .so's, etc...) which fixes 1 or more bugs to an existing version of SE.
The main difference is in how the updates are distributed to our customers and the version numbering scheme that they use:

A patch will typically contain a small # of bug fixes or features (1 or 2), typically for just 1 customer. Patches are placed on the New Atlanta FTP server only.

A hotfix is a "rollup" of 1 or more patches and may be thought of as an officially announced "super-patch", which may be of interest to a wider range of our customers. Hotfixes are placed both on the New Atlanta website and our FTP server.

After the 1st SE 6.0 hotfix was released (the Oct 2008 hotfix) it was decided to change the version numbering "scheme" used by ServletExec patches. This was done to more closely mimick how patches are delivered with our BlueDragon Server JX product (now that the BDJX Server 7.1 codebase has been joined to the SE 6.0.0.1_22 codebase).
Patches also provide an easier means of delivering updates to those customers that need them, without unnecessarily troubling those that don't.

Prior to SE 6.0, a patch would use the letter 'p' as part of its version designation.
For example:

The last patches that were made for SE 5.0, 4.2, and 4.1.1 were:
5.0p06, 4.2p20, 4.1.1p27
When it was time to create the next bugfix/update/patch, it was decided to begin using the term hotfix instead. So the first hotfixes that were made for SE 5.0, 4.2, and 4.1.1 were:
5.0.0.07, 4.2.0.21, 4.1.1.28
and those hotfixes include all the updates/bugfixes that were in their "patch" predecessors, along with some new updates/bugfixes.

Hotfixes use dot-notation for their Version numbering scheme. For example the SE 6.0 October 2008 Hotfix is v6.0.0.1

When I request a JSP or Servlet, it executes several times in a row. But I only requested it once. What is wrong?

Answer

In the few cases where we have seen this problem the cause has been the HTML.
For example, a JSP that contains an empty image source like this:
<IMG SRC="" />
results in the browser sending a second request to the HTTP Web Server (using GET) for the same resource.
Giving the SRC attribute a non-empty value causes the problem to disappear.
Another example would be a JSP or Servlet that contains or emits incorrect HTML syntax like this:
<body background="#FFFFFF">
using the correct:
<body bgcolor="#FFFFFF">
alleviates the problem.
We have seen this behavior with both Microsoft Internet Explorer 5.5 and Netscape Navigator 4.7 browsers.
This problem is not due to ServletExec. It is due to how the browser reacts to invalid or unexpected
HTML that it parses. If you are seeing this problem, check the HTTP Web Server access log.
It will likely show 2 or more distinct requests with identical timestamps.
Another way to test to see if this is the problem is to have your JSP or Servlet log a message to the ServletExec log
file each time it is accessed. Print out the timestamp and see if your browser it hitting your resource repeatedly.
If so, and your browser is not sending the session id in each request to a JSP then you may start seeing
OutOfMemoryException since JSPs create a session object by default.
Another way to possibly isolate the problem would be to use a different browser brand and/or version.
Another way to isolate the problem is to test using TestServlet or DateServlet.
If you close out all your browser instances, reinitialize ServletExec,
get a fresh browser window and hit any of the example resources that come with ServletExec such as
TestServlet or DateServlet or hangman.jsp (and hit nothing else) are you able to make the problem occur?

Faq ID

189

Product

ServletExec

Category

Miscellaneous

Question

When I run the StopServletExec script, I sometimes see an error. What does this mean ?

Answer

When SE AS is NOT running, and you try to stop it by invoking the StopServletExec.bat file directly in a DOS window, StopServletExec.bat will say:
ERROR: Received an i/o exception - java.net.ConnectException: Connection refused: connect
ERROR: Failed to stop ServletExec.
The most common causes of this are:

Your ServletExec AS instance was not running to begin with.

Your StopServletExec script is using the wrong port (it must be the same port being used by your SE instance).

This is not a problem with ServletExec.

If you are using SE AS 4.x, and your SE AS instance IS running, and you try to stop it by invoking the StopServletExec.bat file directly in a DOS window, then StopServletExec.bat will give a slightly different error message:
ERROR: Received an i/o exception - java.net.SocketException: Connection reset by peer: JVM_recv in socket input stream
read
ERROR: Failed to stop ServletExec.
This is a bug in the StopServletExec program (not ServletExec), and can safely be ignored.
In this case, ServletExec does correctly shutdown despite what the message says.
On a windows machine, most users run ServletExec AS as a windows Service (which calls the StartServletExec.bat and StopServletExec.bat scripts for you under the covers).
So, the only way you would ever see any output from either of these scripts is if you manually invoke them from the command prompt.
This problem will be fixed in SE 5.0

Faq ID

50

Product

ServletExec

Category

Miscellaneous

Question

Why am I seeing an "Invalid class file format... Wrong Magic Number" error with code that I know is fine?

Answer

A wrong magic number error indicates a corrupted class file. Replace the class file with a freshly compiled one and the problem should magically disappear.

Registration

Faq ID

93

Product

ServletExec

Category

Registration

Question

ServletExec is not accepting my license key when I try to register. What is wrong ?

Answer

First make certain that you are using the clipboard to do a copy and paste of the key (rather than trying to type the key into the text field manually).
If ServletExec is still rejecting your key with a message such as:
! INVALID LICENSE KEY -- PLEASE TRY AGAIN.
Then please make certain that there is no leading or trailing whitespace in the key that you are trying to feed to ServletExec.

A license key for SE X.something will work with SE X.anything.
In other words... license keys are "tied" to the major version of SE, and will work with all point releases of that major version.
For example an SE 4.1.1 key will work with SE 4.1.1 and SE 4.2.
An SE 5.0 key will work with SE 5.anything, but not with SE 6.0.

In the email that was sent to you containing your purchased license key(s), the version for which they were generated should be specified. Make sure that you are registering the correct version of ServletExec for the version of key that you have.

Security

Faq ID

301

Product

ServletExec

Category

Security, Web Server Support

Question

How does SSL (https) integrate with ServletExec?

Answer

SSL is a function of (and is configured in) the webserver, not SE.
SE runs behind the webserver.
SE can run behind an SSL-enabled webserver... yes.
Or SE can run behind a webserver that is not SSL-enabled.
SE does not care about or control whether the protocol is http, or https.

If you wanted to, you could have your servlet or JSP code that runs inside SE
enforce the protocol of the request sort of like this [pseudo-code]:

if(! request.getProtocol().equals("https"))
out.println("Hey! you have to use SSL, or else !!");
else
//forward to the resource that was requested

You could even have code that runs inside SE that obtains the Client Certificate (if one was sent in the request)
and then uses it for some purpose that is specific to your application.
But a Client Certificate is not required for SSL.

You could even make use of the Declaritive Security of webapps to define a Security Constraint in your webapp
whose Transport Guarantee is set to "Confidential". This would cause all requests that match any aliases that
you define for that Security Constraint (via a Web Resource Collection) to be checked for SSL by ServletExec.
Basically it just saves you having to write the code that enforces that the protocol be https.
Instead you just declare that certain aliases should be protected in this manner, and let SE enforce that for you.

Enabling your webserver so that it will support SSL is mostly beyond the scope of this FAQ.
However I can tell you this:

You need to obtain a Server Certificate from a CA [Certificate Authority].
Examples of a CA include companies such as Verisign, & Thawte.
You typically use the webserver software itself to generate a Certificate Request which
is then sent/provided to the CA. The CA in turn provides the Server ID to you, which you then
feed to your webserver to SSL enable it.

If your webserver is a commercial-grade webserver such as IIS, Apache, or SunONE, then
you should consult the documentation for that webserver as well as any information that
the CA can provide you, in order to learn how to SSL-enable your particular webserver.

If your webserver is the built-in webserver that comes with ServletExec 5.0 AS (and higher versions),
Then you should consult the following resources in order to learn how to SSL-enable that webserver:

The SE 5.0 User Guide contains a section describing the settings for the built-in webserver

The SE Admin page for the settings of the built-in webserver has a "Help" page that gives very
detailed information on how to SSL-enable that webserver.

Do not confuse a Server Certificate with a Client Certificate.
They are 2 completely different things.
At the time of this writing, Verisign refers to a Client Certificate as a "Class 1 Digital ID".
An OpenSSL book published by O'Reilly calls it a "Personal Certificate" (p. 55).
At the time of this writing it is possible to get one from Verisign as follows:
www.verisign.com - "Products & Services" - "Content Security" - "Digital IDs for Secure E-mail" - "Buy Now"
Then choose either: $14.95 per year, or free 60-day trial.
They'll send an email to you, with instructions for obtaining and installing the client cert (X509 cert) into your web browser.
Remember, a client certificate is NOT required to SSL-enable your webserver.
A Server Certificate is what's required to SSL-enable your webserver.

Faq ID

111

Product

ServletExec

Category

Security

Question

I enabled the ServletExec Security Manager from the SE Admin UI, and then reinitialized ServletExec. Now I am getting Security Exceptions every time ServletExec receives a request. What is wrong?

Answer

The permission settings that you can set on the Servlet Security page of the SE Admin UI are really only valid for JDK 1.1.x.
JDK 1.2 and newer adds many other security settings that cannot be set from the SE Admin UI. This means that when you enable a Security Manager while running JVM 1.2 or newer, that you must also edit the java.policy file that is currently being used by that JVM so that code running within that JVM will have the necessary permissions to do what is required. First do a test by adding:

grant {
permission java.security.AllPermission;
};

to your java.policy file.
If this fixes the problem then you will know it is an issue involving java.policy. If you then decide to use a more fine-grained approach to granting permissions...
Information about java.policy syntax may be found at:
http://java.sun.com/j2se/1.3/docs/guide/security/index.html

Note:
If you enabled this feature by accident and don't want it enabled anymore then do this:

Stop ServletExec

delete VMSettings.pref

Restart ServletExec

An alternative to step #2 given above is to open VMSettings.pref in a plain text editor and edit the securityManager line so that it reads:
securityManager=null

Faq ID

112

Product

ServletExec

Category

Security

Question

Where can I find my java.policy file ?

Answer

This is really more of a general "Java" question than it is a New Atlanta product question, and the location of that file may vary with the version of your JVM, but using JDK 1.3.1 on Windows as an example it could probably be found at:
C:\jdk1.3.1\jre\lib\security

Faq ID

354

Product

ServletExec

Category

Security

Question

Why (and how) do I disable the invoker servlet?

Answer

The /servlet/* prefix alias is used to invoke any servlet you wish.
It can be used to invoke a servlet in either its configured state
(/servlet/MyConfiguredServlet) or in its unconfigured state
(/servlet/com.mycompany.myservlets.MyServlet).

Depending on your servlet, what it does, and how it does it... allowing it to be invoked in an unconfigured manner may pose
problems for your application ranging from bothersome behavior all the way up to unacceptable security issues.
For this reason it's generally advisable to "disable the invoker servlet" by overriding the /servlet/* prefix alias mapping as described below:

This is done on a per-webapp basis.
Initially, every webapp has its own instance of the invoker servlet, and it's own /servlet/* prefix alias mapping which is mapped to that invoker servlet. Both the servlet and it's mapping are implicit... meaning they are built-in & hidden.
The best and most portable, Servlet-Specification-compliant way to disable this is to simply define your own harmless servlet in your webapp's web.xml file and then override the /servlet/* mapping. For example:

The noInvoker.jsp file could do something harmless such as return a "Sorry, you can't do that" message, or redirect the user to something else, or whatever you want it to do. That JSP would not even need to contain any JSP code if you don't want it to. It could just contain simple HTML if you like. It's up to you.
Then, you should design your web app so that your servlets are configured and have aliases mapped to their configured names so that they can be invoked using the aliases you setup. Exact aliases (/exact) or Prefix aliases (/prefix/*) are probably best to use for invoking your servlets, although suffix aliases could be used if you wish (for example *.do mapping to the Struts ActionServlet).

How can I make sure that the attributes I bind to the Session are cleaned up and don't cause a memory leak?

Answer

Every instance of ServletExec has a thread that runs in the background which periodically examines all the session objects it is maintaining. When ServletExec determines that a session has been idle (unused) for a period of time that is longer than the configured session timeout value, it calls invalidate() on the session object. ServletExec's implementation of invalidate() removes all attributes that were bound to that session and then removes any references to the session object itself so that the JVM will be able to garbage collect it (and all of its attributes).
If you have objects (attibutes) which you bind to the session and you want to make certain that those objects correctly, and gracefully, release any resources that they might have acquired (run any cleanup code that you want them to), then you have 2 choices:

Have your objects, that you bind to the session object, implement the javax.servlet.http.HttpSessionBindingListener interface.
This way ServletExec will call valueBound() and valueUnbound() methods each time the object is added to or removed from the session.
In your implementation of valueUnbound() you would perform any cleanup or resource releasing that you need to do.

Run your code within the context of a Web Application (WEB-INF folder, web.xml file, etc...) and create a listener that will be notified of Session Attribute Change Events. You would do this by implementing the javax.servlet.http.HttpSessionAttributeListener interface.
In your implementations for attributeReplaced() and attributeRemoved() you would perform any cleanup or resource releasing that you need to do (depending upon which attribute is being removed).
The exampleWebApp that comes with ServletExec has a simplistic example of a Session Listener which shows how one might do this. Study this to create your own listener and then configure it in your web app.

Faq ID

144

Product

ServletExec

Category

Session Tracking, Web Application

Question

How does ServletExec track sessions in a Web Application?

Answer

By using either Cookies, or URL Rewriting (if the client does not accept cookies).
This conforms to sections 7.1.1 and 7.1.4 of the Servlet 2.3 Specification.
ServletExec first looks for a cookie named "JSESSIONID" (all upper case) in the request header. The name of that cookie is mandated by the Servlet Specification. If the request has no such cookie, then ServletExec will look at the request URL itself to see if the session id is encoded/embedded there.
Note: If using URL Rewriting, one must be sure to call:

HttpServletResponse.encodeURL()
OR
HttpServletResponse.encodeRedirectURL()

for each link emitted by their code.

For JSPs, one could pass an init parameter named "urlRewriting" with a value of true, to the JSP Engine that's built into ServletExec.

For SE 5.x and newer, that JSP Engine is implemented by a servlet named "JspServlet".

For SE 4.x and older, that JSP Engine is implemented by a servlet named "JSP10Servlet".

For more details on how to configure that Servlet, please read FAQ #315

Section SRV.7.1.3 of the Servlet 2.3 Specification describes the proper format for this. For example:

NOTE: If the client accepts cookies then the above-mentioned encode methods of the Response Object will not actually encode the URL (see JavaDocs for more information about this).
Also note that the name "jsessionid" is all lower case when it appears in the url itself. This is mandated by the Servlet Specification.

Faq ID

164

Product

ServletExec

Category

Session Tracking

Question

How does ServletExec track sessions with Legacy resources ?

Answer

The same way it does with Web Application resources with two exceptions:

By default, the name of the session id cookie is sesessionid instead of JSESSIONID

By default URL rewriting is disabled for session tracking of Legacy resources.
If you want ServletExec to examine the request URL for a session id after it determines that no session cookie was present, then you will need to enable URL Rewriting on the Session Tracking page of SE's Main Admin UI

Note that the name of the session id cookie used for Legacy session tracking is configurable on the Session Tracking page of ServletExec's Main Admin UI.

Faq ID

64

Product

ServletExec

Category

Session Tracking

Question

I'm concerned about hackers being able to calculate a valid session id. What can I do to protect against this?

Answer

First you should use SSL to protect against packet sniffing. Then you should do the following:

When a session is created, add the IP address of the client to the session.

On subsequent requests make sure the IP address of the client for the request matches the IP address of the client stored in the session.

This way the hacker would not only need to calculate a valid session id but also determine the IP address of the client for that session id.

NOTE: this solution won't work well with web servers that run behind a proxy server since in this case the client IP address will be the same for all requests.

Faq ID

149

Product

ServletExec

Category

Session Tracking, Web Application

Question

Is there a way to share session data across different web applications on the same host ?

Answer

With SE 5.0 this will be possible.
One way would be to use the JdbcSessionManager in your webapps so that session data is stored in a database. You'd also need to set the cookie path of your web-app session cookies to be a single forward slash (/) so that the client/browser will return the cookie to all webapps on that server no matter what their context path is.
Another way would be to use the Pluggable Session Management feature added in SE 5.0 to write your own SessionManager and have your web-apps use the custom SessionManager that you write.

Prior to SE 5.0, no.
The Servlet 2.3 Specification indicates that Web Applications are to have separate and distinct, sessions and session management.
Specifically, that document says:

SRV.7.3 Session Scope
HttpSession objects must be scoped at the application (or servlet context) level.
The underlying mechanism, such as the cookie used to establish the session, can be the same for different contexts, but the object referenced, including the attributes in
that object, must never be shared between contexts by the container.
To illustrate this requirement with an example: if a servlet uses the
RequestDispatcher to call a servlet in another web application, any sessions
created for and visible to the callee servlet must be different from those visible to the calling servlet.

However there are a few options available for transmitting information from one web application to another when using a version of SE which precedes SE 5.0:

You could create your own cookie using a cookie path of '/' and return it in the response. Then the cookie would be sent in all subsequent requests (even requests for other web apps). Code in other web apps could then examine the request for this cookie and obtain its value. NOTE: This would not be a session cookie. It would simply be a custom cookie having a name and String value that your code can look for and use in some custom manner.
This option is probably the most portable.

You could use hidden form fields in the HTML that you web app code emits.

You could enable context sharing for a ServletExec Virtual Server. This would allow servlets running in one web app to access the contexts of other web applications by using:
ServletContext.getContext()
Once a web app has a reference to the context of another web app,
ServletContext.getAttribute()
could be used to get attributes that had been previously set (in that other web-app's application scope, not the session scope).

Note: this solution is not the best since it requires that the code have knowledge of how other web apps are deployed (their context path) and also may not be portable to other app server brands (context-sharing between web apps is not mandated by the Servlet 2.3 spec).

Faq ID

63

Product

ServletExec

Category

Session Tracking

Question

Why do some of my servlets throw a ClassCastException when retrieving session data?

Answer

When running your servlets outside the context of a web application, classes that are shared by multiple servlets (such as session data classes) must be placed in the Main ServletExec classpath instead of the Servlets directory. If they are placed in the Servlets directory then ClassCastExceptions will occur.
This problem can likely be avoided by running your servlets inside the context of a web application (since each web application uses a single, custom classloader for loading all classes).

Faq ID

349

Product

ServletExec

Category

Session Tracking

Question

With which databases can I use ServletExec's JdbcSessionManager?

Answer

The JdbcSesssionManager is a feature that was added to ServletExec beginning with version 5.0.
It was designed to be easily customized to work with practically any database that supports
row-level locking.
It has been tested by New Atlanta with the following databases:

If you are using SE 6.0 or higher then the answer is "Yes when using IIS running on a CPU whose architecture is AMD64/Intel64". See the System Requirements area of this website for more details.

If you are using SE 5.x then the answer is either "Yes when using IIS running on a CPU whose architecture is Itanium", or "Yes when using IIS running on a CPU whose architecture is AMD64/Intel64, and when that IIS has been configured to load 32-bit DLL's and when using a 32-bit JVM."

Please read below for the gritty details for doing this.
According to the information found in a Microsoft technote, this should be possible. Go to:
http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS
Then click on the link for "IIS 6.0 Technical Reference".
Then click on the link for "Running 32-bit Applications on 64-bit Windows".
At the time this FAQ was written, the information found there was:

Running 32-bit Applications on 64-bit Windows (IIS 6.0)
Windows Server 2003, Service Pack 1 enables IIS 6.0 to run 32-bit Web applications on 64-bit Windows using the Windows-32-on-Windows-64 (WOW64) compatibility layer. IIS 6.0 using WOW64 is intended to run 32-bit personal productivity applications needed by software developers and administrators, including 32-bit Internet Information Services (IIS) Web applications.
On 64-bit Windows, 32-bit processes cannot load 64-bit DLLs, and 64-bit processes cannot load 32-bit DLLs. If you plan to run 32-bit applications on 64-bit Windows, you must configure IIS to create 32-bit worker processes. Once you have configured IIS to create 32-bit worker processes, you can run the following types of IIS applications on 64-bit Windows:
Internet Server API (ISAPI) extensions
ISAPI filters
Active Server Page (ASP) applications (specifically, scripts calling COM objects where the COM object can be 32-bit or 64-bit)
ASP.NET applications
IIS can, by default, launch Common Gateway Interface (CGI) applications on 64-bit Windows, because CGI applications run in a separate process.
Configuring IIS to run 32-bit Web applications on 64-bit Windows
Before you configure IIS to run 32-bit applications on 64-bit Windows, note the following:
IIS only supports 32-bit worker processes in Worker Process Isolation mode on 64-bit Windows.
On 64-bit Windows, the World Wide Web Publishing service can run 32-bit and 64-bit worker processes. Other IIS services like the IIS Admin service, the SMTP service, the NNTP service, and the FTP service run 64-bit processes only.
On 64-bit Windows, the World Wide Web Publishing service does not support running 32-bit and 64-bit worker processes concurrently on the same server.
For the procedure to run 32-bit Web applications on 64-bit Windows, see Configuring IIS to Run 32-bit Applications on 64-bit Windows.
After configuring IIS to run 32-bit Web applications on 64-bit Windows
After you configure IIS 6.0 to run 32-bit Web applications, IIS stores 32-bit DLLs and ISAPIs in the %windir%\syswow64\inetsrv directory. All other IIS files, including the MetaBase.xml file, are stored in the %windir%\system32\inetsrv directory. File access to the System32 and sub directories are transparently redirected based on the bitness of the process making that file access (64-bit processes have full access, while 32-bit processes have access to System32 redirected to Syswow64). If your legacy applications have specific 32-bit file access needs and you notice application failures, see if the application needs to reference the new %windir%\syswow64\inetsrv to resolve the problem.

The article mentioned above which is named: "Configuring IIS to Run 32-bit Applications on 64-bit Windows"
links to another Microsoft technote page which says:

To enable IIS 6.0 to run 32-bit applications on 64-bit Windows

Open a command prompt and navigate to the %systemdrive%\Inetpub\AdminScripts directory.

Type the following command:
cscript.exe adsutil.vbs set W3SVC/AppPools/Enable32BitAppOnWin64 "true"

Press ENTER.

Note that if your IIS was previously running in 64-bit mode with some 64-bit ISAPI filters then these filters will need to be removed or changed to their 32-bit equivalents before IIS will run properly in 32-bit mode. For example, if you have ASP.NET 2.0 installed then you'll need to make sure the ISAPI filter for it points to the 32-bit version of aspnet_filter.dll and not the 64-bit version.

Note that several customers have reported to us that the above procedures work just fine. However 1 customer who was using Windows Server 2003 R2 (64-bit) told us that the above procedures did NOT work for them. That customer rebuilt their machine to use Windows Server 2003 SP1, performed the procedures given above and it then worked for them. So it would seem (at least from that 1 customer report) that R2 may require other or additional procedures, but we've not tested that here.
However, the information given here:
http://office.microsoft.com/en-us/assistance/HA100211591033.aspx
(under the heading: "Configuring IIS for 32-Bit Emulation Mode")
clearly states that the procedure for configuring 64-bit IIS to run in 32-bit Emulation Mode is exactly the same for both Windows 2003 & Windows 2003 R2.
At the time this note was written, the link above gave the following information:

Click Start, and then click Run.

In the Open box, type cmd, and then click OK.

In the command prompt window, navigate to the %drive%:\Inetpub\Adminscripts folder, where %drive% is the drive in which Windows Server 2003 is installed.

The only difference we see between the 2 sets of Microsoft-recommended steps given above is that the first set uses:
W3SVC/AppPools/Enable32BitAppOnWin64 "true"
while the 2nd set uses:
W3SVC/AppPools/Enable32BitAppOnWin64 1

If you are using R2, and neither of the above 2 procedures work for you, then you may want to contact Microsoft about it, and ask them "how do I make my 64-bit IIS on R2 be able to load 32-bit DLL's ?"

Faq ID

348

Product

ServletExec

Category

System Requirements

Question

Does ServletExec 5 support Windows Vista?

Answer

We've not tested SE 5 on Vista, so that combination is not officially supported.
SE 6 will officially support Vista.

We can say that we have 1 Vista machine here where we installed SE 5.0.0.13 AS running with its built-in webserver
and it works fine for light development use. You are welcome to install SE 5 on a Vista machine and see how it goes.

The only issue we found is that Vista has IPv6 support enabled, and SE 5 does not fully support IPv6.
To better understand that issue and how to get around it, please see SE FAQ #347

Faq ID

361

Product

ServletExec

Category

System Requirements

Question

The documentation states that SE only works on a 64 bit Windows operating system. Is that correct?

Answer

No.

Perhaps you have found the following statement in section 2.2.2 of the SE 5.0 Installation Guide:

ServletExec/ISAPI 5.0 will only run on Windows 2003 64-bit Edition with a 64-bit version of the JDK/JRE.

That statement is poorly worded.
In fact SE 5.x is best suited for 32-bit (x86) systems.

SE 6.0 supports both x86 and x64, and that statement was updated in the 6.0 docs to read as follows:

ServletExec/ISAPI 6.0 (when run on a 64-bit Edition of Windows) requires that the JDK/JRE also be a 64-bit version.

Faq ID

302

Product

ServletExec

Category

System Requirements, Web Server Support

Question

What can you tell me about 64-bit CPUs for Windows and SE's support for them?

Answer

Currently there are a few different 64-bit architectures available for Windows.
They fall into 2 categories:

A 32-bit chip that has had 64-bit capabilities added to it (64-bit Extensions, refered to as X64)

A full-blown 64-bit chip

Here are some details:

In the second quarter of 2004, Intel outfitted its 32-bit Xeon processors
with the ability to run 64-bit as well as 32-bit applications.
They call it Intel Extended Memory 64 Technology, or Intel EM64T

2 reasons they did this are:

For users who currently are running 32-bit applications on Xeon-based systems
and who want to gradually migrate into 64-bit computing.

To compete with AMD's Opteron chips, which also run 32- and 64-bit x86 applications, and
which came out about 1 year before Intel's EM64T.

Intel's Itanium is a higher-end 64-bit CPU for customers with needs for more memory and higher performance.
Itanium systems can run 32-bit applications, but only through an emulation software layer, and at a lower level of
performance than 64-bit software.

SE 5.0 ISAPI supports 64-bit IIS running on Intel's Itanium architecture.
When run on an Itanium machine, the ServletExec_ISAPI.dll file that the
5.0 ISAPI installer will install, will be a 64-bit version of that DLL which was built
for the Itanium architecture.
This way the 64-bit IIS running there will be able to load the 64-bit DLL.
So long as your JVM is also 64-bit, then SE should work fine. New Atlanta has tested this
on an Itanium machine using Windows 2003 Server, Enterprise and found that it worked fine.

Before running the SE 5.0 ISAPI installer on an Intel EM64T machine, you must have a 32-bit JVM installed and you must configure IIS to run in 32-bit mode as described in FAQ #296. This must be done before installing SE 5.0 ISAPI. If you are using the SE 5.0.0.13 ISAPI installer or later then no other installation steps are necessary. Older SE 5.0 ISAPI installers incorrectly install the ISAPI DLL for Itanium
onto the machine (wrong architecture). This has been identified as SE Bug #2131. This will never work. But since IIS on EM64T is actually a 32-bit application,
the solution is very simple. Right next to the ServletExec_ISAPI.dll file (which is a 64-bit Itanium DLL)
you should see a file named ServletExec_ISAPI32.dll (likely in the C:\Inetpub\Scripts\ folder unless you selected
some other location during the SE installation process).
You just need to stop the IIS admin service, rename ServletExec_ISAPI.dll to something like ServletExec_ISAPI.dll_5.0_Itanium,
and then copy ServletExec_ISAPI32.dll, to ServletExec_ISAPI.dll. Note that you must leave a file named ServletExec_ISAPI32.dll in this location so that ServletExec will uninstall properly. Then start your website and try to request <hostname>/servletexec/admin.

It has also been found that Bug #2131 (see above) occurs with the SE 5.0.0.13 AS installer when run against the IIS webserver (definitely on Win 2003 Server R2, and possibly on other Windows versions).
When this problem occurs, the ServletExec_Adapter.dll file that is placed into the ...\Inetpub\Scripts\ folder on the hard-drive will be about 249KB in size. This is a DLL that's intended for the Itanium Architecture which again... will never work on a Xeon machine. The result would be that IIS is unable to load that DLL (SE Filter in IIS would show with red arrow pointing downward, and Event Viewer messages would indicate that IIS could not load that DLL).
The solution in this case is to manually apply the August 2006 Hotfix (or a newer one if available). This is mainly to replace the incorrectly installed Itanium DLL with one that will work on Xeon (about 89KB in size). FAQ #195 tells how to obtain and apply the latest hotfix.

UPDATE:
A variation of bug #2131 has been found to occur (in rare cases) with the SE AS 6.0 installer on 32-bit Xeon CPU Windows, when run against IIS.
SE 6.0 does not support the Itanium CPU.

Here is the problem description:
On Xeon CPU machines running 32-bit Windows, the installer for SE 6.0 AS on Windows will incorrectly install the AMD/Intel 64-bit (x64) version of ServletExec_Adapter.dll.
This occurs on machines that have SQL Server Reporting Services installed (the SQL Server Database need not be installed for this problem to occur).
The reason this problem occurs is because the SE 6.0 AS installer looks in the Windows registry in order to decide if the OS is 32-bit or 64-bit. It looks for the presence of this Registry key:
HKEY_LOCAL_MACHINE\Software\Wow6432Node\

It appears that that key is present even on a 32-bit OS when the SQL Server Reporting Services are installed.
So the installer then installs a 64-bit DLL which is incorrect... resulting in the 32-bit IIS not starting up properly and Windows Event Viewer messages indicating that ServletExec_Adapter.dll is not the correct bitness for IIS to be able to load it.
The solution is to stop the IIS Admin Service, rename C:\Inetpub\Scripts\ServletExec_Adapter.dll to ServletExec_Adapter_x64.dll, and then copy C:\Program Files\New Atlanta\ServletExec AS\bin\isapi\ServletExec_Adapter.dll to C:\Inetpub\Scripts\

Then IIS should be able to load that DLL so that SE can function.

Here is a detailed breakdown of the various SE 6.0 native DLLs required when using SE 6.0 AS with IIS.

(NOTE: SE AS does require ServletExec_ISAPI.dll during installation and uninstallation, but does NOT need that file during runtime.
The reason it needs that DLL is because that DLL also contains some code that is used to hook/unhook SE from IIS).

One other point about using SE AS 5.0.0.13 on a 64-bit Windows OS:
Be sure to add the -Xrs JVM option to your StartServletExec.bat file.
For more details, see:

SE 5.0 ISAPI has not been tested on an AMD x64 version of Windows.
If IIS runs as a 32-bit application on that architecture, then most likely the workaround described
above would work. But if IIS runs as a 64-bit application on that architecuture, then you should know
that it likely won't work.

Summary:

The only 64-bit architecture for which SE 5.0 ISAPI currently has a DLL is Itanium.
The bitness of your IIS matters.
A search on the web turned up the following relevant postings from a Microsoft engineer:

IIS is the same bitness as the underlying OS.
There is no such thing as 32bit IIS on 64bit Windows or 64bit IIS on 32bit
Windows.
Also, 64bit IIS will support running 32bit web applications with WS03SP1.
Unless you are running WS03SP1 on AMD64 or running WS03 on Itanium, you are
likely running 32bit OS and IIS.

I believe the instructions you followed resulted in building an IA64 binary
for the Intel Itanium Family of Servers. It is NOT the same as X64
architecture of the popular AMD64 nor Xeon 64. Thus, when you try to run
IA64 binary code on an X64 architecture machine, it is incompatible and
failed by design.
You are going to have to compile an X64 binary to natively run it on AMD64
or Intel X64.
...
...

The quote above was found here
NOTE: It is not you (the customer of New Atlanta) that needs to compile the SE DLL.
It is New Atlanta that may need to do this depending on your Architecture and the bitness of your IIS.

What is New Atlanta's position with regard to running ServletExec AS on Unix variants that are not officially supported?

Answer

The appropriate System Requirements section of the appropriate ServletExec Installation Guide will list the specific Operating System / Web Server combinations which are officially supported. For other UNIX configurations:

ServletExec is not officially supported on Solaris for Intel, or any Unix variant that's not listed in the System Requirements section (either online or in the Installation Guide).

However, ServletExec/AS, when used ONLY with the Apache web server, will most likely work on Solaris for Intel, and other untested/unsupported Unix variants.

This might seem obvious since ServletExec is (essentially) 100% Java. However, in order for an installation of ServletExec to integrate with any production-grade, supported web server, the use of a native code adapter to connect with the associated web server is required.

When used with Apache on a UNIX/Linux machine, this adapter is delivered in source code form and is built right on that machine during the installation process using the GNU C compiler and a linking-loader (gcc and ld).

Therefore, ServletExec/AS should run with Apache on Solaris for Intel and also with other Unix variants such as SuSE Linux, Caldera Linux, 64-bit systems, and any other untested/unsupported platform that supports a version of JVM that SE supports.

Please note that GNU C compiler (GCC) must be used. Vendor-specific C compilers are NOT supported. Using one will likely result in installation failures. Also, vendor-specific Apache distributions are not supported.
Please see SE FAQ #141 for more information regarding that.

Note that we currently have a small set of customers who have successfully installed and are using the ServletExec/AS product on unsupported platforms, namely SGI IRIX and Compaq Digital UNIX. Although, we cannot assure that these installations will operate without some unknown difficulties since we have not tested these configurations. Therefore we do not support them officially.
We will assist customers with any installation or configuration problems free of charge just as we do with our standard product usage. However, there will be no support for problems that arise which are due to the Operating System and/or the Java VM port with these non-standard/unsupported configurations.

Faq ID

190

Product

ServletExec

Category

System Requirements

Question

When will ServletExec support Red Hat Linux Advanced Server 2.1 ?

Answer

ServletExec 4.2 AS for Apache should work just fine on this OS.
In the past SE x.x AS for Apache has always worked fine on newer versions of Unix/Linux.
The important thing is that you use a brand and version of webserver that is supported with the version of SE you are using.

Version differences

Faq ID

95

Product

ServletExec

Category

Version differences

Question

How can I find out exactly which configuration of ServletExec I am running?

Here are some ways you can find out which configuration of SE you currently have installed on your machine:

If your OS is Windows then open the "Add/Remove Programs" Dialog and look for "ServletExec". There it will say either ISAPI or AS.

Use your browser to login to the ServletExec Admin UI and then look in the upper left corner. If it says ISAPI then you are running SE ISAPI. If it says NSAPI then you are running SE NSAPI, if you see the name of your SE AS instance (typically the name of your machine) beneath "ServletExec" then you are running SE AS.

Look on your hard-drive where SE is installed. Look at the name of the folder. Is it "ServletExec ISAPI" or "ServletExec AS"?

If your OS is Windows, then open the Windows Services Dialog and look to see if you have a service whose name goes something like this:
"ServletExec-<instance-name>"
If so then you have SE AS installed.

Look at the name of the installer that was used to install your SE. If the name has "ISAPI" or "NSAPI" in it, then you are running either SE ISAPI or SE NSAPI. If the name of the installer has "AS" in it then you are running SE AS.

Virtual Server

Faq ID

126

Product

ServletExec

Category

Virtual Server

Question

How is the Virtual Directory (VD) in IIS used by the ServletExec ISAPI Filter that's configured in the IIS Metabase ?

Answer

For every request that comes to IIS, IIS will pass it to the ISAPI filters that are hooked into IIS. This is true for all such filters (SE ISAPI, SE AS, or some other vendor's ISAPI filter-based program). Each ISAPI filter gets to tell IIS "this request is for me, don't hand it off to any subsequent filters that come after me", or "this request is not for me, pass it to the next filter". This can be thought of as the request-filtering phase of the request handling process.

If the SE Filter decides that the request is meant for SE, it will make an ISAPI callback to perform an internal redirect (not a round trip to the client) to invoke either ServletExec_ISAPI.dll (For SE ISAPI) or ServletExec_Adapter.dll (for SE AS). The Virtual Directory which points to where that DLL resides is used for this internal redirect.

In this way the DLL is invoked again... only this time it runs in a different "mode". It can be thought of as the request-servicing phase.
This is where the native DLL code passes the request info to SE's Java code (running inside the JVM) which then builds the response that the webserver then sends to the client.

Here is some more detail on the Virtual Directory:
With the default IIS website, the ServletExec filter looks for the very FIRST virtual folder/directory that points to the physical folder containing the ServletExec DLL and uses that. Normally this is the virtual folder named "Scripts".
When using ServletExec with subsequent IIS virtual Servers they must have a Virtual folder that points to the physical folder containing the ServletExec DLL, AND that virtual folder must have the same exact name as the virtual folder in the default IIS website. So for example if you have more than one virtual folder defined in the default IIS website that points to the folder containing ServletExec DLL, then the one that is listed first is the one that is actually being used by the ServletExec filter. Therefore you would have to create a Virtual Folder in the 2nd IIS virtual server having the same name in order to use ServletExec with that 2nd IIS Virtual Server.

Faq ID

54

Product

ServletExec

Category

Virtual Server

Question

I have SE working with IIS in the default configuration (default website). Now I want to get it working with a different IIS website. How can I configure this?

Answer

Here is how you do it:

Create a new virtual directory (VD) within EACH of your new IIS virtual domains (each IIS website) with which you want to use ServletExec. For SE AS the name of this VD must be "Scripts", for SE ISAPI it's name is "ServletExec". You'd do this in the MMC (Microsoft Management Console). The important thing is that all SE-enabled IIS websites must use exactly the same name for the VD. Typically you already have IIS site 'A' (Default Web Site) using a VD named "Scripts" or "ServletExec". So for IIS site 'B', site 'C', etc... you need to use the same name for your VD.

Point each VD to the physical folder on your hard drive where the ServletExec DLL resides. This is probably "...\Inetpub\Scripts\", and be sure to give each VD "Execute (including scripts)" (or "Scripts and Executables") Permission in the MMC.

FYI: Each VD that points to the folder where the DLL resides, for each IIS Domain, MUST have the exact same name and must have "Scripts and Executables" Permission [also known as "Execute (including scripts)" permission]. Also the ServletExec filter that is set up in the Metabase (Master properties dialog, not the properties dialog for the website) must point to the ServletExec DLL file that resides in the physical "Scripts" folder.

Tech Note:
The reason that the VD must have the same name in each IIS website is because on the first request, the SE DLL will ask IIS "which VD points to me?" and it will 'cache" the answer from then on (until the next time IIS is cycled). That VD is then used when requests are routed to SE to be processed. If more than 1 VD in a single IIS website points to the SE DLL then you may need to ensure that ALL of them have the proper permission settings since it's unclear which VD IIS will say is the one that points to the SE DLL. It's likely the first one you see listed in the MMC, but that may not be true in all cases. It's up to IIS.

Faq ID

113

Product

ServletExec

Category

Virtual Server

Question

I'm running SE in a virtual server environment. When I request a JSP from one virtual server, sometimes I get a JSP from the other virtual server instead of the one that I expected. What is wrong?

Answer

This problem does not occur when using a Web Application.
It only occurs if you are running your JSPs as "Legacy" (i.e. non-webapp).
When this problem occurs, it is likely that the 2 JSPs have the same name. If things are not configured correctly, JSP files generated for one virtual server can overwrite the files generated by another virtual server. Anytime you are running ServletExec with multiple Virtual Servers you must make certain that ServletExec is creating and using a separate pagecompile folder for each virtual server. This way JSPs that execute for each virtual server will be the correct and expected versions for that virtual server.

If your virtual servers are distinguished by host name:

Then you would accomplish this by using the ServletExec Admin UI to add a Virtual Server for the 2nd, 3rd, ...etc host names and specify a unique Servlets folder for each. This will stop the generated servlet files from overwriting each other since each virtual server will have its own separate Servlets directory (and therefore its own separate pagecompile directory).

If your virtual servers are distinguished by port number:

Then configure the JSP10Servlet with the init argument packageLevel set to 1. This will cause the JSP10Servlet to add additional levels to the package used by the generated servlet files. This will cause the generated files to have unique package names and to be placed into unique directories beneath the Servlets directory.

If you continue to have problems with Legacy JSPs in a virtual server environment then you should verify that the generated files for each virtual server are being placed in separate directories and not in the same directory where they could overwrite each other.
Note: The best way to ensure that the JSP pages generated for each virtual server have a unique class name is to use Web Applications exclusively.

VM Settings

Faq ID

320

Product

ServletExec

Category

VM Settings, VM Support

Question

Does a JVM have any limitations on the amount of RAM I can allocate to the JVM's Heap?

Answer

The majority of this FAQ deals with 32-bit (x86) JVMs. For 64-bit (x64) JVMs please see the very bottom of this FAQ.

From what I've read and from personal experience, the limits are about:

Solaris 2.6 and x86 - 2GB

Solaris 7 and Solaris 8 SPARC - 4GB

Mac OS X - 2GB

Win (2000/XP) - 1648 MB

AS/400 / iSeries (V5R1M0) - Using os400.gc.heap.size.max (overwrites Xmx) 139,264,000 KB. If not set the setting defaults to *NOMAX which is around 240 GB

We've also found other supporting details online which are summarized as follows:

On 32-bit processor machines, the largest contiguous memory address space the operating system can allocate to a process is 1.8GB. Because of this, the maximum heap size can only be set up to 1.8GB.
On 64-bit processor machines, the 1.8 GB limit does not apply, as 64-bit processor machines have a larger memory address space.

I need to prevent ServletExec/AS from using the JITC but there is no way to set this from the admin UI. How do I do it?

Answer

When ServletExec is running out-of-process with the web server, you will not be able to disable the JITC from the admin UI, instead you have to edit the StartServletExec batch file (for windows) or script file(for UNIX) that is used to start ServletExec. To disable the JITC, you need to pass a-D
option to the java interpreter. In the appropriate StartServletExec file add the option:
-Djava.compiler=
so that the java interpreter receives the option (with no value). Then stop and restart ServletExec.

You can check to see if the JITC is disabled by looking at the Virtual Machine Settings page of the SE admin UI. The entry for the JITC should now read "none" An alternative way to disable the JITC is to use Sun's Hotspot Client VM or Server VM.

Faq ID

367

Product

ServletExec

Category

VM Settings

Question

I used the SE Admin UI to configure my heap settings and now I can't access the SE Admin UI to change it back. How do I correct this?

Answer

If using SE ISAPI, the preferred way to configure the JVM Heap size is to use the SE Admin UI (and then cycle IIS). But if you configure the heap with invalid values then it is possible that IIS won't load SE the next time it initializes. "Service Unavailable" is a common response seen in the browser in this case.

The solution is to use a plain text editor such as Notepad to manually edit the file that contains the heap size settings. There are 2 possible files that could contain this information. Which one is used in your setup depends upon which Admin UI page you used (VM Settings Page -or- VM Options Page) in order to configure the heap.

My Java code writes or reads a file, but the file cannot be found. Where did it go ?

Answer

If you don't specify the absolute path for the file, then the JVM will use the value of the System property named
user.dir
when reading or writing a file.

To get around this JVM issue, you have 3 options:

Use absolute paths for your files

append the value of the user.dir System property to the front of your filename

Set the user.dir System property to be what your code expects
NOTE: this option has the potential to break other code which may be relying on the value of that property (i.e. it may result in unexpected failures/behavior), so we don't really recommend it.

Faq ID

318

Product

ServletExec

Category

VM Settings

Question

What can you tell me about setting the Heap size of the JVM inside which my ServletExec installation runs?

Answer

Setting the Heap size of your JVM typically requires that you pass what is called
an "additional option" to your JVM. There are many additional options that a person
could pass to a JVM... for various reasons. When it comes to Heap size, there are
2 options in particular that you may need to use.
One of them is used to set the Min heap size, and the other is used to set the Max heap size.

If you would like to learn more about all of these "additional options" that Sun's JVM supports then please read
SE FAQ #182

If you are running SE in an out-of-process configuration (AS) then you must
do this by editing the StartServletExec script/batch file.
As the Javadocs (linked in the FAQ #182 pointed to above) explain, options are passed to a JVM like this:
java [ JVM options ] classname [ program arguments ]
This fact is also given in SE FAQ #33

As an EXAMPLE, here is the syntax for setting the Min heap to 128MB and the Max heap to 256MB:
java -Xms128M -Xmx256M -classpath "C:\myClasses;C:\myJars\a.jar" MyJavaClass arg01 val01 arg02 val02

If you are running SE in an in-process configuration (ISAPI or NSAPI) then
you must do this from the SE admin pages (in your browser).
You can use either:

You would then need to cycle the JVM by cycling the webserver.
NOTE: for IIS 5 & 6, this means cycling the Windows service named "IIS Admin Service". For IIS 7 this means cycling the *single* IIS Application Pool in which SE ISAPI is running.

NOTE: If you then receive "Service Unavailable" responses when trying to access the SE Admin UI pages (or any servlet or JSP) then please read SE FAQ #367

If you are running SE ISAPI, then you should also be aware of an IIS limitation on the amount of RAM (i.e. heap) that
the JVM can grab. SE FAQ #317 explains.

For additional information about the Java Heap, you should also read:
SE FAQ #320 for more details.

What values does New Atlanta recommend for setting the Min. and Max. Heap size of the JVM ?

Answer

We don't really have any hard recommendations for you.
Most people just use the default settings that are established by the JVM version. If you start running into OutOfMemory Exceptions, or just like playing around with Heap sizes then we recommend that you:

Research what Sun Microsystems has to say on the matter.
How to use the -X options [ -Xms for min heap, and -Xmx for max heap ] to set the min and max heap sizes is discussed in the JavaDocs for JDK 1.3.x and newer.
Here for instance:
JVM Non-Standard Options

Do your own testing.
Configurations such as heap size are highly dependent on an individual's specific situation. Anyone that tells you:
"oh, just set it to this..."
is probably doing you a disservice. There is no substitute for tweaking this yourself and studying the result. What works well for one application (on one machine) may not necessarily work well for another.

When using SE ISAPI with IIS 6, how much RAM may I allocate for my JVM's Heap?

Answer

From customer reports, the answer depends on the number of processors on the machine.
It appears that IIS 6 will limit the amount of RAM for each application pool (IIS 6 or higher only) to 256 MB per CPU.
This can be tested at SE ISAPI startup time, by setting the Min Heap (not the Max Heap)
to various values and seeing how high you can go before IIS will no longer startup fresh. Setting the Min. heap allows you see the effect
right away (at JVM startup time) since the JVM will try to grab all that memory right then.
This can be better than using Max heap only and then having to wait for the heap to grow large enough to show you the effect. Note that with IIS 6, you can't simply cycle IIS, you must then send a request to IIS so that IIS will then crank up SE ISAPI (which will then crank up the JVM which will then try to grab RAM for it's min. heap).
One customer did this (set the Min heap to various values) and reported the following:

We use Win 2003 (IIS 6) and JVM 1.4.2_08 on all the machines.
The highest value for Min Heap that we have been able to set on the 2 CPU macines is 512MB.
We tried 768MB but that failed (IIS won't startup and we get "Service Unavailable" in the browser).
We tried to increase the memory on a 4 CPU machine to 1.5GB, but found that 1GB was the highest we could go there.
So... 512MB on a 2 cpu box, and 1GB on a 4 cpu box... yes we agree, this appears to be an IIS limitation that's related to the number of cpu's.

Here is ONE way to set the Min (and Max) heap size for SE ISAPI (using 1GB ==> 1000M as an EXAMPLE):

Go to the VM Options admin page and enter -Xms1000M in the text area beneath the one that contains -Xmixed
(that is for MIN heap)

Submit that and then verify that the admin page now shows the additional entry you just put there.
(maybe even go view vmoptions.properties to verify that the -Xms1000M was written there.

now repeat it for -Xmx1000M (if you want to also set Max heap... probably uneccessary)

Now cycle the service named "IIS Admin Service"

Now try to request something from IIS (using your browser) does it get served? Or do you get "Service Unavailable" ?

NOTE: If you configure your MinHeap to a value that IIS cannot allocate, then you'll likely receive "Service Unavailable" responses when trying to access the SE Admin UI pages (or any servlet or JSP). If this happens to you then please read SE FAQ #367

It is our belief that if a person were to set their Max heap too high for the given number of CPU's,
it would be like a time bomb... as soon as the heap tried to grow beyond the IIS 6 limitation it would be prevented
from doing so. At that point, the JVM would effectively be OutOfMemory. The result then would be INDETERMINATE.
That means that the JVM might be able to recover, might be able to report OutOfMemoryError, or might not be able to do either.
Such an error is considered to be very nasty, and could result in the JVM crashing hard with no errors.
When the JVM is running inside the IIS process (as is the case with SE ISAPI) then such a crash could potentially
cause IIS itself to crash, giving ugly Dr. Watson errors, or Windows Events.
You could check ServletExecNative.log and/or ServletExec.log for clues in such a case. But those files may or may not contain clues.

SE FAQ #5 is an example of a similar case.
Similar in the sense that it's an IIS (not just IIS 6) limitation that is effected by the number of CPUs on the machine.
For that case, there is actually a Windows registry entry that can be used to configure IIS differently, to get past that
particular limitation. We don't know if there is a similar fix for the 256MB per CPU limitation of IIS 6 app pools (maybe the app pool can be configured differently). If you need to know, you might consider asking microsoft about it. Or you might consider using SE AS instead of SE ISAPI to sidestep the entire issue.

And here is yet another example (not CPU related) of how IIS sometimes needs a registry entry value in order
to behave as one might prefer.

Yes.
As of 2.10.2005, this has been tested and found to work fine on Windows.
It will also work on Unix if you use the SE 5.0.0.13 installer [the name of that installer is "ServletExec_AS_50013.sh"].

If for some reason you cannot use that Unix installer, and must instead use the SE 5.0 Unix installer [ServletExec_AS_50.sh], then some extra effort is required.
Here are the steps to getting SE 5.0 (not 5.0.0.13) installed and running on a Unix machine:

The installer will ask you where your JVM resides.
If you point it to JVM 1.5, the installer will abort.
To get past this, setup a symbolic link of /usr/java
that points to JVM 1.3 or JVM 1.4 and when the installer
asks you for where your JVM resides, tell it /usr/java
This way the installer should complete normally.
Then you can change the /usr/java link to point to your JVM 1.5 installation.
Note: The point for using a symbolic link is so that you don't have to edit any
files.

The StartServletExec script that the installer creates
for starting your SE AS instance will exit if it detects
that it's being asked to run with JVM 1.5.
You can correct that script by editing one line as follows:
Replace:
$JR -version 2>&1 | egrep '1.2|1.3|1.4' > /dev/null
with:
$JR -version 2>&1 | egrep '1.3|1.4|1.5' > /dev/null

Please note that beginning with JVM 1.5, "enum" is now a reserved word.
This means that if you have code that uses "enum" for the name of any
variable, that code won't compile with JVM 1.5. Since JSPs are compiled
by the servlet engine, a JSP that uses "enum" won't compile under JVM 1.5.
Such code will run under JVM 1.5, but won't compile using JVM 1.5.
JVM 1.5 may have other such quirks that you may discover when trying to use it.
There is nothing that ServletExec can do to effect JVM requirements like this.

Yes. But if you need to use JDK 1.5.x then you'd be better off just using JDK 1.5.0_12.

If you really need to to use 1.5.0_11 then you need know about some things:

With JDK 1.5 installed:
HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit\CurrentVersion = 1.5
This is correct.
The 1.5 Registry entry has a JavaHome entry whose value points to where the JDK was installed.
For example with JDK 1.5.0_10:
HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit\1.5\JavaHome=C:\Program Files\Java\jdk1.5.0_10
This is correct, and works fine.

If you then install JDK 1.5.0_11, the value of that JavaHome Registry entry becomes "1" (no quotes).
This is completely wrong, and is due to a bug that Sun introduced into the installer for their JDK 1.5.0_11.
Here is the report for that particular Sun JDK installer bug.
The fix is to use RegEdit to manually modify that JavaHome value.
In the above example, the value should be changed to:
C:\Program Files\Java\jdk1.5.0_11
When this problem occurs, SE ISAPI will fail to startup.
This is because ServletExec_ISAPI.dll uses the registry to find the JDK.
Since the registry is wrong, SE's DLL is unable to load the JDK.
ServletExecNative.log (& DBMON) would show the following sort of errors:

If the SE AS installer is run on a Windows machine whose Registry is in this incorrect state,
then the SE AS installer will:

fail to create (or update) the webadapter.properties file

create StartServletExec.bat & StopServletExec.bat files which have an invalid path to the JDK,
thus preventing them from being useable.

The solution is as follows:

uninstall SE AS

fix your registry so that HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit\1.5\JavaHome points to the correct location (instead of having a value of 1 which is incorrect).

re-install SE AS

The reason an invalid registry causes problems for the SE AS installer is because the SE AS installer
actually uses the JDK for certain tasks (writing webadapter.properties, and the start and stop batch files).
If the SE installer can't find the JDK, then it can't complete these tasks properly, leaving you with an SE installation that's missing some required files.

NOTE: The installer for JDK 1.5.0_12 does not suffer from this problem.

Faq ID

148

Product

ServletExec

Category

VM Support

Question

I am trying to run some Java code with ServletExec running on the Solaris Operating System that uses some simple AWT features, and it won't run. It is resulting in very strange behavior. What is wrong?

Answer

Based on the testing we have done here, this problem does not appear to be due to ServletExec.
It appears to be a problem in how the JDK is setup by default after it has been installed on a Solaris OS.
Often the error message seen when this problem occurs looks something like this:

java.lang.UnsatisfiedLinkError:
.../jre/lib/sparc/libfontmanager.so: ld.so.1:
/usr/bin/../java/bin/../bin/sparc/native_threads/java: fatal:
libmawt.so: open failed: No such file or directory
at java.lang.ClassLoader$NativeLibrary.load(Native Method)

AWT makes native calls and it appears that the default installations of certain JDK/JRE implementations for Solaris (we've seen it with JDK 1.3.1) are not setup correctly to look for and use a required .so file named "libmawt.so"
There are a few different ways that you could setup your JDK so that it can find this necessary file. Here are some possible ways to do this, using JDK 1.3.1 (as an example):

The JDK wrapper script that is used to execute java, javac, jar, etc... may already have:
/jre/lib/sparc/ added to the LD_LIBRARY_PATH
Environment variable. If this is the case you could find the correct libmawt.so file for your version of Solaris and place a copy of it into that folder so that your JVM will always be able to find it.
On our Solaris 7 machine we found 2 libmawt.so files for our JDK 1.3.1 installation.
One was found at:
/jre/lib/sparc/motif12/libmawt.so
and the other was found at:
/jre/lib/sparc/motif21/libmawt.so
Our testing showed that Java code (running on the command line, not within ServletExec) which makes a simple AWT call such as:
Component test = new Frame();
would fail to run if we used the motif12/libmawt.so
But would run just fine if we used the motif21/libmawt.so

Another way to fix this so that your JDK installation will work with AWT code, would be to create a symbolic link in the
/jre/lib/sparc/ folder.
The name of the symbolic link would need to be libmawt.so and it should point to the actual libmawt.so file that is correct for your version of Solaris.

Suggestions #1 and #2 above may solve the problem for the entire
JDK on that machine. Which means it would not matter how you were using that JDK (from a command line, from an Application Server).
But if you just wanted to fix this so that your AWT code will only run correctly if run within an Application Server (such as ServletExec), then you may be able to adjust how the Application Server sets up the JVM before it invokes the JVM. How you do this would be application-server specific and even specific to how that application server is running.
For example, if you were running SE NSAPI on a Solaris OS, then if you wanted to you could edit the setting of the LD_LIBRARY_PATH Environment variable within the iPlanet server start script. You would want to include the folder that contains libmawt.so.
Of course this solution only solves the problem for when your AWT code is running inside that application server.
It would not fix the problem for cases when the JVM is started up in some other fashion (directly from a command line, or by some other application server for example).

Faq ID

140

Product

ServletExec

Category

VM Support

Question

I am trying to start ServletExec and getting a "Failed to get JNI Environment" error. What am I doing wrong?

Answer

Make sure that you are not passing unsupported options to your JVM upon startup.
For example:
The -Xmixed option is valid for Sun's JDK 1.3.x and 1.4.x, but is not valid for Sun JVM 1.2.2, nor for IBM JDK 1.3.x (and possibly other brands/versions).
The ways to set these VM options vary depending on what configuration of ServletExec you are using:

If running SE in-process (ISAPI, or NSAPI), edit the vmoptions.properties file directly in a text editor to remove the -X options.
FYI: This could be done from the VM Options page of the SE Admin UI if you were able to start SE and access it, which might be the case if you were running SE fine with Sun's JDK 1.3.x or 1.4.x but then tried to switch to IBM's JDK for example.

If running SE out-of-process (AS) then edit the StartServletExec script to remove the -X options (or other options that your JVM might not support.

Then try to start ServletExec again.
NOTE: -D options are standard options and so they should be supported by all JVMs, so you should not need to remove them.
Also, when a problem like this occurs and you are running SE in-process (ISAPI or NSAPI), messages in DBMON upon startup of SE can be very helpful.
Usually they say something to the effect of:
ServletExec: -Xmixed
ServletExec: Java VM message: Unrecognized option: -Xmixed

Faq ID

181

Product

ServletExec

Category

VM Support

Question

ServletExec ISAPI or NSAPI on Windows won't work with the IBM JDK. What is wrong ?

Answer

Take a look at FAQ #140 at this site to see if that is the problem you are seeing. If that is not it, and you are using the IBM WebSphere SDK for Web Services 1.3.1 SR1 then:

Look at FAQ #6 at this site for a description of the algorithm that SE
is using when it examines the registry in order to find the Current Version
of JVM.

IBM WebSphere SDK for Web Services 1.3.1 SR1 does not create the registry
entries for which ServletExec is looking.
In our tests, that brand/version of SDK creates the following key:
HKEY_LOCAL_MACHINE\SOFTWARE\IBM\IBM WebSphere SDK for Web Services
So the problem is that IBM changed the
registry entries between their 1.3.0 and 1.3.1 versions, and ServletExec is
still looking for the old registry keys.

This problem can be worked around by manually creating the registry
entries for which SE is looking, with the proper variable values as described
by the algorithm.
In the case of IBM WebSphere SDK for Web Services 1.3.1 for example,
you would create a Registry Key:
HKEY_LOCAL_MACHINE\SOFTWARE\IBM\Java Development Kit
and give it a "CurrentVersion" string value of 1.3
Then you would create a Registry Key beneath that:
HKEY_LOCAL_MACHINE\SOFTWARE\IBM\Java Development Kit\1.3
and give it a "JavaHome" string value that is the absolute path to the
folder that contains the "bin" and "lib" folders for IBM's JDK.
For instance, in our tests with IBM WSDK 1.3.1 that location was:
C:\WSDK\sdk

Web Application

Faq ID

278

Product

ServletExec

Category

Web Application, Web Server Support

Question

I don't fully understand how default pages work with a webapp running inside ServletExec 5.x or higher.
Can you please explain it great detail?

Answer

A directory request (http://<hostName>/, for example) is an ambiguous request.
You're not really saying what resource you want.
You're expecting some component on the server side to decide what will actually be served.
The issue is that you have 2 components on the server side:

The webserver (IIS, iPlanet, or Apache)

ServletExec

And both are capable of serving things.

The webserver's notion of a file-list is often referred to as "default pages" (defined in the webserver itself).
ServletExec's notion of a file-list is often referred to as "welcome files" (defined in a webapp).

For any given request, only 1 or the other file-lists can be used (either "default pages" or "welcome files").
This is because only 1 or the other components (webserver or SE) will actually get to process the request by building the response. So the file-list ("default pages" or "welcome files") should only contain resources that the component defining it can actually process.
For example (using an ASP page as an EXAMPLE):
You can't list index.asp as a welcome file in a webapp since a webapp (running inside a servlet container such as ServletExec) can't process an ASP page (at least not without you adding that ability to that webapp). And the same logic is true for the reverse... you can't put index.jsp as a default page in IIS since IIS can't process a JSP.

To better understand this whole issue, you must understand which component is trying to build the response for your request.
There are a few factors involved in this decision.
Consider a webapp that is deployed in SE 5.x (or higher).
When a request comes to that webapp, SE must decide "is this a request for static content, or is it for dynamic content?".
This is decided by checking the aliases defined in the webapp against the request URI to see if the request matches any aliases (prefix, exact, or suffix aliases) that map to anything in the webapp (map to a servlet, or a filter, or a security constraint)... anything that would mandate that SE be the one to "service" the request by performing some action (typically by building a response). Another criteria for deciding that the request is for dynamic content is whether or not the request is a directory request and whether or not the webapp defines ANY welcome files.
If a directory request comes to a webapp that DOES define 1 or more welcome files then that is deemed a request for "dynamic" content, and SE will be the component that will build the response for that request.
If a directory request comes to a webapp that does NOT define any welcome files (and does not have a default alias mapping such as /* then that is deemed a request for "static" content.
If that webapp were set to let SE serve static content then the webapp will return 404-Not Found (since there are no welcome files defined in that webapp).
If that webapp were set to let the webserver serve static content then SE will hand the request back to the webserver and let the webserver try to service it. It makes no sense to try to have the webserver serve a JSP.

You may also need to understand the webapp named "default-app" which has special properties. It's a webapp that's deployed with every new SE 5.x (or higher) installation by default, and it is unlike other, "normal" webapps in the sense that it does NOT use it's own private document root that's separate from the document root of the webserver the way other, "normal" webapps do. Instead the default-app will use the document root of the webserver as it's own document root. Note that with SE AS, this would be the value of the -root option in the Start Script for the AS Instance [ASI]. If that value is edited from it's default, or if the ASI is on a separate machine from the webserver, then it may not truly be the webserver's document root. But it is still the place that is used as the document root of the default-app.
This is what allows someone to drop index.jsp into a webserver's document root (or whatever folder you are using as your -root), request it, and have it be found, and executed/served properly. In that scenario, the person may not even realize that their request actually executed within the context of the webapp named "default-app". This is an important distinction from other webapps because it effects where you should place your content (html files, images, etc...) The context (i.e. the webapp) to which a request maps (based on the context path in the request URI) and what that webapp uses as it's document root, matters.

One way to resolve this is to define ALL your default-pages/welcome-files using the file-list of your webapp running inside of SE (that is... don't use your webserver's file-list at all).
Here is the flow for doing that:
You'd define ALL your welcome files inside your webappp, even something such as index.asp, instead of using the webserver's file-list. Now if you just stop there, then SE would end up serving the source of index.asp as-is (i.e. not actually processed as you want). So don't stop there, have that index.asp be a "dummy" version, that just contains a redirect to the real index.asp... only the real index.asp is called something else like index.aspx. This way a request for http://<hostName>/<webappContextPath> would cause your webapp to serve index.asp (because it's listed as a welcome file within the webapp) which just does a META redirect or a javascript redirect (i.e. it contains no ASP code), redirecting the user to http://<hostName>/<webappContextPath>/index.aspx (or index2.asp, or whatever... just a file by some other name or in some other location within the webapp).
You still can't stop there though... you must also configure your webapp so that it lets the webserver serve static content.
This way when the webapp receives the redirected request for http://<hostName>/<webappContextPath>/index.aspx and deems it to be a request for "static" content, SE will tell the webserver to serve it, and the webserver (presumably IIS for this example) will know how to process index.aspx properly.
Or you could try to obtain a Servlet capable of actually processing the ASP (or whatever resource you're wanting to be served), configure it in your webapp, and then map *.asp to that servlet so that then your webapp actually could process that resource properly (no need to redirect).

I have upgraded to ServletExec 4.2 and I'm getting 404 errors because my jsp files are now case sensitive. How do I disable case sensitivity?

Answer

There is no way to disable case sensitivity in ServletExec. This change was made due to a security risk in older versions of ServletExec. Without this change, it was possible for page source to be served.

Faq ID

242

Product

ServletExec

Category

Web Application

Question

I removed/undeployed a webapp via the SE admin UI, but the webapp comes back whenever I restart SE. Why ?

Answer

Most likely the webapp that you removed, was originally deployed as an auto-deployed app. Removing/Undeploying an auto-deployed webapp is a multi-step process:

Use the SE admin UI to learn the location of the webapp and note this information for future use

Use the SE admin UI to remove the app

Delete or move the app from its auto-deploy folder on the hard-drive (this is the location you noted in step #1)

Faq ID

324

Product

ServletExec

Category

Web Application

Question

I'm moving my Legacy application over into a true Java Servlet Web application.
Is there anything I should know?

Answer

Yes.
First, read the chapter about Web Applications in your SE User Guide.
Then play around with the exampleWebApp that comes with SE (described in the guide).

You should also be aware of how easy it is create an empty webapp structure using the SE admin UI.
See the HINT at the bottom of SE FAQ #137.
You can then begin populating that empty app with the components of your application.

Each webapp has it's own private document root.
Your code can learn where (on the hard-drive) that is by using the techniques given in
SE Interest List posting #84990.

And one of the most common stumbling blocks for people who are new to webapps is the
notion of a context path and what that means to the browser.
Here's an example to help illustrate this:

You have a webapp whose context path is /myWebapp

You request http://myHostName/myWebapp/myPage.html

myPage.html emits a link that looks like this
<a href='/myOtherPage.html'>click here</a> (a page sitting right next to myPage.html)

When you click on the link, the browser requests http://myHostName/myPage.html (Note that the context path is now missing), and you get a 404 - not found response.

In the above example, myPage.html is a static page (not a JSP, or a servlet) and so it's links are hard-coded.
This is fine as long as the context path portion of the hard-coded link matches the context path of the webapp
to which the page belongs (or... from which the page was served).
But if it does not match, then you run into this problem.
There are a few solutions... you could change the context path of your webapp to be just a single forward slash "/".
Or you could edit myPage.html. Or you could rename it to myPage.jsp and use the following sort of code to programatically prepend the right context path:

That way your code would be portable to other webapps without having to make manual modification to account for context path differences. The same applies to links to images, CSS pages, javascript files, or any requests that JavaScript code makes, or anything like that.
If you have many such links then instead of prepending the context path to each and every URL another option would be to use the BASE element to standardize the location to which relative URLs are resolved by the browser. For example:

<head>
<base href='<%=request.getContextPath()%>'>
</head>

You could also just use:
<a href='myOtherPage.html'>click here</a>
But that won't likely work for links emitted by a servlet since the request URI to invoke a servlet typically involves the use of an alias... which does not map to an actual, physical place on the hard-drive.
For example:
You request http://hostname/myWebapp/servlet/MyServlet (a servlet inside your webapp) which returns HTML markup that tries to reference a CSS page (or basically just some physical file inside that very same web application).
The servlet will need to prepend the context path of the webapp to the link... it can't just use "my.css" as the link (even if my.css is sitting right in the root of your webapp).
This is because the browser knows that it just requested /myWebapp/servlet/MyServlet
If it then tries to resolve "my.css" (a relative URL) it will do so relative to where it thinks the page was served.
So it will try to get http://hostname/myWebapp/servlet/my.css which will cause SE to say "Failed to get Servlet... There is no servlet named my.css... ClassNotFoundException" or some such message.

The use of request.getContextPath() above, obviously requires that a request object be available. So that solution can only be used at request-time, by methods that have access to the request object. A more elegant approach would be for your application to learn its own context path at the time it initializes (before any request has arrived). Beginning with Servlet API Specification 2.5 (implemented by SE 6.0) this is possible via the ServletContext.getContextPath() method. If you know your app will only be used on Servlet 2.5 compliant Servlet/JSP Engines then you could use this technique at webapp init time and "cache" the result in the application scope.
Other code that needs it could then look it up from that scope.

Another option would be to use the URL tag provided in the JSTL since that tag takes care of prepending the proper context path automatically. Of course that option only works for JSP pages.

If your webapp code needs to know the physical path on the hard-drive to which it has been deployed then you could use this code:
String appRoot = application.getRealPath("/");
NOTE that for webapps deployed in .war file form, ServletExec will expand the contents of the .war file to a "working" folder, so appRoot in that case will be the absolute path to that "working" folder.

Manually deployed ones that have been defined in application.xml (called application.properties prior to SE 5.0)

auto-deployed .war files

auto-deployed open directory structure web apps

Faq ID

137

Product

ServletExec

Category

Web Application

Question

My browser fails to execute my Applet when the Applet resides inside a Web Application. What is wrong?

Answer

First, view the source of the HTML in the browser window to examine the reference to the applet.
Make certain that the link to the Applet that the browser is trying to interpret is correct.
Keep in mind, a leading forward slash is interpreted by the browser to be the Web Server's Document root
(not the web app's document root).
If there is no leading forward slash in the code attribute of the <applet> tag then the browser will attempt
to locate the .class or .jar file for the Applet relative to where it thinks the HTML was served.
If the HTML received by the browser was served from a Web Application then you may need to alter the reference accordingly.
If this is not the problem then check your browser's Java Console for error message output.
If the Java Console for your browser mentions:
java.lang.ClassFormatError
Then most likely you need to add some mime-mapping entries to you Web Application configuration.
In this case you would need to add the following mappings:

class -> application/java-vm
jar -> application/java-archive

This way ServleExec will understand how to serve .class or .jar content from the Web Application to the client.

HINT:
If you use the Main ServletExec admin UI to create a new, empty web application (pointing to an empty folder or a folder that does not yet exist),
then SE will actually create the basic folders for you (WEB-INF, lib, classes) and will also create a basic web.xml
file for you, which contains a few basic mime mappings. You could then use these basic mime mappings
as an example for adding the mappings mentioned earlier in this FAQ.

Web Server Support

Faq ID

277

Product

ServletExec

Category

Web Server Support

Question

Can Microsoft's URLScan tool (which hooks into IIS) prevent ServletExec from working properly?

Answer

Yes.
URLScan basically just scans the URL of all incoming requests, and parses the URL... looking for request elements that are NOT allowed (as defined in URLScan's initialization file). If URLScan sees an extension or a hack it doesn't like (like .exe or .. for a directory traversal hack) it stops the request cold. In other words, it does not allow the request to proceed through any remaining IIS filters (of which ServletExec is one). Therefore the request is never handed over to ServletExec.
So ServletExec never receives the request... URLScan has blocked it.
URLScan may also be configured to look for http verbs (GET, POST, HEAD, etc...) it doesn't like so you can stop things such as WebDAV (or whatever else you want URLScan to block). URLScan can also stop long requests to block buffer-overrun attacks.
If URLScan is configured properly, then ServletExec won't be effected at all, and will work just fine.
If you have URLScan hooked into your IIS, and you're having problems getting ServletExec to function properly behind IIS, then you may very well need to configure your URLScan differently.

Some common configuration changes that must be made to URLScan after SE has been installed with IIS include:

Telling URLScan to allow the .jsp extension

Telling URLScan to allow the /Scripts Virtual Directory to be used (or setting up a different VD for SE to use)

URLScan *may* be included with certain Microsoft updates such as the IIS lockdown tool.
Please see FAQ #186 for more information.
NOTE: We've had customers tell us that after configuring their URLScan's configuration file properly, SE and URLScan both worked fine with the same IIS installation. So we know that this is possible to do.

My web app's welcome file is not served unless I specify it in the request. What's wrong ?

Answer

This FAQ only applies to those using a version of ServletExec *prior* to version 5.0... and then only if using Apache as your webserver software.

If you have a web app whose context path is a single forward slash then a request such as:
http://<hostname>/
should cause Apache to pass the request over to ServletExec, and then SE should serve the welcome file. If you receive a 404-Not Found response in your browser instead, and yet the welcome file is served perfectly fine if you request:
http://<host-name>/<welcome-file-name>
then the problem is very likely that Apache is not passing requests for the root context over to ServletExec.
A solution to this problem was posted to the ServletExec Interest List by AndrewW@ViAir.com. His posting is message id #50583 and can be viewed:
http://www.newatlanta.com/c/products/servletexec/self_help/archiveSearch/detail?page=1&messageId=50583
To summarize here:
Use the apache "alias" command to redirect requests for the
root context to a different context.
The example httpd.conf given by Andrew looks like this:

(the above JARs may be found in the \common\lib and \common\endorsed subfolders of the JWSDP 1.0 installation)

Deploy the modified HelloWorld web app on ServletExec, and make sure that no errors occurred during the deployment by checking ServletExec.log for error messages (the JAXRPCEndpoint servlet is configured to load at init time)

Before building the client, be sure to modify the build.properties file so that the endpoint property points to the proper hostname and port number for ServletExec (instead of pointing to Tomcat).

Note that JWSDP 1.0 requires JDK 1.3.1 or greater so ServletExec
must be run with JDK 1.3.1 or greater.

XML

Faq ID

241

Product

ServletExec

Category

XML

Question

I'm using JDK 1.4 and trying to use newer XML classes than the ones that came with SE. It's not working, what's going on ?

Answer

JDK 1.4 comes with it's own XML parsing and transforming classes (i.e. those typically found
in xerces.jar and xalan.jar).
It appears that these classes reside in the rt.jar for JDK 1.4.
Furthermore, JDK 1.4 is rigged to *always* use it's built-in versions except under special
circumstances which this FAQ will attempt to describe.
(Note: this may also apply to newer versions of the JDK, use the EnvironmentCheck utility described below to find out).
That in itself is not a bad thing, unless you wish to use a newer version of these XML classes.
Please read info. about this here.

From this info. and our testing, we have found that the XML classes that come with SE will be ignored (we found this out in April of 2004)
and the XML classes that come with JDK 1.4 will be used instead... unless you use one of the following
workarounds:

You put the versions you want to be used (both interfaces and their implementations) in your webapp's lib folder.
This works because SE's own custom classloader will look there first, before it asks the
System classloader to find them.

You use the Endorsed Standards Override Mechanism as described at the above link.

You prepend the updated xalan.jar, xercesImpl.jar, and xml-apis.jar to the boot class path
as described at the link above.

Here is a JSP that ran fine in our SE 5.0 installation.
It uses the Xalan-Java's EnvironmentCheck utility described at the above link.
****

****
The browser output from the above JSP told us that our J2SDK 1.4.2_04 installation was using:

version.xerces2=Xerces-J 2.3.0
version.xalan2_2=Xalan Java 2.4.1

Even if we placed newer versions of xalan.jar, xercesImpl.jar, and xml-apis.jar in SE's lib folder or
on the Main SE classpath.
We found that we could only get the utility to state a newer version of these classes if we placed the newer versions at:
C:\j2sdk1.4.2_04\jre\lib\endorsed
In other words, we applied one of the workarounds given above and confirmed that it worked.

If you wish your code running inside SE to use a newer XML class, you should be aware of this caveat that's caused by the JDK, and utilize the above utility together with the listed workarounds to figure out what's going on in your case, and how best to fix it for your own environment.

Faq ID

202

Product

ServletExec

Category

XML

Question

Where did SE's XML/XSLT JARs come from and which ones does SE absolutely require ?

Answer

SE 5.0 final (released on 10.31.2003):
The following JARs:
jaxp-api.jar, xercesImpl.jar, xsltc.jar, xalan.jar, sax.jar, dom.jar
came from the JWSDP 1.3 dated 10/20/2003.

We know that the previous version of JWSDP (v 1.2) had Xerces 2.3.0 inside it, and that's what SE 5.0b1 used.

SE 4.2 final:
Like SE 5.0, it comes with several XML/XSLT JAR files.
But different from SE 5.0... some of these JARs were obtained from Sun's Java XML Pack,
while others were obtained from JWSDP the Java Web Services Developer Pack.
So these are just standard JARs from Sun.
For example, with SE 4.2, the Summer 02_01 Release of the Java XML Pack, and version 1.0 of the JWSDP were used.
These were the most current versions at the time SE 4.2 was released.
As newer versions (not hotfixes) of SE come out, newer versions of these JARs will be included (in favor of the older ones).
To learn more about the version of any particular JAR, you should read the
Meta-Inf\Manifest.mf file contained within the JAR, using a plain text editor.

For the most part, ServletExec only needs a few of these parsing JARs in order to function.
For example, xercesImpl.jar is the Xerces implementation of the interfaces defined in jaxp-api.jar (those 2 JARs go hand-in-hand).
ServletExec uses the classes in these 2 JARs (or newer, backward compatible versions) in order to parse web.xml files, and TLD files.

The other XML/XSLT JARs are not used unless you run code that needs them.
An example of such code would be if you were to run a Web Service or a Web Service Client inside SE.
Then classes found in JARs such as sax.jar, xalan.jar, etc... would be needed.

You should be able to upgrade any of these JARs so long as the newer versions are backward compatible.