Assembling and Deploying Enterprise Applications

 

WebLogic Portal requires that you deploy all of your e-business resources within enterprise applications. Each enterprise application contains the following types of components (see Figure 5-1):

• Web applications that deploy data and administer your Web application

• EJBs that provide e-business functions

• Deployment descriptors

• Your Web application

  Figure 5-1 Your Enterprise Application

  
   

This topic describes how to assemble and deploy an enterprise application on a WebLogic Portal application server:

• Create Deployment Descriptors

• Create a Root Directory

• Add Your Web Application

• Add Supporting Web Applications

• Add JAR Files

• Create an EAR File (Optional)

• Deploy the Application

 

---

Create a Root Directory

Create a directory that serves as the root of your application. Choose a directory name that indicates the purpose and scope of the application. The name of the directory is not visible to customers who visit your site.

To support multiple developers in a development environment, you might deploy multiple instances of this enterprise application under different names on a single server. To do so, you must create multiple copies of the application's directory tree and rename the root directories for each instance. For example, you want to deploy multiple instances of an enterprise application whose root directory is name BankApp. You create two copies of the BankApp directory tree and change the root name of one tree to BankApp1 and the other to BankApp2. For more information, refer to Deploy Multiple Instances of an Application.

 

---

Create Deployment Descriptors

Each enterprise application uses two deployment descriptors: application.xml, which contains standard J2EE properties and application-config.xml, which contains properties that declare and configure JMX MBeans. WebLogic Portal uses MBeans to dynamically configure application services.

To create deployment descriptors for your enterprise application, do the following:

• Copy Reference Files

• Modify application.xml

• Modify application-config.xml

Copy Reference Files

The reference enterprise applications include deployment descriptors that declare the modules, security roles, and MBeans that are required to support WebLogic Portal.

To copy these files to your enterprise applications, do the following:

1. In the root directory of your application, create a directory named META-INF. For example:

   myApplication/META-INF

2. Copy the following files to your META-INF directory:

   PORTAL_HOME/applications/wlcsApp/META-INF/application.xml
   PORTAL_HOME/applications/wlcsApp/META-INF/application-config.xml

Modify application.xml

Open your application.xml in a text editor to make the following modifications:

• Application Name

• Declarations for Web Applications

• Declarations for EJBs

• Declarations of Security Roles

For a general introduction to the elements in application.xml, refer to "application.xml Deployment Descriptor Elements" in the WebLogic Server Developing Applications guide.

Application Name

At the top of the application.xml file is a declaration of the name of the enterprise application. WebLogic Server displays this name in the WebLogic Server Administration Console. Your customers do not see this name.

To provide a unique name for your application, change the values in the following elements:

<application>
<display-name>name-of-your-application</display-name>
<description>optional-text-description</description>

Declarations for Web Applications

In application.xml you must declare each Web application that you copy into your enterprise application's directory tree. For information about copying Web applications and declaring them in application.xml, refer to the following sections:

• Add Your Web Application

• Add Supporting Web Applications

Remove any <web> modules declaring Web applications that you are not including. Below is an example of a declaration for the catalogws Web application:

<module>
<web>
<web-uri>catalogws-webservice.war</web-uri>
<context-root>wlcsAppCatalogTool</context-root>
</web>
</module>

Declarations for EJBs

In application.xml you must declare each EJB that your application uses. For information on adding EJBs and declaring them in application.xml (and other deployment descriptors), refer to Add JAR Files.

Remove any <ejb> modules declaring EJBs that you are not including in your enterprise application.

Declarations of Security Roles

The application.xml file must declare all J2EE security roles that constituent Web applications use.

A WebLogic Portal application.xml file must declare all of the following security roles. Do not modify them: the EJBs and other components that support your applications expect these role names to be present in the application:

<security-role>
  <description>Registered customers with role CustomerRole
  </description>
  <role-name>CustomerRole</role-name>
</security-role>

<security-role>
  <description>Portal Administrators</description>
  <role-name>AdminRole</role-name>
</security-role> 

<security-role>
  <description>Anonymous access</description>
  <role-name>AnonymousRole</role-name>
</security-role>

<security-role>
  <description>Administrative role for ebusiness</description>
  <role-name>AdministrativeRole</role-name>
</security-role>

You can declare additional security roles to support your security scheme.

The weblogic.xml file for each Web application maps principals in the security realm to these J2EE security roles. For more information, refer to Security-Role Mappings.

The web.xml file for each Web application declares which role can access a set of secured resources. For more information, refer to Declarations of Secure JSPs.

Modify application-config.xml

The application-config.xml deployment descriptor declares MBeans and provides a persistent storage for their configuration data. Before you deploy your enterprise application, use a text editor to remove declarations for MBeans that configure services you do not use.

After you deploy your application, do not use a text editor to modify this file. Instead, use the WebLogic Server Administration Console to modify the MBean configurations. For more information, refer to Use the WebLogic Server Administration Console to Configure MBeans.

Similar to the JAR files and supporting Web applications, WebLogic Portal uses specific MBeans to support services. You can remove declarations for MBeans that configure services you do not use.

In all of the following XML elements, you can change the value of the name attribute to match your enterprise application, but it is not required.

The file contains declarations and configurations for the following MBeans:

• Event Service

• Behavior Tracking Service

• Campaign Service

• The Scenario Service

• Ad Service

• Mail Service

