| Oracle® Fusion Middleware System Administrator's Guide for Oracle Content Server 11g Release 1 (11.1.1) E10792-02 |
|
 Previous |
 Next |
Home > System Administrator's Guid... > Managing System Settings
| Oracle® Fusion Middleware System Administrator's Guide for Oracle Content Server 11g Release 1 (11.1.1) E10792-02 |
|
Previous |
Next |
Home > System Administrator's Guid... > Managing System Settings
This chapter describes concepts and tasks for managing Oracle Content Server system settings on an ongoing basis. It covers the following topics:
This section covers the following topics:
System properties are system-wide settings that enable you to tailor Oracle Content Server to your particular requirements. System properties are set during installation and are generally updated occasionally, or as needed, in contrast to other administration tools, which are used more regularly for maintenance of users and content.
|
Important: Regardless of which method is used to modify system properties, you must restart the Oracle Content Server instance for any configuration changes to take effect. |
There are several ways to interact with system properties:
The Admin Server enables you to configure a single Oracle Content Server instance. You also can enable and disable system components. The Admin Server can be accessed by using a web browser and selecting the Administration link.
The System Properties application enables you to configure a specific Oracle Content Server instance from the system on which the Oracle Content Server instance is deployed. For information on accessing the System Properties utility, see Section 3.4.2, "Running Administration Applications in Standalone Mode."
Most system properties settings correspond to a configuration variable in one of the following configuration files:
IntradocDir/config/config.cfg
DomainHome/ucm/short-product-id/bin/intradoc.cfg
IntradocDir/search/search.cfg
It is recommended that you make changes to these files through the Admin Server or System Properties application to ensure that the settings are entered correctly. While it is possible to edit these files directly using a text editor, it might allow errors to be introduced. See the Oracle Fusion Middleware Idoc Script Reference Guide for more information on configuration variables.
|
Note: For the System Properties utility to run as a standalone application for an Oracle Content Server instance on an Oracle WebLogic Server instance, additional configuration is required. See Section 3.4.2.1, "Configuring a SystemDatabase Provider for Standalone Mode." |
There are many techniques for optimizing the performance of Oracle Content Server. One of the types of tuning involves changing default parameters and software settings that affect the core Oracle Content Server performance. System optimization and performance tuning is often accomplished by adjusting system settings and configuration variables or tuning resources such as databases and indexes.
For example, as the content in your Oracle Content Server instance increases, you might experience a shortage of available space. In this case, moving the vault, weblayout, and search index directories to another drive with more space can help alleviate storage problems. Moving these directories requires adding entries into the DomainHome/ucm/cs/bin/intradoc.cfg file.
You do not have to log in as the system administrator to access the System Properties application. You only need access to the local computer where the Oracle Content Server instance is installed.
You can set general options on the System Properties: Options Tab or on the Admin Server: General Configuration Page. You must restart the Oracle Content Server instance for any configuration changes to take effect.
If you plan to use the Batch Loader utility to update and insert a large number of files on your Oracle Content Server system simultaneously, you must create a batch load file. Two of the optional parameters that you can include in your batch load file are primaryOverrideFormat and alternateOverrideFormat. However, these options only work as parameters in the batch load file if you enable the IsOverrideFormat configuration variable. You can set this variable using the System Properties application.
The metadata field named Revision has a default revision number sequence of 1, 2, 3, 4, 5, and so forth. This number increments automatically for each revision of a document.
You can override the Revision default by changing the definition of the revision label. The revision label consists of two parts: a major and minor revision sequence. The Major Revision Label Sequence is the first number or letter and the Minor Revision Label Sequence follows. For example, in the revision sequence 1a, 1b, 1c, 2a, 2b, 2c, 3a, 3b, 3c, and so forth, the numbers 1, 2, 3 are the major revision sequence and a, b, c are the minor revision sequence.
Both the major and minor revision sequences are defined as a range of numbers or letters. The major sequence can have multiple ranges, while the minor sequence can only have one range.
The following are the restrictions on defining the range:
Numbers or letters can be used, but not both. For example, 1-10 is a valid range but A-10 is not a valid range.
Letter ranges can have only one letter. For example, A-Z is a valid range but AA-ZZ is not a valid range.
The following are examples of different revision sequences and how you would define the major and minor revision entries in the config.cfg file.
Example 1
MajorRevSeq=A-D,1-99
The revision sequence is A, B, C, D, 1, 2, 3, 4, and so forth.
Example 2
MajorRevSeq=1-99
MinorRevSeq=a-c
The revision sequence is 1a, 1b, 1c, 2a, 2b, 2c, 3a, 3b, 3c, and so forth.
To change the default revision sequence manually in the IntradocDir/config/config.cfg file, enter the following name/value pairs:
MajorRevSeq=range1,range2,range3...
MinorRevSeq=range
where range1,range2,range3... and range are the defined range sequence.
The Oracle Content Server Chunking function protects large data transfers from transfer failures by dividing data into chunks and transferring one chunk at a time. If a transfer fails, all chunks transferred to the Oracle Content Server instance before failure are saved, and the transfer can be resumed from the point of failure.
|
Note: If the client session using the Chunking function is killed, either by timeout or by closing the client browser, the transfer will fail. |
You can use the Chunking function with the upload applet.
To enable and configure the Chunking function:
Enable the upload applet or the HTTP provider. See Section 4.1.2, "Configuring General Options."
To enable the upload applet, see Section 4.1.2, "Configuring General Options."
To create an HTTP provider, see Section 5.8, "Additional Oracle Content Server Security Connections."
Set the following configuration settings in the Additional Configuration Variables box on the Admin Server: General Configuration Page:
DisableHttpUploadChunking=false AppletChunkThreshold=size in bytesAppletChunkSize=size in bytes
The AppletChunkSize setting sets the size of the individual chunks. The AppletChunkThreshold setting sets the minimum file size that will use the Chunking function. Both of these values default to 1M.
To debug the Chunking function, set ChunkedRequestTrace=true.
This setting enables you to view the chunked requests on Admin Server Output Page.
Save the changes.
Restart the Oracle Content Server instance.
You can set Oracle Content Server content security options on the System Properties: Content Security Tab or on the Admin Server: Content Security Page.
You must restart the Oracle Content Server instance for any configuration changes to take effect.
You can set Oracle Content Server Internet options on the System Properties: Internet Tab or on the Admin Server: Internet Configuration Page.
You must restart the Oracle Content Server instance for any configuration changes to take effect.
The Oracle Content Server system uses an Oracle WebLogic Server data source to communicate with the system relational database where metadata and other information is stored. The Oracle WebLogic Server Administration Console must be used to manage the database connection information for the system relational database, therefore JDBC user name and password information is not stored in the IntradocDir/config/config.cfg file, and it is not managed through the SystemProperties utility.
|
Note: If you set database connection information for an Oracle WebLogic Server domain using the Oracle Content Server SystemProperties utility, the JDBC user name and password are encrypted and stored in an unspecified location. |
For information about supported databases, see the "System Requirements and Supported Platform" document for your product on the Oracle Fusion Middleware Supported System Configurations page on Oracle Technology Network at
http://www.oracle.com/technology/software/products/ias/files/fusion_certification.html
For information on configuring database connections for an Oracle Content Server system running standalone applications, see Section 3.4.2.1, "Configuring a SystemDatabase Provider for Standalone Mode," Section 3.4.2.2, "Configuring a JDBC Database Driver for Standalone Mode," and Section 3.4.2.3, "Configuring an External Database Provider for Standalone Mode."
Configuring Oracle Content Server for IBM DB2 Database Searches
An IBM DB2 database does not support the keyword CONTAINS in search queries. The correct configuration of the Oracle Content Server instance for IBM DB2 searches requires the addition of the flag SSUseContains=false variable. To configure the Oracle Content Server instance:
Open a new browser window, and log in to the Oracle Content Server instance as system administrator.
In the navigation tree, choose Administration, then Admin Server.
In the option list for the Oracle Content Server instance, choose General Configuration.
The General Configuration page is displayed.
Add the following line in the Additional Configuration Variables area:
SSUseContains=false
Click Save.
Restart the Oracle Content Server instance.
You can set Oracle Content Server options on the System Properties: Server Tab. For security reasons, the Admin Server cannot be used to configure these options. You must use the standalone application to configure Oracle Content Server options. For details about using standalone applications, see Section 3.4.2, "Running Administration Applications in Standalone Mode."
Certain Oracle Content Server configuration options are set using Oracle Enterprise Manager Fusion Middleware Control. For details, see Chapter 2, "Using Fusion Middleware Control to Manage Oracle Universal Content Management."
You must restart the Oracle Content Server instance for any configuration changes to take effect.
|
Caution: If you do not use a Hostname filter, IP Address filter, or some other network-based security, you will have a security hole in your Oracle Content Server instance. For example, with no login, any user with in-depth knowledge of the system could create or modify any other user to have system administrator access. |
Hostname filter or IP Address filter values must be set to allow communication with the Oracle Content Server instance in the following situations:
Running Inbound Refinery and PDF Converter (even on the same physical computer as the Oracle Content Server instance).
Transferring Oracle Content Server archives between computers.
Configurations where the web server and the Oracle Content Server instance are on different systems.
EJB-enhanced operations.
Using the IdcCommand or IdcCommandX utilities on a system separate from the Oracle Content Server instance. (You must change the default value and specify the IP address of the web server.)
You can use the System Properties Localization tab to change language-specific issues such as date/time format, default time zone, sort order, and default interface language. For more information about localization, see Oracle Fusion Middleware Application Administrator's Guide for Content Server.
The default English-US locale uses two digits to represent the year (yy), where the year is interpreted to be between 1969 and 2068. In other words, 65 is considered to be 2065, not 1965. If you want years before 1969 to be interpreted correctly in the English-US locale, you must change the default date format for that locale to use four digits to represent years (yyyy).
This issue does not apply to the English-UK locale, which already uses four digits for the year.
To modify the default English-US data format:
Start the System Properties applet:
Windows operating system:
Select Start, then All Programs, then Oracle Content Server, then [Instance Name], then Utilities, then System Properties.
UNIX operating system:
The SystemProperties utility is located in the /bin subdirectory of the Oracle Content Server installation directory.
Open the Localization tab.
Choose the English-US entry in the list of locales, and click Edit.
The Configure Locale dialog is displayed.
Modify the date format to use four digits for the year (yyyy) rather than two (yy).
After you are done editing, click OK to close the Configure Locale dialog.
Click OK to apply the change and exit System Properties.
Stop and restart the Oracle Content Server instance for configuration changes to take effect.
The default interface language for the Oracle Content Server system can be specified in several ways:
Select a default language in the Localization tab of the System Properties utility, using the same basic procedure described in Section 4.1.7.1, "Date Format."
Use the Oracle Content Server navigation portal to selection Administration, then Localization. Select the checkbox for a default language from the list of Enabled Locales on the Localization Administration page.
You can use the System Properties: Paths Tab to change the location of the help browser, Java classpath, and the shared directory path. For security reasons, the Admin Server cannot be used to configure the path options. You must use the standalone application for this configuration.
You must restart the Oracle Content Server instance for configuration changes to take effect.
This section covers the following topics:
Oracle Content Server interfaces with a variety of indexing tools such as commercial search engines and databases. The indexing tool to use is chosen before installation based on the purpose and environment in which the Oracle Content Server system performs.
Each indexing tool provides full-text indexing and metadata-only indexing. Full-text indexing means that every word in a file is indexed, not only its metadata. Full-text indexing takes longer than metadata indexing; however, it can return a more comprehensive result set. Metadata-only indexing means that every word in the stored content information is indexed. Metadata-only indexing is faster than full-text indexing. By default an Oracle Content Server instance is configured to use metadata-only indexing.
This section covers these topics:
The Repository Manager utility provides an Indexer tab which administrators can use to perform actions on the search index.
To access the Repository Manager, in the Administration tray click Admin Applets, then click Repository Manager. You can also access the Repository Manager as a standalone application. For details, see Section 3.4.2, "Running Administration Applications in Standalone Mode."
The Indexer tab on the Repository Manager screen enables administrators to perform these actions:
Update the Search Index: Incrementally updates the index database. This is usually not necessary because the index is automatically updated approximately every five minutes by the server.
Rebuild the Collection: The search index is entirely rebuilt, and the old index collection is replaced with a new index collection.
Suspend an Update or a Rebuild: Stops the update or rebuild temporarily. You can restart the process by clicking the appropriate Start button.
Cancel Update Search: Index update process terminates, and only files processed to that point are accessible to the search engine.
Cancel Rebuild Collection: Index rebuild process terminates, and the previous index database continues to be used by the search engine.
For more information about managing the repository, see Oracle Fusion Middleware Application Administrator's Guide for Content Server.
On the Repository Manager screen, click the Indexer tab.
Click Start in the Automatic Update Cycle area.
On the Repository Manager screen, click the Indexer tab.
Click Start in the Collection Rebuild Cycle area.
|
Note: OracleTextSearch provides a Fast Rebuild function, which you can use through the Repository Manager Indexer function if your site uses the OracleTextSearch feature. For details, see Section 7.1.3.2, "Fast Rebuild." |
To set the parameters for a search index update or collection rebuild:
On the Repository Manager screen, click the Indexer tab.
Click Configure in either the Automatic Update Cycle portion of the screen or the Collection Rebuild Cycle portion.
Either the Automatic Update Cycle Screen or the Collection Rebuild Cycle Screen is displayed.
Specify the number of content items (files) per indexer batch. This is the maximum number of files that the search index will process simultaneously.
Specify the content items (files) per checkpoint. This is the number of files that will go through all relevant indexing states at a time. You can have multiple batches of files indexed per checkpoint.
Specify the indexer debug level. This is the amount of information pertaining to each file to display in the server window.
Click OK.
If you have configured the Oracle Content Server instance to use DATABASE.FULLTEXT or ORACLETEXTSEARCH as your indexing engine, the Oracle Content Server system uses the Outside In Content Access module to export content to a text file upon check-in. The text file is then passed to the full-text indexer for full-text indexing.
|
Note: When the Outside In Content Access module converts a PostScript file, the conversion process produces text that contains extra characters. Unfortunately, this creates a file that is full-text indexed but cannot be full-text searched. |
If you use DATABASE.FULLTEXT, a full-text search can be problematic on large documents. By default, the maximum document size that is indexed is 10MB. This can be changed by setting the MaxIndexableFileSize configuration variable in the Oracle Content Server repository. The default is MaxIndexableFileSize=10485760. If larger documents require full-text indexing, the value of MaxIndexableFileSize should be increased.
You might want to disable full-text indexing if, for example, you want to conserve file space or if you do not require full-text searching for specific content types. Even if you disable full-text indexing, metadata is still indexed.
To disable full-text indexing on specific files:
Define a format in the Configuration Manager screen named application/noindex.
Enable the Allow Override Format on Check In setting. See Section 4.1.2, "Configuring General Options."
When a user checks in a file that they do not want to be indexed, they should select the application/noindex format. This applies to standard files, batch loads, and archived revisions.
The search index uses weblayout files for indexing by default. In certain situations it may be useful to index native files by default instead of weblayout files. For example, if a converted PDF file cannot be extracted and indexed because of processing issues, the native Word document or an alternate type of document could be extracted and indexed. Another example is if the primary file cannot be indexed because it is an .exe file, but it has an alternate .txt file, then the alternate file could be indexed.
To have the search index use native files for indexing by default, set the following parameter in the Oracle Content Server instance:
UseNativeFormatInIndex=true
Oracle Content Server software supports indexing of e-mail and e-mail attachments (such as original files and zip files). E-mail messages are indexed by default, and if a message contains an attachment it is extracted and indexed as full text. There is no change on what gets returned on search result: if a search finds information in a document, the document metadata is returned.All e-mail attachments supported by Outside In Technology are supported by the search index.
The functionality described in this section is only available if you have installed and enabled the Database Search Contains Operator feature.
|
Note: This feature is not required in the OracleTextSearch component. |
This section covers these topics:
Section 4.2.3.3, "Changing the MinTextFullFieldLength Variable"
Section 4.2.3.4, "Disabling Database Search Contains Operator"
The Database Search Contains Operator feature enables you to use the Contains search operator to search text fields when performing Database and Database Full Text searches on SQL Server and Oracle. You must first enable the text fields that can be queried using the Contains search operator. These text fields are called zone text fields.
When a text field is added as a zone text field, the text within the field is parsed and a full-text index for the field is created in the database. The database performs all the work of creating the index, and the index is dropped from the database if the text field is disabled as a zone text field. Therefore, there is no need to rebuild the collection after enabling or disabling text fields as a zone text fields.
|
Important: Changing a text field to a zone text field can be a very time-consuming operation. The amount of time it takes to parse the text and create the full-text index depends on the number of content items in the Oracle Content Server repository and the amount of text stored in the text field. However, after the text field has been indexed, you should not experience significant performance issues when updating and adding content items. |
When a text field has been enabled as a zone text field, the Contains search operator is available for the text field on the Advanced Search page. It is represented as the Has Word option in the list next to the text field.
To enable or disable zone text fields, complete the following steps:
Log in to the Oracle Content Server instance as an administrator.
Select Zone Fields Configuration from the Administration menu or the Admin Applets page. The Zone Fields Configuration Page is displayed.
Select the search engine from the list.
To enable text fields as zone text fields, complete the following steps:
Select the text fields in the Text Fields list. You can use the [Ctrl] and [Shift] keys on your keyboard to select multiple fields.
By default, text fields with a field length of 20 characters or less are not included in the Text Fields list. You can change this setting by modifying the MinFullTextFieldLength configuration variable. For details, see Section 4.2.3.3, "Changing the MinTextFullFieldLength Variable."
Click the left arrow button to move the text fields to the Zone Text Fields list.
Click Update.
|
Important: Changing a text field to a zone text field can be a very time-consuming operation. The amount of time it takes to parse the text and create the full-text index depends on the number of content items in the Oracle Content Server repository and the amount of text stored in the text field. However, when the text field has been indexed, you should not experience significant performance issues when updating and adding content items. |
To disable zone text fields, complete the following steps:
Select the zone text fields in the Zone Text Fields list. You can use the [Ctrl] and [Shift] keys on your keyboard to select multiple fields.
Click the right arrow button to move the text fields to the Text Fields list.
Click Update.
When enabling and disabling zone text fields, consider the following:
If you start making changes to the lists and you then want to revert to the last saved lists, click Reset.
Custom text fields (the Comments field and any customer created text fields) are shared between the Database and Database search engines, and therefore changing the status of these text fields for one search engine also applies the changes to the other search engine.
Standard text fields (Author, Content ID, Content Type, Title, and so on) can be enabled or disabled independently for each search engine.
The database performs all the work of creating the indexes, and the index are dropped from the database if the text fields are disabled as zone text fields. Therefore, there is no need to rebuild the collection after enabling or disabling text fields as a zone text fields.
You must disable a zone text field before the field can be deleted from the Oracle Content Server instance using Configuration Manager. If you delete an enabled zone text field using Configuration Manager and then click Update Database Design, you will receive an error.
Disabling the zone text field drops the index for the field from the database, allowing the field to be deleted from the database. As an alternative to disabling the zone text field, you could log in to the database and issue a command to drop the index for the field, and then delete the field.
You might want to disable all zone text fields before uninstalling the feature. Otherwise, you are not able to delete the zone text fields from the Oracle Content Server instance unless you reinstall the feature to disable the zone text fields or drop the indexes for the zone text fields from the database manually.
By default, text fields with a field length of 20 characters or less are not included in the Text Fields list. You can change this setting by modifying the MinFullTextFieldLength configuration variable. To change this variable, complete the following steps:
Using a text editor, open the config.cfg file located in the IntradocDir/config/ directory.
Add the MinFullTextFieldLength configuration variable, and set its value (the default value is 21). For example:
MinFullTextFieldLength=16
Save your changes to the config.cfg file.
Restart the Oracle Content Server instance.
Before disabling the feature, you might want to disable all zone text fields. The database contains an index for each enabled zone text field (the indexes are dropped when the zone text fields are disabled). If the database contains an index for a field, it will not let you delete the field from your Oracle Content Server instance using Configuration Manager. For more information, see Section 4.2.3.2, "Enabling and Disabling Zone Text Fields."
If you disable the feature and later want to delete a field that is enabled as a zone text field, you can use one of the following options:
Reinstall the feature, disable the zone text field, use Configuration Manager to delete the field, and uninstall the feature.
Log in to the database and issue a command to drop the index for the field, and then use Configuration Manager to delete the field.
If your system is set up to provide indexing and searching capabilities with databases, your system integrator would have added one of the following lines in IntradocDir/config/config.cfg:
Metadata Searching Only:
SearchIndexerEngineName=DATABASE.METADATA
DATABASE.METADATA is supported in all databases supported by Oracle Fusion Middleware 11g Release 1 (11.1.1).
Full-text Searching:
SearchIndexerEngineName=ORACLETEXTSEARCH
ORACLETEXTSEARCH is supported in Oracle Database version 11.1.0.7 and newer.
Full-text Searching:
SearchIndexerEngineName=DATABASE.FULLTEXT
DATABASE.FULLTEXT is supported in SQL Server, and in Oracle Database (all supported versions).
The dbfulltextsearch script appropriate for the supported database would then be run.
By default, full-text indexing is applied to all converted files.
By default, the Oracle Content Server full-text indexes files that are passed through or converted to any of the following formats:
Oracle Supported Formats
html
htm
xls
hcsp
text
txt
doc
rtf
ppt
MS SQL Supported Formats
text
txt
htm
html
doc
msword
ms-word
ms-powerpoint
ppt
ms-excel
xls
For example, if you want to convert your Microsoft Word (.doc) files to text files instead of PDF, you can specify this in the Configuration Manager. That is, when you use the File Formats option to map the .doc file extension to a text format, then this defines how the file is converted to a web viewable format. In this case, the text file is fully indexed before it is passed to the web site.
For more information about the Configuration Manager's File Formats option, see the Oracle Fusion Middleware Application Administrator's Guide for Content Server.
You can enable contributors to specify whether to full-text index a file by enabling the format override feature in System Properties. See Section 4.1.2, "Configuring General Options."
For example, if you have used the Configuration Manager's File Formats option to map Corel WordPerfect (.wpd) files to use a text format and a contributor selects the use default option in the Format field on the checkin page, the file will be converted to text and full-text indexed. If the contributor selects Corel WordPerfect Document, the file will be passed through in its native format and will not be full-text indexed.
For more information about the Configuration Manager's File Formats option, see the Oracle Content Server Application Administrator's Guide for Content Server.
When you use full-text searching, a search is case sensitive for metadata, and case insensitive for full text. For Content ID, however, lowercase letters are converted to uppercase letters, so Content ID can not be searched with lowercase letters.
If you define a file format to PASSTHRU in the native format, and the format name contains one of the types listed above (such as application/ms-excel.native), the passed through native file will be full-text indexed by default.
Alternatively, you can use configuration variables to control whether a document is full-text indexed. To manage the full-text indexing and search of specific document format types, add applicable entries to IntradocDir/config/config.cfg, and save the file. Full-text indexing configuration variables include:
The FormatMap configuration variable controls whether files of a specific format should be included in the full-text search index. It is a comma-delimited list of all the formats that will be full-text indexed. The decision is made by taking the MIME type assigned to a file, splitting the MIME type apart at any slash (/) or period (.), and then checking if that value is in the FormatMap list.
For example, application/vnd.msword will turn into a list of three items:
application
vnd
msword
If FormatMap has msword in its list, then the indexer engine will attempt to full-text index the file. the comparison test is not case sensitive.
The ExceptionFormatMap configuration variable is used to exclude document formats from the FormatMap test. Any format that satisfies the ExceptionFormatMap test will not be full-text indexed. This test is done after splitting the MIME format at slashes (/), but not periods(.). For example, if msword is included in the exceptions list, then the MIME format application/msword is excluded but not application/vnd.mssword.
The Oracle Query Optimizer component is installed (enabled) by default with the Oracle Content Server system. The functionality only works with the Oracle database.
This section covers these topics:
Section 4.2.5.1, "About The Oracle Query Optimizer Component"
Section 4.2.5.3, "How Reformatted Queries Optimize Searches"
Oracle database does not automatically select the best execution plan for certain types of user queries. To counter this, the Oracle Query Optimizer adds hints to queries that force Oracle database to perform searches more efficiently.
The hints are based on an intrinsic knowledge of Oracle Content Server's table data distribution and its index selectivity. To take advantage of this knowledge, Oracle Query Optimizer uses a pre-defined Hint Rules Table to analyze the database query and then add appropriate hints to the query. In turn, the added hints improve Oracle's search performance.
Oracle Query Optimizer takes advantage of Content Server's data distribution in database tables and its index selection preferences. Based on these characteristics, the Hint Rules Table included with Oracle Query Optimizer contains pre-defined rules. The feature uses these rules to analyze a database query and to add one or more appropriate hints to the query to optimize the search performance.
In very large collections containing millions of content items, the Oracle Content Server software generally has a difficult time selecting an appropriate optimization strategy to resolve even simple queries. To counteract this problem, Oracle Query Optimizer examines the submitted query and, based on its analysis, reformats the query by adding appropriate hints to optimize the search process. To add hints, the feature uses Oracle Content Server hints, The Hint Rules Table, and The Hint Cache.
The stages of the optimization process are completed in the following sequence:
The submitted query is analyzed to verify if it contains one or more hints and, if so, determine the type of hint; see "Stage 1: Query Analysis".
If the query's WHERE clause does not contain a hint, the optimization feature must parse out the WHERE clause; see "Stage 2: Parsing".
After parsing, each condition in the query's WHERE clause is evaluated against the Hint Rules Table in an attempt to qualify the condition and normalize the query; see "Stage 3: Normalization".
After the WHERE clause conditions are qualified and the query is normalized, a hint is selected or retrieved from the hint cache; see "Stage 4: Select Hint".
The query is reformatted using the selected hint; see "Stage 5: Reformat Query".
In this stage, a query is checked for both Oracle (native) and Content Server hints. This is determined based on the hint syntax: Query Hints Syntax. A query that contains Oracle hints is passed through. A query that contains Content Server hints bypasses Stage 2: Parsing and Stage 3: Normalization. If a query contains multiple Content Server hints, the best hint is chosen. Queries that do not contain any hints must be parsed and normalized.
In this stage, a query that does not contain any hints is sent through the query parser and the WHERE clause is parsed out. A WHERE clause consists of one or more conditions joined with either AND or OR conjunctions. For each condition, the field name, operator, and field value are extracted. The AND/OR conjunctions of the clause are preserved; the parentheses are dropped. Conditions must use the following format:
fieldnameoperatorvalue
For example, a properly formatted condition would be dID = 3. An incorrect condition would be 3 = dID.
In this stage, normalization simplifies conditions, finalizes query operators, and provides a stable view of the WHERE clause for additional steps. The result of the normalization process produces a base for generating the cache key and the list of fields to use to search for hints.
|
Note: To establish which database tables and columns have indexes, the Hint Rules Table is defined on Content Server resources and on the running system. |
Qualifying WHERE Clause Conditions:
Each condition in the WHERE clause is checked against The Hint Rules Table. If a condition's field name is included in the Hint Rules Table, then it is qualified and the condition is considered to be normalized. The condition contains its table name and alias. Then the normalized conditions are sorted to ensure that the same set of conditions is always listed consistently.
Discarding WHERE Clause Conditions During Normalization:
During normalization, the following conditions are not considered relevant and are eliminated from further processing:
Join conditions.
Conditions that contain subqueries.
Conditions whose field names do not have entries in the Hint Rules Table and cannot be qualified.
OR conditions that contain more than one field. For example:
(dSecurityGroup = 'Secure' or dDocAccount LIKE 'prj%')
Conditions that contain the LIKE operator whose value begins with a wildcard.
Reformatting WHERE Clause Conditions:
In the normalization step, the query conditions are rewritten to consolidate complex query conditions. OR conditions are reevaluated as follows:
If all the fields are the same and all the operators are equal (or all the operators are LIKE and no values begin with a wildcard), the conditions are combined and changed to an IN query.
If the fields are the same but have different operators, the conditions are combined and the generic operator is assigned.
If the fields are different, the conditions are dropped.
For example, during normalization, the following condition is reformatted:
(dReleaseState = 'Y' OR dReleaseState = 'O")
It is reformatted as follows:
dReleaseState IN ('Y', 'O')
Finding Potential Range Queries:
The parsed query is analyzed to find potential range queries that are then consolidated during the normalization process. For example, the conditions dIndate > date1 and dInDate < date2 are changed to one condition with the operator 'range'.
In this stage, the normalized conditions are checked against the hint cache. If one or more conditions have applicable hints in the cache, they are included. If applicable hints are not found in the cache, the conditions are analyzed and the preference orders are compared to determine the best possible hint.
In this stage, the query is reformatted by adding in the selected hint. For more information about how reformatting queries with hints helps to optimize searches and some examples of reformatted queries, see Section 4.2.5.3, "How Reformatted Queries Optimize Searches."
The majority of queries in an Oracle Content Server instance involve a small, targeted set of content items or return a hundred rows, at most. Oracle Content Server software can easily scale to millions of content items. However, testing on an Oracle database with a collection containing 10 million content items indicates that the execution plan that Oracle selects is not the most efficient. Oracle generally does not choose the best optimization strategies to resolve many queries, even some that are trivial. The following examples explain this issue:
In the environment described above, Oracle does not resolve the following query as efficiently as possible:
SELECT *
FROM Revisions, Documents, DocMeta
WHERE Revisions.dID = Documents.dID
AND Revisions.dID = DocMeta.dID
AND Revisions.dRevClassID = 333
Order By Revisions.dID
Because a fairly selective index is available (dRevClassID_2 for Revisions.dRevClassID), this query should access dRevClassID_2 and perform a sort on the rows that match the dRevClassID. However, in this query example, Oracle chooses to use the Revisions.dID index.
This choice is actually worse than performing a full table scan on the Revisions table because it does a full index scan and accesses the table to obtain the dRevClassID for each row. Obviously, resolving the query using this execution plan does not work well when the Oracle Content Server repository has over 10 million content items. In this case, it requires approximately 500 seconds to return the results.
However, the performance improves dramatically when the query is modified by adding a hint as follows:
SELECT /*+ INDEX(Revisions dRevClassID_2)*/ *
FROM Revisions, Documents, DocMeta
WHERE Revisions.dID = Documents.dID
AND Revisions.dID = DocMeta.dID
AND Revisions.dRevClassID = 333
Order By Revisions.dID
The query is modified by adding the following hint to the SELECT clause:
/*+ INDEX(Revisions dRevClassID_2)*/
This forces Oracle database to choose the dRevClassID_2 index instead of the index for Revisions.dID. Because no more than a few content items share dRevClassID in this example, the modified query returns the results instantly.
In a typical Oracle Content Server instance, most documents have a 'Y' (released) status for the dReleaseState with a dInDate earlier than the current date. However, only a few documents have an 'N' (new, not yet indexed) status for the dReleaseState. The following query is searching for content items that have not yet been released:
SELECT dID
FROM Revisions
WHERE Revisions.dReleaseState = N'N' AND Revisions.dStatus in
(N'DONE', N'RELEASED', N'DELETED')
AND Revisions.dInDate<={ts '2005-02-23 17:46:38.321'}
The optimized result for the query uses the index for dReleaseState:
SELECT/*+ LEADING(Revisions) INDEX (Revisions dReleaseState)*/
dID
FROM Revisions
WHERE Revisions.dReleaseState = N'N' AND Revisions.dStatus in
(N'DONE', N'RELEASED', N'DELETED')
AND Revisions.dInDate<={ts '2005-02-23 17:46:38.321'}
Oracle Content Server queries can be static queries defined in various resources, data sources with additional dynamic WHERE clauses, and dynamic queries that are ad-hoc or defined in the application such as Archiver. Static queries can be updated with Oracle database hints. However, it is nearly impossible to predefine hints for ad-hoc queries and dynamic WHERE clauses.
Content Server hints use a database-neutral hint syntax that supports multiple hints in the same query. An Oracle Content Server hint can be used in any query, data source, and WHERE clause. However, it cannot be combined with an Oracle database hint. If a query contains both types of hints, Oracle Query Optimizer will retain the Oracle database hint and ignore the Content Server hint.
During the optimization processing stages, Oracle Query Optimizer recognizes the distinct syntaxes of both types of hints and correspondingly processes the submitted query. For more detailed information, see Section 4.2.5.2, "Query Optimization Process."
An Oracle hint uses the following format:
/*+ hint */
For example:
/*+ Index(Revisions dID)*/
The Oracle Content Server hint syntax is database neutral and can support multiple Oracle Content Server hints in the same query. During the optimization process, Oracle Content Server hints are evaluated and the best hints are formatted and added back to the query.
During the optimization process, a query that includes one or more Oracle Content Server hints is not parsed. Only Oracle Content Server hints are considered when choosing indexes.
Oracle Content Server Hint Syntax:
When a query undergoes the optimization process, Oracle Content Server hints are added to the reformatted query using the following syntax:
/*$tableName[aliasName]:columnName[:operator [:<value>]][, …]*/
Where:
Values enclosed in angle brackets (<value>) are required.
Values enclosed in brackets ([value]) are optional.
Ellipses (…) indicates a repetition of the previous expression(s).
Query Before Optimization Process:
SELECT * FROM Revisions, DocTypes, RoleDefinition WHERE /*$Revisions:dStatus*/(Revisions.dStatus<>'DELETED' AND Revisions.dStatus<>'EXPIRED' AND Revisions.dStatus<>'RELEASED') AND Revisions.dDocType = DocTypes.dDocType AND /*$Revisions:dReleaseState*/Revisions.dReleaseState<>'E' AND (Revisions.dSecurityGroup = RoleDefinition.dGroupName AND RoleDefinition.dRoleName = ? AND RoleDefinition.dPrivilege > 0)
Reformatted Query with Oracle Content Server Hints Added:
After the query has undergone the optimization process, both indexes are used and are added to the native indexes.
SELECT/*+ LEADING(revisions) INDEX (revisions dStatus dReleaseState)*/ * FROM Revisions, DocTypes, RoleDefinition WHERE (Revisions.dStatus<>'DELETED' AND Revisions.dStatus<>'EXPIRED' AND Revisions.dStatus<>'RELEASED') AND Revisions.dDocType = DocTypes.dDocType AND Revisions.dReleaseState<>'E' AND (Revisions.dSecurityGroup = RoleDefinition.dGroupName AND RoleDefinition.dRoleName = ? AND RoleDefinition.dPrivilege > 0)
Using Oracle sort constructs in search query clauses allows users greater flexibility when performing a query. Sort constructs specify the row data in two or more tables to be extracted, sorted, and combined. Essentially, the sort constructs serve the purpose of limiting the number of rows that are returned. Oracle Query Optimizer recognizes the following sort constructs:
Group by: Sorts a set of records and specifies how to group the results.
Order by: Sorts a set of records and specifies whether the results are to be returned in ascending or descending order.
Inner join: Sorts a set of records by looking for and returning those that match.
Outer join: Sorts a set of records by looking for and returning those that do not match.
The Hint Rules Table contains the rules that the optimization feature uses to determine the proper hints to add to dynamic queries or data sources during the optimization process. Using the Edit Hint Rules Form, a hint rule can be defined for a particular field and operator. A hint rule can also be defined based on values or date/number ranges. The hint rule table is extensible by other components, and can be updated while the Oracle Content Server instance is running.
Several default hint rules included with Oracle Query Optimizer are described in the following text. For more detailed descriptions of the table columns, see Section 4.2.5.8, "Hint Rules Table Column Descriptions." The content of the Hint Rules Table is available on the Hint Rules Configuration Page that is accessed through the Administration tray.
The Hint Rules Table is scheduled to reload every night, and when a rule is added or modified. The hint value is recalculated at each reload.
|
Important: Although the Hint Rules Table includes a column allowing multiple indexes to be used with each other, in Oracle only the bitmap index can be combined. This is because the Hint Rules Table was designed for core Content Server functionality.Therefore, it might not be sufficient for a system with components that create additional tables or add additional metadata fields, or both. However, the Hint Rules Table can be extended or overwritten by other components to provide knowledge of additional tables, indexes and fields. |
Explanation of First Hint Rule:
For this rule, if the WHERE clause contains the following condition the PK_Revisions index is used and added as a hint to the optimized query:
Revisions.dID = some_value
Explanation of Second Hint Rule:
For this rule, if the WHERE clause contains either of the following conditions the dDocName index is used and added as a hint to the optimized query:
Revisions.dDocName = some_value Revisions.dDocName LIKE 'some_value'
Explanation of Third Hint Rule:
For this rule, if the WHERE clause contains the following condition the condition does not meet the requirements and cannot be qualified:
dStatus = 'DONE'
However, if the WHERE clause contains the following condition the dStatus index is used and added as a hint to the optimized query.:
dStatus = 'RELEASED'
This section describes the following columns in the Hint Rules Table:
This column contains the unique name to identify the rule. A component can use the unique key to overwrite a particular rule. This key is usually identical to its index name because the index name is unique in the same database schema.
By default, Oracle uses a B+ Tree (binary tree) as the indexing structure to provide efficient access to logical records. B+ Tree indexes are most useful for queries involving a small number of result rows or when the user needs to execute queries using varying criteria (such as equality and range conditions). Because B+ Tree indexes store the indexed data values, these indexes are useful as sources of data if the requested value is the stored value.
However, bitmapped indexes offer substantial performance improvements with minimal storage cost compared to the default B+ Tree indexes. Bitmapped indexes are particularly effective for searching columns with poor selectivity due to having very few distinct values. Also, a bitmap is built for each value including the NULL value (which means the NULL is indexed). Overall, using bitmapped indexes is very efficient because the index lookup process is a bit-level operation and allows access to multiple indexes.
|
Note: Because hint rules can be overwritten, Oracle Query Optimizer does not allow you to add a hint rule using an existing key. Therefore, it is important when you are creating your bitmapped indexes for columns that you assign unique keys. |
Oracle recommends that you use bitmapped indexes for the table columns listed below, and set the index name to the corresponding column name.
Revisions table:
dIndexerState
dReleaseState
dProcessingState
dIsCheckedOut
dSecurityGroup
dStatus
WorkflowDocuments table:
dWfDocState
This column identifies the specific column within the database table listed in the Table column.
This column is a comma-delimited list of allowable operators. For more information about the valid operator options, see the Operators field and menu on the Hint Rules Configuration Page. The hint rule's operator is important in the decision of whether a hint rule will be applied to a condition.
For example, if the WHERE clause contains the following condition using the PK_Revisions index would be a very valuable hint to include in an optimized query:
Revisions.dID = 3
However, if the WHERE clause contains the following condition then using the PK_Revisions index would not be useful:
Revisions.dID > 3
This column identifies the specific index to use in the optimized query if the condition meets the hint rule requirements.
This column contains the preferred order to use when the rule is included in the Hint Rules Table. The highest ordered rules in a query are given precedence when deciding which hint to use.
The order values include:
5: This value indicates that the specified index is unique or does not match more than 50 rows for any value. For example, specifying dID with the Revisions, Documents, or DocMeta tables.
4: This value indicates that the specified index should be somewhat less selective. The specified value should typically match a few rows and, at the very most, several hundred rows. For example, specifying dDocTitle with the Revisions table.
3: This value indicates that the specified index matches less than a thousand rows. For example, specifying dInDate or dOutDate.
2: This value indicates that the specified index matches less than ten thousand rows.
1: This value indicates that the specified index matches more than ten thousand rows.
This column is Idoc scriptable. This column can only be defined when the Operators column value is one of the following:
in or notIn: When you use either of these operators, the value should be a comma-delimited list enclosed in parenthesis.
range: When you use this operator, the value must use one of the following formats:
Format 1:
([<lowValue>],range[,<highDateValue>])
Examples of acceptable values include:
('Y', 'O')
(,7d)
({ts '2004-12-11 12:03:23.000'}, 2d, <$dateCurrent()$>)
Format 2:
#[d|h]
For example, a range of five days is 5d and seven hours is 7h.
|
Tip: The operators in or notIn can substitute for the operators equal and notEqual, respectively, along with their matching values. For more information about operator options, see the Operators field and menu on the Edit Hint Rules Form. |
The following use cases demonstrate how this column provides additional flexibility to the hint rules:
Use Case 1: State or Status Table Columns
Table columns that indicate a state or status such as dReleaseState or dStatus are biased regarding the finished states. For example, dReleaseState is predisposed for 'Y' (released) or 'O' (old version). Likewise, dStatus is predisposed for RELEASED. Therefore, in WHERE clauses, conditions such as dReleaseState = Y or dStatus = RELEASED match the majority of rows in the Revisions table. Thus, indexes for these two columns are almost useless. Conversely, the condition dReleaseState = N (new, not yet indexed) matches only a few rows. Consequently, indexes on this column would be very helpful.
Use Case 2: Date or Number Table Columns
Table columns that indicate a date or number exhibit similar behavior to state or status. For example, the condition dInDate < <$dateCurrent()$> matches most of the table rows and makes indexes on this field irrelevant. However, the combined conditions dInDate < <$dateCurrent()$> AND dInDate > <$dateCurrent(-1)$> usually match only a small set of rows and would benefit from using the corresponding index as a hint.
This column indicates whether the defined index is used with other indexes. In Oracle, only the bitmap index can be combined.
This column indicates whether a hint rule has been disabled. Any rule in the table can be enabled/disabled. If you disable a hint rule, a value of 'Y' is displayed. Existing rules can be disabled to match the current Content Server state.
For example, if a Content Server instance contains only a few distinct content revClasses, each revClass may have thousands of revisions. Therefore, the dRevClass_2 index is not very effective. In this case, this corresponding hint rule should be disabled and you should add one or more new rules with different preference orders.
|
Note: Although any rule in the table can be enabled/disabled, only the rules that are added using the Edit Hint Rules Form can be removed. The default hint rules that are included with the Oracle Query Optimization feature can only be disabled; they cannot be removed. |
The Edit Hint Rules Form provides a way to add, remove, enable, or disable rules using the Hint Rules Configuration Page. You can add a new rule to reflect new tables and indexes. Existing rules can be removed or disabled to match the current state of Content Server. If you select a hint rule from the hint rule table, the Edit Hint Rules Form fields are automatically populated with the applicable values.
The Edit Hint Rules Form is displayed next to the hint rules configuration table on the Hint Rules Configuration Page.
The hint rules configuration table is scheduled to reload every night and whenever a new rule is added or an existing rule is modified. The hint value is recalculated at each reload.
Although any rule in the table can be enabled/disabled, only the rules that are added through the Edit Hint Rules Form can be removed. The default hint rules that are included with the Oracle Query Optimizer component can only be disabled; they cannot be removed.
Oracle Query Optimizer also contains a hint cache to store dynamically generated hints. For example, a hint derived from a parsed query or data source is cached to maintain persistence. In this way, the hint cache provides stability for queries and data sources.
The hint cache is used during the optimization process to select hints for queries that do not contain Oracle or Content Server hints. The hint cache provides a mechanism to fine tune query hints. In addition, administrator can check/edit cache and change hint for queries at run time.
The hint cache is stored to disk every two hours and is reloaded when the Oracle Content Server instance is started.
The characteristics of the hint cache include:
The same query matches the same cache entry regardless of its values unless the new value does not satisfy the hint rule conditions. Two examples are included below to demonstrate how the same hint cache entry can and cannot be used for multiple queries.
Example 1: Using Similar Hint Cache Entries
In the following two queries, the same hint cache entry is used because both queries match the hint rule requirements.
QueryA:
SELECT *
FROM Revisions
WHERE dDocName = 'name1'
QueryB:
SELECT *
FROM Revisions
WHERE dDocName = 'name2'
Example 2: Using Different Hint Cache Entries
In the following two queries, the same hint cache entry cannot be used because QueryB violates the requirements for the dReleaseState hint rule. The dReleaseState hint rule requires that the dReleaseState values are neither Y (released) nor O (old revision).
QueryA:
SELECT * FROM Revisions WHERE dReleaseState = 'U' AND dStatus = 'DONE'
QueryB:
SELECT * FROM Revisions WHERE dReleaseState = 'Y' AND dStatus = 'DONE'
In the hint cache, you can add a new entry, edit an existing entry, or remove an existing entry using the Hint Cache Updater Page. When adding or editing hint cache entries, you must use the Oracle Content Server Hint Syntax. The ability to manage the hint cache is very useful for fine tuning query hints. The example below demonstrates the benefits of fine tuning a hint cache entry.
Example: Batchloading Unindexed Content
If you have just batchloaded 100K content items into the Content Server and they are not yet indexed, the index-based query used above (Example 2: Using Different Hint Cache Entries) would match all of the batchloaded documents.
QueryA:
If most of the batchloaded documents have not been indexed, the dReleaseState index that is used in this query is not the best choice. For the best results in this case, you should fine tune the hint cache entry to use both the dReleaseState and the dStatus indexes. Use the Hint Cache Updater Page to update hint cache entries.
SELECT dID
FROM Revisions
WHERE Revisions.dReleaseState = N'N' AND Revisions.dStatus in (N'DONE', N'RELEASED', N'DELETED') AND Revisions.dInDate<={ts '2005-02-23 17:46:38.321'}
QueryB:
After updating the hint cache entry, the new optimized query is:
SELECT/*+ LEADING(revisions) INDEX (revisions dReleaseState dStatus)*/ dID
FROM Revisions
WHERE Revisions.dReleaseState = N'N' AND Revisions.dStatus in (N'DONE', N'RELEASED', N'DELETED') AND Revisions.dInDate<={ts '2005-02-23 17:46:38.321'}
By default, the hint cache has a maximum capacity of 1000 hints. The hint cache uses the midpoint insertion least-recently-used (LRU) algorithm which is similar to the one used by Oracle and mySQL. A new entry is inserted into the middle of the queue and each subsequent execution moves the entry up one spot.
When the number of hints in the cache exceed the maximum capacity, the entry at the bottom of the queue is removed from the cache. Thus, the LRU algorithm ensures that the most recently executed query hints are in the upper levels of the queue.
The hint cache key is generated from the normalized query; see Section 4.2.5.2.3, "Stage 3: Normalization." It consists of the qualified columns (columns that are qualified by table/alias names) and columns that have a hint rule defined. The cache key excludes conditions that contain joins or subqueries.
The following example illustrates how the cache key is generated from a given query:
SELECT DocMeta.*, Documents.*, Revisions.* FROM DocMeta, Documents, Revisions WHERE DocMeta.dID = Revisions.dID AND Revisions.dID=Documents.dID AND Revisions.dDocName='abc' AND Revisions.dStatus<>'DELETED' AND (Revisions.dReleaseState='U' OR Revisions.dReleaseState='I' OR Revisions.dReleaseState='Y') AND Documents.dIsPrimary<>0
The generated cache key is as follows:
documents.disprimary:notequal:documents|revisions.ddocname:equal:revisions|revisions.dreleasestate:in:revisions|revisions.dstatus:notequal:revisions
The following tasks are involved in using hint rules:
To access the Edit Hint Rules Form:
Open the Administration tray.
Click Oracle Query Optimizer, then Hint Rules Configuration.
The Hint Rules Configuration Page is displayed, including the Edit Hint Rules Form.
To add a new hint rule to the Hint Rules Table:
Open the Administration tray.
Click Oracle Query Optimizer, then Hint Rules Configuration.
In the Edit Hint Rules Form, complete the fields. For more detailed explanations of each field, see Section 4.2.5.7, "The Hint Rules Table" and the Section A.1.3.8, "Hint Rules Configuration Page."
Click the Add button.
The new hint rule is added to the Hint Rules Table and is effective immediately.
To edit an existing hint rule in the Hint Rules Table:
Open the Administration tray.
Click Oracle Query Optimizer, then Hint Rules Configuration.
Select the desired hint rule in the Hint Rules Table on the Hint Rules Configuration Page.
All of the applicable fields in the Edit Hint Rules Form are populated with the hint rule's values.
Edit the fields as desired. For more detailed explanations of each field, see Section 4.2.5.7, "The Hint Rules Table" and the Section A.1.3.8, "Hint Rules Configuration Page."
Change the key.
Click the Add button.
The Hint Rules Table is refreshed and the new hint rule is added. The modifications are effective immediately.
Delete the old hint rule.
Although any rule in the table can be enabled/disabled, only the rules that are added through the Hint Rules Configuration Page can be removed. The default hint rules that are included with the Oracle Query Optimization feature can only be disabled; they cannot be removed.
To disable a hint rule in the Hint Rules Table:
Open the Administration tray.
Click Oracle Query Optimizer, then Hint Rules Configuration.
Select the desired hint rule in the Hint Rules Table on the Hint Rules Configuration Page.
All of the applicable fields in the Edit Hint Rules Form are populated with the hint rule's values.
Click the Disable button.
The Hint Rules Table is refreshed and 'Y' is displayed in the Disabled column, indicating that the hint rule is deactivated.
Although any rule in the table can be enabled/disabled, only the rules that are added through the Hint Rules Configuration Page can be removed. The default hint rules that are included with the Oracle Query Optimization feature can only be disabled; they cannot be removed.
To enable a disabled hint rule in the Hint Rules Table:
Open the Administration tray.
Click Oracle Query Optimizer, then Hint Rules Configuration.
Select the desired hint rule in the Hint Rules Table on the Hint Rules Configuration Page.
All of the applicable fields in the Edit Hint Rules Form are populated with the hint rule's values.
Click the Enable button.
The Hint Rules Table is refreshed and the Disabled column is clear, indicating that the hint rule is reactivated.
Although any rule in the table can be enabled/disabled, only the rules that are added through the Hint Rules Configuration Page can be removed. The default hint rules that are included with the Oracle Query Optimization feature can only be disabled; they cannot be removed.
To delete a hint rule from the Hint Rules Table:
Open the Administration tray.
Click Oracle Query Optimizer, then Hint Rules Configuration.
Select the desired hint rule in the Hint Rules Table on the Hint Rules Configuration Page.
All of the applicable fields in the Edit Hint Rules Form are populated with the hint rule's values.
Ensure that the hint rule is enabled. If the hint rule is disabled it cannot be removed. To reactivate a disabled hint rule, see Section 4.2.5.11.4, "Enabling Hint Rules."
Click the Remove button.
The Hint Rules Table is refreshed and the selected hint rule is removed.
To access the Query Converter page, select Administration, then Oracle Query Optimizer, then Query Converter. The Query Converter Page is displayed.
The following tasks are involved when you use the Query Converter:
To convert a data source query.
If applicable, select Use Data Source.
The data source-related fields are displayed on the Query Converter page.
Select the desired data source from the DS Name menu.
The data source query is displayed in below the DS Name field.
Enter the applicable information for additional parameters and WHERE clauses.
Click Convert Query.
The data source is converted and the results are displayed in a text area above the Use Data Source checkbox. To view an example of a converted data source query, see Figure 4-4.
To convert a query:
If applicable, unselect Use Data Source.
The data source-related fields are hidden from the Query Converter page.
Enter the applicable information for the query.
Click Convert Query.
The query is converted and the results are displayed in a text area above the Use Data Source checkbox. To view an example of a converted query, see Figure 4-5.
Figure 4-4 Example of Converted Data Source Screen
Figure 4-5 Example of Converted Query Screen
After the data source or query is converted, the results are displayed above the Use Data Source checkbox. Because the conversion process clears the fields, the converted query can only be modified by entering new information in the fields. To edit information for a data source or query, see the applicable sections in Section 4.2.5.12.1, "Converting a Data Source."
The following tasks are involved when updating the hint cache:
To access the Hint Cache Updater page, select Administration, then Oracle Query Optimizer, then click Hint Cache Updater.
To check the hint cache using a data source:
On the Hint Cache Update page, select Use Data Source.
The data source-related fields are displayed on the Hint Cache Updater page.
Select the desired data source from the DS Name menu.
The data source query is displayed in below the DS Name field.
Enter the applicable information for the additional parameters, WHERE clause, and hints.
Click Check Cache.
The results are displayed above the Use Data Source checkbox. To view an example of an unsuccessful hint search, see Figure 4-6.
Figure 4-6 Example of Hint Cache Updater Results with Data Source
To check the hint cache using a query:
On the Hint Cache Update page, ensure the Use Data Source checkbox is unselected.
The data source-related fields are hidden from the Query Converter page.
Enter the applicable information.
Click Check Cache.
The results are displayed above the Use Data Source checkbox. To view an example of an unsuccessful hint search, see Figure 4-7. To view an example of a successful hint search, see Figure 4-8.
Figure 4-7 Example of Hint Cache Updater Results without Data Source
To modify a hint cache query using a data source:
On the Hint Cache Updater page, select Use Data Source.
The data source-related fields are displayed on the Hint Cache Updater page.
Select the desired data source from the DS Name menu.
The data source query is displayed in below the DS Name field.
Enter the applicable information for the additional parameters, WHERE clause, and hints.
Click Update Cache to overwrite the previous hint cache.
The results are displayed in a text box above the Use Data Source checkbox. To see an example of successfully adding a new hint to a query and updating the hint cache, see the screen capture included in this section.
To modify a hint cache using a query:
On the Hint Cache Page, ensure that the Use Data Source checkbox is unselected.
The data source-related fields are hidden from the Query Converter page.
Enter the applicable information.
Click Update Cache to overwrite the previous hint cache.
The results are displayed above the Use Data Source checkbox. In the screen capture note that the new hint was added and the hint cache was updated.
Figure 4-9 New hint added, hint cache updated
To remove a hint cache data source entry:
On the Hint Cache Updater page, select Use Data Source.
The data source-related fields are displayed on the Hint Cache Updater page.
Select the desired data source from the DS Name menu.
The data source query is displayed below the DS Name field.
Enter the applicable information for the additional parameters, WHERE clause, and hints.
Click Remove.
The information entered into the fields is removed. To see an example of successfully removing a hint from a query and the hint cache, see the screen capture included in this section.
To remove a hint cache query:
On the Hint Cache Updater page, ensure that the Use Data Source checkbox is unselected.
The data source-related fields are hidden from the Query Converter page.
Enter the applicable information for the query and hints.
Click Remove.
The results are displayed above the Use Data Source checkbox. In the screen capture note that the previously added hint was deleted from the query and hint cache.
Figure 4-10 Example of a deleted hint from cache
This section contains the following topics:
With the release of version 11gR1, the Oracle Content Server system implemented a file store system for data management, replacing the traditional file system for storing and organizing content. The FileStoreProvider component is installed (enabled) by default with Oracle Content Server deployment. FileStoreProvider software exposes the file store functionality in the Oracle Content Server interface and allows additional configuration options. For example, you can configure the Oracle Content Server instance to use binary large object (BLOB) data types to store content in a database, instead of using a file system. This functionality offers several advantages:
Integrates repository management with database management for consistent backup and monitoring processes.
Helps overcome limitations associated with directory structure and number of files per directory in a file system approach.
Aids in distributing content more easily across systems, for better scaling of the Oracle Content Server system.
Allows for different types of storage devices not commonly associated with a file system, for example, content addressed storage systems and write-only devices necessary in some business uses.
|
Caution: The FileStoreProvider component is installed and enabled by default during Oracle Content Server deployment. It should not be uninstalled or disabled after the default file store is upgraded. If you have not yet upgraded the default file store, you can disable the component following the procedure in Section 6.3.3.3, "Enabling and Disabling a Component." |
This section covers the following topics:
The Oracle Content Server system manages content by tracking the storage of electronic files and their associated metadata. It provides the ability for users to store and access their checked in files, any associated information, and any associated renditions. This section discusses the data management methods historically used by the Oracle Content Server system and how they are addressed with the FileStoreProvider component.
The first half of data management is storing electronic files checked into an Oracle Content Server repository. With the Oracle Content Server system, file storage has typically been done with a traditional file system, storing electronic files in a hierarchical directory structure that includes vault and weblayout directories. By using the revision information specified by the content type, security group and account (if used), files and their associated renditions are placed into particular directories within the vault and weblayout directories. For example, the primary and alternate files specified at check in are stored in subdirectories in the vault directory. The specific file location is defined to be the following:
IntradocDir/vault/dDocType/account/dID.dExtension
In this path name, dDocType is the content type chosen by the user on check in, dID is the unique system-generated identification that identifies this revision, and dExtension is the extension of the file checked in. In this hierarchical model, the system uses the dDocType metadata field to distribute the files within the hierarchy established in the vault directory. Similarly, any web rendition is distributed across the hierarchy within the IntradocDir/weblayout/groups directory. The web rendition is the file served out of a web server, and in the historical file system storage method, could be the native file, the alternate file, or a web-viewable file generated by Inbound Refinery or some other conversion application.
This straightforward determination of file storage location is helpful to component and feature writers, helping them understand where files are located and how to manipulate them. However, it also has the effect of limiting storage management. Without careful management of the location metadata, directories can become saturated, causing the system to slow down.
The second half of data management is storing metadata associated with an electronic file. With the Oracle Content Server system, metadata management has typically been done using a relational database, primarily involving three database tables. Metadata enables users to catalogue content and provides a means for creating file descriptors to facilitate finding it within the Oracle Content Server repository. For users, the retrieval is done by the Oracle Content Server software, and how and where the file is stored can be completely hidden. For component and feature writers, who may need to generate or manipulate files, the metadata provides a robust means of access.
The traditional file system model historically used by the Oracle Content Server system limits scalability. As data management needs grow, adding extra storage devices to increase storage space is not conducive to easy file sharing through a web-based interface. Complex, nested file structures could slow performance. Suppressing the creation of a duplicate web-viewable file when the native file format could be used could be difficult. As a consequence of dealing with large systems, for example over 100 million content items, the Oracle Content Server system has shifted to using a file store. This offers the advantages of scalability, flexibility, and manageability.
The FileStoreProvider component enables you to define data-driven rules to store and access content managed by the Oracle Content Server system. FileStoreProvider offers the following features:
The ability to relocate files easily.
The ability to have the web-viewable file be optional.
The ability to manage and control directory saturation.
The ability to integrate with third-party storage devices.
An API to use, extend, and enhance different storage paradigms.
With FileStoreProvider, checked-in content and associated metadata are examined and assigned a storage rule based on criteria established by a system administrator. Criteria can include metadata, profiles, or other considerations. The storage rule determines how vault and web files are stored by the Oracle Content Server system and how they are accessed by a web server.
A file store for data management is used in the Oracle Content Server system instead of the traditional file system for storing and organizing content. The FileStoreProvider component automatically upgrades the default file store to make use of functionality exposed by the component, including modifying the web, vault and web URL path expressions.
|
Note: Partitions are not required to run the Oracle Content Server system, but any attempt to check in content before creating a partition, changing the vault path root, or creating a new, well-formed storage rule will fail. For more information, see Section 4.3.2.3, "Understanding FileStoreProvider Storage Principles", including the sections on storage rules and path construction. |
|
Note: Oracle WebLogic Server does not support configuring its web server for the Oracle Content Server instance to add a new virtual directory and alias to point to the weblayout directory for each partition that is created. Partitions can be used for the vault files, and partitions are supported for web files. |
|
Caution: Resource files should not be edited directly. Proper modification of resource files should be done within the Oracle Content Server user interface or through additional component development. For more information on component development, see Chapter 6, "Working With Components". |
Three other resource tables are used to define and handle file paths. The defaults for the PathMetaData Table and PathConstruction Table cover most scenarios. The StorageRules Table stores the values specified when a storage rule is defined. These three tables are provider-specific, and as such are defined in the provider.hda file of the defaultfilestore directory. The defaultfilestore directory is located in the IntradocDir/data/providers directory. A fourth table, the FileSystemFileStoreAlgorithmFilters Table requires a component along with Java code to modify.
This section covers the following topics:
Section 4.3.2.1, "Using Standard Oracle Content Server Variables"
Section 4.3.2.3, "Understanding FileStoreProvider Storage Principles"
The FileStoreProvider component makes several modifications to the Oracle Content Server database, Oracle Content Server metadata fields, and other configuration files, allowing for possible configuration options.
This section covers the following topics:
In some situations, content stored in a database may have to be forced onto a file system. One example would be when Inbound Refinery must have access to a file for conversion. Files forced onto a file system are considered temporary cache. The following configuration values are used to control when the temporarily cached files are to be cleaned up. Note that the system only cleans up files that have an entry in the FileCache Table.
FileStoreProvider adds several Oracle Content Server metadata fields and makes additional options available for use in configuration files.
This section covers the following topics:
Configuring Added Metadata Fields
FileStoreProvider adds three metadata fields to the Oracle Content Server instance:
xPartitionId: This metadata field is used in conjunction with the PartitionList table to determine the root location of the content item files. It is recommended that this field be hidden on the user interface, because the partition selection algorithm provides a value.
xWebFlag: This metadata field is used to determine whether a content item has a web-viewable file. Consequently, if the system has content items that have only vault files, then removing this metadata field causes the system to expect the presence of a web-viewable and may cause harm to the system. The metadata field can be specified by the configuration value WebFlagColumn.
xStorageRule: This metadata field is used to track the rule that was used to determine how the file is to be stored. The metadata field may be specified by the configuration value StorageRuleField.
|
Note: These metadata fields are added by FileStoreProvider on startup, and if deleted, are added again when the Oracle Content Server instance restarts. If the metadata fields must be permanently deleted, set the configuration variableFsAddExtraMetaFields=false in the intradoc.cfg file to disable the automatic creation of the fields. The intradoc.cfg file is located in the DomainHome/ucm/cs/bin directory. |
Setting the Default Storage Directory
A StorageDir parameter can be set equal to a root directory, used for all partitions where the PartitionRoot column value has not been specified. In this case the storage directory and the partition name is used to create the PartitionRoot parameter. The StorageDir parameter is set in the intradoc.cfg file, located in the DomainHome/ucm/cs/bin directory.
Standard FileStoreProvider Variables
In the provider.hda located in the IntradocDir/data/providers/defaultfilestore directory, the following parameters and classes are standard for a file system store:
ProviderType=FileStore ProviderClass=intradoc.filestore.BaseFileStore IsPrimaryFileStore=true # Configuration information specific to a file system store provider. ProviderConfig=intradoc.filestore.filesystem.FileSystemProviderConfig EventImplementor=intradoc.filestore.filesystem.FileSystemEventImplementor DescriptorImplementor=intradoc.filestore.filesystem.FileSystemDescriptorImplementor AccessImplementor=intradoc.filestore.filesystem.FileSystemAccessImplementor
When the FileStoreProvider default file store is upgraded, checked-in content and associated metadata are examined and assigned a storage rule based on criteria established by the system administrator. Criteria can include metadata, profiles, or other considerations. The storage rule determines how vault and web files are stored and accessed by Oracle Content Server software and how they are accessed by a web server. Files can be stored in a database or placed on one or more file systems or storage media. Partitions can be created to help manage storage location, but are not required.
|
Caution: The FileStoreProvider component should not be disabled once it has been used with the Oracle Content Server system. |
This section covers the following topics:
You can create partitions to define additional root paths to files managed by the Oracle Content Server system but requiring storage in different locations or on different types of media. You create partitions using the Partition Listing Page. When a new partition is created, the Oracle Content Server system modifies the PartitionList resource table in the fsconfig.hda file, located in the IntradocDir/data/filestore/config/ directory.
|
Note: Oracle WebLogic Server does not support configuring its web server for the Oracle Content Server instance to add a new virtual directory and alias to point to the weblayout directory for each partition that is created. Partitions can be used for the vault files, and partitions are supported for web files. |
To add a partition to the Oracle Content Server instance, perform these steps:
Log in to the Oracle Content Server instance as system administrator.
Open the Administration tray and click File Store Administration.
If there are no partitions defined, click Add Partition. Otherwise, the Add/Edit Partition Page is displayed.
Enter a partition name. The name must be unique.
Modify the partition root, duplication methods, and any other pertinent parameters. See Add/Edit Partition Page for more information.
Ensure that Is Active is enabled.
Click Update. The Partition Listing Page is displayed.
You can edit the DefaultFileStore provider at any time. To edit the provider, perform these steps:
Log in to the Oracle Content Server instance as system administrator.
Open the Administration tray and select Providers. The Providers Page is displayed.
Click Info in the Action column next to the DefaultFileStore provider. The File Store Provider Information Page is displayed.
Click Edit. The Edit File Store Provider Page is displayed.
Make the necessary modifications and click Update to submit the changes. The Providers Page is displayed.
|
Note: Do not navigate away from the Edit File Store page before clicking Update to submit the change. |
Restart the Oracle Content Server instance.
You can add multiple storage rules to the file store.
|
Important: Storage rules cannot be deleted. Carefully consider each storage rule before you create it. |
|
Caution: Changing a storage rule after content has been checked in to a Oracle Content Server repository may cause the Oracle Content Server system to lose track of the content. |
To add or edit storage rules, perform these steps:
Log in to the Oracle Content Server instance as a system administrator.
Open the Administration tray, and select Providers. The Providers Page is displayed.
Click Info in the Action column next to the DefaultFileStore provider. The File Store Provider Information Page is displayed.
Click Edit. The Edit File Store Provider Page is displayed.
Click Add new rule, or select the name of the rule to edit from the Storage choice list, and click Edit rule. The Storage Rule Name Dialog is displayed.
Make the necessary modifications to the storage rule, and click OK. The Edit File Store Provider Page is displayed.
|
Note: If there are records associated with the storage rule being edited, then the following rules can not be modified:FsWeblayoutDir (the weblayout directory) and FsHttpWebRoot (the HttpWebRoot and URL prefix). |
Click Update. The Providers Page is displayed.
|
Important: If the web root used in the web URL file path defined in the storage rule is something other than the default weblayout directory defined for the Oracle Content Server system, you must add an alias or virtual directory in your web server for the web root used in the storage rule. Otherwise, the Oracle Content Server system does not know where to access the file. For information on adding virtual directories to your web server, see the documentation that came with your web server. |
When a content item is checked in to the Oracle Content Server system, it consists of metadata, a primary file selected by the user, and potentially an alternate file. The alternate file may also be selected and checked in by the user, and is presumed to be a web-viewable file. In a file system approach to the Oracle Content Server system, the primary file is stored in the vault directory at the root of the DomainHome directory and is called the native file. If an alternate file is checked in, it is also stored in the vault, but is copied to the weblayout directory or passed to a conversion application, such as Inbound Refinery. If no alternate file is checked in, then the native file is copied from the vault directory to the weblayout directory, existing in two places. If no alternate file is checked in and Inbound Refinery is installed, a rendition of the native file could be created and stored in weblayout directory.
In a file system approach to the Oracle Content Server system, storing content in specified directories defines a path to the content. You can access content from a browser by using a static web URL file path, when you know the content is in a specific location, or using a dynamic Oracle Content Server service request, such as GET_FILE, when you do not. With FileStoreProvider, content may or may not be stored in a file system. Consequently, a new approach to defining paths to the content must be taken.
Depending on how you set up FileStoreProvider, you may or may not have a static web URL. By using a dynamic Oracle Content Server service request, you can access content when you do not know the specific location. With FileStoreProvider, the static web URL is defined as the web URL file, and the dynamic access is simply called the web URL. Using the FileStoreProvider user interface, you can configure only the static web URL file path. However, you can decide to have the static web URL done as an Oracle Content Server service request, essentially making it dynamic.
This section covers the following topics:
Section 4.3.2.3.1, "Using Storage Rules on Renditions to Determine Storage Class"
Section 4.3.2.3.2, "Understanding Path Construction and URL Parsing"
When content is checked in, all versions of the content managed by the Oracle Content Server system are considered renditions. These renditions include the native file, web-viewable file, and any other files that may have been rendered by Inbound Refinery or third-party conversion applications.
Renditions are grouped together into a storage class, which determines where and how a rendition is accessed. Storage classes are grouped together into a storage rule, which defines the vault, web, and web URL path expressions, through a storage class. Additionally, a storage rule determines if a rendition is not stored, as in a web-less file store, or if it is stored in a different device, such as a database rather than a file system.
The following examples illustrate how storage rules can determine where and how different content items can be stored.
Example 1
A storage rule is defined as File system only on the Storage Rule Name Dialog and Is Webless File Store is selected. In this scenario, the system makes a copy of the primary files and places them in the weblayout directory.
This traditional file system storage example typically offers the advantage of faster access time to content when compared with database storage. This advantage diminishes if the file system hierarchy is complex or becomes saturated, or as the quantity of content items increases.
Example 2
A storage rule is defined as File system only on the Storage Rule Name Dialog and Is Webless File Store is selected. In this scenario, no copy is made of the primary files and so the native files are the only renditions. Requests for web-viewable files are routed to the native files stored in the vault.
|
Note: The web-less option of FileStoreProvider can specify that no web rendition be created. When this is used in conjunction with Inbound Refinery, a web rendition is always created and stored in either the file system or the database, depending on the storage rule in effect. |
This traditional file system storage example, like the previous one, offers the advantage of faster access time to content. It also saves on storage space by not copying a version of the content from the vault directory to the weblayout directory. Instead, it redirects web-viewable access to the content in the vault directory. This is useful if most of the native files checked in are in a web-viewable format, or if the Oracle Content Server system is being used to manage content that is not required to be viewed in a browser.
Example 3
A storage rule is defined as JDBC Storage on the Storage Rule Name Dialog and no selection is made from the Renditions choice list. In this scenario, both the vault and web files are stored in the database.
This database storage example offers the advantage of integrating repository management with database management for consistent backup and monitoring processes, and helps overcome limitations associated with directory structure and number of files per directory in a file system approach.
|
Important: When necessary, content items stored in a database can be forced onto the file system, for example, during indexing or conversion. The files on the file system are treated as temporary cache and deleted following the parameters specified in the config.cfg file located in the IntradocDir/config directory. For more information on the parameters used, see Section 4.3.3.7, "FileCache Table." |
Example 4
A storage rule is defined as JDBC Storage on the Storage Rule Name Dialog and Web Files is selected from the Renditions choice list. In this scenario, the vault files are stored in the database and the web files are permanently stored on the file system.
This mixed approach of storing native files in a database but web-viewable files on a file system offers the advantages of database storage in the previous example (integrated backup and monitoring, overcoming file system limitations) for the native files, while providing speedy web access to web-viewable renditions. Like the first example, this advantage can be diminished if the file system structure is overly complex, or the quantity of files is extreme.
The path to content stored in the Oracle Content Server system is defined in the PathExpression column of the PathConstruction Table. Paths are made up of pieces, with each piece separated by a slash (/). Each piece can be made of a static string or a sequence of dynamic parts. A dynamic part is encapsulated by a dollar sign ($). A part can be calculated using an algorithm, Idoc Script variable, environment variable, or a metadata lookup, and can have the following interpretations:
It can be a field defined in the PathMetaData table. If it is defined in the PathMetaData table, it can be mapped to an algorithm, for example, $dDocType$.
If it has the prefix #env., it is an environment variable, for example, $#env.VaultDir$ or $#env.WeblayoutDir$.
It can be an Idoc Script variable, for example, $HttpWebRoot$.
For example, the standard vault location is defined as
$PartitionRoot$/vault/$dDocType$/$dDocAccount$/$dID$$ExtensionSeparator$$dExtension$
When parsed, the path expression turns into five pieces, interpreted according to the rules specified in the PathMetaData table, as follows:
$PartitionRoot$: mapped to the partitionSelection algorithm and uses the xPartitionId as a lookup into the PartitionList table to determine the partition root
/vault/: a string, so no calculation or substitution
$dDocType$: by the PathMetaData table this is a look up in the file parameters
$dDocAccount$: this is mapped to a documentAccount algorithm which takes dDocAccount and parses it into the standard Oracle Content Server account presentation with all the appropriate delimiters
$dID$$ExtensionSeparator$$dExtension$: this piece has three parts:
$dID$: similar to dDocType, this is defined in the file parameters and is a required field
$ExtensionSeparator$: determined by an algorithm and by default it returns '.'
$dExtension$: similar to dDocType
In the standard configuration for the web-viewable path, the URL contains variables to add the partition root to the web-viewable path, security, dDocType, and dispersion information, as well as the dDocName, rendition, and extension information. FsWeblayoutDir denotes $#env.WeblayoutDir$ by default.
$FsWeblayoutDir$groups/$dSecurityGroup$/$dDocAccount$/documents/$dDocType$/$dispersion$/~edisp/$dDocName$$RenditionSpecifier$$RevisionLabel$$ExtensionSeparator$$dWebExtension$
In the standard configuration for the web URL file path, the URL contains variables to add the partition root to the web-viewable path, security, dDocType, and dispersion information, as well as the dDocName, rendition, and extension information. FsHttpWebRoot denotes $HttpWebRoot$ by default.
$FsHttpWebRoot$groups/$dSecurityGroup$/$dDocAccount$/documents/$dDocType$/$dispersion$/~edisp/$dDocName$$RenditionSpecifier$$RevisionLabel$$ExtensionSeparator$$dWebExtension$
The groups separator indicates to the Oracle Content Server system that the directories that follow are the name of the security group and account to which the content item belongs. Accounts are optional and consequently computed by an algorithm. After the security information is the documents separator, which is immediately followed by the dDocType. Dispersion is optional. The last part of the URL is the dDocName, its rendition and revision information, and its format extension.
Because the URL is expected in this format, the Oracle Content Server system can successfully extract metadata from it. More importantly, it can determine the security information for the content item and derive the access privileges for a particular user.
The parsing guidelines have been expanded to allow for dispersion in the web directory. When $dRevClass$ is encountered, the system processes the dispersion information, then continues with dDocName and dWebExtension as before. This means that the system can now successfully parse URLs of the form:
../groups/$dSecurityGroup$/$dDocAccount$/documents/$dDocType$/$dispersion$/~edisp/$dDocName$$RenditionSpecifier$$RevisionLabel$$ExtensionSeparator$$dWebExtension$
This section covers the following topics:
The PartitionList table defines the partitions that are available for the partitionSelection algorithm. The table is defined in the fsconfig.hda file, located in the DomainHome/ucm/cs/data/filestore/config/ directory, and modified using the Add/Edit Partition Page in the Oracle Content Server user interface. The columns of the table are used as follows:
The StorageRules table defines the rules used for storing content items. The rule specifies which path expression to use for which storage class, and how content items are to be stored.
The table is defined in the provider.hda file, located in the DomainHome/ucm/cs/data/providers/defaultfilestore directory, and it can be modified using the Storage Rule Name Dialog in the Oracle Content Server user interface. The columns of the table are used as follows:
The PathMetaData table defines what metadata is used to determine the location of a file. The metadata may come directly from a content item's metadata, or be calculated using an algorithm. The PathMetaData table is defined in the provider.hda file of the defaultfilestore directory. The defaultfilestore directory is located in the DomainHome/ucm/cs/data/providers/ directory.
The columns of the table are used as follows:
The PathConstruction table maps a file to a path. The PathConstruction table is defined in the provider.hda file of the defaultfilestore directory. The defaultfilestore directory is located in the DomainHome/ucm/cs/data/providers/ directory. For more information, see also Section 4.3.2.3.2, "Understanding Path Construction and URL Parsing."
|
Caution: The defaults provided in the PathConstruction table should work for most scenarios. This resource file should not be edited directly. Proper modification should be done through additional component development. For more information on component development, see the chapter about components in the Oracle Fusion Middleware Developer's Guide for Oracle Universal Content Management. |
The columns of the PathConstruction table are defined as follows:
The FileSystemFileStoreAlgorithmFilters table is used to map an algorithm name to an implementation of the FilterImplementor interface. The algorithm can be referenced in the PathMetaData Table and is used to calculate the desired path field. The class implementing the algorithm must return the required metadata fields it uses for calculation, when the file parameters object is null. Through the ExecutionContext, the doFilter method is passed in information about the field, content item, and file store provider that initiated the call. In particular, for the file system provider, the algorithm will be passed the following information through the ExecutionContext. Bear in mind that other file store providers may choose to pass in more or possibly different information.
Properties fieldProperties = (Properties)
context.getCachedObject("FieldProperties");
Parameters data = (Parameters)
context.getCachedObject("FileParameters");
Map localData = (Map) context.getCachedObject("LocalProperties");
String algorithm = (String) context.getCachedObject("AlgorithmName");
The FileSystemFileStoreAlgorithmFilters table is part of FileStoreProvider and requires a component along with Java code to modify.
|
Caution: The defaults provided in the FileSystemFileStoreAlgorithmFilters table should work for most scenarios. This resource file should not be edited directly. Proper modification should be done with Java code and through additional component development. For more information on component development, see Oracle Fusion Middleware Developer's Guide for Oracle Universal Content Management. |
The FileStorage table is added to the Oracle Content Server system when FileStoreProvider is installed. It is used exclusively by the JdbcStorage storage type, when content is stored in a database. The FileStorage table contains the renditions of content items and uses the dID of the content item and rendition to uniquely identify what renditions belong to which content item.
The FileCache table is added to the Oracle Content Server system when FileStoreProvider is installed. It is used exclusively by the JdbcStorage storage type to remember which renditions have been placed on a file system. Renditions stored in a database are placed on a file system when required for a specific event, for example indexing or conversion. These files are often temporary and deleted after a specified interval as part of a scheduled event.
This section list the contents of the tables contained in the provider definition file (provider.hda) for each of the examples. The provider.hda file does not need to be edited manually. Proper modification of the provider.hda file should be done within the Oracle Content Server user interface using the Add/Edit Partition Page, or through additional component development. The provided default options for other resource tables, such as PathMetaData Table, PathConstruction Table, and FileSystemFileStoreAlgorithmFilters Table, should have sufficient flexibility for most scenarios.
This section covers the following topics:
In most of the examples, the following PathMetaData Table configuration definitions are used. The table has been trimmed of some it columns not pertinent to the examples for clarity.
@ResultSet PathMetaData
6
FieldName
GenerationAlgorithm
RequiredForStorage
<trimmed columns>
dID
#all
dDocName
#all
dDocAccount
documentAccount
dDocType
#all
dExtension
#all
dWebExtension
weburl
dSecurityGroup
#all
dRevisionID
#all
dReleaseState
#all
dStatus
web
xPartitionId
partitionSelection
ExtensionSeparator
extensionSeparator
xWebFlag
RenditionId
#all
RevisionLabel
revisionLabel
RenditionSpecifier
renditionSpecifier
@end
FileStoreProvider can be configured to place content on a file system in the standard Oracle Content Server locations.
The first step is to define the storage rule. In this case, the storage rule will be of type FileStorage, because all content is to be stored on the file system.
Example:
@ResultSet StorageRules 4 StorageRule StorageType IsWeblessStore RenditionsOnFileSystem default FileStorage @end@
The second step is to define the path construction for each of the storage classes for the rule. In general, the last part of the path should be standard for all usage examples. If not, then the Oracle Content Server system does not work well with hcs* files. However, the root path can be changed without affecting functionality, assuming that changing the web URL file path root is properly acknowledged by the web server as a Oracle Content Server web root.
In this configuration, the vault, web, and web URL storage classes need to be defined in the PathConstruction Table. The path expression for the vault has already been discussed in Section 4.3.2.3.2, "Understanding Path Construction and URL Parsing." $dispersion$ implements dispersion of content on the file system. The caller can provide this dispersion on the storage rule page.
This setup only looks at the web path expression, which differs from the web URL only in its root. In other words, the web path is an absolute path on the file system, while the web URL is a URL served up by a web server.
Example:
@ResultSet PathConstruction
4
FileStore
PathExpression
AutoCreateLimit
IsWritable
StorageRule
vault
$#env.VaultDir$$dDocType$/$dDocAccount$/$dispersion$/$dID$$ExtensionSeparator$
$dExtension$
6
true
default
weburl
$FsHttpWebRoot$groups/$dSecurityGroup$/$dDocAccount$/documents/$dDocType$/
$dispersion$/~edisp/$dDocName$$RenditionSpecifier$$RevisionLabel$
$ExtensionSeparator$$dWebExtension$
3
false
default
web
$FsWeblayoutDir$groups/$dSecurityGroup$/$dDocAccount$/documents/$dDocType$/
$dispersion$/~edisp/$dDocName$$RenditionSpecifier$$RevisionLabel$
$ExtensionSeparator$$dWebExtension$
3
true
default
@end
The web path construction is defined to be:
$FsWeblayoutDir$groups/$dSecurityGroup$/$dDocAccount$/documents/$dDocType$/ $dispersion$/~edisp/$dDocName$$RenditionSpecifier$$RevisionLabel$ $ExtensionSeparator$$dWebExtension$
This is parsed into its parts as follows:
In this example, the previous example storage rule is configured to have IsWeblessStore set to true and consequently the web-viewable file will not be created by default. However, if the document is processed through Inbound Refinery or WebForms or any other component that requires a web-viewable, the web file will be created. The location of the files is as above in the standard configuration. However, because a file might not have a web rendition, the web URL path must be adjusted. Also, note the use of weburl.file. This is used to compute the URL when the web-viewable actually exists. The metadata field xWebFlag is used to determine how the file is to be served up in the browser.
@ResultSet StorageRules 4 StorageRule StorageType IsWeblessStore RenditionsOnFileSystem default FileStorage true @end@
@ResultSet PathConstruction
4
FileStore
PathExpression
AutoCreateLimit
IsWritable
vault
$#env.VaultDir$$dDocType$/$dDocAccount$/$dispersion$/$dID$$ExtensionSeparator$
$dExtension$
6
true
default
weburl
$HttpCgiPath$?IdcService=GET_FILE&dID=$dRevClassID$
&dDocName=$dDocName$&allowInterrupt=1&noSaveAs=1&fileName=$dOriginalName$
3
false
default
weburl.file
$FsHttpWebRoot$groups/$dSecurityGroup$/$dDocAccount$/documents/$dDocType$/
$dispersion$/~edisp/$dDocName$$RenditionSpecifier$$RevisionLabel$
$ExtensionSeparator$$dWebExtension$
3
false
default
web
$FsWeblayoutDir$groups/$dSecurityGroup$/$dDocAccount$/documents/$dDocType$/
$dispersion$/~edisp/$dDocName$$RenditionSpecifier$$RevisionLabel$
$ExtensionSeparator$$dWebExtension$
3
true
default
@end
To store files in the database, you need a storage rule that is of type JdbcStorage. By default, all content items belonging to this rule have their files stored in the database. However, even though the files are stored in the database, there is the presumption of an underlying file system and the system may need to temporarily cache a file on the file system. In particular, this may happen for indexing or for some conversions.
|
Tech Tip: A rule can be configured to always store renditions belonging to a given storage class on the file system. This is most useful for systems that store vault files in the database, but web files on the file system. |
In the default rule below, all files are stored in the database, while the filesInWeb rule stores the vault files in the database and the web files on the file system.
@ResultSet StorageRules 4 StorageRule StorageType IsWeblessStore RenditionsOnFileSystem default JdbcStorage filesInWeb JdbcStorage web @end@
@ResultSet PathConstruction
4
FileStore
PathExpression
AutoCreateLimit
IsWritable
StorageRule
vault
$#env.VaultDir$$dDocType$/$dDocAccount$/$dispersion$/$dID$$ExtensionSeparator$
$dExtension$
6
true
default
weburl.file
$FsHttpWebRoot$groups/$dSecurityGroup$/$dDocAccount$/documents/$dDocType$/
$dispersion$/~edisp/$dDocName$$RenditionSpecifier$$RevisionLabel$
$ExtensionSeparator$$dWebExtension$
3
false
default
web
$FsWeblayoutDir$groups/$dSecurityGroup$/$dDocAccount$/documents/$dDocType$/
$dispersion$/~edisp/$dDocName$$RevisionLabel$$RenditionSpecifier$
$ExtensionSeparator$$dWebExtension$
3
true
default
@end
The previous examples have kept the file paths consistent with the standard configuration. For very large implementations, this can result in directory saturation and slow performance. The following examples aid in dispersing files over several storage options.
FileStoreProvider makes it easy to use partitions to create a sparser directory structure. By default, the xPartitionId metadata field is used and becomes a part of a content item revision's metadata information. It is recommended that this field is disabled on the Oracle Content Server user interface, instead letting the partition selection algorithm determine the partition to use. The partition selection algorithm looks at all the active partitions, and as a new content enters the system, the partitions are selected in order. Each partition has an entry in the PartitionList Table and can be declared active. The PartitionRoot is calculated from xPartitionId, where the value is a look up key into the PartitionList table. If no xPartitionId is specified, the system finds the next available and active partition and uses this value for the location calculation. The xPartitionId is then stored as part of the content item's metadata.
To use the partition selection, define the vault storage class in the PathConstruction table as follows:
vault $PartitionRoot$/$dDocType$/$dDocAccount$/$dRevClassID$$ExtensionSeparator$$dExtension$ 6 true
Partitions can be deactivated using the "Add/Edit Partition Page" at any time if a system administrator needs to close a partition to contribution, for example if maintenance is required on the storage device.
This example shows how to partition both vault and weblayout directories, and also maintain valid web URL file paths.
Add the partition root to the web-viewable path and web URL file path, and edit the variables $FsWeblayoutDir$ and $FsHttpWebRoot$ on the Storage Rule Name Dialog.
$FsWeblayoutDir$ represents $PartitionRoot$/weblayout. $FsHttpWebRoot$ represents $HttpWebRoot$/$xPartitionId$/weblayout/.
Define partitionRoot in the Add/Edit Partition Page as follows:
| Partition Name | Partition Root |
|---|---|
partition1 |
$#env.WeblayoutDir$/partition1/ |
partition2 |
$#env.WeblayoutDir$/partition2/ |
In order to keep the web URL file path consistent with the web-viewable path in the weblayout directory, the variable xPartitionId is used so that partition1 or partition2 is correctly replaced when creating the web URL file path.
Ensure that the web-viewable path and the web URL file path evaluate into the same path.
$FsWeblayoutDir$ represents $PartitionRoot$/weblayout/. For partition1 this evaluates to $#env.WeblayoutDir$/partition1/weblayout/. For partition2 this evaluates to $#env.WeblayoutDir$/partition2/weblayout/.
$FsHttpWebRoot$ represents $HttpWebRoot$/$xPartitionId$/weblayout/. For partition1 this evaluates to $HttpWebRoot$/partition1/weblayout/. For partition2 this evaluates to $HttpWebRoot$/partition2/weblayout/.
If you set up the partitions (partition1 and partition2) to use the partition root of $#env.VaultDir$/partition1 and $#env.VaultDir$/partition2 instead of the $#env.WeblayoutDir$ and $HttpWebRoot$ settings, then the weblayout file will end up stored in the vault directory. It then can be used only for partitioning the vault files.
Another way of dispersing files is to alter the path so that files get partitioned out by the dRevClassID of the content item. In the example below, the directories are limited to 10,000 files plus extra files for additional renditions.
If your path expression contains $RevClassID[-12:-10:0]/$dRevClassID[-10:-8:0]$/$dRevClassID[-8:-4:0]$ and $dRevClassID is 1234567890, the result is 00/12/3456.
Note the $dRevClassID[-12:-10:0] in the path expression. This is interpreted as follows:
Get the characters starting at 12 back from the end of the string until you get the character 10 back from the end of the string.
Pad the resulting string to length 2, which 12-10, with 0 characters.
An Oracle Content Server system uses an Oracle WebLogic server, which has a built-in web server, to filter pages through a web browser. User requests are authenticated with the Oracle WebLogic server user store and communicated with the Oracle Content Server system.
The WebUrlMapPlugin component enables you to map shortened URLs to other URLs in g] using a substitution script for the mapping, which also enables you to map long URLs to abbreviated versions. The WebUrlMapPlugin component is installed (enabled) by default with the Oracle Content Server instance.
This section covers these topics:
The shortened URLs that you can create generally use the following format:
http://myhostname.com/prefix/suffix
The actual mapping process is based on the part of the URL that follows the host name portion. To resolve the shortened URL, the Oracle Content Server instance compares the prefix to those in the list of defined WebUrlMapPlugin entries. If a match exists, the Oracle Content Server instance uses the map script that corresponds to the matching prefix to display the applicable document or Oracle Content Server page. For more information about the suffix, see Section 4.4.2, "Supported Variables for Referencing."
To construct a URL mapping entry using the WebUrlMaps Screen, you must establish a prefix and define the corresponding map.
Prefix
The prefix portion of the mapping entry is any abbreviation you want to use to identify URLs of a certain form. For example, if you want your short URL to return the dynamic conversions of documents, you can use idc as your prefix (for example, the abbreviated form of dynamic converter).
When you create your prefix, do not enter a slash (/) character at the beginning of it because the Oracle Content Server instance removes the first slash from the incoming URL before the prefix test is performed.
|
Caution: Include a slash (/) at the end of your URL map prefix. Otherwise, your mappings can apply to many more URLs and interfere with standard Oracle Content Server operations. |
Map
The map portion of the mapping entry is the Idoc Script code that the Oracle Content Server instance uses to resolve the shortened URL. You can use substitution tags (<!--$variable-->) in the map portion. Examples include:
<!--$cgipath-->
<!--$internetuser-->
<!--$suffix-->
These substitution tags are variables that refer to the applicable parameters of a URL.
Simple 'if' constructions are also supported. For example, the following script segment performs a test to determine whether a value exists and is not empty:
<!--$if myconfigvar-->something<!--$endif-->
The map portion of the URL mapping entry uses the following standard variables for referencing:
The CGI path
This is the current CGI path of the Oracle WebLogic Server web server filter's configured Oracle Content Server instance. The web server filter is configured to provide both communication and security for this Oracle Content Server instance. A typical example is /idcm1/idcplg.
The 'suffix' parameter
The value of the suffix variable (<!--$suffix-->) is derived from the part of the URL that follows the preliminary mapping 'prefix' and before the question mark (?). Any slashes (/) at the beginning of the suffix are removed before being substituted into this variable. For example, in the following URL, 'dc' is the mapping prefix followed by the suffix.
http://myhostname.com/dc/mydocumentname
After removing the slash, mydocumentname is used as the value for the suffix variable that is used as a substitution tag in the map portion of the mapping entry. Also, the suffix variable does not include any CGI parameters. Therefore, in the following URL, mydocumentname is still used as the suffix variable's value.
http://myhostname.com/dc/mydocumentname?a=1
To enforce the slash separation between the prefix and suffix, add the slash at the end of your prefix abbreviation.
Any plugin variable
For example, you could use the construct <!--$internetuser--> to substitute for the user ID of the currently logged-in user.
Any CGI parameter
To add or edit URL mapping entries:
Select the Administration tray, then click WebUrlMapPlugin.
The WebUrlMaps Screen is displayed.
Enter the appropriate values in the Prefix and Map fields to edit the existing mapping entries, or define new entries, or both.
Click Update.
The screen refreshes and the Prefix and Map field values are saved. If all of the displayed fields are populated, two additional Prefix and Map field pairs are displayed after the screen is redisplayed.
|
Important: The WebUrlMapPlugin feature is designed to support hundreds of mapping entries. However, be aware that thousands of mapping entries will impact performance of the web server. |
The following examples demonstrate mapping scripts and techniques.
You can define a web URL mapping script that enables you to create a shortened URL to generate the Info Update Form for existing content items. You can write the mapping script to allow users to enter any identification variable for a particular document. For example, all URLs with the following format:
http://myhostname.com/u/mydoc_parameter
can be mapped to the URL:
http://myhostname.com/idcm1//idcplg?IdcService=GET_UPDATE_FORM&dDocName=mydocumentname
To map URLs, define the following web URL map entry using the WebUrlMaps Screen:
Prefix:
u/
Map:
<!--$cgipath-->?IdcService=GET_UPDATE_FORM<!--$suffix-->&myparam=<!--$myparam-->
Dynamic Converter must be installed for this URL mapping example to work.
You can define a web URL mapping script that enables you to create shortened URLs to various dynamic conversions of documents. For example, all URLs with the following format:
http://myhostname.com/dc/mydocumentname
can be mapped to the URL:
http://myhostname.com/idcm1/idcplg?IdcService=GET_DYNAMIC_CONVERSION&dDocName=mydocumentname&RevisionSelectionMethod=LatestReleased
To map URLs, define the following web URL map entry using the WebUrlMaps Screen:
Prefix:
dc/
Map:
<!--$cgipath-->?IdcService=GET_DYNAMIC_CONVERSION&dDocName=<!--$suffix-->&RevisionSelectionMethod=LatestReleased
You can also directly reference CGI parameters. For example, URLs with the following format:
http://myhostname.com/dcp/mydocumentname?myparam=myvalue
can be mapped to the URL:
http://myhostname.com/idcm1/idcplg?IdcService=GET_DYNAMIC_CONVERSION&dDocName=mydocumentname&RevisionSelectionMethod=LatestReleased&myparam=myvalue
To map URLs, define the following web URL map entry using the WebUrlMaps Screen:
Prefix:
dcp/
Map:
<!--$cgipath-->?IdcService=GET_DYNAMIC_CONVERSION&dDocName=<!--$suffix-->&RevisionSelectionMethod=LatestReleased&myparam=<!--$myparam-->
This section covers these topics:
A provider is an Application Programming Interface (API) that establishes connection between the Oracle Content Server instance and outside entities. These entities can be:
Oracle WebLogic Server
LDAP servers
databases
server sockets
file store system
Inbound Refinery
By default, an Oracle Content Server instance has three system providers:
In addition, you can create the following types of providers:
Outgoing: A connection initiated to an outside entity. You can use this type to communicate between Oracle Content Server instances. If you want to use SSL with an outgoing provider, see details in Section 4.5.1.3, "Security Providers."
Database: An information repository server that provides an API for connecting and communicating with it. This retrieves information and enables information to be changed in the database. Examples of this type are system databases.
Incoming: A connection initiated from an outside entity like a browser or client application. The provider listens on a specified port to be aware of incoming connections. If you want to use SSL with an incoming provider, see details in Section 4.5.1.3, "Security Providers."
Preview: An outgoing provider connection to Oracle Content Publisher, for use with the optional HTML Preview feature.
LDAP: A connection initiated to an LDAP (Lightweight Directory Access Protocol) server for managing external user access to the Oracle Content Server instance. This type of provider is supported by the ActiveDirectoryLdap component, which is installed (disabled) by default during Oracle Content Server installation. As of 11g Release 1 (11.1.1) its functionality is mostly superseded by JpsUserProvider, in particular for nested group support.
HTTP: A connection that allows communication between Oracle Content Server instances using the HTTP protocol. This type of provider requires the Proxy Credentials Extension component, which is installed (enabled) by default during Oracle Content Server installation.
JpsUserProvider: A connection to an Oracle WebLogic Server instance. This provider uses Java Platform Security (JPS) to perform user authentication, user authorization, and retrieval of user metadata through an Oracle WebLogic Server instance. This type of provider is supported by the JpsUserProvider component, which is installed (enabled) by default with the Oracle Content Server instance.
The different types of providers described in the previous section are added under specific circumstances to work with various other Oracle products or utilities. The following subsections describe those conditions and the particular provider types that must be added in each scenario.
Outgoing providers are added to use the Oracle Content Server Archiver utility and Inbound Refinery. If you want to use SSL or keepalive with an outgoing provider, see details in Section 4.5.1.3, "Security Providers."
Archiver Utility (Oracle Content Server): The Archiver is a utility within the core Oracle Content Server product that enables system administrators to copy and remove content and store it for future use. Users can query a set of content from the Oracle Content Server instance and export it to an archive. Archives can then be imported to other Oracle Content Server instances or can be imported back to the same instance with changed metadata fields.
An outgoing provider is required to use the Archiver Transfer feature, which is used to archive content across a firewall or between two systems that do not share a file system. For more information about the Transfer feature, the different types of transfers and the outgoing provider requirements, see the Managing Migration chapter for more information.
For additional reference information about outgoing providers and each specific field, see Section A.1.6.4, "Outgoing Socket Provider Page."
Inbound Refinery: The Inbound Refinery server processes content checked in to Oracle Content Server and converts it to specified formats. An outgoing connection to the Inbound Refinery server is necessary for communication with Oracle Content Server. For details, see Oracle Fusion Middleware Administrator's Guide for Conversion.
Database providers are added to use external databases.
Frequently, it is desirable or necessary to perform database queries on databases that are not the default Oracle Content Server database. In this case, customized database providers can be created that make it possible to access any data from any application, regardless of which database management system is handling the data. Using customized database providers to integrate external databases into a Oracle Content Server system, search results can be combined and viewed on a single search screen. Additionally, data can be imported from these external database sources.
Administrators can create a database provider in one of two methods:
Use the Oracle WebLogic Server Administration Console to create an Oracle WebLogic Server data source to the database, then configure an Oracle Content Server database provider to use that data source. For information, see "Creating a JDBC Data Source for a WebLogic Domain Server" in Oracle Fusion Middleware Developer's Guide for Oracle Application Development Framework.
Create an Oracle Content Server database provider to connect directly to the database through a JDBC connection, without using an Oracle WebLogic Server data source. This mode is provided for instances with pre-existing connections in their configurations.
For additional reference information about Oracle Content Server database providers and each specific field, see Section A.1.6.5, "Database Provider Page."
Incoming providers are added to use WebDAV support and the Oracle Content Server Archiver utility. If you want to use SSL or keepalive with an incoming provider, see details in Section 4.5.1.3, "Security Providers."
Oracle WebDAV Support: With version 6.2 of Oracle Content Server, you could implement WebDAV (Web-Based Distributed Authoring and Versioning) support using an incoming provider and the Oracle Content Server integrated Tomcat servlet engine. In Oracle Content Server version 7.0 and later, however, WebDAV support is provided by a custom feature, so the provider and servlet engine are no longer necessary.
See the Oracle Fusion Middleware Applications Administrator's Guide for Content Server for more information.
Archiver Utility (Oracle Content Server): The Archiver is a utility within the core Oracle Content Server product that enables system administrators to copy and remove content and store it for future use. Users can query a set of content from the Oracle Content Server instance and export, import, or replicate to another instance, or change metadata fields. Tasks most frequently performed involve transfer, backup, and reorganization of information within the system.
Generally, when data or content items are moved from one repository to another, the Archiver utility uses a push technology to relocate the files. However, occasionally your system might require that the files be pulled rather than pushed. In this case, an incoming provider must be created. For additional reference information about incoming providers and each specific field, see Section A.1.6.6, "Incoming Provider Page."
Consulting Services are required perform this operation.
Preview providers are added to use HTML Preview and Content Categorizer.
HTML Preview: HTML Preview is a feature that provides users with instant feedback on how their content will display on the published web site. This feature enables users to modify the original content before it is actually checked in. HTML Preview also helps users ensure that correct metadata has been assigned to the content. During the installation process, a preview provider must be created. For additional overview and installation information about HTML Preview, see the Oracle Fusion Middleware Application Administrator's Guide for Content Server.
Content Categorizer: Content Categorizer suggests metadata values for documents being checked into Oracle Content Server or for existing documents that need to have metadata reapplied. For Content Categorizer to recognize structural properties of a document, the file must be converted to XML.
If you are using Content Publisher to set up a template for the required XML conversion process, the HTML Preview feature must be configured as a preview provider. (HTML Preview is a feature that enables users to preview their content and see what the converted output from Content Publisher will look like.)
For more information about Content Categorizer, see the Oracle Fusion Middleware Application Administrator's Guide for Content Server. This guide provides relevant information about any additional products that may be required or are optional. For additional reference information about preview providers and each specific field, see Section A.1.6.7, "Preview Provider Page."
Lightweight Directory Access Protocol (LDAP) is a directory service protocol that runs over TCP/IP. It provides high-level functionality to manage resources within a network and works with Oracle Content Server to manage security and user authentication. The LDAP directory service model is based on a collection of attributes and is used to access information stored in an information directory. As such, LDAP is used to validate a set of user name and password credentials against an authentication source. This process will grant privileges to a user to give them access to web resources.
An LDAP server provides a single source for user-related information that can be accessed from applications such as Oracle Content Server and other Oracle product modules. Instead of maintaining user information within the Oracle Content Server instance, you can integrate an LDAP directory to authenticate user credentials to the Oracle Content Server instance.
|
Note: As of 11g Release 1 (11.1.1), LDAP provider functionality is superseded by JpsUserProvider. Use of the LDAP provider is not recommended. See Section 4.5.1.2.6, "When to Edit JpsUserProvider." |
If you decide to use an LDAP server (other than Active Directory, which can be integrated directly with the Oracle Content Server instance), you must create an LDAP provider to set up communication between the Oracle Content Server instance and the LDAP server. When properly configured, the LDAP provider authorizes external users through the mapping properties that are linked to role assignments and account permissions (defined on the Ldap Provider page).
For additional reference information about LDAP providers and each specific field, see Section A.1.6.8, "LDAP Provider Page."
Although not required, you are encouraged to have Consulting Services assist you with creating an LDAP security model and deploying the LDAP integration. Contact your sales representative for more information.
LDAP integration is also useful with the following content management products and architectures:
Portlets on WebSphere: WebSphere users can access Oracle Content Server through the Oracle Content Integration Suite. This portal interface enables users and developers to retrieve, view, and download Oracle Content Server content items based on full text or metadata search queries. When using the Content Integration Suite, the WebSphere Application Server is recommended. If you are using a WebSphere Portal Server, the Oracle Content Portal Suite is a recommended addition to the Content Integration Suite.
The Content Integration Suite connects directly to the Oracle Content Server instance instead of the database. This direct connection avoids the authentication step at the web server and enables the developer total control over the authentication and authorization of users. The advantage is you can authenticate users at the Content Integration Suite layer however you want. You can integrate with an LDAP server at the application server level, or you can ask the Oracle Content Server instance to validate the passwords for you.
For more information about using WebSphere with the Content Integration Suite and the Content Portal Suite, see the documentation provided with the WebSphere Portal Server, WebSphere Application Server, Oracle Content Integration Suite, and Oracle Content Portal Suite.
Content Tracker: Content Tracker is a system that is built from a collection of software features that, when combined, enable users to use a standard browser to track content usage through an integrated set of analytical tools. The data provided by the Oracle Content Server instance is derived from logged data that includes web server log data, Oracle Content Server data, and user information. Content Tracker accesses this data, performs analysis on it, and produces descriptive reports. Integrating an LDAP directory server with Content Tracker is optional. However, if LDAP is used, an LDAP provider must be created.
For more information about the related data repositories, report generation, producing queries and installation procedures, see the Oracle Fusion Middleware Application Administrator's Guide for Content Server.
The system-defined JpsUserProvider connects to an Oracle WebLogic Server instance and supports the Oracle WebLogic Server authentication mechanism (Basic, Form, Single Sign-On, WNA, and so forth). Java Platform Security (JPS) provides a uniform interface for authenticating and authorizing users from Oracle Fusion Middleware applications regardless of the back-end user storage (XML, LDAP, database, Active Directory, and so on). JPS API calls are used to perform user authentication, user authorization and retrieval of user metadata.
|
Note: As of 11g Release 1 (11.1.1), LDAP provider functionality is superseded by JpsUserProvider, in particular for cases such as nested group support. |
The JpsUserProvider component is installed and enabled as a system component when the Oracle Content Server instance is installed against an Oracle WebLogic Server instance. It also is available as a standard Oracle Content Server component. You can edit the JpsUserProvider configuration from the Providers page in the Oracle Content Server instance. The connection configuration also can be edited through the jps-config.xml file to use identity and credential stores.
It is unlikely that a site would ever add a JpsUserProvider in addition to the system-defined JpsUserProvider. Adding another such provider could cause problems for the Oracle Content Server installation.
If you want to authenticate against a JPS store, JpsUserProvider can be used to share the same security storage as another application on an Oracle WebLogic Server instance. For example, you could use JpsUserProvider to share security storage with Image and Processing Manager software installed on an Oracle WebLogic Server instance.
This section covers the following topics:
The SecurityProviders component can be used to add security by extending the functionality of basic incoming and outgoing socket providers with two new types of providers:
Secure Socket Layer (SSL) provider
Keepalive provider
Appropriate use of security providers, along with keys and certificates, can improve the security for network and Internet communication with the Oracle Content Server instance. Benefits of using the SecurityProviders component include the following:
SSL enhances security for web communication by providing communication encryption and authentication.
Security providers enable use of certificates for socket or server authentication.
Keepalive and connection pooling logic help avoid SSL expense overhead by reducing the amount of SSL socket creation and teardown.
The SecurityProviders component is installed (enabled) by default with the Oracle Content Server instance.
References
To use the SecurityProviders component it is necessary to be familiar with socket providers, security and authentication, SSL, keepalive, and other aspects of security for network communication. The following sources of information can be useful in working with the SecurityProviders component:
Section 4.5, "Connecting to Outside Entities with Providers"
Sun Java Secure Socket Extension (JSSE) Reference Guide for the Java 2 SDK, Standard Edition
This online document is available from Sun Microsystems at www.sun.com. It contains an extensive Related Documents section that includes web links to reference books, security standards, government security policies and regulations, and a list of books on cryptography and SSL.
keytool Key and Certification Management Tool
This online document is available from Sun Microsystems at www.sun.com.
RSA's Public Key Cryptography Standards
This online document is available from RSA at www.rsasecurity.com.
RSA's Cryptography FAQ
This online document is available from RSA at www.rsasecurity.com.
SSL Certificate FAQ
This online document is available from The Linux Documentation Project at www.tldp.org.
Terminology
The following table shows definitions for some of the security terms used in this section. For detailed information refer to the list of information references or to security and authentication standards sources.
| Term | Description |
|---|---|
| Certificate | A digital signature that verifies the identity and public key for an entity (a person or company). A certificate can be issued by a Certification Authority or by an individual entity. |
| Certificate Authority (CA) | An entity that issues certificates for other entities, and is recognized as a well-known and trusted source for certificates, such as VeriSign and Thawte. |
| Keystore | A file or database of information for keys, used for authentication processing. |
| Private key | Information packaged as a key that is known only to the entity that issues it. Private keys are used in generating signatures. |
| Public key | Information packaged as a key that is publicly associated with an entity. Public keys are used in verifying signatures. |
| SSL | Secure Socket Layer, a protocol for secure network communication using a combination of public and secret key technology. |
| Truststore | A file or database of keys that the trust manager has determined can be trusted. |
It is recommended that you determine how you want to use security providers before implementing SSL socket providers or keepalive socket providers. Examine the keepalive and SSL connection types and determine whether additional configuration is required to use the security providers you select, such as a need to create keystores or a truststore. See the additional sources of information listed in Section 4.5.1.3.1, "About Security Providers."
The following sections provide more information about the SSL and keepalive provider types, including the Java classes used to control the behavior of the provider types, and additional configuration that may be necessary.
Keepalive Connections
The keepalive feature enables persistent connections and the pooling of socket connections for service requests. The setup for keepalive connections is most useful in situations where connection setup and teardown can take a considerable amount of time, and you want to minimize the time spent on that activity. The SecurityProviders component provides two keepalive socket providers: incoming and outgoing.
The following Java classes are used to set up the keepalive incoming socket provider:
| Java Class | Description |
|---|---|
| Provider Class | idc.provider.ExtendedSocketIncomingProvider |
| Connection Class | idc.provider.KeepaliveSocketIncomingConnection |
| Server Thread Class | idc.server.KeepaliveIdcServerThread |
The following Java classes are used to set up the keepalive outgoing socket provider:
| Java Class | Description |
|---|---|
| Provider Class | idc.provider.KeepaliveSocketOutgomingProvider |
| Connection Class | idc.provider.KeepaliveSocketOutgomingConnection |
| Request Class | idc.server.KeepaliveServerRequest |
SSL Connections
The SSL provider setup enables the use of SSL connections in a keepalive environment. This setup is recommended over a simple SSL provider setup because it helps minimize the cost of SSL socket setup and teardown. The SecurityProviders component provides two SSL socket providers with keepalive: incoming and outgoing.
The following Java classes are used to set up the SSL keepalive incoming socket provider:
| Java Class | Description |
|---|---|
| Provider Class | idc.provider.ssl.SSLSocketIncomingProvider |
| Connection Class | idc.provider.KeepaliveSocketIncomingConnection |
| Server Thread Class | idc.server.KeepaliveIdcServerThread |
The following Java classes are used to set up the keepalive SSL outgoing socket provider:
| Java Class | Description |
|---|---|
| Provider Class | idc.provider.KeepaliveSocketOutgoingProvider |
| Connection Class | idc.provider.ssl.SSLSocketOutgoingConnection |
| Request Class | idc.provider.KeepaliveServerRequest |
Additional Configuration
Depending on which type of security provider you choose, there can be additional required configuration.
Keepalive and SSL outgoing providers—The Add Provider page includes a Num Connections field, which specifies the number of connections to pool.
SSL incoming providers—The Add Provider page includes two additional options:
Request Client Auth option—If clients are able, they should authenticate themselves when they make a connection.
Require Client Auth option—Clients must authenticate themselves in order to make a connection.
SSL providers may also require setup of a keystore or keystores, and a truststore, for both the client and server, depending on the value of the Request Client Auth option, the value of the Require Client Auth option, and what type of Certification Authority signed the certificates handled by these options. For information on keystores and truststore refer to Section 4.5.1.3.3, "Keystores and Truststore."
SSL providers may require use of keystores and may require a truststore. Keystores are files that hold public and secret key information for use in SSL. A truststore contains certificates that have been determined to be trusted. If a certificate used on the server and client is signed by a well-known Certification Authority (CA) such as VeriSign or Thawte, then a truststore is not necessary, because the default JVM truststore contains the certificates of these CAs. Truststores are needed when certificates used by the SSL providers are self-signed or signed by a private CA. If SSL providers require keystores, and a truststore, then they must be created and managed.
The following sections provide overview information about keystores and truststore.
For detailed information on keystores and truststores refer to the sources of information listed in Section 4.5.1.3.1, "About Security Providers."
When to Use Keystores and Truststore
The following examples present different situations and uses for keystores and a truststore.
The server requires a keystore containing a signed SSL certificate in order to create SSL sockets.
The server requests or requires client authentication, which may require a truststore. If the client's certificate is not signed by a well-known CA, then the server will need a truststore containing that CA's certificate.
The server requests or requires client authentication, which may require that the client have a keystore in which it stores the certificate the client presents for authentication.
The server uses a certificate that hasn't been signed by a well-known CA, therefore the client will require a truststore that contains the server's certificate.
Specifying Keystore and Truststore Information
In order to use keystore and truststore information, the SSL incoming and outgoing providers require that a file named sslconfig.hda be set up in the providers directory (next to the provider.hda file). The sslconfig.hda file contains configuration information you specify for your keystore and truststore. It has a format similar to the following example. For security reasons, there is no web interface to assist in editing this file; all edits must be done manually using a text editor. Make certain no trailing spaces are included at the end of each line of this or any .hda file.
@Properties LocalDataTruststoreFile=/servers/idc/data/providers/ssloutgoing1/truststoreKeystoreFile=/servers/idc/data/providers/ssloutgoing1/keystore@end
| Configuration Name | Value Description |
|---|---|
| TruststoreFile | The full path to the truststore file. |
| KeystoreFile | The full path to the keystore file. |
Generating a Keystore
This section describes the basic process for generating a keystore. You must determine the specific requirements and names for keys and keystores you want to create for your SSL providers. You can store keystore files wherever you want, because the sslconfig.hda file contains full paths for its KeystoreFile config settings. However, it is recommended that keystore files are stored in the IntradocDir/data/providers/provider_name directory (next to the provider.hda and sslconfig.hda files) or in the IntradocDir/config/ directory. Aliases and passwords are set using the provider page in the Oracle Content Server instance.
For detailed information on how to use the keytool utility to generate a keystore, see the document titled keytool Key and Certification Management Tool, available online from Sun at www.sun.com.
|
Note: The Java keytool utility has a feature that prevent direct interaction with private keys. This feature means that a certificate that is generated using keytool is "stuck" in the keystore; there is no way to retrieve the private key portion of the certificate. Inversely, there is no way for keytool to import a pre-existing certificate into a Java keystore.The Portecle Java keystore allows the import and export of private keys from Java keystores. For information refer to portecle.sourceforge.net. |
To use keytool you must have the utility in your path when you enter the command.
Create a key in a keystore. The following command-line example shows how to create a key entry with the name alias in a keystore with the name keystore. This command prompts for a keystore password, for information that will be used to generate the key, and for a password for the key itself. If the password on the key is different from the password on the keystore, then the values KeystoreAlias and KeystoreAliasPassword are required to retrieve the key.
keytool -genkey -v -alias alias -keystore keystore
Generate a certificate signing request.The following command-line example shows how to generate a certificate signing request for the key entry named alias in the keystore named keystore, which is then stored in the file named csr_file. This file can be sent to a CA to be signed.
keytool -certreq -v -alias alias -keystore keystore -file csr_file
Import the CA's certificate into the keystore. The keytool checks the chain of trust on the user's certificate upon import. If the certificate was signed by a CA that is not well-known and the keytool knows nothing about the CA, the certificate is rejected. Therefore any certificate from a CA that is not well-known must first be imported into the keystore to permit the user's certificate to successfully be imported in the next step. The following command line example shows how to import a certificate in a file named cert_file into the keystore named keystore:
keytool -import -v -alias ca_alias -keystore keystore -file cert_file
Import the signed certificate back into the keystore. Once the certificate signing request has been received by a CA and the signed certificate is sent back from the CA, the certificate can be read into the keystore entry identified by alias.The following command line example shows how to import the signed certificate.
keytool -import -v -alias alias -keystore keystore_name -file csr_file
Check that everything is in the keystore.
keytool -list -v -keystore keystore_name
Creating a Truststore
This section describes the basic process for generating a truststore. A truststore is necessary when an SSL provider uses keys that have not been signed by a well-known Certification Authority. A truststore contains only public certificates that have been verified by the person managing the truststore (the trust manager) for the Oracle Content Server instance. You must determine the specific requirements and name for the truststore you want to create. You can store a truststore file wherever you want, because the sslconfig.hda file contains a full path for a TruststoreFile config setting. However, it is recommended that a truststore file is stored in the IntradocDir/data/providers/provider_name directory (next to the provider.hda and sslconfig.hda files) or in the IntradocDir/config/ directory.
For detailed information on how to use the keytool utility to generate a truststore refer to the document titled keytool Key and Certification Management Tool, available online from Sun at www.sun.com.
To use keytool you must have the utility in your path when you enter the command.
The following command line example shows how to create a truststore:
keytool -import -v -alias alias -keystore keystore -file cert_files
| Variable | Description |
|---|---|
| alias | Alias name for the key. |
| keystore | Name of the keystore. |
| cert_file | Path to the Certification Authority's certificate. |
The following tasks are involved in managing providers.
To add an outgoing provider:
Display the Providers Page.
In the Create a New Provider table, click Add in the Action column for the outgoing provider type.
The Outgoing Socket Provider Page is displayed.
Complete the following:
Required Fields
Provider Name
Provider Description
Server Host Name
Server Port
Provider Class (predefined)
Optional Fields
Connection Class (predefined)
Configuration Class
Relative Web Root
HTTP Server Address
Instance Name
Required Roles
Account Filter
Optional Checkboxes
Proxied
Notify Target
Users
Released Documents
Click Add.
The Providers page is displayed, with the new provider added to the Providers table.
Restart the Oracle Content Server instance.
Database provider configuration is specified when Oracle Universal Content Management and the Oracle Content Server instance is installed in an Oracle WebLogic Server domain.
If you want to configure database connections for a standalone Oracle Content Server system, see Section 3.4.2.1, "Configuring a SystemDatabase Provider for Standalone Mode," Section 3.4.2.2, "Configuring a JDBC Database Driver for Standalone Mode," and Section 3.4.2.3, "Configuring an External Database Provider for Standalone Mode."
To add a database provider:
Display the Providers Page.
In the Create a New Provider section, click Add in the Action column for the database provider type.
The Database Provider Page is displayed.
Complete the following:
Required Fields
Provider Name
Provider Description
Provider Class (predefined)
Database Type
JDBC Driver
JDBC Connection String
Test Query
Optional Fields
Connection Class (predefined)
Configuration Class
Data Source
Database Directory
Database Name
JDBC User
JDBC Password
Number of Connections (default provided)
Extra Storage Keys (default provided)
Additional Settings
Optional Checkboxes
Use Data Source
Click Add.
The Providers page is displayed, with the new provider added to the Providers table.
Restart the Oracle Content Server instance.
Consulting Services are required to use providers to connect to server sockets.
To add an incoming provider:
Display the Providers Page.
In the Create a New Provider section, click Add in the Action column for the incoming provider type.
The Incoming Provider Page is displayed.
Complete the following:
Required Fields
Provider Name
Provider Description
Server Port
Provider Class (predefined)
Optional Fields
Connection Class (predefined)
Configuration Class
Click Add.
The Providers page is displayed, with the new provider added to the Providers table.
Restart the Oracle Content Server instance.
See the Oracle Fusion Middleware Application Administrator's Guide for Content Server for instructions on adding the Preview provider. The HTML Preview feature zip file and guide are available for download from the Oracle Technology Network web site.
To add an incoming security provider, follow these steps:
Display the Providers Page.
In the Create a New provider table, click Add in the Action column for the keepaliveincoming or the sslincoming provider type. The keepaliveincoming Provider Page or the sslincoming Provider Page is displayed.
Complete the following:
Required Fields
Provider Name
Provider Description
Provider Class (predefined)
Server Port
Optional Fields
Connection Class (predefined)
Configuration Class
Server Thread Class (predefined)
Optional Checkboxes (sslincoming provider only)
Request Client Authentication
Require Client Authentication
Click Add. The Providers Page is displayed with the new provider added to the Providers table.
Restart the Oracle Content Server instance.
To add an outgoing security provider, follow these steps:
Display the Providers Page.
In the Create a New provider table, click Add in the Action column for the keepaliveoutgoing or ssloutgoing provider type. The keepaliveoutgoing Provider Page or the ssloutgoing Provider Page is displayed.
Complete the following:
Required Fields
Provider Name
Provider Description
Provider Class (predefined)
Server Host Name (predefined)
Server Port
Instance Name
Relative Web Root
Optional Fields
Connection Class (predefined)
Configuration Class
Request Class (predefined)
Number of Connections (predefined)
HTTP Server Address
Required Roles
Account Filter
Optional Checkboxes
Proxied
Notify Target
Users
Released Documents
Click Add. The Providers Page is displayed, with the new provider added to the Providers table.
Restart the Oracle Content Server instance.
A defaut JPS User provider, which integrates with Oracle JPS (for an Oracle WebLogic Server instance), is provided with installation of the Oracle Content Server system. It is unlikely that another JPS User provider would be needed. However, if you need to add a user provider, follow these steps:
Display the Providers Page.
In the Create a New Provider table, click Add in the Action column for the jpsuser provider type.
The JPS User Provider Page is displayed.
Complete the following fields:
Required fields
Provider Name
Provider Description
Provider Class (predefined)
Source Path
Optional fields
Connection Class
Configuration Class
JPS Context
Default Network Roles
To specify an attribute map:
Select an information field from the JPS Attributes list.
Select an Oracle Content Server user information field from the User Attribute list.
Click Add.
The attribute map is added to the text box.
If necessary, edit the attributes directly in the Attribute Map text box.
If necessary, change or add Default Network Roles.
Click Add.
The Providers page is displayed, with the new provider added to the Providers table.
Restart the Oracle Content Server instance.
Restart the web server.
To add an HTTP outgoing provider:
Display the Providers Page.
In the Create a New Provider table, click Add in the Action column for the httpoutgoing provider type.
The Outgoing Http Provider Page is displayed.
Complete the following fields:
Required fields
Provider Name
Provider Description
Provider Class (predefined)
CGI URL
Instance Name
Relative Web Root
Optional fields
Connection Class (predefined)
Configuration Class
Connection Password Name
Connection Password
Client IP Filter
Click Add.
The Providers page is displayed, with the new provider added to the Providers table.
Restart the Oracle Content Server instance.
To edit information for an existing provider (except for default system providers):
Display the Providers Page.
In the Providers table, click Info in the Action column for the provider to edit.
The Provider Information Page is displayed.
Click Edit.
The Add/Edit Provider Page is displayed.
Make the required changes.
Click Update to save the changes and return to the Providers page.
Restart the Oracle Content Server instance.
To delete an existing provider (except for default system providers):
Display the Providers Page.
In the Providers table, click the Info link in the Action column for the provider you want to delete.
The Provider Information Page is displayed.
Click Delete.
A confirmation screen is displayed.
Click OK.
The provider is removed from the Providers table.
|
Important: Ensure that you intend to delete the provider and not just edit the information. When you delete a provider, the provider name and all of its related information is permanently removed from the Providers table. |
