Deployment to Oracle8i with Server-Side Translation

This section describes the steps for deployment to Oracle8i with server-side translation.

The steps are as follows:

1. Use loadjava to load untranslated JSP page or SQLJ JSP page source files into Oracle8i.

2. Use the session shell publishjsp command to translate and publish the pages.

The publishjsp step automatically handles translation, compilation, hotloading (if applicable), and publishing.

Loading Untranslated JSP Pages into Oracle8i (loadjava)

As the first step for deployment with server-side translation, use the Oracle loadjava tool to load untranslated .jsp or .sqljsp files into Oracle8i as Java resource files.

If you are loading multiple files, it is recommended that you put the files into a JAR file for loading.

The loadjava tool is provided with Oracle8i as a general-purpose tool for loading Java files into the server. For an overview, see "Overview of the loadjava Tool". For further information, see the Oracle8i Java Tools Reference.

Following is an example of loading an untranslated page:

% loadjava -u scott/tiger Foo.jsp

This loads Foo.jsp into the SCOTT schema (password TIGER) as a Java resource object. There is no need to specify the loadjava -resolve (-r) option.

This will result in the following resource schema object being created in the database:

• SCOTT:Foo.jsp

Note that any path information you specify for the .jsp file, either in a JAR file or on the loadjava command line, determines placement of the resource schema object. Consider the following modification of the previous example:

% loadjava -u scott/tiger xxx/yyy/Foo.jsp

This will result in the following resource schema object being created in the database:

• SCOTT:xxx/yyy/Foo.jsp

For an overview of how loadjava names the schema objects it produces, see "Database Schema Objects for Java".

You can also load a .sqljsp file:

% loadjava -u scott/tiger Foo.sqljsp

This loads Foo.sqljsp into the SCOTT schema and will result in the following resource schema object being created in the database:

• SCOTT:Foo.sqljsp

If you want to load multiple .jsp (or .sqljsp) files, you can use a wildcard character (depending on your operating environment; assume % is a UNIX prompt):

% loadjava -u scott/tiger *.jsp

Or presume you had put the .jsp files into a JAR file:

% loadjava -u scott/tiger myjspapp.jar

Translating and Publishing JSP Pages in Oracle8i (Session Shell publishjsp)

Translation, compilation, hotloading (if enabled), and publishing all occur automatically in the scenario of deployment with server-side translation, as the result of executing the JServer session shell publishjsp command. See "Overview of the sess_sh Session Shell Tool" for how to start the session shell and connect to the database.

Run publishjsp after you have loaded a .jsp (or .sqljsp) file into Oracle8i as a resource schema object. (This section includes separate discussion for running publishjsp on a .sqljsp file because there are some logistical differences in the results.)

Note: JSP pages that are published with publishjsp can be "unpublished" (removed from the JServer JNDI namespace) with the session shell unpublishjsp command. See "Unpublishing JSP Pages with unpublishjsp".

Overview of publishjsp Syntax and Options

Starting sess_sh establishes a connection to the database. Once you start sess_sh, you can run the publishjsp command from the session shell $ prompt.

The publishjsp command uses the following general syntax:

$ publishjsp [options] path/name.jsp

The options can be any of the following:

[-schema schemaname] [-virtualpath path] [-servletName name] [-packageName name] 
[-context context] [-hotload] [-stateless] [-verbose] [-resolver resolver] 
[-extend class] [-implement interface]

Important: Enable boolean options, such as -hotload, by typing only the option name in the command line (not setting it to true). For options where you specify a value, the value does not have to be in quotes.

The file name.jsp (or name.sqljsp for a SQLJ JSP page) is the JSP page resource schema object that you loaded with loadjava and is the only required parameter, along with any relevant schema path information.

By default, if no -virtualpath option is specified, path/name.jsp becomes the servlet path. For example, running publishjsp on dir1/foo.jsp (the path within the current schema or specified schema) results in dir1/foo.jsp as the servlet path.

By default, if no -context option is specified, the OSE default servlet context is used and "/" is the context path.

Together, the context path and servlet path (along with the host name and port) determine the URL to invoke the page, as described in "URLs for the Oracle Servlet Engine".

The following informative options are also available:

• Use -showVersion by itself to display the OracleJSP version number and exit.

• Use -usage by itself to display a publishjsp option list and exit.

Following are the option descriptions:

• -schema schemaname

  Use this option to specify the schema where the JSP page resource schema object is located, if it is not in the same schema you logged in to through sess_sh.

  This schema must be accessible from your sess_sh login schema. The publishjsp command does not offer a way to specify passwords.

