|Oracle9i Data Cartridge Developer's Guide
Release 1 (9.0.1)
Part Number A88896-01
This chapter describes a recommended development process, including relationships and dependencies among parts of the process. Topics include:
The simplest questions are the most profound: Who? What? When? Where? How? You could say that this chapter is concerned with the when and where of how. But before we examine the road-map to building data cartridges, it would be wise to give a moment to viewing the project as a whole.
The very first step in developing a data cartridge is to establish the domain-specific value you intend to provide. Clearly define the new capabilities the cartridge will make available. More specifically: What are the objects that cartridge will expose to users as a means to accessing to these capabilities?
Who are the intended users of this cartridge? Are they other developers -- in which case the extensibility of the cartridge is of crucial importance. Are they end- users -- in which case the cartridge must be highly attuned to the domain in question. Building a cartridge is a non-trivial project that should be founded in a business model that clearly distinguishes who these users are.
Being realistic about the complexity of building a data cartridge, raises the question of who it is that will perform the task. Are all the necessary skills present in the development team? Most essentially, the developers (be they one or many) must be able to bridge the object-relational database management system with the domain.
What are the deliverables? How much time is there for development? Is there a software development process? The project is much more likely to succeed if there are clearly defined expectations and milestones. This chapter should aid you in mapping out a realistic development path.
Choose and design objects so that their names and semantics are familiar in the developer's and users' domain. Given the complexity of the project, you should consider using one of the standard object-oriented design methodologies.
In defining a collection of objects, give care to the interface between the SQL side of object methods and the 3GL code that incorporates your value-added technology. Keep this interface as simple as possible by limiting the number of methods that call out to library routines and by allowing the 3GL code to do a block of work independently. Avoid defining hundreds of calls into low-level library entry points.
With this interface defined, you can proceed along parallel paths, as illustrated in Figure 2-1. You can complete the paths sequentially or alternately work among the paths until you complete all three.
The 'leftmost' of these parallel paths packages any existing 3GL code that performs operations relevant to your domain in a DLL, possibly with new entry points on top of old code. The DLL will be called by the SQL component of the object's method code. Where possible, this code should all be tested in a stand-alone fashion using a 3GL test program.
The 'middle' path defines and writes the object's type specification and the PL/SQL components of the object's method code. Some methods may be written entirely in PL/SQL, while others may call into the external library. If your application requires an external library, provide the library definition and the detailed bindings to library entry routines.
The direction you take at the choice point results from the simplicity or complexity of the access methods you need to deploy, which in turn derives from the nature of the data as represented by columns in the table. If you the methods you need to query your data are relatively simple, you can build regular indexes. By contrast, dealing with complex data means you will need to define complex index types as the basis for making use of Oracle's extensible indexing technology. If you are in addition faced with implementing multi-domain queries, you should choose to make use of Oracle's extensible optimizer technology.
It may be that you do not have execute queries on multiple domains. If I/O is the only significant factor affecting performance, you can make use of standard optimizing techniques. If, however, there are other factors in play, you may still need to utilize the extensible optimizer.
Finally, you will want to test the application and create the necessary installation scripts.
Before you can use a data cartridge, you must install it. Installation is the process of assembling the sub-components so that the server can locate them and understand the object type definitions.
Putting the sub-components in place involves defining object types and tables in the server (usually accomplished by running SQL scripts), putting dynamic link libraries in the location expected by the linkage specification, and copying on-line documentation, help files, and error message files to a managed location.
Telling the server about the object types involves running SQL scripts that load the individual object types defined by the cartridge. This step must be done from a privileged account.
Finally, users of the cartridge must be granted the necessary privileges to use it.
The following requirements and guidelines apply to certain database objects associated with the data cartridge.
The database components that make up each cartridge must be installed in a schema of the same name as the cartridge name. If a cartridge needs multiple schemas, the first 10 characters of the schema must be the same as the cartridge name. Note that the maximum permissible length of schema names in Oracle is 30 bytes (30 characters in single-byte languages.)
The following database components of a data cartridge must be placed in the cartridge schema:
The choice of a schema name determines the Oracle username, because the schema name and username are always the same in Oracle.
Some database-level constituents of cartridges may be global in scope, and so not within the scope of a particular user (schema) but visible to all users. Examples of such globals are:
All globals should start with the cartridge name. For example, a global role for the Acme video cartridge should have a unique global name like C$ACMEVID1ROL1, and not merely ROL1.
Currently, error codes 20000-20999 are reserved for user errors or application errors. When a cartridge encounters an error, it should generate an error of the form ORA 20000: %s, where %s is a place holder for a cartridge-specific error message. Cartridge developers must ensure that their error messages are unique. You can ensure uniqueness by having all cartridge-specific error messages consist of a cartridge message name in the format C$pppptttm-nnnn plus message text. For example, an error raised by the Acme video cartridge might reported as:
In this example:
ORA 20000is the server error code.
C$ACMEVID1is the cartridge name.
0001is the number assigned by Acme for this specific error.
No such fileis the description of the error, as written by Acme.
In many cases, a cartridge installation directory is desirable. All the operating system-level components of the cartridge, such as shared libraries, configuration files, and so on, can be put under a directory that is specific to a vendor or organization.
This directory name should be the same as the prefix chosen by the organization, and the directory should be created under the root directory for the platform. For example, if the Acme Cartridge Company needs to store any files, libraries, or directories, it must create a directory /ACME, and then store any files in cartridge-specific subdirectories.
Message files that associate cartridge error or message numbers with message text can be put in one or more cartridge-specific subdirectories.
Configuration files can be placed in a cartridge-specific subdirectory. For example:
Use one of the following guidelines for each shared library (.so or .dll file):
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.
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.
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. See "Internationalization" for a discussion of using other character sets.
In a production environment, an Oracle 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 Oracle 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.
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:
The following table describes the parts of this naming convention format.
Recommended by Oracle for all data cartridges.
Prefix selected by the data cartridge creator. (Must be exactly four characters.)
Type of cartridge, using an abbreviation meaningful to the creator. Three characters.
AUD (for audio)
Miscellaneous information indicator, to allow a designation meaningful to the creator. One character.
1 (perhaps a version number)
Period required if specifying an object in full schema.object form.
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:
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:
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.
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.
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.
Your long range planning should consider ways to integrate directory structure with the Network Computer Architecture (NCA).
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.
To import and export objects, you need to understand how Oracle's import and export facilities handle Oracle 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.
There are two types of cartridge versioning problems that need to be addressed. They are:
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 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.
You may want to internationalize your cartridges. This means they will need to be able to support multiple languages and have access to Globalization Support facilities for messages and parsing. For details on Globalization Support, see the Oracle9i Globalization Support Guide. It includes a chapter on the Globalization Support 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, Oracle 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.
Administrators need to administer access rights to internal and external components such as programs and data files to specific 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 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 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.
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.
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++)
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.
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:
After you have the prototype working, you may want to follow a development process that includes these steps: