This edition of Qizx/db does not include a stand-alone server program. It is designed to be embedded in a Java™ application, typically a Servlet. You'll learn in this chapter everything needed to implement a basic application using Qizx/db. For an introduction to using Qizx/db, please see the chapter Getting started.

The target audience of this chapter are experienced Java programmers, having a good knowledge of XML and at least a basic knowledge of XQuery.

This chapter is organized in 7 lessons:

The Put class implements a command-line tool allowing to create a Library and populate it with Collections and Documents. More precisely, it allows to copy one or more source files or directories to a single destination Collection or Document. If multiple sources are specified, the destination must be an existing Collection. Moreover the Put class allows to filter what's being copied by the means of a simple java.io.FileFilter.

The outline of this program is (excerpts of Put.java):

        LibraryManager libManager = getLibraryManager(storageDir);
        Library lib = getLibrary(libManager, libName);

        LibraryMember dst = lib.getMember(dstPath);
        boolean dstIsCollection = (dst != null && dst.isCollection());

        if (args.length > l+4 && !dstIsCollection) {
            shutdown(lib, libManager);
            usage("'" + dstPath + "', does not exist or is a document");
        }

        try {
            for (int i = l+2; i < last; ++i) {
                File srcFile = new File(args[i]);

                String dstPath2 = dstPath;
                if (dstIsCollection) {
                    dstPath2 = joinPath(dstPath, srcFile.getName());
                }
                put(lib, srcFile, filter, dstPath2);
            }

            verbose("Committing changes...");
            lib.commit();
        } finally {
            shutdown(lib, libManager);
        }

Objects involved:

    private static LibraryManager getLibraryManager(File storageDir) 
        throws IOException, QizxException {
        LibraryManagerFactory factory = LibraryManagerFactory.getInstance();
        if (storageDir.exists()) {
            return factory.openLibraryGroup(storageDir);
        } else {
            if (!storageDir.mkdirs()) {
                throw new IOException("cannot create directory '" + 
                                      storageDir + "'");
            }

            verbose("Creating library group in '" + storageDir + "'...");
            return factory.createLibraryGroup(storageDir);
        }
    }

    private static Library getLibrary(LibraryManager libManager,
                                      String libName) 
        throws QizxException {
        Library lib = libManager.openLibrary(libName, /*user*/ null);
        if (lib == null) {
            verbose("Creating library '" + libName + "'...");
            lib = libManager.createLibrary(libName, /*user*/ null);
        }
        return lib;
    }

Library lib = libManager.openLibrary(libName, /*user*/ null);

    private static void put(Library lib,File srcFile, FileFilter filter,
                            String dstPath) 
        throws IOException, QizxException {
        if (srcFile.isDirectory()) {
            Collection collection = lib.getCollection(dstPath);
            if (collection == null) {
                verbose("Creating collection '" + dstPath + "'...");
                collection = lib.createCollection(dstPath);
            }

            File[] files = srcFile.listFiles(filter);
            if (files == null) {
                throw new IOException("cannot list directory '" + 
                                      srcFile + "'");
            }

            for (int i = 0; i < files.length; ++i) {
                File file = files[i];
                put(lib, file, filter, joinPath(dstPath, file.getName()));
            }
        } else {
            verbose("Importing '" + srcFile + "' as document '" + 
                    dstPath + "'...");
            lib.importDocument(dstPath, srcFile);
        }
    }

XMLPushStream out = lib.beginImportDocument(docPath);
out.putDocumentStart();
QName helloName = lib.getQName("hello", "http://www.acme.com/ns/test");
out.putElementStart(helloName);
out.putText("Hello world!");
out.putElementElement(helloName);
out.putDocumentEnd();
Document doc = lib.endImportDocument();

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"
         prefer="public">
  ...
  <public publicId="-//W3C//DTD XHTML 1.0 Transitional//EN"
          uri="xhtml1-transitional.dtd"/>
  ...
