Hands-on: Understanding Applications in MarkLogic Server: Part 1
This tutorial will walk you through the creation of a simple Mark Logic based application. The only prerequisites to this tutorial are that you have downloaded and installed the latest version of the Mark Logic server. Installation instructions for the server can be found here. OK, now that we've covered the prerequisites let's start the actual tutorial!
The first thing we are going to need for this application is some sort of XML content. Without any content our application is going to be rather hard to test and somewhat dull. So, for the purposes of this tutorial we're going to use some Shakespeare that has been converted into XML. The content can be found here. At this point all you need to do is download the zip file and extract the contents to your disk somewhere. We'll get back to our content in a little while.
Database Setup
While Shakespeare's works are downloading, let's setup the Mark Logic database where this content is going to live. Your Mark Logic server is administered via your web browser via a default address of http://localhost:8001. The first step to creating our new database is to enter that address in our browser. That should result in a screen that looks like this (click to see images full size):
From there we want to click on "Database" on the left side of our window. Next, click on the "Create" tab that will appear on the right hand side of the window. You are now looking at the database creation page. Don't be intimidated by all of the configuration options. We're going to ignore almost all of them at this point. Right now all we want to do is to give our database a name. Being logical (and easily confused) individual I'm going to name the database "Shakespeare" (you should do the same - it will make it easier to follow along). Your window should now resemble the following image:
If all looks good then go ahead and click on the "Ok" button at the top right of the window. We're almost done with setting up our MarkLogic database. The only thing remaining is to attach a Forest to our database. Many of you have probably noticed the message that appeared at the top of the window after we clicked on "Ok". This message is telling us that "This database has no forests, select Database->Forests to attach a forest." What the server is trying to tell us is that while we have done an admirable job creating our database, it has no place to actually store our physical data. A Forest is the term that is used to describe how and where the physical data that is associated with our database is going to be stored. Go ahead and click on the "Database->Forests" link at the top of the page. As soon as we do that the server lets us know that we need to create a Forest so that we can associate it with our newly created database. In order to do that we'll click on the "Create A Forest" link that has been so helpfully presented to us. When we do we are now presented with this screen:
At this point we'll go ahead and, following our previous convention, name our Forest "Shakespeare". No other information needs to be filled out on this screen so we will go ahead and click on "ok". Now, we need to associate this newly created Forest with our Shakespeare database. In order to do that, expand the "Database" entry found in the tree on the left most side of the window. You will see a list of all of the databases for this server and in that list will be our Shakespeare database. Expand the Shakespeare database and click on the "Forests" entry that now appears directly under the Shakespeare entry. Finally, check the check box to attach this Forest to our Shakespeare database and then click on "ok" to apply the change.
Loading Our First File
Now that we have our MarkLogic database setup let's load it with some data. For this initial load of some data we are going to use the simplest possible means of loading data into the database. To do this, click on the Shakespeare database entry in the tree on the left side of your window. You will then notice a series of tabs on the top right side of the window. Go ahead and click on the "Load" tab.
Using this form we will tell the server what data we want to load. This form can be used to load multiple files all at once via the use of wildcards in the file name but for right now we will just load one file. Enter the absolute path to the directory where you unzipped the Shakespeare plays into the directory field. Then, enter a_and_c.xml into the filter field to indicate that we only want to upload that single file. When you click on "ok" you should get a confirmation that is similar to the one below but using your paths. If not, the server will give you a helpful message indicating the problem for you to correct.
Once your hit the "ok" button the server will go ahead and load the data and present you with a confirmation screen. To make things really easy for us, there is only one button on the confirmation screen so go ahead and press it when you're ready to move on. Since this is the first time we've loaded data into the server it couldn't hurt to go ahead and verify that our data was loaded. If you click on the "Status" tab that now appears at the top of the screen you will be presented with the status of your Shakespeare database, complete with the number of documents that it currently contains. Yes, there is a lot of other information there but for now we're just interested in verifying that our document was really loaded.
Creating an HTTP Server
In addition to being the industry's top XML server, Mark Logic is also an HTTP server. Surprise! It is this feature that allows us to build web applications directly on the server using XQuery and to expose functionality to other services via an XML-RPC style interface. CQ is really nothing more than a web application running directly on Mark Logic that provides a programming interface to the server.
In order to create our HTTP server we need to expand the "Groups" entry in the tree on the left side of the screen until we see the "App Servers" entry. Click on "App Servers" and on the top right you will be presented with a series of tabs. Click on the tab labeled "Create HTTP" and you will be presented with yet another form, a portion of which is shown here:
There are only four items that we need to complete to create out HTTP server. The first is the name. I would hate to break a trend at this point so let's call our HTTP server Shakespeare. We also need to define the root directory for our HTTP server. This is the directory where the server will be looking for content to serve in response to HTTP requests. For those of you who have done some web application development in Java, this is the same as configuring the web root of your application server. Pick a location on your file system where you are going to want to store the XQuery code that we are going to write for this application. Bear in mind that the server is going to need read / write access to this area so be careful to pick someplace where directory permissions won't be an issue.
The next item that we need to configure here is the port that our HTTP server will listen on. I'm going to choose 8010 as I know that is a free port and it's easy to remember. Feel free to choose a different port if that one isn't free on your machine.
The final thing that we need to do here is to attach this HTTP server to our database. All HTTP servers have to be associated with a database so that the server has a context for evaluating any XQuery that comes in via the HTTP server. Simply select the "Shakespeare" database from the drop down list then click on the "ok" button. That's it! Our HTTP server is all setup!
Getting Started with CQ
OK. That was easy enough. However, like most programmers, I'm somewhat skeptical. Sure, we checked the status page and it says that there is now one document in the database but how do I know that it's my document? We also setup the HTTP server and that seemed to go well but I haven't tested it yet. Well, we can use CQ to help us verify that the HTTP server is working and that our document is in the database (and to do lots of other stuff as well). CQ is basically a web based programming environment for the Mark Logic server. To get started go ahead and download the latest release of CQ from here.
Once the download is complete, installation couldn't be simpler. All we need to do is to unzip the file into the root directory that we specified for the HTTP server we just created. For me that meant unzipping into /Users/clarkrichey/Documents/MarkLogic/Education/Tutorial 1/code/. Now, under that "code" directory there is a "cq" directory where the CQ application lives.
Now that CQ is installed let's verify that everything is working as expected. We can access CQ by going to http://localhost:8010/cq. Remember that if you didn't use 8010 as the port for your HTTP server you will have to adjust the URL accordingly. CQ lives in a folder directly underneath the root of our HTTP server so we have to provide that path (/cq) in our URL. You have probably noticed that while we specified a directory in our URL we didn't ask for a specific web page. The server will, in those cases, look for a file named default.xqy and serve up the content from that page. CQ comes with a default.xqy page so when we enter that URL into our browser we should see something very similar to the following:
The very fact that we're seeing the CQ screen tells us that we've properly configured our HTTP server. Looking at the value in the content-source dropdown box tells us that we also correctly connected our HTTP server to our Shakespeare database. Now we can use CQ to verify that our play was loaded into the database. Click on the "explore" link at the top left of the CQ screen, just under the "Current XQuery" heading. Under the "Query results" heading you should now see a list off all documents (in this case one) contained in our database, as well as a little bit of information about the documents. If you click on the document link you will be presented with the actual content of the document. Now we know for sure that we have the database configured, our single play loaded and the HTTP server up and running.
Lastly, let's get a quick glimpse of the power and utility of CQ by using it to execute some XQuery for us. In the work space on the left of the screen, underneath where it says "Current Query" go ahead an delete all of the text except for the XQuery version statement. Now, let's enter a bit of simple XQuery to show us an HTML rendering of Speakers and their Lines. Enter the XQuery found below into the text area in CQ where you just deleted the default text:
Now, click on the HTL button to see the results rendered as HTML. Experiment with clicking on the XML and TEXT buttons as well to see what your output looks like in each format.
That about warps things up for now! In this tutorial you've learned the fundamental skills necessary to begin programming with the Mark Logic server, from installation and configuration through data loading and executing a simple query. In upcoming tutorials we'll explore more advanced topics. Until then, don't be afraid to keep exploring on your own and don't forget that there is a ton of helpful documentation available here at http://developer.marklogic.com.
Continue on to Part 2.