Package com.lucimber.dbus.type

package com.lucimber.dbus.type
Type-safe D-Bus data types and containers providing compile-time marshalling safety.

This package implements the complete D-Bus type system as Java wrapper classes that ensure type safety and prevent marshalling errors. All D-Bus types are represented as immutable Java objects that can be safely used across threads.

Getting Started

For first-time users: Start with common types like DBusString, DBusInt32, and DBusBoolean. For paths use DBusObjectPath, and for collections use DBusArray and DBusDict. All types use static factory methods like DBusString.valueOf("hello").

Type Hierarchy

All D-Bus types implement the DBusType interface and are organized into two main categories:

Basic Types (DBusBasicType)

Fixed-size, atomic data types:

Container Types (DBusContainerType)

Variable-size, composite data types:

Usage Examples

Basic Types


 // Creating basic types
 DBusString text = DBusString.valueOf("Hello, D-Bus!");
 DBusInt32 number = DBusInt32.valueOf(42);
 DBusBoolean flag = DBusBoolean.valueOf(true);
 DBusObjectPath path = DBusObjectPath.valueOf("/org/example/Object");

 // Type safety at compile time
 // This would be a compilation error:
 // DBusString text = DBusInt32.valueOf(42); // Won't compile!

Arrays


 // Create a string array
 DBusSignature signature = DBusSignature.valueOf("as");
 DBusArray<DBusString> stringArray = new DBusArray<>(signature);
 stringArray.add(DBusString.valueOf("first"));
 stringArray.add(DBusString.valueOf("second"));
 stringArray.add(DBusString.valueOf("third"));

 // Type safety ensures only strings can be added
 // stringArray.add(DBusInt32.valueOf(123)); // Compilation error!

Dictionaries


 // Create a string-to-integer dictionary
 DBusSignature dictSignature = DBusSignature.valueOf("a{si}");
 DBusDict<DBusString, DBusInt32> dict = new DBusDict<>(dictSignature);
 dict.put(DBusString.valueOf("count"), DBusInt32.valueOf(10));
 dict.put(DBusString.valueOf("limit"), DBusInt32.valueOf(100));

 // Access values safely
 DBusInt32 count = dict.get(DBusString.valueOf("count"));
 if (count != null) {
     System.out.println("Count: " + count.getDelegate());
 }

Structures


 // Create a structure (string, int32, boolean)
 DBusSignature structSig = DBusSignature.valueOf("(sib)");
 DBusStruct struct = new DBusStruct(structSig,
     DBusString.valueOf("example"),
     DBusInt32.valueOf(42),
     DBusBoolean.valueOf(true)
 );

 // Access struct elements
 List<DBusType> elements = struct.getElements();
 DBusString firstElement = (DBusString) elements.get(0);

Variants


 // Variants can hold any D-Bus type
 DBusVariant stringVariant = DBusVariant.valueOf(DBusString.valueOf("text"));
 DBusVariant numberVariant = DBusVariant.valueOf(DBusInt32.valueOf(123));

 // Type checking when extracting values
 if (stringVariant.getValue() instanceof DBusString) {
     DBusString text = (DBusString) stringVariant.getValue();
     System.out.println("Text: " + text.toString());
 }

Type Signatures

D-Bus type signatures describe the structure of data using a compact string format:

D-Bus Type Signatures
TypeSignatureJava Type
ByteyDBusByte
BooleanbDBusBoolean
Int32iDBusInt32
StringsDBusString
Array of stringsasDBusArray<DBusString>
Dictionarya{si}DBusDict<DBusString, DBusInt32>
Struct(si)DBusStruct
VariantvDBusVariant

Validation and Constraints

All types enforce D-Bus specification constraints:

  • String validation: Strings must be valid UTF-8 and not contain NUL characters
  • Object path validation: Object paths must follow D-Bus naming conventions
  • Signature validation: Type signatures must be syntactically correct
  • Size limits: Arrays and strings have maximum size limits (64MB for arrays, 256MB for strings)
  • Alignment requirements: Data is properly aligned according to D-Bus specification

Immutability and Thread Safety

All D-Bus types are immutable and thread-safe:

  • Once created, type instances cannot be modified
  • Container types provide defensive copies when needed
  • All operations are safe for concurrent access
  • No synchronization is required when sharing instances between threads

Memory Efficiency

The type system is designed for memory efficiency:

  • Basic types wrap primitive values with minimal overhead
  • Container types use efficient underlying collections
  • Large objects (arrays, strings) are handled with care for memory usage
  • Type signatures are validated once and cached
Since:
1.0
See Also: