TRUNK-6469: Add support for automatic initialization of Envers audit tables

Author: wikumChamith

CLAUDE.md

@@ -0,0 +1,296 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+OpenMRS is a patient-based medical record system focusing on providing a free, customizable electronic medical record system (EMR). This is the core platform repository written in Java, using Spring Framework, Hibernate ORM, and a modular architecture that allows extending functionality through modules.
+
+**Version**: 3.0.0-SNAPSHOT
+**License**: Mozilla Public License 2.0 with Healthcare Disclaimer
+**Java Version**: 21 (JDK 21 minimum)
+**Maven Version**: 3.8.0+ required
+
+## Common Development Commands
+
+### Building the Project
+```bash
+# Full build with all tests
+mvn clean package
+
+# Build without tests (faster for quick compilation)
+mvn clean install -DskipTests
+
+# Build with specific Maven profile
+mvn clean install -Pskip-all-checks
+```
+
+### Running Tests
+```bash
+# Run all unit tests
+mvn test
+
+# Run integration tests
+mvn test -Pskip-default-test -Pintegration-test
+
+# Run specific test class
+mvn test -Dtest=PatientServiceTest
+
+# Run specific test method
+mvn test -Dtest=PatientServiceTest#shouldGetPatientByUuid
+```
+
+### Running the Application Locally
+```bash
+# Using Jetty (from webapp directory)
+cd webapp
+mvn jetty:run
+
+# Using Jetty on custom port
+mvn -Djetty.http.port=8081 jetty:run
+
+# Using Cargo
+cd webapp
+mvn cargo:run
+
+# Using Cargo on custom port
+mvn -Dcargo.servlet.port=8081 cargo:run
+```
+
+After starting, access the application at `http://localhost:8080/openmrs`
+
+### Docker Development
+```bash
+# Build development image
+docker compose build
+
+# Build with custom Maven arguments
+docker compose build --build-arg MVN_ARGS='install -DskipTests'
+
+# Run development version
+docker compose up
+
+# Build and run production version
+docker compose -f docker-compose.yml build
+docker compose -f docker-compose.yml up
+
+# Run with ElasticSearch backend
+docker compose -f docker-compose.yml -f docker-compose.override.yml -f docker-compose.es.yml up
+```
+
+### Code Quality and Formatting
+```bash
+# Run checkstyle
+mvn checkstyle:check
+
+# Format code (uses Eclipse formatter)
+mvn java-formatter:format
+
+# Check license headers
+mvn license:check
+
+# Format license headers
+mvn license:format
+```
+
+## Architecture
+
+### Multi-Module Structure
+
+The repository is organized as a Maven multi-module project:
+
+- **api/** - Core Java API containing domain models, service interfaces, and business logic
+  - Domain models: `org.openmrs.*` (Patient, Encounter, Obs, Concept, etc.)
+  - Service interfaces: `org.openmrs.api.*` (PatientService, ConceptService, etc.)
+  - Service implementations: `org.openmrs.api.impl.*`
+  - DAO interfaces: `org.openmrs.api.db.*`
+  - Hibernate DAOs: `org.openmrs.api.db.hibernate.*`
+
+- **web/** - Web layer containing controllers, filters, and web utilities
+  - Controllers: `org.openmrs.web.controller.*`
+  - Filters: `org.openmrs.web.filter.*`
+
+- **webapp/** - WAR packaging module that assembles the final web application
+
+- **test/** - Shared test infrastructure and base test classes
+
+- **tools/** - Development tools (formatters, doclets)
+
+- **liquibase/** - Database schema management and migration scripts
+
+### Layered Architecture
+
+OpenMRS follows a classic layered architecture:
+
+1. **Domain Model Layer** (`org.openmrs.*`)
+   - All domain objects extend either `BaseOpenmrsData` (for clinical data) or `BaseOpenmrsMetadata` (for configuration)
+   - `BaseOpenmrsData` provides: uuid, creator, dateCreated, changedBy, dateChanged, voided, voidedBy, dateVoided, voidReason
+   - `BaseOpenmrsMetadata` adds: name, description, retired, retiredBy, dateRetired, retireReason
+   - Domain objects implement marker interfaces: `OpenmrsObject`, `Auditable`, `Voidable`, `Retireable`
+
+2. **Service Layer** (`org.openmrs.api.*`)
+   - All services implement `OpenmrsService` interface (onStartup/onShutdown lifecycle methods)
+   - Service implementations extend `BaseOpenmrsService`
+   - Services are annotated with `@Transactional` for transaction management
+   - Retrieved via Spring using `Context.getService(ServiceClass.class)` or dependency injection
+   - Common services: PatientService, ConceptService, EncounterService, ObsService, OrderService, PersonService
+
+3. **DAO Layer** (`org.openmrs.api.db.*` and `org.openmrs.api.db.hibernate.*`)
+   - DAO interfaces define data access contracts
+   - Hibernate implementations provide persistence
+   - Generic DAOs: `OpenmrsDataDAO`, `OpenmrsMetadataDAO`, `OpenmrsObjectDAO`
+   - Entity-specific DAOs for complex queries
+
+4. **Web Layer** (`org.openmrs.web.*`)
+   - Spring MVC controllers handle HTTP requests
+   - Filters handle initialization, authentication, and request processing
+   - `Context` class provides static access to services and session management
+
+### Key Design Patterns
+
+**Context Pattern**: The `Context` class provides static access to authenticated user, services, and application state. Always use `Context.getService()` to retrieve services rather than direct instantiation.
+
+**Service Locator**: Services are registered in Spring and accessed via `Context.getService(ServiceClass.class)`. Custom services from modules can be accessed using `Context.getService(CustomService.class)`.
+
+**DAO Pattern**: Data access is abstracted through DAO interfaces with Hibernate implementations. This allows swapping persistence implementations without affecting business logic.
+
+**Interceptors**: Hibernate interceptors enforce business rules at persistence layer:
+- `AuditableInterceptor` - Automatically sets audit fields (creator, dateCreated, etc.)
+- `ImmutableEntityInterceptor` - Prevents modification of immutable entities
+- `DropMillisecondsHibernateInterceptor` - Ensures database compatibility
+
+**Module System**: OpenMRS supports dynamic loading of modules that can extend core functionality by providing additional services, domain objects, and web resources.
+
+### Database Schema Management
+
+OpenMRS uses Liquibase for database schema versioning and migration:
+
+- Schema snapshots: `api/src/main/resources/org/openmrs/liquibase/snapshots/schema-only/`
+- Core data: `api/src/main/resources/org/openmrs/liquibase/snapshots/core-data/`
+- Updates: `api/src/main/resources/org/openmrs/liquibase/updates/`
+
+When making database changes:
+1. Add changesets to the appropriate `liquibase-update-to-latest-*.xml` file
+2. Liquibase automatically applies changes on application startup
+3. For new major/minor versions, generate new snapshots (see liquibase/README.md)
+
+### Testing Infrastructure
+
+**Base Test Classes**:
+- `BaseContextSensitiveTest` - Loads full Spring context with H2 in-memory database for integration tests
+- Tests extending this class have access to all services via `Context.getService()`
+- Test data can be loaded using `@DataSet` annotations or by placing XML datasets in `test/resources`
+
+**Test Naming Conventions**:
+- Unit tests: `*Test.java` (run in standard test phase)
+- Integration tests: `*IT.java` (run with `-Pintegration-test` profile)
+- Database integration tests: `*DatabaseIT.java` (separate execution group)
+
+**Test Database**:
+- H2 in-memory database for most tests
+- Testcontainers for database-specific integration tests (MySQL, PostgreSQL, MariaDB)
+- Standard test database initialized with `initial_test_db.sql`
+
+### Authentication and Security
+
+- Spring Security handles authentication and authorization
+- Privileges control access to specific operations
+- Roles group privileges
+- Use `@Authorized` annotation on service methods to enforce privilege requirements
+- `Context.getAuthenticatedUser()` returns current authenticated user
+- CSRF protection via OWASP CSRFGuard
+
+### Search and Indexing
+
+- Hibernate Search with Lucene backend (or ElasticSearch as alternative)
+- Full-text search on Patients, Concepts, and other entities
+- Search indexes automatically maintained by Hibernate Search
+- Rebuild indexes via Administration UI or REST endpoint if needed
+
+## Important Development Practices
+
+### Working with Domain Objects
+
+When creating or modifying domain objects:
+- Always extend appropriate base classes (`BaseOpenmrsData` or `BaseOpenmrsMetadata`)
+- Implement proper `equals()` and `hashCode()` based on uuid
+- Add Hibernate mapping annotations (`@Entity`, `@Table`, `@Column`, etc.)
+- Use `@AttributeOverride` for audit fields to customize column names if needed
+- For @ManyToOne audit fields, use `fetch = FetchType.LAZY` (default fetch is now LAZY)
+
+### Working with Services
+
+When implementing service methods:
+- Add `@Transactional` at class or method level
+- Use `@Authorized(PrivilegeConstants.SOME_PRIVILEGE)` to enforce security
+- Validate inputs using `ValidateUtil.validate(object)` for JSR-303 validation
+- Throw `APIException` or appropriate subclass for business rule violations
+- Delegate to DAO layer for all data access
+
+### Working with DAOs
+
+- Implement DAO interface in `org.openmrs.api.db`
+- Create Hibernate implementation in `org.openmrs.api.db.hibernate`
+- Use `SessionFactory` injected by Spring
+- Prefer HQL or Criteria API over native SQL when possible
+- For complex queries, use `@NamedQuery` on entity classes
+
+### JIRA Workflow
+
+OpenMRS uses JIRA for issue tracking at https://issues.openmrs.org
+
+When working on issues:
+1. Find a "Ready For Work" issue
+2. Claim the issue (changes status to "In Progress")
+3. Create a branch named after the JIRA ticket (e.g., `TRUNK-6444`)
+4. Make changes following coding conventions
+5. Include ticket number in all commit messages: `TRUNK-6444: Description of change`
+6. Squash commits into atomic units before creating PR
+7. Create pull request and link it in JIRA
+8. Click "Request Code Review" button in JIRA
+
+### Coding Conventions
+
+- Follow Eclipse code formatter configuration: `tools/src/main/resources/eclipse/OpenMRSFormatter.xml`
+- Use checkstyle configuration: `checkstyle.xml`
+- All files must have MPL 2.0 license header
+- Use meaningful variable names and JavaDoc for public APIs
+- Maximum line length: variable (formatter handles this)
+- Use slf4j for logging: `private static final Logger log = LoggerFactory.getLogger(ClassName.class);`
+
+### Module Development
+
+Modules extend OpenMRS functionality:
+- Modules packaged as OMOD files (OpenMRS Module)
+- Can add new services, domain objects, web resources
+- Activated/deactivated at runtime
+- Module API separate from OMOD (web components)
+- See https://wiki.openmrs.org/display/docs/Modules for module development guide
+
+### Performance Considerations
+
+- Use lazy loading for associations where appropriate (now default for @ManyToOne audit fields)
+- Batch processing for large datasets
+- Cache frequently accessed data using Infinispan
+- Optimize HQL queries with proper indexes
+- Use pagination for large result sets
+- Profile with JProfiler or VisualVM if performance issues arise
+
+## Common Troubleshooting
+
+**Build failures**: Ensure Java 21 and Maven 3.8.0+ are installed. Clear local Maven repository if dependency issues occur: `rm -rf ~/.m2/repository/org/openmrs`
+
+**Test failures**: Some integration tests require specific database state. Run `mvn clean install` to reset test environment.
+
+**Module loading errors**: Check module compatibility with platform version. Modules must be built for Platform 2.x or 3.x.
+
+**Database migration issues**: Check `liquibasechangelog` table for failed changesets. Review OpenMRS logs for Liquibase errors.
+
+## Resources
+
+- **JIRA**: https://issues.openmrs.org
+- **Wiki**: https://wiki.openmrs.org
+- **Talk Forum**: https://talk.openmrs.org
+- **Developer Guide**: https://openmrs.atlassian.net/wiki/spaces/docs/pages/25477022/Getting+Started+as+a+Developer
+- **Module Repository**: https://addons.openmrs.org
+- **Demo Site**: http://demo.openmrs.org