X-Hive/DB 8.0 - Manual

1.1 What is this?

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

This manual contains the basic information on X-Hive/DB. There is also more detailed information on specific aspects of X-Hive/DB, and information on using X-Hive/DB combined with other tools. These 'Advanced Topics' can be found in the Documentation Extras section on our support site.

1.2 Who is this manual for?

This manual is for all users of X-Hive/DB, 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.

1.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 X-Hive/DB.

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

General information describes the architecture of X-Hive/DB, 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 X-Hive/DB.

Installing X-Hive/DB 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 X-Hive/DB 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 X-Hive/DB transaction model.

Using XQuery explains in detail how to use XQuery within X-Hive/DB.

Using Indexes describes how you can use one of X-Hive/DB's indexing methods to enhance the performance of your X-Hive/DB application.

Using the Catalog and DTDs describes how X-Hive/DB deals with DTDs.

Internal Structure of X-Hive/DB gives advanced information on the physical data-structure of X-Hive/DB.

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

1.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 X-Hive/DB. This approach is especially important if you are using X-Hive/DB 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 X-Hive/DB, 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 X-Hive/DB.

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

1.5 Conventions

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

Here is where you
find sample code.

1.6 Support and feedback

X-Hive Corporation provides both telephone and e-mail technical support.

We appreciate your feedback on this manual, and on any aspect of the X-Hive/DB product. You can send your feedback by e-mail to product_strategy@x-hive.com.

You can also access product information, browse FAQs, and submit questions through our Web site at www.x-hive.com. Up-to-date technical information, including newer versions of and updates to this manual, can be found at support.x-hive.com.

2.1 Pre-installation

Before installing X-Hive/DB, be aware that:

• X-Hive/DB 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.

• X-Hive/DB requires a Sun JDK 5, or fully compatible Java Virtual Machine. You need to install the JDK before installing X-Hive/DB.

2.2 Installing X-Hive/DB

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 X-Hive/DB running, ensure you uninstall them in the proper way or choose other directories and port-numbers. For more information, see the Uninstalling X-Hive/DB section.

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

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

2.3 Creating a database

The first step after installing X-Hive/DB is creating a database.

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

1. Start the AdminClient by running XHAdmin, which is located in the bin subdirectory of the X-Hive/DB target directory, and in the Start menu group of X-Hive/DB 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 X-Hive/DB 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 XHCreateDB can be used to create databases.

2.4 Running a sample

X-Hive/DB 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:

   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. You should check the values of the properties in SampleProperties.java, so that they match your settings, before running the samples.

3.1 What is X-Hive/DB?

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

X-Hive/DB 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

3.2 The technology behind X-Hive/DB

This section introduces the following technical aspects of X-Hive/DB:

• 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

3.3 X-Hive/DB logical architecture

This section describes the logical architecture of X-Hive/DB. For an overview of the internal architecture of X-Hive/DB, go to the Internal X-Hive/DB architecture section.

The following diagram provides an overview of the logical architecture of X-Hive/DB:

Figure 1. X-Hive/DB's logical architecture

4.1 Installation requirements

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

4.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 - X-Hive/DB is then ready for use.

4.2.1 Run the installation program

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

When you run 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.

   

   Figure 3.

2. Specify the target installation directory. The default on Microsoft Windows is C:\Program Files\Xhive.

   

   Figure 4.

3. Browse for the base directory of the applicable Java Development Kit. For example, C:\jdk1.5.

   

   Figure 5.

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

   

   Figure 6.

5. Specify the password of the super user. This password is later needed to create databases with X-Hive/DB and perform other super user tasks.

   

   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 X-Hive/DB 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 X-Hive/DB 5, that makes a bigger difference then in previous X-Hive/DB 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.

   

   Figure 9.

8. 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 does determine 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. You generally do not want to make this amount smaller, but if memory permits you can make it larger to improve performance.
   • By default, only processes running on the same machine can access the server for security reasons. If you want to have processes on multiple machines access the database, you can choose here to allow it here.
   

   Figure 10.

9. Finally, 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 11.

After successful installation of X-Hive/DB, 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).

4.3 Installation - UNIX

On UNIX platforms you can install X-Hive/DB as any user. Installation consists of three steps:

1. Starting the installation.

2. Entering installation parameters.

3. Performing post-installation steps.

sh setup.sh InstallationPath/xhive

sh setup.sh /opt/xhive

/opt/xhive/bin
          /lib
          /doc

Question [default] :

4.3.3 Performing post-installation steps

After you have installed X-Hive/DB on Unix, you have to perform the following post-installation steps:

• Add the XhiveDir/bin directory to your path, for example:

  bash$ export PATH=${PATH}:XhiveDir/bin
  

  or if you use a (t)csh:

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

• Start the page server with the command XHStartServer. This will start a background process for the page server that can then be accessed from e.g. the Administrator client.

Figure 12.

4.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 X-Hive/DB API. More information on each command can be found by running them without any parameters. Additional commands are described in the administration sections.

4.5 Running the samples

