Package com.lucimber.dbus.annotation

package com.lucimber.dbus.annotation

Annotations for defining D-Bus interfaces, methods, properties, and signals.

This package provides annotations that simplify the implementation of D-Bus services by allowing you to annotate Java classes and have the framework automatically handle D-Bus introspection, property access, and method calls.

Getting Started

For first-time users: Start by annotating your service class with DBusInterface and its methods/properties with the appropriate annotations. Then use StandardInterfaceHandler to handle incoming calls.

Available Annotations

DBusInterface

Marks a class or interface as representing a D-Bus interface:

 @DBusInterface("com.example.MyService")
 public class MyService {
     // Methods and properties
 }
 

DBusMethod

Exposes a method as a D-Bus method:

 @DBusMethod(name = "Echo")
 public String echo(String message) {
     return message;
 }

 @DBusMethod  // Uses Java method name
 public void doSomething() {
     // Implementation
 }
 

DBusProperty

Exposes fields or getter/setter methods as D-Bus properties:

 // Field-based property
 @DBusProperty(name = "Version")
 private String version = "1.0.0";

 // Method-based property (read-only)
 @DBusProperty
 public String getStatus() {
     return currentStatus;
 }

 // Method-based property (read-write)
 @DBusProperty(name = "Count")
 public int getCount() {
     return count;
 }

 @DBusProperty(name = "Count")
 public void setCount(int count) {
     this.count = count;
 }
 

DBusSignal

Marks methods that emit D-Bus signals:

 @DBusSignal(name = "StatusChanged")
 public void emitStatusChanged(String oldStatus, String newStatus) {
     // Framework handles signal emission
 }
 

Complete Example

 @DBusInterface("com.example.Calculator")
 public class CalculatorService {

     @DBusProperty
     private String version = "1.0.0";

     @DBusProperty(access = DBusProperty.Access.READ)
     private int calculationCount = 0;

     @DBusMethod
     public double add(double a, double b) {
         calculationCount++;
         emitCalculationPerformed("add", a, b);
         return a + b;
     }

     @DBusMethod(name = "Multiply")
     public double multiply(double a, double b) {
         calculationCount++;
         emitCalculationPerformed("multiply", a, b);
         return a * b;
     }

     @DBusSignal
     public void emitCalculationPerformed(String operation, double a, double b) {
         // Signal emission handled by framework
     }
 }

 // Register the service
 CalculatorService calculator = new CalculatorService();
 StandardInterfaceHandler handler = new StandardInterfaceHandler(
     "/com/example/Calculator", calculator);
 connection.getPipeline().addLast("calculator", handler);
 

Integration with Standard Interfaces

When using these annotations with StandardInterfaceHandler, the following standard D-Bus interfaces are automatically implemented:

• org.freedesktop.DBus.Introspectable - Generates introspection XML from annotations
• org.freedesktop.DBus.Properties - Provides Get/Set/GetAll access to annotated properties
• org.freedesktop.DBus.Peer - Standard Ping and GetMachineId implementation

Property Access Modes

The DBusProperty.Access enum controls property accessibility:

• AUTO - Automatically determined based on field/methods
• READ - Read-only property
• WRITE - Write-only property
• READWRITE - Read-write property

Type Mapping

Java types are automatically mapped to D-Bus types:

Java Type	D-Bus Type	Notes
String	s (STRING)	UTF-8 strings
boolean	b (BOOLEAN)
byte	y (BYTE)
short	n (INT16)
int	i (INT32)
long	x (INT64)
double	d (DOUBLE)
List<T>	a* (ARRAY)	Type parameter determines element type
Map<K,V>	a{**} (DICT)	Key must be basic type

Best Practices

• Interface Naming: Use reverse domain notation (com.example.Service)
• Method Naming: Use PascalCase for D-Bus names in annotations
• Property Naming: Use PascalCase for D-Bus property names
• Signal Naming: Use descriptive names indicating what changed
• Thread Safety: Ensure annotated methods are thread-safe
• Error Handling: Throw appropriate exceptions for D-Bus errors

Limitations

Current limitations of the annotation framework:

• Complex type mapping may require manual conversion
• Generic type information may be lost at runtime
• Signal emission requires framework support
• Method overloading is not supported (D-Bus limitation)

Since:

2.0

See Also:

• StandardInterfaceHandler
• com.lucimber.dbus.standard

Class	Description
DBusInterface	Marks a Java interface or class as a D-Bus interface.
DBusMethod	Marks a method as a D-Bus method.
DBusProperty	Marks a field or getter/setter method as a D-Bus property.
DBusProperty.Access	Property access modes.
DBusSignal	Marks a method as a D-Bus signal emitter.
StandardInterfaceHandler	Handler that implements standard D-Bus interfaces using reflection and annotations.