Skip to content

Commit 4020275

Browse files
rjrudinrjrudin
committed
Extracted CONTRIBUTING.md info
Didn't want this buried in the README. It's a little awkward still because .github/CONTRIBUTING.md exists with a bunch of boilerplate on how to create and submit a PR. That can be cleaned up later. The key is for the top-level CONTRIBUTING.md to describe how to actually develop and test an enhancement. Also removed the "What's new" content from the README. This was a bit random - some for Java 4, some for Java 5.3. The CHANGELOG has all this data too, so I removed it from the README.
1 parent 3e7d694 commit 4020275

File tree

2 files changed

+45
-88
lines changed

2 files changed

+45
-88
lines changed

‎CONTRIBUTING.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
To develop the Java Client and ultimately submit a pull request, you'll first need to be able to build the client and
2+
run the tests locally.
3+
4+
Please see [this guide](.github/CONTRIBUTING.md) for information on creating and submitting a pull request.
5+
6+
To build the client locally, complete the following steps:
7+
8+
1. Clone this repository on your machine.
9+
2. Choose the appropriate branch (usually develop)
10+
3. Ensure you are using Java 8 or Java 11
11+
4. Verify that you can build the client by running `./gradlew build -x test`
12+
13+
"Running the tests" in the context of developing and submitting a pull request refers to running the tests found
14+
in the `marklogic-client-api` module. The tests for this module depend on a
15+
[ml-gradle](https://github.com/marklogic-community/ml-gradle) application being deployed from the `test-app` module.
16+
This application contains a number of database and security resources that the tests depend on.
17+
The `./gradle.properties` file defines the connection properties for this application; these default
18+
to `localhost` and an admin password of `admin`. To override these, create the file `./gradle-local.properties`
19+
and add the following (you can override additional properties as necessary):
20+
21+
mlHost=changeme
22+
mlPassword=changeme
23+
24+
Note that additional properties are defined via `./tests-app/gradle.properties`, though it is not expected that these
25+
properties will need to be changed.
26+
27+
The application is then deployed via the following command:
28+
29+
./gradlew mlDeploy -i
30+
31+
You can then run the tests, which will use the values of `mlHost` and `mlPassword` for connecting to MarkLogic as an
32+
admin user:
33+
34+
./gradlew marklogic-client-api:test
35+
36+
Individual tests can be run in the following manner (replace `GraphsTest` with the name of the test class you wish to run):
37+
38+
./gradlew marklogic-client-api:test --tests GraphsTest
39+
40+
You can also undeploy the test application if you do not wish to keep it around on your MarkLogic instance:
41+
42+
./gradlew mlUndeploy -i -Pconfirm=true

‎README.md‎

Lines changed: 3 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -30,60 +30,20 @@ The Java API supports the following core features of the MarkLogic database:
3030
* Call Data Services by means of a Java interface on the client for data functionality
3131
implemented by an endpoint on the server.
3232

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
33+
## QuickStart
7434

7535
To use the API in your maven project, include the following in your pom.xml:
7636

7737
<dependency>
7838
<groupId>com.marklogic</groupId>
7939
<artifactId>marklogic-client-api</artifactId>
80-
<version>5.2.0</version>
40+
<version>6.0.0</version>
8141
</dependency>
8242

8343
For gradle projects, use gradle 4.x+ and include the following:
8444

8545
dependencies {
86-
compile group: 'com.marklogic', name: 'marklogic-client-api', version: '5.3.0'
46+
compile "com.marklogic:marklogic-client-api:6.0.0"
8747
}
8848

8949
Read [The Java API in Five Minutes](http://developer.marklogic.com/try/java/index)
@@ -118,50 +78,5 @@ Files can be verified with the command:
11878
$ gpg marklogic-client-api-5.3.0.jar.asc
11979

12080

121-
### Building and Contributing
122-
123-
You can build the API in the same way as any Gradle project on git:
124-
125-
1. Clone the java-client-api repository on your machine.
126-
2. Choose the appropriate branch (usually develop)
127-
3. Execute a Gradle build in the directory containing the main project's build.gradle file.
128-
129-
You might want to skip the tests until you have configured a test database and REST server:
130-
131-
$ ./gradlew build -x test
132-
133-
See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for more on contributing to this github project.
134-
135-
### Running JUnit Tests
136-
137-
The JUnit tests depend on an [ml-gradle](https://github.com/marklogic-community/ml-gradle) application being deployed.
138-
This application contains a number of database and security settings that the tests depend on.
139-
The `./gradle.properties` file defines the connection properties for this application; these default
140-
to `localhost` and an admin password of `admin`. To override these, create the file `./gradle-local.properties`
141-
and add the following (you can override additional properties as necessary):
142-
143-
mlHost=changeme
144-
mlPassword=changeme
145-
146-
Note that additional properties are defined via `./tests-app/gradle.properties`, though it is not expected that these
147-
properties will need to be changed.
148-
149-
The application is then deployed via the following command:
150-
151-
./gradlew mlDeploy -i
152-
153-
You can then run the tests, which will use the values of `mlHost` and `mlPassword` for connecting to MarkLogic as an
154-
admin user:
155-
156-
./gradlew marklogic-client-api:test
157-
158-
Individual tests can be run in the following manner (replace `GraphsTest` with the name of the test class you wish to run):
159-
160-
./gradlew marklogic-client-api:test --tests GraphsTest
161-
162-
You can also undeploy the test application if you do not wish to keep it around on your MarkLogic instance:
163-
164-
./gradlew mlUndeploy -i -Pconfirm=true
165-
16681
## Support
16782
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

Comments
 (0)