Application Developer's Guide (PDF)
Total Page:16
File Type:pdf, Size:1020Kb
MarkLogic Server Application Developer’s Guide 1Application Developer’s Guide MarkLogic 10 May, 2019 Last Revised: 10.0-7, June, 2021 Copyright © 2021 MarkLogic Corporation. All rights reserved. MarkLogic Server Table of Contents Table of Contents Application Developer’s Guide 1.0 Developing Applications in MarkLogic Server ...........................................16 1.1 Overview of MarkLogic Server Application Development .................................16 1.2 Skills Needed to Develop MarkLogic Server Applications ..................................16 1.3 Where to Find Specific Information .....................................................................17 2.0 Loading Schemas .........................................................................................19 2.1 Configuring Your Database ..................................................................................19 2.2 Loading Your Schema ..........................................................................................20 2.3 Referencing Your Schema ....................................................................................21 2.4 Working With Your Schema ................................................................................21 2.5 Validating XML and JSON Data Against a Schema ............................................22 2.5.1 Validating Schemas using Schematron .....................................................22 2.5.2 Validating Schemas using the XQuery validate Expression ....................25 2.5.3 Validating JSON Documents against JSON Schemas ..............................26 3.0 Understanding Transactions in MarkLogic Server ......................................28 3.1 Terms and Definitions ..........................................................................................29 3.2 Overview of MarkLogic Server Transactions ......................................................31 3.2.1 Key Transaction Attributes .......................................................................32 3.2.2 Understanding Statement Boundaries .......................................................33 3.2.3 Single-Statement Transaction Concept Summary ....................................35 3.2.4 Multi-Statement Transaction Concept Summary .....................................36 3.3 Commit Mode .......................................................................................................37 3.4 Transaction Type ..................................................................................................38 3.4.1 Transaction Type Overview ......................................................................38 3.4.2 Controlling Transaction Type in XQuery .................................................39 3.4.3 Controlling Transaction Type in JavaScript .............................................42 3.4.4 Query Transactions: Point-in-Time Evaluation ........................................44 3.4.5 Update Transactions: Readers/Writers Locks ...........................................45 3.4.6 Example: Query and Update Transaction Interaction ...............................48 3.5 Single vs. Multi-statement Transactions ...............................................................48 3.5.1 Single-Statement, Automatically Committed Transactions ......................49 3.5.2 Multi-Statement, Explicitly Committed Transactions ..............................49 3.5.3 Semi-Colon as a Statement Separator .......................................................54 3.6 Transaction Mode .................................................................................................56 3.6.1 Transaction Mode Overview ....................................................................56 3.6.2 Auto Transaction Mode ............................................................................58 3.6.3 Query Transaction Mode ..........................................................................59 MarkLogic 10—May, 2019 Application Developer’s Guide—Page 2 MarkLogic Server Table of Contents 3.6.4 Update Transaction Mode .........................................................................59 3.6.5 Query-Single-Statement Transaction Mode .............................................60 3.6.6 Multi-Auto Transaction Mode ..................................................................61 3.7 Interactions with xdmp:eval/invoke ......................................................................61 3.7.1 Isolation Option to xdmp:eval/invoke ......................................................61 3.7.2 Preventing Deadlocks ...............................................................................63 3.7.3 Seeing Updates From eval/invoke Later in the Transaction .....................65 3.7.4 Running Multi-Statement Transactions under xdmp:eval/invoke ............66 3.8 Functions With Non-Transactional Side Effects ..................................................67 3.9 Reducing Blocking with Multi-Version Concurrency Control .............................68 3.10 Administering Transactions ..................................................................................68 3.11 Transaction Examples ...........................................................................................69 3.11.1 Example: Multi-statement Transactions and Same-statement Isolation ...69 3.11.2 Example: Multi-Statement Transactions and Different-transaction Isolation 70 3.11.3 Example: Generating a Transaction Report With xdmp:host-status ........72 4.0 Working With Binary Documents ...............................................................74 4.1 Terminology ..........................................................................................................74 4.2 Loading Binary Documents ..................................................................................75 4.3 Configuring MarkLogic Server for Binary Content .............................................75 4.3.1 Setting the Large Size Threshold ..............................................................75 4.3.2 Sizing and Scalability of Binary Content .................................................76 4.3.3 Selecting a Location For Binary Content .................................................77 4.3.4 Monitoring the Total Size of Large Binary Data in a Forest ....................78 4.3.5 Detecting and Removing Orphaned Binaries ...........................................79 4.4 Developing Applications That Use Binary Documents ........................................80 4.4.1 Adding Metadata to Binary Documents Using Properties ........................80 4.4.2 Downloading Binary Content With HTTP Range Requests ....................81 4.4.3 Creating Binary Email Attachments .........................................................83 4.5 Useful Built-ins for Manipulating Binary Documents .........................................84 5.0 Importing XQuery Modules, XSLT Stylesheets, and Resolving Paths .......86 5.1 XQuery Library Modules and Main Modules ......................................................86 5.1.1 Main Modules ...........................................................................................86 5.1.2 Library Modules .......................................................................................87 5.2 Rules for Resolving Import, Invoke, and Spawn Paths ........................................87 5.3 Module Caching Notes .........................................................................................89 5.4 Example Import Module Scenario ........................................................................90 6.0 Library Services Applications ......................................................................91 6.1 Understanding Library Services ...........................................................................91 6.2 Building Applications with Library Services .......................................................93 6.3 Required Range Element Indexes .........................................................................93 6.4 Library Services API ............................................................................................94 MarkLogic 10—May, 2019 Application Developer’s Guide—Page 3 MarkLogic Server Table of Contents 6.4.1 Library Services API Categories ..............................................................95 6.4.2 Managed Document Update Wrapper Functions ......................................95 6.5 Security Considerations of Library Services Applications ...................................96 6.5.1 dls-admin Role ..........................................................................................96 6.5.2 dls-user Role .............................................................................................96 6.5.3 dls-internal Role ........................................................................................97 6.6 Transactions and Library Services ........................................................................97 6.7 Putting Documents Under Managed Version Control ..........................................97 6.8 Checking Out Managed Documents .....................................................................98 6.8.1 Displaying the Checkout Status of Managed Documents ........................98 6.8.2 Breaking the Checkout of Managed Documents ......................................98 6.9 Checking In Managed Documents ........................................................................99 6.10 Updating Managed Documents ............................................................................99