|Oracle® Fusion Middleware Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server
11g Release 1 (10.3.1)
Part Number E13712-01
The following sections describe how to configure Web application resources.
The resources that you use in a Web application are generally deployed externally to the Web application. JDBC DataSources can optionally be deployed within the scope of the Web application as part of an EAR file.
To use external resources in the Web application, you resolve the JNDI resource name that the application uses with the global JNDI resource name using the
weblogic.xml deployment descriptors. (The
web.xml file is located in the
WEB-INF directory of your Web application.) See Configuring Resources for more information.
You can also deploy JDBC DataSources as part of the Web application EAR file by configuring those resources in the weblogic-application.xml deployment descriptor. Resources deployed as part of the EAR file with scope defined as application are referred to as application-scoped resources. These resources remain private to the application, and application components can access the resource names by adding
<resource-ref> as explained in Configuring Resources.
When accessing resources such as a DataSource from a Web application through Java Naming and Directory Interface (JNDI), you can map the JNDI name you look up in your code to the actual JNDI name as bound in the global JNDI tree. This mapping is made using both the
weblogic.xml deployment descriptors and allows you to change these resources without changing your application code. You provide a name that is used in your Java code, the name of the resource as bound in the JNDI tree, and the Java type of the resource, and you indicate whether security for the resource is handled programmatically by the servlet or from the credentials associated with the HTTP request. You can also access JMS module resources, such as queues, topics, and connection factories. For more information see, "Configuring JMS Application Modules for Deployment" in Oracle Fusion Middleware Configuring and Managing JMS for Oracle WebLogic Server.
To configure resources:
Enter the resource name in the deployment descriptor as you use it in your code, the Java type, and the security authorization type.
Map the resource name to the JNDI name.
The following example illustrates how to use an external DataSource. It assumes that you have defined a data source called
accountDataSource. For more information, see "JDBC Data Sources " in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help.
Example 7-1 Using an External DataSource
javax.sql.DataSource ds = (javax.sql.DataSource) ctx.lookup ("myDataSource"); web.xml entries: <resource-ref> . . . <res-ref-name>myDataSource</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>CONTAINER</res-auth> . . . </resource-ref> weblogic.xml entries: <resource-description> <res-ref-name>myDataSource</res-ref-name> <jndi-name>accountDataSource</jndi-name> </resource-description>
Web applications can access EJBs that are deployed as part of a different application (a different EAR file) by using an external reference. The EJB being referenced exports a name to the global JNDI tree in its
weblogic-ejb-jar.xml deployment descriptor. An EJB reference in the Web application module can be linked to this global JNDI name by adding an
ejb-reference-description element to its
weblogic.xml deployment descriptor.
This procedure provides a level of indirection between the Web application and an EJB and is useful if you are using third-party EJBs or Web applications and cannot modify the code to directly call an EJB. In most situations, you can call the EJB directly without using this indirection. For more information, see Oracle Fusion Middleware Programming Enterprise JavaBeans for Oracle WebLogic Server.
To reference an external EJB for use in a Web application:
Enter the EJB reference name you use to look up the EJB in your code, the Java class name and the class name of the home and remote interfaces of the EJB in the
ejb-ref element of the J2EE standard deployment descriptor,
web.xml file is located in the
WEB-INF directory of your Web application.)
Map the reference name in the
ejb-reference-description element of the WebLogic-specific deployment descriptor,
weblogic.xml, to the JNDI name defined in the
If the Web application is part of an Enterprise Application Archive (EAR file), you can reference an EJB by the name used in the EAR with the
ejb-link element of the J2EE standard deployment descriptor,
ejb-ref element in the
web.xml deployment descriptor declares that either a servlet or JSP is going to be using a particular EJB. The
ejb-reference-description element in the
weblogic.xml deployment descriptor binds that reference to an EJB, which is advertised in the global JNDI tree.
ejb-reference-descriptor element indicates which
ejb-ref element it is resolving with the
ejb-ref-name element. That is, the
ejb-ref elements with the same
ejb-ref-name element go together.
With the addition of the
ejb-link syntax, the
ejb-reference-descriptor element is no longer required if the EJB being used is in the same application as the servlet or JSP that is using the EJB.
ejb-ref-name element serves two purposes in the
web.xml deployment descriptor:
It is the name that the user code (servlet or JSP) uses to look up the EJB. Therefore, if your
ejb-ref-name element is
ejb1, you would perform a JNDI name lookup for
ejb1 relative to
ejb-ref-name element is bound into the component environment (
java:comp/env) of the Web application containing the servlet or JSP.
ejb-ref-name element is
ejb1, the code in your servlet or JSP should look like:
Context ctx = new InitialContext(); ctx = (Context)ctx.lookup("java:comp/env"); Object o = ctx.lookup("ejb1"); Ejb1Home home = (Ejb1Home) PortableRemoteObject.narrow(o, Ejb1Home.class);
It links the
ejb-reference-descriptor elements together.
Within an application, WebLogic Server binds any EJBs referenced by other application components to the environments associated with those referencing components. These resources are accessed at runtime through a JNDI name lookup relative to
The following is an example of an application deployment descriptor (
application.xml) for an application containing an EJB and a Web application, also called an Enterprise Application. (For the sake of brevity, the XML header is not included in this example.)
Example 7-2 Example Deployment Descriptor
<application> <display-name>MyApp</display-name> <module> <web> <web-uri>myapp.war</web-uri> <context-root>myapp</context-root> </web> </module> <module> <ejb>ejb1.jar</ejb> </module> </application>
To allow the code in the Web application to use an EJB in
ejb1.jar, the J2EE standard Web application deployment descriptor,
web.xml, must include an
ejb-ref stanza that contains an
ejb-link referencing the JAR file and the name of the EJB that is being called.
The format of the
ejb-link entry must be as follows:
filename is the name of the JAR file, relative to the Web application, and
ejbname is the EJB within that JAR file. The
ejb-link element should look like the following:
Note that since the JAR path is relative to the WAR file, it begins with "
../". Also, if the
ejbname is unique across the application, the JAR path may be dropped. As a result, your entry may look like the following:
ejb-link element is a sub-element of an
ejb-ref element contained in the Web application's
web.xml descriptor. The
ejb-ref element should look like the following:
Example 7-3 <ejb-ref> Element
<web-app> ... <ejb-ref> <ejb-ref-name>ejb1</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <home>mypackage.ejb1.MyHome</home> <remote>mypackage.ejb1.MyRemote</remote> <ejb-link>../ejb1.jar#myejb</ejb-link> </ejb-ref> ... </web-app>
Referring to the syntax for the
ejb-link element in the above example,
the portion of the syntax to the left of the
# is a relative path to the EJB module being referenced. The syntax to the right of
# is the particular EJB being referenced in that module. In the above example, the EJB JAR and WAR files are at the same level.
The name referenced in the
ejb-link (in this example,
myejb) corresponds to the
ejb-name element of the referenced EJB's descriptor. As a result, the deployment descriptor (
ejb-jar.xml) of the EJB module that this
ejb-ref element is referencing should have an entry similar to the following:
Example 7-4 <ejb-jar> Element
<ejb-jar> ... <enterprise-beans> <session> <ejb-name>myejb</ejb-name> <home>mypackage.ejb1.MyHome</home> <remote>mypackage.ejb1.MyRemote</remote> <ejb-class>mypackage.ejb1.MyBean</ejb-class> <session-type>Stateless</session-type> <transaction-type>Container</transaction-type> </session> </enterprise-beans> ... </ejb-jar>
ejb-name element is set to
At runtime, the Web application code looks up the EJB's JNDI name relative to
java:/comp/env. The following is an example of the servlet code:
MyHome home = (MyHome)ctx.lookup("java:/comp/env/ejb1");
The name used in this example (ejb1) is the ejb-ref-name defined in the
ejb-ref element of the
web.xml segment above.
If you need to serve classes or other resources from the system
CLASSPATH, or from the
WEB-INF/classes directory of a Web application, you can use a special servlet called the
ClasspathServlet is useful for applications that use applets or RMI clients and require access to server-side classes. The
ClasspathServlet is implicitly registered and available from any application.
ClasspathServlet is always enabled by default. To disable it, set the
default = false).
ClasspathServlet returns the classes or resources from the system
CLASSPATH in the following order:
jar files under
To serve a resource from the
WEB-INF/classes directory of a Web application, call the resource with a URL such as:
In this case, the resource is located in the following directory, relative to the root of the Web application:
ClasspathServletserves any resource located in the system
CLASSPATH, do not place resources that should not be publicly available in the system
Note:WebLogic Server provides functionality to support your legacy Common Gateway Interface (CGI) scripts. For new projects, we suggest you use HTTP servlets or JavaServer Pages.
WebLogic Server supports all CGI scripts through an internal WebLogic servlet called the
CGIServlet. To use CGI, register the
CGIServlet in the Web application deployment descriptor. See Configuring How a Client Accesses a Web Application.
To configure CGI in WebLogic Server:
CGIServlet in your Web application by using the
servlet-mapping elements in the J2EE standard Web application deployment descriptor,
web.xml file is located in the
WEB-INF directory of your Web application.) The class name for the
weblogic.servlet.CGIServlet. You do not need to package this class in your Web application.
Register the following initialization attributes for the
CGIServlet by defining the following
cgiDir—The path to the directory containing your CGI scripts. You can specify multiple directories, separated by a "
;" (Windows) or a "
:" (UNIX). If you do not specify
cgiDir, the directory defaults to a directory named
cgi-bin under the Web application root.
useByteStream—By default, character streams are used to read the output of CGI scripts. When scripts produce binary data, the stream may become corrupted due to character encoding. Use the useByteStream parameter to keep the stream from becoming corrupted. Using this parameter for ascii output also improves performance.
extension mapping—Maps a file extension to the interpreter or executable that runs the script. If the script does not require an executable, this initialization attribute may be omitted.
param-name for extension mappings must begin with an asterisk followed by a dot, followed by the file extension, for example,
param-value contains the path to the interpreter or executable that runs the script. You can create multiple mappings by creating a separate
init-param element for each mapping.
Example 7-5 Example Web Application Deployment Descriptor Entries for Registering the CGIServlet
<servlet> <servlet-name>CGIServlet</servlet-name> <servlet-class>weblogic.servlet.CGIServlet</servlet-class> <init-param> <param-name>cgiDir</param-name> <param-value> /bea/wlserver6.0/config/mydomain/applications/myWebApp/cgi-bin </param-value> </init-param> <init-param> <param-name>*.pl</param-name> <param-value>/bin/perl.exe</param-value> </init-param> </servlet> ... <servlet-mapping> <servlet-name>CGIServlet</servlet-name> <url-pattern>/cgi-bin/*</url-pattern> </servlet-mapping>
The URL used to request a Perl script must follow the pattern:
host:port—Is the host name and port number of WebLogic Server.
myWebApp—is the name of your Web application.
url-pattern name mapped to the
myscript.pl—is the name of the Perl script that is located in the directory specified by the
cgiDir initialization attribute.
For a list of CGI Best Practices, see CGI Best Practices.