</catalog>

  <target name="run" depends="compile">
    <java classpathref="cp" fork="yes" classname="Put">
      <sysproperty key="xml.catalog.files" 
                   value="${basedir}/../../xhtml_dtd/catalog.xml" />
      <sysproperty key="xml.catalog.prefer" value="public" />
      <sysproperty key="xml.catalog.verbosity" value="0" />
      ...
    </java>
  </target>

        ...
            verbose("Committing changes...");
            lib.commit();
        } finally {
            shutdown(lib, libManager);
        }
        ...

    private static void shutdown(Library lib, LibraryManager libManager) 
        throws QizxException {
        if (lib.isModified()) {
            lib.rollback();
        }
        lib.close();
        libManager.closeAllLibraries(10000 /*ms*/);
    }

Library lib = libManager.openLibrary("MyLib", null); // AS=121,SS=121 

Thread.sleep(10);

//AS=121,SS=121
Expression expr = lib.compileExpression(query1);
ItemSequence results = expr.evaluate();

Thread.sleep(10000);

//AS=123,SS=121
expr = lib.compileExpression(query1);
ItemSequence results = expr.evaluate();

//AS=123,SS=121
lib.importDocument(file1, "/maps/Germany.xml");
lib.commit(); //AS=124,SS=124 

Thread.sleep(10000);

//AS=130,SS=124
Document doc = lib.getDocument("/maps/Germany.xml");
doc.setProperty("lastModified", new Date());
lib.commit(); //AS=131,SS=131

lib.close();

Library lib = libManager.openLibrary("MyLib", null);

Thread.sleep(10);

lib.refresh();
Expression expr = lib.compileExpression(query1);
ItemSequence results = expr.evaluate();

Thread.sleep(10000);

lib.refresh();
expr = lib.compileExpression(query1);
ItemSequence results = expr.evaluate();

// this lock will wait as long as necessary:
Collection maps = lib.lockCollection("/maps", -1);
if (maps != null) { // null means deleted
    lib.importDocument(file1, "/maps/Germany.xml");
    lib.commit();
}

Thread.sleep(10000);

Document doc = lib.lockDocument("/maps/Germany.xml", -1);
if (doc != null) {
    doc.setProperty("lastModified", new Date());
    lib.commit();
}

lib.close();

The Get class implements a command-line tool allowing to make local copies of Collections and Documents stored in a Library. This tool can match the names of the Collections and Documents to be copied against a wildcard. For example, it can be used to make local copies all Documents whose names end with ".xhtml" found in the "/Author Blurbs" Collection (corresponding command-line argument is "/Author Blurbs/*.xhtml").

Excerpts of Get.java:

            ...
            LibraryMember libMember = lib.getMember(path);
            if (libMember == null) {
                error("dont't find '" + path + "'");
                return;
            }

            get(libMember, dstFile);
            ...

   private static void get(LibraryMember libMember, File dstFile) 
        throws IOException, QizxException {
        File dstFile2;
        if (dstFile.isDirectory()) {
            String baseName = libMember.getName();
            if ("/".equals(baseName))
                baseName = "root";

            dstFile2 = new File(dstFile, baseName);
        } else {
            dstFile2 = dstFile;
        }

        if (libMember.isCollection()) {
            getCollection((Collection) libMember, dstFile2);
        } else {
            getDocument((Document) libMember, dstFile2);
        }
    }

A local copy of a Document is created as follows:

    private static void getDocument(Document doc, File dstFile) 
        throws IOException, QizxException {
        verbose("Copying document '" + doc.getPath() + 
                "' to file '" + dstFile + "'...");

        FileOutputStream out = new FileOutputStream(dstFile);
        try {
            doc.export(new XMLSerializer(out, "UTF-8"));
        } finally {
            out.close();
        }
    }

