Developing WebLogic Server 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.

• Establishing a Development Environment
• Application Lifecycle Events
• 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
• Compiling Java Code
• Auto-Deployment for Development Enviroments" on page 2-26

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.

 

---

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 "Deployment Tools Reference" in Deploying WebLogic Server Applications.

appc Compiler

The appc compiler compiles and generates EJBs and JSPs for deployment. It also validates the descriptors for compliance with the current specifications at both the individual module level and the application level. The application level checks include checks between the application-level deployment descriptors and the individual modules as well as validation checks across the modules.

The appc compiler reports any warnings or errors encountered in the descriptors. Finally, the appc compiler compiles all of the relevant modules into an EAR file, which can be deployed to WebLogic Server.

appc Syntax

Use the following syntax to run appc:

prompt>java weblogic.appc [options] <ear, jar, or war file or directory>

appc Options

Option	Description
-print	Prints the standard usage message.
-version	Prints jspc version information.
-output <file>	Specifies an alternate output archive or directory. If not set, the output is placed in the source archive or directory.
-forceGeneration	Forces generation of EJB and JSP classes. Without this flag, the classes may not be regenerated (if determined to be unnecessary).
-lineNumbers	Adds JSP line numbers to generated class files to aid in debugging.
-basicClientJar	Does not include deployment descriptors in client JARs generated for EJBs.
-idl	Generates IDL for EJB remote interfaces.
-idlOverwrite	Always overwrites existing IDL files.
-idlVerbose	Displays verbose information for IDL generation.
-idlNoValueTypes	Does not generate valuetypes and the methods/attributes that contain them.
-idlNoAbstractInterfaces	Does not generate abstract interfaces and methods/attributes that contain them.
-idlFactories	Generates factory methods for valuetypes.
-idlVisibroker	Generates IDL somewhat compatible with Visibroker 4.5 C++.
-idlOrbix	Generates IDL somewhat compatible with Orbix 2000 2.0 C++.
-idlDirectory <dir>	Specifies the directory where IDL files will be created (default : target directory or JAR)
-idlMethodSignatures <>	Specifies the method signatures used to trigger IDL code generation.
-iiop	Generates CORBA stubs for EJBs.
-iiopDirectory <dir>	Specifies the directory where IIOP stub files will be written (default : target directory or JAR)
-keepgenerated	Keeps the generated .java files.
-compiler <javac>	Selects the Java compiler to use.
-g	Compiles debugging information into a class file.
-O	Compiles with optimization on.
-nowarn	Compiles without warnings.
-verbose	Compiles with verbose output.
-deprecation	Warns about deprecated calls.
-normi	Passes flags through to Symantec's sj.
-J<option>	Passes flags through to Java runtime.
-classpath <path>	Selects the classpath to use during compilation.
-advanced	Prints advanced usage options.

The following are the available appc options:

appc Ant Task

You can use the following Ant task to invoke the appc compiler:

<taskdef name="appc" classname="weblogic.ant.taskdefs.j2ee.Appc"/>

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.

 

---

Application Lifecycle Events

Application lifecycle listener events provide handles on which developers can control behavior during deployment, undeployment, and redeployment. This section discusses how you can use the application lifecycle listener events.

Four application lifecycle events are provided with WebLogic Server:

• Prestart—the beginning of the prepare phase. You can use the prestart event to establish a connection pool.
• Poststart—the end of the activate phase; the application is deployed.
• Prestop—the beginning of the deactivate phase. You can use the prestop event to disconnect from the database.
• Poststop—the end of the remove phase.

User-defined listeners can be:

• Listeners—attachable to any event. Possible methods for Listeners are:
• public void preStart(ApplicationLifecycleEvent evt) {}
• public void postStart(ApplicationLifecycleEvent evt) {}
• public void preStop(ApplicationLifecycleEvent evt) {}
• public void postStop(ApplicationLifecycleEvent evt) {}
• Startup—attachable to prestart and poststart events.
• Shutdown—attachable to prestop and poststop events.

Note: For Startup and Shutdown classes, you only implement a main{} method. If you implement any of the methods provided for Listeners, they are ignored.

