3
Document Viewing

This chapter introduces and describes the various document viewers provided in the ConText Workbench. In particular, this chapter provides configuration and usage information for the Viewer Plugin and Viewer Cartridge.

The following topics are covered in this chapter:

Viewer Control

This section provides setup and usage information for the Viewer Control:

About the Viewer Control

Figure 3-1

The ConText Viewer Control is a 32-bit Windows OCX custom control for use in two-tier client/server configurations. The Viewer Control uses Net8 to retrieve documents from an Oracle8 database and display the retrieved documents using the intended layout and with search terms highlighted. It is delivered with a sample application implemented as a stand-alone container.

A viewed document can be in any of the supported server-side document filter formats. The user can scroll through the document using the Next and Previous buttons to jump to subsequent/previous occurrences of the search term(s).

The Viewer Control currently supports WYSIWYG viewing and query term highlighting in the following formats:

WordPerfect for Windows 5.x, 6.x
WordPerfect for DOS 5.0, 5.1, 6.0
Microsoft Word for Windows 2, 6.x

All other formats supported by ConText are displayed, by default, as plain (ASCII) text; that is, highlighting is retained, but WYSIWYG formatting is lost.

See Also:

For further information about document viewing, see Oracle8 ConText Cartridge Application Developer's Guide

Registering the Viewer Control

The Viewer Control is normally registered automatically during installation. If, for some reason, the Viewer Control has not been registered, the following message will appear when you try to use the ConText Cartridge Workbench Viewer Example:

Can't load (or register) custom control: 'CTXV245.OCX'

In this case, register it manually using the regsvr32 utility (located in ORACLE_HOME\bin). For example:

regsvr32 ctxv245.ocx

Note that the viewer is not unregistered during deinstallation. You must manually unregsiter it using the regsvr32 utility before deinstallation. For example:

regsvr32 /u ctxv32.ocx

Using the Viewer Control

The Viewer Control can be embedded in Windows applications or in HTML pages for display in Internet Explorer using the Object tag.

Note:

Full usage information for the Viewer Control is provided online as a WinHelp file.

Windows Applications

The Viewer Control can be embedded in any application environment that supports custom controls:

as a client-side ActiveX control component in a Windows application, to view a document directly from the viewer's own database connection
as a client/server component in an HTML page as an ActiveX control to view a document directly from the viewer's own database connection
in a helper application to view documents that may be provided by means other than via the viewer's own database connection (see "URL to Invoke a Helper Application" in this chapter)

HTML Pages

To use the Viewer Control in an HTML environment, the browser must support ActiveX controls (e.g. Internet Explorer). In addition, the Viewer Control must be installed, along with the Required Support Files (RSFs), on the machine from which the browser is running.

Viewer Plugin

This section provides setup and usage information for the Viewer Plugin.

About the Viewer Plugin

Figure 3-2

The ConText Viewer Plugin is a client-side Netscape plugin (provided by ConText) that can display many documents on the World Wide Web just as they would appear in their native format.

Note:

To use the Viewer Plugin in a Netscape browser, the Viewer Plugin must be installed on each machine on which the browser is installed.

Supported Formats

The Viewer Plugin actually consists of a set of libraries that provide the means for viewing the document. The plugin currently supports WYSIWYG viewing and query term highlighting in the following formats:

WordPerfect for Windows 5.x, 6.x
WordPerfect for DOS 5.0, 5.1, 6.0
Microsoft Word for Windows 2, 6.x

All other formats supported by ConText are displayed, by default, as plain (ASCII) text; that is, highlighting is retained, but WYSIWYG formatting is lost.

See Also:

For further information about document viewing, see Oracle8 ConText Cartridge Application Developer's Guide

Viewer Cartridge

The Viewer Plugin requires the Viewer Cartridge, which is configured separately on the middle tier and runs under the Oracle Web Application Server Java cartridge. The Viewer Cartridge generates the highlight information for a document, fetches the document from the ConText database, and then sends the document as a file (MIME type "application/x-ctxv") to the Web browser, which uses the Viewer Plugin (if available) to display the document.

However, for MIME types other than the ConText-specific "application/x-ctxv", the Web browser can use its own mapping to invoke a helper application or plugin which can display the ConText-indexed documents natively. In such cases, suitable URLs should be specified for the Viewer Cartridge, thus removing the need for the Viewer Plugin.

