A Web Module Administration

This appendix provides reference documentation of OC4J features for administering Web modules through Oracle Enterprise Manager 10g Application Server Control, covering the following topics:

• Application Server Control Console Top-Level Web Module Pages

• Application Server Control Web Module Configuration Pages

• Summary of Web Module MBeans and Administration

Application Server Control Console Top-Level Web Module Pages

The Application Server Control Console provides a Web-based user interface for deploying, configuring, and monitoring applications, as well as managing the OC4J instance and the Web services used by your applications. It is installed, preconfigured, and started automatically when you install the OC4J software (either in a standalone or Oracle Application Server environment), and is bound to whichever port the OC4J instance is using. In a standalone environment, the port is typically 8888. In an Oracle Application Server environment, the port is usually 7777.

For example, in a standalone OC4J environment, you can use port 8888 of the appropriate host to access the console:

http://host:1888

See the Application Server Control Console online help for detailed instructions on using this interface.

The console is organized into functional areas for applications, administration, performance, and Web services. You can manage Web modules through the applications area.

Web module configuration starts from the applicable Web Module Home page in the Application Server Control Console. This page has a General tab, a Performance tab, and an Administration tab.

The rest of this section covers the following topics:

• How to Get to a Web Module Home Page

• Summary of Top-Level Web Module Pages

How to Get to a Web Module Home Page

To get to a Web Module Home page from the OC4J Home page, select the Applications tab. From there, you can get to a Web Module Home page in one of two ways:

1. View applications, by selecting "Applications" in the View dropdown menu.

2. Select the application of interest.

3. In the resulting Application Home page, select the module of interest.

or:

1. View modules from all applications, by selecting "Modules" in the View dropdown menu.

2. Select the module of interest.

Summary of Top-Level Web Module Pages

From a Web Module Home page, you can access the following:

• General tab (the Web Module Home page itself): This lists the host, port, and context path for the Web module, as well as the module's active servlets and JSP pages. For each servlet and JSP page, the General tab page lists the following metrics:

  • Active Requests

  • Current Client Processing Time (average processing time for each request over the preceding five minutes)

  • Requests per Second

  • Requests Processed

  • Total Client Processing Time (since startup of the servlet or JSP page)

  (These metrics are not persistent if OC4J is restarted.)

• Performance tab: This page graphically displays the following metrics for servlets and JSP pages that have been executed.

  • Active Sessions: The number of sessions active at any given point, over the indicated period of time.

  • Active Requests: The number of requests active at any given point, over the indicated period of time.

  • Response and Load: The average request processing time over the preceding five minutes, together with the requests per second over the preceding five minutes, over the indicated period of time.

• Administration tab: From this page, you can view or edit certain Web module configuration properties, view the web.xml or orion-web.xml file, and view or edit various kinds of mappings that relate to the Web module. Specifically, you can reach the following pages:

  • Configuration Properties page

  • View Deployment Descriptor page

  • View Proprietary Deployment Descriptor page

  • Servlet Mappings page

  • Filter Mappings page

  • Resource Reference Mappings page

  • EJB Reference Mappings page

  • Environment Entry Mappings page

  See the next section, "Application Server Control Web Module Configuration Pages", for information about these pages.

For more information about the pages summarized in the preceding paragraphs, see the context-sensitive topics "Web Module Home Page", "Web Module Performance Page", and "Web Module Administration Page" in the Application Server Control online help. For more information about OC4J performance metrics, see the topic "Summary of the OC4J Performance Metrics" in the online help.

Application Server Control Web Module Configuration Pages

From the Web Module Administration page, you can select "Go to Task" for several viewing and editing functions related to Web module configuration. These are described in the following sections:

• Configuration Properties Page

• Deployment Descriptor Viewing Pages

• Servlet Mappings Page

• Filter Mappings Page

• Resource Reference Mappings Page

• EJB Reference Mappings Page

• Environment Entry Mappings Page

• Resource Reference Lookup Context Page