• Cache Service

• Document Manager and Document Connection Pool

• Entitlements Service

• JDBC Helper Service

• Tax and Payment Service Clients

Event Service

The following elements set parameters for the Event service:

<EventService
  Listeners="com.bea.campaign.internal.CampaignEventListener"
  Name="wlcsApp"    
>

</EventService>

You can include any of the following values in the Listeners attribute (separate multiple values with a comma):

• com.bea.p13n.events.listeners.DebugEventListener, which prints all dispatched events to the command window for debug purposes.

• com.bea.p13n.tracking.listeners.BehaviorTrackingListener, which activates the Behavior Tracking service.

• com.bea.campaign.internal.CampaignEventListener, which activates campaign-event listening. If you include this value, your application must deploy campaign.jar. For more information, refer to JARs for Campaign Services.

• A custom Java class that implements com.bea.p13n.events.EventListener.

For more information about these properties, refer to "Persisting Tracking Behavior Data" in the Guide to Events and Behavior Tracking.

Behavior Tracking Service

The following elements set parameters for the Behavior Tracking service:

<BehaviorTracking
    Name="wlcsApp" 
    MaxBufferSize="100"
    SweepInterval="10"
    SweepMaxTime="120"
    DataSourceJndiName="weblogic.jdbc.jts.commercePool"

    PersistedEventTypes="AddToCartEvent,BuyEvent,CampaignUserActivityEvent, 
    ClickContenEvent,ClickProductEvent,ClickCampaignEvent,DisplayContentEvent,
    DisplayProductProductEvent,DisplayCampaignEvent,PurchaseCartEvent,
    RemoveFromCartEvent,RuleEvent,SessionBeginEvent,SessionEndEvent,
    SessionLoginEvent,UserRegistartionEvent"
> 

</BehaviorTracking> 

Campaign Service

The following element and its subelements configure the Campaign Service for all Web applications in the current enterprise application.

Note: If you include this element and subelements, your CLASSPATH variable must specify campaign_system.jar. For more information, refer to Add Directories to CLASSPATH.

<CampaignService
      Name="wlcsApp"
      GoalCheckTime="300000"
      EmailBrowseBaseDir="campaigns/emails"
      EmailURIExtensions="jsp,html,htm,txt"
>

      <CampaignEventListener
        Name="wlcsApp"
       CampaignServiceJNDIName="${APPNAME}.
       BEA_campaign.CampaignService"
      >
      </CampaignEventListener>

      <MailAction
        Name="wlcsApp"
        DefaultFromAddress="[e-mail]"
        EmailPropertySet="CustomerProperties"
        EmailPropertyName="Email"
        OptInPropertySet="Demographics"
        OptInPropertyName="Email_Opt_In"
       >
      </MailAction>

</CampaignService> 

For more information about configuring campaigns to send email, refer to "Setting Up and Sending Email for Campaigns" in the Guide to Developing Campaign Infrastructure.

For information on configuring basic Mail Service features, refer to Mail Service.

The Scenario Service

The following element configures MBeans for the Scenario Service.

Note: If you include this element and subelements, your CLASSPATH variable must specify campaign_system.jar. For more information, refer to Add Directories to CLASSPATH.

<ScenarioService
      Name="wlcsApp"
      RulesSessionAttrNames="RulesRequestAttrNames"
>
</ScenarioService>

If you use Commerce services with your campaigns, include the following element:

<AttributeLoader
 RequestLoaders="com.bea.commerce.ebusiness.campaign.ShoppingCartAttribute
/>

In addition to including the <AttributeLoader> element your application must deploy commerce_campaign_bridge_util.jar. For more information, refer to JARs for Campaign and Commerce Interaction.

Ad Service

The attributes and subelements in the AdService element support ad placeholders and the <ad:adTarget> JSP tag. The AdContentProvider element register Java classes that render the HTML necessary to display specific types of content (based on MIME type). If you create Java classes to display additional types of content, you must add a <AdContentProvider> element as described in "Supporting Additional MIME Types" under "Setting Up Ads for Campaigns" in the Guide to Developing Campaign Infrastructure.

The AdService element includes an EventTracker attribute. You can place any of the following values in the EventTracker attribute (separate multiple entries with a comma):

• com.bea.p13n.ad.AdEventTrackerBase (the default).

• com.bea.campaign.AdTracking. This attribute enables campaigns to use ad placeholders. If you use this attribute, you must deploy campaign.jar.

• A custom written class that implements com.bea.p13n.ad.AdEventTracker.

Below is an example of the <AdService> element:

<AdService
    Name="wlcsApp"
    DisplayFlushSize="10"
    Rendering="com.bea.p13n.ad.AdContentProviderBase"
    EventTracker="<AdEventTracker class name>"
    AdClickThruURI="AdClickThru"
    ShowDocURI="ShowDoc"
>

    <AdContentProvider
      Name="text"
      Provider="com.bea.p13n.ad.render.TextContentProvider"
      Properties=""
     >
     </AdContentProvider>

     <AdContentProvider
       Name="image"
       Provider="com.bea.p13n.ad.render.ImageContentProvider"
       Properties="AdClickThruURI=AdClickThru;ShowDocURI=ShowDoc"
      >
      </AdContentProvider>

     <AdContentProvider
       Name="application/x-shockwave-flash"
       Provider="com.bea.p13n.ad.render.ShockwaveContentProvider"
       Properties="ShowDocURI=ShowDoc"
     >
     </AdContentProvider>