Note:

For more information, see "Viewer Cartridge" in this chapter.

Installing the Viewer Plugin

The Viewer Plugin is installed automatically when the ConText Workbench is installed; however, you do not have to install the entire Workbench to install the Viewer Plugin. The Installer allows you to select the Viewer Cartridge as a sub-component of the ConText Workbench and install it individually.

Viewer Plugin Files

When you use the Installer to install the Viewer Plugin, the Viewer Plugin file - called npctxvpi.dll - is automatically placed in the Web browser plugins directory. The required support dlls for the Viewer Plugin are placed in the <ORACLE_HOME>\bin directory.

If no Web browser is installed:

install the Web browser
copy the Viewer Plugin file (npctxvpi.dll) manually from the <ORACLE_HOME>\ctxw\viewer\plugin directory to the Web browser plugins directory

Manual Installation on Multiple Machines

After you install the Viewer Plugin on a machine, if you want to use other machines for viewing, you can either use the Installer to install the Viewer Plugin on each machine or you can manually copy the Viewer Plugin file to the appropriate directory on each machine.

If you choose to manually copy the Viewer Plugin file to other machines, you must also copy the required support dlls to each machine. These support files are provided in a file named ctxvpi.zip, which is in the <ORACLE_HOME>\ctxw\middle\cfgmgr directory on the machine where the Configuration Manager was initially installed.

Copy this file to the Web browser plugins directory on the viewing machine(s), then unzip the files to make the Viewer Plugin available.

Note:

If you require full NLS support on a viewing machine(s), you must use the Installer to perform a full installation on the machine(s).

Activating the Viewer Plugin

To activate the Viewer Plugin file:

Close down all open Web browser sessions (if any),
Start a new Web browser session.

To ensure that the file has been registered, select the Help -> About Plug-ins menu item from Netscape. The Viewer Plugin should appear in the list.

When Is the Viewer Plugin Invoked?

Once installed, the Viewer Plugin is automatically invoked by the Web browser when:

a document with the MIME (Multipurpose Internet Mail Extensions) type "application/x-ctxv" is delivered to the Web browser via the Viewer Cartridge and Oracle Web Application Server, or
a local file with the extension ".ctxv" is loaded into the Web browser

Note:

Before using the Viewer Plugin, the Viewer Cartridge must be installed and configured, and at least one suitable URL must be specified.

For more information, see "Viewer Cartridge" in this chapter.

Viewer Cartridge

This section provides setup and usage information for the ConText Viewer Cartridge:

About the Viewer Cartridge

The Viewer Cartridge is installed as a middle-tier component and runs under the Oracle Web Application Server Java cartridge. Its purpose is to deliver ConText-indexed documents, and other data held in an Oracle database, to Web browsers. These documents can then be viewed in the Netscape browser, either by the supplied Viewer Plugin, or by a helper application.

Note:

The Viewer Cartridge is installed with the ConText Workbench via the Oracle Installer; however, the Installer does not automatically configure the Viewer Cartridge.

Following the installation of the ConText Workbench, the Viewer Cartridge is configured by means of an icon which launches a separate Oracle Installer session.

Uniform Resource Locators (URLs)

URLs are used to tell the Viewer Cartridge (how) to view ConText-indexed documents that come from an Oracle database. When these URLs are specified, a MIME type determines how the documents will be delivered. With the default ConText MIME type, "application/x-ctxv", the Web browser automatically tries to use the Viewer Plugin, if available.

URLs can be used to display documents in various ways. Documents can be viewed full-frame, in a separate window, or to predetermined dimensions.

See Also:

For more information about URLs in the Viewer Cartridge, see "Specifying URLs" and "Using URLs" in this chapter.

Realms and Configuration Files

Access to ConText-indexed documents can be restricted through the Oracle Web Application Server by the use of realms.

A Viewer Cartridge configuration file is used to determine how the Viewer Cartridge connects to the database. Multiple configuration files can be used to allow different database connection details to be protected by different realms. This allows varying levels of security to be applied to realms containing particular documents.

See Also:

For more information about using realms, see "Security Mechanisms" in this chapter.

For more information about configuration files, see "Configuration Files" in this chapter.

Configuration Requirements

Before you configure the Viewer Cartridge, ensure the following requirements are met:

