Portal Content Management

A key component of any portal is its content. WebLogic Portal provides content by using a Content Manager. A Content Manager provides content and document management capabilities for use in personalization services to target users with dynamic web content. It works with files or with content managed by third-party vendor tools. While developing portal resources, you will have to configure the Content Manager and use various content-related tags so that the user has access to the most relevant content available.

This section includes information on the following subjects:

• Adding Content by Using the Bulk Loader

• Using Content-Selector Tags and Associated JSP Tags

• Integrating External Content Management Systems

• Constructing Content Queries

 

---

Adding Content by Using the Bulk Loader

The easiest way to add content to a portal is to use the bulk loader scripts provided by BEA. To implement this strategy, use this procedure:

1. Publish files to a directory on the file system at a specified interval. Ideally, you should publish content to subdirectories under \dmsBase directory in the appropriate domain folder. For example, place ads in:

   <BEA_HOME>\weblogic700\samples\portal\<DOMAIN_NAME>\dmsBase\ads

2. When you are done publishing the content to the file on your directory system, run the BulkLoader by running one of the following scripts:

   • If you are loading text or image files, run loaddocs.bat (loaddocs.sh for UNIX users).

   • If you are loading ads for placeholders or campaigns, run loadads.bat (loadads.sh for UNIX users).

   The load scripts can be found at this location:

   <BEA_HOME>\weblogic700\samples\portal\<DOMAIN_NAME>\

   You can run these scripts either by typing them at the command line (or Start | Run in Windows NT or 2000) or by going to the Windows Explorer, locating the script you want to run, and double-clicking it in the file list. If you run the BulkLoader from a command line, you can also use any of the switches listed in Table  8-1.

   Table 8-1 Bulk Loader Switch Settings

   Switch Setting	Description
   -verbose	Emits verbose messages.
   +verbose	Runs quietly [default].
   -recurse	Recurses into directories [default].
   +recurse	Does not recurse into directories.
   -delete	Removes document from database.
   +delete	Inserts documents into database [default].
   -metaparse	Parses HTML files for <meta> tags [default].
   +metaparse	Does not parse HTML files for <meta> tags.
   -cleanup	If specified, this only performs a table cleanup using the -d argument as the document base. (All files will need to be under that directory.)
   +cleanup	Turns off table cleanup (do a document load) [default].
   -hidden	Specifies to ignore hidden files and directories [default].
   +hidden	Specifies to include hidden files and directories.
   -inheritProps	Specifies to have metadata properties be inherited when recursing [default].
   +inheritProps	Specifies to have metadata properties not be inherited when recursing.
   -truncate	Attempts to truncate data values if they are too large for the database (controlled via loader.properties).
   +truncate	Does not attempt to truncate data values [default].
   -ignoreErrors	Ignores any errors while loading a document (errors will still be reported).
   +ignoreErrors	Stops processing on any error [default].
   -htmlPat <pattern>	Specifies a pattern for determining which files are HTML files when determining whether to do the <meta> tag parse. This can be specified multiple times. If none are specified, *.htm and *.html are used.
   -properties <name>	Specifies the location of the loaddocs.properties file that should contain the connectionPool definition. This file may contain jdbc.column.<columnName>=<propname> entries similar to the -columnMap argument.
   -conPool <name>	Specifies the connectionPool name from the properties file from which the BulkLoader should get the connection information.
   -schema <name>	Specifies the path to the schema file the BulkLoader will generate (defaults to document-schema.xml).
   +schema	If specified, then no schema file will be created.
   -schemaName <name>	Specifies the name of the schema generated by the BulkLoader. Defaults to "LoadedData".
   -encoding <name>	Specifies the file encoding to use. Defaults to your system's default encoding. (See your JDK documentation for the valid encoding names.)
   -commitAfter <num>	Commits the JDBC transaction after this many documents are loaded. Defaults to: only at the end of the full load.
   -match <pattern>	Specifies a file pattern the BulkLoader should include. This can be specified multiple times. If none are specified, all files and directories are included.
   -ignore <pattern>	Specifies a file pattern the BulkLoader should not include. This can be specified multiple times.
   -d <dir>	Specifies the docBase that non-absolute paths will be relative to. If not specified, "." (current directory) is used.
   -mdext <ext>	Specifies the filename extension for metadata property files. The value should starts with a "." (defaults to .md.properties).
   -filter <filter class>	Specifies the class name of a LoaderFilter to run files through. This can be specified multiple times to add to the list of Loader Filters.
   +filters	Clears the current list of Loader Filters. (This will clear the default filters as well.)
   --	Everything after this is considered a file or directory.
   -columnMap <file.properties>	Specifies a properties file containing the jdbc.column.<columnName>=<propname,...> list of additional columns to the DOCUMENT table (see -column). This cannot be used to override behavior for standard columns.
   -column <columnName>=<propName,...>	Specifies an additional column to the DOCUMENT table and the property names that map onto the column. This cannot be used to override behavior for standard columns.
   +columns	Clears any configured additional columns.

   
    

3. Make the sure that the DocumentConnectionPool in the application's META-INF/application-config.xml or through the WebLogic Server console is configured to point to the correct directory.

4. In order for the docPool to reload the XML schema files, it must be restarted.

For this strategy to succeed, the CMS must be able to publish document metadata in one of the three ways the BulkLoader supports:

• In a corresponding md.properties file; this file should be a standard Java-style properties file containing the user-defined metadata for the document. For example, for image.gif the file would be image.gif.md.properties.

• In the document file; for HTML files, the metadata can be placed in standard <META name="" content=""> tags in the document file itself.

• In some other form for which a LoaderFilter can be written to gather the metadata.

BulkLoader Performance Tips

The following suggestions will improve BulkLoader performance.

Clean Up the Cache

If you've made a lot of small updates to a page, before running the BulkLoader, you should clean up the cache. On the Cache Manager Administration tab on the Administration Console, select Flush Entire Cache and click Flush, as shown in Figure  8-1.

Figure 8-1 Flushing the Cache

 

Flushing is particularly helpful for these caches:

• DocumentMetaDataCache

• AdBucketServicesCache

• DocumentContentCache

• AdServicesCache

Restarting the ConnectionPool

If you used the E-Business Control Center to add new metadata properties, you need to restart the connectionPool. To do so:

1. From left pane of the Administration Console, open the following node:

   <yourDomain> —> Deployments —> Applications —> <yourPortal> —> Service Configurations —> Documents —> DocumentConnectionPool Services —> Default

   The Document Connection Pool Services Default tab appears in the right pane of the Console, as shown in Figure  8-2.

   Figure 8-2 Restarting the ConnectionPool

   
    

2. Click Apply and Restart.

 

---

Configuring the Content Manager

If you are using a third-party Content Management System to populate a portal, you will need to configure it to work with WebLogic Portal. This section explains the configuration procedures you will need to perform.

The Content Manager is a run-time subsystem that provides access to content through tags and EJBs. When developing JSPs, the Content Management tags allow you to receive an enumeration of content objects by querying the content database directly by using a search expression syntax. The Content Manager component works alongside the other components to deliver personalized content, but does not have a GUI-based tool for edit-time customization.

The following section describes the tasks required to configure a Content Manager. It includes information on the following subjects:

• Configuring the DocumentManager EJB Deployment Descriptor

• Configuring the PropertySetManager EJB Deployment Descriptor for Content Management

• Configuring DocumentManager MBeans

• Setting Up Document Connection Pools

• Editing a DocumentConnectionPool MBean in the WebLogic Console

• Configuring the Web Application

Configuring the DocumentManager EJB Deployment Descriptor

