Skip navigation.

eDocs Home > BEA WebLogic Server 9.1 Documentation > Beehive Integration in WebLogic Server 9.1 > Building Beehive Applications

Beehive Integration in WebLogic Server 9.1

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents Index View as PDF   Get Adobe Reader

Building Beehive Applications


 

 

Build Resources

WebLogic Server ships with the following Ant files for building and deploying Beehive applications:

<WEBLOGIC_HOME>\beehive\weblogic-beehive\ant\weblogic-beehive-buildmodules.xml
<WEBLOGIC_HOME>\beehive\weblogic-beehive\ant\weblogic-beehive-tools.xml
<WEBLOGIC_HOME>\beehive\weblogic-beehive\ant\weblogic-beehive-imports.xml

weblogic-beehive-buildmodules.xml contains build macros (<macrodef> elements) for building a web app module and other module-leve artifacts. Use this file for easiest building.

weblogic-beehive-tools.xml contains build macros for building other Beehive-related source artifacts, including XMLBean schemas and the three Beehive components: Java Controls, NetUI Page Flow and Web Services. Use this file instead of weblogic-beehive-buildmodules.xml if you need more flexible control over project structure.

weblogic-beehive-imports.xml is a utility file that defines paths to build resource JARs required by weblogic-beehive-tools.xml.

To use these build resources, import these three files into your Ant build file:

<import file="${beehive.home}/weblogic-beehive/ant/weblogic-beehive-imports.xml"/>
<import file="${beehive.home}/weblogic-beehive/ant/weblogic-beehive-tools.xml"/>
<import file="${beehive.home}/weblogic-beehive/ant/weblogic-beehive-buildmodules.xml"/>

Then call the build macros to build your Beehive application. For example, the following Ant target calls the build-webapp macro (<macrodef name="build-webapp"/>) located in weblogic-beehive-buildmodules.xml.

<build-webapp
     webapp.src.dir="${src.dir}/myWebApp"
     webapp.build.dir="${dest.dir}/myWebApp"
     app.build.classpath="myWebApp.build.classpath"/>
</target>

A template Ant build file is provided in Template Build File. The Beehive Tutorial puts this template Ant build file into practice.

Note that the template build file assumes that your Beehive application contains the following library reference in myBeehiveApp\META-INF\weblogic-application.xml:

<weblogic-application xmlns="http://www.bea.com/ns/weblogic/90">
  <library-ref>
    <library-name>weblogic-beehive-1.0</library-name>
  </library-ref>
</weblogic-application>

If your Beehive application contains a web module, the template build file assumes the following library references in myBeehiveApp\myWebApp\WEB-INF\weblogic.xml:

<weblogic-web-app
    xmlns="http://www.bea.com/ns/weblogic/90"
    xmlns:j2ee="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.bea.com/ns/weblogic/90
    http://www.bea.com/ns/weblogic/90/weblogic-web-app.xsd">
    <library-ref>
        <library-name>beehive-netui-1.0</library-name>
    </library-ref>
    <library-ref>
        <library-name>struts-1.2</library-name>
    </library-ref>
    <library-ref>
        <library-name>jstl-1.1</library-name>
    </library-ref>
</weblogic-web-app>

On disk, these referenced libraries reside in the EAR and WAR files at <WEBLOGIC_HOME>\common\deployable-libraries. Note that the Ant task <libclasspath> is used to unpack the referenced EAR and WAR files. See Using the libclasspath Ant Task in Developing Applications with WebLogic Server.

Note: These libraries allow you to use the Beehive JARs without copying them into your application or putting them on the systm CLASSPATH. For an overview and detailed information about shared libraries, see the WebLogic Server document Creating Shared J2EE Libraries and Optional Packages

 

Ant Tasks

The following Ant macros describe the most important Ant tasks included in the build resource files.

weblogic-beehive-buildmodules.xml

build-webapp-module

Builds and assembles a web application module. This Ant task will compile any page flows and Java Controls inside the web application.

This task takes the following parameters:

Name

Definition

webapp.src.dir

Required. The base directory of the web application

webapp.build.dir

Required. The web application build directory

app.build.dir

Required. The application build directory

app.build.classpath

Required. The classpath used for compilation

temp.dir

Required. A temporary directory

Control source Java files are assumed to be under [webAppDir]\WEB-INF\src.

Page flow source Java files are assumed to be under [webAppDir].

build-control-module

Builds a distributable control JAR from a directory of Java control source files.

The task takes the following parameters:

Name

Definition

srcdir

Required. The directory containing the Java sources

