Crowd 2.1 REST Java Client Migration guide

This page tells you how to update your SOAP based-client application code to the new REST client when updating from Crowd 2.0.x to Crowd 2.1.0 or later.

Step 1. Add additional dependency

Add a dependency on crowd-integration-client-rest. Remove the previous dependency on crowd-integration-client-api.

1
2
<dependencies>
  <dependency>
    <groupId>com.atlassian.crowd</groupId>
    <artifactId>crowd-integration-client-rest</artifactId>
  </dependency>
</dependencies>

Step 2. Create a CrowdClient and CrowdHttpAuthenticator

1
2
final ClientProperties clientProperties = ClientPropertiesImpl.newInstanceFromProperties(properties);
final CrowdClient crowdClient = com.atlassian.crowd.integration.rest.service.factory.RestCrowdClientFactory.newInstance(clientProperties);
final CrowdHttpAuthenticator crowdHttpAuthenticator = new CrowdHttpAuthenticatorImpl(crowdClient, clientProperties, CrowdHttpTokenHelperImpl.getInstance());

Step 3. Update old SOAP specific classes to new integration classes

New classes and interfaces replace the functionality of the older classes that were tied to the SOAP API. A list of some of the common classes and their mappings appear below. This list is by no means exhaustive - we encourage developers to move away from SOAP specific classes to the generic interfaces and move to using REST instead of SOAP.

Other changes to note:

• Previously retrieving the details such as the first name or last name of a user required retrieving the corresponding attribute of the user. These details are now standard fields of the User object returned by CrowdClient and CrowdHttpAuthenticator.
• Most of the methods in CrowdHttpAuthenticator should be familiar from using HttpAuthenticator with only minor changes in the methods. E.g. getUser instead of getPrincipal and logout instead of logoff.

Step 4. Update search code

CrowdClient allows for more powerful searching capabilities than ever before. Membership queries are now possible with CrowdClient. To perform a search, create a SearchRestriction using the com.atlassian.crowd.search.builder.Combine and com.atlassian.crowd.search.builder.Restriction classes.

Important search classes:

• com.atlassian.crowd.embedded.api.SearchRestriction Interface for search restrictions defining what results should be returned
• com.atlassian.crowd.search.builder.Combine Creates a boolean AND or OR search restriction
• com.atlassian.crowd.search.builder.Restriction Creates a restriction based on a property of the entity and a matching criteria
• com.atlassian.crowd.search.query.entity.restriction.constants.UserTermKeys Defines some user properties
• com.atlassian.crowd.search.query.entity.restriction.constants.GroupTermKeys Defines some group properties

For example, to find a user with a first name of "Bob" and an email address starting with "b", you can do the following:

1
2
Combine.allOf(Restriction.on(UserTermKeys.FIRST_NAME).exactlyMatching("Bob"),
              Restriction.on(UserTermKeys.EMAIL).startingWith("b"));

More examples can be found on the QueryBuilder API Javadocs.