• Chapter 1: Getting Started with Stylus Studio
• Chapter 2: Editing and Querying XML
• Chapter 3: Converting Non-XML Files to XML
• Chapter 4: Working with XSLT
• Chapter 5: Creating XSLT Using the XSLT Mapper
• Chapter 6: Debugging Stylesheets
• Chapter 7: Defining XML Schemas
• Chapter 8: Defining Document Type Definitions
• Chapter 9: Writing XPath Expressions
• Chapter 10: Working with XQuery in Stylus Studio
• Chapter 11: Composing Web Service Calls
• Chapter 12: Accessing Relational Data as XML
• Chapter 13: Extending Stylus Studio
  • Custom XML Validation Engines
  • Custom Document Wizards
  • Stylus Studio File System Java API
  • Using Stylus Studio with Berkeley DB XML
    • Overview
    • Prerequisites
    • Configuring the BerkeleyDBXML.xml File
    • Naming Files
    • Opening a File Stored on Berkeley DB XML
    • Saving a File Back to Berkeley DB XML
    • Creating Containers with Stylus Studio
    • Usage Tips
• Chapter 14: Stylus Studio GUI Reference

Home > Online Product Documentation > Table of Contents > Using Stylus Studio with Berkeley DB XML

Using Stylus Studio with Berkeley DB XML

Integration with the Berkeley DB XML file system is available only in Stylus Studio XML Professional Edition.

Stylus Studio allows you to access XML documents stored on Sleepycat Software's Berkeley DB XML database and to write documents back to the database. This section describes prerequisites, as well as the configuration and procedural information you need to get started.

This section covers the following topics:

Overview

Stylus Studio can read and write well-formed XML documents ( .xml, .xsl, and so on) to/from Berkeley DB XML container files (containers). Containers typically have a .dbxml extension. In Stylus Studio, you reference external files using a URL. The URL used to access Berkeley DB XML files is dbxml:///container_pathname /filename .xml:

For example, to access one of the sample files provided with Berkeley DB XML, you might enter the following in the URL field of the Stylus Studio Open dialog box: dbxml:///C:/samples/simpleExampleData.dbxml/Allspice.xml.

Note that the container name ( C:/samples/simpleExampleData.dbxml in the example) appears in the URL field as if it were a directory name. This is because Stylus Studio treats Berkeley DB XML containers very much like directories, and the XML documents stored within a container are treated like files within a directory.

You can save files back to the same container from which they were read, to a new container, or to some other file system (your local machine, for example).

Berkeley DB XML Support

Stylus Studio supports Berkeley DB XML Version 1.2.1, and Version 2.0.7 and later.

Usage Summary

The process for using Stylus Studio with Berkeley DB XML consists of the following steps:

Each of these steps is described in greater detail in the sections that follow.

Prerequisites

In order for Stylus Studio to access files stored on the Berkeley DB XML database, it must be able to access the .jar and .dll files shown in Table 75. Note that specific files vary based on the Berkeley DB XML version you are using, as shown in the following table.

These files are supplied by Sleepycat software - either as part of a pre-built binary distribution of Berkeley DB XML, or built by you if you received a source code distribution from Sleepycat. These files are not provided as part of your Stylus Studio installation.

Once you have acquired these files, you must make them accessible to Stylus Studio. You do this by modifying your CLASSPATH and PATH environment variables as follows:

These environment variables must be established before you start Stylus Studio. You cannot set them within Stylus Studio.

Saving Files to Berkeley DB XML

In order to save files to Berkeley DB XML, you must first edit the settings in a configuration file. See Configuring the BerkeleyDBXML.xml File.

Configuring the BerkeleyDBXML.xml File

You need to configure the BerkeleyDBXML.xml file in order to be able to save XML documents back to a Berkeley DB XML container. Until you configure the BerkeleyDBXML.xml file as described in this section, any files you read from Berkeley DB XML are marked read-only and cannot be written back to Berkeley DB XML.

The Berkeley Database Environment

The Berkeley database has the concept of a database environment. The database environment is typically a directory that contains the log and lock files that provide support for transaction processing. This directory may also contain databases - files that contain user data. The containers in which Berkeley DB XML stores XML documents are examples of Berkeley databases and typically, though not always, have a .dbxml extension.

To be able to determine what database environments exist in Berkeley DB XML, and which ones are associated with which containers, you need to

These files are installed in the \bin\lib\sleepycat directory where you installed Stylus Studio ( c:\Program Files\Stylus Studio XML Professional Edition\bin\lib\sleepycat, for example).

The BerkeleyDBXML.xml Configuration File

The BerkeleyDBXML.xml configuration file contains elements that allow you to specify Berkeley DB XML database environments and directories:

A finished BerkeleyDBXML.xml configuration file might look like this:

<dbxml>
               
   <dbenv path="c:\dbenv1">
               
      <dbdir path="d:\datadir1"/>
               
      <dbdir path="e:\datadir2"/>
               
   </dbenv>
               
   <dbenv path="c:\testenv">
               
      <dbdir path="c:\testdata"/>
               
   </dbenv>
               
   <dbenv path="c:\testenv2"/>
               
</dbxml>
               

            

Omitting <dbdir> and <dbenv> elements

In some cases, it is not necessary do have any <dbdir> elements, as is illustrated by the <dbenv path="c:\testenv2"/> element in the example BerkeleyDBXML.xml configuration file. You can omit the <dbdir> element

If you use the DB_HOME environment variable to locate your database environment and all its data directories are listed in the DB_CONFIG file for that database environment, you can omit that database environment from the BerkeleyDBXML.xml configuration file. Indeed, if that is your only database environment, you do not need the BerkeleyDBXML.xml configuration file at all.

