Data Navigators
Data Navigators provide a fluent, safe way to navigate and extract data from complex data structures in BoxLang
Data Navigators are a powerful BoxLang feature that provides a fluent, chainable interface for safely navigating and extracting data from complex data structures. Whether you're working with JSON files, API responses, configuration data, or nested structures, Data Navigators eliminate the need for verbose null checking and provide elegant error handling.
Overview
Data Navigators solve common problems when working with complex data:
Safe Navigation: No more "key doesn't exist" errors when traversing nested structures
Fluent Interface: Chainable methods that read like natural language
Type Safety: Built-in type casting with sensible defaults
Multiple Data Sources: Works with JSON strings, files, structures, maps, and more
Flexible Extraction: Get values with defaults, throw on missing data, or check existence
Getting Started
Creating a Data Navigator
Use the dataNavigate() BIF to create a navigator from various data sources:
// From a structure
config = {
"app": {
"name": "MyApp",
"version": "1.0.0",
"database": {
"host": "localhost",
"port": 5432,
"ssl": true
}
}
}
nav = dataNavigate( config )
// From a JSON string
jsonData = '{"users": [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]}'
nav = dataNavigate( jsonData )
// From a JSON file
nav = dataNavigate( "/path/to/config.json" )
// From a Java Map
javaMap = new java.util.HashMap()
nav = dataNavigate( javaMap )Basic Navigation
Navigate through nested structures using the fluent interface:
// Setup test data
appConfig = {
"application": {
"name": "BoxLang App",
"version": "2.0.0",
"features": {
"caching": true,
"logging": {
"level": "INFO",
"appenders": [ "console", "file" ]
}
}
}
}
nav = dataNavigate( appConfig )
// Navigate to a specific section
loggingNav = nav.from( "application", "features", "logging" )
// Get values with defaults
logLevel = loggingNav.getAsString( "level", "DEBUG" )
println( "Log Level: " & logLevel ) // "INFO"
// Check if values exist
if ( loggingNav.has( "appenders" ) ) {
appenders = loggingNav.getAsArray( "appenders" )
println( "Appenders: " & appenders.toList() )
}Navigation Methods
Navigate to Segments
// Navigate to nested sections
userNav = dataNavigate( userData ).from( "profile", "settings" )
dbNav = dataNavigate( config ).from( "database" )
// Multiple level navigation
deepNav = dataNavigate( complexData )
.from( "api", "v1" )
.from( "endpoints", "users" )Check Existence
nav = dataNavigate( config )
// Check if keys exist
hasDatabase = nav.has( "database" )
hasSSLConfig = nav.has( "database", "ssl", "enabled" )
// Check current segment
userNav = nav.from( "users" )
if ( userNav.isPresent() ) {
println( "Users section exists" )
}
if ( userNav.isEmpty() ) {
println( "Users section is empty" )
}Data Extraction Methods
Basic Retrieval
nav = dataNavigate( appConfig )
// Get raw values
appName = nav.get( "application", "name" )
version = nav.get( "application", "version" )
// Get with defaults
timeout = nav.get( "application", "timeout", 30 )
retries = nav.get( "application", "retries", 3 )
// Throw if missing (for required values)
apiKey = nav.getOrThrow( "application", "apiKey" )Basic Retrieval
nav = dataNavigate( serverConfig )
// BoxLang is dynamic - get() handles all types automatically
serverName = nav.get( "server", "name", "default-server" )
port = nav.get( "server", "port", 8080 )
sslEnabled = nav.get( "server", "ssl", false )
timeout = nav.get( "server", "timeout", 5000 )
lastUpdated = nav.get( "server", "lastUpdated" )
// Complex types work too
dbConfig = nav.get( "database" )
serverList = nav.get( "servers" )Typed Retrievals
For cases where you need explicit type conversion, BoxLang provides typed methods:
// Only use these when you need explicit type conversion
port = nav.getAsInteger( "server", "port", 8080 )
timeout = nav.getAsLong( "server", "timeout", 5000 )
loadFactor = nav.getAsDouble( "server", "loadFactor", 0.75 )
sslEnabled = nav.getAsBoolean( "server", "ssl", false )
lastUpdated = nav.getAsDate( "server", "lastUpdated" )
dbConfig = nav.getAsStruct( "database" )
serverList = nav.getAsArray( "servers" )Conditional Processing
Execute Code Based on Presence
nav = dataNavigate( userProfile )
// Execute if key exists
nav.ifPresent( "email", email -> {
println( "User email: " & email )
sendWelcomeEmail( email )
} )
// Execute with fallback
nav.ifPresentOrElse(
"phone",
phone -> {
println( "Calling: " & phone )
makePhoneCall( phone )
},
() -> {
println( "No phone number available" )
sendEmailInstead()
}
)Practical Examples
Configuration Management
// Load application configuration
function loadAppConfig( configPath ) {
var nav = dataNavigate( configPath )
return {
"appName": nav.get( "app", "name", "Unknown App" ),
"version": nav.get( "app", "version", "1.0.0" ),
"debug": nav.get( "app", "debug", false ),
"database": {
"host": nav.get( "database", "host", "localhost" ),
"port": nav.get( "database", "port", 5432 ),
"ssl": nav.get( "database", "ssl", true )
},
"cache": {
"enabled": nav.get( "cache", "enabled", true ),
"provider": nav.get( "cache", "provider", "memory" ),
"ttl": nav.get( "cache", "ttl", 3600 )
}
}
}
// Usage
appConfig = loadAppConfig( "/app/config.json" )
println( "Starting " & appConfig.appName & " v" & appConfig.version )API Response Processing
// Process API response data
function processUserData( apiResponse ) {
var nav = dataNavigate( apiResponse )
var users = [ ]
// Check if response is successful
if ( nav.getAsBoolean( "success", false ) ) {
// Navigate to user data
var userNav = nav.from( "data", "users" )
if ( userNav.isPresent() ) {
var userArray = userNav.getAsArray( "items", [ ] )
for ( var userData in userArray ) {
var userDataNav = dataNavigate( userData )
users.append( {
"id": userDataNav.get( "id" ),
"name": userDataNav.get( "profile", "fullName", "Unknown" ),
"email": userDataNav.get( "contact", "email" ),
"active": userDataNav.get( "status", "active", false ),
"lastLogin": userDataNav.get( "activity", "lastLogin" )
} )
}
}
}
return users
}
// Usage with API response
apiResponse = '
{
"success": true,
"data": {
"users": {
"items": [
{
"id": "123",
"profile": {"fullName": "Alice Johnson"},
"contact": {"email": "[email protected]"},
"status": {"active": true},
"activity": {"lastLogin": "2024-01-15T10:30:00Z"}
}
]
}
}
}
'
users = processUserData( apiResponse )Feature Flag Management
// Feature flag configuration
function createFeatureManager( configData ) {
var nav = dataNavigate( configData )
return {
"isEnabled": ( feature ) -> {
return nav.get( "features", feature, "enabled", false )
},
"getConfig": ( feature ) -> {
var featureNav = nav.from( "features", feature )
if ( featureNav.isEmpty() ) {
return { }
}
return {
"enabled": featureNav.get( "enabled", false ),
"rolloutPercent": featureNav.get( "rollout", 100 ),
"environments": featureNav.get( "environments", [ ] ),
"config": featureNav.get( "config", { } )
}
},
"shouldShowForUser": ( feature, userID ) -> {
var config = this.getConfig( feature )
if ( !config.enabled ) return false
// Simple hash-based rollout
var userHash = hash( userID ).left( 2 ).parseInt( 16 )
return ( userHash % 100 ) < config.rolloutPercent
}
}
}
// Usage
featureConfig = '
{
"features": {
"newDashboard": {
"enabled": true,
"rollout": 50,
"environments": ["staging", "production"]
},
"betaFeature": {
"enabled": false
}
}
}
'
features = createFeatureManager( featureConfig )
if ( features.isEnabled( "newDashboard" ) ) {
println( "New dashboard is enabled" )
}Database Configuration
// Multi-environment database configuration
function getDatabaseConfig( environment = "development" ) {
var nav = dataNavigate( "/config/database.json" )
var envNav = nav.from( "environments", environment )
// Fallback to default if environment not found
if ( envNav.isEmpty() ) {
envNav = nav.from( "environments", "default" )
}
var config = {
"driver": envNav.get( "driver", "mysql" ),
"host": envNav.get( "host", "localhost" ),
"port": envNav.get( "port", 3306 ),
"database": envNav.get( "database", "myapp" ),
"username": envNav.get( "username", "root" ),
"password": envNav.get( "password", "" ),
"ssl": envNav.get( "ssl", false ),
"pooling": {
"enabled": envNav.get( "pool", "enabled", true ),
"maxConnections": envNav.get( "pool", "max", 10 ),
"timeout": envNav.get( "pool", "timeout", 30 )
}
}
// Apply global settings
var globalNav = nav.from( "global" )
if ( globalNav.isPresent() ) {
config.charset = globalNav.get( "charset", "utf8" )
config.timezone = globalNav.get( "timezone", "UTC" )
}
return config
}
// Usage
dbConfig = getDatabaseConfig( "production" )Log Configuration Processing
// Parse logging configuration
function setupLogging( logConfigPath ) {
var nav = dataNavigate( logConfigPath )
var loggers = [ ]
// Get global log level
var globalLevel = nav.get( "logging", "level", "INFO" )
// Process appenders
var appendersNav = nav.from( "logging", "appenders" )
if ( appendersNav.isPresent() ) {
// Console appender
appendersNav.ifPresent( "console", consoleConfig -> {
var consoleNav = dataNavigate( consoleConfig )
loggers.append( {
"type": "console",
"level": consoleNav.get( "level", globalLevel ),
"pattern": consoleNav.get( "pattern", "%d{yyyy-MM-dd HH:mm:ss} - %m%n" ),
"colored": consoleNav.get( "colored", true )
} )
} )
// File appender
appendersNav.ifPresent( "file", fileConfig -> {
var fileNav = dataNavigate( fileConfig )
loggers.append( {
"type": "file",
"level": fileNav.get( "level", globalLevel ),
"path": fileNav.get( "path", "/logs/app.log" ),
"maxSize": fileNav.get( "maxSize", "10MB" ),
"maxFiles": fileNav.get( "maxFiles", 5 )
} )
} )
}
return loggers
}Error Handling and Validation
Safe Navigation Patterns
// Safe navigation with validation
function getSecureConfig( configPath ) {
try {
var nav = dataNavigate( configPath )
// Validate required sections exist
if ( !nav.has( "security" ) ) {
throw( type: "ConfigurationError", message: "Security configuration missing" )
}
var secNav = nav.from( "security" )
return {
"encryption": {
"algorithm": secNav.getOrThrow( "encryption", "algorithm" ),
"keyLength": secNav.get( "encryption", "keyLength", 256 ) // Keep as number
},
"authentication": {
"provider": secNav.get( "auth", "provider", "local" ),
"timeout": secNav.get( "auth", "timeout", 3600 ) // Keep as number
}
}
} catch ( any e ) {
writeLog( "Failed to load security config: " & e.message, "error" )
return getDefaultSecurityConfig()
}
}
function getDefaultSecurityConfig() {
return {
"encryption": {
"algorithm": "AES",
"keyLength": 256
},
"authentication": {
"provider": "local",
"timeout": 3600
}
}
}Graceful Degradation
// Load configuration with graceful fallbacks
function loadConfigWithFallbacks( primaryPath, fallbackPath ) {
var config = { }
// Try primary configuration
try {
var primaryNav = dataNavigate( primaryPath )
config = extractConfig( primaryNav )
println( "Loaded primary configuration from: " & primaryPath )
} catch ( any e ) {
writeLog( "Primary config failed: " & e.message, "warn" )
// Try fallback configuration
try {
var fallbackNav = dataNavigate( fallbackPath )
config = extractConfig( fallbackNav )
println( "Loaded fallback configuration from: " & fallbackPath )
} catch ( any e2 ) {
writeLog( "Fallback config failed: " & e2.message, "error" )
config = getHardcodedDefaults()
println( "Using hardcoded default configuration" )
}
}
return config
}
function extractConfig( nav ) {
return {
"app": nav.get( "name", "DefaultApp" ),
"port": nav.get( "server", "port", 8080 ),
"debug": nav.get( "debug", false )
}
}Advanced Patterns
Configuration Inheritance
// Implement configuration inheritance
function buildInheritedConfig( environment ) {
var nav = dataNavigate( "/config/app.json" )
var config = { }
// Start with base configuration
var baseNav = nav.from( "base" )
if ( baseNav.isPresent() ) {
config = extractAllSettings( baseNav )
}
// Apply environment-specific overrides
var envNav = nav.from( "environments", environment )
if ( envNav.isPresent() ) {
var envConfig = extractAllSettings( envNav )
config = mergeConfigs( config, envConfig )
}
return config
}
function mergeConfigs( base, override ) {
// Simple merge - in practice you'd want deep merging
var merged = duplicate( base )
for ( var key in override ) {
merged[ key ] = override[ key ]
}
return merged
}Dynamic Configuration Validation
// Validate configuration structure
function validateConfig( configData ) {
var nav = dataNavigate( configData )
var errors = [ ]
// Required fields
var required = [
[ "app", "name" ],
[ "app", "version" ],
[ "database", "host" ]
]
for ( var path in required ) {
if ( !nav.has( path[ 1 ], path[ 2 ] ?: "" ) ) {
errors.append( "Missing required field: " & path.toList( "." ) )
}
}
// Type validations
nav.ifPresent( "server", serverConfig -> {
var serverNav = dataNavigate( serverConfig )
var port = serverNav.get( "port" )
if ( port != null && ( !isNumeric( port ) || port <= 0 || port > 65535 ) ) {
errors.append( "Invalid port number: " & port )
}
} )
return {
"valid": errors.isEmpty(),
"errors": errors
}
}Best Practices
1. Use Meaningful Defaults
// Provide sensible defaults for all configuration values - get() works dynamically
serverConfig = nav.get( "server", {
"host": "localhost",
"port": 8080,
"ssl": false,
"timeout": 30
} )2. Validate Critical Configuration
// Always validate required configuration
apiKey = nav.getOrThrow( "api", "key" ) // Will throw if missing
dbHost = nav.getOrThrow( "database", "host" )3. Leverage BoxLang's Dynamic Nature
// BoxLang handles all types automatically with get()
enabled = nav.get( "feature", "enabled", false )
maxRetries = nav.get( "http", "maxRetries", 3 )
serverName = nav.get( "server", "name", "default" )
config = nav.get( "database" ) // Works for complex types too4. Handle Missing Sections Gracefully
// Check for section existence before processing
var cacheNav = nav.from( "cache" )
if ( cacheNav.isPresent() ) {
// Configure caching
setupCaching( cacheNav )
} else {
// Use default caching or disable
useDefaultCaching()
}5. Log Configuration Issues
// Log when using fallbacks or defaults
nav.ifPresentOrElse(
"timeout",
timeout -> println( "Using configured timeout: " & timeout ),
() -> println( "No timeout configured, using default: 30s" )
)Conclusion
Data Navigators offer a robust and fluent way to work with complex data structures in BoxLang. They eliminate common errors, provide excellent defaults, and make configuration management both safe and readable.
Key benefits:
Safe Navigation: No more null pointer exceptions when traversing data
Type Safety: Built-in type conversion with sensible defaults
Fluent API: Chainable methods that read like natural language
Flexible Sources: Works with JSON files, strings, structures, and maps
Error Handling: Graceful fallbacks and validation capabilities
Whether you're processing API responses, managing application configuration, or working with complex data structures, Data Navigators make your code more robust and maintainable.
Last updated
Was this helpful?