Notes: For orion-web.xml properties you can view or edit in these pages, corresponding elements and attributes are described under "Elements and Attributes of orion-web.xml, global-web-application.xml". Where properties are documented as being under the <web-app> element, existing values may be coming from either the web.xml file or the orion-web.xml file. The <web-app> element is the root element of web.xml, with the schema being defined in the servlet specification. This definition is also imported into the orion-web.xml schema definition. Settings under the <web-app> element in orion-web.xml effectively override any of the same settings under the <web-app> element in web.xml. Changes made to any of these properties through the Application Server Control Console are persisted to the orion-web.xml file.

Configuration Properties Page

Table A-1 discusses the Web module properties you can configure through the Configuration Properties page of the Application Server Control Console. This page is accessible from the Web Module Administration page. For additional information about the properties, see the appropriate elements under "Elements and Attributes of orion-web.xml, global-web-application.xml".

The Configuration Properties page also displays the Web module name and application name.

Also see the context-sensitive topic "Web Module Configuration Properties Page" in the Application Server Control online help.

Table A-1 Properties of the Configuration Properties Page

Application Server Control Property	Corresponding XML Entity	Description
Display Name	<display-name> element under <web-app>	A short name for the Web module, for display by tools. Note: This is read-only through Application Server Control
Description	<description> element under <web-app>	An optional description of the Web module. Note: This is read-only through Application Server Control
Distributable	<distributable> element under <web-app>	Indicates whether the application is distributable, as described in the servlet specification. This property is not editable through this page. Note: This is read-only through Application Server Control
Classpath	<classpath> subelement of <orion-web-app>	Informs OC4J of additional code locations for Web application class loading—either library files or locations for individual class files.
Persistence Path	persistence-path attribute of <orion-web-app>	Indicates where to store servlet HttpSession objects for persistence across server restarts or application redeployments. Specify a relative path, which will be relative to an OC4J temporary storage area under application-deployments directory. If no value is specified, then there is no persistence of session objects across restarts or redeployments. Note: This attribute is ignored if OC4J clustering is enabled.
Temporary Directory	temporary-directory attribute of <orion-web-app>	This is the path to a temporary directory that can be used by servlets and JSP pages for scratch files. The path can be either absolute, or relative to the deployment directory.
File Modification Check Interval	file-modification-check-interval attribute of <orion-web-app>	This attribute, in milliseconds, determines when to check a static file, such as an HTML file, to see whether its timestamp has changed and it should therefore be reloaded from the file system. The default is "1000". For performance reasons, a very large value ("1000000", for example) is recommended in a production environment.
Session Timeout	<session-timeout> subelement of <session-config> element under <web-app>	Defines the default session timeout for all sessions created in the Web application, in minutes. For a value of 0 or less, there is no timeout.
Default Buffer Size	default-buffer-size attribute of <orion-web-app>	Specifies the default size of the output buffer for servlet responses, in bytes. Without specifying, the default is "2048".
Allow Directory Browsing	directory-browsing attribute of <orion-web-app>	Specifies whether to allow directory browsing for a URL that ends in "/". Supported values are "allow" and "deny" (default). See "<orion-web-app>" for additional information about directory browsing.

Deployment Descriptor Viewing Pages

You can view, but not edit, the application web.xml file and orion-web.xml file through the View Deployment Descriptor page and View Proprietary Deployment Descriptor page, respectively, of the Application Server Control Console.

Servlet Mappings Page

In the Servlet Mappings page of the Application Server Control Console, you can view, but not edit, mappings between servlet names and URL patterns. These mappings are described in Table A-2.

Also see the context-sensitive topic "Web Module Servlet Mappings Page" in the Application Server Control online help.

Table A-2 Properties of the Servlet Mappings Page

Application Server Control Property	Corresponding XML Entity	Description
Servlet Name	<servlet-name> subelement of <servlet-mapping> element under <web-app>	A reference to the desired name of the servlet, as defined in the <servlet-name> subelement of a corresponding <servlet> element under <web-app>.
URL Pattern	<url-pattern> subelement of <servlet-mapping> element under <web-app>	The desired URL pattern (servlet path) for the servlet, to map to the corresponding servlet name. The URL to invoke the servlet includes this pattern.

