Professional Documents
Culture Documents
November 2011 This document describes building WebLogic Server e-commerce applications using the Java Platform, Enterprise Edition 5.
Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server, 11g Release 1 (10.3.6) E13706-06 Copyright 2007, 2011, Oracle and/or its affiliates. All rights reserved. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065. This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.
Contents
Preface ................................................................................................................................................................. xi
Documentation Accessibility ..................................................................................................................... Conventions ................................................................................................................................................. xi xi
Database System and JDBC Driver ................................................................................ 1-15 Web Browser ..................................................................................................................... 1-16 Third-Party Software........................................................................................................ 1-16
Overview of the Split Development Directory Environment .............................................. 3-1 Source and Build Directories.............................................................................................. 3-2 Deploying from a Split Development Directory ............................................................. 3-3 Split Development Directory Ant Tasks .......................................................................... 3-4 Using the Split Development Directory Structure: Main Steps ........................................... 3-4 Organizing Java EE Components in a Split Development Directory.................................. 3-5 Source Directory Overview ................................................................................................ 3-5 Enterprise Application Configuration .............................................................................. 3-8 Web Applications ................................................................................................................ 3-8 EJBs ........................................................................................................................................ 3-9 Important Notes Regarding EJB Descriptors................................................................ 3-10 Organizing Shared Classes in a Split Development Directory ......................................... 3-11 Shared Utility Classes ...................................................................................................... 3-11 Third-Party Libraries........................................................................................................ 3-11 Class Loading for Shared Classes................................................................................... 3-12
Generating a Basic build.xml File Using weblogic.BuildXMLGen................................... weblogic.BuildXMLGen Syntax ..................................................................................... Developing Multiple-EAR Projects Using the Split Development Directory ................. Organizing Libraries and Classes Shared by Multiple EARs..................................... Linking Multiple build.xml Files.................................................................................... Best Practices for Developing WebLogic Server Applications..........................................
Resolving Class References Between Modules and Applications .................................... About Resource Adapter Classes ................................................................................... Packaging Shared Utility Classes ................................................................................... Manifest Class-Path .......................................................................................................... Using the Classloader Analysis Tool (CAT) ........................................................................ Sharing Applications and Modules By Using Java EE Libraries ...................................... Adding JARs to the Domain /lib Directory ......................................................................
vii
10.6.2 10.6.3
Types of Application Version Life Cycle Events.......................................................... 10-6 Example of Production Deployment Sequence When Using Application Version Life Cycle Events 10-6
A.1.17 fast-swap ............................................................................................................................ A-28 A.2 weblogic-application.xml Schema......................................................................................... A-29 A.3 application.xml Schema .......................................................................................................... A-29
ix
Preface
This preface describes the document accessibility features and conventions used in this guideDeveloping Applications for Oracle WebLogic Server.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc. Access to Oracle Support Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.
Conventions
The following text conventions are used in this document:
Convention boldface italic monospace Meaning Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary. Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values. Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.
xi
xii
1
1
Section 1.1, "Document Scope and Audience" Section 1.2, "WebLogic Server and the Java EE Platform" Section 1.3, "Overview of Java EE Applications and Modules" Section 1.4, "Web Application Modules" Section 1.5, "Enterprise JavaBean Modules" Section 1.6, "Connector Modules" Section 1.7, "Enterprise Applications" Section 1.8, "WebLogic Web Services" Section 1.9, "JMS and JDBC Modules" Section 1.10, "WebLogic Diagnostic Framework Modules" Section 1.11, "XML Deployment Descriptors" Section 1.12, "Deployment Plans" Section 1.13, "Development Software"
1-1
x.html). Java EE is the standard platform for developing multi-tier Enterprise applications based on the Java programming language. The technologies that make up Java EE were developed collaboratively by Oracle and other software vendors. An important aspect of the Java EE programming model is the introduction of metadata annotations. Annotations simplify the application development process by allowing a developer to specify within the Java class itself how the application component behaves in the container, requests for dependency injection, and so on. Annotations are an alternative to deployment descriptors that were required by older versions of Enterprise applications (Java EE 1.4 and earlier). According to Oracle, "the focus in Java EE 5 is ease of development. With Java EE 5, there is less code to write much of the boilerplate code has been removed, defaults are used whenever possible, and annotations are used extensively to reduce the need for deployment descriptors."
EJB 3.0 makes it much easier to program an EJB, in particular by reducing the number of required programming artifacts and introducing a set of EJB-specific metadata annotations that make programming the bean file easier and more intuitive. Another goal of EJB 3.0 is to standardize the persistence framework and reduce the complexity of the entity bean programming model and object-relational (O/R) mapping model. WebLogic Server continues to support Version 2.1 of the EJB specification. Java EE 5 includes simplified Web Services support and the latest web services APIs, making it an ideal implementation platform for Service-Oriented Architectures (SOA). Constructing web applications is made easier with JavaServer Faces (JSF) technology and the JSP Standard Tag Library (JSTL). Java EE 5 supports rich thin-client technologies such as AJAX, for building applications for Web 2.0.
WebLogic Server Java EE applications are based on standardized, modular components. WebLogic Server provides a complete set of services for those modules and handles many details of application behavior automatically, without requiring programming. Java EE defines module behaviors and packaging in a generic, portable way, postponing run-time configuration until the module is actually deployed on an application server. Java EE includes deployment specifications for Web applications, EJB modules, Web Services, Enterprise applications, client applications, and connectors. Java EE does not specify how an application is deployed on the target serveronly how a standard module or application is packaged. For each module type, the specifications define the files required and their location in the directory structure. Java is platform independent, so you can edit and compile code on any platform, and test your applications on development WebLogic Servers running on other platforms. For example, it is common to develop WebLogic Server applications on a PC running Windows or Linux, regardless of the platform where the application is ultimately deployed. For more information, refer to the Java EE specification at: http://download.oracle.com/javaee/5/api/
Web application modulesHTML pages, servlets, JavaServer Pages, and related files. See Section 1.4, "Web Application Modules". Enterprise Java Beans (EJB) modulesentity beans, session beans, and message-driven beans. See Section 1.5, "Enterprise JavaBean Modules". Connector modulesresource adapters. See Section 1.6, "Connector Modules". Enterprise applicationsWeb application modules, EJB modules, resource adapters and Web Services packaged into an application. See Section 1.7, "Enterprise Applications". Web ServicesSee Section 1.8, "WebLogic Web Services".
JDBC and JMS modulesSee Section 1.9, "JMS and JDBC Modules". WebLogic Diagnostic FrameWork (WLDF) modulesSee Section 1.10, "WebLogic Diagnostic Framework Modules".
At least one servlet or JSP, along with any helper classes. Optionally, a web.xml deployment descriptor, a Java EE standard XML document that describes the contents of a WAR file. Optionally, a weblogic.xml deployment descriptor, an XML document containing WebLogic Server-specific elements for Web applications. A Web application can also include HTML and XML pages with supporting files such as images and multimedia files.
1.4.1 Servlets
Servlets are Java classes that execute in WebLogic Server, accept a request from a client, process it, and optionally return a response to the client. An HttpServlet is most often used to generate dynamic Web pages in response to Web browser requests.
Section 3.3, "Organizing Java EE Components in a Split Development Directory". Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server
1-3
Enterprise Applications
ejb-jar.xml deployment descriptor defines security roles for the beans, and transactional behaviors for the beans' methods. Additional deployment descriptors provide WebLogic-specific deployment information. A weblogic-cmp-rdbms-jar.xml deployment descriptor unique to container-managed entity beans maps a bean to tables in a database. The weblogic-ejb-jar.xml deployment descriptor supplies additional information specific to the WebLogic Server environment, such as JNDI bind names, clustering, and cache configuration.
1-5
For development purposes, Oracle recommends the WebLogic split development directory structure. Rather than having a single archived EAR file or an exploded EAR directory structure, the split development directory has two parallel directories that separate source files and output files. This directory structure is optimized for development on a single WebLogic Server instance. See Chapter 3, "Creating a Split Development Directory Environment." Oracle provides the wlpackage Ant task, which allows you to create an EAR without having to use the JAR utility; this is exclusively for the split development directory structure. See Section 5.2, "Packaging Applications Using wlpackage". For development purposes, Oracle further recommends that you package standalone Web applications and Enterprise JavaBeans (EJBs) as part of an Enterprise application, so that you can take advantage of the split development directory structure. See Section 3.3, "Organizing Java EE Components in a Split Development Directory". For production purposes, Oracle recommends the exploded (unarchived) directory format. This format enables you to update files without having to redeploy the application. To update an archived file, you must unarchive the file, update it, then rearchive and redeploy it. You can choose to package your application as a JAR archived file using the jar utility with an .ear extension. Archived files are easier to distribute and take up less space. An EAR file contains all of the JAR, WAR, and RAR module archive files for an application and an XML descriptor that describes the bundled modules. See Section 5.2, "Packaging Applications Using wlpackage".
The optional META-INF/application.xml deployment descriptor contains an element for each Web application, EJB, and connector module, as well as additional elements to describe security roles and application resources such as databases. If this descriptor is present the WebLogic deployer picks the list of modules from this descriptor. However if this descriptor is not present, the container guesses the modules from the annotations defined on the POJO (plain-old-Java-object) classes. See Appendix A, "Enterprise Application Deployment Descriptor Elements."
A Web Service implementation hosted by a server on the Web. WebLogic Web Services are hosted by WebLogic Server. A Web Service module may include either
Java classes or EJBs that implement the Web Service. Web Services are packaged either as Web application archives (WARs) or EJB modules (JARs), depending on the implementation.
A standard for transmitting data and Web Service invocation calls between the Web Service and the user of the Web Service. WebLogic Web Services use Simple Object Access Protocol (SOAP) 1.1 as the message format and HTTP as the connection protocol. A standard for describing the Web Service to clients so they can invoke it. WebLogic Web Services use Web Services Description Language (WSDL) 1.1, an XML-based specification, to describe themselves. A standard for clients to invoke Web servicesJAX-WS or JAX-RPC. See Getting Started With JAX-WS Web Services for Oracle WebLogic Server or Getting Started With JAX-RPC Web Services for Oracle WebLogic Server, respectively. A standard for finding and registering the Web Service (UDDI).
For more information about WebLogic Web Services and the standards that are supported, see Introducing WebLogic Web Services for Oracle WebLogic Server.
"Configuring JMS Application Modules for Deployment" "Configuring JDBC Application Modules for Deployment"
1-7
module is configured in an XML configuration file named weblogic-diagnostics.xml which is packaged with the application archive. For detailed instructions for configuring instrumentation for applications, see "Configuring Application-Scoped Instrumentation".
Then place the external diagnostic descriptor file under the URI. Using the example above, you would place the descriptor file under d:\plan\ META-INF.
can create the standard deployment descriptors in addition to, or instead of, the metadata annotations. Modules and applications have deployment descriptorsXML documentsthat describe the contents of the directory or JAR file. Deployment descriptors are text documents formatted with XML tags. The Java EE specifications define standard, portable deployment descriptors for Java EE modules and applications. Oracle defines additional WebLogic-specific deployment descriptors for deploying a module or application in the WebLogic Server environment. Table 11 lists the types of modules and applications and their Java EE-standard and WebLogic-specific deployment descriptors.
Note:
The XML schemas for the WebLogic deployment descriptors listed in the following table include elements from the http://xmlns.oracle.com/weblogic/weblogic-javaee/1.2/weblo gic-javaee.xsd schema, which describes common elements shared among all WebLogic-specific deployment descriptors. For the most current schema information, see the Oracle WebLogic Server Schema Home page at http://www.oracle.com/technology/weblogic/index.html.
Table 11
Java EE and WebLogic Deployment Descriptors Scope Java EE Deployment Descriptors web.xml See the Servlet 2.5 Schema at http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd. WebLogic weblogic.xml Schema: http://xmlns.oracle.com/weblogic/weblogic-web-app/1.3 /weblogic-web-app.xsd See "weblogic.xml Deployment Descriptor Elements" in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.
Java EE
WebLogic
weblogic-ejb-jar.xml Schema: http://xmlns.oracle.com/weblogic/weblogic-ejb-jar/1.2 /weblogic-ejb-jar.xsd weblogic-rdbms-jar.xml Schema: http://xmlns.oracle.com/weblogic/weblogic-rdbms-jar/1 .2/weblogic-rdbms-jar.xsd persistence-configuration.xml Schema: http://xmlns.oracle.com/weblogic/persistence-configur ation/1.0/persistence-configuration.xsd See Programming WebLogic Enterprise JavaBeans, Version 3.0 for Oracle WebLogic Server.
1-9
Table 11 (Cont.) Java EE and WebLogic Deployment Descriptors Module or Application Enterprise Bean 2.1 Scope Java EE Deployment Descriptors ejb-jar.xml See the EJB 2.1 Schema at http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd WebLogic weblogic-ejb-jar.xml Schema: http://xmlns.oracle.com/weblogic/weblogic-ejb-jar/1.2 /weblogic-ejb-jar.xsd See "The weblogic-ejb-jar.xml Deployment Descriptor" in Programming WebLogic Enterprise JavaBeans for Oracle WebLogic Server. weblogic-cmp-rdbms-jar.xml Schema: http://xmlns.oracle.com/weblogic/weblogic-rdbms-jar/1 .2/weblogic-rdbms-jar.xsd See "The weblogic-cmp-rdbms-jar.xml Deployment Descriptor" in Programming WebLogic Enterprise JavaBeans for Oracle WebLogic Server. Web Services Java EE webservices.xml See the Web Services 1.2 Schema at http://java.sun.com/xml/ns/javaee/javaee_web_ services_1_2.xsd. WebLogic weblogic-webservices.xml Schema: http://xmlns.oracle.com/weblogic/weblogic-webservices /1.1/weblogic-webservices.xsd weblogic-wsee-clientHandlerChain.xml Schema: http://xmlns.oracle.com/weblogic/weblogic-wsee-client HandlerChain/1.0/weblogic-wsee-clientHandlerChain.xsd weblogic-webservices-policy.xml Schema: http://xmlns.oracle.com/weblogic/webservice-policy-re f/1.1/webservice-policy-ref.xsd weblogic-wsee-standaloneclient.xml Schema: http://xmlns.oracle.com/weblogic/weblogic-wsee-standa loneclient/1.0/weblogic-wsee-standaloneclient.xsd See "WebLogic Web Service Deployment Descriptor Element Reference" in WebLogic Web Services Reference for Oracle WebLogic Server. Resource Adapter Java EE ra.xml See the Connector 1.5 Schema at http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd. WebLogic weblogic-ra.xml Schema: http://xmlns.oracle.com/weblogic/weblogic-connector/1 .2/weblogic-connector.xsd See "weblogic-ra.xml Schema" in Programming Resource Adapters for Oracle WebLogic Server.
Table 11 (Cont.) Java EE and WebLogic Deployment Descriptors Module or Application Enterprise Application Scope Java EE Deployment Descriptors application.xml See the Application 5 Schema at http://java.sun.com/xml/ns/javaee/application_5.xsd. WebLogic weblogic-application.xml Schema: http://xmlns.oracle.com/weblogic/weblogic-application /1.3/weblogic-application.xsd See Section A.1, "weblogic-application.xml Deployment Descriptor Elements". Client Application Java EE application-client.xml See the Application Client 5 Schema at http://java.sun.com/xml/ns/javaee/application-client_ 5.xsd. WebLogic application-client.xml Schema: http://xmlns.oracle.com/weblogic/weblogic-application -client/1.2/weblogic-application-client.xsd See "Developing a Java EE Application Client (Thin Client)" in Programming Stand-alone Clients for Oracle WebLogic Server. HTTP Pub/Sub Application WebLogic weblogic-pubsub.xml Schema: http://xmlns.oracle.com/weblogic/weblogic-pubsub/1.0/ weblogic-pubsub.xsd See "Using the HTTP Publish-Subscribe Server" in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server. JMS Module WebLogic FileName-jms.xml, where FileName can be anything you want. Schema: http://xmlns.oracle.com/weblogic/weblogic-jms/1.2/web logic-jms.xsd See "Configuring JMS Application Modules for Deployment" in Configuring and Managing JMS for Oracle WebLogic Server. JDBC Module WebLogic FileName-jdbc.xml, where FileName can be anything you want. Schema: http://xmlns.oracle.com/weblogic/jdbc-data-source/1.2 /jdbc-data-source.xsd See "Configuring JDBC Application Modules for Deployment" in Configuring and Managing JDBC for Oracle WebLogic Server. Deployment Plan WebLogic plan.xml Schema: http://xmlns.oracle.com/weblogic/deployment-plan/1.0/ deployment-plan.xsd See "Understanding WebLogic Server Deployment" in Deploying Applications to Oracle WebLogic Server. WLDF Module WebLogic weblogic-diagnostics.xml Schema: http://xmlns.oracle.com/weblogic/weblogic-diagnostics /1.0/weblogic-diagnostics.xsd See "Deploying WLDF Application Modules" in Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.
When you package a module or application, you create a directory to hold the deployment descriptorsWEB-INF or META-INFand then create the XML deployment descriptors in that directory.
1.11.2 EJBGen
EJBGen is an Enterprise JavaBeans 2.x code generator or command-line tool that uses Javadoc markup to generate EJB deployment descriptor files. You annotate your Bean class file with Javadoc tags and then use EJBGen to generate the Remote and Home classes and the deployment descriptor files for an EJB application, reducing to a single file you need to edit and maintain your EJB .java and descriptor files. See "EJBGen Reference" in Programming WebLogic Enterprise JavaBeans for Oracle WebLogic Server.
java weblogic.marathon.ddinit.EarInit automatically generates the deployment descriptors for Enterprise applications. java weblogic.marathon.ddinit.WebInit automatically generates the deployment descriptors for Web applications.
For an example of DDInit, assume that you have created a directory called c:\stage that contains the JSP files and other objects that make up a Web application but you have not yet created the web.xml and weblogic.xml deployment descriptors. To automatically generate them, execute the following command:
prompt> java weblogic.marathon.ddinit.WebInit c:\stage
The utility generates the web.xml and weblogic.xml deployment descriptors and places them in the WEB-INF directory, which DDInit will create if it does not already exist.
1.11.4 Upgrading Deployment Descriptors From Previous Releases of Java EE and WebLogic Server
So that your applications can take advantage of the features in the current Java EE specification and release of WebLogic Server, Oracle recommends that you always upgrade deployment descriptors when you migrate applications to a new release of WebLogic Server. To upgrade the deployment descriptors in your Java EE applications and modules, first use the weblogic.DDConverter tool to generate the upgraded descriptors into a temporary directory. Once you have inspected the upgraded deployment descriptors to ensure that they are correct, repackage your Java EE module archive or exploded directory with the new deployment descriptor files.
Deployment Plans
where archive_file_or_directory refers to the archive file (EAR, WAR, JAR, or RAR) or exploded directory of your Enterprise application, Web application, EJB, or resource adapter. The following table describes the weblogic.DDConverter command options.
Option -d <dir> -help -quiet -verbose Description Specifies the directory to which descriptors are written. Prints the standard usage message. Turns off output messages except error messages. Turns on additional output used for debugging.
The following example shows how to use the weblogic.DDConverter command to generate upgraded deployment descriptors for the my.ear Enterprise application into the subdirectory tempdir in the current directory:
prompt> java weblogic.DDConverter -d tempdir my.ear
weblogic.PlanGenerator creates a template deployment plan with null variables for selected categories of WebLogic Server deployment descriptors. This tool is recommended if you are beginning the export process and you want to create a template deployment plan with null variables for an entire class of deployment descriptors. The Administration Console updates or creates new deployment plans as necessary when you change configuration properties for an installed application. You can use the Administration Console to generate a new deployment plan or to add or override variables in an existing plan. The Administration Console provides greater flexibility than weblogic.PlanGenerator, because it allows
Development Software
you to interactively add or edit individual deployment descriptor properties in the plan, rather than export entire categories of descriptor properties. For complete and detailed information about creating and using deployment plans, see:
"Understanding WebLogic Server Deployment" "Exporting an Application for Deployment to New Environments" "Understanding WebLogic Server Deployment Plans"
The Apache Jakarta Web site publishes online documentation for only the most current version of Ant, which might be different from the version of Ant that is bundled with WebLogic Server. Use the following command, after setting your WebLogic environment, to determine the version of Ant bundled with WebLogic Server:
To view the documentation for a specific version of Ant, such as the version included with WebLogic Server, download the Ant zip file from http://archive.apache.org/dist/ant/binaries/ and extract the documentation. For more information on using Ant to compile your cross-platform scripts or using cross-platform scripts to create XML scripts that can be processed by Ant, refer to any of the WebLogic Server examples, such as WL_ HOME/samples/server/examples/src/examples/ejb20/basic/beanManage d/build.xml.
Development Software
Also refer to the following WebLogic Server documentation on building examples using Ant: WL_ HOME/samples/server/examples/src/examples/examples.html.
If you plan to use a different version of Ant, you can replace the appropriate JAR file in the WL_HOME\server\lib\ant directory with an updated version of the file (where WL_HOME refers to the main WebLogic installation directory, such as c:\Oracle\Middleware\wlserver_10.x) or add the new file to the front of your CLASSPATH.
If you want to set the heap size permanently, add or update the MEM_ARGS variable in the scripts that set your environment, start WebLogic Server, and so on, as shown in the following snippet from a Windows command script that starts a WebLogic Server instance:
set MEM_ARGS=-Xms32m -Xmx200m
See the scripts and commands in WL_HOME/server/bin for examples of using the MEM_ARGS variable.
Development Software
Check with the software vendor to verify software compatibility with your platform and WebLogic Server version.
2
2
Section 2.1, "Overview of Configuring and Starting Domains Using Ant Tasks" Section 2.2, "Starting Servers and Creating Domains Using the wlserver Ant Task" Section 2.3, "Configuring a WebLogic Server Domain Using the wlconfig Ant Task" Section 2.4, "Using the libclasspath Ant Task"
Compile your application using the wlcompile, wlappc, and Web Services Ant tasks. Create a new single-server domain and start the Administration Server using the wlserver Ant task. Configure the new domain with required application resources using the wlconfig Ant task. Deploy the application using the wldeploy Ant task. Automatically start a compiled client application to demonstrate or test product features.
The sections that follow describe how to use the configuration Ant tasks, wlserver and wlconfig.
2.2 Starting Servers and Creating Domains Using the wlserver Ant Task
The wlserver Ant task enables you to start, reboot, shutdown, or connect to a WebLogic Server instance. The server instance may already exist in a configured
Using Ant Tasks to Configure and Use a WebLogic Server Domain 2-1
Starting Servers and Creating Domains Using the wlserver Ant Task
WebLogic Server domain, or you can create a new single-server domain for development by using the generateconfig=true attribute. When you use the wlserver task in an Ant script, the task does not return control until the specified server is available and listening for connections. If you start up a server instance using wlserver, the server process automatically terminates after the Ant VM terminates. If you only connect to a currently-running server using the wlserver task, the server process keeps running after Ant completes. The wlserver WebLogic Server Ant task extends the standard java Ant task (org.apache.tools.ant.taskdefs.Java). This means that all the attributes of the java Ant task also apply to the wlserver Ant task. For example, you can use the output and error attributes to specify the name of the files to which output and standard errors of the wlserver Ant task is written, respectively. For full documentation about the attributes of the standard java Ant task, see Java on the Apache Ant site (http://ant.apache.org/manual/Tasks/java.html).
Set your environment. On Windows NT, execute the setWLSEnv.cmd command, located in the directory WL_HOME\server\bin, where WL_HOME is the top-level directory of your WebLogic Server installation. On UNIX, execute the setWLSEnv.sh command, located in the directoryWL_ HOME\server\bin, where WL_HOME is the top-level directory of your WebLogic Server installation.
Note:
The wlserver task is predefined in the version of Ant shipped with WebLogic Server. If you want to use the task with your own Ant installation, add the following task definition in your build file:
2.
Add a call to the wlserver task in the build script to start, shutdown, restart, or connect to a server. See Section 2.2.3, "wlserver Ant Task Reference" for information about wlserver attributes and default behavior. Execute the Ant task or tasks specified in the build.xml file by typing ant in the staging directory, optionally passing the command a target argument:
prompt> ant
3.
Use ant -verbose to obtain more detailed messages from the wlserver task.
Starting Servers and Creating Domains Using the wlserver Ant Task
This target connects to an existing, running server using the indicated connection parameters and username/password combination:
<target name="connect-server"> <wlserver host="127.0.0.1" port="7001" username="weblogic" password="weblogic" action="connect"/> </target>
This target starts a WebLogic Server instance configured in the config subdirectory:
<target name="start-server"> <wlserver dir="./config" host="127.0.0.1" port="7001" action="start"/> </target>
This target creates a new single-server domain in an empty directory, and starts the domain's server instance:
<target name="new-server"> <delete dir="./tmp"/> <mkdir dir="./tmp"/> <wlserver dir="./tmp" host="127.0.0.1" port="7001" generateConfig="true" username="weblogic" password="weblogic" action="start"/> </target>
Using Ant Tasks to Configure and Use a WebLogic Server Domain 2-3
Starting Servers and Creating Domains Using the wlserver Ant Task
Table 21 (Cont.) Attributes of the wlserver Ant Task Attribute username Description Data Type Required? No
String The username of an administrator account. If you omit both the username and password attributes, wlserver attempts to obtain the encrypted username and password values from the boot.properties file. See "Boot Identity Files" in the Managing Server Startup and Shutdown for Oracle WebLogic Server for more information on boot.properties. The password of an administrator account. If you omit both the String username and password attributes, wlserver attempts to obtain the encrypted username and password values from the boot.properties file. See "Boot Identity Files" in the Managing Server Startup and Shutdown for Oracle WebLogic Server for more information on boot.properties. The private key password for decrypting the SSL private key file. String The maximum time, in milliseconds, that wlserver waits for a server to boot. This also specifies the maximum amount of time to wait when connecting to a running server. The default value for this attribute is 0, which means the Ant task never times out. long
password
No
pkpassword timeout
No No
timeoutSeconds
The maximum time, in seconds, that wlserver waits for a server long to boot. This also specifies the maximum amount of time to wait when connecting to a running server. The default value for this attribute is 0, which means the Ant task never times out.
No
productionmodeenab Specifies whether a server instance boots in development mode led or in production mode. Development mode enables a WebLogic Server instance to automatically deploy and update applications that are in the domain_name/autodeploy directory (where domain_name is the name of a WebLogic Server domain). In other words, development mode lets you use auto-deploy. Production mode disables the auto-deployment feature. See "Deploying Applications and Modules" for more information. Valid values for this attribute are True and False. The default value is False (which means that by default a server instance boots in development mode.) Note: If you boot the server in production mode by setting this attribute to True, you must reboot the server to set the mode back to development mode. Or in other words, you cannot reset the mode on a running server using other administrative tools, such as the WebLogic Server Scripting Tool (WLST). host The DNS name or IP address on which the server instance is listening. The default value for this attribute is localhost. port The TCP port number on which the server instance is listening. The default value for this attribute is 7001. generateconfig Specifies whether or not wlserver creates a new domain for the specified server. Valid values for this attribute are true and false. The default value is false.
boolean
No
String
No
int
No
boolean
No
Starting Servers and Creating Domains Using the wlserver Ant Task
Table 21 (Cont.) Attributes of the wlserver Ant Task Attribute action Description Specifies the action wlserver performs: start, shutdown, reboot, or connect. The shutdown action can be used with the optional forceshutdown attribute perform a forced shutdown. The default value for this attribute is start. failonerror This is a global attribute used by WebLogic Server Ant tasks. It specifies whether the task should fail if it encounters an error during the build. Valid values for this attribute are true and false. The default value is false. forceshutdown This optional attribute is used in conjunction with the action="shutdown" attribute to perform a forced shutdown. For example: <wlserver host="${wls.host}" port="${port}" username="${wls.username}" password="${wls.password}" action="shutdown" forceshutdown="true"/> Valid values for this attribute are true and false. The default value is false. noExit (Optional) Leave the server process running after ant exits. Valid values are true or false. The default value is false, which means the server process will shut down when ant exits. Specifies the protocol that the wlserver Ant task uses to communicate with the WebLogic Server instance. Valid values are t3, t3s, http, https, and iiop. The default value is t3. forceImplicitUpgrade Specifies whether the wlserver Ant task, if run against an 8.1 (or previous) domain, should implicitly upgrade it. Valid values are true or false. The default value is false, which means that the Ant task does not implicitly upgrade the domain, but rather, will fail with an error indicating that the domain needs to be upgraded. For more information about upgrading domains, see Upgrade Guide for Oracle WebLogic Server. Boolean No. Boolean No Boolean No Boolean No Data Type String Required? No
protocol
String
No
Using Ant Tasks to Configure and Use a WebLogic Server Domain 2-5
Table 21 (Cont.) Attributes of the wlserver Ant Task Attribute configFile Description Specifies the configuration file for your domain. The value of this attribute must be a valid XML file that conforms to the XML schema as defined in the WebLogic Server Domain Configuration Schema at http://xmlns.oracle.com/weblogic/domain/1.0/doma in.xsd. The XML file must exist in the Administration Server's root directory, which is either the current directory or the directory that you specify with the dir attribute. If you do not specify this attribute, the default value is config.xml in the directory specified by the dir attribute. If you do not specify the dir attribute, then the default domain directory is the current directory. useBootProperties Specifies whether to use the boot.properties file when starting a WebLogic Server instance. If this attribute is set to true, WebLogic Server uses the username and encrypted password stored in the boot.properties file to start rather than any values set with the username and password attributes. Note: The values of the username and password attributes are still used when shutting down or rebooting the WebLogic Server instance. The useBootProperties attribute applies only when starting the server. Valid values for this attribute are true and false. The default value is false. verbose Specifies that the Ant task output additional information as it is performing its action. Valid values for this attribute are true and false. The default value is false. Boolean No Boolean No Data Type String Required? No.
2.3 Configuring a WebLogic Server Domain Using the wlconfig Ant Task
The following sections describe how to use the wlconfig Ant task to configure a WebLogic Server domain.
Note::
The wlconfig Ant task works only against MBeans that are compatible with the MBean server, which was deprecated as of version 9.0 of WebLogic Server. In particular, the wlconfig Ant task uses the deprecated proprietary API weblogic.management.MBeanHome to access WebLogic MBeans; therefore, wlconfig does not use the standard JMX interface (javax.management.MBeanServerConnection) to discover MBeans. This means that the only MBeans that you can access using wlconfig are those listed under the Deprecated MBeans category in the Oracle WebLogic Server MBean Reference For equivalent functionality, you should use the WebLogic Scripting Tool (WLST). See Oracle WebLogic Scripting Tool.
Create new MBeans, optionally storing the new MBean Object Names in Ant properties. Set attribute values on a named MBean available on the Administration Server. Create MBeans and set their attributes in one step by nesting set attribute commands within create MBean commands. Query MBeans, optionally storing the query results in an Ant property reference. Query MBeans and set attribute values on all matching results. Establish a parent/child relationship among MBeans by nesting create commands within other create commands.
Set your environment in a command shell. See Section 2.2.1, "Basic Steps for Using wlserver" for details.
Note:
The wlconfig task is predefined in the version of Ant shipped with WebLogic Server. If you want to use the task with your own Ant installation, add the following task definition in your build file:
2.
wlconfig is commonly used in combination with wlserver to configure a new WebLogic Server domain created in the context of an Ant task. If you will be using wlconfig to configure such a domain, first use wlserver attributes to create a new domain and start the WebLogic Server instance. Add an initial call to the wlconfig task to connect to the Administration Server for a domain. For example:
<target name="doconfig"> <wlconfig url="t3://localhost:7001" username="weblogic" password="weblogic"> </target>
3.
4. 5.
Add nested create, delete, get, set, and query elements to configure the domain. Execute the Ant task or tasks specified in the build.xml file by typing ant in the staging directory, optionally passing the command a target argument:
prompt> ant doconfig
Use ant -verbose to obtain more detailed messages from the wlconfig task.
Note:
Since WLST is the recommended tool for domain creation scripts, you should refer to the WLST offline sample scripts that are installed with the software. The offline scripts demonstrate how to create domains using the domain templates and are located in the following directory: WL_ HOME\common\templates\scripts\wlst, where WL_HOME refers to the top-level installation directory for WebLogic Server. For example, the basicWLSDomain.py script creates a simple WebLogic domain, while sampleMedRecDomain.py creates a domain that defines resources similar to those used in the Avitek MedRec sample. See Oracle WebLogic Scripting Tool.
Using Ant Tasks to Configure and Use a WebLogic Server Domain 2-7
userconfigfile Specifies the location of a user configuration file to use for obtaining the administrative username and password. Use this option, instead of the username and password attributes, in your build file when you do not want to have the plain text password shown in-line or in process-level utilities such as ps. Before specifying the userconfigfile attribute, you must first generate the file using the WebLogic Scripting Tool (WLST) storeUserConfig command as described in the WebLogic Scripting Tool Command Reference. userkeyfile Specifies the location of a user key file to use for encrypting and decrypting the username and password information stored in a user configuration file (the userconfigfile attribute). Before specifying the userkeyfile attribute, you must first generate the key file using the WebLogic Scripting Tool (WLST) storeUserConfig command as described in the WebLogic Scripting Tool Command Reference.
File
No
File
No
2.3.5.1 create
The create element creates a new MBean in the WebLogic Server domain. The wlconfig task can have any number of create elements. A create element can have any number of nested set elements, which set attributes on the newly-created MBean. A create element may also have additional, nested create elements that create child MBeans. The create element has the following attributes.
Table 23 Attribute name Attributes of the create Element Description The name of the new MBean object to create. Data Type String Required? No (wlconfig supplies a default name if none is specified.) Yes No
type property
The MBean type. The name of an optional Ant property that holds the object name of the newly-created MBean. Note: If you nest a create element inside of another create element, you cannot specify the property attribute for the nested create element.
String String
2.3.5.2 delete
The delete element removes an existing MBean from the WebLogic Server domain. delete takes a single attribute:
Table 24 Attribute mbean Attribute of the delete Element Description The object name of the MBean to delete. Data Type String Required? Required when the delete element is a direct child of the wlconfig task. Not required when nested within a query element.
2.3.5.3 set
The set element sets MBean attributes on a named MBean, a newly-created MBean, or on MBeans retrieved as part of a query. You can include the set element as a direct child of the wlconfig task, or nested within a create or query element. The set element has the following attributes:
Using Ant Tasks to Configure and Use a WebLogic Server Domain 2-9
Attributes of the set Element Description The name of the MBean attribute to set. The value to set for the specified MBean attribute. You can specify multiple object names (stored in Ant properties) as a value by delimiting the entire value list with quotes and separating the object names with a semicolon. Data Type String String Required? Yes Yes
mbean
The object name of the MBean whose values are being set. This String attribute is required only when the set element is included as a direct child of the main wlconfig task; it is not required when the set element is nested within the context of a create or query element. This attribute specifies the JMX domain name for Security MBeans and third-party SPI MBeans. It is not required for administration MBeans, as the domain corresponds to the WebLogic Server domain. Note: You cannot use this attribute if the set element is nested inside of a create element. String
Required only when the set element is a direct child of the wlconfig task. No
domain
2.3.5.4 get
The get element retrieves attribute values from an MBean in the WebLogic Server domain. The wlconfig task can have any number of get elements. The get element has the following attributes.
Table 26 Attribute attribute property mbean Attributes of the get Element Description The name of the MBean attribute whose value you want to retrieve. The name of an Ant property that will hold the retrieved MBean attribute value. Data Type String String Required? Yes Yes Yes
The object name of the MBean you want to retrieve attribute values String from.
2.3.5.5 query
The query elements finds MBean that match a search pattern. The query element supports the following nested child elements:
setperforms set operations on all MBeans in the result set. getperforms get operations on all MBeans in the result set. createeach MBean in the result set is used as a parent of a new MBean. deleteperforms delete operations on all MBeans in the result set. invokeinvokes all matching MBeans in the result set.
wlconfig can have any number of nested query elements. query has the following attributes:
Attributes of the query Element Description The name of the WebLogic Server domain in which to search for MBeans. The type of MBean to query. The name of the MBean to query. A JMX query pattern. The name of an optional Ant property that will store the query results. Data Type String String String String String Required? No No No No No No
This attribute specifies the JMX domain name for Security MBeans String and third-party SPI MBeans. It is not required for administration MBeans, as the domain corresponds to the WebLogic Server domain.
2.3.5.6 invoke
The invoke element invokes a management operation for one or more MBeans. For WebLogic Server MBeans, you usually use this command to invoke operations other than the getAttribute and setAttribute that most WebLogic Server MBeans provide. The invoke element has the following attributes.
Table 28 Attribute mbean Attributes of the invoke Element Description The object name of the MBean you want to invoke. Data Type String Required? You must specify either the mbean or type attribute of the invoke element. You must specify either the mbean or type attribute of the invoke element. Yes No
type
String
methodName arguments
String
The list of arguments (separated by spaces) to pass to String the method specified by the methodName attribute.
Section 2.4.1, "libclasspath Task Definition" Section 2.2.3, "wlserver Ant Task Reference" Section 2.4.5, "Example libclasspath Ant Task"
Using Ant Tasks to Configure and Use a WebLogic Server Domain 2-11
Section 2.4.3, "Main libclasspath Attributes" Section 2.4.4, "Nested libclasspath Elements"
tmpdir classpathproperty
The fully qualified name of the directory to be used for extracting libraries. Contains the classpath for the referenced libraries. For example, if basedir points to a .war file that references web application libraries in the weblogic.xml file, the classpathproperty contains the WEB-INF/classes and WEB-INF/lib directories of the web application libraries. Additionally, if basedir points to a .war file that has .war files under WEB-INF/bea-ext, the classpathproperty contains the WEB-INF/classes and WEB-INF/lib directories for the Oracle extensions.
resourcepathproperty Contains library resources that are not classes. For example, if basedir points to a .war file that has .war files under WEB-INF/bea-ext, resourcepathproperty contains the roots of the exploded extensions.
2.4.4.1 librarydir
The following attribute is required when using this element: dirSpecifies that all files in this directory are registered as available libraries.
2.4.4.2 library
The following attribute is required when using this element:
Using Ant Tasks to Configure and Use a WebLogic Server Domain 2-13
3
3
Section 3.1, "Overview of the Split Development Directory Environment" Section 3.2, "Using the Split Development Directory Structure: Main Steps" Section 3.3, "Organizing Java EE Components in a Split Development Directory" Section 3.4, "Organizing Shared Classes in a Split Development Directory" Section 3.5, "Generating a Basic build.xml File Using weblogic.BuildXMLGen" Section 3.6, "Developing Multiple-EAR Projects Using the Split Development Directory" Section 3.7, "Best Practices for Developing WebLogic Server Applications"
Fast development and deployment. By minimizing unnecessary file copying, the split development directory Ant tasks help you recompile and redeploy applications quickly without first generating a deployable archive file or exploded archive directory. Simplified build scripts. The Oracle-provided Ant tasks automatically determine which Java EE modules and classes you are creating, and build components in the correct order to support common classpath dependencies. In many cases, your project build script can simply identify the source and build directories and allow Ant tasks to perform their default behaviors. Easy integration with source control systems. The split development directory provides a clean separation between source files and generated files. This helps you maintain only editable files in your source control system. You can also clean the build by deleting the entire build directory; build files are easily replaced by rebuilding the project.
3-1
The split development directory structure does not provide support for developing new Resource Adapter components.
Descriptor files for the Enterprise application (application.xml and weblogic-application.xml) Utility classes shared by modules of the application (for example, exceptions, constants) Libraries (compiled.jar files, including third-party libraries) used by modules of the application
The build directory contents are generated automatically when you run the wlcompile ant task against a valid source directory. The wlcompile task recognizes EJB, Web application, and shared library and class directories in the source directory, and builds those components in an order that supports common class path requirements. Additional Ant tasks can be used to build Web Services or generate deployment descriptor files from annotated EJB code.
Figure 31 Source and Build Directories
The build directory contains only those files generated during the build process. The combination of files in the source and build directories form a deployable Java EE application.
The build and source directory contents can be place in any directory of your choice. However, for ease of use, the directories are commonly placed in directories named source and build, within a single project directory (for example, \myproject\build and \myproject\source).
3-3
wlcompileThis Ant task compiles the contents of the source directory into subdirectories of the build directory. wlcompile compiles Java classes and also processes annotated .ejb files into deployment descriptors, as described in Section 4.1, "Compiling Applications Using wlcompile". wlappcThis Ant task invokes the appc compiler, which generates JSPs and container-specific EJB classes for deployment. See Section 4.2, "Building Modules and Applications Using wlappc". wldeployThis Ant task deploys any format of Java EE applications (exploded or archived) to WebLogic Server. To deploy directly from the split development directory environment, you specify the build directory of your application. See Section B, "wldeploy Ant Task Reference". wlpackageThis Ant task uses the contents of both the source and build directories to generate an EAR file or exploded EAR directory that you can give to others for deployment.
Create the main EAR source directory for your project. When using the split development directory environment, you must develop Web applications and EJBs as part of an Enterprise application, even if you do not intend to develop multiple
Java EE modules. See Section 3.3, "Organizing Java EE Components in a Split Development Directory".
2.
Add one or more subdirectories to the EAR directory for storing the source for Web applications, EJB components, or shared utility classes. See Section 3.3, "Organizing Java EE Components in a Split Development Directory" and Section 3.4, "Organizing Shared Classes in a Split Development Directory". Store all of your editable files (source code, static content, editable deployment descriptors) for modules in subdirectories of the EAR directory. Add the entire contents of the source directory to your source control system, if applicable. Set your WebLogic Server environment by executing either the setWLSEnv.cmd (Windows) or setWLSEnv.sh (UNIX) script. The scripts are located in the WL_ HOME\server\bin\ directory, where WL_HOME is the top-level directory in which WebLogic Server is installed. Use the weblogic.BuildXMLGen utility to generate a default build.xml file for use with your project. Edit the default property values as needed for your environment. See Section 3.5, "Generating a Basic build.xml File Using weblogic.BuildXMLGen". Use the default targets in the build.xml file to build, deploy, and package your application. See Section 3.5, "Generating a Basic build.xml File Using weblogic.BuildXMLGen" for a list of default targets.
3.
4.
5.
6.
The following sections describe the basic conventions for staging the following module types in the split development directory structure:
Section 3.3.2, "Enterprise Application Configuration" Section 3.3.3, "Web Applications" Section 3.3.4, "EJBs" Section 3.4.1, "Shared Utility Classes" Section 3.4.2, "Third-Party Libraries"
The directory examples are taken from the splitdir sample application installed in WL_HOME\samples\server\examples\src\examples\splitdir, where WL_ HOME is your WebLogic Server installation directory.
3-5
libraries. The sections that follow provide more details about how individual parts of the enterprise source directory are organized.
3-7
The Enterprise application directory will also have one or more subdirectories to hold a Web application, EJB, utility class, and/or third-party Jar file, as described in the following sections.
The key directories and files for the Web application are:
helloWebApp\ The top level of the Web application module can contain JSP files and static content such as HTML files and graphics used in the application. You can also store static files in any named subdirectory of the Web application (for example, helloWebApp\graphics or helloWebApp\static.) helloWebApp\WEB-INF\ Store the Web application's editable deployment descriptor files (web.xml and weblogic.xml) in the WEB-INF subdirectory. helloWebApp\WEB-INF\src Store Java source files for Servlets in package subdirectories under WEB-INF\src.
When you build a Web application, the appc Ant task and jspc compiler compile JSPs into package subdirectories under helloWebApp\WEB-INF\classes\jsp_ servlet in the build directory. Editable deployment descriptors are not copied during the build process.
3.3.4 EJBs
EJBs use the source directory layout shown in the figure below.
3-9
helloEJB\ Store all EJB source files under package directories of the EJB module directory. The source files can be either .java source files, or annotated .ejb files. helloEJB\META-INF\ Store editable EJB deployment descriptors (ejb-jar.xml and weblogic-ejb-jar.xml) in the META-INF subdirectory of the EJB module directory. The helloWorldEar sample does not include a helloEJB\META-INF subdirectory, because its deployment descriptors files are generated from annotations in the .ejb source files. See Section 3.3.5, "Important Notes Regarding EJB Descriptors".
During the build process, EJB classes are compiled into package subdirectories of the helloEJB module in the build directory. If you use annotated .ejb source files, the build process also generates the EJB deployment descriptors and stores them in the helloEJB\META-INF subdirectory of the build directory.
EJB source code in .java source files and editable deployment descriptors in META-INF
or:
EJB source code with descriptor annotations in .ejb source files, and no editable descriptors in META-INF.
In other words, do not provide both annotated .ejb source files and editable descriptor files for the same EJB component.
Place the source for Java utility classes in a named subdirectory of the top-level Enterprise application directory. Beneath the named subdirectory, use standard package subdirectory conventions. During the build process, the wlcompile Ant task invokes the javac compiler and compiles Java classes into the APP-INF/classes/ directory under the build directory. This ensures that the classes are available to other modules in the deployed application.
Third-party JARs are generally not compiled, but may be versioned using the source control system for your application code. For example, XML parsers, logging implementations, and Web application framework JAR files are commonly used in applications and maintained along with editable source code. During the build process, third-party JAR files are not copied to the build directory, but remain in the source directory for deployment.
The compile and appc tasks for modules also use the lib\echolib\echolib.jar library.
-helpprint standard usage message -versionprint version information -projectName <project name>name of the Ant project -d <directory>directory where build.xml is created. The default is the current directory. -file <build.xml>name of the generated build file -librarydir <directories>create build targets for shared Java EE libraries in the comma-separated list of directories. See Chapter 9, "Creating Shared Java EE Libraries and Optional Packages.". -username <username>user name for deploy commands -password <password>user password
After running weblogic.BuildXMLGen, edit the generated build.xml file to specify properties for your development environment. The list of properties you need to edit are shown in the listing below.
Example 31 build.xml Editable Properties <!-- BUILD PROPERTIES ADJUST THESE FOR YOUR ENVIRONMENT --> <property name="tmp.dir" value="/tmp" /> <property name="dist.dir" value="${tmp.dir}/dist"/> <property name="app.name" value="helloWorldEar" /> <property name="ear" value="${dist.dir}/${app.name}.ear"/> <property name="ear.exploded" value="${dist.dir}/${app.name}_exploded"/> <property name="verbose" value="true" /> <property name="user" value="USERNAME" /> <property name="password" value="PASSWORD" /> <property name="servername" value="myserver" /> <property name="adminurl" value="iiop://localhost:7001" />
In particular, make sure you edit the tmp.dir property to point to the build directory you want to use. By default, the build.xml file builds projects into a subdirectory tmp.dir named after the application (/tmp/helloWorldEar in the above listing). The following listing shows the default main targets created in the build.xml file. You can view these targets at the command prompt by entering the ant -projecthelp command in the EAR source directory.
Example 32 Default build.xml Targets appc build clean compile compile.appStartup Runs weblogic.appc on your application Compiles helloWorldEar application and runs appc Deletes the build and distribution directories Only compiles helloWorldEar application, no appc Compiles just the appStartup module of the application
compile.appUtils compile.build.orig compile.helloEJB compile.helloWebApp compile.javadoc deploy application descriptors ear ear.exploded redeploy.appStartup redeploy.appUtils redeploy.build.orig redeploy.helloEJB redeploy.helloWebApp redeploy.javadoc undeploy
Compiles just the appUtils module of the application Compiles just the build.orig module of the application Compiles just the helloEJB module of the application Compiles just the helloWebApp module of the application Compiles just the javadoc module of the application Deploys (and redeploys) the entire helloWorldEar Generates application and module descriptors Package a standard J2EE EAR for distribution Package a standard exploded J2EE EAR Redeploys just the appStartup module of the application Redeploys just the appUtils module of the application Redeploys just the build.orig module of the application Redeploys just the helloEJB module of the application Redeploys just the helloWebApp module of application Redeploys just the javadoc module of the application Undeploys the entire helloWorldEar application
The following sections refer to the MedRec sample application, which consists of three separate Enterprise applications as well as shared utility classes, third-party JAR files, and dedicated client applications. The MedRec source and build directories are installed under WL_ HOME/samples/server/medrec, where WL_HOME is the WebLogic Server installation directory.
MedRec takes a similar approach to utility classes that are shared by multiple EARs in the project. Instead of including the source for utility classes within the scope of each ear that needs them, MedRec keeps the utility class source independent of all EARs. After compiling the utility classes, the build script archives them and copies the JARs into the build directory under the APP-INF/LIB subdirectory of each EAR that uses the classes, as shown in figure Figure 39.
The above task instructs Ant to execute the file named build.xml in the /startupEar subdirectory. The inheritAll parameter instructs Ant to pass only user properties from the master build file tot the build.xml file in /startupEar. MedRec uses multiple tasks similar to the above to build the startupEar, medrecEar, and physicianEar applications, as well as building common utility classes and client applications.
Package applications as part of an Enterprise application. See Section 5.2, "Packaging Applications Using wlpackage".
Use the split development directory structure. See Section 3.3, "Organizing Java EE Components in a Split Development Directory". For distribution purposes, package and deploy in archived format. See Section 5.2, "Packaging Applications Using wlpackage". In most other cases, it is more convenient to deploy in exploded format. See Section 5.2.1, "Archive versus Exploded Archive Directory". Never deploy untested code on a WebLogic Server instance that is serving production applications. Instead, set up a development WebLogic Server instance on the same computer on which you edit and compile, or designate a WebLogic Server development location elsewhere on the network. Even if you do not run a development WebLogic Server instance on your development computer, you must have access to a WebLogic Server distribution to compile your programs. To compile any code using WebLogic or Java EE APIs, the Java compiler needs access to the weblogic.jar file and other JAR files in the distribution directory. Install WebLogic Server on your development computer to make WebLogic distribution files available locally.
4
4
Section 4.1, "Compiling Applications Using wlcompile" Section 4.2, "Building Modules and Applications Using wlappc"
Deployment descriptors are no longer mandatory in Java EE 5; therefore, exploded module directories must indicate the module type by using the .war or .jar suffix when there is no deployment descriptor in these directories. The suffix is required so that wlcompile can recognize the modules. The .war suffix indicates the module is a Web application module and the .jar suffix indicates the module is an EJB module.
Note:
The following is the order in which events occur using this task:
1.
wlcompile builds the EJBs and automatically includes the previously built Java modules in the compiler's classpath. This allows the EJBs to call the Java modules without requiring you to manually edit their classpath. Finally, wlcompile compiles the Java components in the Web application with the EJB and Java modules in the compiler's classpath. This allows the Web applications to refer to the EJB and application Java classes without requiring you to manually edit the classpath.
3.
4-1
The lib\tools.jar file in the JDK directory, or other standard Java classes required by the Java Development Kit you use. The examples.property file for Apache Ant (for examples environment). This file is discussed in the WebLogic Server documentation on building examples using Ant located at: samples\server\examples\src\examples\examples.html Classes for third-party Java tools or services your programs import.
The format choices for both specificationversion and implementationversion are described in Section 9.3, "Referencing Shared Java EE Libraries in an Enterprise Application". The following output shows a sample library reference:
<library file="c:\mylibs\lib.jar" name="ReqLib" specificationversion="920" implementationversion="1.1" />
4-3
Notes:
See Section 4.2.4, "weblogic.appc Reference" for a list of weblogic.appc options. See also Section 4.1.5, "Library Element for wlcompile and wlappc".
wlappc Ant Task Attributes Description Prints the standard usage message. Prints appc version information. Specifies an alternate output archive or directory. If not set, the output is placed in the source archive or directory. Forces generation of EJB and JSP classes. Without this flag, the classes may not be regenerated (if determined to be unnecessary). Adds line numbers to generated class files to aid in debugging. Specifies that the application or module contains deployment descriptors with annotation information. Does not include deployment descriptors in client JARs generated for EJBs. Generates IDL for EJB remote interfaces. Always overwrites existing IDL files. Displays verbose information for IDL generation. Does not generate valuetypes and the methods/attributes that contain them. Does not generate abstract interfaces and methods/attributes that contain them. Generates factory methods for valuetypes. Generates IDL somewhat compatible with Visibroker 4.5 C++. Generates IDL somewhat compatible with Orbix 2000 2.0 C++. Specifies the directory where IDL files will be created (default: target directory or JAR) Specifies the method signatures used to trigger IDL code generation. Generates CORBA stubs for EJBs. Specifies the directory where IIOP stub files will be written (default: target directory or JAR) Keeps the generated .java files. Specifies a directory of shared Java EE libraries to add to the classpath. See Chapter 9, "Creating Shared Java EE Libraries and Optional Packages." Selects the Java compiler to use. Defaults to JDT. Compiles debugging information into a class file. Compiles with optimization on. Compiles without warnings. Compiles with verbose output. Warns about deprecated calls. Passes flags through to Symantec's sj. Passes flags through to Java runtime
output <file> forceGeneration lineNumbers writeInferredDescriptors basicClientJar idl idlOverwrite idlVerbose idlNoValueTypes idlNoAbstractInterfaces idlFactories idlVisibroker idlOrbix idlDirectory <dir> idlMethodSignatures <> iiop iiopDirectory <dir> keepgenerated librarydir compiler <java.jdt> debug optimize nowarn verbose deprecation normi runtimeflags
Table 43 (Cont.) wlappc Ant Task Attributes Option classpath <path> clientJarOutputDir <dir> advanced Description Selects the classpath to use during compilation. Specifies a directory to place generated client jar files. If not set, generated jar files are placed into the same directory location where the JVM is running. Prints advanced usage options.
The following is an example of a wlappc Ant task command that invokes two options (idl and idlOrverWrite) from Table 43.
<wlappc source="${dest.dir}"idl="true" idlOrverWrite="true" />
4-5
Description A comma-separated list of shared Java EE libraries. Optional name and version string information must be specified in the format described in Section 9.3, "Referencing Shared Java EE Libraries in an Enterprise Application".
-writeInferredDescr Specifies that the application or module contains deployment descriptors with annotation information. iptors -lineNumbers -basicClientJar -idl -idlOverwrite -idlVerbose -idlNoValueTypes Adds line numbers to generated class files to aid in debugging. Does not include deployment descriptors in client JARs generated for EJBs. Generates IDL for EJB remote interfaces. Always overwrites existing IDL files. Displays verbose information for IDL generation. Does not generate valuetypes and the methods/attributes that contain them.
-idlNoAbstractInter Does not generate abstract interfaces and methods/attributes that contain them. faces -idlFactories -idlVisibroker -idlOrbix Generates factory methods for valuetypes. Generates IDL somewhat compatible with Visibroker 4.5 C++. Generates IDL somewhat compatible with Orbix 2000 2.0 C++.
-idlDirectory <dir> Specifies the directory where IDL files will be created (default: target directory or JAR) -idlMethodSignature Specifies the method signatures used to trigger IDL code generation. s <> -iiop -iiopDirectory <dir> -keepgenerated -compiler <javac> -g -O -nowarn -verbose -deprecation -normi -J<option> -classpath <path> Generates CORBA stubs for EJBs. Specifies the directory where IIOP stub files will be written (default: target directory or JAR) Keeps the generated .java files. Selects the Java compiler to use. Compiles debugging information into a class file. Compiles with optimization on. Compiles without warnings. Compiles with verbose output. Warns about deprecated calls. Passes flags through to Symantec's sj. Passes flags through to Java runtime. Selects the classpath to use during compilation.
-clientJarOutputDir Specifies a directory to place generated client jar files. If not set, generated jar files are placed into the same directory location where the <dir> JVM is running. -advanced Prints advanced usage options.
5
5
Section 5.1, "Deploying Applications Using wldeploy" Section 5.2, "Packaging Applications Using wlpackage"
The above task is automatically created when you use weblogic.BuildXMLGen to create the build.xml file. See Appendix B, "wldeploy Ant Task Reference," for a complete command reference.
5-1
You can also package applications in a single archived file, which is convenient for packaging modules and applications for distribution. Archive files are easier to copy, they use up fewer file handles than an exploded directory, and they can save disk space with file compression. The Java classloader can search for Java class files (and other file types) in a JAR file the same way that it searches a directory in its classpath. Because the classloader can search a directory or a JAR file, you can deploy Java EE modules on WebLogic Server in either a JAR (archived) file or an exploded (unarchived) directory.
todir
Name of an exploded directory into which the wlpackage Ant task packages the split development directory application.
String
srcdir
Specifies the source directory of your split development directory application. The source directory contains all editable files for your projectJava source files, editable descriptor files, JSPs, static content, and so forth.
String
destdir
Specifies the build directory of your split development directory application. It is assumed that you have already executed the wlcompile Ant task against the source directory to generate the needed components into the build directory; these components include compiled Java classes and generated deployment descriptors.
String
Yes.
6
6
Section 6.1, "What is Production Redeployment?" Section 6.2, "Supported and Unsupported Application Types" Section 6.3, "Programming Requirements and Conventions" Section 6.4, "Assigning an Application Version" Section 6.5, "Upgrading Applications to Use Production Redeployment" Section 6.6, "Accessing Version Information"
Must be used in an application-scoped manner, having enable-access-outside-app set to false (the default value).
Before resource adapters in a newer version of the EAR are deployed, resource adapters in the older application version receive a callback. WebLogic Server then deploys the newer application version and retires the entire older version of the EAR. For a complete list of production redeployment requirements for resource adapters, see "Production Redeployment" in Programming Resource Adapters for Oracle WebLogic Server.
6.3.2 Versioned Applications Access the Current Version JNDI Tree by Default
WebLogic Server binds application-scoped resources, such as JMS and JDBC application modules, into a local JNDI tree available to the application. As with non-versioned applications, versioned applications can look up application-scoped resources directly from this local tree. Application-scoped JMS modules can be accessed via any supported JMS interfaces, such as the JMS API or a message-driven bean. Application modules that are bound to the global JNDI tree should be accessed only from within the same application version. WebLogic Server performs version-aware JNDI lookups and bindings for global resources deployed in a versioned application. By default, an internal JNDI lookup of a global resource returns bindings for the same version of the application. If the current version of the application cannot be found, you can use the JNDI environment property weblogic.jndi.WLContext.RELAX_VERSION_LOOKUP to return bindings from the currently active version of the application, rather than the same version.
Note::
Set weblogic.jndi.WLContext.RELAX_VERSION_LOOKUP to true only if you are certain that the newer and older version of the resource that you are looking up are compatible with one another.
6-3
This behavior can be problematic for client applications that recursively access other applications when processing requests. WebLogic Server attempts to dispatch requests to the same versions of the recursively-accessed applications, but cannot guarantee that an intermediate application version is not undeployed manually or after a timeout period. If you have a group of related applications with strict version requirements, Oracle recommends packaging all of the applications together to ensure version consistency during production redeployment.
Valid ASCII Characters a-z A-Z 0-9 period ("."), underscore ("_"), or hyphen ("-") in combination with other characters
For example, the following manifest file content describes an application with version "v920.beta":
Manifest-Version: 1.0 Created-By: 1.4.1_05-b01 (Sun Microsystems Inc.) Weblogic-Application-Version: v920.beta
ApplicationRuntimeMBean also provides version information in the new read-only attributes described in the following table.
Table 63 Read-Only Version Attributes in ApplicationRuntimeMBean Description A String that represents the deployment name of the application A string that represents the version of the application. An integer that indicates the current state of the active application version. Valid states for an active version are:
ACTIVATEDindicates that one or more modules of the application are active and available for processing new client requests. PREPAREDindicates that WebLogic Server has prepared one or more modules of the application, but that it is not yet active. UNPREPAREDindicates that no modules of the application are prepared or active.
See the Oracle WebLogic Server API Reference for more information. Note that the currently active version does not always correspond to the last-deployed version, because the Administrator can reverse the production redeployment process. See "Rolling Back the Production Redeployment Process" in Deploying Applications to Oracle WebLogic Server.
6-5
7
7
Section 7.1, "Annotation Processing" Section 7.2, "Dependency Injection of Resources" Section 7.3, "Standard JDK Annotations" Section 7.4, "Standard Security-Related JDK Annotations"
components. Dependency injection is simply an easier-to-program alternative to using the javax interfaces or JNDI APIs to look up resources. A field or a method of an application component can be annotated with the @Resource annotation. Note that the container will unbox the environment entry as required to match it to a primitive type used for the injection field or method. Example 71 illustrates how an application component uses the @Resource annotation to declare environment entries.
Example 71 Dependency Injection of Environment Entries // fields // The maximum number of tax exemptions, configured by the Deployer. @Resource int maxExemptions; // The minimum number of tax exemptions, configured by the Deployer. @Resource int minExemptions; .. }
In the above code the @Resource annotation has not specified a name; therefore, the container would look for an env-entry name called <class-name>/maxExemptions and inject the value of that entry into the maxExemptions variable. The field or method may have any access qualifier (public, private, etc.). For all classes except application client main classes, the fields or methods must not be static. Because application clients use the same life cycle as Java EE applications, no instance of the application client main class is created by the application client container. Instead, the static main method is invoked. To support injection for the application client main class, the fields or methods annotated for injection must be static.
For detailed information about EJB-specific annotations for WebLogic Server Enterprise JavaBeans, see Programming WebLogic Enterprise JavaBeans, Version 3.0 for Oracle WebLogic Server. For detailed information about web component-specific annotations WebLogic Server applications, see "WebLogic Annotation for Web Components" in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.
7.3.1 javax.annotation.PostConstruct
Target: Method Specifies the life cycle callback method that the application component should execute before the first business method invocation and after dependency injection is done to perform any initialization. This method will be called after all injections have occurred and before the class is put into service. This method will be called even if the class doesn't request any resources to be injected. You must specify a @PostConstruct method in any component that includes dependency injection. Only one method in the component can be annotated with this annotation. The method annotated with @PostConstruct must follow these requirements:
The method must not have any parameters, except in the case of EJB interceptors, in which case it takes an javax.interceptor.InvocationContext object as defined by the EJB specification. The return type of the method must be void. The method must not throw a checked exception. The method may be public, protected, package private or private. The method must not be static except for the application client. The method may be final or non-final, except in the case of EJBs where it must be non-final. If the method throws an unchecked exception the class must not be put into service. In the case of EJBs, the method annotated with PostConstruct can handle exceptions and cleanup before the bean instance is discarded.
7.3.2 javax.annotation.PreDestroy
Target: Method Specifies the life cycle callback method that signals that the application component is about to be destroyed by the container. You typically apply this annotation to methods that release resources that the class has been holding. Only one method in the bean class can be annotated with this annotation. The method annotated with @PreDestroy must follow these requirements:
The method must not have any parameters, except in the case of EJB interceptors, in which case it takes an
The return type of the method must be void. The method must not throw a checked exception. The method may be public, protected, package private or private. The method must not be static except for the application client. The method may be final or non-final, except in the case of EJBs where it must be non-final. If the method throws an unchecked exception the class must not be put into service. In the case of EJBs, the method annotated with PreDestroy can handle exceptions and cleanup before the bean instance is discarded.
7.3.3 javax.annotation.Resource
Target: Class, Method, Field Specifies a dependence on an external resource, such as a JDBC data source or a JMS destination or connection factory. If you specify the annotation on a field or method, the application component injects an instance of the requested resource into the bean when the bean is initialized. If you apply the annotation to a class, the annotation declares a resource that the component will look up at runtime. Attributes
Table 71 Name name Attributes of the javax.annotation.Resource Annotation Description Specifies the JNDI name of the resource. If you apply the @Resource annotation to a field, the default value of the name attribute is the field name, qualified by the class name. If you apply it to a method, the default value is the component property name corresponding to the method, qualified by the class name. If you apply the annotation to class, there is no default value and thus you are required to specify the attribute. type Specifies the Java data type of the resource. If you apply the @Resource annotation to a field, the default value of the type attribute is the type of the field. If you apply it to a method, the default is the type of the component property. If you apply it to a class, there is no default value and thus you are required to specify this attribute. authentication Specifies the authentication type to use for the resource. Type Valid values for this attribute are:
Required? No
Class
No
Authentication Type
No
AuthenticationType.CONTAINER AuthenticationType.APPLICATION
Table 71 (Cont.) Attributes of the javax.annotation.Resource Annotation Name shareable Description Indicates whether a resource can be shared between this component and other components. Valid values for this attribute are true and false. Default value is true. mappedName Specifies a WebLogic Server-specific name to which the component reference should be mapped. However, if you do not specify a JNDI name in the WebLogic deployment descriptor file, then the value of mappedName will always be used as the JNDI name to look up. For example: @Resource(mappedName = "http://www.bea.com";) URL url; @Resource(mappedName="customerDB") DataSource db; @Resource(mappedName = "jms/ConnectionFactory") ConnectionFactory connectionFactory; @Resource(mappedName = "jms/Queue") Queue queue; In other words, MappedName is honored as JNDI name only when there is no JNDI name specified elsewhere, typically in the WebLogic deployment descriptor file. description Specifies a description of the resource. String No String No Data Type Boolean Required? No
7.3.4 javax.annotation.Resources
Target: Class Specifies an array of @Resource annotations. Since repeated annotations are not allowed, the Resources annotation acts as a container for multiple resource declarations. Attributes
Table 72 Name value Attributes of the javax.annotation.Resources Annotation Description Specifies the array of @Resource annotations. Data Type Resource[] Required? Yes
Section 7.4.1, "javax.annotation.security.DeclareRoles" Section 7.4.2, "javax.annotation.security.DenyAll" Section 7.4.3, "javax.annotation.security.PermitAll" Section 7.4.4, "javax.annotation.security.RolesAllowed" Section 7.4.5, "javax.annotation.security.RunAs"
7.4.1 javax.annotation.security.DeclareRoles
Target: Class Defines the security roles that will be used in the Java EE container. You typically use this annotation to define roles that can be tested from within the methods of the annotated class, such as using the isUserInRole method. You can also use the annotation to explicitly declare roles that are implicitly declared if you use the @RolesAllowed annotation on the class or a method of the class. You create security roles in WebLogic Server using the Administration Console. For details, see "Manage Security Roles". Attributes
Table 73 Name value Attributes of the javax.annotation.security.DeclareRoles Annotation Data Type String[] Required? Yes
Description Specifies an array of security roles that will be used in the Java EE container.
7.4.2 javax.annotation.security.DenyAll
Target: Method Specifies that no security role is allowed to access the annotated method, or in other words, the method is excluded from execution in the Java EE container. This annotation does not have any attributes.
7.4.3 javax.annotation.security.PermitAll
Target: Method Specifies that all security roles currently defined for WebLogic Server are allowed to access the annotated method. This annotation does not have any attributes.
7.4.4 javax.annotation.security.RolesAllowed
Target: Class, Method Specifies the list of security roles that are allowed to access methods in the Java EE container. If you specify it at the class-level, then it applies to all methods in the application component. If you specify it at the method-level, then it only applies to that method. If you specify the annotation at both the class- and method-level, the method value overrides the class value. You create security roles in WebLogic Server using the Administration Console. For details, see "Manage Security Roles". Attributes
Table 74 Name value Attributes of the javax.annotation.security.RolesAllowed Annotation Description List of security roles that are allowed to access methods of the Java EE container. Data Type Required? String[] Yes
7.4.5 javax.annotation.security.RunAs
Target: Class Specifies the security role which actually executes the Java EE container. The security role must exist in the WebLogic Server security realm and map to a user or group. For details, see "Manage Security Roles". Attributes
Table 75 Name value Attributes of the javax.annotation.security.RunAs Annotation Description Specifies the security role that the Java EE container should run as. Data Type Required? String Yes
8
8
Section 8.1, "Java Classloading" Section 8.2, "WebLogic Server Application Classloading" Section 8.3, "Resolving Class References Between Modules and Applications" Section 8.4, "Using the Classloader Analysis Tool (CAT)" Section 8.5, "Sharing Applications and Modules By Using Java EE Libraries" Section 8.6, "Adding JARs to the Domain /lib Directory"
Java Classloading
Note:
What Oracle refers to as a "system classpath classloader" is often referred to as the "application classloader" in contexts outside of WebLogic Server. When discussing classloaders in WebLogic Server, Oracle uses the term "system" to differentiate from classloaders related to Java EE applications or libraries (which Oracle refers to as "application classloaders").
Java Classloading
Reduces server startup time. The package level index reduces search time for all classes and resources.
The cache uses optimization techniques to minimize the initial cache recording time. Cache recording continues until a specific class has been recorded.
Note:
Class caching is supported in development mode when starting the server using a startWebLogic script. Class caching is disabled by default and is not supported in production mode. The decrease in startup time varies among different JRE vendors.
1. 2.
To enable class caching, set an environment variable (CLASS_CACHE=true for UNIX, set CLASS_CACHE=true for Windows) in the startWebLogic script. Configure class caching using the following properties:
Logging: To debug class caching issues, turn on logging by placing the following system properties in the JAVA_OPTIONS for the section of the startup script that enables caching. -Dclass.load.log.level=finest -Dclass.load.log.file=/tmp/class-load-log.txt There are three levels of logging: fine, finer, finest. Do not enable logging during regular cache operation. Logging will slow the start up of the server. Use logging for debugging only.
Recording limit: Though the recording limit for class caching is set to a specific class, you can configure this class in your environment to a different class.
Understanding WebLogic Server Application Classloading 8-3
-Dlaunch.complete=<fully qualified class name> for example com.oracle.component.Foo The class used in this property must be in the system classpath for WebLogic Server. Example 82 illustrates modified UNIX and Windows startWebLogic scripts with class caching enabled and logging turned on.
Example 82 startWebLogic scripts On UNIX # CLASS CACHING CLASS_CACHE=true if [ "${CLASS_CACHE}" = "true" ] ; then echo "Class caching enabled..." JAVA_OPTIONS="${JAVA_OPTIONS} -Dlaunch.main.class=${SERVER_CLASS} -Dlaunch.class.path="${CLASSPATH}" -Dlaunch.complete=weblogic.store.internal.LockManagerImpl -Dclass.load.log.level=finest -Dclass.load.log.file=/tmp/class-load-log.txt -cp ${WL_HOME}/server/lib/pcl2.jar" export JAVA_OPTIONS SERVER_CLASS="com.oracle.classloader.launch.Launcher" fi
On Windows @REM CLASS CACHING set CLASS_CACHE=true if "%CLASS_CACHE%"=="true" ( echo Class caching enabled... set JAVA_OPTIONS=%JAVA_OPTIONS% -Dlaunch.main.class=%SERVER_CLASS% -Dlaunch.class.path="%CLASSPATH%" -Dclass.load.log.level=finest -Dclass.load.log.file=C:\class-load-log.txt -Dlaunch.complete=weblogic.store.internal.LockManagerImpl -cp %WL_HOME%\server\lib\pcl2.jar set SERVER_CLASS=com.oracle.classloader.launch.Launcher )
Section 8.2.1, "Overview of WebLogic Server Application Classloading" Section 8.2.2, "Application Classloader Hierarchy" Section 8.2.3, "Custom Module Classloader Hierarchies" Section 8.2.6, "Individual EJB Classloader for Implementation Classes" Section 8.2.7, "Application Classloading and Pass-by-Value or Reference" Section 8.2.8, "Using a Filtering Classloader"
An Enterprise JavaBean (EJB) JAR file A Web application WAR file A resource adapter RAR file
Note:
For information on Resource Adapters and classloading, see Section 8.3.1, "About Resource Adapter Classes". For information on overriding generic application files while classloading, see "Generic File Loading Overrides" in Deploying Applications to Oracle WebLogic Server.
If you deploy an EJB and a Web application separately, they are considered two applications. If they are deployed together within an EAR file, they are one application. You deploy modules together in an EAR file for them to be considered part of the same application. Every application receives its own classloader hierarchy; the parent of this hierarchy is the system classpath classloader. This isolates applications so that application A cannot see the classloaders or classes of application B. In hierarchy classloaders, no sibling or friend concepts exist. Application code only has visibility to classes loaded by the classloader associated with the application (or module) and classes that are loaded by classloaders that are ancestors of the application (or module) classloader. This allows WebLogic Server to host multiple isolated applications within the same JVM.
Package the servlets and JSPs in a WAR file Package the Enterprise JavaBeans in an EJB JAR file Package the WAR and JAR files in an EAR file Deploy the EAR file
Although you could deploy the WAR and JAR files separately, deploying them together in an EAR file produces a classloader arrangement that allows the servlets and JSPs to find the EJB classes. If you deploy the WAR and JAR files separately, WebLogic Server creates sibling classloaders for them. This means that you must include the EJB home and remote interfaces in the WAR file, and WebLogic Server must use the RMI stub and skeleton classes for EJB calls, just as it does when EJB clients and implementation classes are in different JVMs. This concept is discussed in more detail in the next section Section 8.2.7, "Application Classloading and Pass-by-Value or Reference".
Note:
The Web application classloader contains all classes for the Web application except for the JSP class. The JSP class obtains its own classloader, which is a child of the Web application classloader. This allows JSPs to be individually reloaded.
loaded. For each Web module, there is a separate child classloader for the classes of that module. For simplicity, JSP classloaders are not described in the following diagram.
Figure 82 Standard Classloader Hierarchy
This hierarchy is optimal for most applications, because it allows call-by-reference semantics when you invoke EJBs. It also allows Web modules to be independently reloaded without affecting other modules. Further, it allows code running in one of the Web modules to load classes from any of the EJB modules. This is convenient, as it can prevent a Web module from including the interfaces for EJBs that it uses. Note that some of those benefits are not strictly Java EE-compliant. The ability to create custom module classloaders provides a mechanism to declare alternate classloader organizations that allow the following:
Reloading individual EJB modules independently Reloading groups of modules to be reloaded together Reversing the parent child relationship between specific Web modules and EJB modules Namespace separation between EJB modules
The top-level element in weblogic-application.xml includes an optional classloader-structure element. If you do not specify this element, then the standard classloader is used. Also, if you do not include a particular module in the definition, it is assigned a classloader, as in the standard hierarchy. That is, EJB modules are associated with the application root classloader, and Web application modules have their own classloaders.
Understanding WebLogic Server Application Classloading 8-7
The classloader-structure element allows for the nesting of classloader-structure stanzas, so that you can describe an arbitrary hierarchy of classloaders. There is currently a limitation of three levels. The outermost entry indicates the application classloader. For any modules not listed, the standard hierarchy is assumed.
Note:
JSP classloaders are not included in this definition scheme. JSPs are always loaded into a classloader that is a child of the classloader associated with the Web module to which it belongs.
For more information on the DTD elements, refer to Appendix A, "Enterprise Application Deployment Descriptor Elements." The following is an example of a classloader declaration (defined in the classloader-structure element in weblogic-application.xml):
Example 84 Example Classloader Declaration <classloader-structure> <module-ref> <module-uri>ejb1.jar</module-uri> </module-ref> <module-ref> <module-uri>web3.war</module-uri> </module-ref> <classloader-structure> <module-ref> <module-uri>web1.war</module-uri> </module-ref> </classloader-structure> <classloader-structure> <module-ref> <module-uri>ejb3.jar</module-uri> </module-ref> <module-ref> <module-uri>web2.war</module-uri> </module-ref> <classloader-structure> <module-ref> <module-uri>web4.war</module-uri> </module-ref> </classloader-structure> <classloader-structure> <module-ref> <module-uri>ejb2.jar</module-uri> </module-ref> </classloader-structure> </classloader-structure> </classloader-structure>
The organization of the nesting indicates the classloader hierarchy. The above stanza leads to a hierarchy shown in the following diagram.
8.2.5.5 Interfaces
The standard WebLogic Server classloader hierarchy makes EJB interfaces available to all modules in the application. Thus other modules can invoke an EJB, even though they do not include the interface classes in their own module. This is possible because EJBs are always loaded into the root classloader and all other modules either share that classloader or have a classloader that is a child of that classloader. With the custom classloader feature, you can configure a classloader hierarchy so that a callee's classes are not visible to the caller. In this case, the calling module must include the interface classes. This is the same requirement that exists when invoking on modules in a separate application.
To perform a partial update of files relative to the root of the exploded application, use the following command line:
Example 85 Performing a Partial File Update java weblogic.Deployer -adminurl url -user user -password password -name myapp -redeploy myejb/foo.class
After the -redeploy command, you provide a list of files relative to the root of the exploded application that you want to update. This might be the path to a specific element (as above) or a module (or any set of elements and modules). For example:
Example 86 Providing a List of Relative Files for Update java weblogic.Deployer -adminurl url -user user -password password -name myapp -redeploy mywar myejb/foo.class anotherejb
Given a set of files to be updated, the system tries to figure out the minimum set of things it needs to redeploy. Redeploying only an EJB impl class causes only that class to be redeployed. If you specify the whole EJB (in the above example, anotherejb) or if you change and update the EJB home interface, the entire EJB module must be redeployed. Depending on the classloader hierarchy, this redeployment may lead to other modules being redeployed. Specifically, if other modules share the EJB classloader or are loaded into a classloader that is a child to the EJB's classloader (as in the WebLogic Server standard classloader module) then those modules are also reloaded.
8-11
WebLogic Server includes an optimization to improve the performance of Remote Method Interface (RMI) calls within the server. Rather than using pass by value and the RMI subsystem's marshalling and unmarshalling facilities, the server makes a direct Java method call using pass by reference. This mechanism greatly improves performance and is also used for EJB 2.0 local interfaces. RMI call optimization and call by reference can only be used when the caller and callee are within the same application. As usual, this is related to classloaders. Because applications have their own classloader hierarchy, any application class has a definition in both classloaders and receives a ClassCastException error if you try to assign between applications. To work around this, WebLogic Server uses call-by-value between applications, even if they are within the same JVM.
Note:
Calls between applications are slower than calls within the same application. Deploy modules together as an EAR file to enable fast RMI calls and use of the EJB 2.0 local interfaces.
Section 8.2.9, "What is a Filtering ClassLoader" Section 8.2.10, "Configuring a FilteringClassLoader" Section 8.2.11, "Resource Loading Order"
The prefer-application-packages descriptor element can also be defined in weblogic.xml. For more information, see "prefer-application-packages". For aid in configuring filtering classloaders, see Section 8.4, "Using the Classloader Analysis Tool (CAT)."
To be more explicit, given a resource /META-INF/foo.xml which exists in all the classloaders, would return the following list of URLs:
META-INF/foo.xml - from the System ClassLoader (3) META-INF/foo.xml - from the App ClassLoader (2) META-INF/foo.xml - from the Web ClassLoader (1)
When filtering is enabled, the resources from the child of the FilteringClassLoader (an application classloader) down to the calling classloader are returned before the ones from the system classloader. In Example 88, if the same resource existed in all the classloaders (D), (B) and (A) one would get them in the following order if requested by the Web classloader:
META-INF/foo.xml - from the App ClassLoader (B) META-INF/foo.xml - from the Web ClassLoader (A) META-INF/foo.xml - from the System ClassLoader (D)
Note:
The resources are returned in the default Java EE delegation model beneath the FilteringClassLoader. Only the resources from the parent of the FilteringClassLoader are appended to the end of the enumeration being returned.
8-13
Example 88 Using a Filtering Classloading Implementation System (D) | FilteringClassLoader (filterList := x.y.*) (C) | App (B) | Web (A)
If the application classloader requested the same resource, the following order would be obtained.
META-INF/foo.xml - from the App ClassLoader (B) META-INF/foo.xml - from the System ClassLoader (D)
For getResource(), only the first descriptor is returned and getResourceAsStream() returns the inputStream of the first resource.
hierarchy). Be aware that using this feature is subtly different from using the manifest Class-Path described in the following section. With this feature, class definitions are shared across the application. With manifest Class-Path, the classpath of the referencing module is simply extended, which means that separate copies of the classes exist for each module.
In the first line of the manifest file, you must always include the Manifest-Version attribute, followed by a new line (CR | LF |CRLF) and then the Class-Path attribute. More information about the manifest format can be found at: http://download.oracle.com/javase/1.4.2/docs/guide/jar/jar.html# JAR The manifest Class-Path entries refer to other archives relative to the current archive in which these entries are defined. This structure allows multiple WAR files and EJB JAR files to share a common library JAR. For example, if a WAR file contains a manifest entry of y.jars, this entry should be next to the WAR file (not within it) as follows:
/<directory>/x.war /<directory>/y.jars
The manifest file itself should be located in the archive at META-INF/MANIFEST.MF. For more information, see http://download-llnw.oracle.com/javase/tutorial/deployment/jar/m anifestindex.html.
8-15
Caution: CAT uses Basic Authentication, which allows login credentials to be sent in the clear. Therefore, Oracle recommends that you undeploy or stop CAT after you are done using it, and that you should never deploy CAT in a production environment.
If CAT is deployed in a production environment, you should prevent access to it immediately. For information about stopping access, see one of the following topics:
"Stop" in Deploying Applications to Oracle WebLogic Server "Stop deployed Web applications" in the Oracle WebLogic Server Administration Console Help
Although the user name and password are Base64 encoded, Base64 encoding is not provided for security purposes but rather for encoding non-HTTP-compatible characters that may be in the user name or password into those that are HTTP-compatible. Basic Authentication can make a system vulnerable to replay and man-in-the middle attacks. Existing browsers retain authentication information indefinitely. HTTP does not provide a method for a server to direct clients to discard these cached credentials. This means that there is no effective way for a server to log out the user without closing the browser.
In the WebLogic Server Administration Console, select Deployments > app_name > Testing and then select the Classloader Analysis Tool link. Enter your Console login credentials. Or, open your browser to http://wls-host:port/wls-cat/ and then enter your Console login credentials.
CAT has a simple Web GUI which displays all your currently running applications and modules. In the left-side navigation pane, you select the application or module that you want to analyze; a brief description of it is shown in the right-side pane. You use the right-side pane to perform actions and analyses on the selected application or module. CAT lets you:
Analyze classloading conflicts View the system and application classloaders Generate reports
CAT analyzes classes loaded by the system classpath classloader and the WebLogic Server main application classloaders, defined here as the filtering, application, and module classloaders. You can perform analysis at the class, package, or JAR level. The results for each action you select can be shown in either a basic view or a detailed view. Here are some of the tasks which you can perform using CAT:
Display basic information about applications and modules Analyze classloading conflicts
Review proposed solutions Get suggestions for configuring filtering classloaders Display the classloader hierarchy and the entire classpath for each classloader Search for a class (or a resource) on a classloader
Shutdown all servers in the domain. Copy the JAR file(s) to share into a lib subdirectory of the domain directory. For example:
mkdir c:\bea\wlserver_10.3\samples\domains\wl_server\lib cp c:\3rdpartyjars\utility.jar c:\bea\wlserver_10.3\samples\domains\wl_server\lib
8-17
Note: WebLogic Server must have read access to the lib directory during startup.
The Administration Server does not automatically copy files in the lib directory to Managed Servers on remote machines. If you have Managed Servers that do not share the same physical domain directory as the Administration Server, you must manually copy JAR file(s) to the domain_name/lib directory on the Managed Server machines.
3.
Start the Administration Server and all Managed Servers in the domain.
9
9
Section 9.1, "Overview of Shared Java EE Libraries and Optional Packages" Section 9.2, "Creating Shared Java EE Libraries" Section 9.3, "Referencing Shared Java EE Libraries in an Enterprise Application" Section 9.4, "Referencing Optional Packages from a Java EE Application or Module" Section 9.5, "Using weblogic.appmerge to Merge Libraries" Section 9.6, "Integrating Shared Java EE Libraries with the Split Development Directory Environment" Section 9.7, "Deploying Shared Java EE Libraries and Dependent Applications" Section 9.8, "Web Application Shared Java EE Library Information" Section 9.9, "Using WebApp Libraries With Web Applications" Section 9.10, "Accessing Registered Shared Java EE Library Information with LibraryRuntimeMBean" Section 9.11, "Order of Precedence of Modules When Referencing Shared Java EE Libraries" Section 9.12, "Best Practices for Using Shared Java EE Libraries"
standalone EJB module standalone Web application module multiple EJB modules packaged in an Enterprise application multiple Web application modules package in an Enterprise application single plain JAR file
Creating Shared Java EE Libraries and Optional Packages 9-1
Oracle recommends that you package a shared Java EE library into its appropriate archive file (EAR, JAR, or WAR). However, for development purposes, you may choose to deploy shared Java EE libraries as exploded archive directories to facilitate repeated updates and redeployments. After the shared Java EE library has been registered, you can deploy Enterprise applications that reference the library. Each referencing application receives a reference to the required library on deployment, and can use the modules that make up the library as if they were packaged as part of the referencing application itself. The library classes are added to the classpath of the referencing application, and the referencing application's deployment descriptors are merged (in memory) with those of the modules that make up the shared Java EE library. In general, this topic discusses shared Java EE libraries that can be referenced only by Enterprise applications. You can also create libraries that can be referenced only by another Web application. The functionality is very similar to application libraries, although the method of referencing them is slightly different. See Section 9.8, "Web Application Shared Java EE Library Information" for details.
Note:
WebLogic Server also provides a simple way to add one or more JAR files to the WebLogic Server System classpath, using the lib subdirectory of the domain directory. See Section 8.6, "Adding JARs to the Domain /lib Directory".
Note:
Oracle documentation and WebLogic Server utilities use the term library to refer to both Java EE libraries and optional packages. Optional packages are called out only when necessary.
Specification VersionIdentifies the version number of the specification (for example, the Java EE specification version) to which a shared Java EE library or optional package conforms. Implementation VersionIdentifies the version number of the actual code implementation for the library or package. For example, this would correspond to the actual revision number or release number of your code. Note that you must also provide a specification version in order to specify an implementation version.
As a best practice, Oracle recommends that you always include version information (a specification version, or both an implementation and specification version) when creating shared Java EE libraries. Creating and updating version information as you develop shared components allows you to deploy multiple versions of those components simultaneously for testing. If you include no version information, or fail to increment the version string, then you must undeploy existing libraries before you can deploy the newer one. See Section 9.7, "Deploying Shared Java EE Libraries and Dependent Applications". Versioning information in the referencing application determines the library and package version requirements for that application. Different applications can require different versions of a given library or package. For example, a production application may require a specific version of a library, because only that library has been fully
Creating Shared Java EE Libraries and Optional Packages 9-3
approved for production use. An internal application may be configured to always use a minimum version of the same library. Applications that require no specific version can be configured to use the latest version of the library. Section 9.3, "Referencing Shared Java EE Libraries in an Enterprise Application".
Both are registered with WebLogic Server instances at deployment time. Both support an optional implementation version and specification version string. Applications that reference shared Java EE libraries and optional packages can specify required versions for the shared files. Optional packages can reference other optional packages, and shared Java EE libraries can reference other shared Java EE libraries.
Optional packages differ from shared Java EE Libraries in the following basic ways:
Optional packages are plain JAR files, whereas shared Java EE libraries can be plain JAR files, Java EE Enterprise applications, or standalone Java EE modules (EJB and Web applications). This means that libraries can have valid Java EE and WebLogic Server deployment descriptors. Any deployment descriptors in an optional package JAR file are ignored. Any Java EE application or module can reference an optional package (using META-INF/MANIFEST.MF), whereas only Enterprise applications and Web applications can reference a shared Java EE library (using weblogic-application.xml or weblogic.xml)
In general, use shared Java EE libraries when you need to share one or more EJB, Web application or Enterprise application modules among different Enterprise applications. Use optional packages when you need to share one or more classes (packaged in a JAR file) among different Java EE modules. Plain JAR files can be shared either as libraries or optional packages. Use optional packages if you want to:
Share a plain JAR file among multiple Java EE modules Reference shared JAR files from other shared JARs Share plain JARs as described by the Java EE 5.0 specification
Use shared Java EE libraries to share a plain JAR file if you only need to reference the JAR file from one or more Enterprise applications, and you do not need to maintain strict compliance with the Java EE specification. Oracle documentation and WebLogic Server utilities use the term shared Java EE library to refer to both libraries and optional packages. Optional packages are called out only when necessary.
Note:
Assemble the shared Java EE library into a valid, deployable Java EE module or Enterprise application. The library must have the required Java EE deployment descriptors for the Java EE module or for an Enterprise application. See Section 9.2.1, "Assembling Shared Java EE Library Files".
2.
Assemble optional package classes into a working directory. See Section 9.2.2, "Assembling Optional Package Class Files".
3.
Create and edit the MANIFEST.MF file for the shared Java EE library to specify the name and version string information. See Section 9.2.3, "Editing Manifest Attributes for Shared Java EE Libraries".
4.
Package the shared Java EE library for distribution and deployment. See Section 9.2.4, "Packaging Shared Java EE Libraries for Distribution and Deployment".
An EJB module, either an exploded directory or packaged in a JAR file. A Web application module, either an exploded directory or packaged in a WAR file. An Enterprise application, either an exploded directory or packaged in an EAR file. A plain Java class or classes packaged in a JAR file. A shared Java EE library referenced from another library. (See Section 9.8, "Web Application Shared Java EE Library Information".)
You must ensure that context roots in Web application modules of the shared Java EE library do not conflict with context roots in the referencing Enterprise application. If necessary, you can configure referencing applications to override a library's context root. See Section 9.3, "Referencing Shared Java EE Libraries in an Enterprise Application". Shared Java EE libraries cannot be nested. For example, if you are deploying an EAR as a shared Java EE library, the entire EAR must be designated as the library. You cannot designate individual Java EE modules within the EAR as separate, named libraries. As with any other Java EE module or Enterprise application, a shared Java EE library must be configured for deployment to the target servers or clusters in your domain. This means that a library requires valid Java EE deployment descriptors as well as WebLogic Server-specific deployment descriptors and an optional deployment plan. See Deploying Applications to Oracle WebLogic Server.
Oracle recommends packaging shared Java EE libraries as Enterprise applications, rather than as standalone Java EE modules. This is because the URI of a standalone module is derived from the deployment name, which can change depending on how the module is deployed. By default, WebLogic Server uses the deployment archive
filename or exploded archive directory name as the deployment name. If you redeploy a standalone shared Java EE library from a different file or location, the deployment name and URI also change, and referencing applications that use the wrong URI cannot access the deployed library. If you choose to deploy a shared Java EE library as a standalone Java EE module, always specify a known deployment name during deployment and use that name as the URI in referencing applications.
Create a working directory for the new optional package. For example:
mkdir /apps/myOptPkg
2.
Copy the compiled class files into the working directory, creating the appropriate package sudirectories as necessary. For example:
mkdir -p /apps/myOptPkg/org/myorg/myProduct cp /build/classes/myOptPkg/org/myOrg/myProduct/*.class /apps/myOptPkg/org/myOrg/myProduct
3.
If you already have a JAR file that you want to use as an optional package, extract its contents into the working directory so that you can edit the manifest file:
cd /apps/myOptPkg jar xvf /build/libraries/myLib.jar
Table 91 Attribute
Manifest Attributes for Java EE Libraries Description An optional string value that identifies the name of the shared Java EE library. Referencing applications must use the exact Extension-Name value to use the library. As a best practice, always specify an Extension-Name value for each library. If you do not specify an extension name, one is derived from the deployment name of the library. Default deployment names are different for archive and exploded archive deployments, and they can be set to arbitrary values in the deployment command.
Extension-Name
Specification-Version
An optional String value that defines the specification version of the shared Java EE library. Referencing applications can optionally specify a required Specification-Version for a library; if the exact specification version is not available, deployment of the referencing application fails. The Specification-Version uses the following format: Major/minor version format, with version and revision numbers separated by periods (such as "9.0.1.1") Referencing applications can be configured to require either an exact version of the shared Java EE library, a minimum version, or the latest available version. The specification version for a shared Java EE library can also be set at the command-line when deploying the library, with some restrictions. See Section 9.7, "Deploying Shared Java EE Libraries and Dependent Applications".
Implementation-Version
An optional String value that defines the code implementation version of the shared Java EE library. You can provide an Implementation-Version only if you have also defined a Specification-Version. Implementation-Version uses the following formats:
Major/minor version format, with version and revision numbers separated by periods (such as "9.0.1.1") Text format, with named versions (such as "9011Beta" or "9.0.1.1.B")
If you use the major/minor version format, referencing applications can be configured to require either an exact version of the shared Java EE library, a minimum version, or the latest available version. If you use the text format, referencing applications must specify the exact version of the library. The implementation version for a shared Java EE library can also be set at the command-line when deploying the library, with some restrictions. See Section 9.7, "Deploying Shared Java EE Libraries and Dependent Applications".
Open (or create) the manifest file using a text editor. For the example shared Java EE library, you would use the commands:
cd /apps/myLibrary mkdir META-INF emacs META-INF/MANIFEST.MF
In the text editor, add a string value to specify the name of the shared Java EE library. For example:
Extension-Name: myExtension
Applications that reference the library must specify the exact Extension-Name in order to use the shared files.
3.
As a best practice, enter the optional version information for the shared Java EE library. For example:
Extension-Name: myExtension Specification-Version: 2.0 Implementation-Version: 9.0.0
Using the major/minor format for the version identifiers provides the most flexibility when referencing the library from another application (see Table 92)
Note:
Although you can optionally specify the Specification-Version and Implementation-Version at the command line during deployment, Oracle recommends that you include these strings in the MANIFEST.MF file. Including version strings in the manifest ensures that you can deploy new versions of the library alongside older versions. See Section 9.7, "Deploying Shared Java EE Libraries and Dependent Applications".
weblogic-application.xml Elements for Referencing a Shared Java EE Library Description library-ref is the parent element in which you define a reference to a shared Java EE library. Enclose all other elements within library-ref. A required string value that specifies the name of the shared Java EE library to use. library-name must exactly match the value of the Extension-Name attribute in the library's manifest file. (See Table 92.) An optional String value that defines the required specification version of the shared Java EE library. If this element is not set, the application uses a matching library with the highest specification version. If you specify a string value using major/minor version format, the application uses a matching library with the highest specification version that is not below the configured value. If all available libraries are below the configured specification-version, the application cannot be deployed. The required version can be further constrained by using the exact-match element, described below. If you specify a String value that does not use major/minor versioning conventions (for example, 9.2BETA) the application requires a shared Java EE library having the exact same string value in the Specification-Version attribute in the library's manifest file. (See Table 92.)
library-name
specification-version
implementation-version
An optional String value that specifies the required implementation version of the shared Java EE library. If this element is not set, the application uses a matching library with the highest implementation version. If you specify a string value using major/minor version format, the application uses a matching library with the highest implementation version that is not below the configured value. If all available libraries are below the configured implementation-version, the application cannot be deployed. The required implementation version can be further constrained by using the exact-match element, described below. If you specify a String value that does not use major/minor versioning conventions (for example, 9.2BETA) the application requires a shared Java EE library having the exact same string value in the Implementation-Version attribute in the library's manifest file. (See Table 92.)
exact-match
An optional boolean value that determines whether the application should use a shared Java EE library with a higher specification or implementation version than the configured value, if one is available. By default this element is false, which means that WebLogic Server uses higher-versioned libraries if they are available. Set this element to true to require the exact matching version as specified in the specification-version and implementation-version elements. An optional String value that provides an alternate context root to use for a Web application shared Java EE library. Use this element if the context root of a library conflicts with the context root of a Web application in the referencing Java EE application. Web application shared Java EE library refers to special kind of library: a Web application that is referenced by another Web application. See Section 9.8, "Web Application Shared Java EE Library Information".
context-root
For example, this simple entry in the weblogic-application.xml descriptor references a shared Java EE library, myLibrary:
<library-ref> <library-name>myLibrary</library-name> </library-ref>
In the above example, WebLogic Server attempts to find a library name myLibrary when deploying the dependent application. If more than one copy of myLibrary is registered, WebLogic Server selects the library with the highest specification version. If multiple copies of the library use the selected specification version, WebLogic Server selects the copy having the highest implementation version.
This example references a shared Java EE library with a requirement for the specification version:
<library-ref> <library-name>myLibrary</library-name> <specification-version>2.0</specification-version> </library-ref>
In the above example, WebLogic Server looks for matching libraries having a specification version of 2.0 or higher. If multiple libraries are at or above version 2.0, WebLogic Server examines the selected libraries that use Float values for their implementation version and selects the one with the highest version. Note that WebLogic Server ignores any selected libraries that have a non-Float value for the implementation version. This example references a shared Java EE library with both a specification version and a non-Float value implementation version:
<library-ref> <library-name>myLibrary</library-name> <specification-version>2.0</specification-version> <implementation-version>81Beta</implementation-version> </library-ref>
In the above example, WebLogic Server searches for a library having a specification version of 2.0 or higher, and having an exact match of 81Beta for the implementation version. The following example requires an exact match for both the specification and implementation versions:
<library-ref> <library-name>myLibrary</library-name> <specification-version>2.0</specification-version> <implementation-version>8.1</implementation-version> <exact-match>true</exact-match> </library-ref>
The following example specifies a context-root with the library reference. When a WAR library reference is made from weblogic-application.xml, the context-root may be specified with the reference:
<library-ref> <library-name>myLibrary</library-name> <context-root>mywebapp</context-root> </library-ref>
Table 93 Element
weblogic-application.xml Elements for Overriding a Shared Java EE Library Description An optional String value that overrides the context-root elements declared in libraries. In the absence of this element, the library's context-root is used. Only a referencing application (for example, a user application) can override the context-root elements declared in its libraries.
context-root
override-value
An optional String value that specifies the value of the library-context-root-override element when overriding the context-root elements declared in libraries. In the absence of these elements, the library's context-root is used.
The following example specifies a context-root-override, which in turn, refers to the old context-root specified in one of its libraries and the new context-root that should be used instead. (override):
<library-ref> <library-name>myLibrary</library-name> <specification-version>2.0</specification-version> <implementation-version>8.1</implementation-version> <exact-match>true</exact-match> </library-ref> <library-context-root-override> <context-root>webapp</context-root> <override-value>mywebapp</override-value> </library-context-root-override>
In the above example, the current application refers to myLibrary, which contains a Web application with a context-root of webapp. The only way to override this reference is to declare a library-context-root-override that maps webapp to mywebapp.
Table 94 Attribute
Manifest Attributes for Referencing Optional Packages Description A required String value that defines a logical name for an optional package dependency. You can use multiple values in the Extension-List attribute to designate multiple optional package dependencies. For example: Extension-List: dependency1 dependency2
[logical_name-]Extension-Name A required string value that identifies the name of an optional package dependency. This value must match the Extension-Name attribute defined in the optional package's manifest file. If you are referencing multiple optional packages from a single archive, prepend the appropriate logical name to the Extension-Name attribute. For example: dependency1-Extension-Name: myOptPkg [logical_ name-]Specification-Version An optional String value that defines the required specification version of an optional package. If this element is not set, the archive uses a matching package with the highest specification version. If you include a specification-version value using the major/minor version format, the archive uses a matching package with the highest specification version that is not below the configured value. If all available package are below the configured specification-version, the archive cannot be deployed. If you specify a String value that does not use major/minor versioning conventions (for example, 9.2BETA) the archive requires a matching optional package having the exact same string value in the Specification-Version attribute in the package's manifest file. (See Table 92.) If you are referencing multiple optional packages from a single archive, prepend the appropriate logical name to the Specification-Version attribute. [logical_ name-]Implementation-Version An optional String value that specifies the required implementation version of an optional package. If this element is not set, the archive uses a matching package with the highest implementation version. If you specify a string value using the major/minor version format, the archive uses a matching package with the highest implementation version that is not below the configured value. If all available libraries are below the configured implementation-version, the application cannot be deployed. If you specify a String value that does not use major/minor versioning conventions (for example, 9.2BETA) the archive requires a matching optional package having the exact same string value in the Implementation-Version attribute in the package's manifest file. (See Table 92.) If you are referencing multiple optional packages from a single archive, prepend the appropriate logical name to the Implementation-Version attribute.
For example, this simple entry in the manifest file for a dependent archive references two optional packages, myAppPkg and my3rdPartyPkg:
Extension-List: internal 3rdparty internal-Extension-Name: myAppPkg 3rdparty-Extension-Name: my3rdPartyPkg
This example requires a specification version of 2.0 or higher for myAppPkg, and an exact match for the implementation version of my3rdPartyPkg:
Extension-List: internal 3rdparty internal-Extension-Name: myAppPkg 3rdparty-Extension-Name: my3rdPartyPkg internal-Specification-Version: 2.0 3rdparty-Implementation-Version: 8.1GA
By default, when WebLogic Server deploys an application or module and it cannot resolve a reference in the application's manifest file to an optional package, WebLogic Server prints a warning, but continues with the deployment anyway. You can change this behavior by setting the system property weblogic.application.RequireOptionalPackages to true when you start WebLogic Server, either at the command line or in the command script file from which you start the server. Setting this system property to true means that WebLogic Server does not attempt to deploy an application or module if it cannot resolve an optional package reference in its manifest file.
Section 9.5.1, "Using weblogic.appmerge from the CLI" Section 9.5.2, "Using weblogic.appmerge as an Ant Task"
Example:
Creating Shared Java EE Libraries and Optional Packages 9-13
Integrating Shared Java EE Libraries with the Split Development Directory Environment
9.6 Integrating Shared Java EE Libraries with the Split Development Directory Environment
The BuildXMLGen includes a -librarydir option to generate build targets that include one or more shared Java EE library directories. See Section 3.5, "Generating a Basic build.xml File Using weblogic.BuildXMLGen". The wlcompile and wlappc Ant tasks include a librarydir attribute and library element to specify one or more shared Java EE library directories to include in the classpath for application builds. See Section 4, "Building Applications in a Split Development Directory".
For simplicity, this section uses the term Web application library when referring to a shared Java EE library that is referenced only by another Web application.
In particular:
Web application libraries can only be referenced by other Web applications. Rather than update the weblogic-application.xml file, Web applications reference Web application libraries by updating the weblogic.xml deployment descriptor file. The elements are almost same as those described in Section 9.3, "Referencing Shared Java EE Libraries in an Enterprise Application"; the only difference is that the <context-root> child element of <library-ref> is ignored in this case. You cannot reference any other type of shared Java EE library (EJB, Enterprise application, or plain JAR file) from the weblogic.xml deployment descriptor file of a Web application.
Other than these differences in how they are referenced, the way to create, package, and deploy a Web application library is the same as that of a standard shared Java EE library.
When multiple libraries are present, the CLASSPATH/resource path precedence order follows the order in which the library-refs elements appear in the weblogic.xml file.
getLibraryRuntimes() returns the shared Java EE libraries referenced in the weblogic-application.xml file. getOptionalPackageRuntimes() returns the optional packages referenced in the manifest file.
For more information, see the Oracle WebLogic Server API Reference.
When the Enterprise application is deployed, WebLogic Server reads its weblogic-application.xml deployment descriptor. WebLogic Server reads the deployment descriptors of any referenced shared Java EE libraries. Depending on the type of library (Enterprise application, EJB, or Web application), the read file might be weblogic-application.xml, weblogic.xml, weblogic-ejb-jar.xml, and so on. WebLogic Server first merges the referenced shared Java EE library deployment descriptors (in the order in which they are referenced, one at a time) and then merges the weblogic-application.xml file of the referencing Enterprise application on top of the library descriptor files.
3.
As a result of the way the descriptor files are merged, the elements in the descriptors of the shared Java EE libraries referenced first in the weblogic-application.xml file have precedence over the ones listed last. The elements of the Enterprise application's descriptor itself have precedence over all elements in the library descriptors. For example, assume that an Enterprise application called myApp references two shared Java EE libraries (themselves packaged as Enterprise applications): myLibA and myLibB, in that order. Both the myApp and myLibA applications include an EJB module called myEJB, and both the myLibA and myLibB applications include an EJB module called myOtherEJB. Further assume that once the myApp application is deployed, a client invokes, via the myApp application, the myEJB module. In this case, WebLogic Server actually invokes the EJB in the myApp application (rather than the one in myLibA) because modules in
the referencing application have higher precedence over modules in the referenced applications. If a client invokes the myOtherEJB EJB, then WebLogic Server invokes the one in myLibA, because the library is referenced first in the weblogic-application.xml file of myApp, and thus has precedence over the EJB with the same name in the myLibB application.
Use shared Java EE Libraries when you want to share one or more Java EE modules (EJBs, Web applications, Enterprise applications, or plain Java classes) with multiple Enterprise applications. If you need to deploy a standalone Java EE module, such as an EJB JAR file, as a shared Java EE library, package the module within an Enterprise application. Doing so avoids potential URI conflicts, because the library URI of a standalone module is derived from the deployment name. If you choose to deploy a shared Java EE library as a standalone Java EE module, always specify a known deployment name during deployment and use that name as the URI in referencing applications. Use optional packages when multiple Java EE archive files need to share a set of Java classes. If you have a set of classes that must be available to applications in an entire domain, and you do not frequently update those classes (for example, if you need to share 3rd party classes in a domain), use the domain /lib subdirectory rather than using shared Java EE libraries or optional packages. Classes in the /lib subdirectory are made available (within a separate system level classloader) to all Java EE applications running on WebLogic Server instances in the domain. Always specify a specification version and implementation version, even if you do not intend to enforce version requirements with dependent applications. Specifying versions for shared Java EE libraries enables you to deploy multiple versions of the shared files for testing. Always specify an Extension-Name value for each shared Java EE library. If you do not specify an extension name, one is derived from the deployment name of the library. Default deployment names are different for archive and exploded archive deployments, and they can be set to arbitrary values in the deployment command When developing a Web application for deployment as a shared Java EE library, use a unique context root. If the context root conflicts with the context root in a dependent Java EE application, use the context-root element in the EAR's weblogic-application.xml deployment descriptor to override the library's context root. Package shared Java EE libraries as archive files for delivery to Administrators or deployers in your organization. Deploy libraries from exploded archive directories during development to allow for easy updates and repeated redeployments. Deploy shared Java EE libraries to all WebLogic Server instances on which you want to deploy dependent applications and archives. If a library is not registered with a server instance on which you want to deploy a referencing application, deployment of the referencing application fails.
10
10
Section 10.1, "Understanding Application Life Cycle Events" Section 10.2, "Registering Events in weblogic-application.xml" Section 10.3, "Programming Basic Life Cycle Listener Functionality" Section 10.4, "Examples of Configuring Life Cycle Events with and without the URI Parameter" Section 10.5, "Understanding Application Life Cycle Event Behavior During Re-deployment" Section 10.6, "Programming Application Version Life Cycle Events"
Note:
Application-scoped startup and shutdown classes have been deprecated as of release 9.0 of WebLogic Server. The information in this chapter about startup and shutdown classes is provided only for backwards compatibility. Instead, you should use life cycle listener events in your applications.
Listenersattachable to any event. Possible methods for Listeners are: public void preStart(ApplicationLifecycleEvent evt) {} The preStart event is the beginning of the prepare phase, or the start of the application deployment process. public void postStart(ApplicationLifecycleEvent evt) {} The postStart event is the end of the activate phase, or the end of the application deployment process. The application is deployed. public void preStop(ApplicationLifecycleEvent evt) {} The preStop event is the beginning of the deactivate phase, or the start of the application removal or undeployment process.
Programming Application Life Cycle Events 10-1
public void postStop(ApplicationLifecycleEvent evt) {} The postStop event is the end of the remove phase, or the end of the application removal or undeployment process.
Application-scoped shutdown classes have been deprecated as of release 9.0 of WebLogic Server. Use life cycle listeners instead.
For Startup and Shutdown classes, you only implement a main{} method. If you implement any of the methods provided for Listeners, they are ignored. No remove{} method is provided in the ApplicationLifecycleListener, because the events are only fired at startup time during deployment (prestart and poststart) and shutdown during undeployment (prestop and poststop).
listenerUsed to register user defined application life cycle listeners. These are classes that extend the abstract base class weblogic.application.ApplicationLifecycleListener. shutdownUsed to register user-defined shutdown classes. startupUsed to register user-defined startup classes.
Example 101 illustrates how you override the ApplicationLifecycleListener. In this example, the public class MyListener extends ApplicationLifecycleListener.
Example 101
MyListener
import weblogic.application.ApplicationLifecycleListener; import weblogic.application.ApplicationLifecycleEvent; public class MyListener extends ApplicationLifecycleListener { public void preStart(ApplicationLifecycleEvent evt) { System.out.println ("MyListener(preStart) -- we should always see you.."); } // preStart public void postStart(ApplicationLifecycleEvent evt) { System.out.println ("MyListener(postStart) -- we should always see you.."); } // postStart public void preStop(ApplicationLifecycleEvent evt) { System.out.println ("MyListener(preStop) -- we should always see you.."); } // preStop public void postStop(ApplicationLifecycleEvent evt) { System.out.println ("MyListener(postStop) -- we should always see you.."); } // postStop public static void main(String[] args) { System.out.println ("MyListener(main): in main .. we should never see you.."); } // main }
Example 102 illustrates how you implement the shutdown class. The shutdown class is attachable to preStop and postStop events. In this example, the public class MyShutdown does not extend ApplicationLifecycleListener because a shutdown class declared in the weblogic-application.xml deployment descriptor does not need to depend on any WebLogic Server-specific interfaces.
Example 102 MyShutdown
import weblogic.application.ApplicationLifecycleListener; import weblogic.application.ApplicationLifecycleEvent; public class MyShutdown { public static void main(String[] args) { System.out.println ("MyShutdown(main): in main .. should be for post-stop"); } // main }
Example 103 illustrates how you implement the startup class. The startup class is attachable to preStart and postStart events. In this example, the public class MyStartup does not extend ApplicationLifecycleListener because a startup class declared in the weblogic-application.xml deployment descriptor does not need to depend on any WebLogic Server-specific interfaces.
Example 103 MyStartup
import weblogic.application.ApplicationLifecycleListener; import weblogic.application.ApplicationLifecycleEvent; public class MyStartup { public static void main(String[] args) { System.out.println ("MyStartup(main): in main .. should be for pre-start"); } // main }
Examples of Configuring Life Cycle Events with and without the URI Parameter
Follow the basic programming steps outlined in Section 10.3, "Programming Basic Life Cycle Listener Functionality". Within the listener element add the run-as-principal-name element to specify the user who has privileges to startup and/or shutdown the event. For example:
<listener> <listener-class>myApp.MySessionAttributeListenerClass</listener-class> <run-as-principal-name>javajoe</run-as-principal-name> </listener>
The identity specified here should be a valid user name in the system. If run-as-principal-name is not specified, the deployment initiator user identity will be used as the run-as identity for the execution of the application life cycle listener.
10.4 Examples of Configuring Life Cycle Events with and without the URI Parameter
The following examples illustrate how you configure application life cycle events in the weblogic-application.xml deployment descriptor file. The URI parameter is not required. You can place classes anywhere in the application $CLASSPATH. However, you must ensure that the class locations are defined in the $CLASSPATH. You can place listeners in APP-INF/classes or APP-INF/lib, if these directories are present in the EAR. In this case, they are automatically included in the $CLASSPATH. The following example illustrates how you configure application life cycle events using the URI parameter. In this case, the archive foo.jar contains the classes and exists at the top level of the EAR file. For example: myEar/foo.jar.
Example 104 Configuring Application Life Cycle Events Using the URI Parameter
<listener> <listener-class>MyListener</listener-class> <listener-uri>foo.jar</listener-uri> </listener> <startup> <startup-class>MyStartup</startup-class> <startup-uri>foo.jar</startup-uri> </startup> <shutdown> <shutdown-class>MyShutdown</shutdown-class> <shutdown-uri>foo.jar</shutdown-uri> </shutdown>
The following example illustrates how you configure application life cycle events without using the URI parameter.
Example 105 Parameter Configuring Application Life Cycle Events without Using the URI
preStop{} postStop{} Initialization takes place. (Unless you have set debug flags, you do not see the initialization.) preStart{} postStart{}
Section 10.6.1, "Understanding Application Version Life Cycle Event Behavior" Section 10.6.2, "Types of Application Version Life Cycle Events" Section 10.6.3, "Example of Production Deployment Sequence When Using Application Version Life Cycle Events"
For both static and dynamic deployments. Using either anonymous ID or using user identity. Only if the current application is versioned; otherwise, version life cycle events are ignored. for all application versions, including the version that registers the listener. Use the ApplicationVersionLifecycleEvent.isOwnVersion method to determine if an event belongs to a particular version. See the ApplicationVersionLifecycleEvent class for more information on types of version life cycle events.
public void preDeploy(ApplicationVersionLifecycleEvent evt) The preDeloy event is invoked when an application version deploy or redeploy operation is initiated.
public void postDeploy(ApplicationVersionLifecycleEvent evt) The postDeloy event is invoked when an application version is deployed or redeployed successfully.
public void preUndeploy(ApplicationVersionLifecycleEvent evt) The preUndeloy event is invoked when an application version undeploy operation is initiated.
public void postDelete(ApplicationVersionLifecycleEvent evt) The postDelete event is invoked when an application version is deleted.
Note: A postDelete event is only fired after the entire application version is completely removed. It does not include a partial undeploy, such as undeploying a module or from a subset of targets.
10.6.3 Example of Production Deployment Sequence When Using Application Version Life Cycle Events
The following table provides an example of a deployment (V1), production redeployment (V2), and an undeploy (V2).
Table 101 Sequence of Deployment Actions and Application Version Life Cycle Events Time Version V1 preDeploy(V1) invoked. Deployment starts. Application life cycle listeners for V1 are registered. V1 is active version, Deployment is complete. postDeploy(V1) invoked. Version V2
Deployment action
Deployment of Version V1 T0 T1 T2 T3 T4
Table 101 (Cont.) Sequence of Deployment Actions and Application Version Life Cycle Events Deployment action Time T5 Production Redeployment T6 of Version V2 T7 T8 T9 T10 If deploy(V2) succeeds, V1 ceases to be active version. Application version listener receives preDeploy(V1). Deployment starts. Application life cycle listeners for V2 are registered. If deploy(V2) succeeds, V2 replaces V1 as active version. Deployment is complete. T11 postDeploy(V2) invoked. Note: This event occurs even if the deployment fails. T12 Application version listener gets postDeploy(V2). If deploy(V2) fails, V1 remains active. Application listeners gets postDeploy(V2). If deploy(V2) succeeds, V1 begins retirement. Application listeners for V1 are unregistered. V1 is retired. preUndeploy(v2) invoked. Application listeners gets preUndeploy(v2) invoked. Undeployment begins. V2 is no longer active version. Application version listeners for V2 are unregistered. Undeployment is complete. If the entire application is undeployed, postDelete(V2) is invoked. Note: This event occurs even if the undeployment fails. Version V1 Application Listeners gets postDeploy(V1). preDeploy(V2) invoked. Version V2
T13 T14 T15 T16 Undeployment of V2 T17 T18 T19 T20 T21 T22 T23
11
11
The following sections describe how to use the context propagation APIs in your applications:
Section 11.1, "Understanding Context Propagation" Section 11.2, "Programming Context Propagation: Main Steps" Section 11.3, "Programming Context Propagation in a Client" Section 11.4, "Programming Context Propagation in an Application"
11-1
Table 111
Interfaces and classes of the WebLogic Context Propagation API Description Main context propagation interface used to tag applications with data and propagate that information via application requests. WorkContextMaps is part of the client or application's JNDI environment and can be accessed through JNDI by looking up the name java:comp/WorkContextMap. Interface used for marshaling and unmarshaling the user data that is passed along with an application. This interface has four implementing classes for marshaling and unmarshaling the following types of data: simple 8-bit ASCII contexts (AsciiWorkContext), long contexts (LongWorkContext), Serializable context (SerializableWorkContext), and String contexts (StringWorkContext). WorkContext has one subinterface, PrimitiveWorkContext, used to specifically marshal and unmarshal a single primitive data item.
WorkContext Interface
WorkContextOutput/Inpu Interfaces representing primitive streams used for marshaling and unmarshaling, t Interfaces respectively, WorkContext implementations. PropagationMode Interface Defines the propagation properties of WorkContexts. Specifies whether the WorkContext is propagated locally, across threads, across RMI invocations, across JMS queues and topics, or across SOAP messages. If not specified, default is to propagate data across remote and local calls in the same thread. PrimitiveContextFactor Convenience class for creating WorkContexts that contain only primitive data. y Class
For the complete API documentation about context propagation, see the weblogic.workarea Javadocs.
Update your client application to create the WorkContextMap and WorkContext objects and then add user data to the context. See Section 11.3, "Programming Context Propagation in a Client".
2.
If your client application is standalone (rather than running in a Java EE component deployed to WebLogic Server), ensure that its CLASSPATH includes the Java EE application client, also called the thin client. See Programming Stand-alone Clients for Oracle WebLogic Server.
3.
Update your application (EJB, Web Service, servlet, and so on) to also create a WorkContextMap and then get the context and user data that you added from the client application. See Section 11.4, "Programming Context Propagation in an Application".
For the complete API documentation about context propagation, see the weblogic.workarea Javadocs.
Note:
See Getting Started With JAX-WS Web Services for Oracle WebLogic Server for information on creating Web Services and client applications that invoke them.
package examples.workarea.client; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import javax.xml.rpc.Stub; import javax.naming.InitialContext; import javax.naming.NamingException; import weblogic.workarea.WorkContextMap; import weblogic.workarea.WorkContext; import weblogic.workarea.PrimitiveContextFactory; import weblogic.workarea.PropagationMode; import weblogic.workarea.PropertyReadOnlyException; /** * This is a simple standalone client application that invokes the * the <code>sayHello</code> operation of the WorkArea Web service. * */ public class Main { public final static String SESSION_ID= "session_id_key"; public static void main(String[] args) throws ServiceException, RemoteException, NamingException, PropertyReadOnlyException{ WorkAreaService service = new WorkAreaService_Impl(args[0] + "?WSDL"); WorkAreaPortType port = service.getWorkAreaPort(); WorkContextMap map = (WorkContextMap)new InitialContext().lookup("java:comp/WorkContextMap"); WorkContext stringContext = PrimitiveContextFactory.create("A String Context"); // Put a string context map.put(SESSION_ID, stringContext, PropagationMode.SOAP); try { String result = null; result = port.sayHello("Hi there!"); System.out.println( "Got result: " + result ); } catch (RemoteException e) { throw e; } } }
The following code shows how to import the needed weblogic.workarea.* classes, interfaces, and exceptions:
import import import import import weblogic.workarea.WorkContextMap; weblogic.workarea.WorkContext; weblogic.workarea.PrimitiveContextFactory; weblogic.workarea.PropagationMode; weblogic.workarea.PropertyReadOnlyException;
11-3
The following code shows how to create a WorkContextMap by doing a JNDI lookup of the context propagation-specific JNDI name java:comp/WorkContextMap:
WorkContextMap map = (WorkContextMap) new InitialContext().lookup("java:comp/WorkContextMap");
The following code shows how to create a WorkContext by using the PrimitiveContextFactory. In this example, the WorkContext consists of the simple String value A String Context. This String value is the user data that is passed to the invoked Web Service.
WorkContext stringContext = PrimitiveContextFactory.create("A String Context");
Finally, the following code shows how to add the context data, along with the key SESSION_ID, to the WorkContextMap and associate it with the current thread. The PropagationMode.SOAP constant specifies that the propagation happens over SOAP messages; this is because the client is invoking a Web Service.
map.put(SESSION_ID, stringContext, PropagationMode.SOAP);
See Getting Started With JAX-WS Web Services for Oracle WebLogic Server for information on creating Web Services and client applications that invoke them.
package examples.workarea; import javax.naming.InitialContext; // Import the Context Propagation classes import weblogic.workarea.WorkContextMap; import weblogic.workarea.WorkContext; import javax.jws.WebMethod; import javax.jws.WebService; import weblogic.jws.WLHttpTransport; @WebService(name="WorkAreaPortType", serviceName="WorkAreaService", targetNamespace="http://example.org") @WLHttpTransport(contextPath="workarea", serviceUri="WorkAreaService", portName="WorkAreaPort") /** * This JWS file forms the basis of simple WebLogic * Web Service with a single operation: sayHello * */ public class WorkAreaImpl { public final static String SESSION_ID = "session_id_key"; @WebMethod()
public String sayHello(String message) { try { WorkContextMap map = (WorkContextMap) new InitialContext().lookup("java:comp/WorkContextMap"); WorkContext localwc = map.get(SESSION_ID); System.out.println("local context: " + localwc); System.out.println("sayHello: " + message); return "Here is the message: '" + message + "'"; } catch (Throwable t) { return "error"; } } }
The following code shows how to import the needed context propagation APIs; in this case, only the WorkContextMap and WorkContext interfaces are needed:
import weblogic.workarea.WorkContextMap; import weblogic.workarea.WorkContext;
The following code shows how to create a WorkContextMap by doing a JNDI lookup of the context propagation-specific JNDI name java:comp/WorkContextMap:
WorkContextMap map = (WorkContextMap) new InitialContext().lookup("java:comp/WorkContextMap");
The following code shows how to get context's user data from the current WorkContextMap using a key; in this case, the key is the same one that the client application set when it invoked the Web Service: SESSION_ID:
WorkContext localwc = map.get(SESSION_ID);
11-5
12
12
Section 12.1, "Overview of Using JavaMail with WebLogic Server Applications" Section 12.2, "Understanding JavaMail Configuration Files" Section 12.3, "Configuring JavaMail for WebLogic Server" Section 12.4, "Sending Messages with JavaMail" Section 12.5, "Reading Messages with JavaMail"
The weblogic.jar also contains the Java Activation Framework (JAF) package, which JavaMail requires. The javax.mail package includes providers for Internet Message Access protocol (IMAP) and Simple Mail Transfer Protocol (SMTP) mail servers. Sun has a separate POP3 provider for JavaMail, which is not included in weblogic.jar. You can download the POP3 provider from Sun and add it to the WebLogic Server classpath if you want to use it.
Import the JNDI (naming), JavaBean Activation, and JavaMail packages. You will also need to import java.util.Properties:
import import import import import java.util.*; javax.activation.*; javax.mail.*; javax.mail.internet.*; javax.naming.*;
2.
3.
If you need to override the properties you set for the Session in the Administration Console, create a java.util.Properties object and add the properties you want to override. Then call getInstance() to get a new Session object with the new properties.
Properties props = new Properties(); props.put("mail.transport.protocol", "smtp"); props.put("mail.smtp.host", "mailhost"); // use mail address from HTML form for from address props.put("mail.from", emailAddress); Session session2 = session.getInstance(props); 4.
Construct a MimeMessage. In the following example, to, subject, and messageTxt are String variables containing input from the user.
Message msg = new MimeMessage(session2); msg.setFrom(); msg.setRecipients(Message.RecipientType.TO, InternetAddress.parse(to, false)); msg.setSubject(subject); msg.setSentDate(new Date()); // Content is stored in a MIME multi-part message // with one body part MimeBodyPart mbp = new MimeBodyPart(); mbp.setText(messageTxt); Multipart mp = new MimeMultipart(); mp.addBodyPart(mbp); msg.setContent(mp);
5.
The JNDI lookup can throw a NamingException on failure. JavaMail can throw a MessagingException if there are problems locating transport classes or if communications with the mail host fails. Be sure to put your code in a try block and catch these exceptions.
Import the JNDI (naming), JavaBean Activation, and JavaMail packages. You will also need to import java.util.Properties:
import java.util.*; import javax.activation.*; import javax.mail.*; Programming JavaMail with WebLogic Server 12-3
3.
If you need to override the properties you set for the Session in the Administration Console, create a Properties object and add the properties you want to override. Then call getInstance() to get a new Session object with the new properties:
Properties props = new Properties(); props.put("mail.store.protocol", "pop3"); props.put("mail.pop3.host", "mailhost"); Session session2 = session.getInstance(props);
4.
Get a Store object from the Session and call its connect() method to connect to the mail server. To authenticate the connection, you need to supply the mailhost, username, and password in the connect method:
Store store = session.getStore(); store.connect(mailhost, username, password);
5.
Get the default folder, then use it to get the INBOX folder:
Folder folder = store.getDefaultFolder(); folder = folder.getFolder("INBOX");
6.
7.
Operate on messages in the Message array. The Message class has methods that allow you to access the different parts of a message, including headers, flags, and message contents.
Reading messages from an IMAP server is similar to reading messages from a POP3 server. With IMAP, however, the JavaMail API provides methods to create and manipulate folders and transfer messages between them. If you use an IMAP server, you can implement a full-featured, Web-based mail client with much less code than if you use a POP3 server. With POP3, you must provide code to manage a message store via WebLogic Server, possibly using a database or file system to represent folders.
13
13
The following sections contain information on additional WebLogic Server programming topics:
Section 13.1, "Using Threads in WebLogic Server" Section 13.2, "Using the Work Manager API for Lower-Level Threading" Section 13.3, "Programming Applications for WebLogic Server Clusters"
Applications that create their own threads do not scale well. Threads in the JVM are a limited resource that must be allocated thoughtfully. Your applications may break or cause WebLogic Server to thrash when the server load increases. Problems such as deadlocks and thread starvation may not appear until the application is under a heavy load. Multithreaded modules are complex and difficult to debug. Interactions between application-generated threads and WebLogic Server threads are especially difficult to anticipate and analyze.
In some situations, creating threads may be appropriate, in spite of these warnings. For example, an application that searches several repositories and returns a combined result set can return results sooner if the searches are done asynchronously using a new thread for each repository instead of synchronously using the main client thread. If you must use threads in your application code, create a pool of threads so that you can control the number of threads your application creates. Like a JDBC connection pool, you allocate a given number of threads to a pool, and then obtain an available thread from the pool for your runnable class. If all threads in the pool are in use, wait until one is returned. A thread pool helps avoid performance issues and allows you to optimize the allocation of threads between WebLogic Server execution threads and your application. Be sure you understand where your threads can deadlock and handle the deadlocks when they occur. Review your design carefully to ensure that your threads do not compromise the security system.
To avoid undesirable interactions with WebLogic Server threads, do not let your threads call into WebLogic Server modules. For example, do not use enterprise beans or servlets from threads that you create. Application threads are best used for independent, isolated tasks, such as conversing with an external service with a TCP/IP connection or, with proper locking, reading or writing to files. A short-lived thread that accomplishes a single purpose and ends (or returns to the thread pool) is less likely to interfere with other threads. Avoid creating daemon threads in modules that are packaged in applications deployed on WebLogic Server. When you create a daemon thread in an application module such as a Servlet, you will not be able to redeploy the application because the daemon thread created in the original deployment will remain running. Be sure to test multithreaded code under increasingly heavy loads, adding clients even to the point of failure. Observe the application performance and WebLogic Server behavior and then add checks to prevent failures from occurring in production.
A
A
The following sections describe Enterprise application deployment descriptors: application.xml (a Java EE standard deployment descriptor) and weblogic-application.xml (a WebLogic-specific application deployment descriptor). With Java EE annotations, the standard application.xml deployment descriptor is optional. Annotations simplify the application development process by allowing developers to specify within the Java class itself how the application component behaves in the container, requests for dependency injection, and so on. Annotations are an alternative to deployment descriptors that were required by older versions of Enterprise applications (Java EE 1.4 and earlier). See Chapter 7, "Using Java EE Annotations and Dependency Injection" The weblogic-application.xml file is also optional if you are not using any WebLogic Server extensions.
Section A.1, "weblogic-application.xml Deployment Descriptor Elements" Section A.2, "weblogic-application.xml Schema" Section A.3, "application.xml Schema"
A.1.1 weblogic-application
The weblogic-application element is the root element of the application deployment descriptor. The following table describes the elements you can define within a weblogic-application element.
A-1
Table A1
Element <ejb>
Required? Optional
Description Contains information that is specific to the EJB modules that are part of a WebLogic application. Currently, one can use the ejb element to specify one or more application level caches that can be used by the application's entity beans. For more information on the elements you can define within the ejb element, see Section A.1.2, "ejb".
<xml>
Optional
Contains information about parsers and entity mappings for XML processing that is specific to this application. For more information on the elements you can define within the xml element, see Section A.1.4, "xml".
<jdbc-connection -pool>
Optional
Unbounded
Zero or more. Specifies an application-scoped JDBC connection pool. For more information on the elements you can define within the jdbc-connection-pool element, see Section A.1.5, "jdbc-connection-pool".
<security>
Optional
Specifies security information for the application. For more information on the elements you can define within the security element, see Section A.1.6, "security".
<application-par am>
Optional
Unbounded
Zero or more. Used to specify un-typed parameters that affect the behavior of container instances related to the application. The parameters listed here are currently supported. Also, these parameters in weblogic-application.xml can determine the default encoding to be used for requests and for responses.
webapp.encoding.defaultCan be set to a string representing an encoding supported by the JDK. If set, this defines the default encoding used to process servlet requests and servlet responses. This setting is ignored if webapp.encoding.usevmdefault is set to true. This value is also overridden for request streams by the input-charset element of weblogic.xml. webapp.encoding.usevmdefaultCan be set to true or false. If true, the system property file.encoding is used to define the default encoding.
The following parameter is used to affect the behavior of Web applications that are contained in this application.
webapp.getrealpath.accept_context_pathThis is a compatibility switch that may be set to true or false. If set to true, the context path of Web applications is allowed in calls to the servlet API getRealPath.
Example: <application-param> <param-name>webapp.encoding.default </param-name> <param-value>UTF8</param-value> </application-param> For more information on the elements you can define within the application-param element, see Section A.1.7, "application-param".
Required? Optional
Description A classloader-structure element allows you to define the organization of classloaders for this application. The declaration represents a tree structure that represents the classloader hierarchy and associates specific modules with particular nodes. A module's classes are loaded by the classloader that its associated with this element. Example: <classloader-structure> <module-ref> <module-uri>ejb1.jar</module-uri> </module-ref> </classloader-structure> <classloader-structure> <module-ref> <module-uri>ejb2.jar</module-uri> </module-ref> </classloader-structure> For more information on the elements you can define within the classloader-structure element, see Section A.1.8, "classloader-structure".
<listener>
Optional
Unbounded
Zero or more. Used to register user-defined application lifecycle listeners. These are classes that extend the abstract base class weblogic.application.ApplicationLifecycleListe ner. For more information on the elements you can define within the listener element, see Section A.1.9, "listener".
<singleton-servi ce>
Optional
Unbounded
Zero or more. Used to register user-defined singleton services. These are classes that implement the interface weblogic.cluster.singleton.SingletonService. For more information on the elements you can define within the singleton-service element, see Section A.1.10, "singleton-service".
<startup>
Optional
Unbounded
Zero or more. Used to register user-defined startup classes. For more information on the elements you can define within the startup element, see Section A.1.11, "startup". Note: Application-scoped startup and shutdown classes have been deprecated as of release 9.0 of WebLogic Server. Instead, you should use lifecycle listener events in your applications. For details, see Chapter 10, "Programming Application Life Cycle Events"
<shutdown>
Optional
Unbounded
Zero or more. Used to register user defined shutdown classes. For more information on the elements you can define within the shutdown element, see Section A.1.12, "shutdown". Note: Application-scoped startup and shutdown classes have been deprecated as of release 9.0 of WebLogic Server. Instead, you should use lifecycle listener events in your applications. For details, see Chapter 10, "Programming Application Life Cycle Events."
A-3
Element <module>
Required? Optional
Description Represents a single WebLogic application module, such as a JMS or JDBC module. This element has the following child elements:
nameThe name of the module. typeThe type of module. Valid values are JMS, JDBC, or Interception. pathThe path of the XML file that fully describes the module, relative to the root of the Enterprise application.
The following example shows how to specify a JMS module called Workflows, fully described by the XML file jms/Workflows-jms.xml: <module> <name>Workflows</name> <type>JMS</type> <path>jms/Workflows-jms.xml</path> </module> <library-ref> Optional Unbounded A reference to a shared Java EE library. For more information on the elements you can define within the library element, see Section A.1.15, "library-ref". <fair-share-requ est> Optional Unbounded Specifies a fair share request class, which is a type of Work Manager request class. In particular, a fair share request class specifies the average percentage of thread-use time required to process requests. The <fair-share-request> element can take the following child elements:
nameThe name of the fair share request class. fair-shareAn integer representing the average percentage of thread-use time.
See "Using Work Managers to Optimize Scheduled Work". <response-time-r equest> Optional Unbounded Specifies a response time request class, which is a type of Work manager class. In particular, a response time request class specifies a response time goal in milliseconds. The <response-time-request> element can take the following child elements:
nameThe name of the response time request class. goal-msThe integer response time goal.
Required? Optional
Description Specifies a context request class, which is a type of Work manager class. In particular, a context request class assigns request classes to requests based on context information, such as the current user or the current user's group. The <context-request> element can take the following child elements:
nameThe name of the context request class. context-caseAn element that describes the context.
The <context-case> element can itself take the following child elements:
user-name or group-nameThe user or group to which the context applies. request-class-nameThe name of the request class.
See "Using Work Managers to Optimize Scheduled Work". <max-threads-con straint> Optional Unbounded Specifies a max-threads-constraint Work Manager constraint. A Work Manager constraint defines minimum and maximum numbers of threads allocated to execute requests and the total number of requests that can be queued or executing before WebLogic Server begins rejecting requests. The max-threads constraint limits the number of concurrent threads executing requests from the constrained work set. The <max-threads-constraint> element can take the following child elements:
nameThe name of the max-thread-constraint. Either count or pool-nameThe integer maximum number of concurrent threads, or the name of a connection pool which determines the maximum.
See "Using Work Managers to Optimize Scheduled Work". <min-threads-con straint> Optional Unbounded Specifies a min-threads-constraint Work Manager constraint. A Work Manager constraint defines minimum and maximum numbers of threads allocated to execute requests and the total number of requests that can be queued or executing before WebLogic Server begins rejecting requests. The min-threads constraint guarantees a number of threads the server will allocate to affected requests to avoid deadlocks. The <min-threads-constraint> element can take the following child elements:
A-5
Element <capacity>
Required? Optional
Description Specifies a capacity Work Manager constraint. A Work Manager constraint defines minimum and maximum numbers of threads allocated to execute requests and the total number of requests that can be queued or executing before WebLogic Server begins rejecting requests. The capacity constraint causes the server to reject requests only when it has reached its capacity. The <capacity> element can take the following child elements:
See "Using Work Managers to Optimize Scheduled Work". <work-manager> Optional Unbounded Specifies the Work Manager that is associated with the application. For more information on the elements you can define within the work-manager element, see Section A.1.13, "work-manager". See "Using Work Managers to Optimize Scheduled Work" for detailed information on Work Managers. <application-adm in-mode-trigger> Optional Unbounded Specifies the number of stuck threads needed to bring the application into administration mode. You can specify the following child elements:
max-stuck-thread-timeThe maximum amount of time, in seconds, that a thread should remain stuck. stuck-thread-countNumber of stuck threads that triggers the stuck thread work manager.
<session-descrip tor>
Optional
Unbounded
Specifies a list of configuration parameters for servlet sessions. For more information on the elements you can define within the <session-descriptor> element, see Section A.1.14, "session-descriptor".
<library-context -root-override>
Optional
Unbounded
Zero or more. Used to override the context-root of a Web module specified in the deployment descriptor of a library referenced by this application. For more information on the elements you can define within the <library-context-root-override> element, see Section A.1.16, "library-context-root-override".
<component-facto ry-class-name>
Optional
Used to enable the Spring extension by setting this element to org.springframework.jee.interfaces.SpringCompo nentFactory. This element exists in EJB, Web, and application descriptors. A module-level descriptor overwrites an application-level descriptor. If set to null (default), the Spring extension is disabled.
Required? Optional
Description Used for filtering ClassLoader configuration. Specifies a list of packages for classes that must always be loaded from the application. Used for filtering ClassLoader configuration. Specifies a list of resources that must always be loaded from the application, even if the resources are found in the system classloader. Note that the resource loading behavior is different from the resource loading behavior when <prefer-application-packages> is used. In that case, application resources get a preference over system resources. The resources captured in this element are never looked up in the system classloader.
Optional
<fast-swap>
Optional
Specifies whether FastSwap deployment is used to minimize redeployment since Java classes are redefined in-place without reloading the ClassLoader. For more information, see "Using FastSwap Deployment to Minimize Redeployment" in Deploying Applications to WebLogic Server. For information on the elements you can define within the <fast-swap> element, see Section A.1.17, "fast-swap".
A.1.2 ejb
The following table describes the elements you can define within an ejb element.
A-7
Table A2
Element <entity-cache>
Required? Optional
Description Zero or more. The entity-cache element is used to define a named application level cache that is used to cache entity EJB instances at runtime. Individual entity beans refer to the application-level cache that they must use, referring to the cache name. There is no restriction on the number of different entity beans that may reference an individual cache. To use application-level caching, you must specify the cache using the <entity-cache-ref> element of the weblogic-ejb-jar.xml descriptor. Two default caches named ExclusiveCache and MultiVersionCache are used for this purpose. An application may explicitly define these default caches to specify non-default values for their settings. Note that the caching-strategy cannot be changed for the default caches. By default, a cache uses max-beans-in-cache with a value of 1000 to specify its maximum size. Example: <entity-cache> <entity-cache-name>ExclusiveCache</entity-cache-name> <max-cache-size> <megabytes>50</megabytes> </max-cache-size> </entity-cache> For more information on the elements you can define within the entity-cache element, see Section A.1.2.1, "entity-cache".
<start-mbds-withapplication
Optional
Allows you to configure the EJB container to start Message Driven BeanS (MDBS) with the application. If set to true, the container starts MDBS as part of the application. If set to false, the container keeps MDBS in a queue and the server starts them as soon as it has started listening on the ports.
A.1.2.1 entity-cache
The following table describes the elements you can define within a entity-cache element.
Table A3
Element
Required?
Description Specifies a unique name for an entity bean cache. The name must be unique within an ear file and may not be the empty string. Example: <entity-cache-name>ExclusiveCache</entity-cache-n ame>
<entity-cache-name> Required
<max-beans-in-cache Optional 1 > If you specify this element, you cannot also specify <max-cache-s ize>. <max-cache-size> Optional If you specify this element, you cannot also specify <max-beans-i n-cache>. 1
Specifies the maximum number of entity beans that are allowed in the cache. If the limit is reached, beans may be passivated. This mechanism does not take into account the actual amount of memory that different entity beans require. This element can be set to a value of 1 or greater. Default Value: 1000 Used to specify a limit on the size of an entity cache in terms of memory sizeexpressed either in terms of bytes or megabytes. A bean provider should provide an estimate of the average size of a bean in the weblogic-ejb-jar.xml descriptor if the bean uses a cache that specifies its maximum size using the max-cache-size element. By default, a bean is assumed to have an average size of 100 bytes. For more information on the elements you can define within the ejb element, see Section A.1.3, "max-cache-size".
1 1
Specifies the maximum SQL queries that can be present in the entity cache at a given moment. Specifies the general strategy that the EJB container uses to manage entity bean instances in a particular application level cache. A cache buffers entity bean instances in memory and associates them with their primary key value. The caching-strategy element can only have one of the following values:
ExclusiveCaches a single bean instance in memory for each primary key value. This unique instance is typically locked using the EJB container's exclusive locking when it is in use, so that only one transaction can use the instance at a time. MultiVersionCaches multiple bean instances in memory for a given primary key value. Each instance can be used by a different transaction concurrently.
A.1.3 max-cache-size
The following table describes the elements you can define within a max-cache-size element.
A-9
Table A4
Element <bytes>
Required? You must specify either <bytes> or <megabytes> You must specify either <bytes> or <megabytes>
Description The size of an entity cache in terms of memory size, expressed in bytes.
<megabytes>
A.1.4 xml
The following table describes the elements you can define within an xml element.
Table A5 xml Elements Maximum Number in File 1
Element <parser-factory>
Required? Optional
Description The parent element used to specify a particular XML parser or transformer for an enterprise application. For more information on the elements you can define within the parser-factory element, see Section A.1.4.1, "parser-factory".
<entity-mapping>
Optional
Unbounded
Zero or More. Specifies the entity mapping. This mapping determines the alternative entity URI for a given public or system ID. The default place to look for this entity URI is the lib/xml/registry directory. For more information on the elements you can define within the entity-mapping element, see Section A.1.4.2, "entity-mapping".
A.1.4.1 parser-factory
The following table describes the elements you can define within a parser-factory element.
Table A6 Element
parser-factory Elements Required? Optional Maximum Number in File 1 Description Allows you to set the SAXParser Factory for the XML parsing required in this application only. This element determines the factory to be used for SAX style parsing. If you do not specify the saxparser-factory element setting, the configured SAXParser Factory style in the Server XML Registry is used. Default Value: Server XML Registry setting
<saxparser-factory>
<document-builder-fact ory>
Optional
Allows you to set the Document Builder Factory for the XML parsing required in this application only. This element determines the factory to be used for DOM style parsing. If you do not specify the document-builder-factory element setting, the configured DOM style in the Server XML Registry is used. Default Value: Server XML Registry setting
<transformer-factory>
Optional
Allows you to set the Transformer Engine for the style sheet processing required in this application only. If you do not specify a value for this element, the value configured in the Server XML Registry is used. Default value: Server XML Registry setting.
A.1.4.2 entity-mapping
The following table describes the elements you can define within an entity-mapping element.
Table A7 entity-mapping Elements Maximum Number in File 1 1 1 1 1
Element
Required?
Description Specifies the name for this entity mapping. Specifies the public ID of the mapped entity. Specifies the system ID of the mapped entity. Specifies the entity URI for the mapped entity. Legal values are:
<entity-mapping-nam Required e> <public-id> <system-id> <entity-uri> <when-to-cache> Optional Optional Optional Optional
The default value is cache-on-reference. <cache-timeout-inte Optional rval> 1 Specifies the integer value in seconds.
A-11
A.1.5 jdbc-connection-pool
Note:
The jdbc-connection-pool element is deprecated. To define a data source in your Enterprise application, you can package a JDBC module with the application. For more information, see "Configuring JDBC Application Modules for Deployment" in Configuring and Managing JDBC for Oracle WebLogic Server.
The following table describes the elements you can define within a jdbc-connection-pool element.
Table A8 jdbc-connection-pool Elements Maximum Number in File Description 1 1 Specifies the JNDI name in the application-specific JNDI tree. Specifies the connection parameters that define overrides for default connection factory settings.
user-nameOptional. The user-name element is used to override UserName in the JDBCDataSourceFactoryMBean. urlOptional. The url element is used to override URL in the JDBCDataSourceFactoryMBean. driver-class-nameOptional. The driver-class-name element is used to override DriverName in the JDBCDataSourceFactoryMBean. connection-paramsZero or more. parameter+ (param-value, param-name)One or more
For more information on the elements you can define within the connection-factory element, see Section A.1.5.1, "connection-factory". <pool-params> Optional 1 Defines parameters that affect the behavior of the pool. For more information on the elements you can define within the pool-params element, see Section A.1.5.2, "pool-params". <driver-params> Optional 1 Sets behavior on WebLogic Server drivers. For more information on the elements you can define within the driver-params element, see Section A.1.5.3, "driver-params". <acl-name> Optional 1 DEPRECATED.
A.1.5.1 connection-factory
The following table describes the elements you can define within a connection-factory element.
Table A9
Element <factory-name>
Required? Optional
Description Specifies the name of a JDBCDataSourceFactoryMBean in the config.xml file. Specifies the connection properties for the connection factory. Elements that can be defined for the connection-properties element are:
<connection-properties> Optional
user-nameOptional. Used to override UserName in the JDBCDataSourceFactoryMBean. passwordOptional. Used to override Password in the JDBCDataSourceFactoryMBean. urlOptional. Used to override URL in the JDBCDataSourceFactoryMBean. driver-class-nameOptional. Used to override DriverName in the JDBCDataSourceFactoryMBean connection-paramsZero or more. Used to set parameters which will be passed to the driver when making a connection. Example:
A.1.5.2 pool-params
The following table describes the elements you can define within a pool-params element.
A-13
Table A10
Element <size-params>
Required? Optional
Description Defines parameters that affect the number of connections in the pool.
initial-capacityOptional. The initial-capacity element defines the number of physical database connections to create when the pool is initialized. The default value is 1. max-capacityOptional. The max-capacity element defines the maximum number of physical database connections that this pool can contain. Note that the JDBC Driver may impose further limits on this value. The default value is 1. capacity-incrementOptional. The capacity-increment element defines the increment by which the pool capacity is expanded. When there are no more available physical connections to service requests, the pool creates this number of additional physical database connections and adds them to the pool. The pool ensures that it does not exceed the maximum number of physical connections as set by max-capacity. The default value is 1. shrinking-enabledOptional. The shrinking-enabled element indicates whether or not the pool can shrink back to its initial-capacity when connections are detected to not be in use. shrink-period-minutesOptional. The shrink-period-minutes element defines the number of minutes to wait before shrinking a connection pool that has incrementally increased to meet demand. The shrinking-enabled element must be set to true for shrinking to take place. shrink-frequency-secondsOptional. highest-num-waitersOptional. highest-num-unavailableOptional.
A-15
Element <xa-params>
Required? Optional
debug-levelOptional. Integer. The debug-level element defines the debugging level for XA operations. The default value is 0. keep-conn-until-tx-complete-enabledOptional. Boolean. If you set the keep-conn-until-tx-complete-enabled element to true, the XA connection pool associates the same XA connection with the distributed transaction until the transaction completes. end-only-once-enabledOptional. Boolean. If you set the end-only-once-enabled element to true, the XAResource.end() method is only called once for each pending XAResource.start() method. recover-only-once-enabledOptional. Boolean. If you set the recover-only-once-enabled element to true, recover is only called one time on a resource. tx-context-on-close-neededOptional. Set the tx-context-on-close-needed element to true if the XA driver requires a distributed transaction context when closing various JDBC objects (for example, result sets, statements, connections, and so on). If set to true, the SQL exceptions that are thrown while closing the JDBC objects in no transaction context are swallowed. new-conn-for-commit-enabledOptional. Boolean. If you set the new-conn-for-commit-enabled element to true, a dedicated XA connection is used for commit/rollback processing of a particular distributed transaction. prepared-statement-cache-sizeDeprecated. Optional. Use the prepared-statement-cache-size element to set the size of the prepared statement cache. The size of the cache is a number of prepared statements created from a particular connection and stored in the cache for further use. Setting the size of the prepared statement cache to 0 turns it off.
<xa-params> Continued...
Optional
Note: Prepared-statement-cache-size is deprecated. Use cache-size in driver-params/prepared-statement. See Section A.1.5.3, "driver-params" for more information.
keep-logical-conn-open-on-releaseOptional. B oolean. Set the keep-logical-conn-open-on-release element to true, to keep the logical JDBC connection open when the physical XA connection is returned to the XA connection pool. The default value is false. local-transaction-supportedOptional. Boolean. Set the local-transaction-supported to true if the XA driver supports SQL with no global transaction; otherwise, set it to false. The default value is false. resource-health-monitoring-enabledOptional. Set the resource-health-monitoring-enabled element to true to enable JTA resource health monitoring for this connection pool.
Required? Optional
Description
xa-set-transaction-timeoutOptional. Used in: xa-params Example: <xa-set-transaction-timeout> true </xa-set-transaction-timeout> xa-transaction-timeoutOptional. When the xa-set-transaction-timeout value is set to true, the transaction manager invokes setTransactionTimeout on the resource before calling XAResource.start. The Transaction Manager passes the global transaction timeout value. If this attribute is set to a value greater than 0, then this value is used in place of the global transaction timeout. Default value: 0 Used in: xa-params Example: <xa-transaction-timeout> 30 </xa-transaction-timeout> rollback-localtx-upon-conncloseOptional. When the rollback-localtx-upon-connclose element is true, the connection pool calls rollback() on the connection before putting it back in the pool. Default value: false Used in: xa-params Example: <rollback-localtx-upon-connclose> true </rollback-localtx-upon-connclose>
Sets the number of seconds to delay before creating each physical database connection. Some database servers cannot handle multiple requests for connections in rapid succession. This property allows you to build in a small delay to let the database server catch up. This delay occurs both during initial pool creation and during the lifetime of the pool whenever a physical database connection is created. Enables JDBC connection leak profiling. A connection leak occurs when a connection from the pool is not closed explicitly by calling the close() method on that connection. When connection leak profiling is active, the pool stores the stack trace at the time the connection object is allocated from the pool and given to the client. When a connection leak is detected (when the connection object is garbage collected), this stack trace is reported. This element uses extra resources and will likely slowdown connection pool operations, so it is not recommended for production use.
A-17
Element
Required?
Description
Defines whether, when, and how connections in a pool is checked to make sure they are still alive. table-nameOptional. The table-name element defines a table in the schema that can be queried. check-on-reserve-enabledOptional. If the check-on-reserve-enabled element is set to true, then the connection will be tested each time before it is handed out to a user. check-on-release-enabledOptional. If the check-on-release-enabled element is set to true, then the connection will be tested each time a user returns a connection to the pool. refresh-minutesOptional. If the refresh-minutes element is defined, a trigger is fired periodically (based on the number of minutes specified). This trigger checks each connection in the pool to make sure it is still valid. check-on-create-enabledOptional. If set to true, then the connection will be tested when it is created. connection-reserve-timeout-secondsOptional. Number of seconds after which the call to reserve a connection from the pool will timeout. connection-creation-retry-frequency-seconds Optional. The frequency of retry attempts by the pool to establish connections to the database. inactive-connection-timeout-secondsOptional. The number of seconds of inactivity after which reserved connections will forcibly be released back into the pool. test-frequency-secondsOptional. The number of seconds between database connection tests. After every test-frequency-seconds interval, unused database connections are tested using table-name. Connections that do not pass the test will be closed and reopened to re-establish a valid physical database connection. If table-name is not set, the test will not be performed. init-sqlOptional. Specifies a SQL query that automatically runs when a connection is created.
1 1
This is an internal setting. Controls whether a connection is removed from the pool when the application asks for the underlying vendor connection object. Enabling this attribute has an impact on performance; it essentially disables the pooling of connections (as connections are removed from the pool and replaced with new connections).
A.1.5.3 driver-params
The following table describes the elements you can define within a driver-params element.
Table A11
Element <statement>
Required? Optional
Description Defines the driver-params statement. Contains the following optional element: profiling-enabled. Example: <statement> <profiling-enabled>true </profiling-enabled> </statement>
<prepared-statemen Optional t
Enables the running of JDBC prepared statement cache profiling. When enabled, prepared statement cache profiles are stored in external storage for further analysis. This is a resource-consuming feature, so it is recommended that you turn it off on a production server. The default value is false.
profiling-enabledOptional. cache-profiling-thresholdOptional. The cache-profiling-threshold element defines a number of statement requests after which the state of the prepared statement cache is logged. This element minimizes the output volume. This is a resource-consuming feature, so it is recommended that you turn it off on a production server. cache-sizeOptional. The cache-size element returns the size of the prepared statement cache. The size of the cache is a number of prepared statements created from a particular connection and stored in the cache for further use. parameter-logging-enabledOptional. During SQL roundtrip profiling it is possible to store values of prepared statement parameters. The parameter-logging-enabled element enables the storing of statement parameters. This is a resource-consuming feature, so it is recommended that you turn it off on a production server. max-parameter-lengthOptional. During SQL roundtrip profiling it is possible to store values of prepared statement parameters. The max-parameter-length element defines maximum length of the string passed as a parameter for JDBC SQL roundtrip profiling. This is a resource-consuming feature, so you should limit the length of data for a parameter to reduce the output volume. cache-typeOptional.
A-19
Element
Required?
Description Specifies whether to enable row prefetching between a client and WebLogic Server for each ResultSet. When an external client accesses a database using JDBC through Weblogic Server, row prefetching improves performance by fetching multiple rows from the server to the client in one server access. WebLogic Server ignores this setting and does not use row prefetching when the client and WebLogic Server are in the same JVM
Specifies the number of result set rows to prefetch for a client. The optimal value depends on the particulars of the query. In general, increasing this number increases performance, until a particular value is reached. At that point further increases do not result in any significant increase in performance. Note: Typically you will not see any increase in performance after 100 rows. The default value should be adequate for most situations. Valid values for this element are between 2 and 65536. The default value is 48.
Specifies the data chunk size for streaming data types, which are pulled from WebLogic Server to the client as needed.
A.1.6 security
The following table describes the elements you can define within a security element.
Table A12 security Elements Maximum Number in File 1 Unbounded
Description Names a security realm to be used by the application. If none is specified, the system default realm is used Declares a mapping between an application-wide security role and one or more WebLogic Server principals. Example: <security-role-assignment> <role-name> PayrollAdmin </role-name> <principal-name> Tanya </principal-name> <principal-name> Fred </principal-name> <principal-name> system </principal-name> </security-role-assignment>
A.1.7 application-param
The following table describes the elements you can define within a application-param element.
Table A13 Element <description> <param-name> <param-value> application-param Elements Required? Optional Required Required Maximum Number in File 1 1 1 Description Provides a description of the application parameter. Defines the name of the application parameter. Defines the value of the application parameter.
A.1.8 classloader-structure
The following table describes the elements you can define within a classloader-structure element.
Table A14 Element <module-ref> classloader-structure Elements Required? Optional Maximum Number in File Unbounded Description The following list describes the elements you can define within a module-ref element:
<classloader-structure> Optional
Unbounded
Allows for arbitrary nesting of classloader structures for an application. However, for this version of WebLogic Server, the depth is restricted to three levels.
A.1.9 listener
The following table describes the elements you can define within a listener element.
A-21
listener Elements Required? Required Optional Maximum Number in File Description 1 1 Name of the user's implementation of ApplicationLifecycleListener. A JAR file within the EAR that contains the implementation. If you do not specify the listener-uri, it is assumed that the class is visible to the application. Specific a user identity to startup and shutdown application lifecycle events. The identity specified here should be a valid user name in the system. If run-as-principal-name is not specified, the deployment initiator user identity will be used as the run-as identity for the execution of the application lifecycle listener. Note: If the run-as-principal-name identity defined for the application lifecycle listener is an administrator, the application deployer must have administrator privileges; otherwise, deployment will fail.
<listener-class> <listener-uri>
<run-as-principal-name> Optional
A.1.10 singleton-service
The following table describes the elements you can define within a singleton-service element.
Table A16 singleton-service Elements Maximum Number in File 1 1
Description Defines the name of the class to be run when the application is being deployed. Defines a JAR file within the EAR that contains the singleton-service. If singleton-uri is not defined, then its assumed that the class is visible to the application.
A.1.11 startup
The following table describes the elements you can define within a startup element.
Note::
Application-scoped startup and shutdown classes have been deprecated as of release 9.0 of WebLogic Server. Instead, you should use lifecycle listener events in your applications. For details, see Chapter 10, "Programming Application Life Cycle Events."
Table A17
Description Defines the name of the class to be run when the application is being deployed. Defines a JAR file within the EAR that contains the startup-class. If startup-uri is not defined, then its assumed that the class is visible to the application.
A.1.12 shutdown
The following table describes the elements you can define within a shutdown element.
Note: : Application-scoped startup and shutdown classes have been deprecated as of release 9.0 of WebLogic Server. Instead, you should use lifecycle listener events in your applications. For details, see Chapter 10, "Programming Application Life Cycle Events."
shutdown Elements Maximum Required Optional Number in File Required Optional 1 1 Description Defines the name of the class to be run when the application is undeployed. Defines a JAR file within the EAR that contains the shutdown-class. If you do not define the shutdown-uri element, it is assumed that the class is visible to the application.
<shutdown-class> <shutdown-uri>
A.1.13 work-manager
The following table describes the elements you can define within a work-manager element. See "Using Work Managers to Optimize Scheduled Work" for examples and information on Work Managers.
A-23
Table A19
Element <name>
Required? Required
Description The name of the Work Manager. See the description of the <response-time-request> element in Section A.1.1, "weblogic-application" for information on this child element of <work-manager>. If you specify this element, you cannot also specify <fair-share-request-class>, <context-request-class>, or <request-class-name>.
See the description of the <fair-share-request> element in Section A.1.1, "weblogic-application" for information on this child element of <work-manager>. If you specify this element, you cannot also specify <response-time-request-class>, <context-request-class>, or <request-class-name>.
<context-request-class>
Optional
See the description of the <context-request> element in Section A.1.1, "weblogic-application" for information on this child element of <work-manager>. If you specify this element, you cannot also specify <fair-share-request-class>, <response-time-request-class>, or <request-class-name>.
<request-class-name>
Optional
The name of the request class. If you specify this element, you cannot also specify <fair-share-request-class>, <context-request-class>, or <response-time-request-class>.
<min-threads-constraint> Optional
See the description of the <min-threads-constraint> element in Section A.1.1, "weblogic-application" for information on this child element of <work-manager>. If you specify this element, you cannot also specify <min-threads-constraint-name>.
The name of the min-threads constraint. If you specify this element, you cannot also specify <min-threads-constraint>.
<max-threads-constraint> Optional
See the description of the <max-threads-constraint> element in Section A.1.1, "weblogic-application" for information on this child element of <work-manager>. If you specify this element, you cannot also specify <max-threads-constraint-name>.
The name of the max-threads constraint. If you specify this element, you cannot also specify <max-threads-constraint>.
Element <capacity>
Required? Optional
Description See the description of the <capacity> element in Section A.1.1, "weblogic-application" for information on this child element of <work-manager>. If you specify this element, you cannot also specify <capacity-name>.
<capacity-name>
Optional
The name of the thread capacity constraint. If you specify this element, you cannot also specify <capacity>.
Used to specify a Stuck Thread Work Manager component that can shut down the Work Manager in response to stuck threads. You can specify the following child elements:
max-stuck-thread-timeThe maximum amount of time, in seconds, that a thread should remain stuck. stuck-thread-countNumber of stuck threads that triggers the stuck thread work manager.
If you specify this element, you cannot also specify <ignore-stuck-threads>. <ignore-stuck-threads> Optional 1 Specifies whether the Work Manager should ignore stuck threads and never shut down even if threads become stuck. If you specify this element, you cannot also specify <work-manager-shutdown-trigger>.
A.1.14 session-descriptor
The following table describes the elements you can define within a session-descriptor element.
Table A20 session-descriptor Elements Maximum Number in File 1
Element <timeout-secs>
Required? Optional
Description Specifies the number of seconds after which the session times out. Default value is 3600 seconds.
Specifies the number of seconds of the invalidation trigger interval. Default value is 60 seconds.
<debug-enabled>
Optional
Specifies whether debugging is enabled for HTTP sessions. Default value is false.
<id-length>
Optional
A-25
Element <tracking-enabled>
Required? Optional
Description Specifies whether session tracking is enabled between HTTP requests. Default value is true.
<cache-size>
Optional
Specifies the cache size for JDBC and file persistent sessions. Default value is 1028.
<max-in-memory-sessions> Optional
Specifies the maximum sessions limit for memory/replicated sessions. Default value is -1, or unlimited.
<cookies-enabled>
Optional
Specifies the Web application container should set cookies in the response. Default value is true.
<cookie-name>
Optional
Specifies the name of the cookie that tracks sessions. Default name is JSESSIONID.
<cookie-path>
Optional
<cookie-domain>
Optional
<cookie-comment>
Optional
<cookie-secure>
Optional
Specifies whether the session tracking cookie is marked secure. Default value is false.
<cookie-max-age-secs>
Optional
Specifies that maximum age of the session tracking cookie. Default value is -1, or unlimited.
<persistent-store-type>
Optional
Specifies the type of storage for session persistence. You can specify the following values:
memoryDefault value. replicatedRequires clustering. replicated_if_clusteredDefaults to memory in non-clustered case. file jdbc cookie
Specifies the name of the cookie that holds the attribute name and values when using cookie-based session persistence. Default value is WLCOOKIE.
Element <persistent-store-dir>
Required? Optional
Description Specifies the name of the directory when using file-based session persistence. The directory is relative to the temporary directory defined for the Web application. Default value is session_db.
<persistent-store-pool>
Optional
1 1
Specifies the name of the JDBC connection pool when using jdbc-based session persistence. Specifies the name of the database table when using jdbc-based session persistence. Default value is wl_servlet_sessions.
<persistent-store-table> Optional
Alternative name for the wl_max_inactive_ interval column name when using jdbc-based session persistence. Required for certain databases that do not support long column names DEPRECATED Specifies whether URL rewriting is enabled. Default value is true.
1 1
Specifies whether WebLogic Server adds the following HTTP header to the response: Cache-control: no-cache=set-cookie This header specifies that proxy caches should not cache the cookies. Default value is true, which means that the header is NOT added. Set this element to false if you want the header added to the response.
Specifies whether WebLogic Server should encode the session ID in the path parameters. Default value is false.
Used to tag runtime information for different sessions. For example, set this element to username if you have a username attribute that is guaranteed to be unique. Specifies whether HTTP sessions are shared across multiple Web applications. Default value is false.
<sharing-enabled>
Optional
A.1.15 library-ref
The following table describes the elements you can define within a library-ref element. See Chapter 9, "Creating Shared Java EE Libraries and Optional Packages," for additional information and examples.
A-27
Table A21
Description Specifies the name of the referenced shared Java EE library. Specifies the minimum specification-version required. Specifies the minimum implementation-version required. Specifies whether there must be an exact match between the specification and implementation version that is specified and that of the referenced library. Default value is false.
<context-root>
Optional
Specifies the context-root of the referenced Web applications shared Java EE library.
A.1.16 library-context-root-override
The following table describes the elements you can define within a library-context-root-override element to override context-root elements within a referenced EAR library. See Section A.1.15, "library-ref". See Chapter 9, "Creating Shared Java EE Libraries and Optional Packages," for additional information and examples.
Table A22 library-context-root-override Elements Maximum Number in File 1
Element <context-root>
Required? Optional
Description Overrides the context-root elements declared in libraries. In the absence of this element, the library's context-root is used. Only a referencing application (for example, a user application) can override the context-root elements declared in its libraries.
<override-value>
Optional
Specifies the value of the library-context-root-override element when overriding the context-root elements declared in libraries. In the absence of these elements, the library's context-root is used.
A.1.17 fast-swap
The following table describes the elements you can define within a fast-swap element. For more information about FastSwap Deployment, see "Using FastSwap Deployment to Minimize Redeployment" in Deploying Applications to WebLogic Server.
application.xml Schema
Table A23
Description Set to true to enable FastSwap deployment in your application. FastSwap checks for changes in application classes when an incoming HTTP request is received. Subsequent HTTP requests arriving within the refresh-interval seconds will not trigger a check for changes. The first HTTP request arriving after the refresh-interval seconds have passed, will cause FastSwap to perform a class-change check again. FastSwap class redefinitions are performed asynchronously by redefinition tasks. They can be controlled and inspected using JMX interfaces. Specifies the number of redefinition tasks that will be retained by the FastSwap system. If the number of tasks exceeds this limit, older tasks are automatically removed.
A-29
application.xml Schema
B
B
The following sections describe tools for deploying applications and standalone modules to WebLogic Server:
Section B.1, "Overview of the wldeploy Ant Task" Section B.2, "Basic Steps for Using wldeploy" Section B.3, "Sample build.xml Files for wldeploy" Section B.4, "wldeploy Ant Task Attribute Reference"
Builds your application from source, using wlcompile, appc, and the Web Services Ant tasks. Creates, starts, and configures a new WebLogic Server domain, using the wlserver and wlconfig Ant tasks. Deploys a compiled application to the newly-created domain, using the wldeploy Ant task.
See Chapter 2, "Using Ant Tasks to Configure and Use a WebLogic Server Domain," for more information about wlserver and wlconfig. See Chapter 4, "Building Applications in a Split Development Directory," for information about wlcompile.
Set your environment. On Windows NT, execute the setWLSEnv.cmd command, located in the directory WL_HOME\server\bin, where WL_HOME is the top-level directory of your WebLogic Server installation. On UNIX, execute the setWLSEnv.sh command, located in the directory WL_ HOME/server/bin, where WL_HOME is the top-level directory of your WebLogic Server installation.
2.
In the staging directory, create the Ant build file (build.xml by default). If you want to use an Ant installation that is different from the one installed with WebLogic Server, start by defining the wldeploy Ant task definition:
wldeploy Ant Task Reference B-1
If necessary, add task definitions and calls to the wlserver and wlconfig tasks in the build script to create and start a new WebLogic Server domain. See Chapter 2, "Using Ant Tasks to Configure and Use a WebLogic Server Domain," for information about wlserver and wlconfig. Add a call to wldeploy to deploy your application to one or more WebLogic Server instances or clusters. See Section B.3, "Sample build.xml Files for wldeploy" and Section B.4, "wldeploy Ant Task Attribute Reference". Execute the Ant task or tasks specified in the build.xml file by typing ant in the staging directory, optionally passing the command a target argument:
prompt> ant
4.
5.
The following example shows a corresponding task to undeploy the application; the example shows that when you undeploy or redeploy an application, you do not specify the source archive file or exploded directory, but rather, just its deployed name.:
<target name="undeploy"> <wldeploy action="undeploy" verbose="true" debug="true" name="DeployExample" user="weblogic" password="weblogic" adminurl="t3://localhost:7001" targets="myserver" failonerror="false" /> </target>
The following example shows how to perform a partial redeploy of the application; in this case, just a single WAR file in the application is redeployed:
<target name="redeploy_partial"> <wldeploy action="redeploy" verbose="true" name="DeployExample" user="weblogic" password="weblogic" adminurl="t3://localhost:7001" targets="myserver" deltaFiles="examples/general/redeploy/SimpleImpl.war" /> </target>
The following example uses the nested <files> child element of wldeploy to specify a particular file in the application that should be undeployed:
<target name="undeploy_partial"> <wldeploy
action="undeploy" verbose="true" debug="true" name="DeployExample" user="weblogic" password="weblogic" adminurl="t3://localhost:7001" targets="myserver" failonerror="false"> <files dir="${current-dir}/output/redeployEAR/examples/general/redeploy" includes="SimpleImpl.jsp" /> </wldeploy> </target>
The following example shows how to deploy a Java EE library called myLibrary whose source files are located in the output/myLibrary directory:
<target name="deploy"> <wldeploy action="deploy" name="myLibrary" source="output/myLibrary" library="true" user="weblogic" password="weblogic" verbose="true" adminurl="t3://localhost:7001" targets="myserver" /> </target>
Attributes of the wldeploy Ant Task Description The deployment action to perform. Valid values are deploy, cancel, undeploy, redeploy, distribute, start, and stop. Data Type String
adminmode
Specifies that the deployment action puts the application into Administration mode. Administration mode restricts access to an application to a configured Administration channel. Valid values for this attribute are true and false. Default value is false, which means that by default the application is deployed in production mode so that all clients can access it immediately.
Boolean
adminurl
The URL of the Administration Server. The format of the value of this attribute is protocol://host:port, where protocol is either http or t3, host is the host on which the Administration Server is running, and port is the port which the Administration Server is listening. Note: In order to use the HTTP protocol, you must enable the http tunnelling option in the Administration Console.
String
allversions
Specifies that the action (redeploy, stop, and so on) applies to all versions of the application. Valid values for this attribute are true and false. The default value is false.
Boolean
altappdd
Specifies the name of an alternate Java EE deployment descriptor (application.xml) to use for deployment. If you do not specify this attribute, and you are deploying an Enterprise application, the default deployment descriptor is called application.xml and is located in the META-INF subdirectory of the main application directory or archive (specified by the source attribute.)
String
altwlsappdd
Specifies the name of an alternate WebLogic Server deployment descriptor (weblogic-application.xml) to use for deployment. If you do not specify this attribute, and you are deploying an Enterprise application, the default deployment descriptor is called weblogic-application.xml and is located in the META-INF subdirectory of the main application directory or archive (specified by the source attribute.)
String
The version identifier of the deployed application. Enable wldeploy debugging messages. Specifies whether to remove static files from a server's staging directory. This attribute is valid only for unarchived deployments, and only for applications deployed using stage mode. You must specify target servers when using this attribute. Specifying the deleteFiles attributes indicates that WebLogic Server should remove only those files that it copied to the staging area during deployment. This attribute can be used only in combination with action="redeploy". Because the deleteFiles attribute deletes all specified files, Oracle recommends that you use caution when using the deleteFiles attribute and that you do not use it in production environments. Valid values for this attribute are true and false. Default value is false.
deltaFiles
Specifies a comma- or space-separated list of files, relative to the root directory of the application, which are to be redeployed. Use this attribute only in conjunction with action="redeploy" to perform a partial redeploy of an application.
String
Table B1 (Cont.) Attributes of the wldeploy Ant Task Attribute enableSecurit yValidation externalStage Description Specifies whether or not to enable validation of security data. Valid values for this attribute are true and false. Default value is false. Specifies whether the deployment uses external_stage deployment mode. In this mode, the Ant task does not copy the deployment files to target servers; instead, you must ensure that deployment files have been copied to the correct subdirectory in the target servers' staging directories. You can specify only one of the following attributes: stage, nostage, or external_stage. If none is specified, the default deployment mode to Managed Servers is stage; the default mode to the Administration Server and in single-server cases is nostage. See "Controlling Deployment File Copying with Staging Modes". failonerror This is a global attribute used by WebLogic Server Ant tasks. It specifies whether the task should fail if it encounters an error during the build. Valid values for this attribute are true and false. Default value is true. graceful Stops the application after existing HTTP clients have completed their work. You can use this attribute only when stopping or undeploying an application, or in other words, you must also specify either the action="stop" or action="undeploy" attributes. Valid values for this attribute are true and false. Default value is false. id Identification used for obtaining status or cancelling the deployment. You assign a unique ID to an application when you deploy it, and then subsequently use the ID when redeploying, undeploying, stopping, and so on. If you do not specify this attribute, the Ant task assigns a unique ID to the application. ignoresessions This option immediately places the application into Administration mode without waiting for current HTTP sessions to complete. You can use this attribute only when stopping or undeploying an application, or in other words, you must also specify either the action="stop" or action="undeploy" attributes. Valid values for this attribute are true and false. Default value is false. libImplVer Specifies the implementation version of a Java EE library or optional package. This attribute can be used only if the library or package does not include a implementation version in its manifest file. You can specify this attribute only in combination with the library attribute. See Chapter 9, "Creating Shared Java EE Libraries and Optional Packages." library Identifies the deployment as a shared Java EE library or optional package. You must specify the library attribute when deploying or distributing any Java EE library or optional package. Valid values for this attribute are true and false. Default value is false. See Chapter 9, "Creating Shared Java EE Libraries and Optional Packages." libSpecVer Provides the specification version of a Java EE library or optional package. This attribute can be used only if the library or package does not include a specification version in its manifest file. You can specify this attribute only in combination with the library attribute. See Chapter 9, "Creating Shared Java EE Libraries and Optional Packages." String Boolean String Boolean String Boolean Boolean Boolean Data Type Boolean
Table B1 (Cont.) Attributes of the wldeploy Ant Task Attribute name Description The deployment name for the deployed application. If you do not specify this attribute, WebLogic Server assigns a deployment name to the application, based on its archive file or exploded directory. nostage Specifies whether the deployment uses nostage deployment mode. In this mode, the Ant task does not copy the deployment files to target servers, but leaves them in a fixed location, specified by the source attribute. Target servers access the same copy of the deployment files. You can specify only one of the following attributes: stage, nostage, or external_stage. If none is specified, the default deployment mode to Managed Servers is stage; the default mode to the Administration Server and in single-server cases is nostage. See "Controlling Deployment File Copying with Staging Modes". noversion Indicates that the wldeploy Ant task should ignore all version related code paths on Boolean the Administration Server. This behavior is useful when deployment source files are located on Managed Servers (not the Administration Server) and you want to use the external_stage staging mode. If you use this option, you cannot use versioned applications. Valid values for this attribute are true and false. Default value is false. nowait password Specifies whether wldeploy returns immediately after making a deployment call (by deploying as a background task). The administrative password. To avoid having the plain text password appear in the build file or in process utilities such as ps, first store a valid username and encrypted password in a configuration file using the WebLogic Scripting Tool (WLST) storeUserConfig command. Then omit both the username and password attributes in your Ant build file. When the attributes are omitted, wldeploy attempts to login using values obtained from the default configuration file. If you want to obtain a username and password from a non-default configuration file and key file, use the userconfigfile and userkeyfile attributes with wldeploy. See the command reference for storeUserConfig in the WebLogic Scripting Tool Command Reference for more information on storing and encrypting passwords. plan Specifies a deployment plan to use when deploying the application or module. By default, wldeploy does not use an available deployment plan, even if you are deploying from an application root directory that contains a plan. planversion remote The version identifier of the deployment plan. Specifies whether the server is located on a different machine. This affects how filenames are transmitted. Valid values for this attribute are true and false. Default value is false, which means that the Ant task assumes that all source paths are valid paths on the local machine. retiretimeout Specifies the number of seconds before WebLogic Server undeploys the int currently-running version of this application or module so that clients can start using the new version. It is assumed, when you specify this attribute, that you are starting, deploying, or redeploying a new version of an already-running application. See "Updating Applications in a Production Environment". String Boolean String Boolean String Boolean Data Type String
Table B1 (Cont.) Attributes of the wldeploy Ant Task Attribute Description Data Type String
securityModel Specifies the security model to use for this deployment. Possible security models are:
Deployment descriptors only Customize roles Customize roles and policies Security realm configuration (advanced model)
Valid actual values for this attribute are DDOnly, CustomRoles, CustomRolesAndPolicy, or Advanced. See "Options for Securing Web application and EJB Resources" for more information on these security models. source stage The archive file or exploded directory to deploy. Specifies whether the deployment uses stage deployment mode. In this mode, the Ant task copies deployment files to target servers' staging directories. You can specify only one of the following attributes: stage, nostage, or external_stage. If none is specified, the default deployment mode to Managed Servers is stage; the default mode to the Administration Server and in single-server cases is nostage. See "Controlling Deployment File Copying with Staging Modes". submoduletar Specifies JMS server targets for resources defined within a JMS application module. gets The value of this attribute is a comma-separated list of JMS server names. See "Using Sub-Module Targeting with JMS Application Modules". targets The list of target servers to which the application is deployed. The value of this attribute is a comma-separated list of the target servers, clusters, or virtual hosts. If you do not specify a target list when deploying an application, the target defaults to the Administration Server instance. timeout upload The maximum number of seconds to wait for a deployment to succeed. Specifies whether the source file(s) are copied to the Administration Server's upload directory prior to deployment. Use this attribute when you are on a remote machine and you cannot copy the deployment files to the Administration Server by other means. Valid values for this attribute are true and false. Default value is false. usenonexclusi Specifies that the deployment action (deploy, redeploy, stop, and so on) uses the velock existing lock on the domain that has already been acquired by the same user performing the action. This attribute is particularly useful when the user is using multiple deployment tools (Ant task, command line, Administration Console, and so on) simultaneously and one of the tools has already acquired a lock on the domain. Valid values for this attribute are true and false. Default value is false. user The administrative username. String Boolean int Boolean String String File Boolean
Table B1 (Cont.) Attributes of the wldeploy Ant Task Attribute userconfigfile Description Specifies the location of a user configuration file to use for obtaining the administrative username and password. Use this option, instead of the user and password attributes, in your build file when you do not want to have the plain text password shown in-line or in process-level utilities such as ps. Before specifying the userconfigfile attribute, you must first generate the file using the WebLogic Scripting Tool (WLST) storeUserConfig command as described in the WebLogic Scripting Tool Command Reference. userkeyfile Specifies the location of a user key file to use for encrypting and decrypting the username and password information stored in a user configuration file (the userconfigfile attribute). Before specifying the userkeyfile attribute, you must first generate the key file using the WebLogic Scripting Tool (WLST) storeUserConfig command as described in the WebLogic Scripting Tool Command Reference. verbose Specifies whether wldeploy displays verbose output messages. Boolean String Data Type String
The <files> element works the same as the standard <fileset> Ant task (except for the difference in actual task name). Therefore, see the Apache Ant Web site at http://ant.apache.org/manual/Types/fileset.html for detailed reference information about the attributes you can specify for the <files> element.