Fusion Middleware Documentation
Advanced Search


Developing Applications for Oracle WebLogic Server
Close Window

Table of Contents

Show All | Collapse

1 Overview of WebLogic Server Application Development

This chapter provides an overview of WebLogic Server applications and basic concepts.

This chapter includes the following sections:

Document Scope and Audience

This document is written for application developers who want to build WebLogic Server e-commerce applications using the Java Platform, Enterprise Edition 6. 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 and the Java EE Platform

WebLogic Server implements Java Platform, Enterprise Edition (Java EE) Version 6.0 technologies (see http://www.oracle.com/technetwork/java/javaee/overview/index.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 several 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).

Starting in Java EE 5 and continuing in Java EE 6, the focus has been ease of development. 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.1 provides simplified programming and packaging model changes. The mandatory use of Java interfaces from previous versions has been removed, allowing plain old Java objects to be annotated and used as EJB components. The simplification is further enhanced through the ability to place EJB modules directly inside of Web applications, removing the need to produce archives to store the Web and EJB components and combine them together in an EAR file.

  • Java EE 6 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 6 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 server—only 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://www.oracle.com/technetwork/java/javaee/tech/index-jsp-142185.html.

Overview of Java EE Applications and Modules

A WebLogic Server Java EE application consists of one of the following modules or applications running on WebLogic Server:

A WebLogic application can also include the following WebLogic-specific modules:

Web Application Modules

A Web application on WebLogic Server includes the following files:

  • 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.

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.

JavaServer Pages

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 JavaBean Modules

Enterprise JavaBeans (EJB) 3.1 technology is the server-side component architecture for the development and deployment of component-based business applications. EJB technology enables rapid and simplified development of distributed, transactional, secure, and portable applications based on Java EE 6 technology.

The EJB 3.1 specification provides simplified programming and packaging model changes. The mandatory use of Java interfaces from previous versions has been removed, allowing plain old Java objects to be annotated and used as EJB components. The simplification is further enhanced through the ability to place EJB modules directly inside of Web applications, removing the need to produce archives to store the Web and EJB components and combine them together in an EAR file.

EJB Documentation in WebLogic Server

For more information about using EJBs with WebLogic Server, see:

Additional EJB Information

To learn more about EJB concepts, such as the benefits of enterprise beans, the types of enterprise beans, and their life cycles, then visit the following Web sites:

Connector Modules

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 Java EE applications to access a remote EIS. WebLogic Server application developers can use HTTP servlets, JavaServer Pages (JSPs), Enterprise JavaBeans (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 standalone modules or as part of an enterprise application. See Enterprise Applications.

For more information on connectors, see Developing Resource Adapters for Oracle WebLogic Server.

Enterprise Applications

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 can be optionally defined by an application.xml file, which was the standard Java EE deployment descriptor for enterprise applications.

Java EE Programming Model

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 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 (1.4 and earlier).

With Java EE annotations, the standard application.xml and web.xml deployment descriptors are optional. The Java EE programming model uses the JDK annotations feature (see http://docs.oracle.com/javaee/6/api/) for Web containers, such as EJBs, servlets, Web applications, and JSPs. See Chapter 8, "Using Java EE Annotations and Dependency Injection."

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 Appendix A, "Enterprise Application Deployment Descriptor Elements."

Packaging and Deployment Overview

For both production and development purposes, Oracle recommends that you package and deploy even standalone Web applications, EJBs, and resource adapters as part of an enterprise application. Doing so allows you to take advantage of Oracle's split development directory structure, which greatly facilitates application development. See Chapter 4, "Creating a Split Development Directory Environment."

An enterprise application consists of Web application modules, EJB modules, and resource adapters. It can be packaged as follows:

  • 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 4, "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 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 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 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."

WebLogic Web Services

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.

A Web service consists of the following modules, at a minimum:

  • 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 services—JAX-WS or JAX-RPC. See Developing JAX-WS Web Services for Oracle WebLogic Server or Developing 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 Understanding WebLogic Web Services for Oracle WebLogic Server.

JMS and JDBC Modules

JMS and JDBC configurations are stored as modules, defined by an XML file that conforms to the weblogic-jms.xsd and jdbc-data-source.xsd schema, respectively. These modules are similar to standard Java EE modules. An administrator can create and manage JMS and JDBC modules as global system resources, as modules packaged with a Java EE 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.

For more information, see:

WebLogic Diagnostic Framework Modules

The WebLogic Diagnostic Framework (WLDF) provides features for generating, gathering, analyzing, and persisting diagnostic data from 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".

Using an External Diagnostics Descriptor

WebLogic Server also supports the use of an external diagnostics descriptor so you can integrate diagnostic functionality into an application that has not imported diagnostic descriptors. This feature supports the deployment view and deployment of an application or a module, detecting the presence of an external diagnostics descriptor if the descriptor is defined in your deployment plan (plan.xml).

Defining an External Diagnostics Descriptor

First, define the diagnostic descriptor as external and configure its URI in the plan.xml file. For example:

<module-override>
  <module-name>reviewService.ear</module-name>
  <module-type>ear</module-type>
  </module-descriptor>
  <module-descriptor external="true">
  <root-element>wldf-resource</root-element>
  <uri>META-INF/weblogic-diagnostics.xml</uri>
  ...
  ...
</module-override>
<config-root>D:\plan</config-root>

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.

Coherence Grid Archive (GAR) Modules

A Coherence GAR module provides distributed in-memory caching and data grid computing that allows applications to increase their availability, scalability, and performance. GAR modules are deployed as both standalone modules and packaged with Java EE applications (as a packaged resource). A GAR module may also be made globally available.

A GAR module is defined by the coherence-application.xml deployment descriptor and must conform to the coherence-application.xsd XML schema. The GAR contains the artifacts that comprise a Coherence application: Coherence configuration files, application classes (such as entry processors, aggregators, filters), and any dependencies that are required.

Bean Validation

The Bean Validation specification (JSR 316) defines a metadata model and API for validating data in JavaBeans components. It is supported on both the server and Java EE 6 client; therefore, instead of distributing validation of data over several layers, such as the browser and the server side, you can define the validation constraints in one place and share them across the different layers. Further, bean validation is not only for validating beans. In fact, it can also be used to validate any Java object.

Bean Validation and JNDI

Where required by the Java EE 6 specifications, the default Validator and ValidatorFactory are located using JNDI under the names java:comp/Validator and java:comp/ValidatorFactory. These two artifacts reflect the validation descriptor that is in scope.

Bean Validation Configuration

Bean validation can be configured by using XML descriptors or annotation.

  • Descriptors:

    • Descriptor elements override corresponding annotations.

    • Weblogic Server allows one descriptor per module. Therefore, an application can have several validation descriptors but only one is allowed per module scope.

    • Validation descriptors are named validation.xml and are packaged in the META-INF directory, except for Web modules, where the descriptor is packaged in the WEB-INF directory.

  • Annotations:

    • Injection of the default Validator and ValidatorFactory is requested using the @Resource annotation. However, not all source files are scanned for this annotation.

    • The WebLogic Connector uses bean validation internally to validate the connector descriptors.

Once bean validation is configured, the standard set of container managed classes for a given container will be scanned. For example, for EJBs, bean and interceptor classes are scanned. Web application classes and ManagedBeans also support the injection of Validator and ValidatorFactories.

For more information about the classes that support bean validation, please see the related component specifications for the list of classes that support dependency injection.

XML Deployment Descriptors

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: Java EE deployment descriptors, WebLogic Server descriptors, and WebLogic Server deployment plans. This section describes the Java EE and WebLogic-specific deployment descriptors. See Deployment Plans for information on deployment plans.

The Java EE programming model uses the JDK annotations feature for Web containers (see http://docs.oracle.com/javaee/6/api/), such as EJBs, servlets, Web applications, and JSPs. Annotations simplify the application development process by allowing a developer to specify within the Java class itself how the 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 Web applications (2.4 and earlier), enterprise applications (1.4 and earlier), and Enterprise JavaBeans (2.x and earlier). See Chapter 8, "Using Java EE Annotations and Dependency Injection."

However, enterprise applications fully support the use of deployment descriptors, even though the standard Java EE ones are not required. For example, you may prefer to use the old EJB 2.x programming model, or might want to allow further customizing of the EJB at a later development or deployment stage; in these cases you can create the standard deployment descriptors in addition to, or instead of, the metadata annotations.

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 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 1-1 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.4/weblogic-javaee.xsd schema, which describes common elements shared among all WebLogic-specific deployment descriptors.

For the most current schema information, see: http://www.oracle.com/technetwork/middleware/weblogic/overview/index.html.

Table 1-1 Java EE and WebLogic Deployment Descriptors

Module or Application Scope Deployment Descriptors

Web Application

Java EE

web.xml

See the Servlet 3.0 Schema at http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/web-app_3_0.xsd

WEB-INF/beans.xml—required only if the classes in the WAR file are to participate in Contexts and Dependency Injection (CDI)

Schema: http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/beans_1_0.xsd

See Chapter 9, "Using Contexts and Dependency Injection for the Java EE Platform."

 

WebLogic

weblogic.xml

Schema: http://xmlns.oracle.com/weblogic/weblogic-web-app/1.5/weblogic-web-app.xsd

See "weblogic.xml Deployment Descriptor Elements" in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.

Enterprise Bean 3.0

Java EE

ejb-jar.xml

See the EJB 3.1 Schema at http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/ejb-jar_3_1.xsd

META-INF/beans.xml—required only if the classes in the EJB JAR file are to participate in CDI

Schema: http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/beans_1_0.xsd

See Chapter 9, "Using Contexts and Dependency Injection for the Java EE Platform."

 

WebLogic

weblogic-ejb-jar.xml

Schema http://xmlns.oracle.com/weblogic/weblogic-ejb-jar/1.4/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-configuration/1.0/persistence-configuration.xsd

See Developing Enterprise JavaBeans for Oracle WebLogic Server.

Enterprise Bean 2.1

Java EE

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.4/weblogic-ejb-jar.xsd

See "The weblogic-ejb-jar.xml Deployment Descriptor" in Developing Enterprise JavaBeans, Version 2.1, 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 Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.

Web services

Java EE

webservices.xml

See the Web services 1.2 Schema at http://www.oracle.com/webfolder/technetwork/jsc/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-clientHandlerChain/1.0/weblogic-wsee-clientHandlerChain.xsd

weblogic-webservices-policy.xml

Schema: http://xmlns.oracle.com/weblogic/webservice-policy-ref/1.1/webservice-policy-ref.xsd

weblogic-wsee-standaloneclient.xml

Schema: http://xmlns.oracle.com/weblogic/weblogic-wsee-standaloneclient/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.6 Schema at http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/connector_1_6.xsd

META-INF/beans.xml—required only if the classes in the RAR file are to participate in CDI

Schema: http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/beans_1_0.xsd

See Chapter 9, "Using Contexts and Dependency Injection for the Java EE Platform."

 

WebLogic

weblogic-ra.xml

Schema: http://xmlns.oracle.com/weblogic/weblogic-connector/1.4/weblogic-connector.xsd

See "weblogic-ra.xml Schema" in Developing Resource Adapters for Oracle WebLogic Server.

Enterprise Application

Java EE

application.xml

See the Application 6 Schema at http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/application_6.xsd

 

WebLogic

weblogic-application.xml 

Schema: http://xmlns.oracle.com/weblogic/weblogic-application/1.5/weblogic-application.xsd

See weblogic-application.xml Deployment Descriptor Elements.

Client Application

Java EE

application-client.xml 

See the Application Client 6 Schema at http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/application-client_6.xsd

META-INF/beans.xml—required only if the classes in the application client JAR file are to participate in CDI

Schema: http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/beans_1_0.xsd

See Chapter 9, "Using Contexts and Dependency Injection for the Java EE Platform."

 

WebLogic

application-client.xml 

Schema: http://xmlns.oracle.com/weblogic/weblogic-application-client/1.4/weblogic-application-client.xsd

See "Developing a Java EE Application Client (Thin Client)" in Developing 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/weblogic-jms.xsd

See "Configuring JMS Application Modules for Deployment" in Administering JMS Resources 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.3/jdbc-data-source.xsd

See "Configuring JDBC Application Modules for Deployment" in Administering JDBC Data Sources 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.

Coherence Modules

WebLogic

coherence-application.xml

Schema: http://xmlns.oracle.com/coherence/coherence-application/1.0/coherence-application.xsd

See Developing Oracle Coherence Applications for Oracle WebLogic Server.


When you package a module or application, you create a directory to hold the deployment descriptors—WEB-INF or META-INF—and then create the XML deployment descriptors in that directory.

Automatically Generating Deployment Descriptors

WebLogic Server provides a variety of tools for automatically generating deployment descriptors. These are discussed in the sections that follow.

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 Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.

Java-based Command-line Utilities

WebLogic Server includes a set of Java-based command-line utilities that automatically generate both standard Java EE 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 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.

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.

Invoke weblogic.DDConverter with the following command:

prompt> java weblogic.DDConverter [options] archive_file_or_directory

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 Description

-d <dir>

Specifies the directory to which descriptors are written.

-help

Prints the standard usage message.

-quiet

Turns off output messages except error messages.

-verbose

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

Deployment Plans

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 Java EE 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 Server provides the following tools to help programmers export an application's deployment configuration:

  • 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 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:

Development Tools

This section describes required and optional tools for developing WebLogic Server applications.

Java API Reference and the wls-api.jar File

Oracle provides the Oracle Fusion Middleware Java API Reference for Oracle WebLogic Server, which defines all of the supported Java classes available for use when developing Java EE applications for WebLogic Server. See the Java API Reference for Oracle WebLogic Server.

In conjunction with the Java API Reference for Oracle WebLogic Server, Oracle recommends using the wls-api.jar file to develop and compile Java EE applications for your WebLogic Server environment. The wls-api.jar file is located in the wlserver/server/lib directory of your WebLogic Server distribution and offers the following benefits:

  • developing more performant code based on tested best practices

  • avoiding deprecated or unsupported code paths

Using the wls-api.jar File

Use the wls-api.jar file and the api.jar file to develop and compile your Java EE applications in Integrated Development Environments (IDEs), such as Oracle JDeveloper. IDEs provide an array of tools to simplify development of Java-based applications. The wls-api.jar file provides a clean and concise API jar to develop and run Java EE applications for WebLogic environments.

Note:

The wls-api.jar file does not reference any Java EE classes. Oracle provides the api.jar file with a manifest classpath that includes access to Java EE JARs.

You may need to include the weblogic.jar file in the classpath of your development environment to access tools such as WLST, the weblogic.Deployer utilty, and weblogic.appc.

Using the weblogic.jar File

You must continue to use the weblogic.jar file for runtime environments, as a client or to develop and compile legacy applications. However, use the wls-api.jar file to develop and compile Java EE applications for your WebLogic Server environment.

Apache Ant

The preferred Oracle 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. Oracle 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 WL_SERVER\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:

prompt> ant -version

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 EXAMPLES_HOME/wl_server/examples/src/examples/ejb20/basic/beanManaged/build.xml, where EXAMPLES_HOME represents the directory in which the WebLogic Server code examples are configured. For more information about the WebLogic Server code examples, see "Sample Applications and Code Examples" in Understanding Oracle WebLogic Server.

Also refer to the following WebLogic Server documentation on building examples using Ant: EXAMPLES_HOME/wl_server/examples/src/examples/examples.html.

Using a Third-Party Version of Ant

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:

prompt> ant -version

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\Oracle_Home\wlserver) or add the new file to the front of your CLASSPATH.

Changing the Ant Heap Size

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:

prompt> setenv ANT_OPTS=-Xmx128m

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.

Source Code Editor or IDE

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 an enterprise-level IDE with DTD validation or another development tool that supports editing of XML files.

Database System and JDBC Driver

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, or IBM DB2. Refer to Oracle Fusion Middleware Supported System Configurations at http://www.oracle.com/technology/software/products/ias/files/fusion_certification.html to find out about supported database systems and JDBC drivers.

Web Browser

Most Java EE 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 Firefox 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 so that everyone has the same Java run-time version.

Third-Party Software

You can use third-party software products to enhance your WebLogic Server development environment. See "WebLogic Developer Tools Resources" at http://www.oracle.com/technology/products/developer-tools/index.html, which provides developer tools information for products that support the application servers.

Note:

Check with the software vendor to verify software compatibility with your platform and WebLogic Server version.

New and Changed Features in this Release

This document contains the following updates to describe the new application development features introduced in this release of WebLogic Server:

  • Maven updates—In this release of WebLogic Server, the weblogic-maven-plugin provides enhanced functionality to install, start and stop servers, create domains, execute WLST scripts, and compile and deploy applications. With the weblogic-maven-plugin, you can install WebLogic Server from within your Maven environment to fulfill the local WebLogic Server requirement. See Chapter 3, "Using the WebLogic Development Maven Plug-In".

  • OSGi bundles for WebLogic Server applications—In this release of WebLogic Server, developers who want to use OSGi in their applications can easily share OSGi facilities, such as the OSGi service registry, class loaders, and other OSGi services. See Chapter 16, "Developing OSGi Bundles for WebLogic Server Applications".

  • WebSockets—This release of WebLogic Server adds support for the WebSocket Protocol (RFC 6455), which provides two-way, full-duplex communication over a single TCP connection between clients and servers, where each side can send data independently from the other. See Chapter 17, "Using WebSockets in WebLogic Server".

  • Coherence Grid Archive (GAR) module support—A Coherence GAR module provides distributed in-memory caching and data grid computing that allows applications to increase their availability, scalability, and performance. See "Coherence Grid Archive (GAR) Modules".

For a comprehensive listing of the new WebLogic Server features introduced in this release, see What's New in Oracle WebLogic Server.