JRun™ 4 for Windows®,
UNIX™, and Linux™

These release notes contain the following information about JRun 4:

• New features
• JRun documentation set
• JRun documentation changes and additions

JRun Known Issues is a separate document available at
http://www.macromedia.com/v1/Handlers/index.cfm?ID=22790&Method=Full.

JRun 4 provides the following new features:

• Dynamic deployment/update of J2EE modules (archive files or expanded directories)
• Deployment of Sun Reference Implementation and Jakarta Tomcat J2EE modules
• Dynamic servlet, helper class, and tag library compilation
• Stubless EJB development
• Dynamic creation of database tables for entity beans
• Customizable EJB container-managed persistence
• XDoclet integration for automatic generation of code and deployment descriptors
• Enterprise Deployment Wizard for EJBs
• PointBase database server
• JRun sample applications
• Web services features and tools
• Flash J2EE connectivity
• Improved JRun Server Tags (JST) functionality
  

• XML-based configuration
• JMX-based architecture
• Redesigned web-based management console
• Redesigned web server connector installer with connectors for all major web servers
• Load balancing and failover based on object clustering and web server connectors
• JRun 3.x migration features

J2EE 1.3 certification

J2EE 1.3 implementations

• Servlet 2.3
• JSP (JavaServer Pages) 1.2
• EJB (Enterprise JavaBeans) 2.0
• J2EE Connector Architecture 1.0
• JAAS (Java Authentication and Authorization Service) 1.0
• JDBC
• JMS (Java Message Service) 1.02b
• JTA (Java Transaction API) 1.0.1
• JavaMail 1.2 and JAF (JavaBeans Activation Framework) 1.0
• JAXP (Java API for XML Parsing) 1.1

Developer-oriented features

Dynamic deployment/update of J2EE modules

JRun provides dynamic deployment of web applications, EJBs, enterprise applications, and enterprise resource adapters from Java archive files or expanded directories. When you copy a J2EE module archive file or directory to a deploy directory (jrun_root/servers/jrun_server by default), the module is dynamically deployed. The deployment is dynamically updated when any module file is modified. For more information, see JRun Assembly and Deployment Guide at jrun_root/docs/dochome.htm.

Note: You cannot use the JRun Management Console (JMC) to undeploy a module that is in a deploy directory. To undeploy the module, you must remove the file from the directory manually.

You can deploy a J2EE module created for the Sun Reference Implementation (RI) server or Jakarta Tomcat without modification. You also can generate JRun-specific deployment descriptors for these modules by setting the persistXML attribute of the DeployerService to true in the jrun_root/servers/jrun_server/SERVER-INF/jrun.xml file; for more information, see Automatically generating deployment descriptors.

If you do not remove an RI-specific deployment descriptor from a module, JRun uses both he RI-specific and the JRun -specific descriptors, but values in the RI-specific descriptor override those in the JRun-specific descriptor.

You can configure JRun to dynamically recompile and reload servlets and JSPs, servlet helper classes, and JSP helper classes when a servlet or JSP is called. When the compile and reload features are enabled, JRun dynamically recompiles and reloads servlets and JSPs when they are called. JRun also dynamically recompiles and reloads classes in the WEB-INF/classes directory and tag library classes when they are called by a servlet or JSP. This feature is disabled by default. You can enable dynamic compiling and reloading by creating a WEB-INF/jrun-web.xml file containing the following text (jrun-web-app is the root element of the deployment descriptor):

<jrun-web-app>
<reload>true</reload>
<compile>true</compile>
</jrun-web-app>

The default-ear/default-war web application in the default JRun server, and any new server you create through the JMC, contains a jrun-web.xml file with the reload and compile properties set to true.

There is no need to generate EJB stubs to deploy EJBs in JRun. The server handles this for you dynamically.

When you deploy an entity bean and its required database tables do not yet exist, JRun generates them for you when you have configured the appropriate Java Database Connectivity (JDBC) data source in JRun.

JRun provides a JRun-specific EJB deployment descriptor, jrun-ejb-jar.xml, that lets you customize container-managed persistence for CMP beans. For more information, see JRun Programmer's Guide at jrun_root/docs/dochome.htm.

JRun provides integration with XDoclet, a popular open source tool that simplifies the development of EJBs, web applications, and JSP tag libraries by letting you maintain your component metadata using Javadoc tags in a single source file. JRun automates the process of generating and compiling code. For more information, see JRun Programmer's Guide.

JRun includes the Enterprise Deployment Wizard for developing, packaging, and deploying EJBs. Using its Swing-based graphical user interface, you can create any type of EJB, or edit the deployment descriptor of existing EJBs, package them into JAR files, and deploy them on JRun. In particular, the object-relational mapping capabilities of the Enterprise Deployment Wizard let you streamline the entity bean development process. The Enterprise Deployment Wizard runs as a stand-alone tool, or as a plug-in on top of the Borland JBuilder, Forte for Java, and Intellij IDEA Integrated Development Environments (IDEs).

To start the stand-alone version of the Enterprise Deployment Wizard, open a console window to the jrun_root/bin directory and enter the following command:

