EMC Documentum xdb. Installation and Administration Guide P/N A01. Version 9.0

(1)

xDB

Version 9.0

Installation and Administration Guide

P/N 300-008-705-A01

EMC Corporation Corporate Headquarters: Hopkinton, MA 01748-9103 1-508-435-1000 www.EMC.com

(2)

without notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com.

(3)

xDB includes software developed by the Apache Software Foundation (http://www.apache.org).

8.11.2.1 Full text search query syntax 8.11.2.2 Boolean queries 8.11.2.3 Prefix search 8.11.2.4 Phrase search 8.11.2.5 Wildcards 8.11.2.6 Tokenization 8.11.2.7 The analyzer 8.11.2.8 Examples 8.11.2.9 Limitations 9 Using indexes 9.1 Library indexes 9.1.1 Library id indexes 9.1.2 Library name indexes 9.2 Id attribute indexes 9.3 Element name indexes 9.4 Value indexes 9.4.1 Value Index Types 9.5 Full text indexes 9.6 Path indexes

9.6.1 Path index specification syntax 9.7 Metadata value indexes

9.8 Context conditioned indexes 9.9 Index performance

9.9.1 Index scope 9.9.2 Index selectiveness 9.9.3 Index property: sorted keys 9.9.4 Summary

9.10 Concurrent indexes 10 Using validation and the Catalog 10.1 Introduction

10.2 Catalog content 10.2.1 Catalog location

10.2.2 Identification of XML Schema and DTD models 10.2.3 Managing models

10.3 Linking models to documents 10.3.1 DTDs 10.3.2 XML Schema 10.4 Validated parsing 10.4.1 DTDs 10.4.2 XML Schema 10.5 Validation 10.5.1 DTDs 10.5.2 XML Schema 10.6 PSVI 11 Performance 11.1 Internal server

11.2 JVM settings and cache size 11.3 Database page size 11.4 Multiple disks 11.5 Linux filesystems 11.6 Disk write caches 12 Internal structure of xDB 12.1 Segments and files 12.1.1 Segments 12.1.2 Files

12.1.3 Setting up database configurations 12.1.4 Log files

12.2 Detachable Libraries 12.3 Database configuration files 12.3.1 xhive-clustering element 12.3.2 segment element 12.3.3 file element 13 Administering xDB 13.1 The Admin Client

(7)

13.1.2 Importing data

13.1.3 Exporting and editing documents 13.1.4 Adding Indexes

13.1.5 Querying

13.2 The Command Line Client 13.2.1 Running single commands 13.2.2 The interactive console 13.3 Creating a new federation 13.4 Creating a backup 13.4.1 Online ("hot") backups 13.4.2 Incremental backups 13.4.3 The xdb backup command 13.4.4 Restoring backups 13.4.5 The xdb restore command 13.4.6 Offline ("cold") backups 13.4.7 Snapshot backups

13.4.8 Exporting individual libraries and documents 13.5 Managing a detachable library

13.6 Creating a library backup 13.6.1 Online backup using API 13.6.2 The xdb backup-library command 13.6.3 Restoring a library backup 13.6.4 The xdb restore-library command 13.7 Using Secure Socket Layer (SSL) 13.7.1 Server side setup

13.7.2 Client side setup

13.8 Readonly federations (CDROM usage) 13.9 Federation sets

13.9.1 Creating federation sets 13.9.2 Using federation sets 14 Replication 14.1 Introduction 14.2 Creating a replica 14.3 Running a replicator 14.3.1 Dedicated server 14.3.2 Internal server

14.4 Readonly usage of replicators 14.4.1 Temporary data 14.5 Removing a replica 14.6 Federation metadata 14.6.1 Replicated metadata 14.6.2 Metadata not replicated 14.7 Moving the master copy 14.7.1 Failure of the master server

14.7.2 Scheduled moving of the master copy 15 Ant tasks

15.1 Introduction 15.2 Requirements:

15.3 Working with xDB's Ant tasks: 15.4 xDB's Ant Types:

15.5 xDB Ant Types Reference: 15.5.1 <federation/> 15.5.2 <database/> 15.5.3 <library/> 15.5.4 <document/> 15.5.5 <user/> 15.5.6 <group/>

15.6 Referencing xDB's Ant Types: 15.7 xDB's Ant Tasks: 15.7.1 <createdatabase/> 15.7.2 <copydatabase/> 15.7.3 <renamedatabase/> 15.7.4 <deletedatabase/> 15.7.5 <backup/> 15.7.6 <restore/> 15.7.7 <replicatefederation/> 15.7.8 <createlibrary/> 15.7.9 <deletelibrary/> 15.7.10 <upload/> 15.7.11 <parse/>

(8)

15.7.12 <libraryidindex/> 15.7.13 <idattributeindex/> 15.7.14 <pathvalueindex/> 15.7.15 <valueindex/> 15.7.16 <elementindex/> 15.7.17 <fulltextindex/> 15.7.18 <metadatavalueindex/> 15.7.19 <metadatafulltextindex/> 15.7.20 <listindexes/> 15.7.21 <deleteindex/> 15.7.22 <batchindexadder/> 15.7.23 <exportlibrary/> 15.7.24 <serialize/> 15.7.25 <deserialize/> 15.7.26 <serialize-users/> 15.7.27 <deserialize-users/> 15.7.28 <adduser/> 15.7.29 <deleteuser/> 15.7.30 <addgroup/> 15.7.31 <deletegroup/> 15.7.32 <session/> 15.7.33 <createfederation/> 15.7.34 <updatefederation/> 15.7.35 <registerreplicator/> 15.7.36 <unregisterreplicator/> 15.7.37 <closedriver/> 15.8 Notes

Appendix

1 Table of contents

2 Introduction

2.1 What is this?

This manual is designed to provide a technical introduction to the xDB product. This manual describes all aspects of installing, configuring, programming with, administering, and using xDB.

This manual contains the basic information on xDB. There is also more detailed information on specific aspects of xDB, and information on using xDB combined with other tools. These 'Advanced Topics' can be found on the EMC Developer Network.

http://community.emc.com/community/edn/documentum

2.2 Who is this manual for?

This manual is for all users of xDB, and assumes that you have knowledge of:

Java. XML.

The operating system that you are using.

Basic database principles such as transactions, locking, and access rights.

Furthermore, some knowledge of the following subjects is recommended, but not necessary:

DOM. XQuery XSLT.

2.3 How is this manual structured?

This manual is structured in a way that provides basic and essential information first, and then moves on to more advanced topics. This enables you to get started quickly with xDB.

(9)

Quickstart gives you an overview of the essential steps you need to perform to install and set up xDB on your system. It gives you enough information to reach a point where you have installed xDB, created your first database, and learned how to use the sample files provided with the product. These sample files illustrate the key concepts of xDB functionality.

General information describes the architecture of xDB, and provides information on the concepts that you need to understand when using the product. These concepts cover both XML in general and specific issues that relate to xDB.

Installing xDB gives instructions on how to prepare your system for installing the product, and describes the actions you need to perform when running the installation program.

Creating applications gives you instructions on how to develop xDB applications, moving from basic tasks such as programming a transaction to advanced techniques such as using versioning, XLink and content models.

Using Sessions (and Locking) explains in detail the features and issues of the xDB transaction model.

Using XQuery explains in detail how to use XQuery within xDB.

Using Indexes describes how you can use one of xDB's indexing methods to enhance the performance of your xDB application.

Using the Catalog and DTDs describes how xDB deals with DTDs.

Internal Structure of xDB gives advanced information on the physical data-structure of xDB.

Administering xDB describes the tasks you need to perform as a database administrator in xDB. The information provided includes basic tasks such as creating users, and also deals with more advanced topics such as backing up a database.

2.4 How to use this manual?

It is recommended that you read this manual chapter by chapter, as this provides you with a logical progression through the concepts and tasks involved in using xDB. This approach is especially important if you are using xDB for the first time. However, if you are a first-time user, you may want to leave the later chapters (covering issues such as maintenance and optimization) until you have gained experience in the basic features of the product.

If you are an experienced user of XML and xDB, you may not need to read the General information chapter in detail. However, it is

recommended that you browse through the chapter before starting to use the product, because there are some changes in architecture as well as new functionality in this release of xDB.

If you are an administrator, the Administering xDB chapter should be of particular interest. However, all users may find essential information in this chapter.

2.5 Conventions

To ensure clarity and consistency, this manual uses various conventions in the areas of terminology and text usage.

2.5.1 Terminology

Unless otherwise stated, the product and the application refer to the xDB application.

The adminclient is a front-end component of xDB that gives easy access to administration features, such as user management. The administrator is the database administrator who uses the adminclient.

In general, the xDB API conforms to the coding standards supplied by Sun Microsystems.

2.5.2 Text usage

Strings of literal code and command-line entries appear in courier font. When requested to enter such a string, enter the string exactly as it appears in the manual.

Variable information appears in italicized text. Sometimes variables are located in the middle of a literal string, in which case you must replace the italicized part with a suitable value in that context.

Sample code appears in a text box, like this:

Here is where you find sample code.

Sample code is provided to illustrate various programming concepts and techniques in xDB. In most cases, the sample code included in the manual is available in sample files that are supplied with the product. If this is the case, the sample code in the manual is followed by a

(10)

reference to the appropriate sample file.

2.6 Support and feedback

EMC provides support via Powerlink http://powerlink.emc.com.

We appreciate your feedback on this manual, and on any aspect of the xDB product. You can send your feedback by e-mail to [email protected].

You can also access product information, browse FAQs, and submit questions through the EMC Developer Network http://community.emc.com/community/edn/documentum.

3 Quickstart

This section aims to get you started quickly with xDB. It covers all the steps necessary to get xDB running, from installation to creating a database to running your first sample. For more detailed information, consult the chapter Installing xDB.

3.1 Pre-installation

Before installing xDB, be aware that:

xDB should run on any system that has a Java 5 installation.

When installing on Windows 2000, you must be logged on as an administrator or a user with similar access.

xDB requires a Sun JDK 5, or fully compatible Java Virtual Machine. You need to install the JDK before installing xDB.

3.2 Installing xDB

On Windows, simply run the setup.exe file and follow the instructions on screen. Besides installing the files in the proper directories, your

PATH environment variable is augmented, and a page server service is started. If you have previous versions of xDB running, ensure you uninstall them in the proper way or choose other directories and port-numbers. For more information, see the Uninstalling xDB section.

On UNIX, start the distribution from the distribution directory, with the command sh setup.sh /InstallationPath/xdb.

The UNIX installation requires some post-installation steps, which are described in the readme.txt file of the distribution. You can install the xDB program under any account.

3.3 Creating a database

The first step after installing xDB is creating a database.

The easiest way to do this is through the AdminClient, as follows:

1. Start the AdminClient by running xdb admin, which is located in the bin subdirectory of the xDB target directory, and in the Start menu group of xDB on Windows.

2. Create a database by selecting the menu option Databases->Create database.

3. Create a database named united_nations with the super user password as entered during installation of xDB and administrator password northsea. This database will be used by default in all samples described in this manual.

4. After creating the database, you can close the administrator client. Note that you can also use the administrator client to view the data after you have run the samples, and to perform other actions.

Alternatively the command line tool xdb create-database can be used to create databases.

3.4 Running a sample

xDB samples are run using the ant build system. A command line tool called xhive-ant is provided which sets the proper CLASSPATH and other parameters. The samples are run as follows:

1. Open a command prompt and go (cd) to the XhiveDir\bin directory.

2. To run a sample which inserts two documents into the database, enter the command:

(11)

On successful completion of the sample, a message appears stating the number of documents stored in the database.

The sources of all the samples can be found in XhiveDir\src\samples\manual. You should check the values of the properties in

SampleProperties.java, so that they match your settings, before running the samples.

4 General information

4.1 What is xDB?

xDB is a database that enables high-speed storage and manipulation of very large numbers of XML documents. Using xDB, programmers can build custom XML content management solutions that are fully tailored to the exact requirements of any given application. xDB stores XML documents in an integrated, highly scalable, high-performance, object-oriented database. exposes the database and its contents to the user via an application programming interface (API). The API is written in Java.

xDB implements (and extends) the following recommendations of the World-Wide Web Consortium (W3C) for querying, retrieving, manipulating, and writing XML documents:

Document Object Model (DOM) Level 1 DOM Level 2 (Core and Traversal) DOM Level 3 (Core and Load/Save)

The eXtensible Stylesheet Language - Transformation (XSLT) XQuery

XPath XLink XPointer

4.2 The technology behind xDB

This section introduces the following technical aspects of xDB:

DOM support and data manipulation Searching, linking and indexing Session and transaction control Administration features

Import from non-XML resources and storage of BLOBs Transform XML into various outputs

Versioning

4.2.1 DOM support and data manipulation

xDB implements an extended DOM level 3 interface for manipulating the content, structure, and style of documents. xDB supports all DOM level 3 functionality, including functions for retrieval, modification and navigation within XML documents. DOM level 3 does not support XML collections for handling more than one document, so extended API functions in xDB provide support for processing multiple documents simultaneously.

xDB supports nested libraries. You can store libraries within other libraries in the same way that you store documents within libraries. All operations on documents (incl. XQuery queries) can also be performed on libraries as they are implemented as DOM nodes.

4.2.2 Searching, linking and indexing

XML Query Language (XQuery) is a string syntax that you can use to address any piece of information in an XML document, make selections based on conditions, and even construct new structures based on queried information. This makes XQuery an extremely useful tool for searching in XML databases. xDB includes an XQuery query engine implementation. For information on using XQuery, see Using XQuery.

(12)

Besides XQuery, we also have support for XPath and XPointer queries. For information on using XPath and XPointer, see Use XPath and XPointer.

XLink is a W3C recommendation that enables links between XML documents. You can use XLink to create simple links equivalent to <a href> links in HTML, and to create more complex links, known as extended links. You can use extended links to, for example, create one-to-many links, and to add some semantic meaning to your links. For a complete and up-to-date description of XLink, refer to the XML Linking Language (XLink) Version 1.0 documentation at the W3C website.

Indexing enables faster access to parts of a library or document and increases the performance and scalability of xDB applications. xDB supports several different indexing methods: Context Conditioned Indexing, library id and library name indexing, id attribute indexing, element name indexing, value indexing and full text indexing.

4.2.3 Session and transaction control

xDB includes a transaction mechanism to ensure that changes and updates to the database (the 'transactions') are completed harmoniously across the system. All transactions take place within a session that can be committed or rolled back if the transaction conflicts with other transactions.

For instructions on how to use sessions and transactions in xDB, see Using sessions & transactions.

4.2.4 Administration features

The administration features of xDB enable the xDB administrator to manage user and user group permissions for access to documents and queries. An administration tool (a.k.a. 'the adminclient') provides access to the administration features and also includes a data browser that displays the contents of the xDB database using a tree-view. The administration features are also accessible through the API.

4.2.5 Import from non-XML resources and storage of BLOBs

xDB contains an SQL Loader that uses JDBC to import data stored in relational databases. All JDBC-compliant RDBMSs are supported. Data in sequential files can also be loaded into xDB using the SQL Loader interface.

xDB also contains an integrated version of the Xerces parser for importing XML documents from files on the file system.

More information on the import facilities of xDB can be found in the Import non-XML data section.

Next to XML documents it is also possible to store Binary Large OBjects (BLOBs) in xDB.

4.2.6 Transform XML into various outputs

xDB contains a transformation engine that uses XSLT. XSLT provides a declarative means for transforming an XML source tree into any required result tree. This makes it possible to transform XML into such formats as HTML or WML. Powerful publishing of XML content on the Web (or for any device) invariably requires extensive use of XSLT.

xDB includes a special interface, com.xhive.util.interfaces.XhiveFormatterIf, for producing formatted documents that are converted to PDF. You can either format an FO document as a PDF string, or can transform an XML file into a FO document and then format it as a PDF string. For a detailed specification of the formatAsPDF method, refer to the Publish XML documents section.

4.2.7 Versioning

xDB provides linear versioning with branches. This feature enables the storage of multiple (older) versions of a document within the context of the document. Storing multiple versions of a document makes it easier to keep track of the changes in a document and to restore older versions when needed.

4.3 xDB logical architecture

This section describes the logical architecture of xDB. For an overview of the internal architecture of xDB, go to the Internal xDB architecture section.

(13)

Figure 1. xDB's logical architecture

4.3.1 Federated database

A single xDB application contains one or more databases. These databases are grouped within a single federated database (the xDB Federation).

A federated database contains the following objects:

Super user Databases

You can obtain an iterator for all the database names using the getDatabases() method of XhiveFederationIf.

4.3.2 Databases

An xDB application can contain one or more databases. These databases are contained in the federated database, and are created by the super user. A database can contain:

Users and user lists Groups and group lists Indexes and index lists Libraries

Documents

Catalogs and Schemas Blobs (binary large objects)

4.3.3 Users and user lists

Every user of an xDB application has a user account stored in the database. This user account is identified by a unique user name, and has a password for access control. Each user has his own specific set of access rights to the database. For example, one user could be allowed to update documents in the database, while another user has read-only access to documents.

(14)

In addition to regular users, a super user account exists. This account is created automatically during installation, and enables initial database configuration. All other users have their accounts created by the database administrator (a regular user with extra privileges).

xDB maintains a user list for each database which contains all the users of that database.

4.3.4 Groups and group lists

A group is an object in the database with which you can associate one or more users. The main purpose of a group is to enable you to assign the same access rights and privileges to a subset of users. By assigning rights to groups, you then only need to add and remove users from a group to change their privileges.

xDB maintains a group list for each database which contains all groups of that database.

4.3.5 Indexes and index lists

An index list provides a list of all the indexes of a library or document.

4.3.6 Libraries

A library is a logical means of storing documents or other libraries. You can create as many libraries as you need to produce a hierarchy or storage architecture for your documents.

The nested structure of libraries within xDB is very similar to the nested structure of directories or folders within your file system: any library can contain other libraries and there is exactly one root library. The root library is automatically created when the database is created but otherwise behaves like an ordinary library.

4.3.7 Catalogs and DTDs and XML Schemas

The catalog is the part of the database that stores Document Type Definitions (DTDs) and XML Schemas. For information, see the Catalog section.

4.3.8 Documents

A document is the means of storage for XML data in an xDB database. xDB can handle both valid (that is, conforming to a structure defined in a DTD or XML Schema) and well-formed XML documents.

4.3.9 Super user

A federated database has one super user, with username superuser. The super user has the right to create and delete databases, and to perform administration operations like setting the license key and backing up the database. The super user cannot access regular data like libraries and documents.

The super user is not represented by an object in the xDB API. The super user is created during xDB installation.

5 Installing xDB

5.1 Installation requirements

Before running the installation program, you need to perform both checks and tasks to ensure that the installation is successful.

5.1.1 Things to check before installation

You need to check the following issues before installation:

Supported platforms System requirements Java settings

5.1.1.1 Supported platforms

xDB is a Java application. Therefore you can install it on any platform provided you have already installed a Java Development Kit 5 or higher. Installers are available for Windows 2000/XP and Unix (tested on Linux, Solaris, HP-UX and Mac OS X).

5.1.1.2 System requirements

(15)

5.1.1.3 Java

To install xDB, you must already have installed a Java Development Kit (JDK 5 or higher), or a fully compatible Java Virtual Machine. For platform-specific information, see System Requirements. Also note the base directory of the JDK installation. The installation program requires this information.

5.1.2 Things to do before installation

You need to perform the following tasks before installation:

Read the readme.txt file.

On Windows, log in as an administrator, or as a user with similar access.

5.2 Installation - Windows

When you have satisfied the installation requirements, you can run the installation program. Follow all the prompts in the installation program, then create a database. This completes the installation procedure - xDB is then ready for use.

5.2.1 Run the installation program

On Windows, the installation program you need to run is called xdb_setup.exe, located in the root directory of the xDB CD or distribution file. Besides installing the files in the proper directories, your PATH environment variable is augmented. If you have previous versions of xDB running, ensure you uninstall them in the proper way. For information on uninstalling xDB, see the Uninstalling xDB section.

When you run xdb_setup.exe, the installation process begins.

Figure 2.

You simply need to follow the instructions on screen to complete the installation. The installation program requires your input for the following steps:

1. Accept the software license agreement. If you do not accept the license agreement, the installation is terminated. System requirements for xDB

RAM 256MB

Hard drive space for xDB software 50MB

Hard drive space per database 1MB (minimum, real size depending on data loaded) Java JDK 5 or higher (http://java.sun.com)

(16)

Figure 3.

2. Specify the target installation directory. The default on Microsoft Windows is C:\Program Files\xDB (or similar, depending on the language of your Windows installation).

Figure 4.

(17)

Figure 5.

4. Enter the license key you received for the product. Note that there is a time limit on the validity of xDB software licenses. If in doubt about your license, contact xDB customer support.

Figure 6.

(18)

Figure 7.

6. Choose whether to proceed with a standard installation (recommended), or to perform some additional advanced installation steps.

Figure 8.

If you proceed with a standard installation, the program files for xDB are now installed on your host machine. If you proceed with an advanced installation, your input is needed for the following two additional steps.

7. Specify the database directories. The installation program provides defaults for all database directories, based on the installation directory. You should never put database files on remote file servers, like NFS servers or MS Windows shares. For performance, it's best to place the log files on another disk then the database files (in xDB 5, that makes a bigger difference then in previous xDB versions).

It is also possible to change the default page size. Ideally, the page size should match the page size of the filesystem where the database shall reside. You should not pick larger sizes than the file system one. See the section on page sizes for more information.

(19)

Figure 9.

8. You can set some JVM properties, that only relate to with what JVM options client applications like the samples through ant and the Adminclient are run.

Figure 10.

9. During installation, a service is installed and started that acts as a page-server. There are some settings to specify for this service:

The server can run on any port. A check is made whether the port is available. The port-number determines what URL you have to

use later to access the database.

The cache size determines the amount of pages cached by the server to speed up performance. This is one of the major factors

determining overall performance. Leaving it at 0 so that the database will use half the JVM's memory as cache is a safe default.

By default, only processes running on the same machine can access the server for security reasons. If you want to have processes

(20)

Figure 11.

After successful installation of xDB, the installation program displays a message confirming that the installation completed without errors.

To have all settings take effect you will need to do log off and log in (a reboot is not necessary, only the PATH variable change needs to be registered).

5.3 Installation - UNIX

On UNIX platforms you can install xDB as any user. Installation consists of three steps:

1. Extracting the distribution to a directory.

2. Entering installation parameters.

3. Performing post-installation steps.

5.3.1 Starting the installation

Extract the distribution .tar.gz file to the directory where you would like to install xDB. Make sure that you have a working Java 5 executable in your PATH (test this by running java -version from the command line). Then run the included setup script using sh setup.sh.

You will need write permissions in both the installation directory (the directory where you untarred the distribution to) and the directory where you create your initial federation.

5.3.2 Entering installation parameters

After the installation files have been copied, you need to enter a number of parameters needed during installation. The format for these questions is:

Question [default] :

For most questions a default answer is provided. If that default is okay, press the Enter-key, otherwise type a new value (and press Enter) to override that default. If information you enter is incorrect, a message is displayed, and the question is asked again. For yes/no-style questions the default alternative is printed in upper case - in [y/N], no will be the default.

The basic questions are:

A base directory to the JDK - the installation program attempts to identify where the JDK resides based on the JAVA_HOME and PATH

environment variables, but it is wise to check whether that directory really contains the full JDK.

Your valid xDB license key.

(21)

text when run with Java versions older than 6.

The database directory, where your data will reside.

After this you are asked whether you want to alter advanced settings. If you select no (the default) the installation is completed using default values for the advanced settings. If you select yes you can set the following parameters:

The directory for journal files, for performance reasons you could place the journal files on a different harddisk from your database files. The page size in bytes, ideally this should be equal to the block-size of the filesystem where the databases will be located (and never

larger than that size). See the section on page sizes for more information.

The portnumber where the xDB page server will accept connections on.

Whether or not applications on other machines may access the pageserver on this machine.

The minimum and maximum amount of memory passed to the JVM (-Xms and -Xmx). These values are used in scripts to start up client applications like the Adminclient and xhive-ant.

The amount of pages the page server will cache. More means more memory usage but better performance. The default is 0, which means

the server will use 50% of the JVM's available memory.

Other Java command line options (we try to default to some useful options here for certain platforms, usually you do not need to change

them).

5.3.3 Performing post-installation steps

After you have installed xDB on Unix, you have to perform the following post-installation steps:

Add the $XHIVE_HOME/bin directory to your path, for example:

bash$ export PATH="${PATH}:$XHIVE_HOME/bin"

or if you use a (t)csh:

tcsh> setenv PATH ${PATH}:$XHIVE_HOME/bin

Start the page server with the command xdb run-server. This will start a process for the page server that can then be accessed from the Administrator client, the command line tools etc.

(22)

Figure 12.

5.4 Verify the installation

The following are the most important commands that are available after installation. Note that everything that can be done with these commands can also be done by programing your own application using the xDB API. More information on each command can be found by running them without any parameters. Additional commands are described in the comman line section.

Important xDB commands

xdb admin Graphical administration client, for maintaining databases, users and content.

xhive-ant _{Compile and run the samples, as well as other programs.}

xdb create-database Create a new database.

xdb delete-database Remove an existing database.

xdb create-federation Create a new empty federation

xdb configure-federation _{Set the superuser password and/ or license key on a federation.}

xdb backup Backup a federation to a backup file

xdb restore Restore a federation from a backup file

xdb info Shows debug information on currently open transactions and their locks

xdb start-server, xdb

stop-server Start a server process for a specific federation

(23)

5.5 Configuration files

The installation process will create the following three configuration files for you:

xdb.properties, which contains settings used when launching commands through the xdb command, the xhive-ant tool, or one of theXH* tools (which in turn map to xdb).

$XHIVE_HOME\bin\xDB Server.lax contains JVM options for the NT service process on Windows. The relevant options in this file arelax.nl.java.option.java.heap.size.initial, equivalent to -Xms, and lax.nl.java.option.java.heap.size.max, equivalent to -Xmx. You can also change JVM parameters using lax.nl.java.option.additional and the default JVM to use

(lax.nl.current.vm). All other settings will be read from the regular property file. This only applies to Windows, on UNIX operating systems the server is configured through xdb.properties.

$XHIVE_HOME\bin\xDB Admin Client.lax contains JVM options for thexDB Admin Client.exe executable on Windows. These settings only apply when you start the Admin Client through the Start Menu shortcut or the executable, not when you start it through xdb admin or xhive-ant run-admin.

xdb.properties contains key/value pairs for the database settings, described below. Settings from the configuration file can be overridden by setting an environment variable with the same name (e.g. XHIVE_BOOTSTRAP), or simply by passing the corresponding command line switch to the tool.

The command line tools will first search for a .xdb.properties file in the current user's home directory. This way, you can create default xDB configurations for specific users.

xdb stop-server Stop the dedicated server process for the default federation

xdb create-replica Create a full replica (optionally including registering a replica id for it) of a federation at a given

location.

xdb suspend-diskwrites Ensure the federation files are flushed to disk and suspend (or resume) writing to them

xDB settings

Property Example value (Windows) Explanation

XHIVE_BOOTSTRAP xhive://localhost:1235

The xDB URL used by command line tools. In the example, tools will try to connect to a server running on localhost.

XHIVE_DATABASE empty The default database to use. This is not set by the installer. XHIVE_USERNAME Administrator The default username for the command line tools. Do not

use this on production systems!

XHIVE_PASSWORD empty The default password for the command line tools. Do not

use this on production systems!

XHIVE_MAX_MEMORY 128M Maximum memory used by a single command line tool, as

in the -Xmx parameter to the JVM.

XHIVE_MIN_MEMORY 32M Minimum memory used by a single command line tool, as

in the -Xms parameter to the JVM.

XHIVE_CACHEPAGES 0 The number of cachepages allocated in command line

tools. 0 will cause half of the JVM memory to be used.

XHIVE_FEDERATION C:/Program

Files/xDB/data/XhiveDatabase.bootstrap

The location of the default database file. Note that you can have more than one federation. This property is used by the xdb run-server (XHStartServer, and the Windows service), xdb create-federation, and the xdb restore

tools.

XHIVE_SERVER_MAX_MEMORY 256M Maximum memory for the xDB server process.

XHIVE_SERVER_CACHEPAGES 0 Cachepages for the xDB server process. 0 will cause half of the JVM memory to be used.

XHIVE_OPTS -server Additional options to be passed to the JVM.

XHIVE_SERVER_ADDRESS localhost

The server will listen at this address. If set to "*", the server will accept connections from all hosts, if set to "localhost" only connections from the same machine are accepted.

XHIVE_SERVER_PORT 1235 The port used by the xDB server.

XHIVE_HOME C:/Program Files/xDB

The installation location. You can change this to use a different xDB version or an installation in a different location. If left empty, the tools will try to infer a location.

The JDK installation to be used with the xDB tools. This must be a proper Java Development Kit, not a Java

(24)

Changing server related settings (such as XHIVE_SERVER_MAX_MEMORY) will require a server restart. Other settings will be picked up the next time you run a command line tool. For more information about the command line tools, see here

5.6 Running the samples

After you have installed xDB you can create databases and run the samples that are provided with xDB.

5.6.1 Create a database To create a database:

1. Start the AdminClient by running xdb admin, which is located in the bin subdirectory of the xDB target directory, and in the Start

menu group of xDB on Windows.

2. Create a database by selecting the menu option Databases->Create database.

3. Create a database named united_nations with the super user password as entered during installation of xDB and administrator password northsea. This database will be used by default in all samples described in this manual.

4. After creating the database, you can close the administrator client. Note that you can also use the administrator client to view the data after you have run the samples, and to perform other actions.

You can also create databases using the command line tool xdb create-database. For more details on creating databases, see the section Create a database in the Creating applications chapter.

5.6.2 Execute the samples

xDB samples can be run using the ant tool:

1. Open a command prompt and go (cd) to the XhiveDir\bin directory.

2. To run a sample which inserts two documents into the database, enter the command:

xhive-ant run-sample -Dname=manual.StoreDocuments

On successful completion of the sample, a message appears stating the number of documents stored in the database.

The sources of all the samples can be found in XhiveDir\src\samples\manual.

5.7 Uninstalling xDB

In the (hypothetical) event that you would like to uninstall xDB, follow the instructions in the uninstalling.txt file.

Uninstalling xDB on Windows can be done by using the Add/ Remove Programs item in the Control Panel, or the Uninstall xDB link in the xDB program group. The uninstaller will not delete data directories, compiled samples and other files created after installation. These can be removed 'by hand' afterwards.

On Unix, you should first stop the page server if running, with the command xdb stop-server. Then, you can remove the installation and data directories.

5.8 Configuring the xhive.bootstrap property

A property called xhive.bootstrap specifies the location of the xDB federation. The property can be used in two different ways:

If the property is a URL of the form xhive://host:port, the xDB code will attempt to connect to an xDB server running behind the

specified TCP/IP port.

If the property is the complete (or relative) path to an XhiveDatabase.bootstrap file, an xDB server will be started in the current JVM.

Depending on the application, this can be much faster than using a remote server because the communication overhead is avoided. However, only one JVM can run an xDB server for a specific federation at the same time.

If you are using xhive-ant to run xDB applications, the xhive.bootstrap property automatically points to the location of the xDB server. XHIVE_JAVA_HOME C:/Program Files/Java/jdk1.6.0_10

Runtime Environment (JRE). If left empty, the tools will use JAVA_HOME or, as a last resort, any java executable on the path.

(25)

The syntax of the xhive.bootstrap property as used with xhive-ant is:

java -Dxhive.bootstrap=xhive:// host : port

or

java -Dxhive.bootstrap= PathName /XhiveDatabase.bootstrap

Where PathName is the complete path to the XhiveDatabase.bootstrap file. Enclose the parameter in quotation marks if it contains whitespace.

It is also possible to specify the path to XhiveDatabase.bootstrap or the URL to connect to in your Java application, as an argument to

getDriver() on XhiveDriverFactory.

5.9 Using the Java command line instead of xhive-ant

If you use the Java command line, you first need to configure the CLASSPATH variable to include the necessary jar files. What jars are necessary depends on the functionality that you need to use.

xhive.jar, google-collect.jar, xercesImpl.jar, xbean.jar, jrs173_api.jar, antlr-3.1.1-runtime.jar, icu4j.jar, lucene.jar: These are all needed for basic xDB functionality. When using Java 6, the jsr173_api.jar file is not needed, as the interfaces in it are included in Java 6.

xalan.jar, serializer.jar: These jars are only needed when using XSLT transformations. If desired, you can substitute another JAXP compliant XSLT processor like Saxon.

fop.jar, xmlgraphics-commons.jar, avalon-framework.jar, batik-all.jar, commons-io.jar, commons-logging.jar:

These jars are only needed when creating PDFs using the XhiveFormatterIf.

jline.jar: This jar is only used by the command line clients and is not necessary for applications using xDB.

ant.jar, ant-launcher.jar: These jars are only used by the xhive-ant script. They are not necessary to run applications.

5.10 The xDB dedicated server process

When you have installed xDB, the system is configured to run with a dedicated page server that runs as a background process and to which other applications that want to access the database can connect.

It is important to realize that this process is not a required part for the xDB architecture. Java applications could also access the database directly through the bootstrap file without making any network connection. However, when accessing database files directly, no other processes (including the dedicated server described here) may be accessing the database at the same time (but that does not need to be a problem, as long as the 'main application' starts a listener thread for other applications to connect to, see below).

What is also important to realize is that the server program is a very small Java program, accessing the xDB API like any xDB application you would write yourself. There are some different configuration possibilities, but apart from those options and the processing of the passed parameters the whole server process is essentially these five lines:

XhiveDriverIf driver = XhiveDriverFactory.getDriver(bootstrapPath); // Get a driver for a bootstrap-location driver.init(cachePages); // Initialize the cache of the driver

ServerSocket socket = new ServerSocket(port); // Create a listen socket driver.startListenerThread(socket); // Start accepting remote connections wait(); // Wait forever in this main thread

Only the lines related to startListenerThread are specific to accepting remote connections, adding these lines to your own application will make it accept connections from other applications.

As mentioned in the performance section, running xDB with a separate dedicated server such as configured after installation is not necessarily the best configuration for performance. The reason that it is configured by default with a separate server is because we feel that is is the more convenient way to get started, but for production applications where performance is essential running the complete database in process with the application itself might be better.

5.10.1 Configuration of the server

The default configuration of a server is determined during the installation. The settings are the port-number to accept connections on (default is '1235'), the size of the page-cache to use in the server (default is '0', which will make the server use half of the available JVM memory), and from what address(es) to accept connections ('localhost' means only connections from the same machine are accepted, '*' means that connections from every machine are accepted).

(26)

service, this file is xdb-server.properties. For Unix the parameters need to be changed in the xdb.properties file. The files are located in the xDB installation directory. You will have to stop and start the server process after any changes (see below). Please note that when enlarging the cache size, you will also have to allocate more memory to the process, configured through the XHIVE_SERVER_MAX_MEMORY parameter in the same configuration file. Your selected page size can be found in the XhiveDatabase.bootstrap file, but cannot be changed after creating a federation.

The dedicated process is not configured for SSL connections by default. However, examination of the configuration files should show that that the server process is essentially the Java class com.xhive.tools.XhiveServer, which matches the xdb run-server command. So examining the options of the xhive run-server command and reading the SSL section should get you started on how to change the configuration file.

As explained, it is not required to use a server process at all. If you want to configure xDB for use without a server, you have to:

Use /path/to/XhiveDatabase.bootstrap instead ofxhive://hostname:portname as the bootstrap path in your application.

Stop the server (since only one process is allowed access to the federation). On Unix, the server is simply not started if you don't run it.

On Windows you need to stop the server using net stop xhive-server , and disable the automatic startup in the system preferences.

5.10.2 XHStartServer

XHStartServer starts a background server process for the default federation, to which other processes can connect. The log output of any errors is redirected to a file named server.log which by is placed in the same directory where the XhiveDatabase.bootstrap file resides.

On Windows, this background server is implemented as a service, so this command consists only of starting the service named 'xdb-server', which effectively runs the Java program com.xhive.tools.XhiveServer. The service starts automatically when the machine boots. Note that since this is a service, the SYSTEM account must have access to all involved resources (jars and database files).

On Unix, the background server is implemented as simply a Java process running in the background, so the command consists of a script that starts a background Java process for the class com.xhive.tools.XhiveServer. If you would want to run a server at startup, you should add this command to your system startup configuration (be aware of the user under which the command is started in that case, that user must have full access to all involved resources).

5.10.3 XHStopServer

XHStopServer stops the background server process for the default federation.

On Windows, this means simply stopping the 'xdb-server' service.

On Unix, this involves killing the background process whose pid was registered in the file server.pid placed in the same directory as where the XhiveDatabase.bootstrap file resides, by XHStartServer. If there are any unexpected terminations of the process, you will have to remove this pid-file manually.

An alternative to this is the xdb stop-server tool, which will connect to a running federation and tell it to exit.

6 Creating applications

6.1 Introduction

This chapter describes how to create xDB applications of varying complexities. The sections appear in logical order, beginning with basic steps such as creating a database, and moving to advanced topics such as using XPointer, XQuery, XLink and Abstract Schema.

When developing an xDB application, you may need to:

Create a database Connect to the database Use sessions and transactions Create libraries

Parse XML documents Validate XML documents Store XML documents DOM configuration settings

(27)

Parse documents with context Store BLOBs

Import non-XML data Create documents

Retrieve XML documents and document parts Use XQuery

Use XPath and XPointer Use indexes

Traverse XML documents Export XML documents Publish XML documents Use XLink

Use abstract schemas

Revalidate documents with XML schema Access PSVI information

Manage users and groups Use versioning

Using metadata on library children Using JAAS to connect to the database

We provide samples for most of the important functions. One of the ways to run a sample is through the xhive-ant tool. For example, you can use

xhive-ant run-sample

-Dname=manual.StoreDocuments

to compile and run the StoreDocuments sample. Before you run the samples, it is wise to adjust the values in src/samples/manual.SampleProperties.java to match your system.

6.2 Create a database

When you install xDB on a system, one database, called a federated database, is created by default. This federated database acts as a holder for one or more "regular" xDB databases. The federated database also contains super user information. For more information on xDB architecture, see the xDB architecture section.

As an xDB user, you can choose to create as many "regular" databases as you need. You can create a database in xDB using any of the following means:

The command-line utility xdb create-db.

The adminclient.

The Application Programming Interface (API) functions.

6.2.1 Creating a database using xdb create-database

The command line utility xdb create-database is located in the XhiveDir /bin directory. When creating a new database using xhive create-database, you must give the name of the new database, the super user password, and the administrator password, as follows:

(28)

Note:

xDB is case-sensitive for database names, user names, and passwords. For example, Xhive and XHIVE are regarded as different database names. Passwords must be between three and eight characters long, and must be alphanumeric.

The default administrator password used in all samples is northsea. Make the appropriate changes to SampleProperties.java if a different password is used.

6.2.2 Creating a database using the adminclient To create a database using the adminclient:

1. Start the adminclient.

2. Select Databases->Create database. The Create database window is displayed.

Figure 13. Create database

3. Enter the database name, super user password, and administrator password.

6.2.3 Creating a database using API functions

If you are a super user, you can create a database using the API.

The method for creating a database is called createDatabase(), and is located in the com.xhive.core.interfaces.XhiveFederationIf

interface.

To create a new database using the API:

1. Start a session and open a connection to the database as super user. The databaseName parameter of the connect() call should be null:

XhiveDriverIf driver = XhiveDriverFactory.getDriver(); if (!driver.isInitialized()) {

driver.init(1024); }

XhiveSessionIf session = driver.createSession();

session.connect(superUserName, superUserPassword, null);

Note:

By default, sample CreateDatabase.java uses northsea as the super user password. If you entered a different super user password during xDB installation, change the source code of the sample accordingly.

2. Get a handle to the database federation:

XhiveFederationIf federation = session.getFederation();

3. Call createDatabase() with the name of the new database and the administrator password. You can specify a configuration file or use a default configuration (null):

federation.createDatabase(newDbName, administratorPassword, null, System.out);

(29)

Note:

A super user can only create (and delete) a database. Therefore, after creating a database using the createDatabase() method, you need to disconnect and reconnect as an administrator to perform actions on the new database.

6.3 Connect to the database

To connect to an xDB database:

1. Obtain an xDB driver:

XhiveDriverIf xhiveDriver = XhiveDriverFactory.getDriver();

If you do not specify the bootstrap location in the environment of the JVM, you can also pass it as an argument to getDriver:

XhiveDriverIf xhiveDriver =

XhiveDriverFactory.getDriver("xhive://localhost:1235");

(if you connect to the database without a server you should use a path to the file XhiveDatabase.bootstrap)

2. Initialize the local page cache shared by the sessions for this driver:

xhiveDriver.init(1024);

(You should only initialize a specific driver once in your application, you can check with isInitialized()).

3. Create a new XhiveSessionIf:

XhiveSessionIf session = xhiveDriver.createSession();

4. Connect to the database, supplying a user name, password, and database name:

session.connect(UserName, UserPassword, DatabaseName);

See also: samples: <XhiveDir>\src\samples\manual\ConnectDatabase.java API documentation: com.xhive.XhiveDriverFactory com.xhive.core.interfaces.XhiveDriverIf com.xhive.core.interfaces.XhiveSessionIf

6.4 Use sessions and transactions

There is also a separate chapter with background information on sessions.

In xDB all operations to databases take place within a session. The developer can determine the scope of a session.

To create a session in xDB:

1. Establish a connection to the database, as described in the Connect to the database section.

2. Create a session using the createSession() method, which you can find in the com.xhive.core.interfaces.XhiveSessionIf

interface.

XhiveDriverIf driver = XhiveDriverFactory.getDriver(); if (!driver.isInitialized()) {

driver.init(1024); }

(30)

XhiveSessionIf session = driver.createSession();

session.connect( userName, userPassword, databaseName );

Within a session one or more transactions can occur. A transaction is a group of operations that accesses and updates one or more XML documents or parts of XML documents in a database. Uniting a group of operations in a transaction enables you to make that group of operations 'atomic', that is, either all the instructions are executed to (successful) completion, or none are performed. This ensures that a database is never left in an inconsistent state.

To use transactions within xDB do the following:

1. Start the transaction with the begin() method of com.xhive.core.interfaces.XhiveSessionIf.

2. Enter the instructions you want executed during the transaction.

3. End the transaction using either the commit() or rollback() method. Use the commit() method when you actually want to execute your transaction. Use the rollback()method when, because of some kind of failure during the transaction, you want to reverse all the instructions within the transaction. You should take care to always roll back the transaction if you get an unexpected exception. If for instance the disk becomes full while loading a document, modifications may have been done only partially. Committing such partial modifications can result in an inconsistent data structure in the database.

Within the scope of the transaction, an application could, for example, parse external XML documents and append them to a library. If an error occurs during parsing or appending, the complete transaction is rolled back and none of the files are appended:

session.begin(); try {

XhiveLSParserIf parser = rootLibrary.createLSParser(); for ( int i=1; i<=numFiles; i++ ) {

XhiveDocumentIf newDocument = parser.parseURI( new File(baseFileName + i + ".xml").toURL().toString()); rootLibrary.appendChild(newDocument);

}

session.commit(); } catch (Exception e) {

// in case of an error: do a rollback session.rollback();

e.printStackTrace(); }

// remove the session session.disconnect(); session.terminate();

In addition to commit(), xDB offers an alternative method, called checkpoint(), which you can use to commit all persistent operations executed since the last begin() or checkpoint(). One advantage of using checkpoint() instead of commit() is that the transaction remains active after the checkpoint() call, another is that references to database variables remain usable.

After a commit has been performed and you begin a new transaction on the same session, you must re-get all database variables on the session. This means that for instance the code

session.begin(); XhiveLibraryIf library =

session.getDatabase().getRoot(); session.commit(); session.begin(); System.out.println(library.getName()); session.commit();

will not execute. You will get a XhiveException with error code XhiveException.OBJECT_DEAD when you access the library after the second

begin. The reason is that another concurrent session may have removed the database objects that you have references to. You have to get a new reference to the library after the second begin, e.g.:

session.begin();

XhiveLibraryIf library = session.getDatabase().getRoot(); session.commit(); session.begin(); library = session.getDatabase().getRoot(); System.out.println(library.getName());

session.commit();

The following sections discuss some of the possible persistent operations, including creating a library and storing a document.

Note:

Although disconnect() marks the end of the scope of a session, it does not free all the resources allocated by the session. To improve performance, you should use the terminate() method to terminate a session when you no longer need it. If this is a remote session, this will terminate the TCP connection to the xDB server. If you do not call terminate(), the TCP connection will be closed when the session is finalized after it has been garbage collected.

(31)

samples: <XhiveDir>\src\samples\manual\UseSessions.java API documentation: com.xhive.core.interfaces.XhiveSessionIf com.xhive.core.interfaces.XhiveDriverIf

6.5 Create libraries

In xDB, a library is a means of storing documents or other libraries. You can create as many libraries as you need to produce a hierarchy or storage architecture for your documents.

The nested structure of libraries within xDB is very similar to the nested structure of directories or folders within your file system: any library can contain other libraries and there is exactly one root library. The root library is automatically created when the database is created but otherwise behaves like an ordinary library.

To create a library, perform the following steps:

1. Obtain a handle to the parent library. If the root library is the parent library, use the getRoot() method to get a handle. Otherwise, use a previously instantiated variable.

2. Create the library using the createLibrary() method.

3. Give the new library a unique name using the setName() method (optional).

4. Append the new library to its parent using the appendChild() method.

The following code creates a library structure in the sample database with one top-level library called Publications. This top-level library has one sub-library called General Info.

// get a handle to the root library

XhiveLibraryIf rootLibrary = united_nations_db.getRoot(); // create a library

XhiveLibraryIf newLibA = rootLibrary.createLibrary(); // give the new library a name

newLibA.setName("Publications"); // append the new library to its parent rootLibrary.appendChild(newLibA);

// create a library which is a sublibrary of newLibA XhiveLibraryIf newLibA1 = newLibA.createLibrary(); // give the new library a name

newLibA1.setName("General Info"); // append the new library to its parent newLibA.appendChild(newLibA1);

The created library hierarchy looks like this:

Figure 14. Sample library hierarchy

To create a detachable library, one must call method XhiveLibraryIf.createLibrary(int options, String segmentId) with option flag

XhiveLibaryIf.DETACHABLE_LIBRARY set. When flag XhiveLibraryIf.DETACHABLE_LIBRARY is set, one must also specify a segment id. If an unused segment with the given id already exists, the existing segment will be used for the library. If the specified segment does not exist, server will create one with the given name and use it for the library. Once used for a detachable library, a segment cannot be used for anything else but the descendants of the library.

Note:

Although naming a library is optional, it is strongly recommended as several access and indexing methods only work with named libraries.

6.6 Parse XML documents

To import an XML document from an external source, the XML document needs to be parsed. You can parse documents using the parseURI

method of the DOM Load/ Save LSParser interface.

The XhiveLibraryIf interface extends DOMImplementationLS, which can be used to create LSParser and LSSerializer objects. You must create LSParsers on the library where you want to store the document.

When parsing succeeds, a DOM Document is returned.

LSParser builder = rootLibrary.createLSParser();

Document firstDocument = builder.parseURI( new File(fileName).toURL().toString());

To store a parsed document in the database, you also need to perform an explicit appendChild. Otherwise, the document is only parsed and not stored. See the Store XML documents section for more information on storing documents.

The parse documents sample uses the default LSParser configuration settings. Section Using DOM configuration provides more information on builder configuration options and how to change them.

xDB supports the DOM Load/ Save specification, which provides standard ways for parsing and serializing DOMs.

For more documentation, see the Load/ Save specification.

See also: samples: <XhiveDir>\src\samples\manual\ParseDocuments.java <XhiveDir>\src\samples\manual\DOMLoadSave.java API documentation: org.w3c.dom.as com.xhive.dom.interfaces.XhiveLibraryIf org.w3c.dom.ls.LSParser org.w3c.dom.ls.LSSerializer

6.7 Validate XML documents

Validation consists of two main steps:

1. The document is validated.

2. The DTD/ XML Schema information is stored in the catalog as an abstract schema.

As described in the catalog section, each time a document is validated, the application checks whether a abstract schema with the PUBLIC id of that document for DTDs, or the XML Schema with the namespace and file id, is already in the catalog. If so, the validation process uses this abstract schema instead of the external DTD. However, setting LSParser configuration parameter 'xhive-ignore-catalog' to true during parsing overrides catalog checking and always creates a new abstract schema for each document being validated. This is an important note, if there is only a system ID referring to a DTD, and you parse with validation, then a DTD is stored for every document you parse (this does not happen for XML Schemas)! By setting configuration parameter 'xhive-store-schema' to false it is possible to parse with validation without storing the schema

The 'validate' configuration parameter default value is false. Therefore, to parse a file with validation, you need to set this parameter:

LSParser parser = charterLib.createLSParser();

parser.getDomConfig().setParameter("validate", Boolean.TRUE);

Document firstDocument = parser.parseURI( new File(fileName).toURL().toString());

The parsed document contains a reference to a DTD. This DTD is stored as an ASModel within the catalog of the library on which the document is parsed.

The XhiveCatalogIf interface (in the com.xhive.dom.interfaces package) contains several methods for updating and querying the abstract schema models stored:

(33)

// retrieve the catalog of the "UN Charter" library XhiveCatalogIf unCharterCatalog = charterLib.getCatalog();

// get the abstrac

EMC Documentum xdb. Installation and Administration Guide P/N A01. Version 9.0

Version 9.0

THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Table of Contents

Appendix

2.2 Who is this manual for?

2.3 How is this manual structured?

2.4 How to use this manual?

2.5 Conventions

2.5.1 Terminology

2.6 Support and feedback

3.1 Pre-installation

3.2 Installing xDB

3.3 Creating a database

3.4 Running a sample

4 General information

4.2 The technology behind xDB

4.2.1 DOM support and data manipulation

4.2.3 Session and transaction control

4.2.5 Import from non-XML resources and storage of BLOBs

4.2.6 Transform XML into various outputs

4.3 xDB logical architecture

4.3.1 Federated database

4.3.2 Databases

4.3.3 Users and user lists

4.3.5 Indexes and index lists

4.3.7 Catalogs and DTDs and XML Schemas

5 Installing xDB

5.1.1 Things to check before installation

5.1.1.2 System requirements

5.2 Installation - Windows

5.2.1 Run the installation program

RAM 256MB

5.3 Installation - UNIX

5.3.1 Starting the installation

5.3.3 Performing post-installation steps

5.4 Verify the installation

5.5 Configuration files

Property Example value (Windows) Explanation

5.6 Running the samples

5.6.2 Execute the samples

5.7 Uninstalling xDB

5.9 Using the Java command line instead of xhive-ant

5.10 The xDB dedicated server process

5.10.1 Configuration of the server

5.10.2 XHStartServer

6 Creating applications

6.2 Create a database

6.2.1 Creating a database using xdb create-database

6.2.3 Creating a database using API functions

See also: samples:

6.3 Connect to the database

6.4 Use sessions and transactions

6.5 Create libraries

See also: samples:

6.6 Parse XML documents

6.7 Validate XML documents