java client, based on spring http interface, to interact with Bitbucket's REST API. Note: Support java 21 with spring 6.2.x
Being built on top of Spring-webflux 6.X for use http interface client https://www.baeldung.com/spring-6-http-interface means things are broken up into Apis.
Apis are just Interfaces that are analagous to a resource provided by the server-side program (e.g. /api/branches, /api/pullrequest, /api/commits, etc..).
The methods within these Interfaces are analagous to an endpoint provided by these resources (e.g. GET /api/branches/my-branch, GET /api/pullrequest/123, DELETE /api/commits/456, etc..).
The user only needs to be concerned with which Api they need and then calling its various methods. These methods, much like any java library, return domain objects
(e.g. POJO's) modeled after the json returned by bitbucket.
Interacting with the remote service becomes transparent and allows developers to focus on getting things done rather than the internals of the API itself, or how to build a client, or how to parse the json.
New Api's or endpoints are generally added as needed and/or requested. If there is something you want to see just open an ISSUE and ask or send in a PullRequest. However, putting together a PullRequest for a new feature is generally the faster route to go as it's much easier to review a PullRequest than to create one ourselves. There is no problem doing so of course but if you need something done now than a PullRequest is your best bet otherwise you may have to patiently wait for one of our contributors to take up the work.
- The next milestone is support reactive Mono and Flux objects
Can be sourced from maven like so:
<dependency>
<groupId>io.github.hillelmed</groupId>
<artifactId>bitbucket-client</artifactId>
<version>X.Y.Z</version>
<classifier>sources|tests|javadoc|all</classifier> (Optional)
</dependency>
We use semantic version for upload and upgrade versions
Can be found via github pages here
When using Basic (e.g. username and password) authentication:
String url = "http://127.0.0.1:7990";
String user = "admin";
String password = "password";
BitbucketProperties bitbucketProperties = new BitbucketProperties(url, user, password);
BitbucketClient client = BitbucketClient.create(bitbucketProperties);
Version version = client.api().systemApi().version();
When using Anonymous authentication or sourcing from system/environment (as described below):
String url = "http://127.0.0.1:7990";
BitbucketProperties bitbucketProperties = new BitbucketProperties(url);
BitbucketClient client = BitbucketClient.create(bitbucketProperties);
Version version = client.api().systemApi().version();
Because we are built on top of Http interface using webClient we can take advantage of overriding various internal HTTP properties by
passing in a BitbucketClient.create object WebClient and custom BitbucketClient create(BitbucketProperties bitbucketProperties, WebClient webClient) or, and in following with the spirit of this library, configuring them
found HERE.
When configuring through a BitbucketClient object you must pass in create the customer WebClient:
//Default webClient when use regular client create
WebClient webClient = WebClient.builder()
.uriBuilderFactory(factory)
.filter(bitbucketAuthenticationFilter)
.filter(scrubNullFromPathFilter)
.filter(BitbucketErrorHandler.handler())
.build();
When Passing through BitbucketClient :
WebClient myWebClient = WebClient.builder()
.uriBuilderFactory(url)
.filter(myFilterErrorHandling)
.build();
BitbucketProperties bitbucketProperties = new BitbucketProperties(url);
BitbucketClient client = BitbucketClient.create(bitbucketProperties,myWebClient);
When something pops server-side bitbucket will hand us back a list of BitbucketError objects. we're throwing an exception at runtime we attach this List of Error objects
The throwing object is Bitbucket BitbucketAppException.java
to most domain objects. Thus, it is up to the user to check the handed back domain object to see if the attached List is empty, and if not, iterate over the Error objects to see if it's something
truly warranting an exception. List of Error objects itself will always be non-null but in most cases empty (unless something has failed).
An example on how one might proceed:
try {
PullRequest pullRequest = client.api().pullRequestApi().get("MY-PROJECT", "MY-REPO", 99999).getBody();
} catch (BitbucketAppException e) {
for(Error error : e.errors()) {
if (error.message().matches(".*Pull request \\d+ does not exist in .*")) {
throw new RuntimeException(error.message());
}
}
}
The mock and live tests provide many examples that you can use in your own code. If there are any questions feel free to open an issue and ask.
- Spring 6 - used as the backend for communicating with Bitbucket's REST API
- Jackson data-bind - used to create value serialized types both to and from the bitbucket program
- Lombok - Automate getter setter contracture program
Running mock tests can be done like so:
./mvn test -Punit
Running integration tests can be done like so (requires Bitbucket instance):
./mvn test -Plive
Various properties exist for you to configure