Writing and Searching for POJOs in MarkLogic
With traditional relational databases, persisting your in-memory data structures requires complex ORM (Object-Relational Mapping) tools to handle the well-known impedance mismatch. Next-generation NoSQL databases that support variety on stored information can provide a simpler solution. In this tutorial, find out how to store and search POJOs in a MarkLogic database without giving up consistency, reliability, or scale.
A Quick Introduction to MarkLogic Server
MarkLogic Server is an Enterprise NoSQL database, supporting a schema-optional document data model, ACID transactions, security, and real-time search indexing. Supported document formats include XML, JSON, text, and even binary (such as video or PDF). Features include:
Speed – with a C++ implementation optimized for today’s IO systems.
Scalability – with a shared-nothing distributed architecture.
High availability – with replication and disaster recovery.
The latest version adds the MarkLogic Java API to make it easy to take advantage of the server in your Java applications. For this tutorial, you'll download the free version of MarkLogic Server. We'll work through some typical data discovery scenarios with a music dataset, executing queries both to answer specific questions and to get a better overall understanding of the dataset. To make things simple, we'll work with data in a POJO representation. The setup steps consist of installing MarkLogic Server, downloading the tutorial, and running a bootstrapping utility that defines a couple of users and creates the database and REST server.
Installing and Starting MarkLogic Server
Download and install the latest version of MarkLogic from http://developer.marklogic.com/products. Once you've installed and started MarkLogic, go to the browser-based administrative interface (at http://localhost:8001/), which will walk you through getting an Express license and creating an admin user. (This tutorial assumes you'll be running MarkLogic on your local machine; if that's not the case, just substitute your server name whenever you see "localhost" in this tutorial.)
For more detailed instructions on installing and running MarkLogic, see Installing MarkLogic Server.
Downloading the Tutorial
After starting the server,
download the tutorial source code from http://developer.marklogic.com/media/pojo-tutorial-01.zip.
Unzip the distribution. You'll find a standard Maven source
structure that you can use, for instance, in m2e. You can, of
course, work with the sources and classes without Maven if you
prefer by looking for the sources under the
src/main/java directory and for runtime
environment under the
In the following sections, we'll only show the highlights from the source code and output. To get the most out of this tutorial, you should view the complete examples in your IDE or editor and run the examples to see the complete output.
To run the tutorial examples, you'll need to set up a Java 6 runtime environment (preferrably the latest stable distribution). You configure your CLASSPATH in the usual way:
From the command-line, specify the root directory for the tutorial classes and the jars for the Java API and its lib dependencies on your CLASSPATH.
In an IDE such as Eclipse, create a project with the tutorial classes in the source directory. Either add the jars for the Java API and its lib dependencies to your build path or use the Maven POM in the tutorial distribution to download these dependencies to your Maven repository.
Setting up the Tutorial's Server Environment
This tutorial focuses on application programming rather than MarkLogic server adminstration. Therefore, this tutorial provides a utility to set up the server environment in one step. Before you start, find and check the values in tutorial.properties. The default values should be correct for your setup; simply ensure that the values for tutorial.bootstrap_user and tutorial.bootstrap_password match the adminstrative credentials for the MarkLogic server. Be wary of modifying the other values shipped with tutorial.properties. To bootstrap the REST server's environment, run the following command at the command line:
Bootstrapping the Tutorial's server-side environment
java -cp CLASSPATH com.marklogic.client.tutorial.util.CreateDatabaseServer
Alternatively, use an IDE to execute this class's main method. When its done, this command will have completed the following:
Created two users for running your application.
the rest-admin user is permitted to configure the application. The bootstrapper sets up this user with the password "
The rest-writer user is allowed to write and update documents, as well as execute searches and retrieve documents. This user is also created with the password "
Created a new database called "TopSongs" for the application data, and "TopSongs-modules" to hold extension code.
Added two range indexes to the "TopSongs" database to support some of the searches below.
Later, when you want to set up your own database, REST server, and indexes, go to http://localhost:8000/appservices/, click the New Database button, select the database, and click the Configure button. Now we're ready for a quick look at the dataset.