</AdService>

Mail Service

The MailService element configures the basic features of the Mail Service:

<MailService
Name="wlcsApp"
SMTPHost="boulder"
>
</MailService>

Note: The Campaign Service uses the Mail Service to send email. The <CampaignService> element includes a subelement for configuring how campaigns use the Mail Service. For more information, refer to Campaign Service.

In addition to using campaigns to access the Mail Service, you can access and use the Mail Service from the com.bea.p13n.mail.MailManager command. For more information, refer to "Sending Bulk Mail" in the Guide to Developing Campaign Infrastructure.

Cache Service

The CacheManager element and its subelements declare named configurations for caches. When you create a cache, you can specify one of these configurations. The CacheFactory API spawns an MBean which, in turn, configures the cache on all nodes of a cluster.

For more information about configuring caches, refer to "Using Caches" in the Performance Tuning Guide.

Document Manager and Document Connection Pool

Use the DocumentManager element to configure the DocumentManager EJB, which does the following:

• Gets an enumeration of content objects (documents stored in a content management system) that match the search parameters of a query.

• Retrieves the content objects for the object that initiated the query.

In the following example from a reference web.xml file, the Web application configures DocumentManager with all default values:

<DocumentManager
    Name="default"
    DocumentConnectionPoolName="default"
    PropertyCase="none"
    MetadataCaching="true"
    MetadataCacheName="documentMetadataCache"
    UserIdInCacheKey="false"
    ContentCaching="true"
    ContentCacheName="documentContentCache"
    MaxCachedContentSize="32768"
>
</DocumentManager>

Use the DocumentConnectionPool element to configure a connection pool for the DocumentManager EJB. The DocumentManager uses this pool to maintain connections to the content management system, and thus reduce overhead for each time it accesses the system.

In the following example from a reference web.xml file, the Web application configures DocumentConnectionPool:

<DocumentConnectionPool
    Name="default"
    DriverName="com.bea.p13n.content.document.jdbc.Driver"
    URL="jdbc:beasys:docmgmt:com.bea.p13n.content.document.  
          ref.RefDocumentProvider"
    Properties="jdbc.dataSource=weblogic.jdbc.pool.commercePool;
                schemaXML=C:/bea/Portal4.0/dmsBase/doc-schemas;
                docBase=C:/bea/Portal4.0/dmsBase"
    InitialCapacity="20"
    MaxCapacity="20"
    CapacityIncrement="0"
/>

For more information, refer to "Creating and Managing Content" in the Guide to Building Personalized Applications.

Entitlements Service

An entitlement segment is a visitor group based on common characteristics that allows a member of the group to view certain aspects of a portal. For example, if you create a portal that provides information about city council meeting in Los Angeles, you might want to define an entitlement group for that portlet that consists of visitors who live in Los Angeles county and are of voting age.

The Entitlements Service MBean specifies the JNDI name for the Rules Service, which it uses to evaluate whether a visitor belongs to a given entitlement group and to determine which resources the visitor can access.

<Entitlements
Name="wlcsApp"
RulesServiceJNDIName="BEA_personalization.RulesManager"
>
</Entitlements>

Commerce Pipeline

The following element declares an MBean for configuring a JDBC Pool. Commerce Pipeline Components use this JDBC pool to get sequence numbers for new orders (in CommitOrderPC) and when generating a transactionID for a payment transaction.

<CommercePipelineComponentSupport
JdbcPoolName="weblogic.jdbc.jts.commercePool"
/>

You must deploy this MBean if you use any Order-related Pipeline Components.

If you include this element, your CLASSPATH variable must specify commerce_system.jar. For more information, refer to Add Directories to CLASSPATH.

JDBC Helper Service

The JDBC Helper Service is the only means for services to explicitly establish a database connection. The process for getting a connection includes wait and retry functionality.

The service also provides Java classes (delegates) to coordinate the processing of CLOB data. Use the WebLogic Server Administration Console to specify the delegate class for your specific database type. For information on setting up the JDBC Helper for Oracle and SQL Server database types, refer to Part II, Deploying Your Business Data. For information on setting up the service for other database types that are supported for the current release, refer to PORTAL_HOME/db/readme.html.

<JdbcHelper Name="JdbcHelper"
JdbcHelperDelegate="@DATABASE_JDBC_HELPER@"
MaxRetries="-1"
MaxWaitTime="-1"
>
</JdbcHelper>

Tax and Payment Service Clients

The Tax Service client enables your WebLogic Portal application to contact a Web service that will calculate taxes for the orders on your site. WebLogic Portal provides a sample Web service application (taxWSApp). You must find a third party Web service to fulfill this function of your site. The following element in application-config.xml configures an MBean, which, in turn, you use to configure the Tax Service client.

You do not need to change this element in application-config.xml. Instead, use the WebLogic Server Administration Console to configure the Tax Service client. (Refer to Use the WebLogic Server Administration Console to Configure MBeans.)

