MarkLogic Server Java Application Developer’s Guide 1 MarkLogic 10 May, 2019 Last Revised: 10.0, May, 2019 Copyright © 2019 MarkLogic Corporation. All rights reserved. MarkLogic Server Table of Contents Table of Contents Java Application Developer’s Guide 1.0 Introduction to the Java API ........................................................................12 1.1 Java Client API Overview ....................................................................................12 1.2 Java Client API or Java XCC? ..............................................................................13 1.3 Getting Started ......................................................................................................14 1.3.1 Required Software ....................................................................................14 1.3.2 Make the Libraries Available to Your Application ..................................14 1.3.2.1 ZIP File ......................................................................................14 1.3.2.2 Maven ........................................................................................15 1.3.2.3 Gradle ........................................................................................15 1.3.3 Choose a REST API Instance ...................................................................15 1.3.4 Create Users ..............................................................................................16 1.3.5 Explore the Examples ...............................................................................16 1.4 Creating, Working With, And Releasing a Database Client .................................17 1.4.1 The Role of a Database Client ..................................................................17 1.4.2 Expected Database Client Lifetime ..........................................................17 1.4.3 Connection Management and Configuration ............................................17 1.4.4 Creating a Database Client .......................................................................18 1.4.5 Connecting Through a Load Balancer ......................................................19 1.4.6 Releasing a Database Client .....................................................................19 1.5 Authentication and Connection Security ..............................................................20 1.5.1 Creating a SecurityContext Object ...........................................................20 1.5.2 Using Kerberos Authentication ................................................................20 1.5.2.1 Configuring MarkLogic to Use Kerberos .................................21 1.5.2.2 Configuring Your Client Host for Kerberos .............................21 1.5.2.3 Creating a Database Client that Uses Kerberos ........................22 1.5.3 Connecting to MarkLogic with SSL .........................................................22 1.5.4 Using SAML Authentication ....................................................................24 1.6 A Basic “Hello World” Method ............................................................................26 1.7 Document Managers .............................................................................................26 1.8 Streaming ..............................................................................................................27 1.9 Using Handles for Input and Output .....................................................................27 1.9.1 Handle Overview ......................................................................................27 1.9.2 Specifying Content Format .......................................................................29 1.9.3 Handle Type Quick Reference ..................................................................29 1.9.4 Handle Example ........................................................................................30 1.10 Shortcut Methods as an Alternative to Creating Handles .....................................31 1.10.1 Understanding Shortcut Methods .............................................................31 1.10.2 When to Choose Strongly Typed Over Shortcut ......................................32 MarkLogic 10—May, 2019 Java Application Developer’s Guide—Page 2 MarkLogic Server Table of Contents 1.10.3 Extending Shortcuts by Registering Handle Factories .............................33 1.11 Thread Safety of the Java API ..............................................................................34 1.12 Downloading the Library Source Code ................................................................34 2.0 Single Document Operations .......................................................................36 2.1 Document Creation ...............................................................................................36 2.1.1 Writing an XML or JSON Document To The Database ..........................37 2.1.2 Creating a Text Document In the Database ..............................................38 2.1.3 Automatically Generating Document URIs ..............................................39 2.1.4 Format-Specific Write Capabilities ..........................................................40 2.2 Document Deletion ...............................................................................................40 2.3 Reading Document Content ..................................................................................41 2.4 Writing A Binary Document .................................................................................43 2.5 Reading Content From A Binary Document ........................................................43 2.6 Reading, Modifying, and Writing Metadata .........................................................43 2.6.1 Document Metadata ..................................................................................44 2.6.2 Reading Document Metadata ....................................................................44 2.6.3 Collections Metadata ................................................................................46 2.6.4 Values Metadata .......................................................................................47 2.6.5 Properties Metadata ..................................................................................48 2.6.6 Quality Metadata .......................................................................................48 2.6.7 Permissions Metadata ...............................................................................49 2.6.8 Manipulating Document Metadata In Your Application ..........................49 2.6.9 Writing Metadata ......................................................................................50 2.7 Working with Temporal Documents ....................................................................50 2.8 Conversion of Document Encoding ......................................................................51 2.9 Partially Updating Document Content and Metadata ...........................................53 2.9.1 Introduction to Content and Metadata Patching .......................................54 2.9.2 Basic Steps for Patching Documents and Metadata .................................56 2.9.3 Construct a Patch From Raw XML or JSON ...........................................58 2.9.4 Defining the Context for a Patch Operation .............................................60 2.9.5 Example: Replacing Parts of a JSON Document ......................................60 2.9.6 Example: Patching Metadata ....................................................................61 2.9.7 Managing XML Namespaces in a Patch ...................................................65 2.9.7.1 Defining Namespaces With a Builder .......................................66 2.9.7.2 Defining Namespaces in Raw XML .........................................67 2.9.8 Construct Replacement Data on the Server ..............................................67 3.0 Synchronous Multi-Document Operations ..................................................70 3.1 Write Multiple Documents ...................................................................................70 3.1.1 Overview of Multi-Document Write ........................................................70 3.1.2 Example: Loading Multiple Documents ...................................................72 3.1.3 Understanding Metadata Scoping .............................................................73 3.1.4 Understanding When Metadata is Preserved or Replaced ........................76 3.1.5 Example: Controlling Metadata Through Defaults ..................................77 MarkLogic 10—May, 2019 Java Application Developer’s Guide—Page 3 MarkLogic Server Table of Contents 3.1.6 Example: Adding Documents to a Collection ..........................................80 3.1.7 Example: Writing a Mixed Document Set ................................................81 3.2 Read Multiple Documents by URI .......................................................................83 3.3 Read Multiple Documents Matching a Query ......................................................84 3.3.1 Overview of Multi-Document Read by Query .........................................84 3.3.2 Example: Read Documents Matching a Query .........................................85 3.3.3 Add Query Options to a Search ................................................................87 3.3.4 Return Search Results ...............................................................................88 3.3.5 Read Documents Incrementally