Appendix B       Runtime Considerations


This appendix convers the following topics:

• Runtime Environments

• The Classloader Hierarchy

• Dynamic Reloading

Runtime Environments

---

Whether you register a component as a standalone module or as an application, registering affects both the file system and the registry. Figure B-1 shows the standalone module runtime environment. Figure B-2 shows the application runtime environment.

Standard Module Runtime Environment

The figure below illustrates the environment for module-based deployment. Note that for file system entries, modules are extracted as follows:

install_dir/ias/APPS/modules/module_name/extracted_class

Registry entries are added under this key:

SOFTWARE\iPlanet\Application Server\6.5\J2EE-Module\module_name

---

Tip	All standalone modules are extracted under the same directory, and all modules are extracted to the same LDAP location, therefore it is important that no two modules have the same name.

---

Figure B-1    Standalone Module runtime environment

Application Runtime Environment

The figure below illustrates the environment for application-based deployment. Note that for file system entries, applications are extracted as follows:

install_dir/ias/APPS/app_name/module_name/extracted_class

For Registry entries, modules within the application are added under this key:

SOFTWARE\iPlanet\Application Server\6.5\J2EE-Module\module_name

Figure B-2    Application runtime environment

The Classloader Hierarchy

---

In a Java Virtual Machine (JVM), the class loaders dynamically load a specific java class file needed for resolving a dependency. For example, when an instance of java.util.Enumeration needs to be created, one of the classloaders loads the relevant class into the environment. Class loaders in the iPlanet Application Server runtime follow a rigid hierarchy that is illustrated in Figure B-3.

Figure B-3    Classloader runtime hierarchy

A delegation design is used to load classes and resources at runtime. In this delegation design, each instance of a class loader has an associated parent class loader, which could be either a system class loader or another custom classloader.

When called upon to to find a class or resource, a class loader instance will delegate the search for the class or resource to its parent class loader before attempting to find the class or resources itself. If the parent classloader can't load a class, a method, called findClass (), is called on the custom class loader.

In effect, the custom class loader is responsible for loading only the classes not available to the parent. These would presumably be classes that come from a new type of class repository, i.e from the specified file system or from the network. Each class loader looks at a different repository for classes. The classloaders and the files they examine are described in Table B-1.

---

Note

When Versioning is enabled in iPlanet Application Server, the J2EE component classes(Servlet/JSP and EJB Implementation classes) are loaded by WebClassLoader/EjbClassLoader. Whereas, all other classes(helper classes) are loaded by ApplicationClassLoader. If two classes which happen to be in the same package are loaded by different ClassLoaders and their runtime packages are different, the JVM considers them to be classes in different packages. Therefore, accessing protected method in helper class from servlet/JSP/EJB implementaion class will throw IllegalAccerssError. If you want to take advantage of the dynamic reloading of classes, then make protected methods public.

---

Table B-1    iPlanet Application Server classloaders