<TaxServiceClient
Name="wlcsApp"
TaxCalculatorJNDIName="BEA_commerce.TaxCalculator"
TaxCalculatorWSDL= "http://localhost:7501/taxws/BEA_commerce.TaxWebService/wsdl.jsp"
Currency="USD"
ShipFromProvince="CO"
ShipFromCity="Boulder"
ShipFromPostalCode="80302"
ShipFromLocationCode="00"
ShipFromCountryCode="USA"
OrderOriginProvince="CO"
OrderOriginCity="Boulder"
OrderOriginPostalCode="80302"
OrderOriginLocationCode="00"
OrderOriginCountryCode="USA"
CompanyID="Company ID goes here"
BusinessLocationCode="Business Location code"
AVSReturnListOnZipFailure="false"
>
</TaxServiceClient>

The <TaxServiceClient> element specifies the JNDI name of the tax service (the Order and Payment service use this JNDI name to contact the Tax Service client), the location of your tax Web service application, and default values that WebLogic Portal provides as part of the tax calculation process. For more information on the Tax Service client, refer to "Taxation Services" in the Guide to Managing Purchases and Processing Orders.

The Payment Service client enables your WebLogic Portal application to contact a Web service that will confirm and complete credit card transactions for the orders on your site. WebLogic Portal provides a sample Web service application (paymentWSApp). You must find a third party Web service to fulfill this function of your site. The following element in application-config.xml configures an MBean, which, in turn, you use to configure the Payment Service client.

You do not need to change this element in application-config.xml. Instead, use the WebLogic Server Administration Console to configure the Payment Service client. (Refer to Use the WebLogic Server Administration Console to Configure MBeans.)

<PaymentServiceClient
Name="bankApp"
PaymentWebServiceWSDL=
"http://localhost:7501/paymentws/BEA_commerce.CreditCardWebService/wsdl.jsp"
DeferAuthorization="true"
PaymentModel="AUTO_MARK_AUTO_SETTLE"
>
</PaymentServiceClient>

The <PaymentServiceClient> element specifies the JNDI name of the payment service (the Order and Payment service use this JNDI name to contact the payment service) and an option to collect all credit card requests as a batch (DeferAuthorization="true"). For more information on the Payment Service, refer to "Payment Services" in the Guide to Managing Purchases and Processing Orders.

Use the WebLogic Server Administration Console to Configure MBeans

After you deploy your application, use only the WebLogic Server Administration Console to configure MBeans.

To configure MBeans, do the following:

1. Start the WebLogic Server Administration Console by entering the following URL in a Web browser:

   http://hostname:port-number/console

   For example, you started a server on a host named bonnie and it uses port 7001 as a listen-on port. Enter the following URL:

   http://bonnie:7001/console

2. The WebLogic Server Administration Console prompts you to log in with a user account that has administrator privileges.

3. After you log in to the WebLogic Server Administration Console, in the left pane, click Deployments -> Applications -> MyApplication -> Service Configuration.

4. Click the MBean that you want to configure. (See Figure 5-2 for an example of configuring cache MBeans.)

   Figure 5-2 Configuring a Cache MBean

   
    

 

---

Add Your Web Application

Copy your Web application into the root directory of the enterprise application. In a development environment, we recommend that you deploy the Web application as an exploded directory tree. In this format, you can dynamically deploy additional or modified JSPs and other resources.

In a production environment, deploy the Web application as an archive file (WAR file).

In the application.xml deployment descriptor, use the following syntax to declare your Web application:

<module>
<web>
<web-uri>WAR-file or
root directory of a non-archived Web application
</web-uri>
<context-root>
name by which you want to access the Web application
</context-root>
</web>
</module>

 

---

Add Supporting Web Applications

Each WebLogic Portal uses supporting Web applications to manage the deployment and administration of application and business data. This section includes the following subsections:

• Adding DataSync

• Adding the WebLogic Portal Administration Tools and ToolSupport

• Adding Support for the E-Business Control Center

Adding DataSync

The DataSync Web application makes data that the E-Business Control Center creates available to one or more enterprise applications. For more information, refer to How Application Data is Organized and Distributed.

To add the DataSync Web application, do the following:

1. Copy the PORTAL_HOME/applications/wlcsApp/datasync directory and its contents to the root directory of your enterprise application. After the copy, your enterprise application contains the following directory: MyApp/datasync.

2. Look in the MyApp/datasync/WEB-INF directory and remove any directories with names that start with _tmp_war. These directories contain compiled versions of the application, which the server generated when you accessed the Web application on the reference site.

3. Modify the URI of the DataSync Web application so that its address reflects the parent enterprise application:

   1. Open MyApp/META-INF/application.xml in a text editor.

   2. Find the XML element that declares the DataSync Web application:

      <module>
      <web>
      <web-uri>datasync</web-uri>
      <context-root>wlcsAppDataSync</context-root>
      </web>
      </module>

   3. Modify the value of the <context-root> element to provide a unique value. We recommend that you encode the name of the parent enterprise application in the DataSync URI.

      For example, for the Bank enterprise application, you specify <context-root>BankAppDataSync</context-root>. Then the following URL accesses the DataSync Web application within the Bank enterprise application: http://host-name:listen-port/BankAppDataSync

      BAs use this address in the E-Business Control Center to synchronize their modifications with the BankApp application.

Adding DataSync in a Cluster

If you are assembling an enterprise application that you will use in a cluster, you must add two instances of the DataSync Web application to your enterprise application. One instance will be used by Managed Servers for configuring their own Master Data Repositories; the other instance will be used to synchronize data across the cluster.

Note: To reduce the risk associated with synchronizing application data and business policies across a live cluster, you can do the following to synchronize data:

1. Take the cluster offline.