• -virtualpath path

  You can use this option to specify an alternative servlet path for the JSP page; otherwise, the servlet path is simply the specified .jsp file name itself along with any specified schema path.

  For example:

  -virtualpath altpath/Foo.jsp
  
  

  or perhaps simply:

  -virtualpath mypath.jsp
  
  

• -servletName name

  You can use this option to specify an alternative servlet name (in OSE named_servlets) for the JSP page; however, the servlet name has no bearing on how the page is invoked so is rarely needed.

  By default, the servlet name is the base name of the .jsp file along with any path you specified. For example, running publishjsp on SCOTT:dir1/Foo.jsp results in dir1.Foo as the servlet name in OracleJSP release 8.1.7 (1.1.0.0.0) (Be aware that implementation details are subject to change in future releases.)

• -packageName name

  You can use this option to specify a package name for the generated page implementation class; otherwise, it is determined by any path specification for the .jsp file when you run publishjsp. For example, running publishjsp on SCOTT:dir1/Foo.jsp results in package dir1 for the page implementation class.

  The -packageName option affects where schema objects are placed in the schema, but does not affect the servlet path of the JSP page.

• -context context

  You can use this option to specify a servlet context in the Oracle Servlet Engine. The context path of this servlet context becomes part of the URL used to invoke the page.

  If you do not use this option, the JSP page will be in the OSE default context, /webdomains/contexts/default, whose context path is simply "/".

  Any specified context should be under /webdomains/contexts, such as:

  /webdomains/contexts/mycontext
  
  

  Important: Remember that it is the context path of the servlet context, not the context name itself, that is used in URLs to access the page. When a servlet context is created in OSE with the session shell createcontext command, both the context path (through the createcontext -virtualpath option) and the context name must be specified. It is convenient, and probably typical, to specify the context name and context path to be the same, but it is not required.

• -hotload

  Enable this flag to enable and perform hotloading. This results in the following steps being performed by the publishjsp command:

  1. Static output is written to a resource schema object instead of to the page implementation class schema object.

  2. A main() method and a hotloading method are implemented in the generated page implementation class to allow hotloading.

  3. The main() method is executed to perform hotloading.

  To use -hotload, you must have permission for the JServer hotloader. This can be granted as follows (from SQL*Plus, for the SCOTT schema, for example):

  dbms_java.grant_permission('SCOTT', 'SYS:oracle.aurora.security.JServerPermission', 'HotLoader', null);
       
  
  
           

  For an overview of hotloading, see "Overview of Hotloaded Classes in Oracle8i".

• -stateless

  This is a boolean option that tells the Oracle Servlet Engine that the JSP page is to be stateless--the JSP page should not have access to the HttpSession object during execution.

  This flag is used for mod_ose optimization. For information about the Apache mod_ose module, see the Oracle8i Oracle Servlet Engine User's Guide.

• -verbose

  Set this option to true to direct publishjsp to report the translation steps as it executes.

• -resolver

  Use this option to specify an alternative Java class resolver. The resolver is used in compiling and resolving Java source through loadjava, including locating classes used in JSP pages.

  The default resolver is ((* user) (* PUBLIC)). For the SCOTT schema, for example, this is the following:

  ((* SCOTT) (* PUBLIC))
  
  

  For the -resolver option, you must specify the value in quotes as in the following example:

  $ publishjsp ... -resolver "((* BILL) (* SCOTT) (* PUBLIC))" ...
  
  

• -extend

  Use this option to specify a Java class that the generated page implementation class will extend.

• -implement

  Use this option to specify a Java interface that the generated page implementation class will implement.

Examples: Publishing JSP Pages with publishjsp

This section provides examples of using publishjsp to translate and publish .jsp pages in Oracle8i. The pages will have already been loaded as resource schema objects in a particular schema, such as SCOTT:Foo.jsp.

(For information about running publishjsp on .sqljsp pages, see "Publishing SQLJ JSP Pages with publishjsp".)

To review how the servlet path and context path combine in forming the URL to invoke the page, see "URLs for the Oracle Servlet Engine".

