Package com.osohq.oso_cloud.querybuilder

Interface QueryBuilder

  • All Superinterfaces:
    QueryComposer<QueryBuilder>
    All Known Implementing Classes:
    QueryBuilderImpl
    public interface QueryBuilder
extends QueryComposer<QueryBuilder>
    Interface to support building a custom Oso query.

    Initialize this with oso.buildQuery and chain calls to and, in, and withContextFacts to add additional constraints.

    After building your query, run it and get the results by calling evaluate(EvaluateArg). The shape of the result is determined by the QueryBuilderImpl.EvaluateArg provided. Use the static factory methods in EvaluateArgs to easily construct the desired argument structure.

    Example usage: 

    
 Oso oso = new Oso("YOUR_API_KEY");
 TypedVar user = new TypedVar("User");
 TypedVar action = new TypedVar("String");
 TypedVar repo = new TypedVar("Repo");
 Value userVal = new Value("User", "alice");

 // Check if alice can read repo:acme
 boolean allowed = oso.buildQuery("allow", userVal, new Value("read"), new Value("Repo", "acme"))
                    .evaluate(EvaluateArgs.exists());

 // Get all actions alice can perform on repo:acme
 List<String> actions = oso.buildQuery("allow", userVal, action, new Value("Repo", "acme"))
                         .evaluate(EvaluateArgs.values(action));

 // Get map of Repo -> List<Action> for alice
 Map<String, List<String>> repoToActions = oso.buildQuery("allow", userVal, action, repo)
                                            .evaluate(EvaluateArgs.map(repo, EvaluateArgs.values(action)));

 // Get map of User -> Repo -> Action for all users/actions/repos
 Map<String, Map<String, Boolean>> userRepoAction = oso.buildQuery("allow", user, action, repo)
                                                     .evaluate(EvaluateArgs.map(user, EvaluateArgs.map(repo, EvaluateArgs.values(action))));

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      <T> T evaluate​(QueryBuilderImpl.EvaluateArg<T> arg)
      Evaluate the query based on the structure of the provided QueryBuilderImpl.EvaluateArg.
      java.lang.String evaluateLocalFilter​(java.lang.String columnName, TypedVar queryVar)
      Fetches a SQL fragment, which you can embed into the WHERE clause of a SQL query against your database to filter out unauthorized rows (ie.
      java.lang.String evaluateLocalSelect()
      Fetches a complete SQL query that can be run against your database, selecting a single row with a boolean column called result.
      java.lang.String evaluateLocalSelect​(java.util.Map<java.lang.String,​TypedVar> columnNamesToQueryVars)
      Fetches a complete SQL query that can be run against your database, selecting a row for each authorized combination of the query variables in columnNamesToQueryVars (ie.

    • Method Detail

      • evaluate

        <T> T evaluate​(QueryBuilderImpl.EvaluateArg<T> arg)
        throws java.io.IOException,
               ApiException
        Evaluate the query based on the structure of the provided QueryBuilderImpl.EvaluateArg. The shape of the return value is determined by the specific EvaluateArg used, constructed typically via the EvaluateArgs static factory methods.
        Type Parameters:
        T - The expected result type, inferred from the arg.
        Parameters:
        arg - An QueryBuilderImpl.EvaluateArg specifying the desired structure of the results. Use EvaluateArgs factory methods.
        Returns:
        An object of type T representing the evaluated results, matching the structure requested by arg.
        Throws:
        java.io.IOException - if an I/O error occurs during the API call.
        ApiException - if an API error occurs during the API call.
        java.lang.IllegalArgumentException - if the arg type is internally inconsistent or unsupported (should not happen with EvaluateArgs).
        java.lang.NullPointerException - if arg is null.

      • evaluateLocalSelect

        java.lang.String evaluateLocalSelect​(java.util.Map<java.lang.String,​TypedVar> columnNamesToQueryVars)
                              throws java.io.IOException,
                                     ApiException
        Fetches a complete SQL query that can be run against your database, selecting a row for each authorized combination of the query variables in columnNamesToQueryVars (ie. combinations of variables that satisfy the Oso query).

        See the Oso documentation for examples and limitations.

        Parameters:
        columnNamesToQueryVars - A mapping of the desired column names to the query variables whose values will be selected into those columns in the returned SQL query.
        Returns:
        SQL query containing the desired columns.
        Throws:
        java.io.IOException - if an I/O error occurs during the API call.
        ApiException - if an API error occurs during the API call.
        java.lang.IllegalArgumentException - if columnNamesToQueryVars contains duplicate variable values.

      • evaluateLocalSelect

        java.lang.String evaluateLocalSelect()
                              throws java.io.IOException,
                                     ApiException
        Fetches a complete SQL query that can be run against your database, selecting a single row with a boolean column called result.

        See the Oso documentation for examples and limitations.

        Returns:
        SQL query containing the result column.
        Throws:
        java.io.IOException - if an I/O error occurs during the API call.
        ApiException - if an API error occurs during the API call.

      • evaluateLocalFilter

        java.lang.String evaluateLocalFilter​(java.lang.String columnName,
                                     TypedVar queryVar)
                              throws java.io.IOException,
                                     ApiException
        Fetches a SQL fragment, which you can embed into the WHERE clause of a SQL query against your database to filter out unauthorized rows (ie. rows that don't satisfy the Oso query).

        See the Oso documentation for examples and limitations.

        Parameters:
        columnName - The name of the SQL column to filter.
        queryVar - The variable corresponding to the column to filter.
        Returns:
        SQL fragment, suitable for embedding in a WHERE clause.
        Throws:
        java.io.IOException - if an I/O error occurs during the API call.
        ApiException - if an API error occurs during the API call.
        java.lang.NullPointerException - if columnName or queryVar is null.