2. Add the DataSync Web applications to your enterprise application.

3. Synchronize the data across the offline cluster.

4. Verify the synchronization.

5. Remove the DataSync Web applications for security purposes.

6. Place the cluster online.

To add two instances of the DataSync Web application, repeat the steps in the previous section, and provide a unique name for each DataSync Web application. For example, use the following names for the DataSync Web applications that you deploy in an enterprise application named Bank:

• BankAppDataConfig for the instance that the Managed Servers use to configure their Master Data Repositories.

• BankAppDataSync for the instance that synchronizes data across the cluster. Deploy this second Data Sync Web application (the one that synchronizes data) as an exploded directory. Do not archive this Web application until you have configured Proxy Data Repositories as described in Configuring a Proxy Data Repository.

For information on configuring and deploying these applications in a cluster, refer to Deploy and Configure DataSync Web Applications for the Cluster.

Removing DataSync for Security

To prevent additions or modifications to the data that you have synchronized to your application, you can remove the DataSync Web application after you synchronize. For example:

1. You deploy your enterprise application to your production environment. The application includes the DataSync Web application.

2. You synchronize E-Business Control Center data with the application in your production environment. Note that the application must include DataSync for the synchronization process to succeed.

3. To prevent developers from deploying data to the production environment, you remove the DataSync Web application. If you want to archive your enterprise application, you can do so now.

4. If you want to add or modify data in the application, for example, if you want to modify a discount, you must redeploy the DataSync Web application as described in the previous section. If you archived the enterprise application, you must expand it before you redeploy the DataSync Web application.

For information about undeploying the DataSync Web application in a cluster, refer to Preventing Synchronization by Undeploying DataSync Web Applications.

Adding the WebLogic Portal Administration Tools and ToolSupport

Each enterprise application that you deploy must include the WebLogic Portal Administration Tools Web application, which maintains data in the RDBMS repository. For example, you use it to do the following:

• Create and maintain user and group profiles

• Add or remove users from the database security realm

• Maintain catalog items and categories

• Review and manage your customers' payment and order histories

In addition to the WebLogic Portal Administration Tools, you must also add the ToolSupport Web application.

To add the Web applications, do the following:

1. Copy the PORTAL_HOME/applications/portal/tools directory and its contents to the root directory of your enterprise application. After the copy, your enterprise application contains the following directory: MyApp/tools.

2. Copy the PORTAL_HOME/applications/portal/toolSupport directory and its contents to the root directory of your enterprise application.

3. Look in the MyApp/tools/WEB-INF directory and remove any directories with names that start with _tmp_war. These directories contain compiled versions of the applications, which the server generated when you accessed the Web applications on the reference site.

4. Look in the MyApp/toolsupport/WEB-INF directory and remove any directories with names that start with _tmp_war.

5. If you deploy multiple enterprise applications onto the same server instance, you must modify the URI of the WebLogic Portal Administration Tools Web application so that each one uses a unique address.

   To modify the URI, do the following

   1. Open MyApp/META-INF/application.xml in a text editor.

   2. Find the XML element that declares the WebLogic Portal Administration Tools Web application:

      <module>
      <web>
      <web-uri>tools</web-uri>
      <context-root>tools</context-root>
      </web>
      </module>

6. Modify the value of the <context-root> element. We recommend that you encode the name of the parent enterprise application in the WebLogic Portal Administration Tools Web application.

   For example, for the Bank enterprise application, you specify <context-root>tools_BankApp</context-root>. Then you use the following URL to access the Administration Tools Web application within the Bank enterprise application: http://host-name:listen-port/tools_BankApp

7. In MyApp/META-INF/application.xml, add the following elements to declare toolSupport:

   <module>
   <web>
   <web-uri>toolSupport</web-uri>
   <context-root>wlcsAppTool</context-root>
   </web>
   </module>

Adding Support for the E-Business Control Center

You can use the E-Business Control Center to browse some types of data that has been deployed to an application. To support this feature, you must deploy a set of helper Web applications:

1. Copy the WAR from the location described in Table 5-1 to the root directory of your enterprise application.

2. Open yourApp/META-INF/application.xml and use the following element syntax to declare the Web application:
   <module>
   <web>
   <web-uri>
   WAR-file
   </web-uri>
   <context-root>ContextRoot</context-root>
   </web>
   </module>

Table 5-1 specifies the WAR-file and for each Web application.

For example, the following elements declare the catalogws-webservice.war:

<module>
<web>
<web-uri>catalogws-webservice.war</web-uri>
<context-root>wlcsAppCatalogTool</context-root>
</web>
</module>

Table 5-1 Web Applications That Support the E-Business Control Center

Add This Web Application...	By Copying It From...
propertysetws-webservice.war Enables the E-Business Control Center to retrieve property sets from the application. If you deploy this Web application, you must also deploy propertysetws.jar as described in JARs for Personalization Services.	PORTAL_HOME/lib/p13n/ /web/propertysetws-webservice.war
campaignws-webservice.war Enables the E-Business Control Center to populate ad query and email picklists. If you deploy this Web application, you must also deploy campaignws.jar as described in JARs for Campaign Services.	PORTAL_HOME/lib/campaign/ web/campaignws-webservice.war
catalogws-webservice.war Enables the E-Business Control Center browsing the Product Catalog. If you deploy this Web application, you must also deploy catalogws.jar as described in JARs for Commerce Services.	PORTAL_HOME/lib/commerce/ web/catalogws-webservice.war

 

---

Add JAR Files

The following sections describe the JARs that WebLogic Portal provides to support your Web application:

• JARs for Personalization Services

• JARs for Campaign Services

• JARs for Commerce Services

• JARs for Campaign and Commerce Interaction

• JARs for Portal Services

Determine which of these JARs you need based on the product you use. Then copy them to the root directory of your enterprise application.

If you created EJBs to extend functionality, copy the JAR that contains them to the root directory of your enterprise application as well.

JARs for Personalization Services

If you use personalization services, do the following:

1. Copy PORTAL_HOME/lib/p13n/ejb/p13n_util.jar to the root directory of your enterprise application. This JAR provides miscellaneous utilities for personalization services that you must make available to your application.

2. For each of the JARs that you want to use from Table 5-2, do the following:

   1. Copy the JAR from PORTAL_HOME/lib/p13n/ejb to the root directory of your enterprise application.

   2. Open yourApp/META-INF/application.xml and use the following element syntax to declare the EJBs that are in the JAR:
      <module>
      <ejb>jar-name</ejb>
      </module>

   3. Open yourApp/yourWebApp/WEB-INF/web.xml and use the following element syntax to specify the EJB interfaces that servlets and JSP tags need to access directly:
      <ejb-ref>
      <ejb-ref-name>ejb/ServiceName</ejb-ref-name>
      <ejb-ref-type>Session</ejb-ref-type>
      <home>home-interface</home>
      <remote>remote-interface</remote>
      </ejb-ref>
      Table 5-2 indicates ServiceName, home-interface, and remote-interface for each EJB.

   4. Open yourApp/yourWebApp/WEB-INF/weblogic.xml and use the following element syntax to specify the EJB JNDI names that servlets and JSP tags need to access directly:
      <ejb-reference-description>
      <ejb-ref-name>ejb/ServiceName</ejb-ref-name>
      <jndi-name>${APPNAME}.BEA_personalization.ServiceName
      </jndi-name>
      </ejb-reference-description>

      Table 5-2 indicates ServiceName for each EJB.

      Table 5-2 Personalization JARs with EJBs That Must Declare References for Web Applications

      JAR	Service Name	Interfaces
      document.jar Supports document management services (searching, retrieval, and schemas).	DocumentManager	Home: com.bea.p13n.content.document. DocumentManagerHome Remote: com.bea.p13n.content.document. DocumentManager
      	ContentManager	Home: com.bea.p13n.content. ContentManagerHome Remote: com.bea.p13n.content. ContentManager
      ejbadvisor.jar Supports Personalization Advisor and advislet framework.	EjbAdvisor	Home: com.bea.p13n.advisor.EjbAdvisorHome Remote: com.bea.p13n.advisor.EjbAdvisor
      events.jar Supports the Events and Behavior Tracking service.	EventService	Home: com.bea.p13n.events. EventServiceHome Remote: com.bea.p13n.events.EventService
      ldapprofile.jar Provides your application access to user and group profile information that is stored in an LDAP server.	LdapPropertyManager	Home: com.bea.p13n.usermgmt.profile. ldap.LdapPropertyManagerHome Remote: com.bea.p13n.usermgmt.profile. ldap.LdapPropertyManager
      mail.jar Gives your application access to the outbound Mail Service, which uses the JavaMail API to send email to customers in batches.	MailService The sample applications do not declare this service because they do not call the Mail Service directly from any JSPs (instead, the Campaign Service calls the Mail Service). However, if you want to use the Mail Service to generate e-mail from JSPs, you must declare it in web.xml and weblogic.xml.	Home: com.bea.p13n.mail. MailServiceHome Remote: com.bea.p13n.mail.MailService
      pipeline.jar Support for the Pipeline service.	PipelineExecutor	Home: com.bea.p13n.appflow.pipeline. PipelineExecutorHome Remote: com.bea.p13n.appflow.pipeline. PipelineExecutor
      placeholder.jar The placeholder, ads, and ad bucket services.	AdBucketService	Home: com.bea.p13n.ad. AdBucketServiceHome Remote: com.bea.p13n.ad.AdBucketService
      	AdService	Home: com.bea.p13n.ad.AdServiceHome Remote: com.bea.p13n.ad.AdService
      	PlaceholderService	Home: com.bea.p13n.placeholder. PlaceholderServiceHome Remote: com.bea.p13n.placeholder. PlaceholderService
      property.jar Provides properties for com.beasys.commerce.foundation.ConfigurableEntity. The ConfigurableEntity provides the interface to an Entity that can be configured at runtime by associating properties via name-value pairs. The values are permanently associated with the entity by use of the EntityPropertyManager.	The EJBs in this JAR do not need to be declared in web.xml and weblogic.xml to support default WebLogic Portal services.
      propertysetws.jar Provides a web service that the E-Business Control Center uses to retrieve property set information from an active server.	The EJBs in this JAR do not need to be declared in web.xml and weblogic.xml to support default WebLogic Portal services.
      rules.jar Provides the Rules Manager, which is the public interface to the rules engine.	The EJBs in this JAR do not need to be declared in web.xml and weblogic.xml to support default WebLogic Portal services.
      usermgmt.jar Provides user and group management and Unified User Profile (UUP) services.	The EJBs in this JAR do not need to be declared in web.xml and weblogic.xml to support default WebLogic Portal services.