The DocumentManager EJB deployment descriptor handles the EJB portion of the Content Management component configuration and must be configured to recognize the correct environmental settings. To configure the DocumentManager EJB, ensure that the following environment settings are in its deployment descriptor:

• DocumentManagerMBeanName—specifies the name of the DocumentManager MBean to use to configure this DocumentManager.

  • In the enterprise application's application-config.xml file, a <DocumentManager> entry must exist with a Name attribute equal to the value specified in the deployment descriptor. If this is not specified in the deployment descriptor, it defaults to "default".

• DocumentConnectionPoolName—specifies the name of the DocumentConnectionPool MBean that this DocumentManager should use.

  • In the application's application-config.xml file, a <DocumentConnectionPool> entry must exist with a Name attribute equal to the value specified in the deployment descriptor.

  • If the DocumentManager's DocumentConnectionPoolName attribute is configured to use MBeans, then the value in the deployment descriptor is ignored.

• jdbc/docPool—specifies the J2EE resource reference to the javax.sql.DataSource that this DocumentManager should use to access a document connection pool.

  If jdbc/docPool is specified in the deployment descriptor, then:

  • DocumentConnectionPoolName is ignored, and

  • Any DocumentConnectionPool MBeans in the application's application-config.xml file are also ignored.

• PropertyCase—specifies how the DocumentManager modifies the incoming property name.

  • If the PropertyCase attribute of the DocumentManager MBean being used is set, the value in the deployment descriptor is ignored.

  • If this is lower, all property names are converted to lowercase.

  • If this is upper, all property names are converted to uppercase.

  • If this is anything else or not specified, property names are not modified.

  Note: Use lower or upper depending upon the document connection pool implementation being used. For the document reference implementation, do not specify the PropertyCase.

Configuring the PropertySetManager EJB Deployment Descriptor for Content Management

The DocumentManager needs to be integrated into the PropertySetManager EJB deployment descriptor so that content property sets are exposed to the system. To configure the PropertySetManager EJB Deployment Descriptor for content management, add the following environment settings:

• repository/CONTENT—specifies the fully qualified class name of com.bea.p13n.property.PropertySetRepository implementation. Use com.bea.p13n.content.PropertySetRepositoryImpl to integrate with the Content Management component.

• ejb/ContentManagers/[type]— the com.bea.p13n.content.PropertySetRepositoryImpl looks for all environment entries starting with ejb/ContentManagers. It expects these to be J2EE EJB references to ContentManagers (or subclasses).

  To integrate a ContentManager or DocumentManager with the PropertySetManager, add an EJB reference here. For example, ejb/ContentManagers/Document is mapped to the standard DocumentManager.

Alternately, you can set the JNDIName attribute of the DocumentManager MBean to the JNDI Home name of the DocumentManager. The ${APPNAME} construct can be used in the value; it will be replaced by the current J2EE application name. The com.bea.p13n.content.PropertySetRepositoryImpl will automatically pick up those DocumentManagers and the J2EE EJB reference is not required.

Configuring DocumentManager MBeans

The DocumentManager implementation uses DocumentManager MBeans to maintain its configuration. A deployed DocumentManager finds which DocumentManager MBean to use from the DocumentManagerMBeanName EJB deployment descriptor setting. You will need to configure the DocumentManager MBeans in the application so that their values correspond to the Name attributes in the DocumentManagerMBeanName EJB deployment descriptor.

To configure a DocumentManager MBean, you can modify the application's META-INF/application-config.xml file to add or change the following XML, as shown in Listing  8-1.

Listing 8-1 Modifying the <DocumentManager> Element in an Application's META-INF/application-config.xml File

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

Do not try to change these attributes from within the application-config.xml file. Instead, use the WebLogic Server Administration Console, as described in Using the WebLogic Server Administration Console to Modify DocumentManager MBeans.

Using the WebLogic Server Administration Console to Modify DocumentManager MBeans

To modify DocumentManager MBeans by using the WebLogic Server Administration Console, use this procedure.

1. Start WebLogic Server and open a Web browser.

2. Open the WebLogic Server Administration Console by typing the following URL in the Address field:

   http://<hostname>:<port>/console

   For example, if you are launching the console on the server itself, the default URL is:

   http://localhost:7501/console

3. Press Enter.

   The WebLogic Server sign-in screen appears.

4. Sign in by entering your username and password and clicking Sign in. The default username/password pair is system/weblogic.

5. The WebLogic Server Administration Console appears, as show in Figure  8-3.

   Figure 8-3 WebLogic Server Administration Console

   
    

6. In the left pane, drill down to the DocumentManager MBean for your applicaion. Select these nodes:

   MyDomain —> Deployments —> Applications —> MyApplication —> Service Configuration —> Document Manager —> MyMBean

   Where:

   • MyDomain is the domain inwhich the application resides.

   • MyApplication is the Web application that uses the MBean.

   • MyMBean is the actual MBean you want to configure.

   Figure  8-4 shows an example of the nodes you would select to drill down to the Default MBean for the DocumentManager for an application called portalApp.

   Figure 8-4 Drilling Down to an MBean

   
    

   When you select the MBean node, the DocumentManager Services screen for that MBean appears in the right pane, as shown in Figure  8-5. Note the MBean name on the tab.

   Figure 8-5 DocumentManager Service Screen

   
    

7. Change the attributes as necessary and click Apply. These attributes are listed in Table  8-2.

   Table 8-2 DocumentManager MBean Attributes

   Attribute	Screen Label/Control Type	Description
   DocumentConnectionPoolName	Document Connection Pool Name Text Box	Specifies the name of the DocumentConnectionPool MBean the DocumentManager should use.
   PropertyCase	Property Case Drop-down List	Specifies how the DocumentManager modifies the incoming property name. If this is lower, all property names are converted to lowercase. If this is upper, all property names are converted to uppercase. If this is anything else or not specified, property names are not modified. Use lower or upper depending upon the document connection pool implementation being used. For the document reference implementation, do not specify the PropertyCase.
   MetadataCaching	Metadata Caching Enabled? Checkbox	Specifies whether the DocumentManager should cache Document metadata from searches. Use true to have the DocumentManager cache search results in the com.bea.p13n.cache.Cache specified by MetadataCacheName; otherwise, use false. This defaults to true.
   MetadataCacheName	MetaData Cache Name Text Box	Specifies the name of the com.bea.p13n.cache.Cache to use if MetadataCaching is set to true. This defaults to documentMetadataCache.
   UserIdInCacheKey	Is Userid in the Cache Key? Checkbox	Specifies whether the user's identifier should be used as part of the key when caching document metadata or content. This defaults to true. If using WebLogic Portal reference implementation document management system, set this to false.
   ContentCaching	Content Caching Enabled? Checkbox	Specifies whether the DocumentManager should cache document content (that is, the bytes of the document). Use true to have the DocumentManager cache document content bytes; otherwise use false. This value defaults to true.
   ContentCacheName	Content Cache Name Text Box	Specifies the name of the com.bea.p13n.cache.Cache to use if ContentCaching is set to true. This defaults to documentContentCache.
   MaxCachedContent Size	Maximum Size of Cached Content Text Box	Specifies the maximum size of a document's content bytes that the DocumentManager will cache, if ContentCaching is true. This defaults to 32768 (32K) bytes.
   JNDIName	n/a	Specifies the JNDI home name of the DocumentManager EJB that is connected to this MBean. The ${APPNAME} construct can be used in the value; it will be replaced by the current J2EE application name. This is used by the com.bea.p13n.content.PropertySet RepositoryImpl to tie document property set information into the PropertySetManager.

   
    

Disabling an MBean

You can enable or disable an MBean from the WebLogic Server Administration Console. To do so, use this procedure.

