A comprehensive, multi-module OSGi workspace demonstrating "pure" OSGi concepts using the programmatic approach: BundleActivators and ServiceTrackers, without Declarative Services or modern frameworks.

This project teaches OSGi fundamentals "the hard way" to build deep understanding before adopting convenience frameworks.

What This Means:

• ✅ Manual BundleActivator for lifecycle management
• ✅ Explicit context.registerService() for service registration
• ✅ ServiceTracker with ServiceTrackerCustomizer for dynamic service consumption
• ✅ Hand-written MANIFEST.MF configuration
• ✅ Raw JDBC (no JPA), raw Servlets (no JAX-RS), manual JSON parsing
• ❌ NO Declarative Services (@Component, @Reference)
• ❌ NO Blueprint, Spring DM, or OSGi Annotations

osgi-example/
├── api     → Service contract (SensorService interface, POJOs)
├── core    → Business logic (JDBC PostgreSQL implementation)
├── web     → HTTP REST API (Raw HttpServlet, ServiceTrackers)
├── target  → P2 dependency resolution (Eclipse Equinox, Jetty, JDBC)
└── releng  → Product packaging (Start levels, launcher configuration)

cd osgi-example
docker-compose up --build

# GET all readings
curl http://localhost:8080/api/sensors

# POST new reading
curl -X POST http://localhost:8080/api/sensors \
  -H 'Content-Type: application/json' \
  -d '{"sensorId":"sensor-001","temperature":23.5,"humidity":45.2}'

docker logs -f osgi-application
# Type 'ss' to see bundle status
# Type 'services' to see registered services

This project includes comprehensive documentation (100+ pages):

→ Start with DOCUMENTATION_INDEX.md for guided learning paths

1. BundleActivator Pattern - Manual service registration and lifecycle
2. ServiceTracker Pattern - Dynamic service discovery and consumption
3. Service Registry - Understanding OSGi's runtime service model
4. Bundle Dependencies - Import-Package vs Export-Package
5. Start Levels - Controlling bundle activation order
6. Eclipse Tycho - Building OSGi with Maven

• Manual service registration: context.registerService()
• ServiceTrackerCustomizer for service lifecycle events
• Raw servlet registration with HttpService
• Direct JDBC without connection pooling frameworks
• Manual JSON serialization/deserialization
• Explicit MANIFEST.MF configuration

# Maven build only
mvn clean verify

# Run the built product
cd com.github.marceloleite2604.osgiexample.releng/target/products/.../
./osgi-example -console -consoleLog

Note: Requires Java 17 and Maven 3.6+

1. File → Import → Maven → Existing Maven Projects
2. Select osgi-example directory → Import all modules
3. Open com.github.marceloleite2604.osgiexample.target/osgi-example.target
4. Click "Set as Active Target Platform"
5. Open com.github.marceloleite2604.osgiexample.releng/osgi-example.product
6. Click "Launch an Eclipse application"

Quick diagnostics:

# Check bundle status
osgi> ss

# Diagnose bundle issues
osgi> diag <bundle-id>

# List registered services
osgi> services

# View logs
docker logs -f osgi-application

→ See OSGI_CONSOLE_REFERENCE.md for comprehensive troubleshooting

✅ Pure OSGi - No shortcuts, no frameworks masking concepts
✅ Production-Ready - Docker deployment with PostgreSQL
✅ Comprehensive Documentation - 8 detailed guides
✅ Real Integration - Database + HTTP + JSON
✅ Eclipse Compatible - Import directly into Eclipse IDE
✅ Educational Focus - Learn fundamentals deeply

This project demonstrates OSGi's dynamic nature:

// Core Bundle: Manual Registration
public void start(BundleContext context) {
    SensorServiceImpl impl = new SensorServiceImpl();
    context.registerService(SensorService.class, impl, null);
}

// Web Bundle: Dynamic Tracking
ServiceTracker<SensorService, SensorService> tracker = 
    new ServiceTracker<>(context, SensorService.class, 
        new ServiceTrackerCustomizer<>() {
            public SensorService addingService(ServiceReference ref) {
                // React to service appearing
            }
            public void removedService(ServiceReference ref, SensorService svc) {
                // React to service disappearing
            }
        });
tracker.open();

→ See ARCHITECTURE.md for complete flow diagrams

1. Run the project - Follow Quick Start above
2. Explore the console - Use OSGi commands to see dynamic behavior
3. Read the architecture - Understand the "why" behind design decisions
4. Modify the code - Add features, experiment with bundles
5. Compare with DS - Appreciate modern conveniences after mastering fundamentals

Marcelo Leite
GitHub: @MarceloLeite2604

Educational example demonstrating OSGi fundamentals.

Master OSGi the right way. Understand the fundamentals before using frameworks. 🎓