JARs for Campaign Services

If you use campaign services, do the following:

1. Copy the following files from PORTAL_HOME/lib/campaign/ejb to the root directory of your enterprise application:

   • campaignws.jar. This JAR supports a web service that the E-Business Control Center uses to populate ad query and email picklists.p13n_util.jar. This JAR provides miscellaneous utilities for personalization services that you must make available to your application.

   • campaign.jar. This JAR includes EJBs that provide campaign and scenario services and repositories.

2. Open yourApp/META-INF/application.xml and add the following elements to declare the campaign EJBs:
   <module>
   <ejb>campaignws.jar</ejb>
   </module>
   <module>
   <ejb>campaign.jar</ejb>
   </module>

JARs for Commerce Services

If you use commerce services, do the following:

1. Copy the following file from PORTAL_HOME/lib/commerce/ejb to the root directory of your enterprise application:

   commerce_util.jar. This JAR provides miscellaneous utilities for commerce services.

2. For each of the JARs that you want to use from Table 5-3, do the following:

   1. Copy the JAR from PORTAL_HOME/lib/commerce/ejb to the root directory of your enterprise application.

   2. Open yourApp/META-INF/application.xml and use the following element syntax to declare the EJBs that are in the JAR:
      <module>
      <ejb>jar-name</ejb>
      </module>

      Table 5-3 Commerce JARs with EJBs

      JAR	Description
      catalogws.jar	Provides a web service that the E-Business Control Center uses to browsing the product catalog. This JAR includes EJBs that provide campaign and scenario services and repositories.
      customer.jar	Supports com.beasys.commerce.ebusiness.customer.Customer entity. Customer stores the information required to do business with a customer. It inherits most attributes from the Person object and adds the ability to authenticate and to bill for product via a credit card.
      ebusiness.jar	Supports commerce services, including product catalog, order, tax calculation, shipping, payment, and supporting EJB Pipeline components.

JARs for Campaign and Commerce Interaction

If you use campaigns and commerce services together, copy PORTAL_HOME/lib/commerce_campaign_bridge/ejb/ commerce_campaign_bridge_util.jar
to the root directory of your enterprise application.

This JAR provides the campaign service with access to discounts and the shopping cart.

JARs for Portal Services

If you use portal services, do the following:

1. Copy the following files from PORTAL_HOME/lib/portal/ejb to the root directory of your enterprise application:

   • portal_util.jar. This JAR provides miscellaneous utilities for portal services.

   • portal.jar. This JAR includes EJBs that provide portal services.

2. Open yourApp/META-INF/application.xml and add the following element to declare the campaign EJBs:
   <module>
   <ejb>portal.jar</ejb>
   </module>

 

---

Create an EAR File (Optional)

In a production environment, we recommend that you archive your enterprise application into an Enterprise Archive (EAR) file and deploy the EAR file.

Before you create an EAR file, do the following:

• Undeploy the DataSync Web applications if you want to prevent additions or modifications to the data that you have synchronized to your application. For more information, refer to Preventing Synchronization by Undeploying DataSync Web Applications.

• Archive all constituent Web applications as WAR files.

Use the Java jar command to archive your enterprise application. For more information, open a command shell and enter the jar command with no arguments. With this syntax, the JDK displays help for the command.

 

---

Deploy the Application

Use the WebLogic Server Administration Console to complete the following deployment tasks:

• Deploy an Application in the Exploded Directory Format

• Deploy an Application in the EAR File Format

• Deploy Multiple Instances of an Application

Installing an application via the WebLogic Server Administration Console also creates entries for that application in the domain's configuration file (/config/domain_name/config.xml). The domain's Administration Server also generates JMX Management Beans (MBeans) that enable configuration and monitoring of the application and application components.

Deploy an Application in the Exploded Directory Format

In a development environment, we recommend that you deploy your enterprise application and Web application in the exploded directory format. To do so, complete these steps:

1. Copy your application onto the computer that hosts the application server.

2. Launch the WebLogic Server Administration Console for the server.

3. In the left pane, open the Deployments folder.

4. Right click the Applications folder and click Configure a New Application. (See Figure 5-3.)

   Figure 5-3 Configure a New Application

   
    
    

5. On the Configure a New Application page, do the following:

   1. In the Name box, enter the name of the application. WebLogic Server uses this name only within the WebLogic Server Administration Console. The name does not affect the URIs of resources within the enterprise application.

   2. In the Path box, enter the relative path of the application's root directory.

   3. Select the Deploy check box.

   4. Click Create.

6. In the left pane, open the Servers folder and click the server on which you want to deploy the application.

7. On the Server Page, click the Deployments tab. Then click the Web Applications subtab.

8. On the Web Applications subtab, move the Web applications that are in your enterprise application from the Available to the Selected list. Then click Apply.

9. Click the EJB subtab. Move EJBs from the Available to the Selected list. For information on which EJBs to move, refer to Add JAR Files. Then click Apply.

10. Click the Startup/Shutdown subtab. Move any classes from the Available to the Selected list. Then click Apply.

Deploy an Application in the EAR File Format

To facilitate management of your resources in a production environment, we recommend that you deploy your enterprise application as an enterprise application archive (EAR). You cannot add or modify JSPs that are within an archived application. You can, however, use the E-Business Control Center to synchronize application data, use the WebLogic Portal Administration Tools to modify business data, and use the WebLogic Server Administration Console to modify MBean configurations for archived applications.