Filter Mappings Page

Table A-3 discusses the properties you can configure for servlet filters, through the Filter Mappings page.

Also see the context-sensitive topic "Web Module Filter Mappings Page" in the Application Server Control online help.

Table A-3 Configurable Properties of the Filter Mappings Page

Application Server Control Property	Corresponding XML Entity	Description
Filter Name	<filter-name> subelement of <filter-mapping> element under <web-app>	A reference to the desired name of the filter, as defined in the <filter-name> subelement of a corresponding <filter> element under <web-app>.
URL Pattern or Servlet Name	<url-pattern> or <servlet-name> subelement of <filter-mapping> element under <web-app>	This is to map either a URL pattern or a servlet name (not both) to the corresponding filter name.
Apply to Forwards	<dispatcher> subelement of <filter-mapping> element under <web-app>, with value of FORWARD	Use this for the filter to be applied to any "forward" targets matching the servlet name or URL pattern.
Apply to Requests	<dispatcher> subelement of <filter-mapping> element under <web-app>, with value of REQUEST	Use this in addition to an "Apply to Forwards" or "Apply to Includes" setting for the filter to also be applied to direct request targets matching the servlet name or URL pattern.
Apply to Includes	<dispatcher> subelement of <filter-mapping> element under <web-app>, with value of INCLUDE	Use this for the filter to be applied to any "include" targets matching the servlet name or URL pattern.
Apply to Errors	<dispatcher> subelement of <filter-mapping> element under <web-app>, with value of ERROR	Use this for the filter to be applied under the error page mechanism.

Table A-4 discusses addition servlet filter properties that are displayed for reference in the Filter Mappings page.

Table A-4 Reference Properties of the Filter Mappings Page

Application Server Control Property	Corresponding XML Entity	Description
Name	<filter-name> subelement of <filter> element under <web-app>	The desired name of the filter.
Class	<filter-class> subelement of <filter> element under <web-app>	The fully qualified name of the class containing the filter code.
Description	<description> subelement of <filter> element under <web-app>	An optional description of the filter.

Note: See Chapter 5, "Understanding and Using Servlet Filters", for related information.

Resource Reference Mappings Page

Use the Resource Reference Mappings page to specify a JNDI location for a resource such as a data source, JMS queue, or mail session. Table A-5 shows properties you can configure in this page.

Also see the context-sensitive topic "Web Module Resource Reference Mappings" in the Application Server Control online help.

From the Resource Reference Mappings page, you can also edit a JNDI lookup context, taking you to the Resource Reference Lookup Context page, described in "Resource Reference Lookup Context Page".

Table A-5 Properties of the Resource Reference Mappings Page

Application Server Control Property	Corresponding XML Entity	Description
Name	name attribute of <resource-ref-mapping> subelement of <orion-web-app>	The name of the resource, which refers to the value of a <res-ref-name> subelement of <resource-ref> under <web-app>. More specifically, this is the name of a resource manager connection factory reference.
Type	<res-type> subelement of <resource-ref> element under <web-app>	The type of the data source or other resource. This is the fully qualified Java type that is implemented by the resource.
Authorization	<res-auth> subelement of <resource-ref> element under <web-app>	Indicates whether sign-on to the resource manager is programmatic in the application component (Authorization value is Application) or is managed by the OC4J container (Authorization value is Container).
JNDI Location	location attribute of <resource-ref-mapping> element under <orion-web-app>	The desired JNDI location from which to look up the resource.
Lookup Context	location attribute of <lookup-context> subelement of <resource-ref-mapping> element under <orion-web-app>	Specifies an optional JNDI context that will be used instead of the default context in looking up the resource.

EJB Reference Mappings Page

Use the EJB Reference Mappings page to specify a JNDI location for an EJB. Table A-6 discusses the properties in this page.

Also see the context-sensitive topic "Web Module EJB Reference Mappings Page" in the Application Server Control online help.