Note: This procedure assumes that you are connected to WebLogic Server and have the Administartion console open, as you did in Using the WebLogic Server Administration Console to Modify DocumentManager MBeans.

1. In the left pane, drill down to the Add or remove service configurations node, which is under the Service Configurations node, as shown in Figure  8-6.

   Figure 8-6 Selecting the Add or remove service configurations Node

   
    

   The Service Configuration screen appears in the right pane, as shown in Figure  8-7.

   Figure 8-7 Service Configuration Screen

   
    

2. Locate the MBean you want to remove from the list and click the associated checkbox to deselect it, as shown in Figure  8-8.

   Figure 8-8 Service Configuration Screen with MBean Deselected

   
    

3. Deselect each MBean you want to disable. When you are done, click Submit.

   You receive the message "You must redeploy your application [APP_NAME] for these changes to take place."

4. Redeploy the application or restart the server.

Restoring a Disabled MBean

To restore the MBean disabled in the preceding procedure, click its acssociated checkbox to select it. Again, once you've restored all necessary MBeans, click Submit.

Setting Up Document Connection Pools

The DocumentManager implementation uses connection pools to a specialized JDBC driver to handle searches on content. A deployed DocumentManager finds the document connection pool to use via either the DocumentConnectionPoolName attribute of its DocumentManager MBean or the DocumentConnectionPoolName EJB deployment descriptor setting. That value must correspond to a DocumentConnectionPool MBean.

To configure a DocumentConnectionPool MBean, modify the application's META-INF/application-config.xml file by adding or changing the XML shown in Listing  8-2:

Listing 8-2 Modifying an Application's META-INF/application-config.xml File to Configure a DocumentConnectionPool MBean

<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=D:/bea/user_projects/myNEWdomain/dmsBase/
   doc-schemas;docBase=D:/bea/user_projects/myNEWdomain/dmsBase"
InitialCapacity="20"
MaxCapacity="20"
CapacityIncrement="0"

/>

Editing a DocumentConnectionPool MBean in the WebLogic Console

As with the DocumentManager MBeans, you must modify the DocumentConnectionPool MBean by using the WebLogic Server Administration Console. See the procedure in Using the WebLogic Server Administration Console to Modify DocumentManager MBeans for instructions. Note that, for the DocumentConnectionPool MBeans, you need to select the Document Connection Pool Service node and make the changes on the Document Connection Pool Service screen, shown in Figure  8-9.

Figure 8-9 Document Connection Service Pool Screen

 

The attributes of the DocumentConnectionPool MBean that you can change are listed in Table  8-3.

Table 8-3 DocumentConnectionPool MBean Attributes

Attribute	Screen Label/ Control Type	Description
DriverName	Driver Name Text Box	Specifies the JDBC driver class name to use. This should be set to com.bea.p13n.content.document.jdbc.Driver
URL	JDBC URL Text Box	Specifies the JDBC URL to use. For WebLogic Portal's reference implementation document management system, this should be set to: jdbc:beasys:docmgmt:com.b ea.p13n.content.document. ref.RefDocumentProvider. For a different Document Provider, use: jdbc:beasys:docmgmt:<clas sname> where <classname> is the fully qualified class name of the implementation of com.bea.p13n.content. document.spi.DocumentProv ider.
Properties	JDBC Properties Text Box	The semi-colon separated list of name=value pairs which will be passed to the DocumentProvider specified in the URL. Table  8-4 lists the properties that the reference implementation understands.
InitialCapacity	Initial Capacity of Pool Text Box	Specifies the initial number of connections to create when the document connection pool is started.
MaxCapcity	Maximum Capacity of Pool Text Box	Specifies the maximum number of connections this pool will ever create and maintain.
CapacityIncrement	Capacity Increment Text Box	Specifies the number of connections the pool will create whenever it needs to create an available connection.
LoginTimeout	n/a	Specifies the amount of time to wait for a connection: after this time expires, an exception is thrown. Use 0 or less to have the pool not timeout, which is the default.
ClassPath	n/a	Specifies the semicolon -separated list of additional directories and JARs the connection pool should use when attempting to load the Driver and the DocumentProvider classes. All paths are assumed to be relative to the application directory.

 

Table  8-4 Describes the valid reference implementation properties you can set for the DocumentConnectionPool MBean.

Table 8-4 Reference Implementation Properties

Property	Description
jdbc.dataSourceSp	Specifies the JNDI name of the javax.sql.DataSource to use to get database connections. This datasource should be connected to the database that contains the DOCUMENT and DOCUMENT_METADATA tables.
jdbc.url	Specifies the JDBC URL to connect to. If jdbc.dataSource is specified, this is ignored.
jdbc.driver	Specifies the JDBC driver class to load. If jdbc.dataSource is specified, this is ignored.
jdbc.isPooled	If true, or if jdbc.url starts with jdbc:weblogic:pool or jdbc:weblogic:jts, or if jdbc.dataSource is specified, then assumes the connection is pooled and won't cache it. If anything else, assumes the connection is not pooled and will maintain one connection.
jdbc.supportsLikeEscape Clause	Specifies whether the underlying database supports the SQL LIKE ESCAPE clause. If this is not specified, the connection will be queried.
jdbc.docBase	Specifies under which base directory the documents are stored. Assumes all paths coming from the database are relative to this directory.
jdbc.schemaXML	Specifies the path to the directory containing XML files following the doc-schemas DTD which contain the property set information. The system will recurse through the directory, loading all files ending in .xml.
jdbc.isolationLevel	Configures the transaction isolation level to set on the database connections. This can be one of the following: READ_COMMITTED READ_UNCOMMITTED SERIALIZABLE REPEATABLE_READ NONE If not specified, it defaults to SERIALIZABLE. For further details, see the Javadoc API documentation for java.sql.Connection.
jdbc.column.<colName>	Specifies an additional column to the DOCUMENT table. The value is the comma-separated list of property names that map onto that column. This can be specified multiple times. This should be used in conjunction with the -columnMap and/or -column arguments to the BulkLoader. If the same property is mapped to more than one column, the result is indeterminate.

 

You can edit a DocumentConnectionPool MBean to change attribute and property values as needed by using the WebLogic Server Administration Console, as shown in Figure  8-9.

Configuring the Web Application