To archive and deploy an enterprise application, complete the following steps:

1. For each Web application that is in your enterprise application, you must do the following:

   1. Compress the Web application into a Web application Archive (WAR). Use the Java jar command to create a WAR file. Make sure that WAR file does not include the name of the Web application's root directory. For example, the pathname for the Web application's deployment descriptor must be WEB-INF/web.xml as opposed to MyWebApp/WEB-INF/web.xml

   2. In the deployment descriptor for the enterprise application (META-INF/application.xml), change the value of the <web-uri> element to refer to a WAR file. For example, you use the following element to declare an exploded Web application: <web-uri>MyWebApp</web-uri>. When you archive the Web application, you change the value of the element as follows: <web-uri>MyWebApp.war</web-uri>

   3. Remove the exploded Web applications from the enterprise application. After you archive them, you do not need to include the exploded directories in the enterprise application.

      For troubleshooting purposes, after your archive your Web applications, you can deploy your enterprise application as an exploded directory that contains only JAR and WAR files. If you can access your WAR files, then you can move on to the following step.

2. To archive your enterprise application, use the Java jar command to create an EAR file. Make sure that EAR file does not include the name of the application's root directory. For example, the pathname for the application's deployment descriptor must be META-INF/application.xml as opposed to MyApp/META-INF/application.xml

3. Copy your application onto the computer that hosts the application server.

4. Launch the WebLogic Server Administration Console for the server.

5. In the left pane, open the Deployments folder.

6. Right click the Applications folder and click Configure a New Application.

7. On the Configure a New Application page, do the following:

   1. In the Name box, enter the name of the application. WebLogic Server uses this name only within the WebLogic Server Administration Console. The name does not affect the URIs of resources within the enterprise application.

   2. In the Path box, enter the pathname of the EAR file.

   3. Select the Deploy check box.

   4. Click Create.

8. In the left pane, open the Servers folder and click the server on which you want to deploy the application.

9. On the Server Page, click the Deployments tab. Then click the Web Applications subtab.

10. On the Web Applications subtab, move the Web applications that are in your enterprise application from the Available to the Selected list. Then click Apply.

11. Click the EJB subtab. Move EJBs from the Available to the Selected list. For information on which EJBs to move, refer to Add JAR Files. Then click Apply.

12. Click the Startup/Shutdown subtab. Move classes from the Available to the Selected list. Then click Apply.

Deploy Multiple Instances of an Application

In a development environment, we recommend that you deploy one instance of your enterprise application for each installation of the E-Business Control Center. Providing multiple application instances prevents Business Engineers who are using the E-Business Control Center from overwriting each other's work.

To deploy multiple copies of an application on a single server, do the following:

1. Copy the enterprise application. You place the copy in a different directory or in the same directory as the original but under a different name. If it is archived in an EAR file, expand the archive into an exploded directory.

2. In a text editor, open the META-INF/application.xml file.

3. In application.xml, provide a unique context root for each Web application by doing the following:

   1. Find the <web> subelement that declares the Web application. For example, the following set of elements declare the dataSync Web application:

      <module>
      <web>
      <web-uri>datasync</web-uri>
      <context-root>datasync</context-root>
      </web>
      </module>

   2. Change the value for the <context-root> element. For example, <context-root>patDataSync</context-root>.

   3. Save application.xml.

4. Deploy the enterprise application as described in Deploy the Application.

5. To access Web applications within the enterprise application, use the value of the <context-root> that you specified in step 3. For example, to access a DataSync Web that you deployed with a context root of datasync-pat, enter the following URL: http://hostname:listen-port/patDataSync

Note: The WebLogic Server Administration Console lists each instance of the Web applications and EJBs with the same name. The server successfully deploys the modules under different JNDI names. If you want to determine the enterprise application within which a particular module resides, click the module in the left pane of the WebLogic Server Administration Console. The right pane displays the pathname to the module.

 

---

Configure the JDBC Helper Service

The JDBC Helper Service is the only means for services to explicitly establish a database connection. The JDBC Helper Service enables services to explicitly establish a database connection and to coordinate the processing of CLOB data. To configure the JDBC Helper service for a Cloudscape RDBMS, do the following:

1. Start the WebLogic Server Administration Console for your domain.

2. In the left pane of the WebLogic Server Administration Console, click Deployments -> Applications -> yourApplication -> Service Configuration -> JDBC Helper Service.

3. In the right pane, on the Configuration tab, enter the following values:

   In this box...	Enter this value...
   Maximum Number of Retries	The maximum number of times the service attempts to connect to the database. A value of -1 instructs the service to retry an unlimited number of times.
   Maximum Wait Time	The number of milliseconds to wait for a database connection. When the time limit expires, the service attempts another connection, up to the maximum number of retries. A value of -1 instructs the service to wait infinitely.
   Delegate Class Name	Leave empty

4. Click Apply.

Note: For information on configuring a JDBC Helper Service for other database types, refer to Part II, Deploying Your Business Data. For Sybase, DB2, and SQL Server 7, the details for setting the JDBC Helper Service are documented in step 2.4 of the section "Update Settings for the JDBC Helper Service" in the <PORTAL_HOME>/db/readme.html file. No Delegate Class Name is required for Cloudscape databases.