Skip Headers

Oracle® XML Developer's Kit Programmer's Guide 10g Release 2 (10.1.2) Part No. B14033-01 |
| Contents | Index

Previous | Next |

# 18 Unified C++ Interfaces

This chapter contains these topics:

- What is the Unified C++ API?

- Accessing the C++ Interface

- OracleXML Namespace

- Ctx Namespace

- IO Namespace

- Tools Package

- Error Message Files

## What is the Unified C++ API?

Unified C++ APIs for XML tools represent a set of C++ interfaces for Oracle XML tools. This unified approach provides a generic, interface-based framework that allows XML tools to be improved, updated, replaced, or added without affecting any interface-based user code, and minimally affecting application drivers and, possibly, application configuration. All three kinds of C++ interfaces: abstract classes, templates, and implicit interfaces represented by generic template parameters, are used by the unified framework.

Note: Use the new unified C++ API in `xml.hpp` for new XDK applications. The old C++ API in `oraxml.hpp` is deprecated and supported only for backward compatibility, but will not be enhanced. It will be removed in a future release. These C++ APIs support the W3C specification as closely as possible; however, Oracle cannot guarantee that the specification is fully supported by our implementation because the W3C specification does not cover C++ implementations.

## Accessing the C++ Interface

The C++ interface is provided with the database and the Oracle Application Server and is also available for download from the OTN site: `http://www.oracle.com/technology/tech/xml`.

Sample files are located at `xdk/demo/cpp`.

`readme.html` in the root directory of the software archive contains release specific information including bug fixes and API additions.

## OracleXML Namespace

`OracleXml` is the C++ namespace for all XML C++ interfaces. It contains common interfaces and namespaces for different XDK packages. The following namespaces are included:

- `Ctx` - namespace for TCtx related declarations

- `Dom` - namespace for DOM related declarations

- `Parser` - namespace for parser and schema validator declarations

- `IO` - namespace for input and output source declarations

- `Xsl` - namespace for XSLT related declarations

- `XPath`- namespace for XPath related declarations

- `Tools` - namespace for Tools::Factory related declarations

`OracleXml` is fully defined in the file `xml.hpp`. Another namespace, `XmlCtxNS`, visible to users, is defined in `xmlctx.hpp`. That namespace contains C++ definitions of data structures corresponding to C level definitions of the `xmlctx` context and related data structures. While there is no need for users to know details of that namespace, `xmlctx.hpp` needs to be included in most application main modules.

Multiple encodings are currently supported on the base of the `oratext` type that is currently supposed to be used by all implementations. All strings are represented as `oratext*`.

### OracleXML Interfaces

XMLException Interface - This is the root interface for all XML exceptions.

## Ctx Namespace

The Ctx namespace contains data types and interfaces related to the TCtx interface.

### OracleXML Datatypes

DATATYPE encoding - a particular supported encoding. The following kinds of encodings (or encoding names) are supported:

- data_encoding

- default_input_encoding

- input_encoding - overwrites the previous one

- error_language - gets overwritten by the language of the error handler, if specified

DATATYPE encodings - array of encodings.

### Ctx Interfaces

`ErrorHandler` Interface - This is the root error handler class. It deals with local processing of errors, mainly from the underlying C implementation. It may throw `XmlException` in some implementations. But this is not specified in its signature in order to accommodate needs of all implementations. However, it can create exception objects. The error handler is passed to the `TCtx` constructor when `TCtx` is initialized. Implementations of this interface are provided by the user.

`MemAllocator` Interface - This is a simple root interface to make the `TCtx` interface reasonably generic so that different allocator approaches can be used in the future. It is passed to the `TCt`x constructor when `TCtx` is initialized. It is a low level allocator that does not know the type of an object being allocated. The allocators with this interface can also be used directly. In this case the user is responsible for the explicit deallocation of objects (with `dealloc`).

If the `MemAllocator` interface is passed as a parameter to the `TCtx` constructor, then, in many cases, it makes sense to overwrite the operator new. In this case all memory allocations in both C and C++ can be done by the same allocator.

`Tctx` Interface - This is an implicit interface to XML context implementations. It is primarily used for memory allocation, error (not exception) handling, and different encodings handling. The context interface is an implicit interface that is supposed to be used as type parameter. The name `TCtx` will be used as a corresponding type parameter name. Its actual substitutions are instantiations of implementations parameterized (templatized) by real context implementations. In the case of errors `XmlException` might be thrown.All constructors create and initialize context implementations. In a shared server environment a separate context implementation has to be initialized for each thread.

## IO Namespace

The `IO` namespace specifies interfaces for the different input and output options for all XML tools.

### IO Datatypes

Datatype `InputSourceType` specifies different kinds of input sources supported currently. They include:

- `ISRC_URI` - Input is to be read from the specified URI.

- `ISRC_FILE` - Input is to be read from a file.

- `ISRC_BUFFER` - Input is to be read from a buffer.

- `ISRC_DOM` - Input is a DOM tree.

- `ISRC_CSTREAM` - Input is a C level stream.

### IO Interfaces

`URISource` - This is an interface to inputs from specified URIs.

`FileSource` - This is an interface to inputs from a file.

`BufferSource` - This is an interface to inputs from a buffer.

`DOMSource` - This is an interface to inputs from a DOM tree.

`CStreamSource` - This is an interface to inputs from a C level stream.

## Tools Package

`Tools` is the package (sub-space of `OracleXml`) for types and interfaces related to the creation and instantiation of Oracle XML tools.

### Tools Interfaces

`FactoryException` - Specifies tool's factory exceptions. It is derived from `XMLExceptions`.

`Factory` - XML tools factory. Hides implementations of all XML tools and provides methods to create objects representing these tools based on their ID values.

## Error Message Files

Error message files are provided in the `mesg` subdirectory. The messages files also exist in the `$ORACLE_HOME/xdk/mesg` directory. You can set the environment variable `ORA_XML_MESG` to point to the absolute path of the `mesg` subdirectory, although this not required.

See Also: Oracle XML API Reference