jrunwizard

To install the Enterprise Deployment Wizard for JBuilder or Forte for Java, open a console window to the jrun_root/lib directory and enter the following command:

java -jar jrunwizard-installer.jar

To configure the Enterprise Deployment Wizard for Intellij IDEA:

1. Create an XML file (with any filename) containing the following text in your IntelliJ_root/config/tools directory; replace jrun_root with the actual root directory of your JRun installation:
   
   <?xml version="1.0" encoding="UTF-8"?>
   <toolSet>
   <tool description="JRun Enterprise Deployment Wizard" disabled="false" name="jrunwizard" showInEditor="true" showInMainMenu="true" showInProject="true" showInSearchPopup="true" synchronizeAfterRun="true" useConsole="true">
   <exec>
   <option name="COMMAND" value="jrun_root\bin\jrunwizard.exe" />
   <option name="PARAMETERS" />
   <option name="WORKING_DIRECTORY" value="jrun_root/bin" />
   </exec>
   </tool>
   </toolSet>
   
   
2. Restart IntelliJ IDEA. A new menu item called JRun is added under the tools menu.

To use the Enterprise Deployment Wizard for a CMP bean:

• The JAR file containing the database driver must be in the jrun_root/servers/lib directory.
• You must have a data source defined in JRun.
• You must start both your database server and the JRun server that contains the data source.

JRun ships with an evaluation version of the PointBase Network Server. This is an all-Java database used with the JRun sample applications. This database server is also available for your development convenience. For more information, see the PointBase documentation in the jrun_root/pointbase/docs directory.

You can start the databases on the samples JRun server either automatically or manually, as follows:

• Automatically - The samples JRun server uses the PointBaseStarter service, a custom JRun service, to automatically start databases when the samples server starts. The PointBaseStarter service is defined in the jrun.xml file. This service is itself a sample application and you can view the source code in the jrun_root/servers/samples/pointbase-service directory.
• Manually - The jrun_root/pointbase directory has batch files (Windows) and shell scripts (UNIX) for starting each of the databases individually. Use these files to start the databases when the samples server is not running or if the PointBaseStarter service doesn't work on your system.

To use the PointBase console, perform the following steps:

1. Navigate to the jrun_root/pointbase directory.
2. Start the database using the appropriate batch file or shell script.
3. Start the console using the console.bat batch file or the console shell script.
4. Connect to the database using the appropriate URL; the sample databases use:

   jdbc:pointbase:server://localhost:9192/sample
   jdbc:pointbase:server://localhost:9292/compass
   jdbc:pointbase:server://localhost:9392/smarticket
   jdbc:pointbase:server://localhost:9692/worldmusic

JRun 4 includes the following sample applications on the samples server at http://localhost:8200 (by default):

• Compass Travel is a sample online vacation reservation system that demonstrates J2EE programming techniques. Getting Started with JRun, at jrun_root/docs/dochome.htm, contains a companion tutorial.
• TravelNet is a travel agent application reselling trips from Compass Travel. This application provides a simple, real life example of a web services application. Getting Started with JRun, available at jrun_root/docs/dochome.htm, contains a companion tutorial.
• Flash Remoting Samples showcase Macromedia Flash Remoting connectivity for J2EE.
• Smarticket is a Sun reference application that demonstrates how a J2ME client application accesses business logic in a J2EE server. JRun includes the standard Smarticket application and a version with a Macromedia Flash user interface implemented with Flash Remoting technology.
• World Music is an online musical CD store that demonstrate J2EE design patterns.
• JRun Programming Techniques contains running examples of code shown in JRun Programmer's Guide.
• JRun Web Services Samples demonstrates web service programming techniques. The sample server must be started before you can use the samples.

The samples server includes a custom service that starts PointBase databases automatically. Source code for this custom service is in the jrun_root/servers/samples/pointbase-service directory.

JRun lets you publish and consume web services. Web services provide platform- and location-independent computing using XML and standard Internet protocols such as HTTP. By allowing previously incompatible applications to interoperate over the web, regardless of language, platform, or operating system, web services create new business opportunities and help companies adapt to changing business relationships. For example, a Microsoft .NET component can communicate with a J2EE component, such as an Enterprise JavaBean (EJB).

Using JRun, you can use existing Java code as a web service, or write new code specifically to publish as a web service. You also can create object- and tag-based clients that can invoke methods on remote web services, even when those services reside on non-Java platforms.
The JRun web services implementation is built on Apache Axis, the third generation of the Apache Software Foundation’s Simple Object Access Protocol (SOAP) engine. For more information, see JRun Programmer's Guide at jrun_root/docs/dochome.htm.

JRun includes the new Flash Remoting technology, giving you the ability to use high impact Flash user interfaces with your J2EE applications .Flash movies can connect in a simple, fast, and secure manner to EJBs, Java classes, and JMX MBeans deployed in JRun.

Note: Flash Remoting requires the Flash MX player. Flash 5 or earlier versions of the player are not supported.

JRun provides Flash J2EE samples. After installing Flash MX, start the Samples server and access the Flash J2EE samples at http://localhost:8200 (by default).

