Rename JAR to marklogic-client-api-M.m.p.jar

[jmakeig]

Today, the Java Client API is packaged as java-client-api-M.m.p.jar, for Major version, minor , patch. This makes it difficult to recognize, for example, in the classpath list of an IDE. A developer is likely looking for marklogic in the name somewhere. (It’s obvious that it’s Java already.)

Update the artifact (and its references in Maven et al) to be marklogic-client-api-M.m.p.jar.

Some relevant external examples:

<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongodb-driver</artifactId>
    <version>3.3.0</version>
</dependency>

<dependency>
  <groupId>com.datastax.cassandra</groupId>
  <artifactId>cassandra-driver-core</artifactId>
  <version>3.1.0</version>
</dependency>

<dependency>
  <groupId>com.oracle.jdbc</groupId>
  <artifactId>ojdbc7</artifactId>
  <version>12.1.0.2</version>
</dependency>

[sammefford]

One thing to note is that this will shift our mvnrepository history away from https://mvnrepository.com/artifact/com.marklogic/java-client-api and instead we'll need to create https://mvnrepository.com/artifact/com.marklogic/marklogic-client-api

[kcoleman-marklogic]

I guess Java gets to be THE Marklogic client API because we don't ever put the Node.js client distribution in maven?

[sammefford]

That makes sense to me. And if we want to put XCC into maven, we can call it XCC . . .

[jmakeig]

I guess Java gets to be THE Marklogic client API because we don't ever put the Node.js client distribution in maven?

Yes, npm is Node.js’s Maven equivalent.

One thing to note is that this will shift our mvnrepository history away from https://mvnrepository.com/artifact/com.marklogic/java-client-api

Can we edit that page with a link to the new one? And vice versa?

[jmakeig]

Note also, that the version string has changed from a hyphen to a dot to separate the minor and the patch. This aligns better with generally accepted semver.

[sammefford]

Can we edit that page with a link to the new one? And vice versa?

Not that I'm aware of. The page is auto-generated.

Note also, that the version string has changed from a hyphen to a dot to separate the minor and the patch. This aligns better with generally accepted semver.

The version string has changed in the description on this issue. But using dots to separate the minor and the patch versions has been a part of the java-client-api releases since we started on github.

[grechaw]

Right now, the project name here in github, the jar name, and maven names all align. I think that's a plus.

It also makes a project look fickle if you go to a page like this and after just a couple of releases it looks gone:

https://mvnrepository.com/artifact/com.marklogic/java-client-api

[sammefford]

Agreed, Charles, that it's not ideal to change the artifact id.

I talked with Justin, and his take is getting "marklogic" in the name is worth enough that we should take the hit on "looking fickle" in mvnrepository. I'm fine with that. So I think we'll proceed barring any other objections.

[grechaw]

OK, so long as it's deliberate

[grechaw]

Changing for ea-4 at this time means we need to update downstream projects too. Not particularly happy about it, but will deal.

[grechaw]

better to do now than later

[sammefford]

We discussed today in the API Team meeting, and agreed that we will:

1. change the jar name as proposed
2. change the maven central artifact id to "marklogic-client-api"
3. leave the github project name as it is

For 1 and 2, we are making the change because it's obvious in the context of a jar or maven central that we're talking about java, but when someone looks at the jar or artifact id in eclipse, it may not be obvious that we're talking about marklogic. For 3, we're not making a change because github hosts more than just java, so we need to clarify which client api we're talking about here: /marklogic/java-client-api or /marklogic/node-client-api

[robsman]

Maybe we could publish a relocation POM under the old artifact ID for some transition period? Benefits are:

• downstream projects don't need to be adjusted immediately
• the Maven repos will contain an official trace that the old artifact was renamed

See https://maven.apache.org/pom.html#Relocation

[grechaw]

👍

[sammefford]

Wonderful! 👍

[grechaw]

@rashiatmarklogic just noted that this change has gone into develop branch. Is it tracked in another spot besides this issue?

[grechaw]

@sammefford this commit is in develop, but not referenced -- is there another issue for tracking this change? I think this task should be set to 'test' now.

[sammefford]

@grechaw , perhaps we need to break this process into multiple issues. I was looking at the change in the pom.xml as just the first step. I'm thinking the bigger step is getting things published in maven central and developer.marklogic.com, and testing everything. That's why this is assigned to @itsshivaverma , because it's my understanding he'll take lead on this.

[sammefford]

@robsman , I looked at the link about relocation, and I'm not groking how to apply it to us. Downstream projects shouldn't need to change immediately . . . we can leave old versions available as they are now. The only reason they'll need to change is if they want to use our upcoming releases, in which case they'll need to change both the artifact id and the version.

the Maven repos will contain an official trace that the old artifact was renamed

Can you help me understand how to achieve this? Should we publish a dummy release with this relocation tag in the pom.xml?

[sammefford]

Looks like I'm not the first to be confused: http://maven.40175.n5.nabble.com/Changing-the-groupId-artifactId-of-an-artifact-in-the-next-version-but-keep-maven-conflict-detection-td3345769.html

[sammefford]

Maybe we just follow steps 4-6 plus "Releasing the next version" under "How to relocate a Maven 2 artifact to a different groupId" at Guide to relocation. We're just changing the artifactid, but it seems the steps are the same. I'm thinking we don't need to move any folders. True?

[robsman]

I think this requires to publish one additional POM per release for a transition period. This can be a
stripped down relocation POM, but has to be under the old coordinate com.marklogic:java-client-api:x.y.z.
The real JAR's POM would go under the new coordinate com.marklogic:marklogic-client-api:x.y.z. Java package names should remain as is.

Previously published POMs would require no adjustment. Just from release 4.0.1 on these two POMs would exist in parallel and make it more convenient for clients using a variable to quickly switch between versions of the MarkLogic API, even if they switch between 3.x.y and 4.x.y.

I have set up a quick validation of this approach, please see https://github.com/robsman/maven-relocation-demo.

[sammefford]

Wow, you rock, @robsman, thanks!

[georgeajit]

Tested with EA4 release. Works.