G Using the wwv_context APIs

G.1.1 add_attribute_section

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 only changed if they exist, that is, if they do not exist this procedure does not do anything.

Parameters:

p_attributeId - ID of the attribute section to add.

p_attributeSiteId - Site ID of the attribute section to add.

G.1.2 create_index

procedure create_index(
    p_index in varchar2
) 

Creates a specific, named Oracle Text index. See Section 8.3.3, "Oracle Text Indexes" for more information.

Use this procedure for troubleshooting purposes only. Under normal circumstances, use create_missing_indexes to create all of the indexes that are absent, or createindex to drop invalid indexes and then re-create the preferences and missing indexes.

For this procedure, use one of the following Constants to name the index:

• 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.CATEGPRY_TEXT_INDEX

• URL content index - wwv_context.URL_TEXT_INDEX

Parameters:

p_index - The name of the index to create, that is, one of the constants listed earlier.

Exceptions:

INVALID_INDEX - The name of the index was not recognized.

G.1.3 create_missing_indexes

procedure create_missing_indexes(
    p_indexes out wwsbr_array
) 

Creates all of the Oracle Text indexes that are absent. 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 first mark them as 'requiring reindexing' and then you must synchronize the indexes. To do this, use the procedure touch_index(p_indexes wwsbr_array).

This procedure does not create Oracle Text preferences as these must already exist. Use the procedure create_prefs to create the preferences, if they do not exist.

Parameters:

p_indexes - returns an array containing the list of indexes created.

G.1.4 create_prefs

procedure create_prefs

Creates the Oracle Text preferences, which are used when creating Oracle Text indexes, that is, both Datastore and Filter preferences. See Section 8.3.3.2, "Oracle Text Index Preferences" for more information.

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 Section 8.3.3.5, "Multilingual Functionality (Multilexer)" for more information.

G.1.5 createindex

procedure createindex(
    p_language in  varchar2 default wwnls_api.nls_default_language,
    p_message  out varchar2
) 

Creates Oracle Text indexes used by OracleAS Portal. See Section 8.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 OracleAS Portal content as requiring reindexing, for all new indexes.

• Synchronizes indexes, that is, first populates and then optimizes the indexes.

This procedure is logically 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;

G.1.6 drop_all_indexes

procedure drop_all_indexes

Drops all the Oracle Text indexes used by OracleAS Portal.

This procedure does not drop the Oracle Text preferences. Use the procedure drop_prefs to do this.

G.1.7 drop_index

procedure drop_index(
    p_index in varchar2
) 

Drops a specific, named Oracle Text index. This procedure does not validate that the index exists.

Use one of the following Constants to name the index:

• 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 content index - wwv_context.URL_TEXT_INDEX

Parameters:

p_index - The name of the index to drop, that is, one of the constants listed earlier.

Exceptions:

INVALID_INDEX - The name of the index was not recognized.

G.1.8 drop_invalid_indexes

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 8.3.8, "Viewing the Status of Oracle Text Indexes" for more information.

G.1.9 drop_prefs

procedure drop_prefs

Drops the Oracle Text datastore and filter preferences. See Section 8.3.3.2, "Oracle Text Index Preferences" for more information.

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.

G.1.10 dropindex

procedure dropindex(
    p_language in varchar2 default wwnls_api.nls_default_language,
    p_message  out varchar2
) 

Drops all existing Oracle Text indexes used by OracleAS Portal. See Section 8.3.3, "Oracle Text Indexes" for more information.

This procedure is equivalent to:

wwv_context.drop_prefs;
wwv_context.drop_all_indexes;

G.1.11 optimize

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 OracleAS Portal. Each index is optimized by calling the Oracle Text procedure ctx_ddl.optimize_index().

Indexes are only optimized if they are sufficiently fragmented to make optimization worthwhile. This is measured by the average number of times that a token occurs more than once. If this value is greater than 10, the index is optimized. See Section 8.3.5.5, "Optimizing Oracle Text Indexes" for more information.

The parameters for this procedure are the same as those required by the Oracle Text procedure ctx_ddl.optimize_index.

Parameters:

p_optlevel - Optimization level, one of 'FULL','FAST' or 'TOKEN'.

p_maxtime - Maximum time for full optimization, in minutes.

p_token - Token to optimize (when doing TOKEN optimization).

You will find additional information in the Oracle Text Reference documentation on the Oracle Technology Network, http://www.oracle.com/technology/products/text/index.html.

G.1.12 set_use_doc_index

procedure set_use_doc_index(
p_value in boolean )

Specifies whether the Document index is required. See Section 8.3.7, "Disabling Document and URL Indexing" for more information. Values are cached for the duration of the session to avoid repeated database calls.

Parameters:

p_value - Either 'true' or 'false'. When set to true, the Document index is required.

G.1.13 set_use_url_index

procedure set_use_url_index(
p_value in boolean )

Specifies whether the URL index is required. See Section 8.3.7, "Disabling Document and URL Indexing" for more information. Values are cached for the duration of the session to avoid repeated database calls.

Parameters:

p_value - Either 'true' or 'false'. When set to true, the URL index is required.

G.1.14 sync

procedure sync

Synchronizes all Oracle Text indexes used by OracleAS Portal. Each index is synchronized by calling the Oracle Text procedure ctx_ddl.sync_index(). This procedure reindexes any rows that have been updated since the last synchronization. After synchronization, newly added or updated content can be searched. See Section 8.3.5.1, "Synchronizing Oracle Text Indexes" for more information.

Before synchronization, the pending queue is updated for the table wwsbr_url$ which contains all URLs attribute values stored in OracleAS Portal. Rows from this queue are removed when the URL value is equal to the value of the constant wwv_context_util.g_noindex. These 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 the Oracle Technology Network, http://www.oracle.com/technology/products/text/index.html.

G.1.15 touch_index(p_indexes wwsbr_array)

procedure touch_index(
    p_indexes in wwsbr_array
) 

Touches content for one or more indexes, that is, marks all index content (or indexes) as requiring synchronization by updating the column on which the index is created for every row in the table. See Section 8.3.5.4, "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.

Parameters:

p_indexes - An array containing index names to touch.

G.1.16 touch_index

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, it can be used to touch all indexes, by passing the value null.

This procedure calls touch_index(p_indexes wwsbr_array) mentioned earlier.

See Section 8.3.5.4, "Synchronizing All the Index Content" for more information.

Parameters:

p_index - The name of the index to touch, or null to touch all indexes.

Refer to Section G.1.15, "touch_index(p_indexes wwsbr_array)" for more information.

G.1.17 update_index_prefs

procedure update_index_prefs

Updates the current Oracle Text index datastore preferences. This procedure has an effect when running on an Oracle Database 10g or later.

If datastore preferences are modified after the indexes have been created, the changes are not applied to the indexes automatically. Use this procedure to apply datastore preference changes to Oracle Text indexes.

If one or more indexes are missing, no action is taken for the missing indexes.

G.2.1 checkindex

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 Section 8.3.7, "Disabling Document and URL Indexing" for more information.

The value returned by checkindex is cached for the duration of the session. Whenever a 'true' value is passed to p_force , the status of Oracle Text indexes is re-evaluated, regardless of any previously cached value.

Parameters:

p_force - Either 'true' or 'false'. When set to true, Oracle Text indexes are checked.

Returns:

Returns true if all required indexes exist and are valid.

G.2.2 get_use_doc_index

function get_use_doc_index
return boolean

Determines whether the Document index is required. See Section 8.3.7, "Disabling Document and URL Indexing" for more information.

The value retuned is cached for the duration of the session to avoid repeated requests for this information.

Returns:

Returns true if the Document index is required.

G.2.3 get_use_url_index

function get_use_url_index
return boolean

Determines whether the URL index is required. See Section 8.3.7, "Disabling Document and URL Indexing" for more information.

The value retuned is cached for the duration of the session to avoid repeated requests for this information.

Returns:

Returns true if the URL index is required.

G.2.4 valid_doc_index

function valid_doc_index
return boolean

Determines whether the Document index is in a valid, usable state. See Section 8.3.7, "Disabling Document and URL Indexing" for more information. Function checkindex is called, if it has not yet been called.

The value retuned is cached for the duration of the session to avoid repeated requests for this information.

Returns:

Returns true if the Document index exists and is valid.

G.2.5 valid_url_index

function valid_url_index
return boolean

Determines whether the URL index is in a valid, usable state. See Section 8.3.7, "Disabling Document and URL Indexing" for more information. Function checkindex is called, if it has not yet been called.

The value retuned is cached for the duration of the session to avoid repeated requests for this information.

Returns:

Returns true if the URL index exists and is valid.

G.3.1 Index Name Constants

The following constants can be used in to specify the six Oracle Text indexes used by OracleAS 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 content index - wwv_context.URL_TEXT_INDEX

PAGE_TEXT_INDEX

PAGE_TEXT_INDEX constant varchar2(30) := 'WWSBR_CORNER_CTX_INDX'

DOC_TEXT_INDEX

DOC_TEXT_INDEX constant varchar2(30) := 'WWSBR_DOC_CTX_INDX'

PERSPECTIVE_TEXT_INDEX

PERSPECTIVE_TEXT_INDEX constant varchar2(30) := 'WWSBR_PERSP_CTX_INDX'

ITEM_TEXT_INDEX

ITEM_TEXT_INDEX constant varchar2(30) := 'WWSBR_THING_CTX_INDX'

CATEGORY_TEXT_INDEX

CATEGORY_TEXT_INDEX constant varchar2(30) := 'WWSBR_TOPIC_CTX_INDX'

URL_TEXT_INDEX

URL_TEXT_INDEX constant varchar2(30) := 'WWSBR_URL_CTX_INDX'

G.3.2 URL Unsuitable for Indexing Constant

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 Section 8.3.6.2, "Unsupported URLs" for more information.

G_NOINDEX

G_NOINDEX constant varchar2(15) := 'wwsbr_noindex'