A modern Spring Boot 3.5 implementation of the Open Energy Services Provider Interface (ESPI) Data Custodian, providing OAuth2 Resource Server capabilities for secure energy usage data access according to the North American Energy Standards Board (NAESB) REQ.21 ESPI specification.

The OpenESPI-DataCustodian serves as a secure OAuth2 Resource Server that:

• Protects energy usage data with scope-based authorization (FB=1_3_4_5_13_14_15_39, FB=4_5_15)
• Provides RESTful APIs for retail customers and third-party applications
• Implements ESPI 4.0 specification with ATOM XML data formats
• Supports multiple databases (MySQL, PostgreSQL, H2) with Flyway migrations
• Offers modern web interface with Thymeleaf templates and Spring Security 6

Built on Spring Boot 3.5 with modern architectural patterns:

• OAuth2 Resource Server with opaque token introspection
• Entity-based data model with UUID primary keys (48-bit+ ESPI compliance)
• Service layer architecture with DTO mapping via MapStruct
• Multi-profile configuration for development, testing, and production
• Comprehensive testing with TestContainers and Cucumber BDD

• Java 21+ (OpenJDK recommended)
• Maven 3.9+
• MySQL 8.0+ or PostgreSQL 15+ (for production)
• OpenESPI-Common-java dependency (built automatically)

git clone https://github.com/GreenButtonAlliance/OpenESPI-DataCustodian-java.git
cd OpenESPI-DataCustodian-java

# Build with default MySQL profile
mvn clean install

# Or skip tests for faster build
mvn clean install -DskipTests

# Start with MySQL (default)
mvn spring-boot:run

# Start with PostgreSQL
mvn spring-boot:run -Pdev-postgresql

# Start with H2 (local development)
mvn spring-boot:run -Plocal

The application will be available at: http://localhost:8080

mvn test

# MySQL integration tests
mvn verify -Ptestcontainers-mysql

# PostgreSQL integration tests  
mvn verify -Ptestcontainers-postgresql

mvn verify

mvn verify jacoco:report
# Reports available in target/site/jacoco/

Interactive API documentation is available via Swagger UI:

• Development: http://localhost:8080/swagger-ui.html
• Production: Configure accordingly per environment

This implementation follows OAuth2 Resource Server patterns:

• Opaque access tokens (no JWT) per ESPI specification
• Scope-based authorization with fine-grained permissions
• Spring Security 6 with modern security configurations
• OWASP dependency scanning integrated in CI/CD

IntelliJ IDEA (Recommended):

# Open project
File → Open → select pom.xml

# Enable annotation processing for Lombok/MapStruct
Settings → Build → Compiler → Annotation Processors → Enable

Eclipse/Spring Tool Suite:

File → Import → Maven → Existing Maven Projects

# Run OWASP security scan
mvn org.owasp:dependency-check-maven:check

# Static analysis with SpotBugs
mvn compile spotbugs:check

# Build application JAR
mvn clean package -DskipTests

# Run with Docker profile
java -jar target/OpenESPI-DataCustodian.jar --spring.profiles.active=docker

Configure production database and OAuth2 authorization server endpoints in:

• src/main/resources/application-prod.yml
• Environment variables or external configuration

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow code style and add tests
4. Commit changes (git commit -m 'Add amazing feature')
5. Push to branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Licensed under the Apache License 2.0. See LICENSE for details.

• Issues: GitHub Issues
• Documentation: Green Button Alliance
• Sandbox: https://sandbox.greenbuttonalliance.org:8443/DataCustodian