Note: No remove{} method is provided in the ApplicationLifecycleListener, since the events are only fired at startup time during deployment (prestart and poststart) and shutdown during undeployment (prestop and poststop).

Basic Functionality

You create a listener by extending the abstract class (provided with WebLogic Server) weblogic.application.ApplicationLifecycleListener. The container then searches for your listener.

You override the following methods provided in the WebLogic Server ApplicationLifecycleListener abstract classto extend your application and add any required functionality:

• preStart{}
• postStart{}
• preStop{}
• postStop{}

Listing 2-1 illustrates how you override the ApplicationLifecycleListener. In this example, the public class MyListener extends ApplicationLifecycleListener.

Listing 2-1 MyListener

import weblogic.application.ApplicationLifecycleListener;

import weblogic.application.ApplicationLifecycleEvent;

public class MyListener extends ApplicationLifecycleListener {

  public void preStart(ApplicationLifecycleEvent evt) {

     System.out.println

     ("MyListener(preStart) -- we should always see you..");

   } // preStart

  public void postStart(ApplicationLifecycleEvent evt) {

     System.out.println

     ("MyListener(postStart) -- we should always see you..");

   } // postStart

  public void preStop(ApplicationLifecycleEvent evt) {

     System.out.println

     ("MyListener(preStop) -- we should always see you..");

   } // preStart

  public void postStop(ApplicationLifecycleEvent evt) {

     System.out.println

     ("MyListener(postStop) -- we should always see you..");

   } // preStart

   public static void main(String[] args) {

     System.out.println

     ("MyListener(main): in main .. we should never see you..");

   } // main

}

Listing 2-2 illustrates how you implement the Shutdown class. This class is attachable to prestop and poststop events. In this example, the public class MyShutdown extends ApplicationLifecycleListener.

Listing 2-2 MyShutdown

import weblogic.application.ApplicationLifecycleListener;

import weblogic.application.ApplicationLifecycleEvent;

public class MyShutdown extends ApplicationLifecycleListener {

   public static void main(String[] args) {

     System.out.println

     ("MyShutdown(main): in main .. should be for post-stop");

   } // main

}

Listing 2-3 illustrates how you implement the Startup class. This class is attachable to prestart and poststart events.. In this example, the public class MyStartup extends ApplicationLifecycleListener.

Listing 2-3 MyStartup

import weblogic.application.ApplicationLifecycleListener;

import weblogic.application.ApplicationLifecycleEvent;

public class MyStartup extends ApplicationLifecycleListener {

   public static void main(String[] args) {

     System.out.println

     ("MyStartup(main): in main .. should be for pre-start");

   } // main

}

Configuring Lifecycle Events: URI Parameter

The following are examples illustrating how you configure the application lifecycle events in the application.xml deployment descriptor file. The URI parameter is not required. You can place classes anywhere in the application $CLASSPATH. However, you must ensure that the class locations are defined in the $CLASSPATH. You can place listeners in APP-INF/classes or APP-INF/lib, if these directories are present in the EAR. In this case, they are automatically included in the $CLASSPATH.

The following example illustrates how you configure application lifecycle events using the URI parameter. In this case, the archive foo.jar contains the classes and exists at the top level of the EAR file. For example: myEar/foo.jar

Listing 2-4 Configuring Application Lifecycle Events without URI Parameter

  <listener>

       <listener-class>MyListener</listener-class>

       <listener-uri>foo.jar</listener-uri>

  </listener>

  <startup>

       <startup-class>MyStartup</startup-class>

       <startup-uri>foo.jar</startup-uri>

  </startup>

  <shutdown>

       <shutdown-class>MyShutdown</shutdown-class>

       <shutdown-uri>foo.jar</shutdown-uri>

  </shutdown>

The following example illustrates how you configure application lifecycle events without using the URI parameter.

Listing 2-5 Configuring Application Lifecycle Events without URI Parameter

 <listener>

       <listener-class>MyListener</listener-class>

  </listener>

  <startup>

       <startup-class>MyStartup</startup-class>

  </startup>

  <shutdown>

       <shutdown-class>MyShutdown</shutdown-class>

  </shutdown>

 

