The wwv_context package contains procedures to create and maintain Oracle Text indexes used by Oracle Portal. This appendix describes the content of this package in the following sections:
Note:
See Chapter 10, "Configuring the Search Features in Oracle Portal" for more information about Oracle Text indexes and how they are used in Oracle Portal.
The wwv_context package contains these procedures:
touch_index(p_indexes wwsbr_array)
procedure add_attribute_section(
p_attributeid in number,
p_attributesiteid in number
)
Adds a new section to the section groups used by the Item and Page indexes. The section group corresponds to an attribute. This changes the index metadata only, it does not update the index data itself. The new sections can be searched but the indexes themselves are not changed.
The indexes are changed only if they exist; if the indexes do not exist, this procedure has no effect.
p_attributeId - ID of the attribute section to add.
p_attributeSiteId - Site ID of the attribute section to add.
procedure commit_sync(
p_index in varchar2
p_commit_sync in boolean
)
(Oracle Database 10g or later) Specifies whether an Oracle Text index is synchronized immediately after data is committed to your portal, or needs to be synchronized manually using wwv_context.sync (see sync).
If you choose to synchronize an index manually or your database is earlier than Oracle Database 10g, you can run wwv_context.sync directly or create a job that calls wwv_context.sync at regular intervals. wwv_context.sync ignores any index where commit_sync is set to true. See also, Section 10.3.5.4, "Scheduling Index Synchronization".
Note:
The commit_sync property is available only in database versions Oracle Database 10g or later. In earlier versions, Oracle Text indexes can be synchronized manually, or according to a synchronization schedule (certain dates and times). See also Section 10.3.5.1, "Synchronizing Oracle Text Indexes".
p_index - The name of the index. One of the Index Name Constants.
p_commit_sync - Determines whether the index synchronizes immediately after a commit. Set commit_sync to true if you want the index to synchronize automatically whenever data is committed in your portal. Set commit_sync to false if you want to synchronize the index manually using wwv_context.sync.
INVALID_INDEX - The name of the index was not recognized.
procedure create_index(
p_index in varchar2
)
Creates a specific, named Oracle Text index. See also, Section 10.3.3, "Oracle Text Indexes".
Use this procedure for troubleshooting purposes only. Under normal circumstances, use create_missing_indexes to create all of the indexes that are missing, or createindex to drop invalid indexes and then re-create the preferences and missing indexes.
p_index - The name of the index you want to create. One of the Index Name Constants.
INVALID_INDEX - The name of the index was not recognized.
procedure create_missing_indexes(
p_indexes out wwsbr_array
)
Creates all of the Oracle Text indexes that are missing. An index is considered to be present if it exists according to the view ctx_user_indexes.
This procedure does not check to see if the existing indexes are valid. Use the procedure drop_invalid_indexes to drop any indexes that are not entirely valid.
This procedure creates empty indexes. To populate the indexes you must mark them as 'requiring re-indexing' using the procedure touch_index(p_indexes wwsbr_array), and then you must synchronize the indexes.
This procedure does not create Oracle Text Datastore and Filter preferences; these preferences must already exist. Use the procedure create_prefs to create the preferences, if they do not exist.
p_indexes - Returns an array containing the list of indexes created.
procedure create_prefs
Creates the Datastore and Filter preferences which are both used when creating Oracle Text indexes. See also, Section 10.3.3.2, "Oracle Text Index Preferences".
This procedure does not create any of the Lexer preferences. Use the script sbrimtlx.sql located in the directory ORACLE_HOME\portal\admin\plsql\wws to create Lexer preferences. See also, Section 10.3.3.5, "Multilingual Functionality (Multilexer)".
Oracle Text preferences must exist before the indexes are created. Subsequent changes to these preferences do not take effect until the Oracle Text indexes are dropped and re-created.
procedure createindex(
p_language in varchar2 default wwnls_api.nls_default_language,
p_message out varchar2
)
Creates Oracle Text indexes used by Oracle Portal. See Section 10.3.3, "Oracle Text Indexes" for more information.
This high level procedure performs the following tasks:
Drops all existing preference objects.
Drops any invalid indexes.
Re-creates Oracle Text preferences.
Creates indexes that are missing (initially empty).
Marks all indexable Oracle Portal content as requiring re-indexing, for all new indexes.
Synchronizes indexes, that is, first populates and then optimizes the indexes.
This procedure is equivalent to:
wwv_context.drop_prefs; wwv_context.drop_invalid_indexes; wwv_context.create_prefs; wwv_context.create_missing_indexes(l_indexes); wwv_context.touch_index(l_indexes); wwv_context.sync; wwv_context.optimize;
procedure drop_all_indexes
Drops all the Oracle Text indexes used by Oracle Portal.
This procedure does not drop the Oracle Text preferences. Use the procedure drop_prefs to do this.
procedure drop_index(
p_index in varchar2
)
Drops a specific, named Oracle Text index. This procedure does not validate that the index exists.
p_index - The name of the index you want to drop. One of the Index Name Constants.
INVALID_INDEX - The name of the index was not recognized.
procedure drop_invalid_indexes
Drops invalid Oracle Text indexes only, that is, valid Oracle Text indexes are not dropped.
An index is considered to be valid, if the following status columns, in the following views, are all set to 'VALID':
user_indexes.status
user_indexes.domidx_status
user_indexes.domidx_optstatus
ctx_user_indexes.idx_status
If any status column is not valid or, if the index does not have an entry in both views, it is considered to be invalid and will be dropped. See Section 10.3.8, "Viewing the Status of Oracle Text Indexes" for more information.
procedure drop_prefs
Drops the Oracle Text Datastore and Filter preferences. See also, Section 10.3.3.2, "Oracle Text Index Preferences".
Datastore and Filter preferences are used when creating the Oracle Text indexes. This procedure does not drop any of the Lexer preferences that are created using the script sbrimtlx.sql. The script is located in the directory ORACLE_HOME\portal\admin\plsql\wws.
procedure dropindex(
p_language in varchar2 default wwnls_api.nls_default_language,
p_message out varchar2
)
Drops all existing Oracle Text indexes used by Oracle Portal. See also, Section 10.3.3, "Oracle Text Indexes".
This procedure is equivalent to:
wwv_context.drop_prefs; wwv_context.drop_all_indexes;
procedure optimize(
p_optlevel in varchar2 default ctx_ddl.optlevel_full,
p_maxtime in number default null,
p_token in varchar2 default null
)
Optimizes all existing Oracle Text indexes used by Oracle Portal. Each index is optimized by calling the Oracle Text procedure ctx_ddl.optimize_index().
The parameters for this procedure are the same as those required by the Oracle Text procedure ctx_ddl.optimize_index.
p_optlevel - The optimization level, one of FULL, FAST or TOKEN.
p_maxtime - The time (in minutes) that Oracle Text spends optimizing the indexes.
p_token - Token to optimize (when doing TOKEN optimization).
You will find additional information in the Oracle Text Reference on the Oracle Technology Network (OTN), http://www.oracle.com/technology/products/text/index.html.
procedure set_parallel_degree(
p_index in varchar2,
p_parallel_degree in pls_integer
)
Sets the degree of parallelism used when an index is synchronized using the procedure wwv_context.sync (see sync). On a multi-processor computer you can run the synchronization operation in parallel. If you use multiple processors during synchronization it can speed up indexing, especially when you have large amounts of data to index.
The default setting is 1, no parallelism. A number greater than 1 turns on parallel synchronization. If you specify a parallel degree that is higher than the total number of processors available in your database server, the degree of parallelism achieved during synchronization might be smaller than requested.
Note:
This setting has no effect if the index synchronizes immediately after a commit (get_commit_sync returns true). See also, commit_sync.
You will find additional information in the Oracle Text Reference on OTN, http://www.oracle.com/technology/products/text/index.html.
p_index - The name of the index. One of the Index Name Constants.
p_parallel_degree - The degree of parallelism to use when the specified index is synchronized.
INVALID_SETTING - The format or value of p_parallel_degree was not recognized.
INVALID_INDEX - The name of the index was not recognized.
INTERNAL_EXCEPTION - An unexpected internal error occurred.
procedure set_sync_memory(
p_index in varchar2,
p_memory in varchar2
)
Specifies the amount of runtime memory that Oracle Text may use when synchronizing an index using the procedure wwv_context.sync (see sync). You can enter the memory value in bytes, or use the suffixes K, B or G to indicate that the value is in kilobytes, megabytes, or gigabytes respectively. For example, enter the value 10000 to specify 10000 bytes, or 10K to specify 10 kilobytes.
When the memory specified becomes full, the data is written to the database. The more frequently this happens, the slower the indexing performance becomes and the Oracle Text indexes also become more fragmented. Fragmentation can slow down portal search queries. Specifying smaller amounts of memory will impact performance and increase index fragmentation, but might be useful when runtime memory is scarce.
If you set p_memory to Null, the default index memory setting is used. This default value is set using the configurable Oracle Text system parameter DEFAULT_INDEX_MEMORY. If you want to specify a different value, it must be less than the Oracle Text system parameter MAX_INDEX_MEMORY.
For more information, see Oracle Text Reference on OTN, http://www.oracle.com/technology/products/text/index.html.
Note:
This setting has no effect if the index synchronizes immediately after a commit (get_commit_sync returns true). See also, commit_sync.
p_index - The name of the index. One of the Index Name Constants.
p_memory - The maximum amount of memory used to synchronize this index.
INVALID_SETTING - The format or range of p_memory was not recognized.
INVALID_INDEX - The name of the index was not recognized.
INTERNAL_EXCEPTION - An unexpected internal error occurred.
procedure set_use_doc_index( p_value in boolean )
Specifies whether the Document index is required. See also, Section 10.3.7, "Disabling Document and URL Indexing".
The value is cached for the duration of the session to avoid repeated requests for this information.
p_value - Either true or false. When set to true, the Document index is required.
procedure set_use_url_index( p_value in boolean )
Specifies whether the URL index is required. See Section 10.3.7, "Disabling Document and URL Indexing" for more information.
The value is cached for the duration of the session to avoid repeated requests for this information.
p_value - Either true or false. When set to true, the URL index is required.
procedure sync
Synchronizes all Oracle Text indexes used by Oracle Portal. Each index is synchronized by calling the Oracle Text procedure ctx_ddl.sync_index(). This procedure re indexes any rows that have been updated since the last synchronization. After synchronization, newly added or updated content can be searched. See also, Section 10.3.5.1, "Synchronizing Oracle Text Indexes".
Before synchronization, the pending queue is updated for the table wwsbr_url$. This table contains values for all the URLs attributes stored in Oracle Portal. Rows from this queue are removed when the URL value is equal to the value of the constant wwv_context_util.g_noindex. Rows are set to this value to indicate that the original URL was not indexable by Oracle Text, for example, URLs such as those beginning with https:// or javascript:.
You will find additional information on ctx_ddl.sync_index in Oracle Text Reference documentation on OTN, http://www.oracle.com/technology/products/text/index.html.
procedure touch_index(
p_indexes in wwsbr_array
)
Touches content for one or more indexes. When an index is touched, all the index content is marked as requiring synchronization. See Section 10.3.5.6, "Synchronizing All the Index Content" for more information.
Once index content is marked in this way, use the procedure sync to re index the marked content.
Note that this procedure operates across multiple virtual private portal subscribers, it is not confined to the current subscriber. The procedure switches to each subscriber in turn and returns back to the original subscriber when complete.
p_indexes - An array containing index names to touch. One or more of the Index Name Constants.
procedure touch_index(
p_index in varchar2 default null
)
Touches content for a single index or for all indexes. This procedure is a convenient way to touch a single, named index. Alternatively, you can use the procedure to touch all indexes, by passing the value null. See also, Section 10.3.5.6, "Synchronizing All the Index Content".
This procedure calls touch_index(p_indexes wwsbr_array) mentioned earlier.
p_index - The name of the index to touch, or null to touch all indexes. When specifying a name, use of one of the Index Name Constants.
Refer to Section D.1.18, "touch_index(p_indexes wwsbr_array)" for more information.
procedure update_index_prefs
Updates the current Oracle Text index datastore preferences. This procedure is valid only for database versions earlier than Oracle Database 10g.
When datastore preferences are modified after the indexes are created, the changes are not applied to the indexes automatically. Use this procedure to apply datastore preference changes to the Oracle Text indexes.
No action is taken for any indexes that are missing.
The wwv_context package contains these functions:
function checkindex(
p_force in boolean default false
) return boolean
Checks whether all required Oracle Text indexes exist. The Document and URL indexes are optional, so the presence and validity of these indexes are determined by calls to valid_doc_index and valid_url_index. See also, Section 10.3.7, "Disabling Document and URL Indexing".
The value returned by checkindex is cached for the duration of the session. Whenever true is passed to p_force, the status of Oracle Text indexes is re-evaluated, regardless of any previously cached value.
p_force - Either true or false. When set to true, Oracle Text indexes are checked.
Returns true if all required indexes exist and are valid.
function doc_index return boolean
Checks whether the Document index is required (using get_use_doc_index) and usable (using valid_doc_index).
Returns true if the Document index is both required and valid.
function get_commit_sync( p_index in varchar2) return boolean
Determines whether an index synchronizes immediately after data commits to your portal, or if it must be synchronized manually. See also, commit_sync.
Note:
The commit_sync property is not available for database versions earlier than Oracle Database 10g. This function returns false when called on an earlier database version.
p_index - The name of the index. One of the Index Name Constants.
Returns true if the index is configured to synchronize immediately after data is committed to your portal. Returns false if the index is configured to synchronize manually.
function get_parallel_degree(
p_index in varchar2)
return boolean
Gets the degree of parallelism used when an index is synchronized using the procedure wwv_context.sync (see sync). On a multi-processor computer you can run the synchronization operation in parallel. If you use multiple processors during synchronization it can speed up indexing, especially when you have large amounts of data to index.
The default setting is 1, no parallelism. A number greater than 1 turns on parallel synchronization. If the parallel degree is higher than the total number of processors available in your database server, the degree of parallelism achieved during synchronization might be smaller than that requested.
Note:
The parallelism setting has no effect if the index synchronizes immediately after a commit (get_commit_sync returns true).
You will find additional information in the Oracle Text Reference on OTN, http://www.oracle.com/technology/products/text/index.html.
p_index - The name of the index. One of the Index Name Constants.
Returns the degree of parallelism used when synchronizing the specified index.
INVALID_INDEX - The name of the index was not recognized.
INTERNAL_EXCEPTION - An unexpected internal error occurred.
function get_sync_memory(
p_index in varchar2)
return boolean
Gets the amount of runtime memory (in bytes) that Oracle Text may use when synchronizing an index using the procedure wwv_context.sync (see sync).
When this memory becomes full, the data is written to the database. The more frequently this happens, the slower the indexing performance becomes and the Oracle Text indexes also become more fragmented. Fragmentation can slow down portal search queries. Small amounts of memory will impact performance and increase index fragmentation, but might be useful when runtime memory is scarce.
A Null value indicates that the default index memory setting is used. This default value is set using the configurable Oracle Text system parameter DEFAULT_INDEX_MEMORY. For more information, see Oracle Text Reference on OTN, http://www.oracle.com/technology/products/text/index.html.
Note:
The memory setting has no effect if the index synchronizes immediately after a commit (get_commit_sync returns true).
p_index - The name of the index. One of the Index Name Constants.
Returns the amount of memory (in bytes) used when synchronizing the specified index.
INVALID_INDEX - The name of the index was not recognized.
INTERNAL_EXCEPTION - An unexpected internal error occurred.
function get_use_doc_index return boolean
Determines whether the Document index is required. See also, Section 10.3.7, "Disabling Document and URL Indexing".
The value is cached for the duration of the session to avoid repeated requests for this information.
Returns true if the Document index is required.
function get_use_url_index return boolean
Determines whether the URL index is required. See also, Section 10.3.7, "Disabling Document and URL Indexing".
The value is cached for the duration of the session to avoid repeated requests for this information.
Returns true if the URL index is required.
function valid_doc_index return boolean
Determines whether the Document index is in a valid, usable state. See also, Section 10.3.7, "Disabling Document and URL Indexing". The function checkindex is called, if it has not yet been called.
The value is cached for the duration of the session to avoid repeated requests for this information.
Returns true if the Document index exists and is valid.
function valid_url_index return boolean
Determines whether the URL index is in a valid, usable state. See also, Section 10.3.7, "Disabling Document and URL Indexing". The function checkindex is called, if it has not yet been called.
The value is cached for the duration of the session to avoid repeated requests for this information.
Returns true if the URL index exists and is valid.
function url_index return boolean
Checks whether the URL index is required (using get_use_url_index) and usable (using valid_url_index).
Returns true if the URL index is both required and valid.
The wwv_context package contains these constants:
Use the following constants to identify the Oracle Text indexes used by Oracle Portal:
Page index - wwv_context.PAGE_TEXT_INDEX
Document index - wwv_context.DOC_TEXT_INDEX
Perspective index - wwv_context.PERSPECTIVE_TEXT_INDEX
Item index - wwv_context.ITEM_TEXT_INDEX
Category index - wwv_context.CATEGORY_TEXT_INDEX
URL index - wwv_context.URL_TEXT_INDEX
PAGE_TEXT_INDEX constant varchar2(30) := 'WWSBR_CORNER_CTX_INDX'
DOC_TEXT_INDEX constant varchar2(30) := 'WWSBR_DOC_CTX_INDX'
PERSPECTIVE_TEXT_INDEX constant varchar2(30) := 'WWSBR_PERSP_CTX_INDX'
ITEM_TEXT_INDEX constant varchar2(30) := 'WWSBR_THING_CTX_INDX'
CATEGORY_TEXT_INDEX constant varchar2(30) := 'WWSBR_TOPIC_CTX_INDX'
URL_TEXT_INDEX constant varchar2(30) := 'WWSBR_URL_CTX_INDX'
The Document and URL indexes uses AUTO_FILTER to convert documents into a plain text format suitable for indexing. Not all document types need to be filtered; some document types can be indexed directly. AUTO_FILTER uses the following settings to determine which documents require filtering:
BINARY_FORMAT - indicates that a document is a format, other than plain text or HTML, but supported by AUTO_FILTER, such as PDF. Such documents are converted into an indexable text format (providing the binary format is supported by AUTO_FILTER).
TEXT_FORMAT - indicates that a document is either plain text or HTML. When specified, the document is not filtered, but might be character set converted.
IGNORE - indicates that a document need not be indexed at all; for example, image files.
Note:
AUTO_FILTER replaces the INSO_FILTER, which is now deprecated.
BINARY_FORMAT constant varchar2(10) := 'BINARY';
TEXT_FORMAT constant varchar2(10) := 'TEXT';
IGNORE constant varchar2(10) := 'IGNORE';
Use these constants for managing Oracle Text maintenance jobs:
SYNC_JOB_PREF - the preference name for storing the synchronization job ID. Used by the index synchronization script textjsub.sql. See also, Section 10.3.5.4, "Scheduling Index Synchronization".
OPTIMIZE_JOB_PREF - the preference name for storing the optimization job ID. Used by the index optimization script optjsub.sql. See also, Section 10.3.5.8, "Scheduling Index Optimization".
SYNC_JOB_PREF constant varchar2(20) := 'text_sync_jobid';
OPTIMIZE_JOB_PREF constant varchar2(20) := 'text_optimize_jobid';
The absolute URL value used to indicate that a row should not be indexed. The URL index is created on the wwsbr_url.absolute_url column and this column is populated by a trigger.
If a URL is not suitable for indexing, such as URLs beginning with javascript:, this constant value is used. See also, Section 10.3.6.2, "Unsupported URLs".
G_NOINDEX constant varchar2(15) := 'wwsbr_noindex'