Setup

Install MarkLogic

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.

Set up the tutorial project

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.)

  1. Download and install the latest stable release of Eclipse (I used the "Indigo" and "Juno" versions while writing this tutorial.)
  2. Start up Eclipse and select the "Help"->"Install New Software…" menu.
  3. In the "Work with:" field, paste the following URL: http://download.eclipse.org/technology/m2e/releases
     

    Machine generated alternative text: 0 0 0 Install _____________________ Available Software Select a site or enter the location of a site. Work wit ttp//download.eclipse.orgftechnology/m2e/re s Find more software by working with the Available Software Sites preferences. flter text Name Version cO There is no site selected.

  4. Click the "Add…" button.
  5. In the next dialog, give the new repository a name, e.g., "m2e", and hit OK:
     

    Machine generated alternative text: 0 C) O Add Repository Name: ______________________ J ( Local... ] Location: http://download,eclipse.org/technology/m2e/releases ‘ (__Archive.., J Cancel OK

  6. Once it appears, check the checkbox next to "Maven Integration for Eclipse":
     

    Machine generated alternative text: ‘Name g O[ Maven Integration for Eclipse

  7. Click the "Next" button and "Next" again to confirm installation.
  8. Review and accept the license in order to begin the installation. Once the installation is complete, you'll be prompted to restart Eclipse.
  9. After Eclipse has restarted, select File->Import…
  10. In the Import dialog, select "Existing Maven Projects" under the "Maven" folder, and click the Next button.
     

    Machine generated alternative text: 0 0 0 Import Select Import Existing Maven Projects [ì’Iá 9 Select an import source: t. t 1 tut tt LEI’ Install Java EE V Maven Check out Maven Projects from SCM Lng I!ivii Projects ______ ________________________ flInstaII or deploy an artifact to a Maven repository Materialize Maven Projects from SCM Plug—in Development Remote Systems <Back Next J ( Cancel ] Finish

  11. 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.
  12. 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.

Create a database

Navigate in your browser to http://localhost:8000/appservices/ and click the "New Database" button near the top of the screen:

Machine generated alternative text: F Database - All - t J Welcome, admln Help

In the dialog that pops up, type the new database name "TutorialDB" and click "Create Database":

Machine generated alternative text: New Database Database name(TutoI Cancel 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:

Machine generated alternative text: Welcome, admln F DatabaseID jJ gure Delete + New Database Help

Then click the checkbox next to "Collection Lexicon":

Machine generated alternative text: Database Settings Enable Indexes U Wildcards oI1onLeœn Fie a ue earches

Create a REST API instance

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:

Machine generated alternative text: REST API Instances Create a REST API instance for accessing a database with the Java API or another HTTP client. Server Name Port Group

Type "TutorialServer" as the server name and choose a port number. In this tutorial, we'll use port 8011:

Machine generated alternative text: New REST API Instance Server Name ialSee Po Group Default Cancel EST API Instan

You should now see "TutorialServer" in the list:

Machine generated alternative text: REST API Instances Create a REST API instance for accessing a database with the Java API or another HTTP client. Server Name Port Group aIr 8011 Default Delete

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:

Machine generated alternative text: 0,IiiMarkLoglc REST Server (— - C Lb0ca1ho5t8Oh1 MarkLogic REST Server . Search and retrieve XML results - /vl/search?format=xml . Search and retrieve JSON results - /vl/search?format=json . Search example - /vl/search?g=.&start=1O&pagel.ength=5 . Query Config - /vl/conÍig/gucry . Transform Config - /vl/conÍig/transforms . Add document (HT!? PUT) o Add JSON document: curl -v --digest --user -H “Content-Type: applicationljson” -X PUT -d ‘{ “person” :{ “first”: “John”, “last”:” Doe” }}‘ “http://localhost:80031v 1/documents? un=/docs/person .json” o Add XML document: curl -v --digest --user admin:***** -H “Content-Type: application/xml” -X PUT -d ‘JohnDoe’ “http://localhost:8003/v 1/documents?un/docsIperson .xml” . View document (HT!? GET) o View JSON document: /vl/documents?uri=Idocs/personjson o View XML document: N1/documcnts?uñ=/docs/personxml . Remove document (HT!? DELETh) o Remove JSON document: curl -v --digest --user admin:***** -H “Content-Type: application/json” -X DELETh “http://localhost:8003/v 1/documents?uri=/docs/person .json” o Remove XML document: curl -v --digest --user admin:***** -H “Content-Type: application/xml” -X DELETh “http://localhost:8003/v 1/documents?uri=/docs/person .xml”

Create REST users

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:

Machine generated alternative text: Package Exporer  V java-api-tutoriaI Q src/main/java V Ç, src/mainfresources Ç3data I E] Config.properties I

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/:

Machine generated alternative text: L] Configure Ø Groups Databases Hosts Forests Miirietypes Clusters S.curlty Robs Execute Prrvdeges URI Privileges EF Amps Collections Certificate Authorities El Certificate Templetes

At the top of the User Summary screen, click the "Create" tab:

Machine generated alternative text: L J L I User Summary Summary Create Help _____________________

On the New User screen, enter the username ("rest-writer"), password ("x"), and optional description:

Machine generated alternative text: New User [ 0k ] carìcei user A database user. user name 7name(unique) Required. You must supply a value for user-name. description REST writer user for Java tutorial An objecrs description. password Encrypted Password. Required. confirm password Encrypted Password. Required,

Then scroll down and check the checkbox next to the "rest-writer" role:

Machine generated alternative text: rest- reader rest- reader- internal wrfter rest-writer- internal search-internal

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:

Machine generated alternative text: qconsole- internal qconsole-user min rest-adrnin- internal rest. internal

If you click the "Summary" tab, you should now see both users, with their associated roles (including inherited roles).

Machine generated alternative text: ‘- j I User Summai7I j Summary User Create Help  DescriptIon Roles adrnin dIs-user, dIs-internai, infostudó- user, dIs adrnin, ... rest-reader, app-user rest- reader, manage-user, rest-admin, rest- writer rest- reader, rest-writer admin infostudio ad min nobody dmin rfter admin user Information Studio CPF pipeline and task runner nobody user REST adrnin user for Java tutorial REST writer user for Java tutorial

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

Comments

  • would you please reupload the java-api-tutorial.zip archive ? I cannot extract it :/
    • I just ran it through unzip and it extracted. What OS are you running? Are you seeing any errors? What's the unzip command you're using?
      • Windows 10 & winrar I got this error https://uploads.disquscdn.com/images/556f3d1e5cdf0511f5ac215ee6acd2672460bfda6b397d1ca2999cb64aeda06c.png
        • The "java-api-tutorial.zip" archive worked fine for me. I'm running Windows 10 Pro (64-bit). I downloaded it with the Google Chrome browser then used Microsoft's own extract (right-click on the file then "Extract All") and it worked fine. Then I downloaded the file again using Microsoft's Edge browser, downloaded and installed WinRAR and it also extracted fine. I suspect you might have a corrupted download. Might re-try the download or try a different browser to download the file.
  • Hello David, I am also using MarkLogic 8. The problem is, that i had to go into the marklogic gui (localhost:8001) and check there "Collection Lexicon". When i try to open "Configurations" i get a grey screen without any content.
    • Sertug, please take a look at ErrorLog.txt (location depends on what OS you are using) to see whether there were any errors. If you don't see any errors there, could you please check for errors in the browser? (In Chrome, go to http://localhost:8000/appservices, then click the View menu, then JavaScript Console. From there, select TutorialDB, then click Configure. Please let me know if you see any error messages in the JavaScript Console.) Was this a fresh install of MarkLogic 8 or was it an upgrade from a previous version?
      • Thanks for your support. the reason for my problems was the internet explorer. ive installed now google chrome and its working now. =)
        • Good to know that IE doesn't like it. I'll make a note to look into that.
  • Hello, this tutorial doenst work after "Creating new Database" it is not possible for me to check the box for lexicon collection and also i cant find the button for creating a rest api instance. Can you support me ?
    • Hello Sertug. What version of MarkLogic are you using? I just verified the steps with MarkLogic 8. What happens when you click the box next to "Collection Lexicon"? The "REST API Instances" section is further down the page, after "Range Indexes" and "Fields".