Table A-6 Properties of the EJB Reference Mappings Page

Application Server Control Property	Corresponding XML Entity	Description
Name	name attribute of <ejb-ref-mapping> subelement of <orion-web-app>	The name of the EJB, which refers to the value of an <ejb-ref-name> subelement of <ejb-ref> under <web-app>.
Type	<ejb-ref-type> subelement of <ejb-ref> element under <web-app>	The type of EJB, either Entity or Session.
Home Interface	<home> subelement of <ejb-ref> element under <web-app>	The fully qualified name of the home interface of the EJB.
Remote Interface	<remote> subelement of <ejb-ref> element under <web-app>	The fully qualified name of the remote interface of the EJB.
JNDI Location	location attribute of <ejb-ref-mapping> subelement of <orion-web-app>	The desired JNDI location from which to look up the EJB.

Note: See "Overview of Enterprise JavaBeans" for related information.

Environment Entry Mappings Page

Use the Environment Entry Mappings Page to set a new value for an environment entry. Table A-7 discusses the properties in this page.

Also see the context-sensitive topic "Web Module Environment Entry Mappings Page" in the Application Server Control online help.

Table A-7 Properties of the Environment Entry Mappings Page

Application Server Control Property	Corresponding XML Entity	Description
Name	name attribute of <env-entry-mapping> subelement of <orion-web-app>	The name of the environment entry, and refers to the value of the <env-entry-name> subelement of an <env-entry> element under <web-app>.
Type	<env-entry-type> subelement of <env-entry> element under <web-app>	The Java type of the environment entry.
Description	<description> subelement of <env-entry> element under <web-app>	An optional description of the environment entry.
Value	<env-entry-value> subelement of <env-entry> element under <web-app>	The assembled value of the environment entry (typically from the web.xml file).
Deployed Value	<env-entry-mapping> subelement of <orion-web-app>	The desired deployment value of the environment entry, to override the assembled value. The value of the <env-entry-mapping> element overrides the value of the <env-entry-value> element.

Resource Reference Lookup Context Page

This page is linked from the Resource Reference Mappings page, described in "Resource Reference Mappings Page", allowing you to specify a new context from which to look up a resource. You can also edit context attributes.

Also see the context-sensitive topic "Resource Reference Lookup Context Page" in the Application Server Control online help.

Table A-8 Properties of the Resource Reference Lookup Context Page

Application Server Control Property	Corresponding XML Entity	Description
Resource Reference Name	name attribute of <resource-ref-mapping> subelement of <orion-web-app>	The name of the resource, which refers to the value of a <res-ref-name> subelement of <resource-ref> under <web-app>. More specifically, this is the name of a resource manager connection factory reference.
Lookup Context Location	location attribute of <lookup-context> subelement of <resource-ref-mapping> element under <orion-web-app>	Specifies an optional JNDI context that will be used instead of the default context in looking up the resource.
Name (of context attribute)	name attribute of <context-attribute> subelement of <lookup-context>	The name of an attribute to send to a nondefault, such as third-party, JNDI context specified as the corresponding Lookup Context.
Value (of context attribute)	value attribute of <context-attribute> subelement of <lookup-context>	The desired value of the attribute.

Summary of Web Module MBeans and Administration

Standards-compliant MBeans play a role in OC4J runtime configuration. The following sections provide an overview:

• General Overview of OC4J MBean Administration

• Summary of OC4J Web Module MBeans

General Overview of OC4J MBean Administration

OC4J support for the JMX specification allows standard interfaces to be created for managing resources dynamically, including resources relating to resource adapters, in a J2EE environment. The OC4J implementation of JMX provides a JMX client, the System MBean Browser, that you can use to manage an OC4J instance through MBeans that are provided with OC4J.

An MBean is a Java object that represents a JMX manageable resource. Each manageable resource within OC4J, such as an application or a resource adapter, is managed through an instance of the appropriate MBean. Each MBean provided with OC4J exposes a management interface that is accessible through the System MBean Browser in the Application Server Control Console. You can set MBean attributes, execute operations to call methods on an MBean, subscribe to notifications of errors or specific events, and display execution statistics.