Oracle8 is installed and a database instance started
if the Oracle8 database is installed on a different machine than the current machine (i.e. the machine from which you are performing the Viewer Cartridge configuration), a Net8 alias for the Oracle8 database must be created on the current machine
Oracle8 ConText Cartridge is installed and at least one ConText server with the DDL (D) personality is started
Oracle WebServer (or Web Application Server), release 2.1.0.3.2 or higher, is installed and at least one runtime listener and one admin listener is started
if Oracle WebServer (or Web Application Server) is installed on a different machine than Oracle8, a Net8 alias for the Oracle8 database must be created on the WebServer machine
Oracle JDBC driver, release 7.3.3.1.3 or higher, is installed

If you need to install an Oracle JDBC driver, note the connection requirements during installation. These are used when writing additional configuration file entries.

To obtain a JDBC driver, either navigate to www.oracle.com, look for the free software page, and choose the Oracle JDBC option. Or navigate directly to the page; currently it is:

www.oracle.com/products/free_software/

Otherwise, you can use an alternative driver.

See Also:

For more information about configuration files, see "Configuration Files" in this chapter.

For more information about alternative JDBC drivers, see "Using an Alternative Oracle JDBC Driver" in this chapter.

Configuring the Viewer Cartridge

Configuration of the Viewer Cartridge involves:

configuring Web Application Server and specifying database connection information (performed by the Installer)
copying required files from the current machine to the machine on which Web Application Server is installed (performed by you or the Installer)

Note:

If configuration of WebServer/Web Application Server for the Viewer Cartridge fails, you can manually configure WebServer/Web Application Server.

In addition, deconfiguration procedures can be applied to manually remove the Viewer Cartridge from the appropriate release of WebServer/Web Application Server.

For more information, see Appendix A, "Viewer Cartridge: Manual Configuration".

Local and Remote Configurations

If Web Application Server is installed on the current machine (i.e. the machine from which Viewer Cartridge configuration is performed), this is considered a 'local' configuration.

If Web Application Server is not installed on the current machine, this is considered a 'remote' configuration.

Configuration Procedure

Configuration is carried out via two Oracle Installer dialog boxes:

Oracle8 ConText Cartridge Viewer Cartridge Setup
Remote Web Application Server (appears only for remote configurations)

Note:

Viewer Cartridge configuration is identical regardless of whether Oracle WebServer or Web Application Server is installed. For convenience purposes, the following configuration procedure assumes Web Application Server is installed; however, WebServer can be inserted wherever Web Application Server appears.

To configure the ConText Viewer Cartridge:

Click on the 'Viewer Cartridge Setup' icon in the ConText Cartridge Workbench program group

Choose Start > Programs > ConText Cartridge Workbench - [HOME_NAME] > Viewer Cartridge Setup.

The Oracle Installer starts and the Oracle8 ConText Cartridge Viewer Cartridge Setup dialog box appears:

Enter the appropriate information in each of the fields, and click OK:

Field¹ Description

Web Application Server

Machine name

Enter the machine name on which Web Application Server is installed. By default, the name of the current machine appears.
If you are performing a local configuration (i.e. Web Application Server is installed on the current machine), use the default.
If you are performing a remote configuration, enter the name of the remote machine on which Web Application Server is installed.

Admin listener port

Enter the port number of the admin listener for Web Application Server. The default ('8888') is the default admin listener port for Oracle Web Application Server 3.0.

Admin listener user and password

Enter the username and password for the admin listener. The default username ('admin') is the default for Oracle Web Application Server 3.0.

Listener name

Enter the name of an existing runtime listener for Web Application Server. The default ('www') is the default runtime listener name for Oracle Web Application Server 3.0 on NT.
Other runtime listener name defaults include:
weblsn (WebServer 2.1 on Unix)
websvr (WebServer 2.1 on Unix)

Database

User/Password

Enter the username and password for the owner of the Viewer Cartridge. The default username is CTXSYS.

Connection alias

Enter the Net8 alias (database connection) to the Oracle8 database for Web Application Server.
There can be several database connections for the Viewer Cartridge. This field allows you to enter an alias for the default database connection. The username/password and connection alias are combined to define the default connection for access by the URL for the Viewer Cartridge.
The alias that you enter here is used as the first entry in the list of connections in the configuration file. After configuration of the Viewer Cartridge, you can add further entries to this configuration file if you wish (see "Configuration Files" in this chapter).
Note: The alias that you enter here is not the alias between the current machine and Oracle8 machine.

