Developing WebLogic Server Applications

Developing WebLogic Server J2EE Applications

The following sections describe the steps for creating different types of WebLogic Server J2EE applications, setting up a development environment, and preparing to compile Java programs.

• Creating Web Applications: Main Steps

• Creating Enterprise JavaBeans: Main Steps

• Creating Resource Adapters: Main Steps

• Creating Resource Adapters: Main Steps

• Creating WebLogic Server Enterprise Applications: Main Steps

• Establishing a Development Environment

• Compiling Java Code

WebLogic Server applications are created by Java programmers, Web designers, and application assemblers. Programmers and designers create components that implement the business logic and presentation logic for the application. Application assemblers assemble the components into applications ready to deploy on WebLogic Server.

Creating Web Applications: Main Steps

Here are the main steps for creating a Web application:

1. Create the HTML pages and JavaServer Pages (JSPs) that make up the Web interface of the Web application. Typically, Web designers create these parts of a Web application.

   For detailed information about creating JSPs, refer to Programming WebLogic JSP

2. Write the Java code for the servlets and the JSP taglibs referenced in JSPs. Typically, Java programmers create these parts of a Web application.

   For detailed information about creating servlets, refer to Programming WebLogic HTTP Servlets.

3. Compile the servlets into class files.

   For detailed information about compiling, refer to Compiling Java Code.

4. Create the web.xml and weblogic.xml deployment descriptors.

   The web.xml file defines each servlet and JSP page and enumerates enterprise beans referenced in the Web application. The weblogic.xml file adds additional deployment information for WebLogic Server.

   Create the web.xml and weblogic.xml deployment descriptors manually or use a Java-based utility included in WebLogic Server to automatically generate them.

   See Automatically Generating Deployment Descriptors, and see Assembling and Configuring Web Applicationsfor detailed information on the elements in these deployment descriptors and instructions for creating them manually.

5. Package the HTML pages, servlet class files, JSP files, web.xml, and weblogic.xml files into a WAR file.

   Create a Web application staging directory and save the JSPs, HTML pages, and multimedia files referenced by the pages in the top level of the staging directory.

   Store compiled servlet classes, taglibs, and, if desired, servlets compiled from JSP pages are stored under a WEB-INF directory in the staging directory. When the Web application components are all in place in the staging directory, you create the WAR file with the JAR command.

   For detailed information on creating WAR files, see Packaging Web Applications.

6. Auto-deploy the WAR file on WebLogic Server for testing purposes.

   While you are testing the Web application you might need to edit the web.xml and weblogic.xml deployment descriptors; you can do this manually, or you can use the deployment descriptor editor in the Administration Console. For detailed information on using the deployment descriptor editor, see Editing Deployment Descriptors.

   Refer to BEA WebLogic Server Administration Guidefor detailed information about auto-deploying components and applications.

7. Deploy the WAR file on the WebLogic Server for production use or include it in an Enterprise ARchive (EAR) file to be deployed as part of an enterprise application. You use the Administration Console to deploy applications and components.

   Refer to WebLogic Server Deployment, for detailed information about deploying components and applications.

Creating Enterprise JavaBeans: Main Steps

Creating an Enterprise JavaBean requires creating the classes for the particular EJB (session, entity, or message-driven) and the EJB-specific deployment descriptors, and then packaging everything into an EAR file to be deployed on WebLogic Server.

Here are the main steps for creating an Enterprise JavaBean:

1. Write the Java code for the various classes required by each type of EJB (session, entity, or message-driven) in accordance with the EJB specification. For example, session and entity EJBs require the following three classes:

   • An EJB home interface

   • A remote interface for the EJB

   • An implementation class for the EJB

     Message-driven beans, however, require only an implementation class.

2. Compile the Java code using a standard compiler for the interfaces and implementation into class files.

   For instructions on compiling, refer to Compiling Java Code.