You need to configure the Web application to have access to the J2EE resources (such as EJBs, servlets, and JSP tag libraries) required to access the content management services. This means you will need to configure EJB references to ejb/ContentManager and ejb/DocumentManager. Additionally, you need to have the com.bea.p13n.content.servlets.ShowDocServlet mapped into your Web Application. BEA suggests that you to map it to the /ShowDoc/* URL in your Web Application, as shown in Listing  8-3.

Listing 8-3 Mapping the ShowDocServlet

<servlet>
  <servlet-name>ShowDocServlet</servlet-name>
  <servlet-class> com.bea.p13n.content.servlets.ShowDocServlet
  </servlet-class>

  <!-- Make showdoc always use the local ejb-ref DocumentManager -->

  <init-param>
    <param-name>contentHome</param-name>
    <param-value>java:comp/env/ejb/DocumentManager</param-value>
  </init-param>

</servlet>

...

<servlet-mapping>
  <servlet-name>ShowDocServlet</servlet-name>
  <url-pattern>/ShowDoc/*</url-pattern>
</servlet-mapping>

This will allow the ShowDoc/ URI under your Web Application's context root (for example, /wlcs/ShowDoc) to be sent to the ShowDocServlet. The contentHome <init-param> will cause that ShowDocServlet to always use the ejb/DocumentManager EJB reference; you can take this out to allow ShowDocServlet to obey any contentHome request parameters.

To access the Content Management tag libraries, you will need to:

• Copy the cm_taglib.jar file in the Web Application's WEB-INF/lib directory. (It can be copied from WL_PORTAL_HOME/lib/p13n/web.)

• Make sure that cm.tld is mapped to /WEB-INF/lib/cm_taglib.jar in a <taglib> entry in your Web Application's WEB-INF/web.xml file.

 

---

Using Content-Selector Tags and Associated JSP Tags

A content selector is one of several mechanisms that WebLogic Portal provides for retrieving documents from a content management system. You can use content selector JSP tags and a set of other JSP tags to retrieve and display the content targeted by the content selector.

This section describes how to use content-selector tags and their associated JSP tags to manage content. It includes information on the following topics:

• Using the <pz:contentSelector> Tag

• Associated Tags That Support Content Selectors

• Using Content Selector Tags and Associated Tags

For information on how WebLogic Portal's content-related JSP tags map to WebLogic Portal's content management service provider interface (SPI), see the "Personalization JSP Tags" section of the JavaServer Page Guide at http://download.oracle.com/docs/cd/E13218_01/wlp/docs70/jsp/p13njsp.htm.

Using the <pz:contentSelector> Tag

The <pz:contentSelector> selector tag allows you to do the following:

• Identify the Content Selector Definition

• Identify the JNDI Home for the Content Management System

• Define the Array That Contains Query Results

• Create and Configure the Cache to Improve Performance

Identify the Content Selector Definition

The content selector definition created in the E-Business Control Center determines the conditions that activate a content selector and the query that the active content selector runs.

To refer to this definition, use the rule attribute:

<pz:contentSelector rule= { definition-name | scriptlet } >

You can use a scriptlet to determine the value of the rule attribute based on additional criteria. For example, you use a content selector in a heading JSP (heading.inc), which is included in other JSPs. You can create different content selectors for each page that includes heading.inc.

A scriptlet is used in heading.inc to provide a value based on the page that currently displays the included JSP file. Listing  8-4 shows an example.

Listing 8-4 Using a Scriptlet in heading.inc

 String banner = (String)pageContext.getAttribute("bannerPh");
   banner = (banner == null) ? "cs_top_generic" : banner;

%>

<!-- ------------------------------------------------------------- -->

<table width="100%" border="0" cellspacing="0" cellpadding="0"
   height="108">

  <tr><td rowspan="2" width="147" height="108">
  <pz:contentSelector rule="<%= banner %>" ... />

</td>

Identify the JNDI Home for the Content Management System

The content selector tag must use the contentHome attribute to specify the JNDI home of the content management system. If you use the reference content management system or a third-party integration, you can use a scriptlet to refer to the default content home. Because the scriptlet uses the ContentHelper class, you must first use the following tag to import the class into the JSP:

<%@ page import="com.bea.p13n.content.ContentHelper"%>

Then, when you use the content selector tag, specify the contentHome as described in Listing  8-5.

Listing 8-5 Specifying contentHome in a Content-Selector Tag

<pz:contentSelector
contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>"
... />

If you create your own content management system, you must specify the JNDI home for your system instead of using the ContentHelper scriptlet. In addition, if your content management system provides a JNDI home, you can specify that one instead of using the ContentHelper scriptlet.

Define the Array That Contains Query Results

You can use the attributes described in Table  8-5 to configure the array that contains the results of the content-selector query.

Table 8-5 Attributes that Define the Array that Contains Query Results

Attribute	Description
id	Specifies a name for the array. This attribute is required. For example, <pz:contentSelector id="docs" .../> places documents in an array named docs.
max	Limits the number of documents the content selector places in its array. For example, <pz:contentSelector max="10" .../> causes the content selector to stop retrieving documents when the array contains 10 documents. This attribute is optional and defaults to -1, which means no maximum.
sortBy	Uses one or more document attributes to sort the documents in the array. The syntax for sortBy follows the SQL order by clause syntax. This attribute is optional. If you do not specify this attribute, the content selector returns the query results in the order that the content management system returns them. For example, <pz:contentSelector sortBy="creationDate" .../> places the documents that were created first at the beginning of the array. The tag <pz:contentSelector sortBy="creationDate ASC, title DESC" .../> places older documents at the beginning of the array. If any documents were created on the same day, it sorts those documents counter-alphabetically by title.

 

Create and Configure the Cache to Improve Performance

To extend accessibility of retrieved content and to improve performance, you can optionally use content selector attributes to create and configure a cache that contains the array contents. Without the cache, you can access the content selector array only from the current JSP page, and only for the customer request that created it. In addition, each time a customer requests a JSP that contains the content selector tag, the content selector must run the query, potentially slowing the overall performance of WebLogic Portal.

To cache the contents of the array, use the attributes listed in Table  8-6.

Table 8-6 Attributes that Cache the Contents of an Array

Attribute	Description
useCache	Determines whether the content selector places the array in a cache. To activate the cache, set this attribute to true. For example, <pz:contentSelector cache="true" ...>. To deactivate the cache, set the attribute to false or do not include it. For example, the following statements are equivalent: <pz:contentSelector cache="false" .../> <pz:contentSelector ...>
cacheId	Assigns a name to the cache. If you do not specify this attribute, the cache uses the name of the array (which you must specify with the id attribute). If you want to access the cache from a JSP or user session other than the one that created the array, you must specify a cacheId.
cacheTimeout	Specifies the number of milliseconds that WebLogic Portal maintains the cache. The content selector does not re-run the query until the number of seconds expires. For example, you create the following tag: <pz:contentSelector cache="true" cacheTimeout="300000" .../> A customer requests the page that contains this content selector tag. The user leaves the page but, 2 minutes (120000 milliseconds) later, requests it again. The content selector evaluates its conditions, but because only 120000 milliseconds have expired since the content selector created the cache, it does not re-run the query. Instead, it displays the documents in the cache.
cacheScope	Determines from where the cache can be accessed. You can provide the following values for this attribute: application. Any JSP page in the Web application that any customer requests can access the cache. session (the default). Any JSP in the Web application that the current customer requests can access the cache. page. Only the current JSP that any customer requests can access the cache. request. Only the current user request can access the cache. If a customer re-requests the page, the content selector re-runs the query and recreates the cache.

 

Associated Tags That Support Content Selectors

The JSP tags listed in Table  8-7 support content selector functions.

Table 8-7 JSP Tags that Support Content-Selector Functions

Tag	Description
<um:getProfile>	Retrieves the profile of the customer who is currently viewing the page. A content selector uses the customer profile to evaluate any conditions that involve customer properties. For example, if you create a content selector that runs a query for all customers in the Gold Customer customer segment, the content selector must access the customer profile to determine if it matches the customer segment. Even if a content selector does not currently use the customer profile for its conditions, we recommend that you include the <um:getProfile> tag; its affect on performance is minimal and with the tag, customer-profile conditions can be added to the content selector without requiring a developer to modify JSPs. The tag must be located closer to the beginning of the JSP than the content selector tag.
<es:forEachInArray>	Iterates through the array that contains the results of a content selector query. With this tag, you can use the following to work with the documents in the array: The System.out.println method to print each item in the array. The <cm:getProperty> tag to retrieve one or more attributes of the documents in the array. You can use the attributes to construct the HTML that a browser requires to display the documents. For example, you use the <cm:getProperty> tag to determine the value of a MIME-type attribute. If the MIME-type of a document in the array is an image, you print the HTML <img> tag with the appropriate attributes. You can also use attributes of the <pz:contentSelector> tag, such as sortBy, to work with the attributes of documents in the array. The <cm:printProperty> to print one or more attributes of the documents in the array. For example, you can use this tag to print a list of document titles that the content selector retrieves.

 

Using Content Selector Tags and Associated Tags

The combination of content selector definitions, tag attributes, and associated JSP tags creates a powerful set of tools for matching documents to customers in specific contexts. The following tasks are the most common uses of content selectors and associated tags:

• Retrieving and Displaying Text-Type Documents

• Retrieving and Displaying Image-Type Documents

• Retrieving and Displaying a List of Documents

• Accessing a Content Selector Cache on a Different JSP

For information on how WebLogic Portal's content-related JSP tags map to WebLogic Portal's content management service provider interface (SPI), see the "Personalization JSP Tags" section of the JavaServer Page Guide at http://download.oracle.com/docs/cd/E13218_01/wlp/docs70/jsp/p13njsp.htm.

Retrieving and Displaying Text-Type Documents

To retrieve and display text-type documents, use this procedure:

Note: This procedure assumes that the content selector query created in the E-Business Control Center includes a filter to retrieve only text documents.

1. Open a JSP in a text editor.

2. Near the beginning of the JSP, add the lines shown in Listing  8-6 to import classes and tag libraries if they are not already in the JSP:

Listing 8-6 Code to Import Classes and Tag Libraries

<%@ page import="com.bea.p13n.content.ContentHelper"%>
<%@ taglib uri="es.tld" prefix="es" %>
<%@ taglib uri="pz.tld" prefix="pz" %>
<%@ taglib uri="um.tld" prefix="um" %>

3. Add the following tag to get the customer profile, if the tag is not already in the JSP:

   <um:getProfile>

   If the JSP already uses this tag for some other purpose, it probably includes other attributes. Make sure that the tag is closer to the beginning of the JSP than the <pz:contentSelector> tag, which you use in the next step.

4. Add the tags shown in Listing  8-7, where SpringSailing is the name of the content selector that was created in the E-Business Control Center:

Listing 8-7 Content Selector Tag Example 1

<pz:contentSelector rule="SpringSailing"
contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>"
id="textDocs"/>
<es:forEachInArray array="<%=textDocs%>" id="aTextDoc" type="com.bea.p13n.content.Content">
<p><cm:printDoc id="aTextDoc"/></p>

</es:forEachInArray>

Note: To verify the content type before you display it, you can surround the <% "<P>" + aTextDoc + "</P>" %> scriptlet with another scriptlet. Listing  8-8 shows an example:

Listing 8-8 Verifying the Content Type

<% if (aTextDoc.getMimeType().contains("text") != -1)
{
%>
<p><cm:printDoc id="aTextDoc"/></p>
<%
}
%>

5. Save the JSP. If you deploy the Web application as a WAR file, re-jar the Web application and deploy it.

   WebLogic Portal deploys the modifications. If you specified a page-check rate for your Web application, WebLogic Portal waits for the page-check interval to expire before deploying any changes.

Retrieving and Displaying Image-Type Documents

To retrieve and display image-type documents, use this procedure:

1. Open a JSP in a text editor.

2. Near the beginning of the JSP, add the lines shown in Listing  8-9 to import classes and tag libraries if they are not already in the JSP:

Listing 8-9 Code to Import Classes and Tag Libraries if They are not Already in the JSP

<%@ page import="com.bea.p13n.content.ContentHelper"%>
<%@ taglib uri="pz.tld" prefix="pz" %>
<%@ taglib uri="um.tld" prefix="um" %>
<%@ taglib uri="cm.tld" prefix="cm" %>

3. Add the following tag to get the customer profile, if the tag is not already in the JSP:

   <um:getProfile>

   If the JSP already uses this tag for some other purpose, it probably includes other attributes. Make sure that the tag is closer to the beginning of the JSP than the <pz:contentSelector> tag, which you create in the next step.

4. Add the tags shown in Listing  8-10, where SpringSailing is the name of the content selector that was created in the E-Business Control Center:

Listing 8-10 Content Selector Tag Example 2

<pz:contentSelector rule="SpringSailing"
contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>"
id="ImageDocs"/>

<es:forEachInArray array="<%=ImageDocs%>" id="anImageDoc" type="com.bea.p13n.content.Content">

<img src="ShowDoc/<cm:printProperty

id="anImageDoc" name="identifier" encode="url"/>"

</es:forEachInArray>

Note: The above tags assume that the content selector query that was created in E-Business Control Center includes a filter to retrieve only image documents. To verify the content type before you display it, you can surround the <img> tag with a scriptlet. Listing  8-11 shows an example:

Listing 8-11 Surrounding an <img> Tag with a Scriptlet

<% if (anImageDoc .getMimeType().contains("image"))
{
%>
  <img src="ShowDoc/<cm:printProperty
  id="anImageDoc" name="identifier" encode="url"/>">
} 
%>

5. Save the JSP. If you deploy the Web application as a .war file, re-jar the Web application and deploy it.

   WebLogic Portal deploys the modifications. If you specified a page-check rate for your Web application, WebLogic Portal waits for the page-check interval to expire before deploying any changes..

Retrieving and Displaying a List of Documents

To retrieve and display a list of documents, use this procedure:

1. Open a JSP in a text editor.

2. Near the beginning of the JSP, add the lines shown in Listing  8-12 to import classes and tag libraries if they are not already in the JSP:

Listing 8-12 Code to Import Classes and Tag Libraries if They are not Already in the JSP

<%@ page import="com.bea.p13n.content.ContentHelper"%> <%@ taglib uri="es.tld" prefix="es" %>
<%@ taglib uri="pz.tld" prefix="pz" %>
<%@ taglib uri="um.tld" prefix="um" %>

3. Add the following tag to get the customer profile, if the tag is not already in the JSP:

   <um:getProfile>

   If the JSP already uses this tag for some other purpose, it probably includes other attributes. Make sure that the tag is closer to the beginning of the JSP than the <pz:contentSelector> tag, which you create in the next step.

4. Add the tags shown inListing  8-13 , where SpringSailing is the name of the content selector that was created in the E-Business Control Center:

Listing 8-13 Content Selector Tags Example 3

<pz:contentSelector rule="SpringSailing"
contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>"
id="docs"/>
<ul>
<es:forEachInArray array="<%=docs%>" id="aDoc"
type="com.bea.p13n.content.Content">

<li>The document title is: <cm:printProperty id="aDoc"
name="Title" encode="html" />
</es:forEachInArray>
</ul>

5. Save the JSP. If you deploy the Web application as a .war file, re-jar the Web application and deploy it.

   WebLogic Portal deploys the modifications. If you specified a page-check rate for your Web application, WebLogic Portal waits for the page-check interval to expire before deploying any changes.

Accessing a Content Selector Cache on a Different JSP

To access a content selector cache on a Different JSP, use this procedure:

1. In a text editor, open the JSP page that contains the content selector tag. For example, you want to cache the results of the following tag:
   <pz:contentSelector rule="SpringSailing" id="docs".../>

2. Add attributes to the content selector tag as shown in Listing  8-14:

Listing 8-14 Content Selector Tag Attributes

<pz:contentSelector rule="SpringSailing"
contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>"
id="docs"
useCache="true" cacheId="SpringSailingDocs" cacheTimeout="120000"
cacheScope="application" />

These attributes create a cache that WebLogic Portal maintains for 2 minutes (120000 milliseconds) and that can be accessed using the name SpringSailingDocs by any user from any page in the Web application. For more information about possible values for cacheScope, see Create and Configure the Cache to Improve Performance.

3. Save and deploy the JSP.

4. In a text editor, open the JSP from which you want to access the cache.

5. Use a content-selector tag that is identical to the tag you created in step 2. For example, on the current JSP, add the tag shown in Listing  8-15:

Listing 8-15 Adding an Identical Tag

<pz:contentSelector rule="SpringSailing" 
contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>"
id="docs" 
useCache="true" cacheId="SpringSailingDocs" cacheTimeout="120000"
cacheScope="application" /> 

6. Save and deploy the JSP.

 

---

Integrating External Content Management Systems

For customers who have larger amounts of content and want more control over the publishing and tagging of content, BEA partners with third-party vendors to add flexibility to WebLogic Portal. Third-party content management systems provide robust, content-creation management solutions while the Content Manager personalizes and serves the content to the end user.

Integration Strategies

BEA recommends three strategies for integrating a third-party content management system with the WebLogic Portal:

• Have the CMS publish the documents onto the file system and use the reference implementation's BulkLoader to load them into the database. This is the same process described in Adding Content by Using the Bulk Loader, except that you must ensure that the third-party CMS loads data into the appropriate location at a regularly scheduled interval. See Adding Content by Using the Bulk Loader for complete information.

• Write an implementation of the DocumentProvider interface. See Adding Content by Implementing a DocumentProvider Interface.

• Have the CMS publish into the reference implementation document repository. See Publishing to Reference Implementation.

Adding Content by Implementing a DocumentProvider Interface

The DocumentProvider object is the entry point into an SPI implementation. It consists of methods that access the underlying content management system. When developing a DocumentProvider, you do not need to be concerned about transactional state or thread safety. Since a DocumentProvider does not need to perform write actions, a transaction is not required to access a DocumentProvider.

Implementing a DocumentProvider interface involves writing implementations of Java interfaces contained in the com.beasys.p13n.content.document.spi package. These interfaces are:

• DocumentProvider

• DocumentIterator

• DocumentMetadataDef

• DocumentDef

• DocumentSchemaDef

The following sections describe how these interfaces are implemented to integrate a CMS with WebLogic Portal.

For more information on these interfaces, see the Javadoc for com.beasys.p13n.content.document.spi.

The following steps present a high-level description of how to implement a DocumentProvider interface.

Step 1. Ensure that the CMS Meets the Minimum Use Requirements

To successfully integrate a Content Management System into WebLogic Portal, the CMS must support the capabilities listed in Table  8-8.

Table 8-8 CMS Minimum Use Requirements

Requirement	Description
Unique document Ids	There must be a single key that identifies a document as unique from all the other documents in the system, and it must be possible to represent the key as a String. For example, some content management systems assign a document an object id, while others (including the reference implementation) use the relative path.
Document Metadata	There must be a way to retrieve all the metadata about a document. The metadata must be comprised of the standard WebLogic Portal types (Boolean, Integer, Float, DateTime, String, Multi-valued), or be able to be converted to those types. This metadata must include, at a minimum, the size of the document in bytes and the MIME 1.0 mime type of the document.
Document content retrieval	There must be some way to retrieve the raw bytes of the document.
Searching	The CMS must allow some mechanism to search for documents based upon a query against the document metadata. (Full-text searches are not required in WebLogic Portal.)
Schemas	The CMS must provide a mechanism to expose the document metadata schemas. Schemas describe which of the metadata attributes and their types will be associated with which types of documents. The rules editor then uses this schema information to let you create the content selector rules that make personalization possible. (Regular document searching methods do not use the schema information, so non-personalized document retrieval is possible without schemas.)
Java access	The CMS must support some mechanism by which Java code can access the documents. These may include, but are not limited to, Java class libraries, a native shared library which JNI can access, socket based access (such as HTTP, DCOM, client-server), DBMS level access, file based access, or eLink capable access. (Java access is optional when publishing into the reference implementation supplied by WebLogic Portal.)

 

If all of these requirements cannot be met in some fashion, it will not be possible to fully integrate the CMS with WebLogic Portal. Additionally, since WebLogic Portal does not provide document creation and editing functionality, the CMS must have some way for users to create and edit documents.

Step 2. Write the SPI Implementation

Next, you need to code the SPI by implementing the interfaces described in Table  8-9 and the additional default and helper classes listed in DefaultDocumentProvider. These interfaces provide two-way communication between your Web application and the CMS by taking BEA objects and converting them to objects recognizable by the CMS.

Table 8-9 DocumentProvider Interfaces

Interface	Description
DocumentIterator	The DocumentIterator interface extends the java.util.Iterator interface by adding a close() method. The close() method is invoked when the DocumentIterator is no longer used. It clears any resources tied to the DocumentIterator. The methods invoked by this interface should not return null. If an exception is necessary, the methods should throw a DocumentException. If the results set is empty, than an empty DocumentIterator should be returned.
DocumentMetadataDef	The DocumentMetadataDef interface represents the metadata attributes of a document. This interface contains methods for retrieving both explicit and implicit (CMS defined) metadata. The getProperty(String name) method for retrieving implicit metadata should not respond to the explicit attributes names: identifier, size, version, author, creationDate, lockedBy, modifiedDate, modifiedBy, description, comments, and mimeType. To retrieve the explicit properties, the infrastructure calls the corresponding individual methods.
DocumentDef	The DocumentDef interface represents the raw bytes of a document's content. Although this interface is required to implement two methods, primarily the openStream() method will be invoked. It is highly recommended that the InputStream returned from openStream() supports the skip() and available() methods in an efficient manner. The skip() method will be used when returning chunks of the content bytes to WebLogic Portal. The available() method will be used to determine how many more bytes are available from the stream.
DocumentSchemaDef	The DocumentSchemaDef represents a single available schema from the underlying CMS. It contains methods to query the attribute names, types, possible values, and descriptions.

 

For information on how WebLogic Portal's content-related JSP tags map to the WebLogic Portal SPI, see the "Personalization JSP Tags" section of the JavaServer Page Guide at http://download.oracle.com/docs/cd/E13218_01/wlp/docs70/jsp/p13njsp.htm.

Additional DocumentProvider Classes to Implement

In addition to the interfaces listed in Table 3-1, you can use some of the abstract classes in the com.bea.p13n.content.document.ref package as base classes to implement some SPI functionality. These classes include:

• DefaultDocumentProvider

• DefaultDocumentIterator

• DefaultDocumentMetadata

• DefaultDocumentSchema

• DefaultDocument

• FileDocument

• URLDocument

Other classes that can help in developing a DocumentProvider implementation include:

• com.bea.p13n.content.document.ref.DocumentComparator

• com.bea.p13n.content.expression.SortCriteria

• com.bea.p13n.content.expression.ExpressionHelper

• com.bea.p13n.content.expression.ExpressionAdapter

• com.bea.p13n.content.MimeTypeHelper

• com.bea.p13n.util.DefaultEntityResolver

• com.bea.p13n.util.jdbc.JdbcHelper

• com.bea.p13n.util.WildCard

Note: Consult the WebLogic Portal Javadoc for further details about each class.

Implementing Search and Schema Methods

In general, integating a third-party CMS requires that you implement both search methods and schema methods.

Search methods return metadata about a document; that is, the data that determines the appearance of the data returned. You will need to determine how the search criteria passed into the search object corresponds to the search methods allowed by the CMS and then define this mapping in order for the search to work.

Schema methods return the "bytes"; that is, something that represents the data to be consumed by the Web application. Assuming that the necessary data exists in the polled CMS, these methods will return:

• The specified schema object

• A list of all schema names

• A map of schema names

Step 3. Place Code Into the Application

Once the SPI implementation is written, WebLogic Portal needs to be configured to use it. To do this, you can either:

• Modify the Existing DocumentConnectionPool

OR

• Configure a New DocumentConnectionPool and DocumentManager

Modify the Existing DocumentConnectionPool

The first method is to simply modify an existing DocumentConnectionPool in the application's META-INF/application-config.xml. The DocumentManager implementation uses connection pools to a specialized JDBC driver to handle searches. A deployed DocumentManager finds the document connection pool to use via either the DocumentConnectionPoolName attribute of its DocumentManager MBean or the DocumentConnectionPoolName EJB deployment descriptor setting.

Configure a New DocumentConnectionPool and DocumentManager

The second way to configure WebLogic Portal is to set up a new DocumentConnectionPool in the application's META-INF/application-config.xml file and to deploy a new DocumentManager EJB in the application.

First, create a new connection pool by following the procedure outlined in the Using the WebLogic Server Administration Console to Modify DocumentManager MBeans Be sure to give the DocumentConnectionPool a unique name in the application (for example, "myConnectionPool").

Next, put together the new EJB by using the following procedure:

1. Unjar the <application-directory>/document.jar file to a temporary directory.

2. Add your implementation code to the directory appropriately.

3. In META-INF/ejb-jar.xml, create a new <session> entry based upon the DocumentManager entry. Be sure to change the <ejb-name> entry to a unique name; for example, in Listing  8-16, that is NewsletterDocumentManager:

Listing 8-16 Creating a New <session>

<!--  The Newsletter DocumentManager  --> 
<session>
<ejb-name>NewsletterDocumentManager</ejb-name>
   <home>com.bea.p13n.content.document.DocumentManagerHome</home>
   <remote>com.bea.p13n.content.document.DocumentManager</remote>
   <ejb-class>com.bea.p13n.content.document.internal.
      SPIFastDocumentManagerImpl</ejb-class>
   <session-type>Stateless</session-type>

   <transaction-type>Container</transaction-type> 

   <!--
    This controls which DocumentManager MBean this instance
    will look for in the application-config.xml.
   --> 

   <env-entry>
      <env-entry-name>DocumentManagerMBeanName</env-entry-name>
      <env-entry-type>java.lang.String</env-entry-type>
      <env-entry-value>newsletter</env-entry-value>
   </env-entry>
</session>

4. In the new <session> entry in META-INF/ejb-jar.xml, change the <env-entry-value> in the <env-entry> for DocumentManagerMBeanName to a unique name ("NewsletterDocumentManager" in this example). This value will be used later in the application-config.xml file.

5. In META-INF/ejb-jar.xml, add <assembly-descriptor> and <container-transaction> entries for your new <session> entry. You can copy the existing ones, being sure to change <ejb-name> to the value used above ("NewsletterDocumentManager" in this example). Listing  8-17 shows an example:

Listing 8-17 Adding <assembly-descriptor> and <container-transaction> Entries

<assembly-descriptor>
   <container-transaction>
      <method>
         <ejb-name>NewsletterDocumentManager</ejb-name>
         <method-name>*</method-name>
      </method>
      <trans-attribute>Required</trans-attribute>
   </container-transaction>
   .
   .
   .
</assembly-descriptor>

6. Edit META-INF/weblogic-ejb-jar.xml to create a new <weblogic-enterprise-bean> entry based upon the DocumentManager entry. Be sure to change the <ejb-name> entry to the name used above ("NewsletterDocumentManager" in this example). Listing  8-18 shows an example.

Listing 8-18 Creating a New <weblogic-enterprise-bean> Entry

<weblogic-ejb-jar>
   <weblogic-enterprise-bean>
      <ejb-name>NewsletterDocumentManager</ejb-name>
      <entity-descriptor>
         <persistence>
            <persistence-type>
               <type-identifier>WebLogic_CMP_RDBMS
               </type-identifier>
               <type-version>7.0</type-version>
               <type-storage>META-INF/weblogic-cmp-rdbms-jar.xml
               </type-storage>
            </persistence-type>
            <persistence-use>
               <type-identifier>WebLogic_CMP_RDBMS
               </type-identifier>
               <type-version>6.0</type-version>
            </persistence-use>
         </persistence>
      </entity-descriptor>

   <jndi-name>${APPNAME}.BEA_portal_examples.
      NewsletterDocumentManage</jndi-name>

</weblogic-enterprise-bean>

7. In META-INF/weblogic-ejb-jar.xml, in the new <weblogic-enterprise-bean> entry, change the <jndi-name> to a desired value. This value will be the JNDI name used in EJB references to your new DocumentManager. For example:

   <jndi-name>${APPNAME}.BEA_portal_examples.
      NewsletterDocumentManager</jndi-name>

8. Jar up the temporary directory back into document.jar.

Step 4. Make the .jar Accessible to the Application

Next, you need to make the .jar file you created accessible to the application accessing the CMS. You can do this by using one of these methods:

• Place the .jar into a .jar file already deployed in the application.

• Place the .jar into a .jar file referenced in the META-INF/Manifest.mf file's Class-Path entry in the .jar file that initializes the DocumentConnectionPool (for example, document.jar).

• Put the .jar name in a classpath attribute on the DocumentConnectionPool MBean in the application's META-INF/application-config.xml file

Step 5. Restart the Server

Because, by this point, you have made a number of configuration changes and changes to classpaths, we recommend that you restart the server.

Step 6. Apply the Portal

Finally, to complete the integration, you need to create the portal into which the CMS data will appear. For instructions on creating a portal or portlet, please refer to Step 3: Add a Portlet.

Publishing to Reference Implementation

This strategy involves directly publishing to the WebLogic Portal reference implementation database tables and XML schema files.

To implement this strategy:

1. Put the document entries and document metadata into the database tables.

2. Put the document metadata schema into WebLogic Portal XML schema files.

3. Put the document files on the file system.

 

---

Constructing Content Queries

This section, which provides guidelines for constructing queries to a content management system, includes information on the following topics.

• Structuring Queries

• Using Comparison Operators to Construct Queries

• Constructing Queries Using Java

• Using the Document Servlet

Structuring Queries

WebLogic Portal queries are similar in syntax to the SQL string syntax that supports basic Boolean-type comparison expressions, including nested parenthetical queries. In general, the query includes a metadata property name, a comparison operator, and a literal value. For example:

attribute_name comparison_operator literal_value

Note: For more information about the query syntax, see the Javadoc API documentation for com.bea.p13n.content.expression.ExpressionHelper.

The following constraints apply to queries constructed using this syntax:

• String literals must be enclosed in single quotes.

  • `WebLogic Server'

  • `football'

• Date literals can be created using a simple toDate method that takes one or two String arguments enclosed in single quotes. The first argument, if two are supplied, is the SimpleDateFormat format string; the second argument is the date string. If only one argument is supplied, it should include the date string in `MM/dd/yyyy HH:mm:ss z' format.

  • toDate(`EE dd MMM yyyy HH:mm:ss z', `Thr 08 Nov 2001 16:56:00 MDT')

  • toDate(`02/23/2005 13:57:43 MST')

• Use the toProperty method to compare properties whose names include spaces or other special characters. In general, use toProperty when the property name does not comply with the Java variable-naming convention that uses alphanumeric characters.

  • toProperty (`My Property') = `Content'

• To include a scope into the property name, use either scope.propertyName or the toProperty method with two arguments.

  • toProperty (`myScope', `myProperty')

  Note: The reference implementation document management system ignores property scopes.

• Use \ along with the appropriate character(s) to create an escape sequence that includes special characters in string literals.

  • toProperty (`My Property\'s Contents') = `Content'

• Additionally, use Java-style Unicode escape sequences to embed non-ASCII characters in string literals.

  • Description like `*\u65e5\u672c\u8a9e*'

  Notes: The query syntax can contain only ASCII and extended ASCII characters (0-255).
  
  Use ExpressionHelper.toStringLiteral to convert an arbitrary string to a fully quoted and escaped string literal which can be put in a query.

• The now keyword, only used on the literal value side of the expression, refers to the current date and time.

• Boolean literals are either true or false.

• Numeric literals consist of the numbers themselves without any text decoration (like quotation marks). The system supports scientific notation in the forms; for example, 1.24e4 and 1.24E-4.

• An exclamation mark (!) can be placed at an opening parenthesis to negate an expression.

  • !(keywords contains `football') || (size >= 256)

• The Boolean and operator is represented by the literal &&.

  • author == `james' && age < 55

• The Boolean or operator is represented by the literal ||.

  • creationDate > now || expireDate < now

The following examples illustrate full expressions:

Example 1:

((color=`red' && size <=1024) || (keywords contains `red' && creationDate < now))

Example 2:

creationDate > toDate (`MM/dd/yyyy HH:mm:ss', `2/22/2000 14:51:00') && expireDate <= now && mimetype like `text/*'

Using Comparison Operators to Construct Queries

To support advanced searching, the system allows construction of nested Boolean queries incorporating comparison operators. Table  8-10 summarizes the comparison operators available for each metadata type.

Table 8-10 Comparison Operators Available for Each Metadata Type  

Operator Type	Characteristics
Boolean (==, !=)	Boolean attributes support an equality check against Boolean.TRUE or Boolean.FALSE.
Numeric (==, !=, >, <, >=, <=)	Numeric attributes support the standard equality, greater than, and less than checks against a java.lang.Number.
Text (==, !=, >, <, >=, <=, like)	Text strings support standard equality checking (case sensitive), plus lexicographical comparison (less than or greater than). In addition, strings can be compared using wildcard pattern matching (that is, the like operator), similar to the SQL LIKE operator or DOS prompt file matching. In this situation, the wildcards will be * (asterisk) to match any string of characters and ? (question mark) to match any single character. Interval matching (for example, using [ ]) is not supported. To match * or ? exactly, the quote character is \ (backslash).
Datetime (==, !=, >, <, >=, <=)	Date/time attributes support standard equality, greater than, and less than checks against a java.sql.Timestamp.
Multi-valued Comparison Operators (contains, containsall)	Multi-valued attributes support a contains operator that takes an object of the attribute's subtype and checks that the attribute's value contains it. Additionally, multi-valued attributes support a containsall operator, which takes another collection of objects of the attribute's subtype and checks that the attribute's value contains all of them. Single-valued operators applied to a multi-valued attribute should cause the operator to be applied over the attribute's collection of values. Any value that matches the operator and operand should return true. For example, if the multi-valued text attribute keywords has the values BEA, Computer, and WebLogic, and the operand is BEA, then the < operator returns true (BEA is less than Computer), the > operator returns false (BEA is not greater than any of the values), and the == operator returns true (BEA is equal to BEA).
User Defined Comparison Operators	Currently, no operators can be applied to a user-defined attribute.

 

Notes: The search parameters and expression objects support negation of expressions using a bit flag (!).

The reference implementation content management system has only single-value Text and Number properties. All implicit properties are single-value Text.

Constructing Queries Using Java

To construct queries using Java syntax instead of using the query language supplied with the Content Management component, see the Javadoc API documentation for com.bea.p13n.content.expression.ExpressionHelper.

The ContentManager session bean is the primary interface to the functionality of the Content Management component. Using a ContentManager instance, content is returned based on a com.bea.p13n.content.expression.Search object with an embedded com.bea.p13n.expression.Expression, which represents the expression tree.

In the expression tree, the following caveats apply for it to be valid for the ContentManager:

• Each branch node can only be of the following types. Any other branch node type is invalid.

com.bea.p13n.expression.operator.logical.LogicalAnd, com.bea.p13n.expression.operator.logical.LogicalOr, com.bea.p13n.expression.operator.logical.LogicalMulitAnd, or com.bea.p13n.expression.operator.logical.LogicalMultiOr.

• Each leaf node can only be of the following types. Any other branch node type is invalid.

com.bea.p13n.expression.operator.comparative.Equals, com.bea.p13n.expression.operator.comparative.GreaterOrEquals, com.bea.p13n.expression.operator.comparative.GreaterThan, com.bea.p13n.expression.operator.comparative.LessOrEquals, com.bea.p13n.expression.operator.comparative.LessThan, com.bea.p13n.expression.operator.comparative.NotEquals, com.bea.p13n.expression.operator.string.StringLike, com.bea.p13n.expression.operator.collection.CollectionContains, or com.bea.p13n.expression.operator.collection.CollectionsContainsAll

• Any valid branch or leaf node may be contained in a com.bea.p13n.expression.operator.logical.LogicalNot node.

• In each leaf node, the left side will always be a com.bea.p13n.content.expression.PropertyRef node, which must contain Strings for getPropertySet() and getPropertyName().

• The right side of these leaf nodes can be a java.util.Collection, Long, Double, String, or java.sql.Timestamp: com.bea.p13n.expression.operator.comparative.Equals, com.bea.p13n.expression.operator.comparative.NotEquals, com.bea.p13n.expression.operator.comparative.GreaterOrEquals, com.bea.p13n.expression.operator.comparative.GreaterThan, com.bea.p13n.expression.operator.comparative.LessOrEquals, com.bea.p13n.expression.operator.comparative.LessThan, or com.bea.p13n.expression.operator.collection.CollectionContains

• The right side of com.bea.p13n.expression.operator.string.StringLike leaf nodes can be a String. Anything else is invalid.

• The right side of com.bea.p13n.expression.operator.collection.CollectionsContainsAll leaf nodes can be a java.util.Collection. Anything else is invalid.

Using the Document Servlet

The Content Management component includes a servlet capable of outputting the contents of a Document object. This servlet is useful when streaming the contents of an image that resides in a content management system or to stream a document's contents that are stored in a content management system when an HTML link is selected. Table  8-11 shows the Request/URL parameters that the servlet supports.

 

Table 8-11 Request Parameters Supported by the Document Servlet  

Request Parameter	Required	Description
contentHome	Maybe	If the contentHome initialization parameter is not specified, then this is required and will be used as the JNDI name of the DocumentHome. If the contentHome initialization parameter is specified, this is ignored.
contentId	No	The string identifier of the Document to retrieve. If not specified, the servlet looks in the PATH_INFO.
blockSize	No	The size of the data blocks to read. The default is 8K. Use 0 or less to read the entire block of bytes in one operation.

 

The servlet supports only Documents, not other subclasses of Content. It sets the Content-Type to the Document's mimeType and, the Content-Length to the Document's size, and correctly sets the Content-Disposition, which should present the correct filename when the file is saved from a browser.

Example 1: Usage in a JSP

This example searches for news items that are to be shown in the evening, and displays them in a bulleted list.

<cm:select sortBy="creationDate ASC, title ASC"

query=" type = `News' && timeOfDay = `Evening' && mimeType like `text/*' "id="newsList"/>

<ul>

<es:forEachInArray array="<%=newsList%>" id="newsItem" type="com.bea.p13n.content.Content">

     <li><a href="ShowDoc/<cm:printProperty id="newsItem"
     name="identifier" encode="url"/>"><cm:printProperty
     id="newsItem" name="title" encode="html"/></a>

  </es:forEachInArray>

</ul>

Example 2: Usage in a JSP

This example searches for image files that match keywords that contain bird and displays the image in a bulleted list.

<cm:select max="5" sortBy="name" id="list"

query=" KeyWords like `*birds*' && mimeType like `image/*' "

contentHome="java:comp/env/ejb/MyDocumentManager"/>

<ul>

<es:forEachInArray array="<%=list%>" id="img" type="com.bea.p13n.content.Content">

   <li><img src="/ShowDoc/<cm:printProperty id="img"
   name="identifier"
   encode="url"/>?contentHome=<es:convertSpecialChars
   string="java:comp/env/ejb/MyDocumentManager"/>">

<es:forEachInArray>

</ul>