Advanced Usage¶

This section covers advanced usage patterns and techniques for Bonsai. These topics build on the basic concepts and operations covered in the previous sections and provide more sophisticated ways to use Bonsai in your applications.

Topics Covered¶

Nested Tree Structures: Learn how to create and work with complex nested tree structures
Custom Context Implementation: Understand how to create custom Context implementations for specific application needs
Tree Validation: Explore techniques for validating tree structures
Versioning and Concurrency: Learn how to handle versioning and concurrent modifications
Contextual Preferences: Understand how to use contextual preferences to override normal tree traversal

When to Use Advanced Features¶

The advanced features of Bonsai are designed for scenarios where:

You need to represent complex, hierarchical data structures
You have specific requirements for context evaluation
You need to ensure the validity of tree structures
You need to handle concurrent modifications
You want to provide user-specific overrides of default configurations

Example: Combining Advanced Features¶

Here's an example that combines several advanced features:

// Create a custom context implementation
public class UserContext extends Context {
    private User user;

    public UserContext(User user) {
        super(JsonPath.parse(user));
        this.user = user;
    }

    // Custom methods to access user data
    public int getUserAge() {
        return user.getAge();
    }

    public String getUserCountry() {
        return user.getCountry();
    }
}

// Create a validator
BonsaiTreeValidator validator = new ComponentBonsaiTreeValidator();

// Get a tree structure
TreeKnot tree = bonsai.getCompleteTree("userEligibility");

// Validate the tree structure
ValidationResult result = validator.validate(tree);
if (!result.isValid()) {
    // Handle validation errors
    List<ValidationError> errors = result.getErrors();
    for (ValidationError error : errors) {
        System.err.println(error.getMessage());
    }
}

// Create a context with preferences
User user = new User("John", 25, "US", "premium");
Map<String, Knot> preferences = preferenceStore.get(user.getId());
UserContext context = new UserContext(user);
context.setPreferences(preferences);

// Evaluate the tree with versioning
try {
    KeyNode result = bonsai.evaluate("userEligibility", context);
    // Process the result
} catch (BonsaiError e) {
    if (e.getErrorCode() == BonsaiErrorCode.VERSION_MISMATCH) {
        // Handle version mismatch error
        System.err.println("Version mismatch: " + e.getMessage());
    } else {
        // Handle other errors
        throw e;
    }
}

Best Practices¶

Start simple: Begin with basic usage patterns and introduce advanced features as needed
Document your approach: Document how you're using advanced features to make your code easier to understand and maintain
Test thoroughly: Advanced features often require more thorough testing to ensure they work as expected
Consider performance implications: Some advanced features may have performance implications, so test and optimize as needed
Use versioning consistently: If you're using versioning, use it consistently across all operations