|
|
|
|
|
|
Creating and Managing Content
The Content Manager provides content and document management capabilities for use in personalization services. The Content Manager works with files or with content managed by third-party vendor tools from Documentum and Interwoven.
This topic includes the following sections:
What Is the Content Manager?
The Content Manager runtime subsystem provides access to content via both tags and EJBs. The Content Management tags allow a JSP developer to receive an enumeration of Content objects by querying the content database directly 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 content engine behind the ContentManager may be set up to be the reference implementation, provided out of the box, or Documentum. The Content Management component supports querying that returns content from a content repository using several methods:
Note: All other attribute names in queries are considered implicit metadata properties.
Note: See Querying Document Content for more information about queries.
BEA partners with third-party vendors to add flexibility to the WebLogic Personalization Server. The Content Manager works with Interwoven's Teamsite/OpenDeploy product and Documentum's 4i product. Both these products provide robust, content-creation management solutions while the Content Manager personalizes and serves the content to the end user.
How Do I Choose What Content Management Tools to Use?
Interwoven Teamsite/OpenDeploy Integration-for customers who have larger amounts of content and want more control over the publishing and tagging of content, WebLogic Personalization Server provides integration with the Interwoven Teamsite/OpenDeploy product. Teamsite is a content capture, versioning, staging, and publishing system. Teamsite templates define the metadata attributes for the content; customers can use the templates to categorize the documents during the creation process. Teamsite is not a run-time engine; it does not actually get queried by the WebLogic Personalization Server. Once content is captured, the Interwoven OpenDeploy workflow capability works with the WebLogic Personalization Server to publish content to a well-known location and the metadata to our JDBC store.
A WebLogic Personalization Server customer can purchase the Interwoven Teamsite product for content management and publishing. The extensions for Interwoven are available from the BEA download center as one of the Commerce Servers download options.
Content developers working with Documentum create metadata capture tools in Documentum 4i. When they complete the authoring process and check in their documents to Documentum, they must tag the content. Depending on administrative options, this content can be available immediately to the WebLogic Personalization Server for display on the customer's e-commerce site.
WebLogic Personalization Server customers can purchase Documentum 4i to manage the documents or content for their e-commerce site. The JDBC driver for Documentum 4i is available from the BEA download center as one of the Commerce Servers download options.
Constructing Queries Using Java
To construct queries using Java syntax instead of using the query language supplied with the Content Management component, refer to the Javadoc API documentation.
Note: Use the constants in TypesHelper when calling Logical.setLogical and Criteria.setComparator.
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 Search object with an embedded Expression. An Expression is a Boolean tree of arbitrary depth, with other sub-Expressions as nodes. The Expression interface is meant to be abstract, where the actual instances are Logical or Criteria interfaces. As an example, the expression color == 'red' && price > 50 would consist of a Logical with the value and that has as children two Criteria.
Differences Between Content Management and Document Management
Content objects include metadata about the content. Metadata provides a means to query and match content with users by allowing the system to retrieve content based on the metadata that describes the content. In general, some kind of content management system provides services such as retrieval of content and content authoring services including creation, editing, versioning, and workflow.
Documents are a specialized type of Content that provide two methods for retrieval: a metadata-searching mechanism and retrieval of the pure bytes of the document's file. Documents should include additional explicit metadata properties related to the file and its versioning, including its size, name, path, author, and version. A document management system usually provides document-based services for documents that reside in the system's repository.
WebLogic Personalization Server provides the entire Content object model; however, it only provides the Document object as a concrete implementation (subclass) of the Content class.
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. The servlet supports the following Request/URL parameters:
|
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 only supports 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 contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME%>" max="5" sortBy="creationDate ASC, title ASC"
query="type = 'News' && timeOfDay = 'Evening' && mimetype like 'text/*' " id="newsList" />
<ul>
<es:forEachInArray array="<%=newsList%>" id="newsItem"
type="com.beasys.commerce.axiom.content.Content">
<li><a href="/showDocServlet/<cm:printProperty
id="newsItem" name="identifier" encode="url"/>
&contentHome=<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME%>">
<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 contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME%">"
max="5" sortBy="name" id="list" query="Keywords like `*birds*' && mimeType like `image/*'" />
<ul>
<es:forEachInArray array="<%=list%>" id="img"
type="com.beasys.commerce.axiom.content.Content">
<li><img src="/showDocServlet?contentId=<cm:printproperty
id="img" name="identifier" encode="url"/>
&contentHome=<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME%>">
</es:forEachInArray>
</ul>
JSP Tags
The Content Management component includes the following four JSP tags. These tags allow a JSP developer to include non-personalized content in a HTML-based page. Note that none of the tags support or use a body.
Configuring the Content Manager
The DocumentSchema EJB and DocumentManager EJB deployment descriptors handle the configuration for the Content Management component. To use the reference implementation document repository, you need to configure the EJB deployment descriptors and also set up two WebLogic Server JDBC connection pools.
Once the deployment descriptor has been written, just build the EJBs as you normally would, then add the resulting JAR file to your ejb.deploy entry in the weblogic.properties file.
Configuring the Document Schema EJB Deployment Descriptor
The logic for loading Document Schema EJBs is handled via a SmartBMP. The Schema EJB implementation loads the SmartBMP object from a class name specified in the EJB environment in the EJB's deployment descriptor. The EJB environment variable is SmartBMPClass. The value must be the fully qualified class name of the SmartBMP to use. This SmartBMP must be capable of populating a SchemaImpl object with PropertyMetaData objects.
To use the reference implementation document management system, set SmartBMPClass to com.beasys.commerce.axiom.document.SPISchemaSmartBMP and specify the following EJB environment variables in the document EJB deployment descriptor:
For example: jdbc:weblogic:pool:docPool.
Other SmartBMP classes for other document management systems will possibly require more and/or different EJB environment variables.
Configuring the DocumentManager EJB Deployment Descriptor
The DocumentManagerSession EJB simply hides the details of getting to the Document and DocumentSchema EJBs. It understands the following environment variables in its deployment descriptor:
Note: Since the Document EJB is deprecated for read access, this will eventually no longer be required.
For example: jdbc:weblogic:pool:docPool.
For the document reference implementation, set up a specialized WebLogic connection pool and DataSource which will be used by the DocumentManager via the jdbc/docPool reference. (See the topic Configuring the DocumentManager EJB Deployment Descriptor.)
For example, if the connection pool name is docPool:
Note: If schemaXML is a directory, the connection will recurse under it and load all files ending in .xml (*.xml).
Note: If schemaXML is a file, the connection loads it.
All other properties are passed with jdbc.url when the Driver Manager opens a database connection.
Example connection pool Entry
The following example shows a sample configuration in the weblogic.properties file.
weblogic.jdbc.connectionPool.docPool=\
url=jdbc:beasys:docmgmt:com.beasys.commerce.axiom.document.ref.RefDocumentProvider,\
driver=com.beasys.commerce.axiom.document.jdbc.Driver,\
loginDelaySecs=1,\
initialCapacity=1,\
maxCapacity=5,\
capacityIncrement=1,\
allowShrinking=true,\
shrinkPeriodMins=15,\
refreshMinutes=10,\
props=jdbc.url=jdbc:weblogic:pool:commercePool;\
jdbc.isPooled=true;\
docBase=C:/WeblogicCommerce/docBase;\
schemaXML=C:/WeblogicCommerce/docSchemas;\
iw.schemaBase=C:/iw-home/templatedata
weblogic.allow.reserve.weblogic.jdbc.connectionPool.docPool=everyone
weblogic.jdbc.DataSource.weblogic.jdbc.pool.docPool=docPool
Configuring WebLogic Commerce Properties
Use a ContentManager or DocumentManager with <cm:select> or <cm:selectById> to retrieve Content or Documents. The default DocumentManager is deployed at com.beasys.commerce.axiom.document.DocumentManager.
To help with the JNDI names, the ContentHelper class has the following six constants:
The values of those constants are read from the weblogiccommerce.properties file from the values for the following properties:
Therefore, in any <cm:select>, <cm:selectById>, <pz:contentQuery> or <pz:contentSelector> tags, define the contentHome (or contenthome) parameter to use a ContentManagerHome or DocumentManagerHome.
Example:
The News Index and News Viewer portlets use the default deployed DocumentManager and can be used as a reference. The JSPs are located in the server/public_html/portals/repository/portlets directory in the news_index.jsp, news_viewer.jsp and content_titlebar.jsp files.
Using the Show Document Servlet
To operate the Show Document servlet, it should be registered with WebLogic Server. The class name of the servlet is com.beasys.commerce.content.ShowDocServlet. To register it with WebLogic, add a line similar to the following to your weblogic.properties files:
weblogic.httpd.register.showDocServlet=\
com.beasys.commerce.content.ShowDocServlet
Reference the class in the URL as /showDocServlet. To change the URL reference, change /showDocServlet. For example, to specify the URL as /myapp/doc-shower, enter the following in the weblogic.properties file:
weblogic.httpd.register.myapp/doc-shower=\
com.beasys.commerce.content.ShowDocServlet
Querying Document Content
There are several way to query the document management system. To query the system, you construct a query expression, then pass the expression to any one of these:
WebLogic Personalization Server queries use a syntax similar to the SQL string syntax that supports basic Boolean-type comparison expressions, including nested parenthetical queries. In general, the template for use includes a metadata property name, a comparison operator, and a literal value. The basic query uses the following template:
attribute_name comparison_operator literal_value
Note: Consult the Javadoc API documentation on com.beasys.commerce.util.ExpressionHelper for more information about the query syntax.
Several constraints apply to queries constructed using this syntax:
Note: The reference document management system ignores property scopes.
Note: The query syntax can only contain ASCII and extended ASCII characters (0-255).
Note: Use ExpressionHelper.toStringLiteral to convert an arbitrary string to a fully quoted and escaped string literal which can be put in a query.
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. The following table summarizes the comparison operators available for each metadata type. (For more information about the native types supported in WebLogic Personalization Server, see Support for Native Types in the Developer's Guide chapter Overview of Personalization Development .)
|
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) for match any and ? (question mark) for match single. Interval matching (for example, using [ ]) is not supported. To match * or ? exactly, the quote character will be \ (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. |
Note: The search parameters and expression objects support negation of expressions via a bit flag (!).
Note: The reference document management system has only single-value Text and Number properties. All implicit properties are single-value Text.
Using the BulkLoader to Load File-based Content
WebLogic Personalization Server provides no run-time tools to load metadata information from a content database. However, the server provides a command-line utility, the BulkLoader, that descends a directory hierarchy, parses the HTML-style <meta> tags, reverses the metadata content contained within the <meta> tags into schema information, and loads the resulting documents into the reference implementation database.
The BulkLoader is a command-line application that is capable of loading document metadata into the reference implementation database from a directory and file structure. The BulkLoader parses the document base and weblogic.properties and loads all the document metadata so that the Content Management component can search for documents. The BulkLoader supports all document types, not just HTML documents.
Command Line Usage
The BulkLoader class allows a number of command-line switches:
java com.beasys.commerce.axiom.document.loader.BulkLoader
[-/+verbose] [-/+recurse] [-/+delete] [-/+metaparse] [-/+cleanup]
[-/+hidden] [-/+inheritProps] [-schemaName <name>] [-encoding <encoding>]
[-properties <name>] -conPool <name> [-schema <name>] [+schema]
[-match <pattern>] [-ignore <pattern>] [-htmlPat <pattern>]
[-d <dir>] [-mdext <ext>] [--]
[files... directories...] [-filter <filter class>] [+filters]
How the BulkLoader Finds Files
The following sequence describes how the BulkLoader locates files:
Note: If the file or directory is not an absolute path, then it is assumed to be relative to the docBase specified by the -d option.
Note: If it is a hidden file (or directory) and the +hidden option was not specified, then the file or directory is ignored.
Note: The -match and -ignore options only apply to files and directories not listed on the command line; in other words, they apply only to those found by recursing into a directory. The patterns specified with the -match and -ignore options (and the -htmlPat options, for that matter) should be DOS-style patterns: '*' matches any set of characters, '?' matches any one character. Sets of characters (for example, [aceg]) are not supported.
Note: Files with an extension matching the extension specified by -mdext (.md.properties by default) are always ignored.
How the BulkLoader Finds Metadata Properties
As the BulkLoader is finding files and directories, it will also attempt to load metadata property files. Whenever the BulkLoader encounters a directory that it will process, it looks for a file called dir.<mdext> where <mdext> is the extension specified by the -mdext option. Therefore, the default filename it looks for is dir.md.properties. If this file exists and is readable by the user, the BulkLoader loads it as a Java-style properties file of name=value properties. If the directory is actually a subdirectory entered because +recurse was not specified and the +inheritProps option is not specified, then the properties from dir.md.properties will be added to the properties from the parent directories. All files in the directory gain these metadata properties.
When the BulkLoader finds a file which is to be included and loaded, it looks for a file whose name is the original file name appended with the -mdext extension. So, by default, if the file is called image.gif, the BulkLoader looks for a file called image.gif.md.properties. If that file exists and is readable, the BulkLoader loads those properties into the directory's properties (and possibly the parent directories' as well).
Next, if the file is an HTML file and the +metaparse option was not specified, then the BulkLoader will parse the HTML, looking for <meta> tags and <title> tags. The BulkLoader determines if a file is an HTML file by using the filename patterns specified by the -htmlPat options. If no -htmlPat patterns are specified, then *.htm and *.html are used. The BulkLoader will load into the file's properties any <meta> tags that contain name and content values found anywhere in the file (not just in the HTML head section). Additionally, it will pull the title from the <title></title> and set it as "title".
Finally, the BulkLoader will pass the file to the loadProperties method of each registered LoaderFilter (the -filter option). The LoaderFilter may assign additional metadata to the file. When the BulkLoader starts up, it looks for a com/beasys/commerce/axiom/document/loader/loader.properties file in the classpath. From that, it looks for a loader.defFilters property. This is the colon-separated list of LoaderFilter class names the BulkLoader should always load. Unless that file is modified, the BulkLoader will load an ImageLoaderFilter, which will pull the width and height from *.gif, *.jpg, *.png, and *.xbm image files.
In summary, the BulkLoader gathers metadata for a document from the following sources (in this order):
From there, the ID of the document in the database will be the file path, relative to the docBase specified by the -d option. If the file path is not relative to the docBase, then it will be relative to the path from the command line. The file size will be retrieved from the file. The mimeType will be determined by the file's extension. The modifiedDate in the database will become the current time (since that is when the document is being modified in the database).
Cleaning Up the Database
If the -cleanup option is specified, the BulkLoader will not actually load any documents. Instead, it will attempt to clean up and update the database tables. It will first query the database, looking for any metadata entries that do not have corresponding document entries. For each of those, it will create a document entry. It will then go over each document entry and update the size, modified date, and possibly the MIME type (if the MIME type is not in the database) based upon the files in the docBase specified with the -d option.
Loading Internationalized Documents
The BulkLoader accepts a -encoding <enc> option. When this is specified, the BulkLoader will use that encoding to open all HTML files to find <meta> tags.
For example, if the files under the Unicode-files directory were saved in the Unicode encoding, you could do:
java com.beasys.commerce.axiom.document.loader.BulkLoader -verbose -properties weblogic.properties -conPool commercePool -schema dmsBase\schemas\unicode-files.xml -d dmsBase unicode-files -encoding Unicode. When -encoding is specified, the generated schema XML file will be in the UTF-8 encoding (since some metadata property names might not be ASCII), which the run-time engine can read in. (Note: UTF-8 is a superset of ASCII and can be mostly read by common text editors.)
When -encoding is specified, all HTML files the BulkLoader encounters will be opened with the specified encoding. Therefore, either the encoding must be a superset of all the files' encodings (for example, ISO8859_1 is a superset of ASCII, where as Unicode is not) or the BulkLoader might not be able to correctly pull out the META tag information. It is recommended to either save all documents in a single encoding or to run the BulkLoader against only certain directories at a time (for example, put all the Big5 files in one directory).
The list of available encoding names is contained in the documentation for your JDK, or the documentation for the tool which created the file. If you are not creating files containing non-ASCII characters, this should not affect you.If you want to check if the BulkLoader is correctly parsing your HTML file, you can use the com.beasys.commerce.axiom.document.loader.MetaParser class. For example:
java com.beasys.commerce.axiom.document.loader.MetaParser unicode.htm unicode would print out the <meta> tags found in the unicode.htm file, assumed to be Unicode encoded. Of course, any non-ASCII character probably will not print correctly to your console window, but you can tell what it thinks it found.
Generating Schema Files
Additionally, the BulkLoader supports a -schemaName <name> argument which controls the name of the schema in the generated XML file; this in turn affects the name of the Content PropertySets which appear in the rules editor. If not specified, it defaults to "LoadedData."
After loading all the documents on the list, if the +schema option is not specified, the BulkLoader will output a XML file containing the schema information and following the doc-schemas DTD. The BulkLoader will output a single schema which contains entries for all the metadata attributes it finds over the entire load.
Using Content Management JSP Tags
To use the Content Management JSP tags, ensure that the cm.tld file resides in the WEB-INF directory of your WAR files or in your document root.
Content Cache
The <cm:select> and <cm:selectById> tags support a session-based, per-user Content cache for content searches. To enable this, both tags support the following parameters. All three tag parameters can be JSP run-time expressions.
Additionally, the commerce.content.cache.useSoftHashMap property in the weblogiccommerce.properties controls whether the ContentCaches internally use SoftReferences to cache the Content. SoftReferences should allow the garbage collector to clear portions of the caches as memory is needed. This defaults to false.
Note: The Windows NT 1.2.2 JVM supports SoftReference quite well; however, the Solaris Production 1.2.1_04 JVM always immediately clears SoftReferences, thereby eliminating their usefulness as a caching mechanism. It is recommended that commerce.content.cache.useSoftHashMap be set to true under Windows NT , but set to false under Solaris.
Example:
The News Index and News Viewer portlets use content caching and can be used as a reference. The JSPs are located in the server/public_html/portals/repository/portlets directory in the news_index.jsp, news_viewer.jsp and content_titlebar.jsp files.
readOnly Content Tag
The <cm:select> and <cm:selectById> tags support an optional readOnly parameter.
If not specified, the default value (from ContentHelper.DEF_CONTENT_READONLY, which is loaded from the commerce.content.defaultReadOnly property in the weblogiccommerce.properties file) is used. Additionally, a ContentHelper.getContent() method and a ContentManager.getContent() method take a readOnly flag.
In the reference implementation, invoking the getContent() method without the readOnly parameter invokes the new getContent() method, passing in ContentHelper.DEF_CONTENT_READONLY. If readOnly is true, then non-EJB instances of Content and Document objects can be returned; with the reference implementation, non-EJB instances will be returned.
Note: This can help performance and prevent deadlocks. It is highly recommended that commerce.content.defaultReadOnly be set to true, and that, if readOnly is specified, it be specified true.
Object Interfaces
The interfaces ConfigurableEntityRemote, ContentRemote, DocumentRemote, UserRemote and GroupRemote extend both EJBObject and their respective non-EJBObject interfaces. For example:
ConfigurableEntityRemote extends EJBObject and ConfigurableEntity.
DocumentRemote extends ContentRemote, which extends ConfigurableEntityRemote.
UserRemote and GroupRemote extend ConfigurableEntityRemote.
In this fashion, SessionBeans, tags and utility methods can return either lightweight objects or the EJB instances, depending upon usage and parameters.
Note: In general, you should only typecast to the non-EJB interfaces (that is, ConfigurableEntity, not ConfigurableEntityRemote).
|
|
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|