For more information, see “Building Flash Services” in JRun Programmer’s Guide available from the documentation home page at jrun_root/docs/dochome.htm.

JST technology has been updated to support JSP 1.2 and recursion. JST lets you to write custom JSP tags using JSP syntax rather than the the custom tag handler API. Recursion allows a JST to call itself. A future release of JRun 4 will provide a utility for packaging JSTs into a tag library that can be used on any J2EE-compliant application server.

JRun uses XML-based server configuration except for JNDI, which uses the J2EE standard jndi.properties file. Server configuration files are located in a JRun server's SERVER-INF directory. JRun uses XML-based deployment descriptors for all J2EE modules. Document Type Declarations (DTDs) for all of the XML-based files that JRun uses are in the jrun_root/lib/jrun.jar file. JRun 4 includes Javadoc-like documentation generated from the J2EE module DTDs at jrun_root/docs/dochome.htm.

JRun is built on a Java Management Extensions (JMX) service-based architecture and uses JMX to provide flexible and dynamic management and administration. JMX is an emerging Java standard for management and customization.

JRun features (for example, EJB container, web container, logging) are implemented as JMX services (called MBeans) plugged into the JRun kernel. These services can be managed by the JMX-enabled JRun Management Console (JMC) or other JMX-enabled management tools.

Because services are independent of each other and can be restarted individually, JRun’s service-based architecture ensures high application availability. It also provides a highly customizable and easily extensible platform. Unneeded services can be unplugged to avoid the overhead of unused functionality. Administrators, advanced developers, and OEMs can also create their own custom services (MBeans) and plug them into the JRun kernel. All JRun services can take advantage of the clustering capabilities built into the JRun kernel.

The JRun Administrator's Guide and the JRun SDK Guide describe how to extend JRun with your own services. In addition, the samples server's jrun.xml file and pointbase-service directory contain sample settings and code for a custom service. For more information about JMX, see the Sun JMX white paper at http://java.sun.com.

The JMX-enabled JRun Management Console (JMC) provides an easy-to-use graphical user interface for managing local and remote JRun servers.
Using the JMC, you create servers, define clusters, manage applications, and implement JAAS-based security.

The new JRun Web Server Configuration tool prefills information and provides a much simpler user interface than previous web server connector installers. Using the Web Server Configuration tool, you can connect one or more web servers to each JRun server. The Web Server Configuration tool, a stand-alone tool, does not require JRun on the web server host. For more information, see Installing JRun at jrun_root/docs/dochome.htm.

JRun provides enterprise-class server clustering for maximum reliability and scalability. Clustering is built into both the web server connectors and the JRun kernel:

• At the web server connector level, clustering enables load balancing and automatic failover between the web server and the web containers. In-memory session replication ensures that state information is preserved if the web server fails over to another web container in the cluster.
  
  
• At the kernel level, clustering enables load balancing and automatic failover for clusterable server objects, such as EJBs, JNDI trees, or any clusterable custom service. The object state (for example, the state of a stateful EJB) is automatically replicated in an optimized manner to provide the highest level of reliability while maintaining performance. JRun servers use the Jini technology to dynamically locate their peers in the cluster, eliminating the risk inherent to a single point of failure.

For more information, see JRun Administrator's Guide available from the documentation home page at jrun_root/docs/dochome.htm.

Note: In addition to the new clustering features, you can use Macromedia ClusterCATS for software-based web server clustering. For more information about ClusterCATS, see http://www.macromedia.com/go/clustercats.

JRun provides a tool for migrating JRun 3.x servers and configuration settings. You can also deploy existing JRun 3.x J2EE modules. For more information, see Installing JRun at jrun_root/docs/dochome.htm.

JRun 4 passed the Sun J2EE certification test suite (CTS) using the following configuration:

• Red Hat Linux 7.1
• JDK 1.3.1_02

JRun fully supports the Servlet 2.3 specification, which includes the following important new features:

• Application events - useful for application initialization code and can replace preloaded servlets in some cases.
• Filters - allow pre- and post-processing of servlet requests.

For more information, see the following resources:

• Java Servlet 2.3 specification and The Essentials of Filters at http://java.sun.com
• JRun Programmer's Guide available from the documentation home page at jrun_root/docs/dochome.htm

JRun fully supports the JavaServer Pages (JSP) 1.2 specification, which includes several additions to the API, including:

• Two new tag types, IterationTag and TryCatchFinallyTag
• An XML syntax for JSP pages (JSPX), which makes it easier to automate the authoring of JSP pages
• A number of enhancements to Tag Library Descriptors (TLD) that improve portability, and better support authoring tools

For more information, see the following resources:

• Java Servlet 2.3 specification at http://java.sun.com
• JRun Programmer's Guide available from the documentation home page at jrun_root/docs/dochome.htm

The JRun EJB container has been re-architected to provide superior support for the new EJB 2.0 features including the following:

