Oracle JavaServer Pages Developer's Guide and Reference Release 8.1.7 Part Number A83726-01 |
Library | Service | Contents | Index

## Functionality of the OracleJSP Translator

JSP translators generate standard Java code for a JSP page implementation class. This class is essentially a servlet class wrapped with features for JSP functionality.

This section discusses general functionality of the OracleJSP translator, focusing on its behavior in on-demand translation environments, such as Apache/JServ or the Oracle Internet Application Server. The following topics are covered:

- Generated Code Features

- Generated Package and Class Names (On-Demand Translation)

- Generated Files and Locations (On-Demand Translation)

- Sample Page Implementation Class Source

  Important: Implementation details discussed in this section regarding package and class naming, output file locations, and generated code are for illustrative purposes only. The precise details apply to OracleJSP release 8.1.7 (1.1.0.0.0) only, in accordance with JSP 1.1 specifications, as applicable. These details are subject to change in future releases.

You must pre-translate JSP pages targeted for the Oracle Servlet Engine, either as a result of running the session shell `publishjsp` command (for deployment with server-side translation) or by running the `ojspc` pre-translation tool directly (for deployment with client-side translation). In either case, there are some differences in functionality compared with the discussion in this section, such as in placement of output files. See "Translating and Publishing JSP Pages in Oracle8i (Session Shell publishjsp)" and "The ojspc Pre-Translation Tool" for information.

### Generated Code Features

This section discusses general features of the page implementation class code that is produced by the OracleJSP translator in translating JSP source (`.jsp` and `.sqljsp` files).

#### Features of Page Implementation Class Code

When the OracleJSP translator generates servlet code in the page implementation class, it automatically handles some of the standard programming overhead. For both the on-demand translation model and the pre-translation model, generated code automatically includes the following features:

- It extends a wrapper class (`oracle.jsp.runtime.HttpJsp`) provided by the OracleJSP container that implements the standard `javax.servlet.jsp.HttpJspPage` interface (which extends the more generic `javax.servlet.jsp.JspPage` interface, which in turn extends the standard `javax.servlet.Servlet` interface).

- It implements the `_jspService()` method specified by the `HttpJspPage` interface. This method, often referred to generically as the "service" method, is the central method of the page implementation class. Code from any Java scriptlets and expressions in the JSP page is incorporated into this method implementation.

- It includes code to request an HTTP session, unless your JSP source code specifically sets `session=false` (which can be done in a `page` directive).

For introductory information about key JSP and servlet classes and interfaces, see Appendix B, "Servlet and JSP Technical Background".

#### Inner Class for Static Text

The service method, `_jspService()`, of the page implementation class includes print commands--`out.print()` calls on the implicit `out` object--to print any static text in the JSP page. The OracleJSP translator, however, places the static text itself in an inner class within the page implementation class. The service method `out.print()` statements reference attributes of the inner class to print the text.

This inner class implementation results in an additional `.class` file when the page is translated and compiled. In a client-side pre-translation scenario (usually for deployment to Oracle8i), be aware this means there is an extra `.class` file to deploy.

The name of the inner class will always be based on the base name of the `.jsp` file or `.sqljsp` file. For `mypage.jsp`, for example, the inner class (and its `.class` file) will always include "mypage" in its name.

Note: The OracleJSP translator can optionally place the static text in a Java resource file, which is advantageous for pages with large amounts of static text. (See "Workarounds for Large Static Content in JSP Pages".) You can request this feature through the OracleJSP `external_resource` configuration parameter (for on-demand translation) or the `ojspc -extres` option (for pre-translation). Enabling hotloading (for deployment to Oracle8i) also results in the static text going into a resource file. Even when static text is placed in a resource file, the inner class is still produced, and its `.class` file must be deployed. (This is only noteworthy if you are in a client-side pre-translation scenario.)

### Generated Package and Class Names (On-Demand Translation)

Although the Sun Microsystems JavaServer Pages Specification, Version 1.1 defines a uniform process for parsing and translating JSP text, it does not describe how the generated classes should be named--that is up to each JSP implementation.

This section describes how OracleJSP creates package and class names when it generates code during translation.

Important: In OracleJSP release 8.1.7 (1.1.0.0.0), the URL path directory and `.jsp` file name (which are used in generating package and class names) are restricted to valid Java package and class identifiers. For example, a path directory or `.jsp` name cannot begin with a number. It is also invalid to use Java reserved words, such as `for` or `class`, as a path directory or `.jsp` name (such as `class.jsp`). Such implementation details may change in future releases.

#### Package Naming

In an on-demand translation scenario, the URL path that is specified when the user requests a JSP page--specifically, the path relative to the doc root or application root--determines the package name for the generated page implementation class. Each directory in the URL path represents a level of the package hierarchy.

It is important to note, however, that generated package names are always lowercase, regardless of the case in the URL.

Consider the following URL as an example:

    http://host[:port]/HR/expenses/login.jsp

In OracleJSP release 8.1.7 (1.1.0.0.0), this results in the following package specification in the generated code (implementation details are subject to change in future releases):

    package hr.expenses;