¹ Ask your web server administrator for assistance with these values.

If a local configuration is being performed (i.e. Web Application Server is installed on the current machine), go to Step 9. Otherwise, the Remote Web Application Server dialog box appears:

Select the platform of the remote machine on which Web Application Server is installed.
In a remote configuration, certain files required by the Viewer Cartridge must be copied to the remote machine on which Web Application Server is installed. The files are initially located in the following directory:

Field¹	Description
Web Application Server
Machine name	Enter the machine name on which Web Application Server is installed. By default, the name of the current machine appears. If you are performing a local configuration (i.e. Web Application Server is installed on the current machine), use the default. If you are performing a remote configuration, enter the name of the remote machine on which Web Application Server is installed.
Admin listener port	Enter the port number of the admin listener for Web Application Server. The default ('8888') is the default admin listener port for Oracle Web Application Server 3.0.
Admin listener user and password	Enter the username and password for the admin listener. The default username ('admin') is the default for Oracle Web Application Server 3.0.
Listener name	Enter the name of an existing runtime listener for Web Application Server. The default ('www') is the default runtime listener name for Oracle Web Application Server 3.0 on NT. Other runtime listener name defaults include: weblsn (WebServer 2.1 on Unix) websvr (WebServer 2.1 on Unix)
Database
User/Password	Enter the username and password for the owner of the Viewer Cartridge. The default username is CTXSYS.
Connection alias	Enter the Net8 alias (database connection) to the Oracle8 database for Web Application Server. There can be several database connections for the Viewer Cartridge. This field allows you to enter an alias for the default database connection. The username/password and connection alias are combined to define the default connection for access by the URL for the Viewer Cartridge. The alias that you enter here is used as the first entry in the list of connections in the configuration file. After configuration of the Viewer Cartridge, you can add further entries to this configuration file if you wish (see "Configuration Files" in this chapter). Note: The alias that you enter here is not the alias between the current machine and Oracle8 machine.

ORACLE_HOME\ctxw\middle\ctxvcart\remote

The files must be copied to the following directory structure on the remote machine:

ORACLE_HOME/ctxw/middle/ctxvcart

Note:

The 'remote' subdirectory is not required on the remote machine.

Select how you want to copy the required files to the Web Application Server machine:

Automatically - the Oracle Installer copies the required files to the appropriate directory for you

You can select 'Automatically' only if Web Application Server is installed on a machine that is mounted to the current machine. If you select this option, you must also specify the directory on the current machine to which the ORACLE_HOME on the Web Application Server remote machine is mounted.

Manually - you must copy the files manually to the appropriate directory on the remote machine after configuration is completed

Note:

If the remote machine is not running Windows NT, all file and directory names must be in lowercase on the remote machine.

Enter the Net8 alias between the current machine and the machine on which Oracle8 is installed. Note that this alias is not the alias between the Web Application Server machine and the Oracle8 machine.
Click OK.
If you chose 'Manually' in Step 5, copy the required files from the current machine to the remote machine.
Shut down and restart all Web Application Server listeners and services.

Specifying URLs

To be able to use the Viewer Cartridge for viewing ConText-indexed documents from an Oracle database, you need to specify URLs and embed them into HTML pages.

These URLs must contain sufficient information for the Web Request Broker to direct the request to the Viewer Cartridge. The Viewer Cartridge can then generate the following to service the request: a database connection, parameters that define what the document is, plus any highlight information that is necessary.

Parameters to the URL can be encoded within the URL (via the HTML GET attribute), or supplied through HTML form fields (via the HTML POST attribute).

URLs for Viewing Highlighted Documents

To get a representation of a highlighted document (in WYSIWYG, if supported, or in ASCII, if WYSIWYG is not supported), use the URL parameters as follows (no spaces allowed):

http://<host>/<virtual_path>/CtxwViewCart?colspec=<policy>&textkey=<textkey>[&conf=<config_
section_name>]&queryex=<query>

where:

<host>

is the Internet name of the host running the Oracle Web Application Server

<virtual_path>