• Message-driven beans; integration with the Java Message Service (JMS)
• Improved container-managed persistence and support for container-managed relationships
• Local interfaces and local home interfaces for session beans and entity beans that allow lightweight access from enterprise beans that are local clients
• Enterprise JavaBeans Query Language, EJB QL, which allows navigation across a network of entity beans defined by container-managed relationships
• Select methods for internal use by entity beans with container-managed persistence. Select methods allow the selection of related beans and values through EJB QL queries
• Support for Home interface methods to implement business logic independent of a specific entity bean instance
• Run-as security identity functionality, which lets you specify the principal to be used as the run-as identity of an
  enterprise bean in terms of its security role
• Interoperability protocol based on CORBA/IIOP that allows remote invocations on session and entity beans from J2EE modules deployed in different vendors' products

For more information, see the following resources:

• Enterprise JavaBeans 2.0 specification at http://java.sun.com
• JRun Programmer's Guide available from the documentation home page at jrun_root/docs/dochome.htm
• Professional EJB by multiple authors, published by Wrox Press Inc.
• Enterprise JavaBeans by Richard Monson-Haefel, published by O'Reilly & Associates, Inc.
• Mastering EJB by Ed Roman, et.al., published by John Wiley & Sons.

The J2EE Connector Architecture supports integration of J2EE servers with enterprise information systems such as ERP systems, mainframe transaction processing systems, and legacy database systems; it defines a standard set of system-level contracts between a J2EE server and a resource adapter. JRun allows you to deploy resource adapters specific to enterprise information systems.

For more information, see the following resources:

• J2EE Connector Architecture 1.0 specification at http://java.sun.com
• JRun Administrator's Guide and JRun Assembly and Deployment Guide available at jrun_root/docs/dochome.htm

The Java Authentication and Authorization Service (JAAS) enables services to authenticate and enforce access controls upon users. For more information, see the following resources:

• Java Authentication and Authorization Service (JAAS) Reference Guide at http://java.sun.com
• JRun Administrator's Guide at jrun_root/docs/dochome.htm

The JDBC API provides programmatic access to relational databases. JRun supports both JDBC 2.2I and JDBC 3.0 database drivers. To take advantage of a driver's 3.0-specific features, the data source's native-results property must be set to true in the jrun-resources.xml. This is the default setting; if a data source has native-results set to false, you can change it to true in the jrun-resources.xml file or select the Native Results data source setting in the JMC.

Note: The Oracle Thin driver does not directly support scrollable or updateable ResultSets. You must set the native-results property to false to use scrollable or updateable ResultSets with this driver.

For more information, see the following resources:

• JDBC specifications at http://java.sun.com
• JRun Administrator's Guide at jrun_root/docs/dochome.htm

JRun includes a durable and transactable Java Message Service (JMS) 1.02b compliant provider that supports both point-to-point and publish/subscribe synchronous and asynchronous messaging. For customers requiring integration with a third-party JMS provider, JRun also provides support for Sonic Software Sonic MQ.

For more information, see the the following resources:

• Java Message Service 1.02b specification at http://java.sun.com
• JRun Administrator's Guide at jrun_root/docs/dochome.htm

The Java Transaction API (JTA) lets you demarcate transactions independent of the transaction manager implementation. For more information, see the Java Transaction API 1.0.1 specification at http://java.sun.com.

The JavaMail API, together with a JavaMail service provider, allow an application to send Internet mail. The JavaMail API makes use of the JavaBeans Activation Framework (JAF) API, so it must be included as well. For more information, see the JavaMail API 1.2 specification at http://java.sun.com.

The Java API for XML Processing (JAXP) provides support for the industry standard SAX and DOM APIs for parsing XML documents, as well as support for XSLT transformation engines. For more information, see the Java API for XML Processing 1.1 specification at http://java.sun.com.

JRun 4 includes the following documents:

• JRun Release Notes (this document)
• JRun core documentation set at jrun_root/docs/dochome.htm
• JRun Known Issues at http://www.macromedia.com/v1/Handlers/index.cfm?ID=22790&Method=Full
  

This section includes documentation corrections and additions related to the following topics:

• Working with web services
• Working with clusters
• Using J2EE and JRun Document Type Definitions
• Configuring web applications
• Configuring EJBs
• Configuring resource adapters
• Generating deployment descriptors
• Manually creating deployment descriptors outside archive files
• Redeploying J2EE modules
• Administration
• JRun licensing
• Using full-text search in JRun 4 online documentation

For additional information, see the following resources:

• JRun product page:
  http://www.macromedia.com/jrun/
• JRun product support page:
  http://www.macromedia.com/support/jrun/
• JRun documentation page
  http://www.macromedia.com/support/jrun/documentation.html

In addition to using the JMC and the command line, JRun 4 lets you start servers using the JRun Launcher. The JRun Launcher, which is configured in the servers.xml file in the jrun_root/lib directory, always starts JRun in the background. This lets you close the Launcher without stopping JRun servers. To start a JRun server in the background from the command line (on Windows or UNIX), use the nohup option, which requires the following syntax, from the jrun_root/bin directory:

jrun -nohup start jrun_server

In JRun 3.x, you used the nohup option on UNIX only with the following syntax, from the jrun_root/bin directory:

jrun -nohup jrun_server

For more information about starting and stopping servers, see Installing JRun.

