Deployment Checklist

At the deployment level, you will face a number of common issues. The most optimal approach to these problems will depend on the particular needs of your application. We list the tasks that we think should form the basis of your checklist, and in some cases propose solutions.

• You will need a way to install and de-install your cartridge components. This includes libraries, database objects, flat files, programs, configuration tools, administration tools, and other objects. Explore whether your cartridge might be able to utilize the Oracle Universal Installer and the Oracle Software Packager (see the Oracle Software Packager User's Guide.).

• You should allow for installation of multiple versions of a cartridge to provide backward compatibility and availability. Make use of Oracle's migration facilities as part of your larger strategy.

• You will need to track which cartridges are installed in order to install data cartridges that depend on other data cartridge, or to handle different versions of installed components.

• You will need to provide an upgrade path for migrating to newer versions of cartridges. Make use of Oracle's migration facilities as part of your larger strategy.

• To be able to limit access to cartridge components to specific users and roles, deploy Oracle's security mechanisms together with a blend of procedures that operate under invoker's and definer's rights depending on the need.

• You will need to be able to keep track of which users have access to a cartridge (for ease of administration). Consider making use of a table with appropriate triggers.

• How do you know where cartridges are installed? This is more of a security/administration concern than a requirement. There is currently no easy way of knowing which cartridges are installed in a particular database or what users have access to the cartridge or any of its components.

Naming Conventions

This section discusses how the components of a data cartridge should be named. It is intended for independent software vendors (ISVs) and others who are creating cartridges to be used by others.

Note: Most examples in this manual do not follow the naming conventions, because they are intended to be as simple and generic as possible. However, as your familiarity with the technology increases and you consider building data cartridges to be used by others, you should understand and follow these naming conventions.

The naming conventions in this chapter assume a single-byte character set. "National Language Support" (NLS) described later in this chapterdiscusses other character sets.

Need for Naming Conventions

In a production environment, an Oracle8i database may have multiple data cartridges installed. These data cartridges may be from different development groups or vendors, and may have been developed in isolation. Each data cartridge consists of various schema objects inside the database, as well as other components visible at the operating system level, such as external procedures in shared libraries. If multiple data cartridges tried to use the same names for schema objects or operating system-level entities, the result would be incorrect and inconsistent behavior.

Furthermore, because exception conditions during the runtime operation of data cartridges can cause the Oracle8i server to return errors, it is important to prevent conflicts between error or message codes of different data cartridges. These conflicts can arise if, for example, two cartridges use the same error code for different error conditions. Having unique error and message codes ensures that the origin of the exception condition can be readily identified.

Unique Name Format

To prevent multiple data cartridge components from having the same name, Oracle recommends the following convention to ensure unique naming of data cartridges. Naming is to be done on a per-vendor or per-supplier basis. That is, each organization developing data cartridges must choose an unique name, and Oracle will provide a name reservation service.

Each organization should choose an reserve a prefix. Oracle will add C$ to the start of the string chosen by the organization, to ensure a unique prefix. This prefix can then be used to name the database schema in which the database components of the data cartridge reside, or to name the directory in which the operating-system components of the data cartridge are placed.

Data cartridges and their components should have names of the following format:

C$pppptttm.ccccccccc

The following table describes the parts of this naming convention format.

Table 2-1 Data Cartridge Naming Conventions

Part	Explanation	Example
C$	Recommended by Oracle for all data cartridges.
pppp	Prefix selected by the data cartridge creator. (Must be exactly four characters.)	ACME
ttt	Type of cartridge, using an abbreviation meaningful to the creator. Three characters.	AUD (for audio)
m	Miscellaneous information indicator, to allow a designation meaningful to the creator. One character.	1 (perhaps a version number)
. (period)	Period required if specifying an object in full schema.object form.
ccccccccc	Component name. Variable length.	mf_set_volume (method function adjusting volume)

Oracle recommends that except for the dollar sign ($) as the second character, all characters in the name should be alphanumeric (letters and numbers, with underscores and hyphens permitted).

For example, Acme Cartridge Company chooses and registers a prefix of ACME. It provides an audio data cartridge and a video data cartridge, and chooses AUD and VID as the type codes, respectively. It has no other information to include in the cartridge name, and so it chooses an arbitrary number 1 for the miscellaneous information indicator. As a result, the two cartridge names are:

• C$ACMEAUD1

• C$ACMEVID1

For each cartridge, a separate schema must be created, and Acme uses the cartridge name is the schema name. Thus, all database components of the audio cartridge must be created under the schema C$ACMEAUD1, and all database components of the video cartridge must be created under the schema C$ACMEVID1. Examples of some components might include:

• C$ACMEVID1.mf_rewind

• C$ACMEVID1.vid_ops_package

• C$ACMEVID1.vid_stream_lib

Each organization is responsible for specific naming requirements after the C$pppp portion of the object name. For example, Acme Cartridge Company must ensure that all of its cartridges have unique names and that all components within a cartridge have unique names.

Name Registration

To register the prefix for your organization, send e-mail to the Oracle Data Cartridge Program with your proposed four-character prefix. Send the message to the following address:

dcprog@us.oracle.com

Oracle will send you a confirmation that the prefix (with C$ added at the start) has been reserved for you.

Cartridge Registration

How do you register cartridges and components?

In order to make a naming scheme work, you need to have a registration process that will handle the administration of names of components that make up a data cartridge.

Directory Structure and Standards

You need some directory standard to know where to put your binaries, support files, messages files, administration files, and libraries.

You also need to define a database user who will install your cartridges. One possible solution is to use EXDSYS, for External Data Cartridge System user.

Note: The EXDSYS user is a user with special privileges required for running cartridges. This user could be installed as part of cartridge installation, but would better be part of the database installation. To do this, you will need to move this process into a standard database creation script. Your long range planning should consider ways to integrate directory structure with the Network Computer Architecture (NCA).

Cartridge Upgrades

Administrators need a safe way to upgrade a cartridge and its related meta-data to a newer version of the cartridge. You also require a process for upgrading data and removing obsolete data. This may entail installation support (Enterprise Manager) and database support for moving to newer database cartridge types

Administrators also require a means to update tables using cartridge types when a cartridge changes.

Import and Export

In order to handle the import and export handle objects, you need to understand how Oracle's import and export facilities handle Oracle8i objects. In particular, you need to know how types are handled and whether the type methods are imported and exported, and also whether user defined methods are supported.

Cartridge Versioning

There are two types of cartridge versioning problems that need to be addressed. They are:

• Internal Versioning

• External Versioning

Internal Versioning

Internal versioning is the harder problem. Ideally, you would like a mechanism to support multiple versions of a cartridge in the database. This would provide backward compatibility and also make for high availability.

Types are amenable to changing methods, but not to changing the type attributes themselves. This implies that upgrades are complicated for types that change over time. You may need a way to use multiple versions of type, and some method to insure that administrators can gradually update your technology.

External Versioning

External versioning is the easier of the two versioning problems. You need to be able to track a cartridge version number and be able to take action accordingly upon installation or configuration based on versioning information.

Internationalization

You may want to internationalize your cartridges. This means they will need to be able to support multiple languages and have access to a National Language Support (NLS) facility for messages as well as an NLS facility for parsing. For details on NLS, see the Oracle 8i National Language Support Guide. It includes a chapter on NLS data cartridge service.

It is recommended that the names for data cartridge components be chosen using the ASCII character set.

If you must name the data cartridge components in a character set other than ASCII, Oracle8i will still assign you a four-character unique prefix. This will, however, increase the number of bytes required to hold the prefix. The names of all Oracle schema objects must fit into 30 bytes. In ASCII, this equals 30 characters. If you have, for example, a six-byte character set and request a four-character prefix string, Oracle may truncate your request to a smaller number of characters.

External Access

• How do administrators know who has access to a cartridge?

  Administrators need to administer access rights to internal and external components such as programs and data files to specific users and roles.

Internal Access

• How do administrators restrict access to certain tables, types, views, and other cartridge components to individual users and roles?

  Administrators for security reasons must be allowed to restrict access to types on an individual basis.

  For instance, some data cartridges, such as Oracle's Image Cartridge, have few security issues. These cartridges may grant privileges to every user in the database. Other cartridges that are more complex, such as Oracle' Time Series Cartridge, may need differing security models. In building complex data cartridges, you will need a way to identify the various components that make up a cartridge and also an instance of a cartridge and be able to grant and revoke security roles on identifiable components.

  It may be that Oracle will provide a visual tool will identify components of a cartridge and allow roles be assigned to each component.

Invoker's Rights

Invoker's rights is a special privilege that allows the system to access database objects that it wouldn't normally have access to. This has been the case for the special SYS user. It also will need to be done for cartridges under whatever user you use (e.g. EXDSYS).

If you don't have invoker's rights, then any types you construct in a central user space (e.g. EXDSYS) will have to grant privileges to public, which is not necessarily desirable.

Test and Debug Services

You will need a way to test and debug your cartridges.Please refer to the guides which pertains to your operating environment (PL/SQL, Java, C/C++)

Administration

Configuration

Data Cartridges need a front end to handle deployment issues, such as installation, as well as configuration tools. While each data cartridge may have differing security needs, a basic front end that allows a user to install, configure, and administer data cartridge components is necessary.

This front end may just be some form of knowledge base or on-line documentation. In any case, it should be on-line, easily navigable, and contain templates exhibiting standards and starting points.

Suggested Development Approach

In developing a data cartridge, it is best to take a systematic approach, starting with small, easy tasks and building incrementally toward a comprehensive solution.This section presents a suggested approach.

To create a prototype data cartridge:

1. Read this book and try the examples on disk and in example chapter.

2. Create the prototype of your own data cartridge, creating a single object type and a few data elements and methods. You can add object types, data elements, and methods, specific indextypes, and user-defined operators as you expand the cartridge's capabilities.)

3. Begin by implementing your methods entirely in SQL, and add callouts to 3GL code (if any) later.

4. Test and debug your cartridge.

After you have the prototype working, you may want to follow a development process that includes these steps:

1. Identify your areas of domain expertise.

2. Identify those areas of expertise that are relevant to persistent data.

3. Consider the feasibility of packaging one or more of these areas as a new data cartridge or as an extension to an existing cartridge.

4. Use an object-oriented methodology to help decide what object types to include in data cartridges.

5. Build and test the cartridges, one at a time.