OracleJSP Support for JavaServer Pages Developer's Guide and Reference Release 1.1.2.3 Part Number A90208-01 |
|
This chapter primarily discusses considerations and procedures for deploying JSP applications to the Oracle9i database or middle-tier database cache to run in the Oracle9i Servlet Engine. It also describes general OracleJSP translation features and briefly discusses deployment in other environments, particularly the Apache/JServ environment used by the Oracle9i Application Server.
The following topics are covered:
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, which is included with the Oracle9i Application Server. The following topics are covered:
You must pre-translate JSP pages targeted for the Oracle9i Servlet Engine, either as a result of running the session shell publishjsp
command (for deployment with server-side translation), by running the ojspc
pre-translation tool directly (for deployment with client-side translation), or by using Oracle WAR deployment. In any 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 Oracle9i (Session Shell publishjsp)" and "The ojspc Pre-Translation Tool" for information about the first two scenarios. For information about Oracle WAR deployment, see the Oracle9i Servlet Engine Developer's Guide.
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).
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:
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).
_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.
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".
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 Oracle9i), 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
Even when static text is placed in a resource file, the inner class is still produced, and its |
The OracleJSP translator follows a consistent set of conventions in naming output classes, packages, files and directories (and, in the case of deployment to the Oracle9i database or database cache, in naming schema paths). However, this set of conventions and other implementation details may change from release to release.
One fact that is not subject to change is that the base name of a JSP page will be included intact in output class and file names as long as it does not include special characters. For example, translating MyPage123.jsp
will always result in the string "MyPage123" being part of the page implementation class name, Java source file name, and class file name.
In OracleJSP release 1.1.2.x (as well as some previous releases), the base name is preceded by an underscore ("_"). Translating MyPage123.jsp
results in page implementation class _MyPage123
in source file _MyPage123.java
, which is compiled into _MyPage123.class
.
Similarly, where path names are used in creating Java package names (and schema path names for Oracle9i), each component of the path is preceded by an underscore. Translating /jspdir/myapp/MyPage123.jsp
, for example, results in class _MyPage123
being in the following package:
_jspdir._myapp
The package name is used in creating directories for output .java
and .class
files, so the underscores are also evident in output directory names. For example, in translating a JSP page in the directory htdocs/test
, the OracleJSP translator by default will create directory htdocs/_pages/_test
for the page implementation class source.
Note:
All output directories are created under the standard |
If special characters are included in a JSP page name or path name, the OracleJSP translator takes steps to ensure that no characters that would be illegal in Java appear in the output class, package, and file names. For example, translating My-name_foo12.jsp
results in _My_2d_name__foo12
being the class name, in source file _My_2d_name__foo12.java
. The hyphen is converted to a string of alpha-numeric characters. (An extra underscore is also inserted before "foo12".) In this case, you can only be assured that alphanumeric components of the JSP page name will be included intact in the output class and file names. For example, you could search for "My", "name", or "foo12".
These conventions are demonstrated in examples provided later in this section and later in this chapter.
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.
Note: For information about general conventions used by OracleJSP in naming output classes, packages, files, and schema paths, see "General Conventions for Output Names" |
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 1.1.2.x, 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
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 1.1.2.x, 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 1.1.2.x, 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.
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".
Note: For information about general conventions used by OracleJSP in naming output classes, packages, files, and schema paths, see "General Conventions for Output Names" |
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:
.sqlj
file is produced by the OracleJSP translator if the page is a SQLJ JSP page (for example, _Foo.sqlj
).
.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:
.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.
.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.)
.class
file is produced for the inner class of the page implementation class. This file will have "Foo" as part of its name.
.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.
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 1.1.2.x, generated files are placed as follows (implementation details may change in future releases):
.jsp
(or .sqljsp
) file is directly in the root directory, then OracleJSP will place generated files into a default _pages
subdirectory directly under the root directory.
.jsp
(or .sqljsp
) file is in a subdirectory under the root directory, then a parallel directory structure is created under the _pages
subdirectory for the generated files. Subdirectory names under the _pages
directory are based on subdirectory names under the root directory.
As an example, consider an Apache/JServ environment with an htdocs
doc 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
This section uses an example to illustrate the information in the preceding sections.
Consider the following scenario:
hello.jsp
.
hello.jsp
file is located in the following directory:
htdocs
/test
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>
Because hello.jsp
is in the test
subdirectory of the root directory (htdocs
), OracleJSP release 1.1.2.x generates the following package name in the page implementation code:
package _test;
The Java class name is determined by the base name of the .jsp
file (including case), 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.)
Because hello.jsp
is located as follows:
htdocs/test/hello.jsp
OracleJSP release 1.1.2.x 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
Following is the generated page implementation class Java code (_hello.java
), as generated by OracleJSP release 1.1.2.x:
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(); } } }
This section is an overview of considerations and logistics in deploying a JSP application into Oracle9i to run in the Oracle9i Servlet Engine. The following topics are covered:
Java code that executes in the Oracle9i Servlet Engine in the Oracle9i database or database cache uses the Oracle JVM. The code must be loaded into a particular Oracle9i schema as one or more schema objects.
The three kinds of schema objects for Java are:
Each schema object is an individual library unit. When you query the ALL_OBJECTS
table of the schema, Java schema objects are seen as type JAVA SOURCE
, JAVA CLASS
, or JAVA RESOURCE
, respectively.
See the Oracle9i Java Developer's Guide for more information.
The Oracle9i loadjava
tool is used to load Java files into Oracle9i as schema objects. (See "Overview of the loadjava Tool".)
When you compile on the client and load the .class
file directly, loadjava
stores the .class
file as a class schema object in Oracle9i.
When you load a resource file (such as a .res
file for static JSP content or .ser
profile file for SQLJ), loadjava
stores the resource file as a resource schema object in Oracle9i.
When you load a .java
(or .sqlj
) source file, loadjava
stores the source file as a source schema object in Oracle9i and compiles it inside the database (or database cache) to create one or more class schema objects.
When you load a .jsp
or .sqljsp
page source file (for server-side translation), loadjava
stores the page source as a resource schema object. During server-side translation (through the Oracle9i session shell publishjsp
command), server-side loadjava
is invoked automatically to create source schema objects, class schema objects, and resource schema objects during translation and compilation.
(See "Tools and Commands for Translation and Deployment to Oracle9i" for an overview of the loadjava
and session shell tools.)
The two forms of schema object names in Oracle9i are full names and short names.
Full names are fully qualified and are used as the schema object names wherever possible. If any full name contains more than 31 characters, however, or contains characters that are illegal or cannot be converted to characters in the database character set, then Oracle9i converts the full name to a short name to employ as the name of the schema object, keeping track of both names and how to convert between them. If the full name contains 31 characters or less and has no illegal or inconvertible characters, then the full name is used as the schema object name.
For more information about these and about other file naming considerations, including DBMS_JAVA
procedures to retrieve a full name from a short name and a short name from a full name, see the Oracle9i Java Developer's Guide.
During loading of Java files into Oracle9i, the loadjava
tool uses the following logic to determine the package for Java schema objects it creates:
.java
and .sqlj
files) and class schema objects (created from .class
files or by compiling .java
files), the schema package is determined by any package information in the Java code.
For example, a class Foo
that specifies the package pkg1.pkg2
and is being loaded into the SCOTT
schema will be stored in the schema as follows:
SCOTT:pkg1/pkg2/Foo
.res
and .ser
Java resource files, for example), the schema package is determined by any path information in the loadjava
command line (if the Java resource file is being loaded directly) or the JAR file (if the Java resource file is being loaded as part of a JAR file).
For example, a .res
file being loaded into the SCOTT
schema as pkg3/pkg4/abcd.res
will be stored in a schema object as follows:
SCOTT:pkg3/pkg4/abcd.res
Any JSP page (or servlet) that will run in the Oracle9i Servlet Engine must be "published", a process that makes its executable Java code (the class schema objects) accessible through entries in the Oracle9i JNDI namespace.
Publishing the JSP page links its page implementation class schema object to a servlet path (and optionally to a non-default servlet context path). The servlet path (and context path, if applicable) becomes part of the URL that an end user would specify to access and execute the page. See "URLs for the Oracle9i Servlet Engine" for more information.
To publish a JSP page, use the Oracle9i session shell publishjsp
command for the "deployment with server-side translation" scenario, or the session shell publishservlet
command for the "deployment with client-side translation" scenario. See "Translating and Publishing JSP Pages in Oracle9i (Session Shell publishjsp)" or "Publishing Translated JSP Pages in Oracle9i (Session Shell publishservlet)".
JSP pages and servlets running in the Oracle9i Servlet Engine are typically accessed through the Oracle HTTP Server, powered by Apache, and its mod_ose
module. It is possible, however, to use OSE itself as the Web server.
For more information about the role of the Oracle HTTP Server and mod_ose
, see "Role of the Oracle HTTP Server, Powered by Apache".
This section describes how URLs are formed for servlets and JSP pages that will run in the Oracle9i Servlet Engine.
As with servlet URLs in general, URLs to invoke JSP pages running in the Oracle9i Servlet Engine are formed by a combination of two components in addition to the hostname and port:
The servlet path is often referred to as the "virtual path" and is determined by the -virtualpath
option when you publish a servlet or JSP page. Be aware, however, that it is the context path that is determined through the -virtualpath
option when a servlet context is created. Do not confuse the servlet path "virtual path" and the context path "virtual path".
For every OSE Web domain there is a default context, /
domain_name
/contexts/default
(where domain_name
represents the name of the particular domain). The context path for any OSE default context is simply:
/
The context path for any other OSE servlet context you create, which you accomplish using the Oracle9i session shell createcontext
command, is whatever you specify in the createcontext -virtualpath
option. It is conventional, but not required, to specify that the context path be the same as the context name. (The -virtualpath
option is required whenever you execute the createcontext
command.)
Notes: For purposes of the discussion here and elsewhere in this chapter, assume OSE single-domain mode. In this case, there is just one domain per Web service. For information about single-domain mode versus multi-domain mode and how this would affect the URL, see the Oracle9i Servlet Engine Developer's Guide. |
For general information about the session shell createcontext
command, see the Oracle9i Java Tools Reference. For an overview of the Oracle9i session shell, see "Overview of the sess_sh Session Shell Tool".
The servlet path (JSP page "virtual path") is determined by how you publish the JSP page, as follows:
publishjsp
command (for server-side translation), then it is determined by the publishjsp -virtualpath
option, or is the same as the specified schema path by default.
publishservlet
command (after client-side translation), then it is determined by the publishservlet -virtualpath
option (which you must specify when you use publishservlet
for a JSP page).
See "Translating and Publishing JSP Pages in Oracle9i (Session Shell publishjsp)" or "Publishing Translated JSP Pages in Oracle9i (Session Shell publishservlet)".
Each OSE Web service has a port associated with it, which an end user must specify as part of the URL if the OSE default Web service (admin
) is not being used:
http://host[:port]/path
In this syntax, path
is the combination of the context path and servlet path.
The port for the default admin
Web service is 8080. The port for any other Web service is determined using the session shell tool addendpoint
command. (See "Overview of the sess_sh Session Shell Tool" for general information about the tool. See the Oracle9i Java Tools Reference for information about the addendpoint
command.)
A Makefile is provided with Oracle9i to create an OSE Web service called scottService
. The domain is /scottRoot
, the default context is /scottRoot/contexts/default
, and an additional context, /scottRoot/contexts/scottContext
, is also created automatically. (Note that these are JNDI names only and are not directly related to URLs.)
The context path for the default context is:
/
The context path for scottContext
is:
/ose
The scottService
port number is 8088.
The scottRoot
servlet contexts will be used in the examples in the next section and elsewhere in this chapter.
This section provides examples of OSE URLs, using servlet contexts of scottService
as described immediately above.
As an example, consider a JSP page that is published to the scottService
default context with a servlet path (virtual path), as follows:
mydir/mypage.jsp
This page is accessed as follows:
http://host:8088/mydir/mypage.jsp
You can access it from another page in the application, say mydir/mypage2.jsp
, in either of the following ways (the first is a page-relative path; the second is an application-relative path):
<jsp:include page="mypage.jsp" flush="true" /> <jsp:include page="/mydir/mypage.jsp" flush="true" />
Now consider the scottContext
servlet context, created as follows ($
is the session shell prompt):
$ createcontext -virtualpath /ose /scottRoot scottContext
This does the following:
/scottRoot
.
/scottRoot/contexts/scottContext
(all servlet contexts in OSE go under /
domain_name
/contexts
).
/ose
as the context path.
If mydir/mypage.jsp
is published to the scottContext
servlet context, it is accessed as follows:
http://host:8088/ose/mydir/mypage.jsp
(Note that /scottRoot
and /scottRoot/contexts/scottContext
are JNDI names only and are not related to the URL. It is the context path that is relevant to the URL.)
You can access the page from another page in the application, say mydir/mypage2.jsp
, in either of the following ways (the first is a page-relative path; the second is an application-relative path):
<jsp:include page="mypage.jsp" flush="true" /> <jsp:include page="/mydir/mypage.jsp" flush="true" />
The syntax for the dynamic jsp:include
statements is the same as in Example 1. Even though a different servlet context is used, the path of the pages relative to the context is unchanged.
This section describes the required placement of static files, such as HTML files, that are used in a JSP application that runs in the Oracle9i Servlet Engine (with OSE being used as its own Web server).
Static files that are dynamic include
or forward
targets (jsp:include
or jsp:forward
) in a JSP application running in the Oracle9i Servlet Engine must be manually moved or copied to the OSE doc root directory corresponding to the servlet context of the application. When you create an OSE servlet context, using the session shell createcontext
command, you specify a doc root directory through the createcontext -docroot
option. Each OSE doc root directory is linked to the Oracle9i JNDI namespace. (For more information about the session shell createcontext
command, see the Oracle9i Java Tools Reference.)
OSE doc root directories are outside the database (or database cache). The JNDI lookup mechanism for static files is a front-end for the file system of the server on which the database resides.
Any file that is statically included (through an include
directive) by a JSP page, whether it is another JSP page or a static file such as an HTML file, must be accessible by the OracleJSP translator during translation.
In the case of a JSP application targeted for OSE, there are three translation scenarios:
This is where you load a .jsp
file into Oracle9i as a Java resource, then use publishjsp
to invoke the OracleJSP translator in the server. (See "Deployment to Oracle9i with Server-Side Translation".)
In this case, static files must be loaded beforehand, using loadjava
, as resource schema objects.
This is where you translate a .jsp
file on the client using ojspc
and load the generated components into Oracle9i.
In this case, static files do not have to be in the server at all. They only have to be accessible by ojspc
on the client during translation. (For application-relative static include
directives, see the discussion of the ojspc -appRoot
option under "Option Descriptions for ojspc".)
See the Oracle9i Servlet Engine Developer's Guide for information, or "WAR Deployment" for an overview.
Developers who are deploying their JSP pages to Oracle9i to run in the Oracle9i Servlet Engine can translate either in the server or on the client.
Deployment with server-side translation requires two steps:
loadjava
to load the JSP page source (.jsp
or .sqljsp
file) into Oracle9i as a resource schema object. (You must also load any required Java classes or other required JSP pages.)
publishjsp
command. This will automatically accomplish the following:
publishjsp -hotload
option).
This step also produces source schema objects, class schema objects, and resource schema objects for all generated .java
files (and .sqlj
files for .sqljsp
pages), .class
files, and resource files, respectively.
See "Deployment to Oracle9i with Server-Side Translation" for more information.
Deployment with client-side translation requires three, or optionally four, steps:
ojspc
. This accomplishes the following:
ojspc
first produces a SQLJ source file then invokes the SQLJ translator to produce Java code.)
ojspc -extres
and -hotload
options.
loadjava
utility to load the class files and any resource files into Oracle9i as class schema objects and resource schema objects.
ojspc -hotload
option during translation) by using the Oracle9i session shell java
command to execute the main()
method of the page implementation class.
publishservlet
command to publish the page implementation classes for execution in Oracle9i.
See "Deployment to Oracle9i with Client-Side Translation" for more information.
Note: Another possible scenario is to use Oracle WAR deployment. See the Oracle9i Servlet Engine Developer's Guide for information, or "WAR Deployment" for an overview. |
If you are using Oracle JDeveloper, you may find it more convenient to translate on the client using the OracleJSP translator provided with JDeveloper and then deploy the resulting classes and resources, as in steps 2, 3, and 4.
If you are not using JDeveloper, however, translating in the server is likely to be more convenient, because the session shell publishjsp
command combines translation, optional hotloading, and publishing into a single step.
In addition, either of the following situations may dictate the need to translate in the server:
Oracle9i offers a feature known as hotloading classes for more efficient use of static final
variables (constants). This becomes relevant whenever the hotloaded classes might be used by multiple concurrent users.
A separate JVM is invoked for each Oracle9i session created in Java. Normally each session gets its own copy of all static final
variables in its session space or, in the case of literal strings, in a hashtable known as the intern table in shared memory. Use of literal strings in the intern table is synchronized across sessions.
The processing of literal strings is especially relevant to JSP pages. By default (without hotloading), the static text in a JSP page is ultimately represented as literal strings.
Note:
This section refers to the OracleJSP pre-translation tool ( |
The ability to hotload a JSP page is enabled during translation, through the ojspc
-hotload
option (for client-side translation) or the publishjsp
-hotload
option (for server-side translation).
Enabling the -hotload
option directs the OracleJSP translator to do the following:
main()
method that invokes the hotloading method.
The hotloading itself is accomplished as follows:
ojspc -hotload
option enabled and loading the page class and static resources into Oracle9i, and before invoking publishservlet
to publish the page, you must use the session shell java
command to invoke the main()
method of the page implementation class. Details of the process are discussed in "Deployment to Oracle9i with Client-Side Translation".
publishjsp
functionality when you enable the publishjsp -hotload
option.
The act of hotloading a page implementation class, either directly through the session shell java
command or indirectly through the publishjsp
command, actually just makes the inner class static text shareable among multiple JVMs in Oracle9i.
Hotloading classes results in the following logistical features and advantages:
char
arrays representing static text.
char
arrays only once.
These char
arrays, instead of being stored in the synchronized intern table, are stored elsewhere in a global area that is shared across all sessions without synchronization (which is feasible because of the knowledge that none of the variables will change).
Hotloading, by avoiding synchronization and other costly overhead, can significantly improve the runtime performance and scalability of JSP pages executed in the Oracle9i Servlet Engine. Furthermore, when a hotloaded class is referenced, the class initializer is not rerun. The session has instant access to the literal strings and other static final
variables.
In addition to allowing better performance of individual JSP pages, hotloading reduces overall CPU usage of the server.
Oracle provides the following tools to use, as applicable, in translating JSP pages and deploying them to Oracle9i. How they are implemented depends on your operating system (such as shell scripts for Solaris or .bat
files for Windows NT):
ojspc
(OracleJSP pre-translation tool)
loadjava
(tool for loading JSP pages or Java files into the Oracle9i database or database cache)
sess_sh
(Oracle9i session shell tool)
Deployment with client-side translation requires all three tools. Pre-translate JSP pages on the client using ojspc
, load the translated pages into Oracle9i using loadjava
, and publish them using the session shell publishservlet
command.
Deployment with server-side translation does not require ojspc
. Load the untranslated JSP pages into Oracle9i using loadjava
, then translate and publish them using the session shell publishjsp
command.
The loadjava
and sess_sh
tools are general-purpose tools for the Oracle9i Java environment; ojspc
is for JSP pages only.
Notes:
|
The first step in deploying a JSP application to Oracle9i with client-side translation is to run the OracleJSP pre-translation tool, ojspc
.
You will then use loadjava
, introduced in the next section, to load the resulting .class
files and resource files (if any) into Oracle9i as class schema objects and resource schema objects, respectively.
The following topics are covered here:
There are other possible scenarios, such as in a middle-tier environment, for using
Notes:
ojspc
to pre-translate JSP pages. See "Use of ojspc for Pre-Translation for Non-OSE Environments".
For a simple JSP (not SQLJ JSP) page, default functionality for ojspc
is as follows:
.jsp
file as an argument.
.jsp
file into Java page implementation class code, producing a .java
file. The page implementation class includes an inner class for static page content.
.java
file, producing two .class
files (one for the page implementation class itself and one for the inner class).
And following is the default ojspc
functionality for a SQLJ JSP page:
.sqljsp
file as an argument instead of a .jsp
file.
.sqljsp
file into a .sqlj
file for the page implementation class (and inner class).
.sqlj
file. This produces a .java
file for the page implementation class (and inner class) and a SQLJ "profile" file that is, by default, a .ser
Java resource file.
For information about SQLJ profiles and Oracle-specific code generation, see the Oracle9i SQLJ Developer's Guide and Reference.
.java
file, producing two .class
files (one for the page implementation class itself and one for the inner class).
Under some circumstances (see the -hotload
and -extres
option descriptions below), ojspc
options direct the OracleJSP translator to produce a .res
Java resource file for static page content instead of putting this content into the inner class of the page implementation class. However, the inner class is still created and must still be deployed with the page implementation class.
Because ojspc
invokes the OracleJSP translator, ojspc
output conventions are the same as for OracleJSP in general, as applicable. For general information about OracleJSP translator output, including generated code features, general conventions for output names, generated package and class names, and generated files and locations, see "Functionality of the OracleJSP Translator".
Table 6-1 describes the options supported by the ojspc
pre-translation utility. These options are further discussed in "Option Descriptions for ojspc".
The second column notes comparable or related OracleJSP configuration parameters for on-demand translation environments (such as Apache/JServ).
Following is the general ojspc
command-line syntax (assume %
is a UNIX prompt):
% ojspc [option_settings] file_list
The file list can include .jsp
files or .sqljsp
files.
Be aware of the following syntax notes:
.jsp
files are translated, they all must use the same character set (either by default or through page
directive contentType
settings).
-hotload
, not -hotload true
.)
Following is an example:
% ojspc -d /myapp/mybindir -srcdir /myapp/mysrcdir -hotload MyPage.sqljsp MyPage2.jsp
This section describes the ojspc
options in more detail.
(fully qualified path; ojspc
default: empty)
Use this option to specify additional classpath entries for javac
to use when compiling generated page implementation class source. Otherwise, javac
uses only the system classpath.
Notes:
|
(fully qualified path; ojspc
default: current directory)
Use this option to specify an application root directory. The default is the current directory, from which ojspc
was run.
The specified application root directory path is used as follows:
include
directives in the page being translated. The specified directory path is prepended to any application-relative (context-relative) paths in the include
directives of the translated page.
This option is necessary, for example, so included files can still be found if you run ojspc
from some other directory.
Consider the following example:
/abc/def/ghi/test.jsp
ojspc
from the current directory, /abc
, as follows (assume %
is a UNIX prompt):
% cd /abc % ojspc def/ghi/test.jsp
test.jsp
page has the following include
directive:
<%@ include file="/test2.jsp" %>
test2.jsp
page is in the /abc
directory, as follows:
/abc/test2.jsp
This requires no -appRoot
setting, because the default application root setting is the current directory, which is the /abc
directory. The include
directive uses the application-relative /test2.jsp
syntax (note the beginning "/"), so the included page will be found as /abc/test2.jsp
.
The package in this case is _def._ghi
, based simply on the location of test.jsp
relative to the current directory, from which ojspc
was run (the current directory is the default application root). Output files are placed accordingly.
If, however, you run ojspc
from some other directory, suppose /home/mydir
, then you would need an -appRoot
setting as in the following example:
% cd /home/mydir % ojspc -appRoot /abc /abc/def/ghi/test.jsp
The package is still _def._ghi
, based on the location of test.jsp
relative to the specified application root directory.
(fully qualified path; ojspc
default: current directory)
Use this option to specify a base directory for ojspc
placement of generated binary files--.class
files and Java resource files. (The .res
files produced for static content by the -extres
and -hotload
options are Java resource files, as are .ser
profile files produced by the SQLJ translator for SQLJ JSP pages.)
The specified path is taken simply as a file system path (not an application-relative or page-relative path).
Subdirectories under the specified directory are created automatically, as appropriate, depending on the package. See "Summary of ojspc Output Files, Locations, and Related Options" for more information.
The default is to use the current directory (your current directory when you executed ojspc
).
It is recommended that you use this option to place generated binary files into a clean directory so that you easily know what files have been produced.
Notes:
|
(boolean; ojspc
default: false
)
Enable this flag to instruct ojspc
to generate a line map to the original .jsp
file for debugging. Otherwise, line-mapping will be to the generated page implementation class.
This is useful for source-level JSP debugging, such as when using Oracle JDeveloper.
Note:
In an on-demand translation scenario, the OracleJSP |
(fully qualified Java class name; ojspc
default: empty)
Use this option to specify a Java class that the generated page implementation class will extend.
(boolean; ojspc
default: false
)
Enable this flag to instruct ojspc
to place generated static content (the Java print commands that output static HTML code) into a Java resource file instead of into an inner class of the generated page implementation class.
The resource file name is based on the JSP page name. For release 1.1.2.x it will be the same core name as the JSP name (unless special characters are included in the JSP name), but with an underscore ("_") prefix and .res
suffix. Translation of MyPage.jsp
, for example, would create _MyPage.res
in addition to normal output. The exact implementation for name generation may change in future releases, however.
The resource file is placed in the same directory as .class
files.
If there is a lot of static content in a page, this technique will speed translation and may speed execution of the page. For more information, see "Workarounds for Large Static Content in JSP Pages".
Notes:
|
(boolean; ojspc
default: false
) (for OSE only)
Enable this flag to allow hotloading. This is relevant only if you will be loading the translated pages into Oracle9i to run in the Oracle9i Servlet Engine.
The -hotload
flag directs ojspc
to do the following:
-extres
functionality, writing static output to a Java resource file (see the -extres
description above).
main()
method and a hotloading method in the generated page implementation class to allow hotloading.
For an overview of hotloading, see "Overview of Hotloaded Classes in Oracle9i". For how to accomplish the hotloading step (once hotloading has been enabled), see "Hotloading Page Implementation Classes in Oracle9i".
(fully qualified Java interface name; ojspc
default: empty)
Use this option to specify a Java interface that the generated page implementation class will implement.
(boolean; ojspc
default: false
)
Enable this flag to direct ojspc
not to compile the generated page implementation class Java source. This allows you to compile it later with an alternative Java compiler.
Notes:
|
(fully qualified package name; ojspc
default: per .jsp
file location)
Use this option to specify a package name for the generated page implementation class, using Java "dot" syntax.
Without setting this option, the package name is determined according to the location of the .jsp
file relative to the current directory (from which you ran ojspc
).
Consider an example where you run ojspc
from the /myapproot
directory, while the .jsp
file is in the /myapproot/src/jspsrc
directory (assume %
is a UNIX prompt):
% cd /myapproot % ojspc -packageName myroot.mypackage src/jspsrc/Foo.jsp
This results in myroot.mypackage
being used as the package name.
If this example did not use the -packageName
option, OracleJSP release 1.1.2.x would use _src._jspsrc
as the package name, by default. (Be aware that such implementation details are subject to change in future releases.)
(-S
followed by SQLJ option setting; ojspc
default: empty)
For SQLJ JSP pages, use the ojspc
-S
option to pass an Oracle SQLJ option to the SQLJ translator. You can use multiple occurrences of -S
, with one SQLJ option per occurrence.
Unlike when you run the SQLJ translator directly, use a space between a SQLJ option and its value (this is for consistency with other ojspc
options).
For example (from a UNIX prompt):
% ojspc -S-default-customizer mypkg.MyCust -d /myapproot/mybindir MyPage.jsp
This invokes the Oracle SQLJ -default-customizer
option to choose an alternative profile customizer, as well as setting the ojspc -d
option.
Here is another example:
% ojspc -S-ser2class true -S-status true -d /myapproot/mybindir MyPage.jsp
This enables the SQLJ -ser2class
option (to convert the profile to a .class
file) and the SQLJ -status
option (to display status information as the .sqlj
file is translated).
Note the following for particular Oracle SQLJ options:
-encoding
option; instead, use the contentType
parameter in a page
directive in the JSP page.
-classpath
option if you use the ojspc -addclasspath
option.
-compile
option if you use the ojspc -noCompile
option.
-d
option if you use the ojspc
-d
option.
-dir
option if you use the ojspc -srcdir
option.
For information about Oracle SQLJ translator options, see the Oracle9i SQLJ Developer's Guide and Reference.
Note:
In an on-demand translation scenario, the OracleJSP |
(fully qualified path; ojspc
default: current directory)
Use this option to specify a base directory location for ojspc
placement of generated source files--.sqlj
files (for SQLJ JSP pages) and .java
files.
The specified path is taken simply as a file system path (not an application-relative or page-relative path).
Subdirectories under the specified directory are created automatically, as appropriate, depending on the package. See "Summary of ojspc Output Files, Locations, and Related Options" for more information.
The default is to use the current directory (your current directory when you executed ojspc
).
It is recommended that you use this option to place generated source files into a clean directory so that you conveniently know what files have been produced.
Notes:
|
(boolean; ojspc
default: false
)
Enable this option to direct ojspc
to report its translation steps as it executes.
The following example shows -verbose
output for the translation of myerror.jsp
(in this example, ojspc
is run from the directory where myerror.jsp
is located; assume %
is a UNIX prompt):
% ojspc -verbose myerror.jsp Translating file: myerror.jsp 1 JSP files translated successfully. Compiling Java file: ./_myerror.java
(boolean; ojspc
default: false
)
Enable this option for ojspc
to display the OracleJSP version number and then exit.
By default, ojspc
generates the same set of files that are generated by the OracleJSP translator in an on-demand translation scenario and places them in or under the current directory (from which ojspc
was executed).
Here are the files:
.sqlj
source file (SQLJ JSP pages only)
.java
source file
.class
file for the page implementation class
.class
file for the inner class for static text
.ser
) or, optionally, a .class
file for the SQLJ profile (SQLJ JSP pages only)
This assumes standard SQLJ code generation. Oracle-specific SQLJ code generation produces no profiles.
.res
) for the static text of the page
For more information about files that are generated by the OracleJSP translator, see "Generated Files and Locations (On-Demand Translation)".
To summarize some of the commonly used options described under "Option Descriptions for ojspc", you can use the following ojspc
options to affect file generation and placement:
-appRoot
to specify an application root directory
-srcdir
to place source files in a specified alternative location
-d
to place binary files (.class
files and Java resource files) in a specified alternative location
-noCompile
to not compile the generated page implementation class source (as a result of this, no .class
files are produced)
In the case of SQLJ JSP pages, translated .java
files are still produced, but not compiled.
-extres
to put static text into a Java resource file
-hotload
to put static text into a Java resource file and to enable hotloading (relevant only for pages targeting the Oracle9i Servlet Engine)
-S-ser2class
(SQLJ -ser2class
option, for SQLJ JSP pages only) to generate the SQLJ profile in a .class
file instead of a .ser
Java resource file
For output file placement, the directory structure underneath the current directory (or directories specified by the -d
and -srcdir
options, as applicable) is based on the package. The package is based on the location of the file being translated relative to the application root, which is either the current directory or the directory specified in the -appRoot
option.
For example, presume you run ojspc
as follows (presume %
is a UNIX prompt):
% cd /abc % ojspc def/ghi/test.jsp
Then the package is _def._ghi
and output files will be placed in the directory /abc/_def/_ghi
, where the _def/_ghi
subdirectory structure is created as part of the process.
If you specify alternate output locations through the -d
and -srcdir
options, a _def/_ghi
subdirectory structure is created under the specified directories.
Now presume ojspc
is run from some other directory, as follows:
% cd /home/mydir % ojspc -appRoot /abc /abc/def/ghi/test.jsp
The package is still _def._ghi
, according to the location of test.jsp
relative to the specified application root. Output files will be placed in the directory /home/mydir/_def/_ghi
or in a _def/_ghi
subdirectory under locations specified through the -d
and -srcdir
options. In either case, the _def/_ghi
subdirectory structure is created as part of the process.
The loadjava
command-line tool is supplied with Oracle9i to create schema objects from Java files and load them into a specified Oracle9i schema.
For information beyond what is provided here, and for information about the associated dropjava
tool (for removing Java source, class, and resource schema objects from Oracle9i), see the Oracle9i Java Tools Reference.
Generally speaking (not for JSP applications in particular), a Java developer can compile Java source on the client and then load the resulting class files, or can load Java source and have it compiled in Oracle9i automatically by the server-side compiler. In the first case, only class schema objects are created. In the second case, both source schema objects and class schema objects are created. In either case, the developer can also load Java resource files, creating resource schema objects.
The loadjava
tool accepts source files, class files, resource files, JAR files, and ZIP files on the command line. Source files and class files cannot be loaded simultaneously, however. A JAR file, ZIP file, or loadjava
command line can contain source files or class files, but not both. (In either case, resource files can be included.)
A JAR or ZIP file is opened and processed, with each file within the JAR or ZIP file resulting in one or more schema objects.
For OracleJSP, use loadjava
as follows:
ojspc
, which, by default, also compiles the translated Java source. Then use loadjava
to load the resulting .class
files and any resource files (the ojspc -hotload
option, for example, produces a resource file), typically all bundled into a JAR file.
Alternatively, you can load the translated .java
file instead of the compiled .class
files. You can have the server-side compiler compile the .java
file as it is being loaded.
loadjava
to load untranslated .jsp
files, typically bundled into a JAR file, as resource schema objects. (They will be translated and published later, in the server, as a result of the session shell publishjsp
command.)
Following is the complete loadjava
option syntax. Brackets, {...}
, are not part of the syntax. They are used to surround two possible option formats that are followed by option input.
loadjava {-user | -u} user/password[@database] [options] file.java | file.class | file.jar | file.zip | file.sqlj | resourcefile [-debug] [-d | -definer] [{-e | -encoding} encoding_scheme] [-f | -force] [{-g | -grant} user [, user]...] [-o | -oci8] [ -order ] [-noverify] [-r | -resolve] [{-R | -resolver} "resolver_spec"] [{-S | -schema} schema] [ -stdout ] [-s | -synonym] [-t | -thin] [-v | -verbose]
Of particular significance are the -user
and -resolve
options (which can be abbreviated to -u
and -r
, respectively). Use the -user
option to specify the schema name and password. Use the -resolve
option to specify whether loadjava
is to compile (if applicable) and resolve external references in the classes you are loading, after all classes on the command line have been loaded.
If you are loading a .java
source file that you want compiled by the server-side compiler during loading, you must enable the -resolve
option.
Following is an example for a client-side translation scenario where the JSP page has already been translated and compiled using the ojspc
utility, producing file _HelloWorld.class
and another .class
file for the page implementation inner class (with a name that starts with "_HelloWorld"). Assume %
is a UNIX prompt:
% loadjava -u scott/tiger -r _HelloWorld*.class
Or you can bundle the files into a JAR file:
% loadjava -v -u scott/tiger -r HelloWorld.jar
The loadjava -v
(-verbose
) option, which provides detailed status reporting as loading progresses, is especially useful when you are loading a number of files or compiling in the server.
The following example is also for a client-side translation scenario (_HelloWorld.java
is the JSP translator output), but where you have elected to skip the compilation step on the client (using the ojspc -noCompile
option) and instead have the server-side compiler handle the compilation:
% loadjava -v -u scott/tiger -r _HelloWorld.java
The following example is for a server-side translation scenario:
% loadjava -u scott/tiger -r HelloWorld.jsp
The sess_sh
(session shell) tool is provided with Oracle9i as an interactive interface to the session namespace of an Oracle9i instance. You specify connection arguments when you start sess_sh
. It then presents you with its $
prompt to indicate that it is ready for commands.
The session shell tool has many commands you can run from the $
prompt, each of which may have its own set of options. For OracleJSP developers, the publishservlet
and unpublishservlet
commands (for deployment with client-side translation), publishjsp
and unpublishjsp
commands (for deployment with server-side translation), and createcontext
command (for creating OSE servlet contexts) are of primary interest.
Following are the key sess_sh
syntax elements for starting the tool:
sess_sh -user user -password password -service serviceURL
-user
parameter specifies the user name of the schema.
-password
parameter specifies the password for the specified user name.
-service
parameter specifies the URL of the database or database cache whose session namespace is to be "opened" by sess_sh
. The serviceURL
parameter should have one of the three following forms:
sess_iiop://
host:port:sid
jdbc:oracle:type:spec
http://host[:port]
Following are some general examples:
sess_iiop://localhost:2481:orcl
jdbc:oracle:thin:@myhost:1521:orcl
http://localhost:8000
Here is an example of a sess_sh
command line:
% sess_sh -user SCOTT -password TIGER -service jdbc:oracle:thin:@myhost:5521:orcl
After starting sess_sh
, you will see its command prompt:
$
In addition to publish object commands, such as publishservlet
and publishjsp
, the session shell tool offers shell commands that give the session namespace much of the "look and feel" of a UNIX file system as seen from one of the UNIX shells (such as the C shell). For example, the following sess_sh
command displays the published objects and publishing contexts in the /alpha/beta/gamma
publishing context (publishing contexts are nodes in the session namespace, analogous to directories in a file system):
$ ls /alpha/beta/gamma
As mentioned previously, key sess_sh
commands for OracleJSP developers include the following:
$ publishjsp ... $ unpublishjsp ... $ publishservlet ... $ unpublishservlet ... $ createcontext ...
For information about the publishservlet
and unpublishservlet
commands, see "Publishing Translated JSP Pages in Oracle9i (Session Shell publishservlet)". For information about the publishjsp
and unpublishjsp
commands, see "Translating and Publishing JSP Pages in Oracle9i (Session Shell publishjsp)".
Each session shell command has a -describe
option to describe its operation, a -help
option to summarize its syntax, and a -version
option to show its version number.
Note:
This document provides only abbreviated discussion of
Beyond what is presented here, for example, commands can be specified within quotes on the There are also top-level options to connect with plain IIOP instead of the default session IIOP, to specify a role, to connect to the database or database cache with SSL server authentication, and to use a service name instead of an SID in the URL.
For complete information about the |
This section describes the steps for deployment to Oracle9i with server-side translation.
The steps are as follows:
loadjava
to load untranslated JSP page or SQLJ JSP page source files into Oracle9i.
publishjsp
command to translate and publish the pages.
The publishjsp
step automatically handles translation, compilation, hotloading (if applicable), and publishing.
As the first step for deployment with server-side translation, use the Oracle loadjava
tool to load untranslated .jsp
or .sqljsp
files into Oracle9i 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 Oracle9i 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 Oracle9i 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 Oracle9i:
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 Oracle9i:
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 Oracle9i:
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
In the scenario of deployment with server-side translation, the translation (.jsp
or .sqljsp
to .java
), compilation (.java
to .class
), hotloading (if enabled), and publishing all occur as the result of executing the Oracle9i session shell publishjsp
command. See "Overview of the sess_sh Session Shell Tool" for how to start the session shell and connect to Oracle9i.
Run publishjsp
after you have loaded a .jsp
(or .sqljsp
) file into Oracle9i 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 |
Starting sess_sh
establishes a connection to Oracle9i. 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:
-context context [-schema schemaname] [-virtualpath path] [-servletName name] [-packageName name] [-hotload] [-stateless] [-verbose] [-extend class] [-implement interface] [-resolver resolver]
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 a required parameter, along with any relevant schema path
information.
In addition, you should always specify a -context
setting.
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.
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 Oracle9i Servlet Engine".
The following informative options are also available:
-showVersion
by itself to display the OracleJSP version number and exit.
-usage
by itself to display a publishjsp
option list and exit.
Following are the option descriptions:
-context
context
Use this option to specify a servlet context in the Oracle9i Servlet Engine. The context path of this servlet context becomes part of the URL used to invoke the page.
Any specified context should be under the appropriate Web domain, as follows:
/domain_name/contexts/context_name
(Where domain_name
represents the name of the particular domain.)
-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 based on 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 1.1.2.x (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 based on 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.
Also be aware that if no -servletName
setting is specified, the -packageName
setting is also reflected in the servlet name. Consider the following example:
$ publishjsp -packageName mytestpkg -verbose simple1_a.jsp
This results in the following servlet name:
mytestpkg._simple1__a.jsp
However, if a -servletName
setting is specified, its effect on the servlet name overrides the effect of the -packageName
setting.
-hotload
Enable this flag to enable and perform hotloading. This results in the following steps being performed automatically by the publishjsp
command:
main()
method and a hotloading method are implemented in the generated page implementation class to allow hotloading.
main()
method is executed to perform hotloading.
To use -hotload
, you must have permission for the Oracle9i 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 Oracle9i".
-stateless
This is a boolean option that tells the Oracle9i 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 Oracle9i Servlet Engine Developer's Guide.
-verbose
Set this option to true
to direct publishjsp
to report the translation steps as it executes.
-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.
-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))" ...
This section provides examples of using publishjsp
to translate and publish .jsp
pages in Oracle9i. 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 Oracle9i Servlet Engine".
These notes apply to the examples that follow:
SCOTT
schema. SCOTT
must either be the schema specified when starting sess_sh
, or accessible from the schema specified.
publishjsp
publishing step. Note that default package names and output schema object names have underscores in them, even though the original JSP resource schema object name and resulting servlet path do not have underscores. Again, this is secondary and does not impact the user.
jsp:include
and jsp:forward
statements inside Oracle9i 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).
$
is the sess_sh
prompt.
$ publishjsp -schema SCOTT dir1/Foo.jsp
This uses the default servlet context of the relevant OSE Web domain, so the context path is "/".
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. The following schema objects are created:
SCOTT:_dir1/_Foo
source schema object
SCOTT:_dir1/_Foo
class schema object
SCOTT:_dir1/_Foo$__jsp_StaticText
)
$ publishjsp -schema SCOTT -context /scottRoot/contexts/scottContext Foo.jsp
Presume scottContext
had been created as follows:
$ createcontext -virtualpath /ose /scottRoot scottContext
The publishjsp
command publishes the page to the scottContext
servlet context, which was created with /ose
specified as the context path.
The default servlet path is simply Foo.jsp
.
After this command, Foo.jsp
can be invoked as follows (assume port 8088 for the Web service):
http://host:8088/ose/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
SCOTT:_Foo$__jsp_StaticText
)
$ publishjsp -schema SCOTT -context /scottRoot/contexts/scottContext dir1/Foo.jsp
Presume scottContext
had been created as follows:
$ createcontext -virtualpath /ose /scottRoot scottContext
The publishjsp
command publishes the page to the scottContext
servlet context, which was created with /ose
specified as the context path.
The default servlet path is dir1/Foo.jsp
.
After this command, Foo.jsp
can be invoked as follows (assume port 8088 for the Web service):
http://host:8088/ose/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
_dir1
for the inner class for static text (with "Foo" in the name, such as SCOTT:_dir1/_Foo$__jsp_StaticText
)
$ publishjsp -schema SCOTT -hotload -packageName mypkg dir1/Foo.jsp
This performs hotloading, uses the default servlet context of the relevant OSE Web domain, 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
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)
This section provides an example of using publishjsp
to translate and publish a .sqljsp
page in Oracle9i. 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 Oracle9i Servlet Engine".
Be aware of the following for .sqljsp
pages:
.jsp
page, an additional schema object 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 and Oracle-specific code generation, see the Oracle9i SQLJ Developer's Guide and Reference.
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 Oracle9i JAVA$OPTIONS
table. These options can be set through the dbms_java.set_compiler_option()
stored procedure (using SQL*Plus, for example). Of these options, only the following is supported for JSP pages:
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 Oracle9i SQLJ Developer's Guide and Reference.
This section presents an example of publishjsp
usage for a .sqljsp
page ($
is the sess_sh
prompt). Be aware of the following:
SCOTT
schema. SCOTT
must either be the schema specified when starting sess_sh
, or accessible from the schema specified.
publishjsp
publishing step. Note that default package names and output schema object names have underscores in them, even though the original SQLJSP resource schema object name and resulting servlet path do not have underscores. Again, this is secondary and does not impact the user.
_Foo
instead of Foo
.
Here is the example:
$ 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, based on 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
_dir1
for the inner class for static text (with "Foo" in the name, such as SCOTT:_dir1/_Foo$__jsp_StaticText
)
_dir1
for the SQLJ profile, if applicable (with "Foo" in the name, such as SCOTT:_dir1/_Foo_SJProfile0.ser
)
The sess_sh
tool also has an unpublishjsp
command that removes a JSP page from the Oracle9i JNDI namespace. This does not, however, remove the page implementation class schema object from Oracle9i.
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
As an example, here is the command to unpublish the page that was published in Example 1:
$ unpublishjsp dir1/Foo.jsp
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
, remember the following:
publishjsp -context
option in publishing the page, use the unpublishjsp -context
option with the same setting when you unpublish the page.
publishjsp -servletName
or -packageName
option in publishing a page, you must use the unpublishjsp -servletName
option to specify the resulting servlet name when you unpublish the page. For information about how these publishjsp
options affect the servlet name, see the option descriptions in "Overview of publishjsp Syntax and Options".
This section describes the steps for deployment to Oracle9i with client-side translation.
The steps are as follows:
ojspc
to pre-translate JSP pages or SQLJ JSP pages on the client.
loadjava
to load files into Oracle9i--.class
files (or, optionally, .java
or .sqlj
files instead) and any Java resource files resulting from the page translation.
publishservlet
command to publish the pages.
For simplicity and convenience, deployment with server-side translation is generally recommended. See "Deployment to Oracle9i with Server-Side Translation".
Note:
To pre-translate JSP pages on a client (typically for pages that will run in the Oracle9i Servlet Engine), use the ojspc
command-line tool to invoke the OracleJSP translator.
For general information about ojspc
and description of its options, see "The ojspc Pre-Translation Tool".
The rest of this section covers the following topics:
The following example shows the simplest usage of ojspc
:
% ojspc Foo.jsp
With this invocation, the following files are produced:
By default, all output goes to the current directory, from which ojspc
was run.
The ojspc
tool also accepts .sqljsp
files for JSP pages that use SQLJ code, as follows:
% ojspc Foo.sqljsp
For .sqljsp
files, ojspc
automatically invokes the SQLJ translator as well as the JSP translator.
With this invocation, the following files are produced:
_Foo.sqlj
(produced from Foo.sqljsp
by the JSP translator)
_Foo.java
(produced from _Foo.sqlj
by the SQLJ translator)
_Foo.class
_Foo$__jsp_StaticText.class
for the inner class for static content
.ser
) or class file (.class
), depending on the setting of the SQLJ -ser2class
option, for the SQLJ "profile" (with "Foo" in the name)
For information about SQLJ profiles and Oracle-specific code generation, see the Oracle9i SQLJ Developer's Guide and Reference.
By default, all output goes to the current directory, from which ojspc
was run.
Use the ojspc -hotload
option to enable hotloading, which (among other things) results in static page content going into a Java resource file instead of into the inner class of the page implementation class.
The following example translates the page and directs the OracleJSP translator to enable hotloading:
% ojspc -hotload Foo.jsp
With this command, the translator will generate the following output:
_Foo.java
(as usual)
_Foo.class
(as usual)
_Foo.res
, a Java resource file to contain the static page content
_Foo$__jsp_StaticText.class
for the inner class, as usual, although the static content goes into Foo.res
instead of going into the inner class
Be aware that the ojspc -hotload
option merely enables hotloading; it does not actually hotload the page. Hotloading requires an additional deployment step, as described in "Hotloading Page Implementation Classes in Oracle9i".
For an overview of hotloading, see "Overview of Hotloaded Classes in Oracle9i".
The following ojspc
options, fully described in "Option Descriptions for ojspc", are especially useful:
-appRoot
--Set an application root directory if you do not want the default (the current directory, from which ojspc
was run).
-noCompile
--Enable this flag if you do not want to compile .java
or .sqlj
files during translation. You would do this, for example, if you want to load the translated page into Oracle9i as a .java
file and have compilation performed by the server-side compiler.
In the case of SQLJ JSP pages, translated .java
files are still produced, but not compiled.
-d
--Specify the directory where ojspc
will place the generated binary files (.class
files and Java resource files). This makes it easier to know what was generated, and therefore what needs to be loaded into Oracle9i.
-srcdir
--Specify the directory where ojspc
will place the generated .java
or .sqlj
source files. For example, this would be useful instead of -d
if you are enabling -noCompile
and will load your translated page into Oracle9i as .java
source.
-extres
--Direct the OracleJSP translator to put static content into a Java resource file instead of into the inner class of the page implementation class.
-hotload
--Direct the OracleJSP translator to put static content into a Java resource file instead of into the inner class of the page implementation class, and generate code in the page implementation class to enable hotloading.
-S
--For SQLJ JSP pages, use the -S
prefix to set an Oracle SQLJ option; ojspc
will pass the option setting to the Oracle SQLJ translator. (You can have multiple -S
settings in the ojspc
command line.)
The following examples show the use of key ojspc
options.
% ojspc -appRoot /myroot/pagesrc -d /myroot/bin -hotload /myroot/pagesrc/Foo.jsp
This example accomplishes the following:
include
directives in the translated page.
_Foo.res
for static content.
_Foo.java
into the current directory, by default. There is no package, because Foo.jsp
is directly under the specified application root directory.
_Foo.class
, _Foo.res
, and the .class
file for the inner class into the /myroot/bin
directory.
% ojspc -appRoot /myroot/pagesrc -srcdir /myroot/gensrc -noCompile -extres /myroot/pagesrc/Foo.jsp
This example accomplishes the following:
include
directives in the translated page.
_Foo.res
for static content (without enabling hotloading).
_Foo.java
into the /myroot/gensrc
directory. There is no package, because Foo.jsp
is directly under the specified application root directory.
_Foo.java
(no .class
files are produced).
_Foo.res
into the current directory, by default.
% ojspc -appRoot /myroot/pagesrc -d /myroot/bin -extres -S-ser2class true /myroot/pagesrc/Foo.sqljsp
This example accomplishes the following:
include
directives in the translated page.
_Foo.res
for static content (without enabling hotloading).
_Foo.sqlj
and _Foo.java
into the current directory, by default. There is no package, because Foo.jsp
is directly under the specified application root directory.
_Foo.class
, _Foo.res
, a .class
file for the inner class, and a .class
file for the SQLJ profile into the /myroot/bin
directory. (Without the SQLJ -ser2class
option setting, the profile would be generated in a .ser
Java resource file instead of a .class
file.)
As Example 3 shows, you can use an explicit
Note:
true
setting in enabling a SQLJ boolean option through the -S
option setting. This is in contrast to ojspc
boolean options, such as -extres
, which do not take an explicit true
setting.
After client-side pre-translation, use the Oracle loadjava
tool to load generated files into Oracle9i. You can use either of the following scenarios:
.class
files and Java resource files (if any).
ojspc -noCompile
option during translation, then load the translated .java
file and resource files (if any). The .java
file can be compiled by the Oracle9i server-side compiler during loading.
In either case, whenever you have multiple files it is recommended that you put the files into a JAR file for loading.
The loadjava
tool is provided with Oracle9i as a general-purpose tool for loading Java files into the database or database cache. For an overview, see "Overview of the loadjava Tool". For further information, see the Oracle9i Java Tools Reference.
Important: In the next two subsections, "Loading Class Files with loadjava" and "Loading Java or SQLJ Source Files with loadjava", be aware of the following important considerations.
|
Assume you translated a JSP page Foo.jsp
with the ojspc -extres
or -hotload
option enabled, producing the following files:
You can ignore _Foo.java
, but the binary files (.class
and .res
) must all be loaded into Oracle9i. Typically, you would put _Foo.class
, _Foo$__jsp_StaticText.class
, and _Foo.res
into a JAR file, suppose Foo.jar
, and load it as follows (assume %
is a UNIX prompt):
% loadjava -v -u scott/tiger -r Foo.jar
The -u
(-user
) option specifies the user name and password for the Oracle9i schema; the -r
(-resolve
) option resolves the classes as they are loaded. Optionally use the -v
(-verbose
) option for detailed status output.
Alternatively, you can load the files individually, as follows. (The syntax depends on your operating environment. In these examples, assume %
is a UNIX prompt.)
% loadjava -v -u scott/tiger -r _Foo*.class _Foo.res
or:
% loadjava -v -u scott/tiger -r _Foo*.*
All these examples result in the following schema objects being created in Oracle9i (you typically need to know only the name of the page implementation class schema object):
SCOTT:_Foo
page implementation class schema object
Or there may be an additional package designation, according to either the ojspc -packageName
option or the relative location of the .jsp
file to the current directory when you ran ojspc
. For example, a -packageName
setting of abc.def
results in that being the package of the _Foo
class, so there would be a SCOTT:abc/def/_Foo
class schema object.
SCOTT:abc/def/_Foo$__jsp_StaticText
class schema object
With the same package designation as the page implementation class.
SCOTT:abc/def/_Foo.res
resource schema object
With a package designation according to any path specification, either in a JAR file or on the loadjava
command line, when it was loaded.
For an overview of how loadjava
names the schema objects it produces, see "Database Schema Objects for Java".
Assume that you translated a JSP page, Foo.jsp
, with the ojspc -noCompile
and -extres
options enabled, producing the following files:
_Foo.java
(which you want to load into Oracle9i as source to be compiled by the server-side compiler)
_Foo.res
Typically, you would put _Foo.java
and _Foo.res
into a JAR file, suppose Foo.jar
, and load it as follows:
% loadjava -v -u scott/tiger -r Foo.jar
When you enable the loadjava -r
(-resolve
) option, this results in the source file being compiled automatically by the server-side compiler, producing class schema objects. The -u
(-user
) option specifies the user name and password for the Oracle9i schema. Optionally use the -v
(-verbose
) option for detailed status reporting.
Alternatively, you can load the files individually:
% loadjava -v -u scott/tiger -r _Foo.java _Foo.res
Or load them using a wildcard character:
% loadjava -v -u scott/tiger -r _Foo.*
All these examples result in the following schema objects being created in Oracle9i (you typically need to know only the name of the page implementation class schema object):
SCOTT:_Foo
source schema object
When you load a source file into Oracle9i with loadjava
, the source is stored separately as a source schema object, in addition to the class schema objects produced by the server-side compiler.
SCOTT:_Foo
page implementation class schema object
Or there may be an additional package designation for the _Foo
class and source schema objects, according either to the ojspc -packageName
option or the relative location of the .jsp
file to the current directory when you ran ojspc
. For example, a -packageName
setting of abc.def
results in that being the package of the _Foo
class, so you would have a SCOTT:abc/def/_Foo
class schema object.
SCOTT:_Foo$__jsp_StaticText
class schema object
With the same package designation as the page implementation class.
SCOTT:_Foo.res
resource schema object
With the same package designation as the page implementation class.
For an overview of how loadjava
names the schema objects it produces, see "Database Schema Objects for Java".
To optionally "hotload" translated JSP pages in Oracle9i, use the session shell java
command to invoke the main()
method of the page implementation class schema object. See "Overview of the sess_sh Session Shell Tool" for how to start the tool and connect to the database or database cache.
You are required to have previously enabled hotloading through the ojspc -hotload
option during translation. The -hotload
option results in a main()
method and hotloading method being implemented in the page implementation class. Invoking the main()
method calls the hotloading method and hotloads the page implementation class.
Here is an example ($
is the sess_sh
prompt):
$ java SCOTT:_Foo
Assuming _Foo
is a class that was translated with the -hotload
option enabled and was then loaded with loadjava
into the SCOTT
schema as in earlier examples, this session shell java
command will hotload the static text portion of the _Foo
page implementation class.
For an overview of hotloading, see "Overview of Hotloaded Classes in Oracle9i". For more information about the session shell java
command, see the Oracle9i Java Tools Reference.
To publish translated pages as part of the "deployment with client-side translation" scenario, use the session shell publishservlet
command. See "Overview of the sess_sh Session Shell Tool" for how to start the tool and connect to Oracle9i.
The publishservlet
command is for general use in publishing any servlet to run in OSE, but also applies to JSP page implementation classes (which are essentially servlets).
Note:
Servlets and JSP pages that are published with |
Starting sess_sh
establishes a connection to Oracle9i. Once you start sess_sh
, you can run the publishservlet
command from the session shell $
prompt.
The publishservlet
command uses the following general syntax:
$ publishservlet context servletName className -virtualpath path [-stateless] [-reuse] [-properties props]
When using publishservlet
, you must specify the following:
context
in the command line above)
This is required by publishservlet
. You can use the default servlet context of the relevant Web domain:
/domain_name/contexts/default
This results in a context path of "/".
If you specify some other servlet context, then the context path of that servlet context will be used.
For example, if you specify a servlet context, mycontext
, created as follows:
$ createcontext -virtualpath /ose /scottRoot scottContext
Then /ose
will be the context path for the published JSP page.
servletName
in the command line above)
This is required by publishservlet
to specify the name for the JSP page in the named_servlets
directory, but has no practical use for the JSP developer or user other than for unpublishing. It can be an arbitrary name.
className
in the command line above)
This is the name of the page implementation class schema object being published.
Use the -virtualpath
option. This is required for a JSP page, although it is optional for publishing servlets in general.
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 Oracle9i Servlet Engine".
In addition to the required parameters, you can specify any of the following options:
-stateless
This is a boolean option that tells the Oracle9i Servlet Engine that the JSP page is to be stateless--it should not have access to the HttpSession
object during execution.
-reuse
This is a boolean option to specify a new servlet path (referred to as the "virtual path") for a JSP page. If you enable it, then the specified servlet path will be linked to the specified servlet name in the JNDI namespace without publishservlet
going through the complete publishing process.
When you enable the -reuse
option, specify a new servlet path, the servlet context, and a previously published servlet name.
-properties
props
Use this option to specify properties to be passed to the JSP page as initialization parameters upon execution.
For more information about the publishservlet
command, see the Oracle9i Java Tools Reference.
The following example publishes a JSP page that has been loaded into Oracle9i ($
is the sess_sh
prompt):
$ publishservlet /scottRoot/contexts/default -virtualpath Foo.jsp FooServlet SCOTT:_Foo
For simplicity, the default servlet context (of the /scottRoot
domain) is specified, resulting in "/" as the context path.
Foo.jsp
will be the servlet path. (You can specify any name you want for the servlet path, but naming it according to the original source file name is a good convention.)
FooServlet
will be the servlet name in the OSE named_servlets
directory, but this name generally will not be used, except for unpublishing.
SCOTT:_Foo
is the page implementation class schema object being published.
After the above publishservlet
command, the end user would invoke the JSP page with a URL as follows:
http://host[:port]/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" />
The sess_sh
tool also has an unpublishservlet
command that removes a servlet or JSP page from the Oracle9i JNDI namespace. This does not, however, remove the servlet class schema object or page implementation class schema object from Oracle9i.
Specify the context, servlet path (referred to on the command line as the "virtual path"), and servlet name. Following is the general syntax to unpublish a JSP page:
$ unpublishservlet -virtualpath path context servletName
For example, to unpublish the page that was published in the previous section:
$ unpublishservlet -virtualpath Foo.jsp /scottRoot/contexts/default FooServlet
Most of this chapter focuses on translation and deployment when targeting the Oracle9i Servlet Engine, because running in Oracle9i is a special situation requiring special considerations and logistics.
This section covers a variety of additional deployment considerations and scenarios, mostly for situations where you are not targeting OSE.
The following topics are covered:
Both the Oracle9i Servlet Engine and the Oracle9i Application Server use the Oracle HTTP Server, essentially an Apache environment, as a Web server for HTTP requests. However, each environment uses its own doc root.
JSP pages and servlets running in the Oracle9i Servlet Engine, which are routed through the Apache mod_ose
module provided by Oracle, use the OSE doc root of the relevant servlet context. OSE doc root directories are in the file system, but are linked to the Oracle9i JNDI mechanism.
Remember that for JSP pages running in OSE, only static files are located in or under the doc root. JSP pages are in the database or database cache.
The doc root directory for an OSE servlet context is specified using the session shell createcontext
command -docroot
option when the servlet context is created. For the default servlet context of the OSE default Web service, admin
, the doc root is the [ORACLE_HOME]/jis/public_html
directory. (It is possible to have a null doc root, although this may lead to undesirable behavior because the default OSE installation uses the doc root for error mapping.)
JSP pages and servlets running in the Apache/JServ environment of the Oracle9i Application Server (release 1.0.x), which are routed through the Apache mod_jserv
module provided with JServ, use the Apache doc root. This doc root (typically htdocs
) is set in the DocumentRoot
command of the Apache httpd.conf
configuration file.
For JSP pages running in JServ, JSP pages as well as static files are located in or under the doc root.
If you are migrating between the Apache/JServ environment and the OSE environment, move or copy static files to the appropriate doc root.
Note:
For an overview of the role of the Oracle HTTP Server and its |
The Oracle ojspc
tool, described in detail in "The ojspc Pre-Translation Tool", is typically used for client-side JSP translation for deployment to Oracle9i. However, you can use ojspc
to pre-translate JSP pages in any environment, which may be useful in saving end users the translation overhead the first time a page is executed.
If you are pre-translating in some environment other than the target environment, specify the ojspc -d
option to set an appropriate base directory for placement of generated binary files.
As an example, consider an Apache/JServ environment with the following JSP source file:
htdocs/test/foo.jsp
A user would invoke this with the following URL:
http://host[:port]/test/foo.jsp
During on-demand translation at execution time, the OracleJSP translator would use a default base directory of htdocs/_pages
for placement of generated binary files. Therefore, if you pre-translate, you should set htdocs/_pages
as the base directory for binary output, such as in the following example (assume %
is a UNIX prompt):
% cd htdocs % ojspc -d _pages test/foo.jsp
The URL noted above specifies an application-relative path of test/foo.jsp
, so at execution time the OracleJSP container looks for the binary files in a _test
subdirectory under the default htdocs/_pages
directory. This subdirectory would be created automatically by ojspc
if it is run as in the above example. At execution time, the OracleJSP container would find the pre-translated binaries and would not have to perform translation, assuming that the source file was not altered after pre-translation. (By default, the page would be re-translated if the source file timestamp is later than the binary timestamp, assuming the source file is available and the bypass_source
configuration parameter is not enabled.)
In an on-demand translation environment, it is possible to specify JSP pre-translation only, without execution, by enabling the standard jsp_precompile
request parameter when invoking the JSP page from the end user's browser.
Following is an example:
http://host[:port]/foo.jsp?jsp_precompile
Refer to the Sun Microsystems JavaServer Pages Specification, Version 1.1, for more information.
If your JSP source is proprietary, you can avoid exposing the source by pre-translating JSP pages and deploying only the translated and compiled binary files. Pages that are pre-translated, either from previous execution in an on-demand translation scenario or by using ojspc
, can be deployed to any environment that supports the OracleJSP container. There are two aspects to this scenario:
.jsp
(or .sqljsp
) source is not available.
After JSP pages have been translated, archive the directory structure and contents that are under the binary output directory, then copy the directory structure and contents to the target environment, as appropriate. For example:
ojspc
, you should specify a binary output directory with the ojspc -d
option, then archive the directory structure under that specified directory.
htdocs/_pages
directory.
In the target environment, restore the archived directory structure under the appropriate directory, such as under the htdocs/_pages
directory in an Apache/JServ environment.
Set OracleJSP configuration parameters as follows to execute JSP pages when the .jsp
or .sqljsp
source is unavailable:
Without these settings, OracleJSP will always look for the .jsp
or .sqljsp
file to see if it has been modified more recently than the page implementation .class
file, and abort with a "file not found" error if it cannot find the .jsp
or .sqljsp
file.
With these parameters set appropriately, the end user can invoke a page with the same URL that would be used if the source file were in place. For an example, consider an Apache/JServ environment--if the binary files for foo.jsp
are in the htdocs/_pages/_test
directory, then the page can be invoked with the following URL without foo.jsp
being present:
http://host:[port]/test/foo.jsp
For how to set configuration parameters, see "OracleJSP Configuration Parameter Settings".
The Sun Microsystems JavaServer Pages Specification, Version 1.1 supports the packaging and deployment of Web applications, including JavaServer Pages, according to the Sun Microsystems Java Servlet Specification, Version 2.2.
In typical JSP 1.1 implementations, JSP pages can be deployed through the WAR (Web archive) mechanism. WAR files are created using the JAR utility. The JSP pages can be delivered in source form and are deployed along with any required support classes and static HTML files.
Oracle9i provides a WAR deployment implementation that adheres to the Sun Microsystems standard.
According to the servlet 2.2 specification, a Web application includes a deployment descriptor file--web.xml
--that contains information about the JSP pages and other components of the application. The web.xml
file must be included in the WAR file.
The servlet 2.2 specification also defines an XML DTD for web.xml
deployment descriptors and specifies exactly how a servlet container must deploy a Web application to conform to the deployment descriptor.
Through these logistics, a WAR file is the best way to ensure that a Web application is deployed into any standard servlet environment exactly as the developer intended.
Deployment configurations in the web.xml
deployment descriptor include mappings between servlet paths and the JSP pages and servlets that will be invoked. Many additional features can be specified in web.xml
as well, such as timeout values for sessions, mappings of file name extensions to MIME types, and mappings of error codes to JSP error pages.
To summarize, the WAR file includes the following:
web.xml
deployment descriptor
For more information about standard WAR deployment, see the Sun Microsystems Java Servlet Specification, Version 2.2.
Each vendor providing a WAR implementation typically includes the following:
web.xml
for standard features
This section provides an overview of the Oracle implementation of these features. For more information about Oracle WAR deployment, see the Oracle9i Servlet Engine Developer's Guide.
The web.xml
file is a vehicle for standard configuration instructions for a Web application and is portable to any standard runtime environment. However, web.xml
cannot provide all the information necessary to deploy an application to a particular servlet container, because each vendor extends standard functionality with their own set of features. The servlet 2.2 specification suggests that each vendor provide an additional descriptor file for configuration of features unique to that vendor's runtime environment.
Oracle specifies and supports such an additional descriptor, known as the Oracle auxiliary descriptor. Like the web.xml
deployment descriptor, the auxiliary descriptor is in XML format. Oracle provides a DTD to specify supported elements and attributes.
Oracle provides a tool that deploys a Web application to Oracle9i for execution in the Oracle9i Servlet Engine. The deployment tool requires that the application be packaged in a WAR file, and can be invoked in any of the following ways:
Oracle JDeveloper release 3.1 and higher includes a deployment option, "Web Application to Web Server", that was added specifically for JSP applications.
This option generates a deployment profile that specifies the following:
The developer can either deploy the application immediately upon creating the profile, or save the profile for later use.
|
Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|