Notes: The following examples use the SCOTT schema. SCOTT must either be the schema specified when starting sess_sh, or accessible from the schema specified. Each example lists the schema objects that are created, although this is secondary. All that matters in invoking the JSP page is the servlet path and context path. The page implementation class schema object is automatically mapped during the publishjsp publishing step. Application-relative and page-relative syntax for dynamic jsp:include and jsp:forward statements inside Oracle8i is the same as for any JSP environment. The relative paths are according to how the JSP pages were published (as shown in the examples below). The exact names of generated schema objects 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 instead of Foo. $ is the sess_sh prompt.

Example 1

$ publishjsp -schema SCOTT dir1/Foo.jsp

This uses the default servlet context, which has a context path of "/".

The default servlet path is dir1/Foo.jsp.

After this command, Foo.jsp can be invoked as follows:

http://host[:port]/dir1/Foo.jsp

Access it dynamically from another JSP page in the application, suppose a page published as dir1/Bar.jsp, as follows (using page-relative syntax and then application-relative syntax):

<jsp:include page="Foo.jsp" flush="true" />

or:

<jsp:include page="/dir1/Foo.jsp" flush="true" />

By default, dir1 is the Java package for the page implementation class and inner class (because of the specified path in the SCOTT schema).

The following schema objects are created:

• SCOTT:dir1/Foo source schema object

• SCOTT:dir1/Foo class schema object

• a class schema object under dir1 for the inner class for static text (with "Foo" in the name, such as SCOTT:dir1/Foo$__jsp__StaticText)

Example 2

$ publishjsp -schema SCOTT -context /webdomains/contexts/mycontext Foo.jsp
    

        

Presume mycontext had been created as follows:

$ createcontext -virtualpath mycontext /webdomains mycontext

The publishjsp command publishes the page to the mycontext servlet context, which was created with mycontext also specified as the context path.

The default servlet path is simply Foo.jsp.

After this command, Foo.jsp can be invoked as follows:

http://host[:port]/mycontext/Foo.jsp

Access it dynamically from another JSP page in the application, suppose a page published as Bar.jsp, as follows (using page-relative syntax and then application-relative syntax):

<jsp:include page="Foo.jsp" flush="true" />

or:

<jsp:include page="/Foo.jsp" flush="true" />

Even though this example specifies a non-default servlet context, that is not relevant for dynamic jsp:include or jsp:forward commands. What is relevant is that the published path of the page relative to that context is simply /Foo.jsp.

By default, there is no Java package for the page implementation class and inner class (because no path is specified in the SCOTT schema).

The following schema objects are created:

• SCOTT:Foo source schema object

• SCOTT:Foo class schema object

• a class schema object for the inner class for static text (with "Foo" in the name, such as SCOTT:Foo$__jsp__StaticText)

Example 3

$ publishjsp -schema SCOTT -context /webdomains/contexts/mycontext dir1/Foo.jsp
    

        

Presume mycontext had been created as follows:

$ createcontext -virtualpath mywebapp /webdomains mycontext

The publishjsp command publishes the page to the mycontext servlet context, which was created with mywebapp specified as the context path.

The default servlet path is dir1/Foo.jsp.

After this command, Foo.jsp can be invoked as follows:

http://host[:port]/mywebapp/dir1/Foo.jsp

Access it dynamically from another JSP page in the application, suppose a page published as dir1/Bar.jsp, as follows (using page-relative syntax and then application-relative syntax):

<jsp:include page="Foo.jsp" flush="true" />

or:

<jsp:include page="/dir1/Foo.jsp" flush="true" />

Example 1 and Example 3 use different servlet contexts, but in either case what is relevant for the application-relative include command is that the published path of the page relative to that context is /dir1/Foo.jsp.

By default, dir1 is the Java package for the page implementation class and inner class.

The following schema objects are created:

• SCOTT:dir1/Foo source schema object

• SCOTT:dir1/Foo class schema object

• a class schema object for the inner class for static text (with "Foo" in the name, such as SCOTT:dir1/Foo$__jsp__StaticText)

Example 4

$ publishjsp -schema SCOTT -hotload -packageName mypkg dir1/Foo.jsp

This performs hotloading, uses the default servlet context, and overrides the default dir1 package.

The context path is "/".

The -packageName option does not affect the servlet path, which, by default, remains dir1/Foo.jsp.

After this command, Foo.jsp can be invoked as follows:

http://host[:port]/dir1/Foo.jsp

Access it dynamically from another JSP page in the application, suppose a page published as dir1/Bar.jsp, as follows (using page-relative syntax and then application-relative syntax):

<jsp:include page="Foo.jsp" flush="true" />

or:

<jsp:include page="/dir1/Foo.jsp" flush="true" />

The following schema objects are created:

• SCOTT:mypkg/Foo source schema object

• SCOTT:mypkg/Foo class schema object

• a class schema object under mypkg for the inner class (with "Foo" in the name, such as SCOTT:mypkg/Foo$__jsp__StaticText)

• SCOTT:mypkg/Foo.res resource schema object for the static text that is normally in the inner class (the resource is hotloaded as part of publishjsp functionality)

Publishing SQLJ JSP Pages with publishjsp

This section provides an example of using publishjsp to translate and publish a .sqljsp page in Oracle8i. The page will have already been loaded as a resource schema object in a particular schema, such as SCOTT:Foo.sqljsp.

In addition, see "Examples: Publishing JSP Pages with publishjsp".

To review how the servlet path and context path combine in forming the URL to invoke the page, see "URLs for the Oracle Servlet Engine".

Be aware of the following for .sqljsp pages:

• Beyond what is created for a .jsp page, an additional schema objects is created--a resource schema object for the SQLJ profile. This is always a .ser resource schema object, as opposed to a class schema object, because there is no SQLJ -ser2class option when translating in the server.

  For information about SQLJ profiles, see the Oracle8i SQLJ Developer's Guide and Reference.

• The generated source schema object is SQLJ source instead of Java source.

• SQLJ has very limited option support in the server.

Server-Side SQLJ Options

Client-side SQLJ options are not available for translation in the server (this is true in general, not just for JSP pages). Instead, there is a small set of options available through the standard Oracle8i JAVA$OPTIONS table as set by the dbms_java.set_compiler_option() stored procedure (using SQL*Plus, for example). Of these options, only the following is supported for JSP pages:

• online

This is a boolean option that enables online semantics-checking through the default oracle.sqlj.checker.OracleChecker front-end.

For more information about server-side SQLJ and semantics-checking, see the Oracle8i SQLJ Developer's Guide and Reference,

Example of publishjsp for SQLJ JSP Page

Following is an example of publishjsp usage for a .sqljsp page ($ is the sess_sh prompt).

Notes: This example uses the SCOTT schema. SCOTT must either be the schema specified when starting sess_sh, or accessible from the schema specified. This example documents the schema objects that are created, although this is secondary. All that matters in invoking the JSP page is the servlet path and context path. The page implementation class schema object is automatically mapped during the publishjsp publishing step. The exact names of generated schema objects 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 instead of Foo.

$ publishjsp -schema SCOTT dir1/Foo.sqljsp

This uses the default OSE servlet context, the context path of which is "/".

The servlet path, by default, is dir1/Foo.sqljsp.

After this command, Foo.sqljsp can be invoked as follows:

http://host[:port]/dir1/Foo.sqljsp

Access it dynamically from another JSP page in the application, suppose a page published as dir1/Bar.jsp, as follows (using page-relative syntax and then application-relative syntax):

<jsp:include page="Foo.sqljsp" flush="true" />

or:

<jsp:include page="/dir1/Foo.sqljsp" flush="true" />

By default, dir1 is the Java package for the page implementation class and inner class (because of the specified path in the SCOTT schema).

The following schema objects are created:

• SCOTT:dir1/Foo source schema object

• SCOTT:dir1/Foo class schema object

• class schema object under dir1 for the inner class for static text (with "Foo" in the name, such as SCOTT:dir1/Foo$__jsp__StaticText)

• resource schema object under dir1 for the SQLJ profile (with "Foo" in the name, such as SCOTT:dir1/Foo_SJProfile0.ser)

Unpublishing JSP Pages with unpublishjsp

The sess_sh tool also has an unpublishjsp command that removes a JSP page from the JServer JNDI namespace. This does not, however, remove the page implementation class schema object from the database.

Unlike the unpublishservlet command, you do not need to specify a servlet name (unless you specified one when you ran publishjsp). Generally, the only required input is the servlet path (sometimes referred to as the "virtual path").

Following is the general syntax:

$ unpublishjsp [-servletName name] [-context context] [-showVersion] [-usage] [-verbose] servletpath
    

        

The -servletName, -context, -showVersion, -usage, and -verbose options are the same as for publishjsp, as described in "Overview of publishjsp Syntax and Options".

In using unpublishjsp, specify the values for -servletName and -context that you specified in using publishjsp.

As an example, here is the command to unpublish the page that was published in Example 4:

$ unpublishjsp dir1/Foo.jsp

(Remember that the -packageName option specified in Example 4 has no effect on the servlet path.)

---