Developing Applications with WebLogic Server
This document is written for application developers who want to build WebLogic Server e-commerce applications using the Java 2 Platform, Enterprise Edition (J2EE) from Sun Microsystems. It is assumed that readers know Web technologies, object-oriented programming techniques, and the Java programming language.
WebLogic Server applications are created by Java programmers, Web designers, and application assemblers. Programmers and designers create modules that implement the business and presentation logic for the application. Application assemblers assemble the modules into applications that are ready to deploy on WebLogic Server.
WebLogic Server implements Java 2 Platform, Enterprise Edition (J2EE) version 1.4 technologies. J2EE is the standard platform for developing multi-tier Enterprise applications based on the Java programming language. The technologies that make up J2EE were developed collaboratively by Sun Microsystems and other software vendors, including BEA Systems.
WebLogic Server J2EE 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.
J2EE includes deployment specifications for Web applications, EJB modules, Web Services, Enterprise applications, client applications, and connectors. J2EE does not specify how an application is deployed on the target server—only how a standard module or application is packaged.
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 J2EE 1.4 specification at: http://java.sun.com/j2ee/download.html#platformspec.
web.xmldeployment descriptor, a J2EE standard XML document that describes the contents of a WAR file.
weblogic.xmldeployment descriptor, an XML document containing WebLogic Server-specific elements for Web applications.
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.
JavaServer Pages (JSPs) are Web pages coded with an extended HTML that makes it possible to embed Java code in a Web page. JSPs can call custom Java classes, known as tag libraries, using HTML-like tags. The appc compiler compiles JSPs and translates them into servlets. WebLogic Server automatically compiles JSPs if the servlet class file is not present or is older than the JSP source file. See Building Modules and Applications Using wlappc.
You can also precompile JSPs and package the servlet class in a Web Application (WAR) file to avoid compiling in the server. Servlets and JSPs may require additional helper classes that must also be deployed with the Web application.
Enterprise JavaBeans (EJBs) beans are server-side Java modules that implement a business task or entity and are written according to the EJB specification. There are three types of EJBs: session beans, entity beans, and message-driven beans.
Session beans execute a particular business task on behalf of a single client during a single session. Session beans can be stateful or stateless, but are not persistent; when a client finishes with a session bean, the bean goes away.
Entity beans represent business objects in a data store, usually a relational database system. Persistence—loading and saving data—can be bean-managed or container-managed. More than just an in-memory representation of a data object, entity beans have methods that model the behaviors of the business objects they represent. Entity beans can be accessed concurrently by multiple clients and they are persistent by definition.
The container creates an instance of the message-driven bean or it assigns one from a pool to process the message. When the message is received in the JMS Destination, the message-driven bean assigns an instance of itself from a pool to process the message. Message-driven beans are not associated with any client. They simply handle messages as they arrive.
J2EE cleanly separates the development and deployment roles to ensure that modules are portable between EJB servers that support the EJB specification. Deploying an EJB in WebLogic Server requires running the WebLogic Server
appc compiler to generate classes that enforce the EJB security, transaction, and life cycle policies. See Building Modules and Applications Using wlappc.
The J2EE-specified deployment descriptor,
ejb-jar.xml, describes the enterprise beans packaged in an EJB application. It defines the beans' types, names, and the names of their home and remote interfaces and implementation classes. The
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.
Connectors (also known as resource adapters) contain the Java, and if necessary, the native modules required to interact with an Enterprise Information System (EIS). A resource adapter deployed to the WebLogic Server environment enables J2EE applications to access a remote EIS. WebLogic Server application developers can use HTTP servlets, JavaServer Pages (JSPs), Enterprise Java Beans (EJBs), and other APIs to develop integrated applications that use the EIS data and business logic.
To deploy a resource adapter to WebLogic Server, you must first create and configure WebLogic Server-specific deployment descriptor, weblogic-ra.xml file, and add this to the deployment directory. Resource adapters can be deployed to WebLogic Server as stand-alone modules or as part of an Enterprise application. See Enterprise Applications.
For more information on connectors, see Programming WebLogic Resource Adapters.
An Enterprise application consists of one or more Web application modules, EJB modules, and resource adapters. It might also include a client application. An Enterprise application is defined by an application.xml file, which is the standard J2EE deployment descriptor for Enterprise applications. If the application includes WebLogic Server-specific extensions, the application is further defined by a weblogic-application.xml file. Enterprise Applications that include a client module will also have a client-application.xml deployment descriptor and a WebLogic run-time client application deployment descriptor. See Enterprise Application Deployment Descriptor Elements.
For both production and development purposes, BEA recommends that you package and deploy even stand-alone Web applications, EJBs, and resource adapters as part of an Enterprise application. Doing so allows you to take advantage of BEA's new split development directory structure, which greatly facilities application development. See Creating a Split Development Directory Environment.
.earextension. 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 Packaging Applications Using wlpackage.
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. See Enterprise Application Deployment Descriptor Elements.
Web services can be shared by and used as modules of distributed Web-based applications. They commonly interface with existing back-end applications, such as customer relationship management systems, order-processing systems, and so on. Web services can reside on different computers and can be implemented by vastly different technologies, but they are packaged and transported using standard Web protocols, such as HTTP, thus making them easily accessible by any user on the Web. See Programming Web Services for WebLogic Server.
As of WebLogic Server 9.0, JMS and JDBC configurations are stored as modules, defined by an XML file that conforms to the
weblogic-jdbc.xsd schema, respectively. These modules are similar to standard J2EE modules. An administrator can create and manage JMS and JDBC modules as global system resources, as modules packaged with a J2EE application (as a packaged resource), or as standalone modules that can be made globally available. With modular deployment of JMS and JDBC resources, you can migrate your application and the required JMS or JDBC configuration from environment to environment, such as from a testing environment to a production environment, without opening an enterprise application file (such as an EAR file) or a JMS or JDBC standalone module, and without extensive manual JMS or JDBC reconfiguration.
Application developers create application modules in an enterprise-level IDE or another development tool that supports editing of XML files, then package the JMS or JDBC modules with an application and pass the application to a WebLogic Administrator to deploy.
The WebLogic Diagnostic Framework (WLDF) provides features for generating, gathering, analyzing, and persisting diagnostic data from BEA WebLogic Server instances and from applications deployed to server instances. For server-scoped diagnostics, some WLDF features are configured as part of the configuration for the domain. Other features are configured as system resource descriptors that can be targeted to servers (or clusters). For application-scoped diagnostics, diagnostic features are configured as resource descriptors for the application.
Application-scoped instrumentation is configured and deployed as a diagnostic module, which is similar to a diagnostic system module. However, an application 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.
A deployment configuration refers to the process of defining the deployment descriptor values required to deploy an Enterprise application to a particular WebLogic Server domain. The deployment configuration for an application or module is stored in three types of XML document: J2EE deployment descriptors, WebLogic Server descriptors, and WebLogic Server deployment plans. This section describes the J2EE and WebLogic-specific deployment descriptors. See Deployment Plans for information on deployment plans.
Modules and applications have deployment descriptors—XML documents—that describe the contents of the directory or JAR file. Deployment descriptors are text documents formatted with XML tags. The J2EE specifications define standard, portable deployment descriptors for J2EE modules and applications. BEA defines additional WebLogic-specific deployment descriptors for deploying a module or application in the WebLogic Server environment.
Table 1-1 lists the types of modules and applications and their J2EE-standard and WebLogic-specific deployment descriptors.
See the Sun Microsystems Servlet 2.4 Schema.
See the Sun Microsystems EJB 2.1 Schema.
See The weblogic-ejb-jar.xml Deployment Descriptor in Programming WebLogic Enterprise JavaBeans.
See The weblogic-cmp-rdbms-jar.xml Deployment Descriptor in Programming WebLogic Enterprise JavaBeans.
See WebLogic Web Service Deployment Descriptor Element Reference in Programming Web Services for WebLogic Server.
Note: The XML Schemas for the WebLogic deployment descriptors listed in the preceding table include elements from the weblogic-j2ee.xsd Schema, which describes common elements shared among all WebLogic-specific deployment descriptors.
EJBGen is an Enterprise JavaBeans 2.0 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
WebLogic Server includes a set of Java-based command-line utilities that automatically generate both standard J2EE and WebLogic-specific deployment descriptors for Web applications and Enterprise Applications.
These command-line utilities examine the classes you have assembled in a staging directory and build the appropriate deployment descriptors based on the servlet classes, and so on. These utilities include:
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
weblogic.xml deployment descriptors. To automatically generate them, execute the following command:
So that your applications can take advantage of the features in the current J2EE specification and release of WebLogic Server, BEA 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 J2EE 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 J2EE module archive or exploded directory with the new deployment descriptor files.
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:
A deployment plan is an XML document that defines an application's WebLogic Server deployment configuration for a specific WebLogic Server environment. A deployment plan resides outside of an application's archive file, and can apply changes to deployment properties stored in the application's existing WebLogic Server deployment descriptors. Administrators use deployment plans to easily change an application's WebLogic Server configuration for a specific environment without modifying existing J2EE or WebLogic-specific deployment descriptors. Multiple deployment plans can be used to reconfigure a single application for deployment to multiple, differing WebLogic Server environments.
After programmers have finished programming an application, they export its deployment configuration to create a custom deployment plan that administrators later use for deploying the application into new WebLogic Server environments. Programmers distribute both the application deployment files and the custom deployment plan to deployers (for example, testing, staging, or production administrators) who use the deployment plan as a blueprint for configuring the application for their environment.
weblogic.PlanGeneratorcreates 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.
weblogic.PlanGenerator, because it allows you to interactively add or edit individual deployment descriptor properties in the plan, rather than export entire categories of descriptor properties.
The preferred BEA method for building applications with WebLogic Server is Apache Ant. Ant is a Java-based build tool. One of the benefits of Ant is that is it is extended with Java classes, rather than shell-based commands. BEA provides numerous Ant extension classes to help you compile, build, deploy, and package applications using the WebLogic Server split development directory environment.
Another benefit is that Ant is a cross-platform tool. Developers write Ant build scripts in eXtensible Markup Language (XML). XML tags define the targets to build, dependencies among targets, and tasks to execute in order to build the targets. Ant libraries are bundled with WebLogic Server to make it easier for our customers to build Java applications out of the box.
To use Ant, you must first set your environment by executing either the
setExamplesEnv.cmd (Windows) or
setExamplesEnv.sh (UNIX) commands located in the
\samples\domains\wl_server directory, where
WL_SERVER is your WebLogic Server installation directory.
For a complete explanation of ant capabilities, see: http://jakarta.apache.org/ant/manual/index.html
Note: 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
You can use your own version of Ant if the one bundled with WebLogic Server is not adequate for your purposes. To determine the version of Ant that is bundled with WebLogic Server, run the following command after setting your WebLogic environment:
If you plan to use a different version of Ant, you can replace the appropriate JAR file in the
\server\lib\ant directory with an updated version of the file (where
WL_HOME refers to the main WebLogic installation directory, such as
c:\bea\weblogic90) or add the new file to the front of your CLASSPATH.
By default the environment script allocates a heap size of 128 megabytes to Ant. You can increase or decrease this value for your own projects by setting the
-X option in your local
ANT_OPTS environment variable. For example:
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:
You need a text editor to edit Java source files, configuration files, HTML or XML pages, and JavaServer Pages. An editor that gracefully handles Windows and UNIX line-ending differences is preferred, but there are no other special requirements for your editor. You can edit HTML or XML pages and JavaServer Pages with a plain text editor, or use a Web page editor such as DreamWeaver. For XML pages, you can also use enterprise-level IDE with DTD validation or another development tool that supports editing of XML files.
Nearly all WebLogic Server applications require a database system. You can use any DBMS that you can access with a standard JDBC driver, but services such as WebLogic Java Message Service (JMS) require a supported JDBC driver for Oracle, Sybase, Informix, Microsoft SQL Server, IBM DB2, or PointBase. Refer to Support Configuration to find out about supported database systems and JDBC drivers.
Most J2EE applications are designed to be executed by Web browser clients. WebLogic Server supports the HTTP 1.1 specification and is tested with current versions of the Netscape Communicator and Microsoft Internet Explorer browsers.
When you write requirements for your application, note which Web browser versions you will support. In your test plans, include testing plans for each supported version. Be explicit about version numbers and browser configurations. Will your application support Secure Socket Layers (SSL) protocol? Test alternative security settings in the browser so that you can tell your users what choices you support.
If your application uses applets, it is especially important to test browser configurations you want to support because of differences in the JVMs embedded in various browsers. One solution is to require users to install the Java plug-in from Sun so that everyone has the same Java run-time version.
You can use third-party software products to enhance your WebLogic Server development environment. See BEA WebLogic Developer Tools Resources, which provides developer tools information for products that support the BEA application servers.
To download some of these tools, see BEA WebLogic Server Downloads at.