After you have installed X-Hive/DB you can create databases and run the samples that are provided with X-Hive/DB.

4.6 Uninstalling X-Hive/DB

In the (hypothetical) event that you would like to uninstall X-Hive/DB, follow the instructions in the uninstalling.txt file.

Uninstalling X-Hive/DB on Windows can be done by using the Add/ Remove Programs item in the Control Panel. The data directories and other remaining files can be removed 'by hand' afterwards.

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

4.7 Configuring the xhive.bootstrap property

A property called xhive.bootstrap specifies the location of the X-Hive/DB federation. The property can be used in two different ways:

• If the property is a URL of the form xhive://host:port, the X-Hive/DB code will attempt to connect to an X-Hive/DB server running behind the specified TCP/IP port.

• If the property is the complete (or relative) path to an XhiveDatabase.bootstrap file, an X-Hive/DB 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 X-Hive/DB server for a specific federation at the same time.

4.8 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 following JAR files:

• antlr.jar

• fop.jar

• icu4j.jar

• jsr173_api.jar

• lucene.jar

• serializer.jar

• xalan.jar

• xbean.jar

• xercesImpl.jar

• xml-apis.jar

• xhive.jar

For example, the following commands run the application myapp (assuming the X-Hive/DB installation directory is C:\xhive):

C:\xhive\bin>java -classpath C:\xhive\lib\antlr.jar;
                             C:\xhive\lib\fop.jar;
                             C:\xhive\lib\icu4j.jar;
                             C:\xhive\lib\jsr173_api.jar;
                             C:\xhive\lib\lucene.jar;
                             C:\xhive\lib\serializer.jar;
                             C:\xhive\lib\xalan.jar;
                             C:\xhive\lib\xbean.jar;
                             C:\xhive\lib\xercesImpl.jar;
                             C:\xhive\lib\xml-apis.jar;
                             C:\xhive\lib\xhive.jar;
                  -Dxhive.bootstrap=C:\xhive\data\XhiveDatabase.bootstrap
                  test.myapp
    

4.9 The X-Hive/DB dedicated server process

When you have installed X-Hive/DB, 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 X-Hive/DB 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 X-Hive/DB API like any X-Hive/DB 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 X-Hive/DB with a separate dedicated server such as configured after installation is not actually 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 it is a poor choice.

5.1 Introduction

This chapter describes how to create X-Hive/DB 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 X-Hive/DB 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

• 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

5.2 Create a database

When you install X-Hive/DB 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" X-Hive/DB databases. The federated database also contains super user information. For more information on X-Hive/DB architecture, see the X-Hive/DB architecture section.

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

• The command-line utility XHCreateDB.

• The adminclient.

• The Application Programming Interface (API) functions.

5.3 Connect to the database

To connect to an X-Hive/DB database:

1. Obtain an X-Hive/DB 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:

5.4 Use sessions and transactions

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

In X-Hive/DB all operations to databases take place within a session. The developer can determine the scope of a session.

