G Using the wwv_context APIs

The wwv_context package contains procedures to create and maintain Oracle Text indexes used by OracleAS Portal. This appendix describes the content of this package in the following sections:

Procedures
Constants
Exceptions

Note:
For more information about Oracle Text indexes and their use in OracleAS Portal, see Chapter 8, "Configuring the Search Features in OracleAS Portal".

G.1 Procedures

The wwv_context package contains these procedures:

add_attribute_section

create_index

create_missing_indexes

touch_index(p_indexes wwsbr_array)

touch_index

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. For more information, see Section 8.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 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 re-indexing' 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. For more information, see Section 8.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. For more information, see Section 8.3.3.5, "Multilingual Functionality (Multilexer)".

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. For more information, see Section 8.3.3, "Oracle Text Indexes".

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 re-indexing, 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.CATEGPRY_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. For more information, see Section 8.3.7, "Viewing the Status of Oracle Text Indexes".

G.1.9 drop_prefs

procedure drop_prefs

Drops the Oracle Text datastore and filter preferences. For more information, see Section 8.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.

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. For more information, see Section 8.3.3, "Oracle Text Indexes".

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. For more information, see Section 8.3.5.5, "Optimizing Oracle Text Indexes".

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'll find additional information in the Oracle Text Reference documentation on the Oracle Technology Network, http://otn.oracle.com/products/text/content.html.

G.1.12 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 re-indexes any rows that have been updated since the last synchronization. After synchronization, newly added or updated content can be searched. For more information, see Section 8.3.5.1, "Synchronizing Oracle Text Indexes".

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'll find additional information on ctx_ddl.sync_index in Oracle Text Reference documentation on the Oracle Technology Network, http://otn.oracle.com/products/text/content.html.

G.1.13 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. For more information, see Section 8.3.5.4, "Synchronizing All the Index Content".

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.14 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.

For more information, see Section 8.3.5.4, "Synchronizing All the Index Content".

Parameters:

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

For more information, refer to touch_index(p_indexes wwsbr_array)described in Section G.1.13.

G.2 Constants

G.2.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.2.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. For more information, see Section 8.3.6.2, "Unsupported URLs".

G_NOINDEX

G_NOINDEX constant varchar2(15) := 'wwsbr_noindex'

G.3 Exceptions

INVALID_INDEX

The name of the index was not recognized.

INVALID_INDEX exception