Note: This information is provided for reference, but key Web module configuration settings are exposed in a more user-friendly manner through other features of the Application Server Control Console, as discussed under "Application Server Control Web Module Configuration Pages".

To access the browser from the OC4J home page, select the Administration tab and then, under the list of tasks, go to the JMX task "System MBean Browser". From the browser, you can do the following:

• Select the MBean of interest in the left-hand frame.

• Use the Attributes tab in the right-hand frame to view or change attributes. An attribute that can be set has a field where you can type in a new value. Then apply the change.

• Use the Operations tab in the right-hand frame to invoke methods on the MBean. Select the operation of interest. In the Operation window, you can invoke it with specified parameter settings.

• Use the Notifications tab (where applicable) in the right-hand frame to subscribe to notifications. You can select each item for which you want notification, and then apply the changes.

• Use the Statistics tab (where applicable) in the right-hand frame to display execution statistics.

Be aware that MBeans and their attributes vary regarding when changes take effect. In the runtime model, changes take effect immediately. In the configuration model, some changes take effect when the resource is restarted, others when the application is restarted, and still others when OC4J is restarted. There is also variation in whether changes are persisted.

See the Oracle Containers for J2EE Configuration and Administration Guide for details. The System MBean Browser itself also provides information about the MBeans.

Summary of OC4J Web Module MBeans

OC4J exports a set of MBeans for each Web module, including the OC4J default Web application, to support administration during application runtime. Some OC4J MBeans are required in order to support the J2EE management specification, but may offer extended features. Other OC4J MBeans are Oracle extensions to the model.

Table A-9 summarizes the OC4J implementation of MBeans that relate to Web modules and are required of an application server according to JSR-77. These implementations are in the oracle.oc4j.admin.management.mbeans package.

Notes: MBeans are self-documenting in the System MBean Browser, providing some documentation of MBean attributes, operations, and notifications (as applicable). Most (if not all) MBean statistical properties are derived from DMS statistics. See "Oracle Application Server Dynamic Monitoring Service" for an introduction to DMS. Regarding the default Web application: OC4J is installed with a default configuration that includes a default J2EE application (also known as the global application). The default application is, by default, the parent of all other J2EE applications in OC4J, except Application Server Control Console. In a typical OC4J installation, the default application contains a default Web application. The name and root directory path of the default Web application are specified in the OC4J global application.xml file. In standalone OC4J, the default Web application is bound to a Web site through the default-web-site.xml file, and the default context path is "/".

Table A-9 Mandatory System MBeans for Web Modules

MBean	Description
Servlet	Manages an instance of a servlet, with properties corresponding to a <servlet> element in the web.xml file.
WebModule	Manages standard features of a Web module, with properties corresponding to the <web-app> element (outside of <servlet> subelements) in the web.xml file.

Table A-10 summarizes the OC4J MBean that relates to Web modules and is an Oracle extension. This MBean implementation is also in the oracle.oc4j.admin.management.mbeans package.

Table A-10 Additional System MBeans for Web Modules

MBean	Description
OC4JWebModule	Manages OC4J-specific features of a Web module, with properties corresponding to the <orion-web-app> element (outside of the <web-app> subelement) in the orion-web.xml file.

Notes Regarding OC4J Web Module MBeans

• WebModule attributes corresponding to the following <web-app> subelements are accessible through the Application Server Control Console: <context-param>, <servlet-mapping>, <filter-mapping>, <session-timeout>.

• OC4JWebModule attributes corresponding to the following <orion-web-app> attributes and subelements are accessible through the Application Server Control Console: file-modification-check-interval, directory-browsing, <classpath>, <resource-ref-mapping>, <env-entry-mapping>, <ejb-ref-mapping>.

• The following JSP-related <orion-web-app> attributes, being global in nature, do not apply to OC4JWebModule: jsp-cache-directory, jsp-cache-tlds, jsp-taglib-locations, jsp-print-null, jsp-timeout.