---

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. Arrange the resources (servlets, JSPs, static files, and deployment descriptors) in the prescribed directory format. For more information on the Web application directory structure, see "Web Application Basics" in Developing Web Applications for WebLogic Server.
5. 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 using WebLogic Builder. For detailed information, refer to WebLogic Builder Online Help. See Developing Web Applications for WebLogic Serverfor detailed information on the elements in these deployment descriptors.

6. Package the HTML pages, servlet class files, JSP files, web.xml file, and weblogic.xml file 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 packaging, refer to WebLogic Server Application Packaging.

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

   For detailed information about auto-deploying components and applications, refer to "Deployment Tool Reference" in Deploying WebLogic Server Applications.

   While you are testing the Web application, you might need to edit the Web application deployment descriptors. You can do this manually or use WebLogic Builder.

   For detailed information, refer to WebLogic Builder Online Help. See Developing Web Applications for WebLogic Serverfor detailed information on the elements in these deployment descriptors.

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

   Refer to Deploying WebLogic Server Applications 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 WebLogic Builder to automatically generate them. For more information, refer to Deploying WebLogic Server Applications.

   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 WebLogic Server Application Packaging.

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

   For detailed information about auto-deploying components and applications, refer to "Deployment Tool Reference" in Deploying WebLogic Server Applications.

   While you are testing the EJB, you might need to edit the EJB deployment descriptors. You can do this manually or use WebLogic Builder.

   For detailed information, refer to WebLogic Builder Online Help. See Developing Web Applications for WebLogic Serverfor detailed information on the elements in these deployment descriptors.

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.

   Refer to Deploying WebLogic Server Applications 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, Final Release (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 WebLogic Server J2EE Connectors.

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 similar to the following in the staging directory:

   jar cvf myRAR.rar * 

   For detailed information about creating the resource adapter RAR archive file, refer to WebLogic Server Application Packaging.

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

   For detailed information about auto-deploying components and applications, refer to "Tools for Deploying" in Deploying WebLogic Server Applications.

   While you are testing the resource adapter, you might need to edit the resource adapter deployment descriptors. You can do this manually or use WebLogic Builder.

   For detailed information, refer to WebLogic Builder Online Help. See Programming WebLogic Server J2EE Connectorsfor detailed information on the elements in these 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 Deploying WebLogic Server Applications 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 WebLogic Server J2EE Connectors 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.

   For detailed information about deploying components and applications, refer to "Tools for Deploying" in Deploying WebLogic Server Applications.

 

---

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 WebLogic Server J2EE Connectors.

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 and edit the XML deployment descriptors manually, or use WebLogic Builder to automatically generate them. For more information, refer to Deploying WebLogic Server Applications.

   For detailed information about the various deployment descriptor elements, refer to Developing Web Applications for WebLogic Server, Programming WebLogic Enterprise JavaBeans, and Programming WebLogic Server J2EE Connectors.

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 WebLogic Server Application Packaging 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 WebLogic Builder to automatically generate it. For more information, refer to Deploying WebLogic Server Applications.

   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, see WebLogic Server Application Packaging.

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 enterprise application deployment descriptor. You can do this manually or use WebLogic Builder.

   For detailed information on WebLogic Builder, refer to WebLogic Builder Online Help.

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

7. For production purposes, deploy the EAR file on WebLogic Server.

   For detailed information about deploying components and applications, refer to "Deployment Tools Reference" in Deploying WebLogic Server Applications.

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

Figure 2-1 Creating Enterprise Applications

 

 

---

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.
• Set your environment by creating a command file or script to set variables in your environment, which you can pass to the compiler.

Creating Compile Scripts Using Apache Ant

The preferred BEA method for compiling is using Apache Ant. Apache Ant is a Java-based build tool. One of the benefits of using Ant is that is it extended using Java classes, rather than shell-based commands. Another benefit is that Ant is a cross-platform tool.

Developers write Ant build scripts using eXtensible Markup Language (XML). XML tags define the targets to build, dependencies among targets, and tasks to execute in order to build the targets.

Instead of a model where it is extended with shell-based commands, Ant is extended using Java classes. Ant libraries are bundled with WebLogic Server to make it easier for our customers to build Java applications out of the box.

In order 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\server\config\examples directory.

For a complete explanation of ant capabilities, see: http://jakarta.apache.org/ant/manual/index.html

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:

samples\server\src\examples\ejb20\basic\beanManaged\build.xml

Also refer to the following WebLogic Server documentation on building examples using Ant:

samples\server\src\examples\examples.html

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\java141 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\java141\bin:$PATH; export $PATH

To add the WebGain sj compiler to your path on Windows NT, Windows 2000 or Windows 2000 XP, 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.
• The examples.property file for Apache Ant (for examples environment). This file is discussed in the WebLogic Server documentation on building examples using Ant located at: samples\server\src\examples\examples.html
• 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\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 an Apache Ant script to compile and package your components and applications.

 

---

Auto-Deployment for Development Enviroments

Auto-deployment is a method for quickly deploying an application on the administration server. It is recommended that this method be used only in a single-server development environment for testing an application. Use of auto-deployment in a production environment or for deployment of components on managed servers is not recommended.

If auto-deployment is enabled, when an application is copied into the \applications directory of the administration server, the administration server detects the presence of the new application and deploys it automatically (if the administration server is running). If WebLogic Server is not running when you copy the application to the \applications directory, the application is deployed the next time the WebLogic Server is started. Auto-deployment deploys only to the administration server

Note: Due to the strict file locking limitations of Windows NT, if your applications are exploded, all the components within your applications must also be exploded. In other words, WebLogic Server cannot support a JAR file within an exploded application or component.

Enabling and Disabling Auto-Deployment

You can run WebLogic Server in two different modes: development and production. You use development mode to test your applications. Once they are ready for a production environment, you deploy your applications on a server that is started in production mode.

Development mode enables a WebLogic Server to automatically deploy and update applications that are in the domain_name/applications directory (where domain_name is the name of a WebLogic Server domain). In other words, development mode lets you use auto-deploy.

Production mode disables the auto-deployment feature. Instead, you must use the WebLogic Server Administration Console or the weblogic.Deployer tool.

By default, a WebLogic Server runs in development mode. To specify the mode for a server, do one of the following:

If you use the startWebLogic startup script, edit the script and set the STARTMODE variable as follows:

STARTMODE = false enables deployment mode

STARTMODE = true enables production mode

If you start a server entering the weblogic.Server command directly on the command line, use the -Dweblogic.ProductionModeEnabled option as follows:

-Dweblogic.ProductionModeEnabled=false enables deployment mode 

-Dweblogic.ProductionModeEnabled=true enables production mode

Auto-Deploying Applications

This is a convenience feature for deploying applications during development. It allows deploying of applications or individual J2EE modules to the administration server just by copying the deployment into a predefined auto-deployment directory. This directory is located under the domain directory, e.g., mydomain/applications.

Stopping and Redeploying Archived Applications

An application or its component that was auto-deployed can be dynamically redeployed while the server is running. To dynamically redeploy a JAR, WAR or EAR file, simply copy the new version of the file over the existing file in the \applications directory.

This feature is useful for developers who can simply add the copy to the \applications directory as the last step in their makefile, and the server will then be updated.

If you delete the application from the \applications directory, the application will be stopped and removed from the configuration.

Redeploying Applications in Exploded Format

You can also dynamically redeploy applications or components that have been auto-deployed in exploded format. When an application has been deployed in exploded format, the administration server periodically looks for a file named REDEPLOY in the exploded application directory. If the timestamp on this file changes, the administration server redeploys the exploded directory.

If you want to update files in an exploded application directory, do the following:

1. When you first deploy the exploded application, create an empty file named REDEPLOY, and place it in the WEB-INF or META-INF directory, depending on the application type you are deploying:

   An exploded application contains a META-INF top-level directory; this contains the application.xml file.

   An exploded Web application contains a WEB-INF top-level directory; this contains the web.xml file.

   An exploded EJB application contains a META-INF F top-level directory; this contains the ejb-jar.xml file.

   An exploded connector contains a META-INF top-level directory; this contains the ra.xml file.

2. To update the exploded application, copy the updated files over the existing files in that directory.
3. After copying the new files, modify the REDEPLOY file in the exploded directory to alter its timestamp.

When the administration server detects the changed timestamp, it redeploys the contents of the exploded directory.