No package name is generated if the JSP page is at the doc root or application root directory, where the URL is as follows:

    http://host[:port]/login.jsp

#### Class Naming

The base name of the `.jsp` file (or `.sqljsp` file) determines the class name in the generated code.

Consider the following URL example:

    http://host[:port]/HR/expenses/UserLogin.jsp

In OracleJSP release 8.1.7 (1.1.0.0.0), this yields the following class name in the generated code (implementation details are subject to change in future releases):

    public class UserLogin extends ...

Be aware that the case (lowercase/uppercase) that end-users type in the URL must match the case of the actual `.jsp` or `.sqljsp` file name. For example, they can specify `UserLogin.jsp` if that is the actual file name, or `userlogin.jsp` if that is the actual file name, but not `userlogin.jsp` if `UserLogin.jsp` is the actual file name.

In OracleJSP release 8.1.7 (1.1.0.0.0), the translator determines the case of the class name according to the case of the file name. For example:

- `UserLogin.jsp` results in class `UserLogin`.

- `Userlogin.jsp` results in class `Userlogin`.

- `userlogin.jsp` results in class `userlogin`.

If you care about the case of the class name, then you must name the `.jsp` file or `.sqljsp` file accordingly. However, because the page implementation class is invisible to the end-user, this is usually not a concern.

### Generated Files and Locations (On-Demand Translation)

This section describes files that are generated by the OracleJSP translator and where they are placed. For pre-translation scenarios, `ojspc` places files differently and has its own set of relevant options--see "Summary of ojspc Output Files, Locations, and Related Options".

The following subsections mention several OracleJSP configuration parameters. For more information about them, see "OracleJSP Configuration Parameters (Non-OSE)" and "OracleJSP Configuration Parameter Settings".

#### Files Generated by OracleJSP

This section considers both regular JSP pages (`.jsp` files) and SQLJ JSP pages (`.sqljsp` files) in listing files that are generated by the OracleJSP translator. For the file name examples, presume a file `Foo.jsp` or `Foo.sqljsp` is being translated.

Source files:

- A`.sqlj` file is produced by the OracleJSP translator if the page is a SQLJ JSP page (for example, `Foo.sqlj`).

- A`.java` file is produced for the page implementation class and inner class (for example, `Foo.java`). It is produced either directly by the OracleJSP translator from the`.jsp` file, or by the SQLJ translator from the`.sqlj` file if the page is a SQLJ JSP page. (The currently installed Oracle SQLJ translator is used by default, but you can specify an alternative translator or an alternative release of the Oracle SQLJ translator by using the OracleJSP `sqljcmd` configuration parameter.)

Binary files:

- In the case of a SQLJ JSP page, one or more binary files are produced during SQLJ translation for SQLJ profiles. By default these are `.ser` Java resource files, but they will be `.class` files if you enable the SQLJ `-ser2class` option (through the OracleJSP `sqljcmd` configuration parameter). The resource file or `.class` file has "Foo" as part of its name.

- A`.class` file is produced by the Java compiler for the page implementation class. (The Java compiler is `javac` by default, but you can specify an alternative compiler using the OracleJSP `javaccmd` configuration parameter.)

- An additional `.class` file is produced for the inner class of the page implementation class. This file will have "Foo" as part of its name.

- A`.res` Java resource file is optionally produced for the static page content (for example, `Foo.res`) if the OracleJSP `external_resource` configuration parameter is enabled.

  Note: The exact names of generated files for the page implementation class may change in future releases, but will still have the same general form. The names would always include the base name (such as "Foo" in these examples), but may include slight variations, such as `_Foo.java` or `_Foo.class`.

#### OracleJSP Translator Output File Locations

OracleJSP uses the Web server document repository to generate or load translated JSP pages.

By default, the root directory is the Web server doc root directory (for Apache/JServ) or the servlet context root directory of the application the page belongs to.

You can specify an alternative root directory through the OracleJSP `page_repository_root` configuration parameter.

In OracleJSP release 8.1.7 (1.1.0.0.0), generated files are placed as follows (implementation details may change in future releases):

- If the `.jsp` (or `.sqljsp`) file is directly in the root directory, then OracleJSP will place generated files into a `_pages` subdirectory directly under the root directory.

- If the `.jsp` (or `.sqljsp`) file is in a subdirectory under the root directory, then an equivalent directory structure is created under the `_pages` subdirectory for the generated files.

  As an example, consider an Apache/JServ environment with an `htdocs` root directory. If a `.jsp` file is in the following directory:

      htdocs/subdir/test

  then generated files will be placed in the following directory:

      htdocs/_pages/subdir/test

### Sample Page Implementation Class Source

This section uses an example to illustrate the information in the preceding sections.

Consider the following scenario:

- JSP page code is in the file `hello.jsp`.

- The page is executed in an Apache/JServ environment.

- The `hello.jsp` file is located in the following directory:

      htdocs/test

  Important: Code generation details discussed here are according to Oracle's implementation of the JSP 1.1 specification. Details may change in the future, as the result of either changes in the specification or changes in how Oracle implements aspects that are not specified.

#### Sample Page Source: hello.jsp