A local copy of a Collection is created as follows:

    private static void getCollection(Collection col, File dstFile) 
        throws IOException, QizxException {
        verbose("Copying collection '" + col.getPath() + 
                "' to directory '" + dstFile + "'...");

        if (!dstFile.isDirectory()) {
            verbose("Creating directory '" + dstFile + "'...");

            if (!dstFile.mkdirs()) {
                throw new IOException("Cannot create directory '" + 
                                      dstFile + "'");
            }
        }

        LibraryMemberIterator iter = col.getChildren();
        while (iter.moveToNextMember()) {
            LibraryMember libMember = iter.getCurrentMember();

            File dstFile2 = new File(dstFile, libMember.getName());
            
            if (libMember.isCollection()) {
                getCollection((Collection) libMember, dstFile2);
            } else {
                getDocument((Document) libMember, dstFile2);
            }
        }
    }

Querying a database (that is, a Library) is fairly easy:

Expression expr = lib.compileExpression(script);
ItemSequence results = expr.evaluate();        
while (results.moveToNextItem()) {
    Item result = results.getCurrentItem();

    /*Do something with result.*/
}

(: Compute and return 2 + 3 :)
2 + 3

(: List all books by their titles. :)
declare namespace t = "http://www.qizx.com/namespace/Tutorial";

collection("/Books")//t:book/t:title

The Query class, which implements a command-line tool allowing to query a Library, is more complicated than the above code sample because it supports somewhat advanced options.

Excerpts of Query.java:

    private static Expression compileExpression(Library lib, 
                                                String script,
                                                LibraryMember queryRoot,
                                                QName[] varNames,
                                                String[] varValues) 
        throws IOException, QizxException {
        Expression expr;
        try {
            expr = lib.compileExpression(script);
        } catch (CompilationException e) {
            Message[] messages = e.getMessages();
            for (int i = 0; i < messages.length; ++i) {
                error(messages[i].toString());
            }

            throw e;
        }

        if (queryRoot != null)
            expr.bindImplicitCollection(queryRoot);

        if (varNames != null) {
            for (int i = 0; i < varNames.length; ++i) {
                expr.bindVariable(varNames[i], varValues[i], /*type*/ null);
            }
        }

        return expr;
    }

(: List all books by their titles. :)
declare namespace t = "http://www.qizx.com/namespace/Tutorial";

//t:book/t:title

(: List all books by their titles. :)
declare namespace t = "http://www.qizx.com/namespace/Tutorial";

collection("/Books")//t:book/t:title

(: List all books containing the value of variable $searched 
   in their titles. :)
declare namespace t = "http://www.qizx.com/namespace/Tutorial";

declare variable $searched external;

collection("/Books")//t:book/t:title[contains(., $searched)]