3. Create the EJB-specific deployment descriptors:

   • ejb-jar.xml describes the EJB type and its deployment properties using a standard DTD from Sun Microsystems.

   • weblogic-ejb-jar.xml adds additional WebLogic Server-specific deployment information.

   • weblogic-cmp-rdbms-jar.xml maps a container-managed entity EJB to tables in a database. This file can must have a different name for each container-managed persistence (CMP) bean packaged in a JAR file. The name of the file is specified in the bean's entry in the weblogic-ejb.jar file.

     Component deployment descriptors are XML documents that provide information needed to deploy the application in WebLogic Server. The J2EE specifications define the contents of some deployment descriptors, such as ejb-jar.xml and web.xml. Additional deployment descriptors supplement the J2EE-specified descriptors with information required to deploy components in WebLogic Server.

     Create and edit the XML deployment descriptors manually, or use a Java-based utility included in WebLogic Server to automatically generate them. For more information on automatically generating these files, see Automatically Generating Deployment Descriptors.

     For detailed information about the elements in the EJB-specific deployment descriptors and how to create the files by hand, refer to Programming WebLogic Enterprise JavaBeans.

4. Package the class files and deployment descriptors into a JAR file.

   Create an EJB staging directory. Place the compiled Java classes in the staging directory and the deployment descriptors in a subdirectory called META-INF. Then run the weblogic.ejbc EJB compiler to generate classes that enforce the EJB security, transaction, and lifecycle policies. Then you create the EJB archive by executing a jar command like the following in the staging directory:

   jar cvf myEJB.jar *

   For detailed information about creating the EJB JAR file, refer to Packaging Enterprise JavaBeans.

5. Auto-deploy the EJB JAR file on WebLogic Server for testing purposes.

   While you are testing the EJB you might need to edit the EJB deployment descriptors; you can do this manually, or use the deployment descriptor editor in the Administration Console. For detailed information on using the deployment descriptor editor, see Editing Deployment Descriptors.

   Refer to BEA WebLogic Server Administration Guidefor detailed information about auto-deploying components and applications.

6. Deploy the JAR file on WebLogic Server for production use or include it in an Enterprise ARchive (EAR) file to be deployed as part of an enterprise application. You use the Administration Console to deploy applications and components.

   Refer to WebLogic Server Deployment, for detailed information about deploying components and applications.

Creating Resource Adapters: Main Steps

Creating a resource adapter requires creating the classes for a resource adapter and the connector-specific deployment descriptors, and then packaging everything into a resource adapter archive (RAR) file to be deployed on WebLogic Server.

Creating a New Resource Adapter (RAR)

The following are the main steps for creating a resource adapter (RAR):