Classloader	Description
Bootstrap Classloader	The Bootstrap Classloader looks for runtime classes in rt.jar and internationalization classes in i18n.jar. The Bootstrap Classloader is the parent of Extension and System Classloaders.
Extension Classloader	The Installed Extensions Classloader looks for classes in JAR files in the lib/ext directory of the JRE.
System Classloader	The System Classpath Classloader looks for classes in JAR files and directories on paths specified by the system property java.class.path. To have a class loaded by the System Classloader, you must include the relevant directory in the class path. This means either in iasenv.ksh (on Unix), the environment (on Unix or NT), or in the \Software\iPlanet\Application Server\6.5\Java\Classpath registry entry (on NT.)
Module Classloader	The iPlanet Application Server Module Classloader looks for classes in all directories under install_dir/ias/APPS/modules/*. All modules share this classloader. The ModuleClassLoader is another instance of the ApplicationClassLoader
Application Classloader	Each registered J2EE application is loaded by its own class loader, which looks for classes under install_dir/ias/APPS/app_name and all subdirectories. This class loader is the parent of the Web/Ejb classloaders in the application. Similarly, there is a ModuleClassLoader, which is used to load classes for all registered standalone modules. The ModuleClassLoader is nothing but another instance of the ApplicationClassLoader, and for all stanalone modules the same heirarchy is followed as for an application. In effect all standalone modules are considered as part of a default application.
Web ClassLoader	Each Web-module(WARs) in a J2EE application is assigned one WebClassLoader. All Web-components i.e Servlet classes and JSP classes(which direcly or indirectly implements javax.servlet.Servlet interface) in a web module are loaded by WebClassLoader. For each standalone web-module, a WebClassLoader is created and ModuleClassLoader is the parent for that. Note Web-component classes are loaded by WebClassLoader only if dynamic reloading is enabled. If dynamic reloading is disabled, then all the classes in an application are loaded by the Application classloader(ModuleClassLoader for standalone web module).
Ejb ClassLoader	Each Ejb-Module(JARs) in a J2EE application is assigned one EjbClassLoader. All EJBcomponents (EJB implementation classes) in the ejb module are loaded by this classloader. This classloader has a common parent classloader, which is, the Application Classloader. For each standalone Ejb- module, an EjbClassLoader is created and the ModuleClassLoader is parent for that. Note Ejb-component classes are loaded by EjbClassLoader only if dynamic reloading is enabled. If dynamic reloading is disabled, then all the classes in an application are loaded by the Application classloader(ModuleClassLoader for standalone EJB module).

Possible limitations imposed by the class loader hierarchy are listed here with suggested work-around solutions:

• Since the iPlanet Application Server ModuleClassloader, which is the class loader for all independent modules, and the iPlanet Application Server Application Classloader do not interact with each other, a J2EE application cannot load J2EE standalone module's classes (and vice versa). One way to circumvent this is to include the relevant path to the required class in the System Classpath, which will then cause it to be loaded by the System Classloader. For an example of this see the following sample:

  http://developer.iplanet.com/appserver/samples/pkging/docs/sampleC.html

  One should however note that including the relavant path for the classes in the System Classpath exposes the classes to all the application deployed under Application Server which may compromise the Security requirements of the application.This also prevents classes to be reloadable, because classses in the System Classpath are loaded by the System classloader.

• Since J2EE specs requires that one applcation should be able to access components in another application, each J2EE application in iPlanet Application Server is loaded by its own classloader and two EAR files that are registered as applications cannot load classes from each other. This ensures that classes from two applications are loaded in isolation, which prevents two similarly named classes from different applications from overwriting each other in the classloader.

• There is only one iPlanet Application Server ApplicationClassloader that is assigned to load all J2EE standalone modules. This allows two standalone modules to interact with each other. However, this means that no two classes in standalone modules should have the same name. For example, if ejb1.jar attempts to load com.samples.company.DBConnector and war1.war attempts to load com.samples.company.DBConnector, one will overwrite the other.

  
  

  ---

  Tip

  Because there is only one application classloader for all standalone modules, there is a potential security risk if you allow classes from one module to be accessed by all of the other standalone modules. Therefore, it is a good idea to include in standalone modules only reusable components that everyone is allowed to access.

  ---

  
  

  
  

  ---

  Note

  A resource such as a file that is accessed by a servlet, JSP, or EJB must be in a directory pointed to by the classloader's classpath. For example, the web class loader's classpath includes these directories: module_name/WEB-INF/classes module_name/WEB-INF/compiled_jsp module_name/WEB-INF/lib If a servlet accesses a resource, it must be in one of these directories or it will not be loaded.

  ---

  
  

Dynamic Reloading

---

Servlets, JSPs, and EJB implementation classes can be dynamically reloaded while the server is running. This allows you to change module and application code and descriptors without restarting the server. This is useful in a development environment, because it allows code changes to be tested quickly.

Dynamic reloading is not recommended for a production environment however, because it may degrade performance. In addition, whenever a reload is done, the sessions at that transit time become invalid. The client must restart the session.

When dynamic reloading is disabled, only one Module Classloader or an Application Classloader are loaded.

Enabling Dynamic Reloading

Dynamic reloading for all classes can be turned on or off using the following two methods:

• Using Administration Tool

• Modifying the Registry

Using Administration Tool

1. Select the application server instance in the left pane of the Administration Tool.

2. Click the Enable Dynamic Class Reloading checkbox.

3. Click Apply

   The appropriate changes are made by the Administration Tool in the registry to enable dynamic class reloading

Modifying the Registry

SYSTEM_JAVA\Versioning\Disable

By default it is set to 1, indicating that dynamic reloading is disabled. A value of 0 enables dynamic reloading.

You can edit the registry using the kregedit tool. For more information, see the Administrator's Guide.

Dynamic Reloading of Servlets and JSPs

Dynamic reloading, when enabled, is built into the server for servlets and JSPs. Changes made while the iPlanet Application Server is running are picked up the next time a request arrives for that servlet or JSP.

Dynamic Reloading of EJBs

Dynamic reloading, when enabled, is built into the server for EJBs. Changes made while the iPlanet Application Server is running are picked up the next time a create request arrives for that EJB.

However, an EJB's interfaces and helper classes are not dynamically reloadable, so if you change them, you must restart the server.

If an EJB changes during a session, the EJB Container serializes the states of the EJB instances involved in the session and deserializes them after recreating the pool of instances.

Limitations of Dynamic Reloading

If a J2EE component, that is Servlet or Ejb implememntaion class is being referred to directly from some other class, then the dynamic reloading for the module which the J2EE component being reffered belongs to would not work. For example creating a new instance of a Servlet/EJB implementation class from a helper class. J2EE does not recommend doing so.

If one J2EE component is accessing a package access member(protected, this case arises when J2EE component and helper classes happens to be in the same package) of an helper class and if Dynamic reloading is enabled then IleegalAccesError occures. In this case Dynamic reloading has to be switched off.

---

Note	If you have migrated from iPlanet Application Server 6.0 SPx to 6.5, you must regenerate the stubs for your EJBs, or dynamic reloading of the EJB implementation classes won't work.

---