Package com.lucimber.dbus.util

package com.lucimber.dbus.util
Utility classes and helper functions for D-Bus operations and internal framework use.

This package contains utility classes that provide common functionality used throughout the D-Bus client library. These utilities handle tasks like byte manipulation, string processing, validation, and other cross-cutting concerns.

Getting Started

For first-time users: Most utilities in this package are used internally. However, LoggerUtils can be helpful for debugging, and ByteBufferPoolManager is useful if you need to optimize memory usage in high-throughput scenarios.

Key Utilities

Byte Operations

Utilities for handling D-Bus binary data and byte array operations: 


 // Byte buffer utilities
 ByteBuffer buffer = ByteBufferUtils.allocateDirect(1024);
 ByteBufferUtils.writeBigEndianInt32(buffer, 42);
 int value = ByteBufferUtils.readBigEndianInt32(buffer);

 // Byte array manipulation
 byte[] data = new byte[]{0x01, 0x02, 0x03, 0x04};
 String hex = ByteUtils.toHexString(data);
 byte[] restored = ByteUtils.fromHexString(hex);

String Processing

String utilities for D-Bus protocol requirements: 


 // String validation
 boolean isValidObjectPath = StringUtils.isValidObjectPath("/org/example/Object");
 boolean isValidInterface = StringUtils.isValidInterfaceName("org.example.Interface");
 boolean isValidBusName = StringUtils.isValidBusName("org.example.Service");

 // String normalization
 String normalized = StringUtils.normalizeObjectPath("/org/example//Object/");
 String sanitized = StringUtils.sanitizeString(userInput);

Validation Utilities

Validation helpers for D-Bus protocol compliance: 


 // Argument validation
 ValidationUtils.requireNonNull(argument, "Argument cannot be null");
 ValidationUtils.requireNonEmpty(collection, "Collection cannot be empty");
 ValidationUtils.requireValidRange(value, 0, 100, "Value must be between 0 and 100");

 // D-Bus specific validation
 ValidationUtils.validateObjectPath(path);
 ValidationUtils.validateInterfaceName(interfaceName);
 ValidationUtils.validateSignature(signature);

Concurrent Utilities

Thread-safe utilities for concurrent operations: 


 // Thread-safe collections
 ConcurrentMap<String, Object> cache = ConcurrentUtils.newConcurrentHashMap();
 Set<String> syncSet = ConcurrentUtils.newConcurrentHashSet();

 // Future utilities
 CompletableFuture<String> future = FutureUtils.completedFuture("result");
 CompletableFuture<Void> timeout = FutureUtils.withTimeout(
     operation, Duration.ofSeconds(30));

Internal Framework Utilities

Logging Support

Structured logging utilities for consistent log formatting: 


 // Structured logging
 Logger logger = LoggerFactory.getLogger(MyClass.class);
 LogUtils.debug(logger, "Processing message",
     "type", messageType,
     "serial", serial,
     "size", messageSize);

 // Performance logging
 try (TimingContext timing = LogUtils.startTiming("operation")) {
     performOperation();
 }

Configuration Helpers

Configuration parsing and validation utilities: 


 // Environment variable parsing
 String dbusAddress = ConfigUtils.getEnvVar("DBUS_SESSION_BUS_ADDRESS");
 int timeout = ConfigUtils.getEnvInt("DBUS_TIMEOUT", 30);
 boolean enabled = ConfigUtils.getEnvBoolean("DBUS_DEBUG", false);

 // Configuration validation
 ConfigUtils.validateConfiguration(config);
 Properties props = ConfigUtils.loadProperties("dbus.properties");

Resource Management

Utilities for managing system resources: 


 // Resource cleanup
 try (CloseableResource resource = ResourceUtils.acquire()) {
     // Use resource
 } // Automatically cleaned up

 // Memory management
 long memoryUsage = ResourceUtils.getMemoryUsage();
 ResourceUtils.runGC();
 boolean lowMemory = ResourceUtils.isLowMemory();

Data Structure Utilities

Collection Helpers

Utilities for working with collections and data structures: 


 // Immutable collections
 List<String> immutableList = CollectionUtils.immutableList("a", "b", "c");
 Set<Integer> immutableSet = CollectionUtils.immutableSet(1, 2, 3);
 Map<String, String> immutableMap = CollectionUtils.immutableMap(
     "key1", "value1",
     "key2", "value2");

 // Collection operations
 List<String> filtered = CollectionUtils.filter(list, String::isEmpty);
 List<Integer> mapped = CollectionUtils.map(list, String::length);
 Optional<String> found = CollectionUtils.find(list, "target"::equals);

Caching Utilities

Simple caching mechanisms for performance optimization: 


 // LRU cache
 Cache<String, Object> cache = CacheUtils.createLRUCache(1000);
 cache.put("key", computeExpensiveValue());
 Object value = cache.get("key");

 // Time-based cache
 Cache<String, Object> timeCache = CacheUtils.createTimeCache(
     Duration.ofMinutes(5));

Protocol Utilities

Marshalling Helpers

Utilities for D-Bus message marshalling and unmarshalling: 


 // Alignment utilities
 int alignedPosition = AlignmentUtils.alignTo(position, 8);
 int padding = AlignmentUtils.calculatePadding(position, 4);

 // Signature parsing
 SignatureParser parser = new SignatureParser("a{sv}");
 SignatureType type = parser.parseNext();
 boolean isContainer = SignatureUtils.isContainer(type);

Endianness Handling

Utilities for handling byte order in D-Bus messages: 


 // Endianness conversion
 ByteOrder order = EndiannessUtils.getSystemByteOrder();
 int swapped = EndiannessUtils.swapInt32(value);
 short swapped16 = EndiannessUtils.swapInt16(value);

 // D-Bus specific endianness
 boolean isLittleEndian = EndiannessUtils.isDBusLittleEndian(flags);

Testing Utilities

Test Helpers

Utilities for testing D-Bus applications: 


 // Test data generation
 DBusString testString = TestUtils.randomDBusString(100);
 DBusArray<DBusInt32> testArray = TestUtils.randomDBusArray(10, DBusInt32.class);

 // Mock utilities
 Connection mockConnection = TestUtils.createMockConnection();
 InboundSignal mockSignal = TestUtils.createMockSignal("org.test.Signal");

 // Assertion helpers
 TestUtils.assertValidObjectPath(path);
 TestUtils.assertValidSignature(signature);
 TestUtils.assertMessageEquals(expected, actual);

Performance Utilities

Profiling Support

Utilities for performance monitoring and profiling: 


 // Performance measurement
 Stopwatch stopwatch = PerformanceUtils.startStopwatch();
 performOperation();
 Duration elapsed = stopwatch.elapsed();

 // Memory profiling
 MemoryProfiler profiler = PerformanceUtils.startMemoryProfiler();
 performMemoryIntensiveOperation();
 MemoryUsage usage = profiler.getUsage();

Best Practices

  • Null Safety: All utility methods handle null inputs gracefully
  • Immutability: Utility classes are stateless and thread-safe
  • Performance: Utilities are optimized for common use cases
  • Validation: Input validation is performed where appropriate
  • Documentation: All utilities are thoroughly documented

Internal Use

While this package is primarily for internal framework use, some utilities may be useful for application developers. However, these utilities are not part of the public API and may change between versions.

Since:
1.0
See Also: