|
1 | | -# The MarkLogic Java Client API |
2 | | - |
3 | | -The API makes it easy to write, read, delete, and find documents |
4 | | -in a [MarkLogic](http://developer.marklogic.com/) database. |
5 | | - |
6 | | -For example: |
7 | | - |
8 | | - // write a text, binary, XML, or JSON document from any source with ACID guarantees |
9 | | - documentManager.write(uri, new FileHandle() |
10 | | - .with(new File("file1234.json")) |
11 | | - .withFormat(JSON)); |
12 | | - |
13 | | - // read and directly parse to your preferred type, even your own POJOs! |
14 | | - JsonNode jsonDocContents = documentManager.readAs(uri, JsonNode.class); |
15 | | - |
16 | | - // get matches super-fast using full-featured search |
17 | | - JsonNode results = queryManager.search( |
18 | | - new StructuredQueryBuilder().term("quick", "brown", "fox"), |
19 | | - new JacksonHandle()).get(); |
20 | | - |
21 | | -The Java API supports the following core features of the MarkLogic database: |
22 | | - |
23 | | -* Write and read binary, JSON, text, and XML documents. |
24 | | -* Query data structure trees, marked-up text, and all the hybrids in between those extremes. |
25 | | -* Project values, tuples, and triples from hierarchical documents and aggregate over them. |
26 | | -* Patch documents with partial updates. |
27 | | -* Use Optimistic Locking to detect contention without creating locks on the server. |
28 | | -* Execute ACID modifications so the change either succeeds or throws an exception. |
29 | | -* Execute multi-statement transactions so changes to multiple documents succeed or fail together. |
30 | | -* Call Data Services by means of a Java interface on the client for data functionality |
31 | | -implemented by an endpoint on the server. |
32 | | - |
33 | | -### What's New in Java Client API 5 |
34 | | - |
35 | | -* Upgrade to OkHttp 4.4.0 release. |
36 | | -* Splitters for CSV records, for entries in a ZipInputStream, and for line-delimited JSON or XML |
37 | | -for streaming to WriteBatcher. |
38 | | -* Support for Bulk IO Data Services to make it easy to implement connectors for dataflow |
39 | | -frameworks - see https://github.com/marklogic/java-client-api/wiki/Bulk-Data-Services for more |
40 | | -detail. |
41 | | - |
42 | | -### What's New in Java Client API 4 |
43 | | - |
44 | | -* Optic API - blends relational with NoSQL by providing joins and aggregates over documents |
45 | | - * is powered by the new row index and query optimizer |
46 | | - * uses row, triple, and/or lexicon lenses |
47 | | - * matches the functionality of the Optic API for XQuery and Javascript, but idiomatic for Java |
48 | | - developers |
49 | | -* Data Movement SDK - move large amounts of data into, out of, or within a MarkLogic cluster |
50 | | - * WriteBatcher distributes writes across many threads and across the entire MarkLogic cluster |
51 | | - * QueryBatcher enables bulk processing or export of matches to a query by distributing the query |
52 | | - across many threads and batch processing to listeners |
53 | | - * Comes with ApplyTransformListener, DeleteListener, ExportListener, ExportToWriterListener, and |
54 | | - UrisToWriterListener |
55 | | - * With custom listeners you can easily and efficiently apply your business logic to batches of query |
56 | | - matches |
57 | | -* Kerberos and Client Certificate Authentication |
58 | | -* Geospatial double precision and queries on region indexes |
59 | | -* Temporal document enhancements |
60 | | - * protect and wipe |
61 | | - * more control over version uris |
62 | | -* Support for document metadata values |
63 | | - |
64 | | -See also [CHANGELOG.md](CHANGELOG.md) |
65 | | - |
66 | | -### QuickStart |
67 | | - |
68 | | -To use the API in your maven project, include the following in your pom.xml: |
69 | | - |
70 | | - <dependency> |
71 | | - <groupId>com.marklogic</groupId> |
72 | | - <artifactId>marklogic-client-api</artifactId> |
73 | | - <version>5.2.0</version> |
74 | | - </dependency> |
75 | | - |
76 | | -And add this repository to your pom.xml repositories section: |
77 | | - |
78 | | - <repository> |
79 | | - <id>jcenter</id> |
80 | | - <url>http://jcenter.bintray.com</url> |
81 | | - </repository> |
82 | | - |
83 | | -For gradle projects, include the following: |
84 | | - |
85 | | - dependencies { |
86 | | - compile group: 'com.marklogic', name: 'marklogic-client-api', version: '5.2.0' |
87 | | - } |
88 | | - |
89 | | -Use gradle 1.7+ and add this to your build.gradle repositories section: |
90 | | - |
91 | | - jcenter() |
92 | | - |
93 | | -Read [The Java API in Five Minutes](http://developer.marklogic.com/try/java/index) |
94 | | - |
95 | | -### Learning More |
96 | | - |
97 | | -The following resources document the Java API: |
98 | | - |
99 | | -* [Java Application Developer's Guide](http://docs.marklogic.com/guide/java) |
100 | | -* [JavaDoc](http://docs.marklogic.com/javadoc/client/index.html) |
101 | | - |
102 | | -### Installing |
103 | | - |
104 | | -To use the Java API, either add Maven or Gradle dependency as explained above or download the jar and its dependencies: |
105 | | - |
106 | | -http://developer.marklogic.com/products/java |
107 | | - |
108 | | -Of course, you'll also need to install the database -- which you can do for free with |
109 | | -the developer license: |
110 | | - |
111 | | -https://developer.marklogic.com/free-developer |
112 | | - |
113 | | -To obtain verified downloads signed with MarkLogic's PGP key, use maven tools or directly download |
114 | | -the .jar and .asc files from |
115 | | -[maven central](http://repo1.maven.org/maven2/com/marklogic/marklogic-client-api/5.2.0/). MarkLogic's |
116 | | -pgp key ID is 48D4B86E and it is available from pgp.mit.edu by installing gnupg and running the command: |
117 | | - |
118 | | - $ gpg --keyserver pgp.mit.edu --recv-key 48D4B86E |
119 | | - |
120 | | -Files can be verified with the command: |
121 | | - |
122 | | - $ gpg marklogic-client-api-5.2.0.jar.asc |
123 | | - |
124 | | - |
125 | | -### Building and Contributing |
126 | | - |
127 | | -You can build the API in the same way as any Gradle project on git: |
128 | | - |
129 | | -1. Clone the java-client-api repository on your machine. |
130 | | -2. Choose the appropriate branch (usually develop) |
131 | | -3. Execute a Gradle build in the directory containing the main project's build.gradle file. |
132 | | - |
133 | | -You might want to skip the tests until you have configured a test database and REST server: |
134 | | - |
135 | | - $ ./gradlew build -x test |
136 | | - |
137 | | -See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for more on contributing to this github project. |
138 | | - |
139 | | -### Running JUnit Tests |
140 | | - |
141 | | - $ ./gradlew java-client-api:compileTestJava |
142 | | - $ ./gradlew testServerInit |
143 | | - $ ./gradlew java-client-api:test |
144 | | - |
145 | | -## Support |
146 | | -The MarkLogic Java Client API is maintained by [MarkLogic](https://www.marklogic.com/) Engineering and is made available under the [Apache 2.0 license](https://github.com/marklogic/java-client-api/blob/master/LICENSE). It is designed for use in production applications with MarkLogic Server. Everyone is encouraged to file bug reports, feature requests, and pull requests through [GitHub](https://github.com/marklogic/java-client-api/issues). This input is critical and will be carefully considered. However, we can’t promise a specific resolution or timeframe for any request. In addition, MarkLogic provides technical support for [release tags](https://github.com/marklogic/java-client-api/releases) of the Java Client API to licensed customers under the terms outlined in the [MarkLogic Technical Support Handbook](http://www.marklogic.com/files/Mark_Logic_Support_Handbook.pdf). Customers with an active maintenance contract can sign up for MarkLogic Technical Support on our [support portal](https://help.marklogic.com/). |
| 1 | +# The MarkLogic Java Client API |
| 2 | + |
| 3 | +The API makes it easy to write, read, delete, and find documents |
| 4 | +in a [MarkLogic](http://developer.marklogic.com/) database. |
| 5 | + |
| 6 | +For example: |
| 7 | + |
| 8 | + // write a text, binary, XML, or JSON document from any source with ACID guarantees |
| 9 | + documentManager.write(uri, new FileHandle() |
| 10 | + .with(new File("file1234.json")) |
| 11 | + .withFormat(JSON)); |
| 12 | + |
| 13 | + // read and directly parse to your preferred type, even your own POJOs! |
| 14 | + JsonNode jsonDocContents = documentManager.readAs(uri, JsonNode.class); |
| 15 | + |
| 16 | + // get matches super-fast using full-featured search |
| 17 | + JsonNode results = queryManager.search( |
| 18 | + new StructuredQueryBuilder().term("quick", "brown", "fox"), |
| 19 | + new JacksonHandle()).get(); |
| 20 | + |
| 21 | +The Java API supports the following core features of the MarkLogic database: |
| 22 | + |
| 23 | +* Write and read binary, JSON, text, and XML documents. |
| 24 | +* Query data structure trees, marked-up text, and all the hybrids in between those extremes. |
| 25 | +* Project values, tuples, and triples from hierarchical documents and aggregate over them. |
| 26 | +* Patch documents with partial updates. |
| 27 | +* Use Optimistic Locking to detect contention without creating locks on the server. |
| 28 | +* Execute ACID modifications so the change either succeeds or throws an exception. |
| 29 | +* Execute multi-statement transactions so changes to multiple documents succeed or fail together. |
| 30 | +* Call Data Services by means of a Java interface on the client for data functionality |
| 31 | +implemented by an endpoint on the server. |
| 32 | + |
| 33 | +### What's New in Java Client API 5 |
| 34 | + |
| 35 | +As of 5.3, the Java API was compiled with Java 8 and tested on Java 8 through 11. |
| 36 | + |
| 37 | +Features: |
| 38 | + |
| 39 | +* Splitters for CSV records, for entries in a ZipInputStream, for line-delimited JSON or XML |
| 40 | +records, and for large JSON or XML files for streaming to WriteBatcher. |
| 41 | +* Support for RowBatcher to make it easy to export rows and documents for a view as modified |
| 42 | +by a plan - see https://github.com/marklogic/java-client-api/wiki/Row-Batcher for more |
| 43 | +detail. |
| 44 | +* Support for Concurrent Bulk IO Data Services to make it easy to implement connectors for dataflow |
| 45 | +frameworks - see https://github.com/marklogic/java-client-api/wiki/Bulk-Data-Services for more |
| 46 | +detail. |
| 47 | +* Upgrade of dependencies including OkHttp 4.7.2 |
| 48 | + |
| 49 | +### What's New in Java Client API 4 |
| 50 | + |
| 51 | +* Optic API - blends relational with NoSQL by providing joins and aggregates over documents |
| 52 | + * is powered by the new row index and query optimizer |
| 53 | + * uses row, triple, and/or lexicon lenses |
| 54 | + * matches the functionality of the Optic API for XQuery and Javascript, but idiomatic for Java |
| 55 | + developers |
| 56 | +* Data Movement SDK - move large amounts of data into, out of, or within a MarkLogic cluster |
| 57 | + * WriteBatcher distributes writes across many threads and across the entire MarkLogic cluster |
| 58 | + * QueryBatcher enables bulk processing or export of matches to a query by distributing the query |
| 59 | + across many threads and batch processing to listeners |
| 60 | + * Comes with ApplyTransformListener, DeleteListener, ExportListener, ExportToWriterListener, and |
| 61 | + UrisToWriterListener |
| 62 | + * With custom listeners you can easily and efficiently apply your business logic to batches of query |
| 63 | + matches |
| 64 | +* Kerberos and Client Certificate Authentication |
| 65 | +* Geospatial double precision and queries on region indexes |
| 66 | +* Temporal document enhancements |
| 67 | + * protect and wipe |
| 68 | + * more control over version uris |
| 69 | +* Support for document metadata values |
| 70 | + |
| 71 | +See also [CHANGELOG.md](CHANGELOG.md) |
| 72 | + |
| 73 | +### QuickStart |
| 74 | + |
| 75 | +To use the API in your maven project, include the following in your pom.xml: |
| 76 | + |
| 77 | + <dependency> |
| 78 | + <groupId>com.marklogic</groupId> |
| 79 | + <artifactId>marklogic-client-api</artifactId> |
| 80 | + <version>5.2.0</version> |
| 81 | + </dependency> |
| 82 | + |
| 83 | +And add this repository to your pom.xml repositories section: |
| 84 | + |
| 85 | + <repository> |
| 86 | + <id>jcenter</id> |
| 87 | + <url>http://jcenter.bintray.com</url> |
| 88 | + </repository> |
| 89 | + |
| 90 | +For gradle projects, include the following: |
| 91 | + |
| 92 | + dependencies { |
| 93 | + compile group: 'com.marklogic', name: 'marklogic-client-api', version: '5.3.0' |
| 94 | + } |
| 95 | + |
| 96 | +Use gradle 4.x+ and add this to your build.gradle repositories section: |
| 97 | + |
| 98 | + jcenter() |
| 99 | + |
| 100 | +Read [The Java API in Five Minutes](http://developer.marklogic.com/try/java/index) |
| 101 | + |
| 102 | +### Learning More |
| 103 | + |
| 104 | +The following resources document the Java API: |
| 105 | + |
| 106 | +* [Java Application Developer's Guide](http://docs.marklogic.com/guide/java) |
| 107 | +* [JavaDoc](http://docs.marklogic.com/javadoc/client/index.html) |
| 108 | + |
| 109 | +### Installing |
| 110 | + |
| 111 | +To use the Java API, either add Maven or Gradle dependency as explained above or download the jar and its dependencies: |
| 112 | + |
| 113 | +http://developer.marklogic.com/products/java |
| 114 | + |
| 115 | +Of course, you'll also need to install the database -- which you can do for free with |
| 116 | +the developer license: |
| 117 | + |
| 118 | +https://developer.marklogic.com/free-developer |
| 119 | + |
| 120 | +To obtain verified downloads signed with MarkLogic's PGP key, use maven tools or directly download |
| 121 | +the .jar and .asc files from |
| 122 | +[maven central](https://repo1.maven.org/maven2/com/marklogic/marklogic-client-api/5.3.0/). MarkLogic's |
| 123 | +pgp key ID is 48D4B86E and it is available from pgp.mit.edu by installing gnupg and running the command: |
| 124 | + |
| 125 | + $ gpg --keyserver pgp.mit.edu --recv-key 48D4B86E |
| 126 | + |
| 127 | +Files can be verified with the command: |
| 128 | + |
| 129 | + $ gpg marklogic-client-api-5.3.0.jar.asc |
| 130 | + |
| 131 | + |
| 132 | +### Building and Contributing |
| 133 | + |
| 134 | +You can build the API in the same way as any Gradle project on git: |
| 135 | + |
| 136 | +1. Clone the java-client-api repository on your machine. |
| 137 | +2. Choose the appropriate branch (usually develop) |
| 138 | +3. Execute a Gradle build in the directory containing the main project's build.gradle file. |
| 139 | + |
| 140 | +You might want to skip the tests until you have configured a test database and REST server: |
| 141 | + |
| 142 | + $ ./gradlew build -x test |
| 143 | + |
| 144 | +See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for more on contributing to this github project. |
| 145 | + |
| 146 | +### Running JUnit Tests |
| 147 | + |
| 148 | + $ ./gradlew java-client-api:compileTestJava |
| 149 | + $ ./gradlew testServerInit |
| 150 | + $ ./gradlew java-client-api:test |
| 151 | + |
| 152 | +## Support |
| 153 | +The MarkLogic Java Client API is maintained by [MarkLogic](https://www.marklogic.com/) Engineering and is made available under the [Apache 2.0 license](https://github.com/marklogic/java-client-api/blob/master/LICENSE). It is designed for use in production applications with MarkLogic Server. Everyone is encouraged to file bug reports, feature requests, and pull requests through [GitHub](https://github.com/marklogic/java-client-api/issues). This input is critical and will be carefully considered. However, we can’t promise a specific resolution or timeframe for any request. In addition, MarkLogic provides technical support for [release tags](https://github.com/marklogic/java-client-api/releases) of the Java Client API to licensed customers under the terms outlined in the [MarkLogic Technical Support Handbook](http://www.marklogic.com/files/Mark_Logic_Support_Handbook.pdf). Customers with an active maintenance contract can sign up for MarkLogic Technical Support on our [support portal](https://help.marklogic.com/). |
0 commit comments