When passing a password-protected WSDL URL (rather than a file) to the WSDL2Java tool, use the following WSDL2Java commandline switches; you cannot include the username and password in the URL itself:

-U or --user username

-P or --password password

JRun Programmer's Guide and the JRun Web Services Samples application on the samples server do not describe how to set a web service username and password when using a proxy client. If the proxy sample included in the web service samples required a username and password, you would instantiate the stubFactory and stub in the client JSP like this:

proxy.LoanServiceLocator stubFactory = new proxy.LoanServiceLocator();
proxy.AxisSampleLoanCalcServiceSoapBindingStub stub = (proxy.AxisSampleLoanCalcServiceSoapBindingStub) stubFactory.getAxisSampleLoanCalcService();

And then you would set the username and password like this:

stub.setUsername("AxisUser");
stub.setPassword("AxisPassword");

JRun Programmer's Guide contains information about the Web Services Tag Library invoke tag's resultType and resultTypeNamespace attributes, but does not include the following information.

• resultType is required unless the target web service returns no data. If you specify an incorrect resultType and Axis knows the correct type, the tag functions correctly.
  
  
• ResultTypeNamespace is only required when a resultType is not an Axis built-in data type in the default xsd namespace. This is the case for complex (user-defined) data types.

Also in JRun Programmer's Guide, there is one place under "Using a JSP tag-based dynamic client" where "resultType" is written as "resulttype"; this is incorrect. The web service referenced in the same section is no longer available.

When a web service backend is an EJB, the implementation field on the web services details page is populated with the bean's JNDI name.

The JWS web services in a web application only function correctly when there is a valid server-config.wsdd file in the web application's WEB-INF directory. The default-ear/default-war web application in the default server and any new server you create with the JMC, contains a server-config.wsdd file that you can copy to your web application's WEB-INF directory.

The Axis web services engine does not include static methods when it generates WSDL documents. As a result, static methods are not included in proxies you generate for Axis-based web services.

You cannot generate a proxy from a Microsoft .NET web service when the return type is DataSet.

Working with clusters

Known limitations

• When using unicast peers, the granularity of peers is based on the hostname or IP address, which causes all servers on a particular host or IP address to get added to a cluster whether you intend to add them or not.
  
  
• There is no failover for JMS in a cluster. Message-driven beans are clustered but share the same JMS backend. Sonic Software SonicMQ is recommended for fully-clustered JMS.
  
  

• If you install a web server connector for a cluster of JRun servers with a local web server on the localhost machine, you must update the bootstrap server in the jrun.ini file to point to the correct IP address of the JRun server (instead of the 127.0.0.1 localhost IP address). If there is a jrunserver.store file, you will also need to update the servers in this file manually to use the machine IP for each JRun server). The jrun.ini and jrunserver.store files for each connector installation are in a numbered subdirectory of jrun_root/lib/wsconfig, such as jrun_root/lib/wsconfig/1.

If a jrunserver.store file exists in the jrun_root/lib/wsconfig/1 directory (numbered directory name is different for each installation) with 127.0.0.1:proxyport entries for all servers, you must manually update those entries.

• For each server in a cluster, the jrun_root/lib/security.properties file (or the jrun_root/servers/jrun_server/SERVER-INF/security.properties file) must specify either the submask or hostname/IP address of each server in the cluster. For more information about the security.properties file, see Configuring JNDI security.
  
  
• When you use the JMC to create a cluster, a default cluster deploy directory (jrun_root/servers/jrun_server/SERVER-INF/cluster) is assigned to each server in the cluster. When you use the JMC to deploy a module to a cluster, JRun deploys the module to the first server listed under the cluster's domain-name element in the jrun_root/lib/jmc.xml file.
  