Following is the JSP code in `hello.jsp`:

    <HTML>
    <HEAD><TITLE>The Hello User JSP</TITLE></HEAD>
    <BODY>
    <% String user=request.getParameter("user"); %>
    <H3>Welcome <%= (user==null) ? "" : user %>!</H3>
    <P><B> Today is <%= new java.util.Date() %>. Have a nice day! :-)</B></P>
    <B>Enter name:</B>
    <FORM METHOD=get>
    <INPUT TYPE="text" NAME="user" SIZE=15>
    <INPUT TYPE="submit" VALUE="Submit name">
    </FORM>
    </BODY>
    </HTML>

#### Sample: Generated Package and Class

Because `hello.jsp` is in the `test` subdirectory of the root directory (`htdocs`), OracleJSP release 8.1.7 (1.1.0.0.0) generates the following package name in the page implementation code:

    package test;

The Java class name is identical to the base name of the `.jsp` file (case included), so the following class definition is generated in the page implementation code:

    public class hello extends oracle.jsp.runtime.HttpJsp
    {
       ...
    }

(Because the page implementation class is invisible to the end-user, the fact that its name does not adhere to Java capitalization conventions is generally not a concern.)

#### Sample: Generated Files

Because `hello.jsp` is located as follows:

    htdocs/test/hello.jsp

OracleJSP release 8.1.7 (1.1.0.0.0) generates output files as follows (the page implementation class `.java` file and `.class` file, and the inner class `.class` file, respectively):

    htdocs/_pages/test/hello.java
    htdocs/_pages/test/hello.class
    htdocs/_pages/test/hello$__jsp_StaticText.class

Note: These file names are based specifically on the OracleJSP 1.1.0.0.0 implementation; the exact details may change in future releases. All file names will always include the base "hello", however.

#### Sample Page Implementation Code: hello.java

Following is the generated page implementation class Java code (`hello.java`), as generated by OracleJSP release 8.1.7 (1.1.0.0.0):

    package test;

    import oracle.jsp.runtime.*;
    import javax.servlet.*;
    import javax.servlet.http.*;
    import javax.servlet.jsp.*;
    import java.io.*;
    import java.util.*;
    import java.lang.reflect.*;
    import java.beans.*;

    public class hello extends oracle.jsp.runtime.HttpJsp {

      public final String _globalsClassName = null;

      // ** Begin Declarations

      // ** End Declarations

      public void _jspService(HttpServletRequest request, HttpServletResponse
    response) throws IOException, ServletException {

        /* set up the intrinsic variables using the pageContext goober:
        ** session = HttpSession
        ** application = ServletContext
        ** out = JspWriter
        ** page = this
        ** config = ServletConfig
        ** all session/app beans declared in globals.jsa
        */
        JspFactory factory = JspFactory.getDefaultFactory();
        PageContext pageContext = factory.getPageContext( this, request, response,
    null, true, JspWriter.DEFAULT_BUFFER, true);
        // Note: this is not emitted if the session directive == false
        HttpSession session = pageContext.getSession();
        if (pageContext.getAttribute(OracleJspRuntime.JSP_REQUEST_REDIRECTED,
    PageContext.REQUEST_SCOPE) != null) {
          pageContext.setAttribute(OracleJspRuntime.JSP_PAGE_DONTNOTIFY, "true",
    PageContext.PAGE_SCOPE);
          factory.releasePageContext(pageContext);
          return;
    }
        ServletContext application = pageContext.getServletContext();
        JspWriter out = pageContext.getOut();
        hello page = this;
        ServletConfig config = pageContext.getServletConfig();

        try {
          // global beans
          // end global beans

          out.print(__jsp_StaticText.text[0]);
          String user=request.getParameter("user");
          out.print(__jsp_StaticText.text[1]);
          out.print(  (user==null) ? "" : user );
          out.print(__jsp_StaticText.text[2]);
          out.print(  new java.util.Date() );
          out.print(__jsp_StaticText.text[3]);

          out.flush();

        }
        catch( Exception e) {
          try {
            if (out != null) out.clear();
          }
          catch( Exception clearException) {
          }
          pageContext.handlePageException( e);
        }
        finally {
          if (out != null) out.close();
          factory.releasePageContext(pageContext);
        }

      }
      private static class __jsp_StaticText {
        private static final char text[][]=new char[4][];
        static {
          text[0] =
          "<HTML>\r\n<HEAD><TITLE>The Welcome User
    JSP</TITLE></HEAD>\r\n<BODY>\r\n".toCharArray();
          text[1] =
          "\r\n<H3>Welcome ".toCharArray();
          text[2] =
          "!</H3>\r\n<P><B> Today is ".toCharArray();
          text[3] =
          ". Have a nice day! :-)</B></P>\r\n<B>Enter name:</B>\r\n<FORM
    METHOD=get>\r\n<INPUT TYPE=\"text\" NAME=\"user\" SIZE=15>\r\n<INPUT
    TYPE=\"submit\" VALUE=\"Submit
    name\">\r\n</FORM>\r\n</BODY>\r\n</HTML>".toCharArray();
        }
      }
    }

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index