specifies the Viewer Cartridge alias (virtual path). ctxwview is the installed virtual path that maps onto the Viewer Cartridge default realm (ctxview_realm). Note that multiple configuration files can be created to allow different database connection details to be protected by different realms. In that case, the appropriate virtual path to the Viewer Cartridge must be specified. See "Security Mechanisms" and "Configuration Files" in this chapter.

CtxwViewCart

is the name of the Java class that provides the entry point to the Viewer Cartridge; always CtxwViewCart

<policy>

specifies the ConText indexing policy to use

<textkey>

specifies the textkey column value identifying the document to be retrieved

<config_section_name>

optionally identifies a section name from the appropriate configuration file

<query>

optionally specifies a query expression

URLs for Viewing Unhighlighted Documents

To get a WYSIWYG display of an unhighlighted document, the correct MIME type must be mapped to the appropriate application in the Netscape web browser. The browser can then use this mapping to invoke a helper application or plugin to handle the data. The syntax is (no spaces allowed):

http://<host>/<virtual_
path>/CtxwViewCart?colspec=<policy>&textkey=<textkey>[&mimetype=<mimetype>][&conf=<conf_section_name>]

where:

<host>

is the Internet name of the host running the Oracle Web Application Server

<virtual_path>

specifies the Viewer Cartridge alias (virtual path). ctxwview is the installed virtual path that maps onto the Viewer Cartridge default realm (ctxview_realm). Note that multiple configuration files can be created to allow different database connection details to be protected by different realms. In that case, the appropriate virtual path to the Viewer Cartridge must be specified (See "Security Mechanisms" and "Configuration Files" in this chapter).

CtxwViewCart

is the name of the Java class that provides the entry point to the Viewer Cartridge; this is always CtxwViewCart

<policy>

specifies the ConText indexing policy to use

<textkey>

specifies the textkey column value identifying the document to be retrieved

<mimetype>

specifies the appropriate MIME type that has been set up in the web browser to enable the document to be viewed in its original, unhighlighted form. If mimetype is omitted, the default MIME type "application/x-ctxv" is assumed, and the browser tries to view the document via the Viewer Plugin, if available. If the document is in a non-supported format, the plugin cannot display it in WYSIWYG.

<conf_section_name>

optionally identifies a section name from the appropriate configuration file

Example

Here, the MIME type for Word has been mapped in the web browser (as "application/msword"). A URL is then set up to retrieve and display an original Word document. No spaces are allowed:

http://<host>/ctxwview/CtxwViewCart?colspec=ctxcm_help_pol&textkey=HELP_
POL&mimetype=application/msword&conf=DEFAULT

URL for Viewing Original Documents

If the document in its original, unhighlighted form is required (without using ConText), and is stored internally in the database - that is, not URL or external data store - it is more efficient to go directly to the base table.

The following URL example displays a document from the table field defined by <table_name>, <column_name> and <where_clause> as these elements would appear in a SQL select statement. No spaces are allowed:

http://<host>/<virtual_path>/CtxwViewCart?table=<table_name>&column=<column_name>&where=<where_
clause>[&mimetype=<mimetype>][&conf=<config_section_name>]

where:

table=<table_name>

table specification

column=<column_name>

column to fetch

where=<where_clause>

row selection

[mimetype=<mime_type_string>]

specifies an appropriate MIME type that has been set up in the web browser to enable the document to be viewed in its original, unhighlighted form. If mimetype is omitted, the MIME type defaults to "application/octet-stream" for binary data and "text/plain" for textual data.

[conf=<config_section_name>]

optionally identifies a section name from the appropriate configuration file

Using URLs

Once suitable URLs have been specified, they can be used in HTML in various ways:

URL as a Link Target

When you use URLs as a link target, highlighted documents are viewed full-frame if the Viewer Plugin has been installed on the client. The frame is resizable, but plugin parameters cannot be specified.

Documents of other MIME types (such as jpeg files) are also supported. These are downloaded and viewed on the client by the best means available to the browser for that MIME type.

URL in an Embedded Plugin Tag

When you use a URL in an embedded plugin tag, you can specify EMBED tag parameters that can be passed to the plugin. These parameters are included within an EMBED tag in the appropriate HTML page and they determine how a document is viewed. The parameters fall into two categories:

Standard HTML Parameters
Private Viewer Plugin Parameters

Note:

Only documents of the MIME type "application/x-ctxv" are supported.

Standard HTML Parameters

For details of the many available standard HTML parameters, refer to your preferred HTML reference source. The most important of the standard HTML parameters are src, which specifies the URL string, and pluginspage, which for our purposes is used to provide the location of the Viewer Plugin archive.

The dimensions of the plugin display are pre-determined. However, the height and width of the document view can be reset by the height and width tag parameters.

Typical syntax within the EMBED tag would be:

src="http://<host>/<virtual_
path>/CtxwViewCart?colspec=<policy>&queryex=<query>&textkey=<tkey>[&conf=<sectio
n>]"
[conf=<section>]
height="nnn" width="nnn"
pluginspage="/ctxw_cm/ctxvpi.zip"
[<optional_private_params>]>

where:

src

specifies the string of standard parameters (as described in "Using URLs" in this chapter). The src attribute value (everything between the double-quotes) must not contain any spaces.

[conf=<section>]

Optional. conf is used to indicate the name of the section in the configuration file that is to be used for database connection data. This parameter defaults to use the [DEFAULT] section.

nnn

is a positive number, in pixels, that determines the height and width of the document view

pluginspage

states where the Viewer Plugin was placed by default when the Configuration Manager was installed; used to provide the location of the plugin archive for an 'install-on-demand' mechanism

<optional_private_params>

is where the private Viewer Plugin parameters are specified (See "Private Viewer Plugin Parameters" in this chapter).

Example:

The following example from the Configuration Manager (View Data form) uses the Viewer Plugin to display a document from the table field implied by the policy and textkey, and uses the query to highlight hit words:

<table border="2" cellpadding="0" cellspacing="0"> 
<tr> 
<td align="center"><EMBED 
src="/ctxwview/CtxwViewCart?colSpec=CTXSYS.CTXCM_HELP_POL&queryEx=(++{policy})+
&textKey=HELP_POL&conf=bugdb" 
align="baseline" border="0" width="556" height="330" 
pluginspage="/ctxw_cm/ctxvpi.zip"><NOEMBED>[OCO Viewer Plugin]</NOEMBED></td> 
</tr> 
</table>

The src attribute value (everything between the double-quotes) must not contain any spaces.

The value bugdb refers to a section contained in the sample configuration file documented in this chapter.

See Also:

For more information, see "Configuration Files" in this chapter.

Private Viewer Plugin Parameters

You can specify optional private Viewer Plugin parameters to be included within the EMBED tag on the HTML page. Like the standard HTML parameters, these influence various aspects of how the document is viewed. These are:

toolbar=true|false
silenterrors=true|false
idleinterval=<n>
shortcutmenu=true|false
pageview=true|false

where:

toolbar

If toolbar is set to true, the toolbar is shown. The default is true.

silenterrors

If silenterrors is set to true, it suppresses error information dialog boxes. The default is false.

idleinterval

represents a value (in milliseconds) between 1 and 500 that sets the interval between document section reads. The default is 50. A value of 0 means that there is no idle time reading of document sections.

shortcutmenu

If shortcutmenu is set to true, you can click the right mouse button on the viewer window to obtain a short-cut menu. The default is true.

pageview

If pageview is set to true, the plugin will attempt to represent the document page as the page would appear when printed. The default is false.

Example:

<p> 
<embed width=600 height=400 pluginspage="http://fred.uk.oracle.com/" 
src="file:///C|/WINNT/Profiles/jbloggs/Desktop/test files/test.ctxv" 
toolbar=true silenterrors=true idleinterval=5 shortcutmenu=false pageview=true 
hidden=false> </embed> 
</p>

Notice the use of a local file in the src parameter.

URL to Invoke a Helper Application

URLs can be used to invoke a helper application to display the document in a separate window as a separate process. However, the mapping between the helper application's MIME type and the program to be executed must have been defined in the Netscape browser. Only then can the helper application be used to display the document.

For example, the URL can be used as a link URL where a MIME type is mapped to the ConText Cartridge Viewer Example that uses the Viewer Control. The ConText Cartridge Viewer Example is then used as a helper application. The Viewer Example is delivered as part of the ConText Workbench, and is accessible via the installed icon called 'ConText Cartridge Viewer Example'.

Security Mechanisms