• When manually deploying modules to a cluster, you should copy modules to the cluster deploy directory of a single server, or master server, to simplify administration.
  
  
• When you use a cluster deploy directory on a master server in a cluster, you should disable the local hot deploy feature (set the jrun.xml DeployerService's hotDeploy attribute to false) on the other servers in the cluster. If you do not disable hot deploy on the other servers in the cluster, modules are undeployed when the master server goes down. With hot deploy enabled on the master server, module changes result in redeployment to the other servers in the cluster; this is fine during development, but as stated in JRun Administrator's Guide, hot deploy should not be used in a production environment.
  
  
• Before removing a module or changing its name in the cluster deploy directory of a master server while the server is down, you should bring down all the servers in the cluster. You should then restart the master server and restart the other servers.
  
  
• When using JMS and a cluster deploy directory, the master JMS server should be the server that contains the cluster deploy directory.
  
  
• When using JMS in a clustered environment, you must set the JMS transport type to RMI or TCPIP. In the jrun_root/servers/jrun_server/SERVER-INF/jrun-resources.xml files of the servers in the cluster, set the value of the transport element to RMI or TCPIP.

• When using JMS in a cluster, you should always start the JMS master server first and wait for it to complete startup before starting other servers in the cluster.
  
  
• You should always start the servers in a cluster separately.

• Session replication only happens at the end of a request when setAttribute or removeAttribute is called on the current session. The only time you must be aware of this feature is when making a change to an existing attribute. For example, the following change would not be replicated:
  
  Collection c = (Collection)session.getAttribute("my.collection");
  c.add("new collection value");

  You must also call:
  
  session.setAttribute("my.collection", c);

  or make sure setAttribute is called on some other object. It doesn't have to be called on the object that you changed.

• In JRun Administrator's Guide, there is an example showing session replication in which the jrun-web.xml file buddy-name element is incorrectly referred to as buddy-list. Also, you do not specify multiple session replication buddies in a single buddy-name element; you use an individual buddy-name element for each buddy or an asterisk (*) to indicate all servers in a cluster are buddies. Do not use an asterisk in production environments.
  
  
• Session failover requires that a server and its session replication buddies form a group. If serverA has buddies serverB and serverC, then serverB must have buddies serverA and serverC. ServerC must have buddies serverA and serverB.
  
  
• Session failover is not available when using the JRun web server.

The final versions of the Document Type Definitions (DTDs) for J2EE module deployment descriptor and JRun server configuration files are in the meta-inf directory of the jrun_root/lib/jrun.jar file. Some of these DTDs were changed after the descriptor documentation in the jrun_root/docs/descriptordocs directory was completed. Those changes are noted in this Release Notes document. You can extract the DTD files and use them directly for informational purposes and for creating and editing XML instances in a validating XML editor.

JRun Assembly and Deployment Guide states that the jrun-web.xml reload and compile elements both have default values of true. Both elements actually have default value of false. For the most accurate deployment descriptor information, see the descriptor documentation at jrun_root/docs/descriptordocs/index.html.

Note: The reload and compile values are set to true in the jrun-web.xml file included in the default server's default-ear/default-war web application and the default-ear/default-war web application of any new server you create using the JMC.

The cacheTags init param to the JSPServlet lets you disable JSP custom tag caching. The default value of cacheTags is true, and it is included in the default server's default-web.xml file.

You can disable the caching of getRealPath results by setting the JRunProxyService's cacheRealPath attribute to false in the jrun_root/servers/jrun_server/SERVER-INF/jrun.xml file. The default value is true. If cachRealPath is set to false, the real path is kept only for the duration of the request.

JRun checks servlet path maps in the following order:

1. Check for an exact match.
2. If not found, check for a path mapping (for example, /servlet/*).
3. If not found, check for an extension mapping (for example, *.jsp).
4. If not found, check for the default mapping (for example, /).

JRun does not hard code the character encoding used for decoding a URI to UTF-8 format. You can override the encoding used by adding the following entry the jrun-web.xml of your web application:

<uri-character-encoding>UTF-8</uri-character-encoding>

The default encoding, if the uri-character-encoding element is not provided, is UTF-8. To use the system default encoder, you can also supply an empty uri-character-encoding for the system default encoder.

Note that the UTF-8 character encoding does not support the character being decoded, but you can update jrun-web.xml to use the default system encoder:

<uri-character-encoding></uri-character-encoding>

Or use a latin-1 encoding:

<uri-character-encoding>ISO-8859-1</uri-character-encoding>

Use the original (undecoded) URI for the request URI, not the decoded URI. The Servlet specification is very explicit about this.

The elements of the jrun-ejb-jar.xml file were changed after JRun Assembly and Deployment Guide was completed. For the most up-to-date information, see the deployment descriptor documentation at jrun_root/docs/descriptordocs/index.html. Notable changes include:

• The ejb-container section, which lets you set bean persistence properties is directly under the jrun-ejb-jar element, not under the entity and session elements.
  
• The cache-size element was added under the entity and session elements. It lets you set cache sizes for entity beans and stateful session beans. The file-cache-size element no longer exists and its functionality is now under the cache-size element.
  
• The following text from JRun Programmer's Guide :
  
  "To start the Enterprise Deployment Wizard, run jrun_root/bin/jrunwizard.bat (Windows) or jrun_root/bin/jrunwizard (UNIX). "
  
  Should be:
  
  "To start the Enterprise Deployment Wizard, run jrun_root/bin/jrunwizard.
  

The JRun Assembly and Deployment Guide states that in order to deploy a resource adapter without a jrun-ra.xml file, the ra.xml file must contain a display-name value because JRun uses that name as the JNDI name. This is no longer the case. If no display-name value is provided in the ra.xml file, JRun uses the classname of the ManagedConnectionFactoryClass as the JNDI name.

JRun can generate JRun-specific and standard deployment descriptors for J2EE modules on a JRun server. This feature is available for modules in archive files or expanded directories. Complete the following steps to generate deployment descriptors:

1. In the jrun_root/servers/jrun_server/SERVER-INF/jrun.xml of a JRun server, set the DeployerService persistXML attribute to true.
   Note: You should not enable persistXML indefinitely because it increases system overhead.
   
2. Restart the JRun server to redeploy the modules and generate deployment descriptors.

For modules in expanded directories, JRun backs up and overwrites existing descriptors and creates jrun-specific descriptors if they do not already exist. For modules in archive files, JRun generates jrun-specific and standard deployment descriptors in the directory containing the archive file. JRun uses the following naming conventions for the descriptors it generates:

• web applications:
  web_app.web.jrun.xml (corresponds to jrun-web.xml)
  web_app.web.xml (corresponds to web.xml)
  
  
• EJBs:
  ejb_module.ejb.jrun.xml (corresponds to jrun-ejb-jar.xml)
  ejb_module.ejb.xml (corresponds to ejb-jar.xml)
  
  
• resource adapters:
  adapter_module.rar.jrun.xml (corresponds to jrun-ra.xml)
  adapter_module.rar.xml (corresponds to ra.xml)

For modules in archive files, the descriptors generated outside the archive files take precedence over those inside the archive files, except for Sun RI-specific descriptors. After generating descriptors, you can remove RI-specific descriptors from the archive files to ensure that they are not used. The initial values of generated descriptors match those of the corresponding descriptors inside the archive files, so you can modify the generated files to quickly change configuration settings. For EAR files, this feature provides functionality equivalent to the alt-dd element in the application.xml file.

You can use deployment descriptors outside of module archive files even if you create them manually rather than automatically as described above. If you use the descriptor naming conventions described above, JRun uses the external descriptors rather than corresponding descriptors inside the archive files. To make a quick change to a configuration setting, you can extract a descriptor from an archive file, rename it appropriately, and then edit it.

To redeploy a module on a running JRun server with hot deploy enabled, save a deployment descriptor file in an expanded directory or overwrite a module archive file. If you delete the module and then replace it with a new version, the server redeploys without flushing any of the class files that were present in the old version. In order to flush the old class files, modify (touch) the new archived module to change the timestamp.

You can control JRun JNDI access at the global or server level. You can limit JNDI access to specific hosts and/or subnet masks, depending on the level of security and flexibility you require. The JRun installation includes a jrun_root/ lib/security.properties file that contains two properties, jrun.subnet.restriction and jrun.trusted.hosts, which control the level of access to JNDI resources for all servers in a JRun installation based on the specified subnet mask and/or host(s), respectively. You can override this global security.properties file for a specific server by creating a security.properties file in that server's jrun_root/servers/jrun_server/SERVER-INF directory. JRun never combines property values from both a global and server-specific security.properties file; when a server-specific file exists, JRun always reads properties from that file rather than the global file.

By default, the jrun.subnet.restriction property is set to the value 255.255.255.0, which limits JNDI access to the 255.255.255.0 subnet. Because no default value is set for the jrun.trusted.hosts property, it is ignored. You can use jrun.trusted.hosts on its own or in combination with jrun.subnet.restriction to allow access JNDI access to a comma-separated list of IP addresses (recommended) or host names. If you are not concerned about security in a development environment, you can allow access from all subnets and hosts by specifying an asterisk (*) as the value of jrun.subnet.restriction or jrun.trusted.hosts. You should not use an asterisk in a production environment.

Important:

• If a machine listed in a jrun.trusted.hosts entry is not available when the JRun server starts and the machine becomes available while the server is running, it is not picked up
  as a trusted host. If you specify an IP address rather than a machine name, the machine is picked up as trusted host. Macromedia suggests that you use IP addresses instead of host names when specifying trusted hosts. This is very important when setting up a cluster where one or more of the machines might not be running when other servers in the cluster are started.
• When working with clusters, the security.properties file must specify either the submask or IP address/host name of each server in the cluster.
• If there is no security.properties file in either the jrun_root/lib directory or the jrun_root/servers/jrun_server/SERVER-INF directory, the JRun server will not start. When an invalid subnet mask is specified, JRun uses the default value of 255.255.255.0. A Security Alert message is printed to the JRun server event log every time a JNDI access request is rejected.
• Any change to the jrun_root//lib/security.properties file is not reflected in the servers that use that file until you restart the servers.
  

The default Java Virtual Machine (JVM) settings are in the jrun_root/bin/jvm.config file. You can edit this file directly or use the JMC to set the following properties. You can also set up custom JVM configuration files for specific JRun servers in a JRun installation; for more information, see Using multiple JVM configurations.

java.home - Specify the location of the JVM.

java.args - Specify arguments to the JVM.

java.class.path - Add individual JAR files and directories from which the JVM should pick up classes, JAR files, and ZIP files to the classpath. Use commas to separate entries.

java.library.path - Specify the location of shared libraries. Use commas to separate entries.

Using multiple JVM configurations

You can use more than one set of JVM configuration properties for the JRun servers in a JRun installation. This feature is documented in Installing JRun, and is available from the command line and when running JRun as a Windows service. Complete these steps to set up and and use a custom JVM configuration from the command line:

1. Copy the jrun_root/bin/jvm.config file to a new filename.
2. Modify the new .config file to meet your needs.
3. As a command prompt or shell, start a JRun server using the following command:
   
   jrun -config custom_jvm.config -start jrun_server
   
   where custom_jvm.config is the name of your JVM configuration file, and jrun_server is the name of your JRun server. You can specify one or more server names separated by commas.

To use a custom JVM configuration when starting JRun as a Windows service, install the service using the following command:

jrunsvc -install jrun_server service-name service-display service-description -config custom_jvm.config

The custom configuration file can be in the jrun_root/bin directory or you can specify a complete path to the file.

Changes to the JRun server configuration descriptors include:

• In the jrun-resources.xml file, there is now a url-resource section.
  
  
• In the jrun-resources.xml file, the description for the native-results element should be:
  
  "The native-results element tells JRun whether to pass through your JDBC driver's native ResultSets (true) or wrap with a JRun-specific ResultSet implementation (false). You should use a value of true unless your JDBC driver's ResultSets do not support JDBC 2.0 extensions."
  To take advantage of a JDBC driver's 3.0-specific features, the data source's native-results property must be set to true. This is the default setting; if a data source has native-results set to false, you can change it to true in the jrun-resources.xml file or select the Native Results data source setting in the JMC.
  
  
• In the jrun-users.xml file, the role-name element replaces rolename and the user-name element replaces username.
  
  
• In the jrun-jms.xml file, there are now max-message-queue-size-mb and max-message-queue-size-test-fail-silently elements. These new attributes control the behavior of a new limiting mechanism which can prevent overwhelming of the JMS subsystem with incoming messages and pushing the JRun server into an out-of-memory condition. For more information on configuring JMS in JRun, refer to tech notes in the JRun Support Center.
  
  Also in the jrun-users.xml file, the default value of the transact element is now false.

For the most accurate descriptor information, see the descriptor documentation at jrun_root/docs/descriptordocs/index.html.

• When you use the JMC to add a JDBC data source, the JDBC password is encrypted by default. To turn encryption off, you must set the value of the data source's encrypted element to false and enter the clear text password as the value of the data source's password element in the jrun_root/servers/jrun_server/SERVER-INF/jrun-resources.xml file.
  
  
• The following table lists the drivers and URLs that the JRun JDBC driver classes use. These drivers are installed in the jrun_root/lib/macromedia_drivers.jar file.
  
  

  Driver	Former driver class	New driver class	New data source class	URL
  DB2	com.merant.datadirect. jdbc.db2.DB2Driver	macromedia.jdbc. db2.DB2Driver	macromedia.jdbcx. db2.DB2DataSource	jdbc:macromedia: db2://server_name:50000; DatabaseName=your_database; CollectionId=your_id; PackageName=your_packname
  Informix	com.merant.datadirect. jdbc.informix.InformixDriver	macromedia.jdbc. informix.InformixDriver	macromedia.jdbcx. informix.InformixDataSource	jdbc:macromedia: informix://server_name:2003; InformixServer=your_server
  Oracle	com.merant.datadirect. jdbc.oracle.OracleDriver	macromedia.jdbc. oracle.OracleDriver	macromedia.jdbcx. oracle.OracleDataSource	jdbc:macromedia: oracle://server_name:1521
  SQL Server	com.merant.datadirect. jdbc.sqlserver.SQLServerDriver	macromedia.jdbc. sqlserver.SQLServerDriver	macromedia.jdbcx. sqlserver.SQLServerDataSource	jdbc:macromedia: sqlserver://server_name:1433
  Sybase	com.merant.datadirect. jdbc.sybase.SybaseDriver	macromedia.jdbc. sybase.SybaseDriver	macromedia.jdbcx .sybase.SybaseDataSource	jdbc:macromedia: sybase://server_name:5000
  mySQL	n/a	org.gjt.mm.mysql.Driver	org.gjt.mm.mysql.jdbc2. optional.MysqlDataSource	jdbc:mysql: //server_name:3306/your_database

  
  Notes:
  The UtilDataConversions.class file referenced in the DataDirect Connect JDBC User's Guide and Reference is in the macromedia.util.UtilDataConversions package in the jrun_root/lib/macromedia_drivers.jar file.
  
  JRun does not include the following JDBC tools documented in the DataDirect Connect JDBC User's Guide:
  JDBCTest tool
  Spy JDBC driver

• The JRun Developer Version and the OEM Single User Edition license are limited to localhost plus only one other machine for both JNDI and web access. The one other machine is determined dynamically based upon the first hit to the web server or JNDI that isn't coming from the localhost.
  
• You can use the JMC to upgrade from a limited version of JRun to the full version by completing the following steps:
  1. Start the admin server and open the JMC.
  2. In the left pane of the JMC, select admin.
  3. In the right pane of the JMC, select Settings.
  4. Under Settings, select Version to display the JRun Version Information page.
  5. In the Update Product Edition - Serial Number field, enter your JRun serial number.
  6. Click Apply.
     
     

  You can also check for product updates and register your copy of JRun from the JRun Version Information page.

JRun 4 online documentation features full-text search capabilities in both HTML and PDF versions.

• The HTML documentation uses an applet to control full-text search. Because this facility uses an applet, support may be limited, depending on your browser, JRE version, and plug-in version.
• The PDF documentation uses built-in Acrobat functionality to control full-text search. Acrobat search is based on Verity technology and is enabled only when the PDF files are opened from the file system. It does not work when when displaying PDF files within a browser.

For complete information on using full-text search in JRun 4 documentation, refer to TechNote 22812.