destjar

Required. The name of the JAR produced

tempdir

Required. A temporary directory containing the generated sources and classes

classpathref

Required. The classpath used for compilation

Error during Build

Because of a known bug, you may encounter this error message when using the build-control-module task:

<drive>:\bea\weblogic91\beehive\weblogic-beehive\ant\weblogic-beehive-buildmodules.xml:140: taskdef class org.apache.beehive.controls.runtime.packaging.ControlJarTask cannot be found

To correct this, you must modify your Ant build file.

After the line in the file where weblogic-beehive-imports.xml and weblogic-beehive-tools.xml are imported, and before the line where weblogic-beehive-buildmodules.xml is imported, insert the following line:

<property name="controls.jars.prop" refid="controls.dependency.path"/>

That section of your Ant build file should then look like this:

<import file="${beehive.home}/weblogic-beehive/ant/weblogic-beehive-imports.xml"/>
<import file="${beehive.home}/weblogic-beehive/ant/weblogic-beehive-tools.xml"/>
<property name="controls.jars.prop" refid="controls.dependency.path"/>
<import file="${beehive.home}/weblogic-beehive/ant/weblogic-beehive-buildmodules.xml"/>

build-ejb-module

Builds an EJB JAR from one or more EJB controls.

The task takes the following parameters:

Name

Definition

srcdir

Required. The directory containing the EJB sources

destjar

Required. The name of the JAR produced containing the EJB controls

tempdir

Required. A temporary directory containing the generated sources and classes

classpathref

Required. The classpath used for compilation

weblogic-beehive-tools.xml

Note: As was mentioned above, you should only use this file if you want the added flexibility it provides. Otherwise, use weblogic-beehive-buildmodules.xml.

assemble-controls

Assemble the controls found in a directory. Assembly is required as part of the process of compiling web service, JMS, and EJB controls. For details on the control build process, see Building JMS and EJB Controls.

The task takes the following parameters:

Name

Definition

moduledir

Required. The directory containing the exploded contents of the module

destdir

Required. The destination directory for compiled class files

classpathref

Required. The classpath used for compilation

assemblerclass

Required.

For EJB modules the value must be

org.apache.beehive.controls.runtime.assembly.EJBAssemblyCo ntext$Factory

For web app modules the value must be

org.apache.beehive.controls.runtime.assembly.WebAppAssembl yContext$Factory

generate-type-library

Generates a Java type library from a WSDL file. The types are packaged as a JAR file. If the WSDL contains complex Java types, it is necessary to run this target as part of the process of generating a service control from the WSDL. For details on generating a service control from a WSDL, see Building Web Service Controls.

The task takes the following parameters:

Name

Definition

wsdl

Required. The WSDL file from which the type library is to be generated

wsdlname

Required. The relative path of the WSDL to the project in which it is placed (without the .wsdl extension)

wsdlservicename

Required. The service name in the WSDL containing the complex-types from which the type-library will be generated

tempdir

Required. A temporary directory

destdir

Required. The directory where the type-library JAR will be placed

typefamily

Optional. The type family; default value is tylar

generate-webservice-client

Generates a web service client from a WSDL file.

The task takes the following parameters:

Name

Definition

wsdl

Required. The WSDL file from which the client will be generated

tempdir

Required. A temporary directory containing the generated sources

destjar

Required. The directory where the client will be placed

package

Required. The package of the generated source

generate-webservice-control

Generates a web service control from a WSDL file.

The task takes the following parameters:

Name

Definition

wsdl

Required. The WSDL file from which the service control is to be generated

wsdlservicename

Required. The WSDL service name

servicecontrolname

Required. The service control class name

destdir

Required. The directory where the web service control class and WSDL will be placed

appdir

Required. The application directory

package

Required.

typefamily

Optional. The type family; the default value is no_complex_types

classpathref

Required. The classpath used for compilation

 

Building Beehive Applications

As a starting point for building Beehive applications, use the build template file provided in Template Build File. For each component in your Beehive application, add build elements to the template build file.

For each web application (any component containing page flows and Java Controls) call <build-webapp>.

Web services should be compiled using the <jwsc> (weblogic.wsee.tools.anttasks.JwscTask) target.

To build applications that contain the system controls, see Building Web Service Controls and Building JMS and EJB Controls.

For a detailed example of building a page flow web application, see Create a New Page Flow Web Application.

Building Web Service Controls

