Download and install the latest version of MarkLogic from this page: http://developer.marklogic.com/products. Once you've installed and started up MarkLogic, go to the browser-based administrative interface (at http://localhost:8001/), where you'll be walked through the process of getting a Developer License, as well as setting up 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.)
If you need more detailed instructions on installing and running MarkLogic, see Installing MarkLogic Server.
Next, download the tutorial project: java-api-tutorial.zip. Unzip the file into a directory of your choice on your machine.
Although you're free to use whatever IDE you prefer, the tutorial files have been packaged as a Maven project and can be opened in Eclipse using the m2eclipse plugin. If you'd like to not have to worry about CLASSPATHs and dependencies to work through this tutorial, then I encourage you to follow the additional steps below. (If you'd rather wire everything up for yourself, you can download the Java API distribution directly and skip the rest of this section.)
- Download and install the latest stable release of Eclipse (I used the "Indigo" and "Juno" versions while writing this tutorial.)
- Start up Eclipse and select the "Help"->"Install New Software…" menu.
- In the "Work with:" field, paste the following URL:
- Click the "Add…" button.
- In the next dialog, give the new repository a name, e.g., "m2e", and hit OK:
- Once it appears, check the checkbox next to "Maven Integration for Eclipse":
- Click the "Next" button and "Next" again to confirm installation.
- Review and accept the license in order to begin the installation. Once the installation is complete, you'll be prompted to restart Eclipse.
- After Eclipse has restarted, select File->Import…
- In the Import dialog, select "Existing Maven Projects" under the "Maven" folder, and click the Next button.
- On the next screen, click "Browse…" and browse to the location where you unzipped the tutorial project, selecting "java-api-tutorial" as the root directory.
- Ensure that the checkbox for the project is checked and click the "Finish" button.
The rest of this section will walk you through these steps.
Navigate in your browser to http://localhost:8000/appservices/ and click the "New Database" button near the top of the screen:
In the dialog that pops up, type the new database name "TutorialDB" and click "Create Database":
You've now created the "TutorialDB" database with the default configuration.
Enable the collection lexicon
The collection lexicon is an indexing feature that we'll need for the tutorial. Back at the top of the window, make sure "TutorialDB" is selected and click the "Configure" button:
Then click the checkbox next to "Collection Lexicon":
Now you'll create the REST API instance, which the Java API uses to interact with the database. On the same page, under "REST API Instances," click the "Add New" button:
Type "TutorialServer" as the server name and choose a port number. In this tutorial, we'll use port 8011:
You should now see "TutorialServer" in the list:
By creating a REST API instance in this way, MarkLogic has automatically created and configured the underlying components for you (specifically, an HTTP app server and an associated modules database). To prove that the REST API instance is running, navigate in your browser to http://localhost:8011/. You should see a page that looks something like this:
MarkLogic has a powerful and flexible security system. Before you can run the Java examples, you'll first need to create a user with the appropriate execute privileges. You of course could use the "admin" user (which has no security restrictions), but as a best practice, we're going to create two users:
- one with the "rest-writer" role, and
- one with the "rest-admin" role.
(There is also a "rest-reader" role available, which provides read-only access to the REST API, but we won't be using that.)
Before we create the users, let's go back into Eclipse and open the Config.properties file:
Take a look at its contents:
This is the default configuration file that comes with the tutorial project. You can modify it as necessary (for example, if MarkLogic is running on a different machine), but the rest of this tutorial will assume the REST API instance is located at http://localhost:8011/. Now we just need to create the "rest-writer" and "rest-admin" users referenced in the above properties file.
Back in your web browser, navigate to "Security"->"Users" in the admin UI at http://localhost:8001/:
At the top of the User Summary screen, click the "Create" tab:
On the New User screen, enter the username ("rest-writer"), password ("x"), and optional description:
Then scroll down and check the checkbox next to the "rest-writer" role:
Click the "ok" button at the bottom of the screen to create the new user.
Repeat the same process (start by clicking the "Create" tab again) for the "rest-admin" user (also with password "x"). Only this time, check the "rest-admin" role instead:
If you click the "Summary" tab, you should now see both users, with their associated roles (including inherited roles).
Now we've got everything set up on the server side, so let's start interacting with MarkLogic via Java.
Learning the MarkLogic Java API
Java API basics