Oracle JSP - Developers Guide Release 1.0

Contents Index

3
What Every Developer Needs to Know

This chapter describes fundamental information about Oracle JSPs that you must know before you begin building applications.

• "JSP Class Names" discusses how Oracle JSP generates the translated code's class names from the incoming HTTP request . Understanding this algorithm allows you to avoid class name collisions.
• "JSP Class Paths" discusses the default locations used by Oracle JSPs to load application dependent classes. This is your (default) mechanism for co-locating application classes with your JSPs for easy deployment and installation.
• "Retranslation rules" discusses when Oracle JSP may require a page to be recompiled.
• "Debugging Oracle JSPs" discusses techniques for isolating JSP application bugs.

3.1 JSP Class Names

Although the JSP standard defines a uniform process for parsing and translating JSP text, it does not describe how the resulting classes are named. Each implementation defines its own rules. You need to understand these rules so that application classes you develop explicitly will not collide with the JSP class names. Likewise, because Oracle JSP supports a runtime only (no translation) version of its engine, you need to understand these rules to properly install a precompiled application in a runtime-only server.

3.1.1 Generation Rules

The following are Oracle JSP's rules for generating class names:

• The complete URI path specifies the class package name. Each directory in the URI path represents a package name in the package hierarchy. Package names are always represented in lowercase, regardless of the case in the URI. For example:

  
  http://myserver/HR/expenses/Login.jsp

  yields a package name of:

  package hr.expenses
   

• The URI target (the jsp reference) names the class. Names are case-sensitive. The case used in the URI must match exactly the name of the .jsp file in the repository (file system), otherwise an Oracle JSP exception is reported. For example:

http://myserver/HR/expenses/Login.jsp

yields a classname of:

public class Login extends ....

The one limitation of this algorithm is that the virtual path namespace can contain names that are invalid Java package or classnames. To use Oracle JSP you must restrict your path and target names to valid Java (package and class) identifiers. For example a path or target can't begin with a number. It is also invalid to use Java reserved words such as for or class as a path directory or classname.

3.1.2 Deployment Considerations

Typically, you will deploy your JSPs in their normal text state. When doing so the application can be installed and mapped using any desired virtual path. It is not required that the path match the one used for development. This does of course assume that all path references in your JSPs are relative rather than absolute. This works because the server that these JSPs are installed on will translate/compile the pages and generate Java classes based on the above rules when the page is first requested. Because server virtual paths are unique within any given host, the generated class names will be unique at least with respect to other generated JSP class names regardless of the path that your JSPs are mapped to on the given server. It is always possible that a name will collide with a library or application class but is unlikely as long as these classes follow the Java guidelines of using company names in their package names.

However, if you deploy precompiled JSPs on a server supporting the Oracle JSP runtime then the above is not true. Precompiled JSPs must be installed and mapped to the same virtual path as used when they were translated and compiled.

3.2 JSP Class Paths

Most JSP applications use class libraries (beans) to provide a significant portion of their function. Oracle JSP defines a standard location on the web server relative to the application root for locating these libraries. Class and jar files located as such do not require additional server configuration to work within your JSP application or page. Instead, Oracle JSP is able to automatically load these classes even though they are not explicitly configured in the server's ClassPath. This simplifies both application development and deployment as well as enhances security as these classes are loaded by a non-system classloader.

Oracle JSPs search for classes in two directories:

/WEB-INF/classes
/WEB-INF/lib

The classes directory contains unjarred Java classes. These classes should be stored in the classes directory according to Java naming rules as class package names are reflected in the directory structure of the path. For example, the class oracle.jsp.sample.lottery.LottoBean.class, would be stored in:

/WEB-INF/classes/oracle/jsp/sample/lottery/LottoBean.class

The lib directory contains jar files. If the LottoBean.class is stored in lottery.jar, then there would be no classes directory, but the lib directory would contain:

/WEB-INF/lib/lottery.jar

The /WEB-INF directory is relative to the application's root directory. The application root directory can be located in any of the following locations (in order):

• The directory containing the globals.jsa file.
• The directory in the web server that this application is mapped to (as an application).
• The document root directory of the web server

Note: Many web servers do not support application configuration yet which is partly why we support globals.jsa. In this case, or when application mapping is not used, the default application is the server itself. Thus, the default application's root is the server's document root.

3.3 Retranslation Rules

Oracle JSP will automatically retranslate a page when:

• the page is changed. The actual check is whether the JSP runtimes in memory cache value holding the last modified time of the JSP pages class file is older than the last modified time of the JSP page itself. Because we use in memory values to remember the last modified time of the class file, removing class files from the repository will not cause Oracle JSP to retranslate the page. It will only retranslate (immediately) if the JSP file's timestamp changes.

  Note: The class file will be regenerated in the above scenario when the cache is lost. This happens whenever a request is directed to this page after the server is restarted or after another page in this application has been retranslated.

Oracle JSP will automatically reload a page when:

• an Oracle JSP loaded application class (bean) is modified. As described in the previous section, Oracle JSP automatically loads classes from prescribed locations. Additionally, Oracle JSP can be configured to have its own classpath (distinct from the web servers). Oracle JSP checks that all classes it loads have not been changed before dispatching a request. If a class has been changed, the page is reloaded.

  Note: This only works for Oracle JSP loaded classes. If the class is loaded from the server's ClassPath, then Oracle JSP does not load it (the system does) and it cannot detect it has been changed.
   

• when any page in the this page's application is reloaded. All Oracle JSP pages run in an application. If the page is not configured to run in a specific application, then it runs in a default application. Oracle JSP loads application-dependent classes (see item above) on an application by application basis. Reloading a page requires (logically) unloading these classes. As these are maintained on an application basis, all the application's classes are unloaded. This requires Oracle JSP to unload all the application's pages and to subsequently reload (but not retranslate) them when a subsequent request occurs.

  Note: Oracle JSP currently doesn't reload a page if an included file (using <%@ include %>) changes.

3.4 Debugging Oracle JSPs

In the course of developing a JSP application you may need to debug your logic. The standard mechanism for this is to add debugging (print) statements within the JSP to either output state directly into the response stream (so you can view it in your browser) or into the server's log (by calling application.log ). Either can be tedious and may prove unsatisfactory for debugging complex problems (for example bugs caused by interactions between a page and its beans). In these situations, a source debugger is needed. The upcoming Oracle JDeveloper 3.0 includes support for source-level JSP development and debugging. JSP pages (including globals.jsa) can be developed in a JDeveloper project, run, and debugged entirely within the IDE. All debugging capabilities are available to the JSP developer by setting breakpoints in JSP source, stepping through JSP source, inspecting JSP variables, and so on.