Specifying <dbdir> pathnames

Pathnames you specify for <dbdir> elements can be absolute or relative. Relative pathnames are relative to the enclosing <dbenv> pathname, not to your current working directory.

The validate attribute

In Berkeley DB XML Version 2.0.7 and later, the <dbxml>, <dbenv>, and <dbdir> elements have a validate attribute that allows Sleepycat to validate XML documents before saving them to the Berkeley DB XML file system. See Validating Documents for more information on this topic.

How to Configure BerkeleyDBXML.xml

To configure BerkeleyDBXML.xml:

3. Click Validate Document .

You are ready to use Berkeley DB XML with Stylus Studio.

Open the Output Window

The first time you perform an operation on the Berkeley DB XML, Stylus Studio tries to process the BerkeleyDBML.xml file. As the file is processed, messages are written to the Stylus Studio Output window. These messages identify which database environments and directories are being processed. This can be a useful way to verify which directories Stylus Studio is associating with which database environment and identify when you might need to make a change in the BerkeleyDBXML.xml file.

Naming Files

File-naming conventions vary between Berkeley DB XML V1.0 and V2.0.

Stylus Studio creates a unique pseudo-name for each named file in a container. Files without a name (supported only in Berkeley DB XML Version 1.2.1) are invisible to Stylus Studio. The pseudo-name consists of the file's name, concatenated with a pound sign (#) and the file ID assigned by Berkeley DB XML.

Example - Berkeley DB XML V 1.2.1

Consider the following files in a container as seen by Berkeley DB XML V 1.2.1:

When you display this container in the Stylus Studio Open dialog box, only these files appear:

Note that only duplicate file names are assigned a numeric ID. The fourth, unnamed, file, is not visible to Stylus Studio.

Opening a File Stored on Berkeley DB XML

You can open files stored on Berkeley DB XML in one of two ways:

To open a file stored on Berkeley DB XML:

The Open dialog box appears. The left panel of the dialog box displays icons representing the file systems to which Stylus Studio has access, including one for Berkeley DB XML:

Figure 335. File System Icon for Berkeley DB XML

The right side of the dialog box displays directories, containers, and any documents that match the extensions in the Files of type field.

Saving a File Back to Berkeley DB XML

You save a file to Berkeley DB XML as you would save a file to any other file system - click File > Save. If the document is not well-formed, Berkeley DB XML will not write it to the container.

Saving and Containers

By default, File > Save saves the file back to the same container from which it was read. Additionally, you can

In any case, in order to save any work back to Berkeley DB XML, you must have previously configured the BerkeleyDBXML.xml file. See Configuring the BerkeleyDBXML.xml File.

Validating Documents

If you are using Berkeley DB XML Version 2.0.7 or later, you can optionally have Sleepycat validate XML documents before saving them to the database. You do this using the validate attribute, which you can set in the <dbxml>, <dbenv>, and <dbdir> nodes in the BerkeleyDBXML.xml file, as shown in the following example:

<dbxml validate="true">
               
   <dbenv path="c:\dbenv1" validate="false">
               
      <dbdir path="d:\datadir1"/>
               
      <dbdir path="e:\datadir2" validate="true"/>
               
   </dbenv>
               
   <dbenv path="c:\testenv" validate="true">
               
      <dbdir path="c:\testdata"/>
               
   </dbenv>
               
</dbxml>
               

            

The syntax for the validate attribute is validate=["true" | "false"]. By default, this attribute is not specified and validation is not performed.

Validation occurs at the container level; each container, specified as a node in the BerkeleyDBXML.xml file, can have its own settings for the validate attribute. A child node inherits the validate attribute from its parent; similarly, you can override settings for child nodes, as shown in the following example:

<dbxml>
               
   <dbenv path="c:\dbenv1" validate="true">
               
      <dbdir path="d:\datadir1"/>
               
      <dbdir path="e:\datadir2" validate="false"/>
               
   </dbenv>
               
</dbxml>
               

            

Here, the validate setting of the <dbenv> node overrides the (implicit) default of "false" of its parent, <dbxml>. The first child of <dbenv> inherits the validate="true" setting, and its second child overrides it.

Schema requirements

In order for Sleepycat to validate an XML document, the XML document must have its schema defined in an internal DTD. If the document does not contain a DTD, or references an external XML Schema, the document is not validated and will be saved if it is well-formed.

Changing settings

Each time Stylus Studio starts, it reads the BerkeleyDBXML.xml configuration file and uses its settings for the entire session. If you want to change the validate attribute for a container, you must exit Stylus Studio, change the BerkeleyDBXML.xml file, and then restart Stylus Studio.

Creating Containers with Stylus Studio

Typically, you use Stylus Studio to access files in existing Berkeley DB XML containers. If you want, you can use Stylus Studio to create new containers. Stylus Studio creates a new container whenever

In order to create a new container:

Node and Wholedoc Containers

Berkeley DB XML Version 2.0.7 and later supports Node and Wholedoc containers. Berkeley DB XML Version 1.2.1 supports only Wholedoc containers. Containers created by Stylus Studio are always created as Wholedoc containers.

Usage Tips

Following are some tips to help you work with Berkeley DB XML in Stylus Studio.

Before Starting Stylus Studio

Before you start Stylus Studio, you must

Database Environment Recovery

Database environment recovery applications must have exclusive access to the database environment they are trying to restore. If you need to perform a database environment recovery, be sure to shut down Stylus Studio - and any other applications that might be using that database environment - prior to starting recovery procedures.