The following instructions explain how to create a web service control, integrate it into a Beehive application, and compile the resulting application. The instructions assume that you have access to the target web service's WSDL file.

  1. Acquire the WSDL for the target web service.
  2. Call <build-type-library> (defined in weblogic-beehive-tools.xml) if there are any complex Java types passed by the target web service.

    3. This will generate a type library JAR file, which should be saved in the application's APP-INF\lib directory.

    <build-type-library
      wsdl="${src.dir}/services/MyService.wsdl"
      wsdlname="MyService.wsdl"
      wsdlservicename="MyService"
      tempdir="c:/temp/services"
      destdir="${dest.dir}/APP-INF/lib"
      typefamily="tylar"
    />

    Calling <build-type-library> is only necessary if the web service contains complex Java types; if the web service contains only standard Java types, this step can be skipped.

  3. Call <generate-webservice-control> (defined in weblogic-beehive-tools.xml).

    4. This will generate a Java source file for the web service control.

    If the web service does not contain complex types, then the typefamily attribute should have the value no_complex_types.

    <generate-webservice-control
              wsdl="${src.dir}/services/MyService.wsdl"
              wsdlservicename="MyService"
              servicecontrolname="MyServiceControl"
              destdir="${dest.dir}/services"
              appdir="${src.dir}"
              package="pkg"
              typefamily="no_complex_types"
               classpathref="app.classpath"/>

    The Java source file that is created should not be modified, except for the addition of security annotations. For details on the available security annotations, see Control Security.

  4. Place the Java web service control source file (and any type library JAR file) into the client application. Before the client can use the web service control, any annotations must be processed using apt.
    5. <taskdef name="apt"
                classname="org.apache.beehive.controls.runtime.generator.AptTask"
                classpathref="apt.task.classpath"
                onerror="fail"/>

            <apt srcdir="${src.dir}"
                destdir="${build.dir}/module"
                gendir="${build.dir}/aptgen"
                classpathref="classpath"
                srcExtensions="*.jws"
                />
  5. After running apt, you build the initial version of the jws ejb jar. You do this by running jwsc against the code generated by apt, which is stored in the directory specified by the gendir attribute in the preceding step.
    6. <taskdef name="jwsc"
                classpath="${weblogic.home}/server/lib/weblogic.jar"
                classname="weblogic.wsee.tools.anttasks.JwscTask"
                onerror="report" />

            <jwsc srcdir="${build.dir}/aptgen"
              destdir="${ent.app.dir}"
              classpathref="classpath"
              debug="on" keepGenerated="true">
              <jws file="hellotest/HelloTest.java"/>
            </jwsc>
  6. Now the client must be assembled, which creates appropriate bindings between the client and the web service control. You do this with the <assemble-controls> task. Calling <assemble-controls> creates Java source code (and modifies some deployment descriptors), which needs to be compiled in turn.

The following Ant targets illustrate how to implement steps 4 and 6 in a J2EE application context. Inside a J2EE application, the assemblerclass attribute should have the value org.apache.beehive.controls.runtime.assembly.EJBAssemblyContext$Factory. Inside of a web application context, assemblerclass should have the value org.apache.beehive.controls.runtime.assembly.WebAppAssemblyContext$Factory.

<!-- Assemble the controls to a tmp dir, then compile the assembly output -->
<assemble-controls
  moduledir="${dest.dir}/myApp"
  destdir="${assembly.build.tmp.dir}"
  classpathref="myWeb.assembly.classpath"   assemblerclass="org.apache.beehive.controls.runtime.assembly.EJBAssemblyContext$Factory"
  />
<javac srcdir="${assembly.build.tmp.dir}"
  destdir="${dest.dir}/myWeb/WEB-INF/classes"
  classpath="customerLoanWeb.assembly.classpath"
  />

Building JMS and EJB Controls

The process for generating JMS and EJB controls is identical to steps 4-6 in Building Web Service Controls: you must run assembly on the control and then compile the results of the assembly.

Detailed Example

For a detailed example of a build script that creates a web service application that uses a service control, see Build Script Sample - Create Web Service That Uses a Service Control,.

 

Template Build File

Use the following Ant build file as a template to build and deploy your Beehive applications.

Note that this template file uses the task <wlcompile>, which ensures that split source compilation and deployment will succeed. <wlcompile> also automatically searches for and compiles all Java files in your application. Be aware that <wlcompile> will fail if it encounters any Beehive-specific classes in your application. For this reason, you should exclude your Beehive projects from the <wlcompile> search. For example: 

<wlcompile srcdir="${src.dir}" destdir="${dest.dir}" excludes="myBeehiveProj1,myBeehiveProj2"/>