To create a session in X-Hive/DB:

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);
   }
   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 X-Hive/DB 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 {
  LSParser parser = rootLibrary.createLSParser();
  for ( int i=1; i<=numFiles; i++ ) {
    Document 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(), X-Hive/DB 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();

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.

See also:

5.5 Create libraries

In X-Hive/DB, 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 X-Hive/DB 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

See also:

5.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.

X-Hive/DB 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:

5.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:

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

// get the abstract schema models that exist in the root library catalog
Iterator iter = unCharterCatalog.getASModels();
ASModel asModel;
while ( iter.hasNext() ) {
  asModel = (ASModel)iter.next();
  System.out.println(" asModel = " + asModel.getLocation());
}

See also:

5.8 Store XML documents

To store XML documents in an X-Hive/DB database, use the appendChild() method. Before you can use the appendChild() method, you need to get a handle to the library where the document should be stored. Every database has a root library by default. To store a document in the root library of the sample database, you could use the following code:

XhiveLibraryIf rootLibrary = united_nations_db.getRoot();
rootLibrary.appendChild(firstDocument);

Alternatively, you can store a document using the insertBefore() method, which is also a standard DOM method. The second parameter to specify with insertBefore() is the document in front of which you want to insert the new document:

rootLibrary.insertBefore(secondDocument, firstDocument);

See also:

5.9 DOM configuration settings

The DOM level 3 DOMConfiguration interface is used to set configuration settings. XhiveDocumentIf, LSParser and LSSerializer objects each have their own configuration object.

DOMConfiguration can be used to set boolean parameters like "validate", "namespaces" and "cdata-sections". Furthermore, the configuration can be used to set string parameters like "schema-location" and user object parameters like error-handler. The boolean configuration settings and string parameters of a document are stored in the database. These settings are used by XhiveDocumentIf function normalizeDocument. The complete list of options can be found in the JavaDOC documentation of DOMConfiguration, and getDomConfig() of LSParser and LSSerializer (all linked below).

the following piece of code shows how to set a boolean parameter and user object parameter on the document configuration:

XhiveDocumentIf document = (XhiveDocumentIf) builder.parseURI(new File(fileName).toURL().toString());
DOMConfiguration config = document.getDomConfig();
config.setParameter("validate", Boolean.TRUE);
config.setParameter("error-handler", new SimpleDOMErrorPrinter());

In X-Hive/DB, the default configuration settings conform to the default settings as defined by the DOM level 3 Core Specification and the Load/ Save Specification. A parameter is supported if it can be set to another value. The following piece of code shows how to test if a boolean parameter value is supported by a configuration:

config.canSetParameter("validate", Boolean.TRUE);

See also:

5.10 Parse documents with context

You can use function parseWithContext on LSParser to parse complete documents.

LSParser parser = charterLib.createLSParser();
// Using null, null, null as arguments here means the document will be completely empty
Document document = charterLib.createDocument(null, null, null);
// Other actions on document...
LSInput source = charterLib.createLSInput();
source.setSystemId("file:///c:/docs/document.xml");
parser.parseWithContext(source, document, LSParser.ACTION_REPLACE);

5.11 Store BLOBs

X-Hive/DB enables the storage of Binary Large OBjects (BLOBs) within a database. Examples of BLOBs are: image files (GIF, JPEG, PNG, BMP etc.), sound files (MP3, WAV etc.) and Microsoft Office files (DOC, XLS, PPT etc.). The advantage of storing BLOBs next to XML documents within X-Hive/DB is the fact that this allows the management of all resources for a specific project or product in one uniform way.

BLOBs are stored in X-Hive/DB as a special type of node, the BLOB node. The method createBlob() creates a BLOB node. After creating a BLOB node, the content of the node must be filled through the setContents() method. To actually add the BLOB node, the normal methods for adding nodes can be used: appendChild() or insertBefore():

String imgFileName = "un_flags.gif";
String imgName = "Flags of UN members";
FileInputStream imgFile = new FileInputStream(SampleProperties.baseDir + imgFileName)

// create BLOB node
XhiveBlobNodeIf img = charterLib.createBlob();

// set the contents and name of the BLOB node
img.setContents(imgFile);
img.setName(imgName);

// append the BLOB node to the library
charterLib.appendChild(img);

BLOBs stored in X-Hive/DB can be retrieved using the getContents() method in XhiveBlobNodeIf. This method returns an InputStream. The getSize() method returns the size of the BLOB in bytes:

// retrieve the contents of the BLOB node
InputStream in = img.getContents();

// retrieve the size of the BLOB node
int imgSize = (int)img.getSize();

A FileOutputStream can be used to output the contents of the BLOB node to a file:

// output the image to a new file
FileOutputStream out = new FileOutputStream(SampleProperties.baseDir + "copy_of_" + imgFileName);
byte[] buffer = new byte[imgSize];
int length;
while((length = in.read(buffer)) != -1) {
  out.write(buffer, 0, length);
}
in.close();

When iterating over the child nodes of a library, BLOB nodes can be distinguished from other nodes by their node type which is XhiveNodeIf.BLOB_NODE:

Node n = charterLib.getFirstChild();
while (n != null) {
  if (n instanceof XhiveBlobNodeIf) {
    System.out.println( "BLOB node found: " + ((XhiveLibraryChildIf)n).getName());
  }
  n = n.getNextSibling();
}

See also:

5.12 Import non-XML data

X-Hive/DB can import data from non-XML files, provided you supply information on how the data fields are separated and arranged in the source file. The com.xhive.util.interfaces.XhiveSqlLoaderIf interface contains the methods used for importing non-XML data. For a detailed specification of these methods, refer to the XhiveSqlLoaderIf Javadoc.

In this example, data is imported in CSV format into X-Hive/DB, and stored as an XML document.

The data to import looks like this:

"Member", "Date of Admission", "Additional Notes"
"Iceland",  19 Nov. 1946, ""
"India",  30 Oct. 1945, ""
"Indonesia",  28 Sep. 1950, "By letter of 20 January ..."
"Iran (Islamic Republic of)",  24 Oct. 1945, ""

Document un_members_doc = loader.loadSqlData(Impl,
                            FileName,
                            ',',
                            '\\',
                            '"',
                            true,
                            "UN_members",
                            XhiveSqlLoaderIf.IGNORE_HEADER,
                            "member",
                            new String[] {"name","admission_date","additional_note"},
                            new boolean[] {false, false, false});

<UN_members>
  <member>
    <name>Iceland</name>
    <admission_date>19 Nov. 1946</admission_date>
    <additional_note></additional_note>
  </member>
  <member>
    <name>India</name>
    <admission_date>30 Oct. 1945</admission_date>
    <additional_note></additional_note>
  </member>
  <member>
    <name>Indonesia</name>
    <admission_date>28 Sep. 1950</admission_date>
    <additional_note>By letter of 20 January 1965...</additional_note>
  </member>
  <member>
    <name>Iran (Islamic Republic of)</name>
    <admission_date>24 Oct. 1945</admission_date>
    <additional_note></additional_note>
  </member>
</UN_members>