A realm is a group of users and (other) groups assigned by an authentication scheme to regulate access to specific documents and directories through the Oracle Web Application Server. Access to ConText-indexed documents can be restricted by using realms.

Authentication schemes allow you to define named groups of user name/password combinations, and named realms that are groups of these groups. You can then assign user, group, and realm names to virtual files and directories, requiring any client requesting access to input one of the specified username/password combinations.

This way, some groups can be granted access to ConText-indexed documents that are held in a variety of databases, while access can be denied to other groups.

To restrict access through realms:

Map a virtual path to a realm through the Oracle Web Application Server Administration pages.
Map that virtual path to the Viewer Cartridge through the Oracle Web Application Server Administration pages.
Create the configuration files to which the virtual paths are mapped.

If the virtual path contains more than one element, the last element is used to map onto the name of the configuration file. In this manner, each realm can have a separate configuration file. This ensures that users in groups with access to one realm can be denied access to information available in other realms.

Enter the connection details into the configuration file (using the conf URL parameter) for each database connection that is within that realm.
Specify URLs using the appropriate virtual paths.

See Also:

For more information about using the Oracle Web Application Server Administration pages, see Appendix A, "Viewer Cartridge: Manual Configuration", and also the Oracle Web Application Server documentation.

For more information about the configuration file, see "Configuration Files" in this chapter.

For more information about specifying URLs, see "Specifying URLs" in this chapter.

Configuration Files

The following section describes Viewer Cartridge configuration files. The Viewer Cartridge uses configuration files to determine how the cartridge connects to a database. Each configuration file contains one or more sections that describe the database connection, including the username/password, database details, and JDBC driver to be used.

Default Configuration File

The default configuration file (CTXVCART.CFG) is installed when the Viewer Cartridge is configured. It is installed on the same tier as the Web Application Server, in the following directory:

$ORACLE_HOME/ctxw/middle/ctxvcart

You can edit this default file if you wish; however, if you need to allow different database connection details to be protected by different realms, you must create additional configuration files.

Multiple Configuration Files

Multiple configuration files can be created to allow different database connection details to be protected by different realms. These files can be used instead of, or in conjunction with, the default file CTXVCART.CFG.

All configuration files must reside on the same tier as the Web Application Server, in the following directory:

$ORACLE_HOME/ctxw/middle/ctxvcart

You create multiple configuration files as text files, giving each file the same name as the last element of the applicable virtual path of the Viewer Cartridge, plus a mandatory .cfg extension.

For example:

Virtual Path Configuration File

/ctxview

ctxvcart.cfg (the default)

/ctxview/secure

secure.cfg

/ctxview/public

public.cfg

Virtual Path	Configuration File
/ctxview	ctxvcart.cfg (the default)
/ctxview/secure	secure.cfg
/ctxview/public	public.cfg

Configuration File Syntax

Each configuration file consists of one or more sections, each section representing a different database connection with its details.

Each section must start with a section name enclosed within square brackets and contains a number of parameters associated with that section.

A section name is specified in a URL by means of the conf parameter (See "Using URLs" in this chapter).

Lines that contain non-standard parameter names are ignored. If one or more parameters of the same name are found within one section, the value associated with last one is used. A value cannot be split over more than one line.

The section syntax is as follows:

[<section_name>]
username=<user_name>
password=<password>
database=<database_specification>
driver=<Java_class>
subprotocol=<subprotocol>

where:

[<section_name>]

names the section. The name is enclosed by square brackets. Duplicate section names are not allowed in the same configuration file. The default configuration file has the section name [DEFAULT].

Each section ends when the next section name is met, or when the end of the file is reached.

See Also:

For information on how the conf parameter is used to point to a section name in a configuration file when using a URL, see "Specifying URLs" in this chapter.

username

specifies the name of the Oracle user that the database connection uses. Defaults to CTXSYS.

password

specifies the password of the Oracle user. Cannot be null.

database

depends on the value of the subprotocol parameter.

For any subprotocol, a full connect descriptor, as used in tnsnames.ora files, can be used. For example:

database=(DESCRIPTION=(ADDRESS=(COMMUNITY=DECCOM.FIN.HQ.ACME)(PROTOCOL=DECNET)(NODE=NY_
VAX.FIN.HQ.ACME)(OBJECT=LSNR))(CONNECT_DATA=(SID=DB1)(GLOBAL_NAME=NY_FIN.FIN.HQ.ACME)))