1. Write the Java code for the various classes required by resource adapter (ConnectionFactory, Connection, and so on) in accordance with the J2EE Connector Specification, Version 1.0, Proposed Final Draft 2 (http://java.sun.com/j2ee/download.html#connectorspec).

   When implementing a resource adapter, you must specify classes in the ra.xml file. For example:

   • <managedconnectionfactory-class>com.sun.connector.blackbox.LocalTxManagedConnectionFactory</managedconnectionfactory-class>

   • <connectionfactory-interface>javax.sql.DataSource</connectionfactory-interface>

   • <connectionfactory-impl-class>com.sun.connector.blackbox.JdbcDataSource</connectionfactory-impl-class>

   • <connection-interface>java.sql.Connection</connection-interface>

   • <connection-impl-class>com.sun.connector.blackbox.JdbcConnection</connection-impl-class>

2. Compile the Java code using a standard compiler for the interfaces and implementation into class files.

   For instructions on compiling, refer to Compiling Java Code.

3. Create the resource connector-specific deployment descriptors:

   • ra.xml describes the resource adapter-related attributes type and its deployment properties using a standard DTD from Sun Microsystems.

   • weblogic-ra.xml adds additional WebLogic Server-specific deployment information.

     For detailed information about creating connector-specific deployment descriptors, refer to Programming the WebLogic J2EE Connector Architecture.

4. Package the Java classes into a Java archive (JAR) file.

   The first step in creating a JAR file is to create a connector staging directory anywhere on your hard drive. Place the JAR file in the staging directory and the deployment descriptors in a subdirectory called META-INF.

   Then you create the resource adapter archive by executing a jar command like the following in the staging directory:

   jar cvf myRAR.rar * 

   For detailed information about creating the resource adapter RAR archive file, refer to Packaging Resource Adapters.

5. Auto-deploy the RAR resource adapter archive file on WebLogic Server for testing purposes.

   During testing, you might need to edit the deployment descriptors. You can do this manually or use the deployment descriptor editor in the Administration Console. For detailed information on using the deployment descriptor editor, see Editing Deployment Descriptors.

6. Deploy the RAR resource adapter archive file on WebLogic Server or include it in an enterprise archive (EAR) file to be deployed as part of an enterprise application.

   Refer to WebLogic Server Deployment, for detailed information about deploying components and applications.

Modifying an Existing Resource Adapter (RAR)

The following is an example of how to take an existing resource adapter (RAR) and modify it for deployment to WebLogic Server. This involves adding the weblogic-ra.xml deployment descriptor and repacking.

1. Create a temporary directory anywhere on your hard drive to stage the resource adapter:

	mkdir c:/stagedir

2. Copy the resource adapter that you will deploy into the temporary directory:

	cp blackbox-notx.rar c:/stagedir

3. Extract the contents of the resource adapter archive:

	cd c:/stagedir

	jar xf blackbox-notx.rar

The staging directory should now contain the following:

• A jar file containing Java classes that implement the resource adapter

• A META-INF directory containing the files: Manifest.mf and ra.xml

  Execute these commands to see these files:

	c:/stagedir> ls

		blackbox-notx.rar 

		META-INF

	c:/stagedir> ls META-INF

		Manifest.mf

		ra.xml

4. Create the weblogic-ra.xml file. This file is the WebLogic-specific deployment descriptor for resource adapters. In this file, you specify parameters for connection factories, connection pools, and security mappings.

   Refer to Programming the WebLogic J2EE Connector Architecture for more information on the weblogic-ra.xml DTD.

5. Copy the weblogic-ra.xml file into the temporary directory's META-INF subdirectory. The META-INF directory is located in the temporary directory where you extracted the RAR file or in the directory containing a resource adapter in exploded directory format. Use the following command:

	cp weblogic-ra.xml c:/stagedir/META-INF

	c:/stagedir> ls META-INF

		Manifest.mf

		ra.xml

		weblogic-ra.xml

6. Create the resource adapter archive:

	jar cvf blackbox-notx.rar -C c:/stagedir

7. Deploy the resource adapter to WebLogic Server. There are several deployment tools. For detailed information about deploying components and applications, refer to WebLogic Server Deployment.

Creating WebLogic Server Enterprise Applications: Main Steps

Creating a WebLogic Server enterprise application requires creating Web, EJB, and Connector (Resource Adapter) components, deployment descriptors, and archive files. The result is an enterprise application archive (EAR file) that can be deployed on WebLogic Server.

Here are the main steps for creating a WebLogic Server enterprise application:

1. Create Web, EJB, and Connector components for your application.

   Programmers create servlets, EJBs, and Connectors using the J2EE APIs for these components. Web designers create Web pages using HTML/XML and JavaServer Pages.

   For overview information about creating Web, EJB, and Connector components, respectively refer to Creating Web Applications: Main Steps, Creating Enterprise JavaBeans: Main Steps, and Creating Resource Adapters: Main Steps.

   For detailed information about creating the Java code that makes up the Web, EJB, and Connector components, refer to Programming WebLogic Enterprise JavaBeans, Programming WebLogic HTTP Servlets, Programming WebLogic JSP, and Programming the WebLogic Server J2EE Connector Architecture.

2. Create Web, EJB, and Connector deployment descriptors.

   Component deployment descriptors are XML documents that provide information needed to deploy the application in WebLogic Server. The J2EE specifications define the contents of some deployment descriptors, such as ejb-jar.xml, web.xml, and ra.xml. Additional deployment descriptors supplement the J2EE-specified descriptors with information required to deploy components in WebLogic Server.

   Create these deployment descriptors manually, or you can use a Java-based utility included in WebLogic Server to generate them automatically. For more information on automatically generating these files, see Automatically Generating Deployment Descriptors.

   For detailed information about manually creating, Web, EJB, and Connector deployment descriptors, refer to Assembling and Configuring Web Applications, Programming WebLogic Enterprise JavaBeans, and Programming the WebLogic Server J2EE Connector Architecture.

3. Package the Web, EJB, and Connector components into their component archive files.

   Component archives are JAR files containing all component files, including deployment descriptors. You package Web components into a WAR file, EJB components into an EJB JAR file, and Connector components into a RAR file.

   Refer to Packaging Web Applications, Packaging Enterprise JavaBeans, and Packaging Resource Adapters for detailed information for creating component archives.

4. Create the enterprise application deployment descriptor.

   The enterprise application deployment descriptor, application.xml, lists individual components that are assembled together in an application.

   Create the application.xml deployment descriptor manually, or use a Java-based utility included in WebLogic Server to automatically generate it. For more information on automatically generating this file, see Automatically Generating Deployment Descriptors.

   Refer to application.xml Deployment Descriptor Elements for detailed information about the elements of the application.xml file.

5. Package the enterprise application into an EAR file.

   Package the Web, EJB, and Connector component archives along with the enterprise application deployment descriptor into an enterprise archive (.ear extension) file. This is the file that is deployed on WebLogic Server. WebLogic Server uses the application.xml deployment descriptor to locate and deploy the individual components packaged in the EAR file.

   For detailed information about creating the EAR file, refer to Packaging Enterprise Applications.

6. For testing purposes, auto-deploy the EAR enterprise application on WebLogic Server.

   While you are testing the enterprise application you might need to edit the application.xml deployment descriptor. Edit the file manually or use the deployment descriptor editor in the Administration Console. For detailed information on using the deployment descriptor editor, see Editing Deployment Descriptors.

7. For production purposes, use the Administration Console to deploy the EAR file on WebLogic Server.

   Refer to WebLogic Server Deployment, for detailed information about deploying components and applications.

Figure 2-1 illustrates the process for developing and packaging WebLogic Server enterprise applications.

Figure 2-1 Creating Enterprise Applications

Establishing a Development Environment

In preparation for developing WebLogic Server applications, you assemble the required software tools and set up an environment for creating, compiling, deploying, testing, and debugging your code.

Software Tools

This section reviews the software required to develop WebLogic Server applications and describes optional tools for development and debugging.

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.

Java Interactive Development Environments (IDEs) such as WebGain VisualCafé usually include a programmer's editor with custom support for Java. An IDE may also have support for creating and deploying servlets and Enterprise JavaBeans on WebLogic Server, which makes it much easier to develop, test, and debug applications.

You can edit HTML or XML pages and JavaServer Pages with a plain text editor, or use a Web page editor such as DreamWeaver.

XML Editor

You use an XML editor to edit the XML files used by WebLogic Server, such as the EJB and Web application deployment descriptors, the config.xml file, and so on. WebLogic Server includes the following two XML editors:

• Deployment Descriptor Editor, part of the Administration Console

• BEA XML Editor, a stand-alone Java-based editor

For detailed information about using these XML editors, see Editing Deployment Descriptors.

Java Compiler

A Java compiler produces Java class files, containing portable byte code, from Java source. The compiler compiles the Java code you write for your applications, as well as the code generated by the WebLogic RMI, EJB, and JSP compilers.

Sun Microsystems Java 2, Standard Edition includes a Java compiler, javac. If you install the bundled Java Runtime Environment (JRE) when you install WebLogic Server, the javac compiler is installed on your computer.

Other Java compilers are available for various platforms. You can use a different Java compiler for WebLogic Server application development as long as it produces standard Java .class files. Most Java compilers are many times faster than javac, and some are integrated nicely with an IDE.

Occasionally, a compiler generates optimized code that does not behave well in all Java Virtual Machines (JVMs). When you debug problems, try disabling optimizations, choosing a different set of optimizations, or compiling with javac to rule out your Java compiler as the cause. Always test your code in each target JVM before deploying.

Development WebLogic Server

Never deploy untested code on a WebLogic Server 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.

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.

Even if you do not run a development WebLogic Server on your development computer, you must have access to a WebLogic Server distribution to compile your programs. To compile any code using WebLogic or J2EE APIs, the Java compiler needs access to the weblogic.jar file and other JAR files in the distribution directory. Installing WebLogic Server on your development computer makes these files available locally.

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, IBM DB2, or PointBase. Refer to Platform Support to find out about supported database systems and JDBC drivers.

JDBC connection pools offer such significant performance advantages that you should only rarely consider writing an application that uses a two-tier JDBC driver directly. On a WebLogic Server cluster, be sure to set up a multipool, which provides load balancing over JDBC connection pools on multiple servers in the cluster.

Web Browser

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.

Third-Party Software

You can use third-party software products, such as WebGain Studio, WebGain StructureBuilder, and BEA WebLogic Integration Kit for VisualAge for Java, to enhance your WebLogic Server development environment.

For more information, 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.

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

Compiling Java Code

Compiling Java code for WebLogic Server is the same as compiling any other Java code. To compile successfully, you must:

• Place a standard Java compiler in your search path.

• Set your classpath so that the Java compiler can find all of the dependent classes.

• Specify the output directories for the compiled classes.

One way to set up your environment is to create a command file or shell script to set variables in your environment, which you can then pass to the compiler. The setExamplesEnv.cmd (Windows) and setExamplesEnv.sh (UNIX) files in the samples\server\config\examples directory are examples of this technique.

Putting the Java Tools in Your Search Path

Make sure the operating system can find the compiler and other JDK tools by adding it to the %PATH% environment variable in your command shell. If you are using the JDK, the tools are in the bin subdirectory of the JDK directory. To use an alternative compiler, such as the sj compiler from WebGain VisualCafé, add the directory containing that compiler to your search path.

For example, if the JDK is installed in /usr/local/java/java130 on your UNIX file system, use a command such as the following to add javac to your path in a Bourne shell or shell script:

PATH=/usr/local/java/java130/bin:$PATH; export $PATH

To add the WebGain sj compiler to your path on Windows NT or Windows 2000, use a command such as the following in a command shell or in a command file:

PATH=c:\VisualCafe\bin;%PATH%

If you are using an IDE, see the IDE documentation for help setting up an equivalent search path.

Setting the Classpath for Compiling Code

Most WebLogic services are based on J2EE standards and are accessed through standard J2EE packages. The Sun, WebLogic, and other Java classes required to compile programs that use WebLogic services are packaged in the weblogic.jar file in the lib directory of your WebLogic Server installation. In addition to weblogic.jar, include the following in your compiler's CLASSPATH:

• The lib/tools.jar file in the JDK directory, or other standard Java classes required by the Java Development Kit you use.

• Classes for third party Java tools or services your programs import.

• Other application classes referenced by the programs you are compiling.

  Include in your classpath the target directories where the compiler writes the classes you are compiling so that the compiler can locate all of the interdependent classes in your application. The next section has more information on target directories.

Setting Target Directories for Compiled Classes

The Java compiler writes class files in the same directory with the Java source unless you specify an output directory for the compiled classes. If you specify the output directory, the compiler stores the class file in a directory structure that matches the package name. This allows you to compile Java classes into the correct locations in the staging directory you use to package your application. If you do not specify an output directory, you have to move files around before you can create the JAR file that contains your packaged component.

J2EE applications consist of modules assembled into an application and deployed on one or more WebLogic Servers or WebLogic Server clusters. Each module should have its own staging directory so that it can be compiled, packaged, and deployed independently from other modules. For example, you can package EJBs in a separate module, Web components in a separate module, and other server-side classes in another module.

See the setExamplesEnv scripts in the samples\server\config\examples directory of the WebLogic Server distribution for an example of setting up target directories for the compiler. The scripts set the following variables:

CLIENT_CLASSES

samples\server\stage\examples\clientclasses

Directory where compiled client classes are written for the Examples domain. These classes are usually standalone Java programs that connect to WebLogic Server.

SERVER_CLASSES

samples\server\stage\examples\serverclasses by default. Directory where server-side classes are written for the Examples domain. Include startup classes and other Java classes that must be in the WebLogic Server CLASSPATH when the server starts up. Application classes usually should not be compiled into this directory, because the classes in this directory cannot be redeployed without restarting WebLogic Server.

EX_WEBAPP_CLASSES

samples\server\stage\examples\applications\examplesWebApp\WEB-INF\classes. Directory where classes used by a Web Application are written for the Examples domain.

APPLICATIONS

SAMPLES_HOME\server\config\examples\applications

Applications directory for the Examples domain. This variable is not used to specify a target for the Java compiler. It is used as a convenient reference to the applications directory in copy commands that move files from source directories into the applications directory. For example, if you have HTML, JSP, and image files in your source tree, you can use the variable in a copy command to install them in your development server.

These environment variables are passed to the compiler in commands such as the following command for Windows:

javac -d %SERVER_CLASSES% *.java

If you do not use an IDE, consider writing a make file, shell script, or command file to compile and package your components and applications. Set the variables in the build script so that you can rebuild components by typing a single command.