<?xml version="1.0" encoding="UTF-8" ?>
<project default="build" basedir=".">
<property environment="env"/>
<!-- provide overrides -->
<property file="build.properties"/>
<property name="src.dir" value="${basedir}"/>
<property name="dest.dir" value="${basedir}/../build"/>
<property name="dist.dir" value="${basedir}/../dist"/>
<property name="app.name" value="beehive_tutorial"/>
<property name="ear.path" value="${dist.dir}/${app.name}.ear"/>
<property name="tmp.dir" value="${java.io.tmpdir}"/>
<property name="weblogic.home" value="${env.WL_HOME}"/>
<property name="user" value="weblogic"/>
<property name="password" value="weblogic"/>
<fail unless="weblogic.home" message="WL_HOME not set in environment"/>
<property name="beehive.home" value="${weblogic.home}/beehive"/>
<!-- beehive-imports defines dependency paths that are required by beehive-tools.xml -->
  <import file="${beehive.home}/weblogic-beehive/ant/weblogic-beehive-imports.xml"/>
  <!-- defines macros for build-schemas, build-controls, build-pageflows -->
  <import file="${beehive.home}/weblogic-beehive/ant/weblogic-beehive-tools.xml"/>
  <!-- defines macros for build-webapp -->
  <import file="${beehive.home}/weblogic-beehive/ant/weblogic-beehive-buildmodules.xml"/>
<taskdef name="libclasspath" classname="weblogic.ant.taskdefs.build.LibClasspathTask"/>
<target name="init.app.libs">
     <!-- Builds classpath for library modules referenced in weblogic-applications.xml. -->
     <libclasspath basedir="${src.dir}" tmpdir="c:/tmp/wls_lib_dir" property="app.lib.classpath">
        <librarydir dir="${weblogic.home}/common/deployable-libraries/" />
     </libclasspath>
     <echo message="app.lib.claspath is ${app.lib.classpath}" level="info"/>
</target>
<target name="init.dirs">
     <mkdir dir="${dest.dir}/APP-INF/classes"/>
     <mkdir dir="${dest.dir}/APP-INF/lib"/>
     <mkdir dir="${dist.dir}"/>
</target>
<target name="init" depends="init.app.libs,init.dirs">
    <path id="app.classpath">
      <pathelement location="${src.dir}/APP-INF/classes"/>
      <pathelement location="${dest.dir}/APP-INF/classes"/>
      <pathelement path="${app.lib.classpath}"/>
      <fileset dir="${src.dir}/APP-INF/lib">
        <include name="**/*.jar"/>
      </fileset>
      <fileset dir="${dest.dir}/APP-INF/lib">
        <include name="**/*.jar"/>
    </fileset>
    <fileset dir="${beehive.home}/apache-beehive-1.0-final/lib/netui">
      <include name="**/*.jar"/>
      <exclude name="**/beehive-netui-compiler.jar"/>
    </fileset>
    </path>
    <wlcompile srcdir="${src.dir}" destdir="${dest.dir}"/>
</target>
<target name="build" depends="compile,appc"/>
<target name="compile" depends="init"/>
<target name="clean" depends="init.dirs,clean.dest,clean.dist"/>
<target name="clean.dest">
    <echo message="deleting dest.dir:${dest.dir}"/>
    <delete includeemptydirs="true" >
      <fileset dir="${dest.dir}" excludes=".beabuild.txt" includes="**/*" />
    </delete>
</target>
<target name="clean.dist">
    <echo message="deleting dest.dir:${dest.dir}"/>
    <delete includeemptydirs="true" >
      <fileset dir="${dist.dir}" includes="**/*" />
    </delete>
</target>
<target name="appc" depends="init" >
    <wlappc source="${dest.dir}" librarydir="${weblogic.home}/common/deployable-libraries/"/>
</target>
<target name="pkg.exploded">
    <antcall target="clean.dist"></antcall>
    <wlpackage toDir="${dist.dir}" srcdir="${src.dir}" destdir="${dest.dir}" />
</target>
<target name="deploy.exploded" >
    <wldeploy user="${user}" password="${password}" action="deploy" name="${app.name}" source="${dist.dir}"/>
</target>
<target name="deploy" >
    <wldeploy user="${user}" password="${password}" action="deploy" name="${app.name}" source="${dest.dir}"/>
</target>
<target name="redeploy">
    <wldeploy user="${user}" password="${password}" action="redeploy" name="${app.name}"/>
</target>
</project>

 

Skip navigation bar  Back to Top Previous Next