Some queries may return thousands of results. Therefore, displaying just a range of results (e.g. from result #100 to result #199 inclusive) is a very common need.

    private static void evaluateExpression(Expression expr, 
                                           int from, int limit) 
        throws QizxException {
        ItemSequence results = expr.evaluate();
        if (from > 0) {
            results.skip(from);
        }

        XMLSerializer serializer = new XMLSerializer();
        serializer.setIndent(2);

        int count = 0;
        while (results.moveToNextItem()) {
            Item result = results.getCurrentItem();

            System.out.print("[" + (from+1+count) + "] ");
            showResult(serializer, result);
            System.out.println();

            ++count;
            if (count >= limit)
                break;
        }
        System.out.flush();
    }

In this lesson, we'll just show how to print the string representation of an Item. In lesson 5, we'll go further and explore the data model of Qizx.

    private static void showResult(XMLSerializer serializer,
                                   Item result) 
        throws QizxException {
        if (!result.isNode()) {
            System.out.println(result.getString());
            return;
        }
        Node node = result.getNode();

        serializer.reset();
        String xmlForm = serializer.serializeToString(node);
        System.out.println(xmlForm);
    }

Class Delete implements a command-line tool allowing to delete one or more Documents or Collections. If no Document or Collection paths are specified as command-line arguments, the tool deletes the whole Library.

Excerpts of Delete.java:

        if (args.length == 2) {
            verbose("Deleting library '" + libName + "'...");
            if (!libManager.deleteLibrary(libName)) {
                warning("Library '" + libName + "' not found");
            }
            libManager.closeAllLibraries(10000 /*ms*/);
        } else {
            Library lib = libManager.openLibrary(libName, /*user*/ null);

            try {
                for (int i = 2; i < args.length; ++i) {
                    String path = args[i];

                    verbose("Deleting member '" + path + "' of library '" + 
                            libName + "'...");
                    if (!lib.deleteMember(path)) {
                        warning("Member '" + path + "' of library '" + 
                                libName + "' not found");
                    }
                }

                verbose("Committing changes...");
                lib.commit();
            } finally {
                shutdown(lib, libManager);
            }
        }

In Qizx/db, updating a document basically consists of replacing its contents in its entirety.

So the strategy we'll use to do the job is:

Unlike the Put, Get, Delete classes which implement generic command-line tools, the Edit class is specific to the dataset used to illustrate this tutorial. The Edit class allows to add a pseudonym to an author. The author is found by her/his full name, and not by the path of the Document containing her/his record.

Excerpts of Edit.java:

        Node author = findAuthor(lib, collectionPath, authorName);
        if (author == null)
            return;

        if (hasPseudonym(author, pseudonym)) {
            warning("'" + authorName + "' already has pseudonym '" + 
                    pseudonym + "'");
            return;
        }

        org.w3c.dom.Document doc = 
            (org.w3c.dom.Document) author.getDocumentNode().getObject();
        if (!doAddPseudo(doc, pseudonym))
            return;

        XMLPushStream out = 
            lib.beginImportDocument(author.getLibraryDocument().getPath());

        DOMToPushStream helper = new DOMToPushStream(lib, out);
        helper.putDocument(doc);
        lib.endImportDocument();

    private static Node findAuthor(Library lib, String collectionPath,
                                   String authorName) 
        throws QizxException {
        Collection collection = lib.getCollection(collectionPath);
        if (collection == null) {
            error("'" + collectionPath + "' is not a collection");
            return null;
        }

        String script = 
            "declare namespace t = '" + TUTORIAL_NS_URI + "';\n" +
            "declare variable $name external;\n" +
            "/t:author[t:fullName = $name]";

        Expression expr = lib.compileExpression(script);
        expr.bindImplicitCollection(collection);
        expr.bindVariable(lib.getQName("name"), authorName, /*type*/ null);

        ItemSequence items = expr.evaluate();
        if (!items.moveToNextItem()) {
            error("Don't find author '" + authorName + "'");
            return null;
        }
        Item item = items.getCurrentItem();

        return item.getNode();
    }

The hasPseudonym method is a simple example of using the Qizx DOM. It searches its pseudonym argument inside an t:author/t:pseudonyms/t:pseudonym element (author having multiple pseudonyms) or inside a t:author/t:pseudonym element (author having a single pseudonym):

    private static boolean hasPseudonym(Node element, String pseudonym) 
        throws QizxException {
        Node child = element.getFirstChild();
        while (child != null) {
            if (child.isElement()) {
                String childName = child.getNodeName().getLocalPart();
                if ("pseudonyms".equals(childName)) {
                    return hasPseudonym(child, pseudonym);
                } else if ("pseudonym".equals(childName)) {
                    if (pseudonym.equals(child.getStringValue())) {
                        return true;
                    }
                }
            }

            child = child.getNextSibling();
        }

        return false;
    }

A LibraryMember, Collection or Document, has not only a content, but also properties. Properties are also explained in the chapter Getting Started.

A property has a name (String) and a value (any Object implementing java.io.Serializable).

Qizx automatically adds a few system properties to all LibraryMembers. The most useful system properties are:

But the real benefit of supporting properties is to allow an application to attach private information to a LibraryMember.

The AddMeta class implements a very specific command-line tool which allows to add metadata^[13] to Documents stored in the "/Author Blurbs" Collection. Remember that the Documents stored in that Collection are copies of articles found on