Migrating to v1 of the Java SDK

The v1 release of the Java SDK represents a significant rethinking of the developer experience. The biggest new feature is the flexible Query Builder API, and there are a few other breaking changes to be aware of.

Packages

The public API surface has been consolidated. Most top-level methods are now directly available under the com.osohq.oso_cloud package via the Oso class. Query-related functionality is accessible through the QueryBuilder returned by oso.buildQuery() and the com.osohq.oso_cloud.querybuilder package.

Key types like Fact and Value, previously found in com.osohq.oso_cloud.api, are now directly available under com.osohq.oso_cloud. When migrating, you will need to update your import statements. For example, if you were using Value and Fact (which were often implicitly used or needed for methods in v0), your imports would change as follows:

Additionally, it's important to note that in v1, Fact and Value constructors no longer accept null for type or id fields. In v0, passing null to a Value constructor was a way to achieve wildcard behavior in oso.get(). In v1, this wildcard behavior is now explicitly handled by ValuePattern.ANY and ValuePattern.ValueOfType when using FactPattern with methods like oso.get() and oso.delete().

Centralized Authorization Data API

The Centralized Authorization Data API has been condensed and made more consistent.

tell to insert

To migrate from tell to insert, you first need to ensure your imports are updated, and then wrap the arguments in a Fact object:

This new Fact-based syntax aligns with how facts are represented across the rest of the API.

delete

To migrate from the previous delete API (for specific facts), update your imports and wrap the arguments in a Fact object:

Additionally, there is a new delete method that supports deleting all facts matching a pattern using FactPattern and wildcards (ValuePattern.ANY or ValuePattern.ValueOfType):

get

The get method now accepts a FactPattern to specify which facts to retrieve, allowing for wildcard matching using ValuePattern.ANY and ValuePattern.ValueOfType.

Previously, in v0, wildcard matches in get were achieved by passing null as an argument to a Value constructor (e.g., new Value("User", null)) or by passing null directly as an argument for one of the fact's positions. This is no longer supported.

Here's how to migrate a get call that used null for wildcards:

The following examples further illustrate using the v1 get(FactPattern) method:

bulk to batch or delete

To migrate from bulk to batch, use the oso.batch() method which accepts a Consumer<BatchTransaction>. Call tx.delete() and tx.insert() within the consumer lambda:

Additionally, the delete API now handles deleting many facts at once via FactPattern with wildcards. If you were previously using the bulk API just to delete many facts at once, you can now use the delete API directly:

bulkTell to batch

To migrate from bulkTell to batch, use the oso.batch() method with a Consumer<BatchTransaction> and call tx.insert() for each fact within the lambda:

bulkDelete to batch

To migrate from bulkDelete to batch, use the oso.batch() method with a Consumer<BatchTransaction> and call tx.delete() for each fact or pattern within the lambda:

Additionally, the batch method supports deleting facts matching patterns via FactPattern within the transaction:

Query API

We've replaced the Query API with a more powerful and flexible QueryBuilder API with a fluent interface. We've also dropped the AuthorizeResources API in favor of the QueryBuilder.

query to buildQuery

We recommend taking a look at the reference docs for the new QueryBuilder API. It's more flexible and expressive than the old Query API, and it may let you simplify your application code.

But if you just want to migrate your existing queries as-is, here's how.

Queries with no wildcards

Typically, a query with no wildcards is used to check for the existence of a derived rule or fact.

With the old Query API:

With the new QueryBuilder API:

Queries with type-constrained wildcards

The old Query API let you query for all the results of a particular type using null or potentially type markers. To migrate these, replace type-constrained wildcards with a TypedVar variable.

With the old Query API:

With the new QueryBuilder API:

If you have several type-constrained wildcards in a single query, you may prefer to get results as a map:

Queries with unconstrained wildcards

The old Query API let you use null to query for many types of results at once:

In the new QueryBuilder API, this is no longer possible directly.

Instead, make one request for each concrete type:

Handling wildcards in results

The old Query API sometimes returned results containing null, indicating that any value could apply at a particular position. For example:

The new QueryBuilder API will instead return a list containing the string "*" to mean the same thing, just like the Check APIs:

Context facts

If you are using context facts with query, check out the withContextFacts QueryBuilder method.

authorizeResources to buildQuery

The authorizeResources API was used to authorize many resources for a single actor and action.

With the old Query API:

With the new QueryBuilder API:

If you are using context facts with authorizeResources, check out the withContextFacts QueryBuilder method.

Exported Types

You can now rely primarily on types exported directly from com.osohq.oso_cloud like Oso, Value, Fact, FactPattern, TypedVar and the QueryBuilder related classes/interfaces rather than implementation details previously exposed.