For the oci7 or oci8 subprotocol, a service name present in a tnsnames.ora file can be used.

For the thin protocol, a value in the form <host>:<port>:<sid> can be used. For example:

hq_server:1521:ORCL

If database is null, it defaults to the installation's default database.

driver

specifies the Java class name of the JDBC driver (of release 7.3.3.1.3 or later). It should always be:

oracle.jdbc.driver.OracleDrive

subprotocol

should be assigned one of the following values:

oci7 | oci8 | thin

If the subprotocol parameter name does not appear within the section, a default of oci7 is used.

Note:

For more information about the values you can specify for the database, driver, and subprotocol parameters, see the documentation for the JDBC driver that you are using. As this information is liable to change, you must look in the JDBC driver readme.txt file and modify the configuration file as appropriate.

Sample Configuration File

This sample file contains three sections: DEFAULT, bugdb, and live. Each section denotes a different database connection.

[DEFAULT] 
username=ctxwvcart 
password=ctxwvcart 
database=(DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (COMMUNITY = tcp.uk) 
(PROTOCOL = TCP) (Host = bris_nt_001) (Port = 1521)) (ADDRESS = (COMMUNITY = 
tcp.world) (PROTOCOL = TCP) (Host = bris_nt_001) (Port = 1526))) (CONNECT_DATA 
= (SID = ORCL))) 
subprotocol=oci7 
driver=oracle.jdbc.driver.OracleDriver 
Note_1=  To connect to a non-default database :- 
Note_2=    1. Add a new section with the new database details (ensure to use a 
unique section name) 
Note_3=    2. Connect to the database as ctxsys and type 'grant select on 
ctxw_message to ctxuser'  
 
[bugdb] 
username=bu1203 
password=he11o 
database=hg_bug:1527:orcl 
subprotocol=thin 
 
[live] 
username=web_user 
password=we8_user 
database=live_quotes 
subprotocol=oci8 
driver=oracle.jdbc.driver.OracleDriver

Using an Alternative Oracle JDBC Driver

It is possible that your driver is not suitable for the platform you are using. To use an alternative Oracle JDBC driver:

Install the alternative driver into the Oracle WebServer's <ORACLE_HOME>.
Modify the Viewer Cartridge CLASSPATH to include a path to (the zip archive containing) the class file root directory.
Modify the Viewer Cartridge LD_LIBRARY_PATH to include a path to the directory containing any native library object files required by the driver.

See Also:

For more information about modifying the CLASSPATH and LD_LIBRARY_PATH, see Appendix A, "Viewer Cartridge: Manual Configuration".

Modify the configuration file that contains the section referred to by the conf parameter in the URL by tailoring the following configuration file parameters:

database=<instance_specification>
driver=<fully_qualified_driver_class_name>
subprotocol=<oci7|oci8|thin>

See Also:

For more information about the values you can specify for the database, driver, and subprotocol parameters, see the documentation for the JDBC driver that you are using. Also refer to "Configuration File Syntax" in this chapter.

Library

Product

Contents

Index

3 Document Viewing

Viewer Control

About the Viewer Control

Figure 3-1

Registering the Viewer Control

Using the Viewer Control

Windows Applications

HTML Pages

Viewer Plugin

About the Viewer Plugin

Figure 3-2

Supported Formats

Viewer Cartridge

Installing the Viewer Plugin

Viewer Plugin Files

Manual Installation on Multiple Machines

Activating the Viewer Plugin

When Is the Viewer Plugin Invoked?

Viewer Cartridge

About the Viewer Cartridge

Uniform Resource Locators (URLs)

Realms and Configuration Files

Configuration Requirements

Configuring the Viewer Cartridge

Local and Remote Configurations

Configuration Procedure

Specifying URLs

URLs for Viewing Highlighted Documents

URLs for Viewing Unhighlighted Documents

Example

URL for Viewing Original Documents

Using URLs

URL as a Link Target

URL in an Embedded Plugin Tag

Example:

Private Viewer Plugin Parameters

Example:

URL to Invoke a Helper Application

Security Mechanisms

Configuration Files

Default Configuration File

Multiple Configuration Files

Configuration File Syntax

Sample Configuration File

Using an Alternative Oracle JDBC Driver

3
Document Viewing