Developer Guide

Verify Java Installation:

java -version
mvn -version
mongod --version

# Clone the repository
git clone https://github.com/BEAS-Software-Solutions/BEASRE.git
cd beas-rule-engine

# Check out the latest release
git checkout main

# Clean and compile
mvn clean compile

# Run tests
mvn test

# Build JAR file
mvn clean package

# Install to local repository
mvn clean install

# Run with Maven
mvn spring-boot:run

# Or run the JAR file
java -jar target/beas-rule-engine.jar

# Run with specific profile
mvn spring-boot:run -Dspring-boot.run.profiles=dev

Create environment file:

# Copy example file
cp env-example.sh .env

# Edit the file with your values
nano .env

# Source the environment variables
source .env

Required Environment Variables:

# MongoDB Configuration
export MONGODB_HOST=localhost
export MONGODB_PORT=27017
export MONGODB_DATABASE=beasre
export MONGODB_USERNAME=admin
export MONGODB_PASSWORD=password

# Cryptography Keys
export CRYPTO_KEY=your-32-character-key
export CRYPTO_IV=your-16-character-iv

# Server Configuration
export SERVER_PORT=8070
export SERVER_CONTEXT_PATH=/beasre

# Keycloak Configuration (Optional)
export KEYCLOAK_AUTH_SERVER_URL=http://localhost:8080/auth
export KEYCLOAK_REALM=beasre
export KEYCLOAK_RESOURCE=beas-rule-engine

spring:
  application:
    name: beas-rule-engine
  data:
    mongodb:
      host: ${MONGODB_HOST:localhost}
      port: ${MONGODB_PORT:27017}
      database: ${MONGODB_DATABASE:beasre}
      username: ${MONGODB_USERNAME:}
      password: ${MONGODB_PASSWORD:}
      authentication-database: admin

server:
  port: ${SERVER_PORT:8070}
  servlet:
    context-path: ${SERVER_CONTEXT_PATH:/beasre}

cryptography:
  key: ${CRYPTO_KEY}
  iv: ${CRYPTO_IV}

logging:
  level:
    com.beassolution.rule: DEBUG
    org.springframework.data.mongodb: DEBUG

Example Java 17 Code:

// Use records for DTOs
public record RuleRequest(
    String ruleName,
    Map<String, Object> parameters,
    Object payload
) {
    // Validation logic
}

// Use pattern matching
public String processRule(Object rule) {
    return switch (rule) {
        case String s -> "String rule: " + s;
        case Rule r -> "Complex rule: " + r.getName();
        case null -> "Null rule";
        default -> "Unknown rule type";
    };
}

Directory Structure:

src/
├── main/
│   ├── java/
│   │   └── com/beassolution/rule/
│   │       ├── advice/           # Global advice and exception handling
│   │       ├── components/       # Core components (cache, crypto)
│   │       ├── config/          # Configuration classes
│   │       ├── controller/      # REST controllers
│   │       ├── crypto/          # Cryptography services
│   │       ├── dto/             # Data transfer objects
│   │       ├── engine/          # Rule engine core
│   │       ├── exception/       # Custom exceptions
│   │       ├── listener/        # Event listeners
│   │       ├── model/           # Entity models
│   │       ├── repository/      # Data access layer
│   │       ├── rsql/            # RSQL query support
│   │       ├── service/         # Business logic services
│   │       └── util/            # Utility classes
│   └── resources/
│       ├── application.yaml     # Application configuration
│       └── application-*.yaml   # Profile-specific configs
└── test/
    └── java/
        └── com/beassolution/rule/
            ├── controller/       # Controller tests
            ├── service/          # Service tests
            └── integration/      # Integration tests

Example Feature Implementation:

// 1. Create model
@Entity
public class NewFeature {
    @Id
    private String id;
    private String name;
    // ... other fields
}

// 2. Create repository
@Repository
public interface NewFeatureRepository extends MongoRepository<NewFeature, String> {
    // Custom queries
}

// 3. Create service
@Service
public class NewFeatureService extends BaseService<NewFeature> {
    // Business logic
}

// 4. Create controller
@RestController
@RequestMapping("/api/v1/new-feature")
public class NewFeatureController extends BaseController<NewFeature> {
    // REST endpoints
}

Example Unit Test:

@ExtendWith(MockitoExtension.class)
class RuleEngineServiceTest {
    
    @Mock
    private RuleRepository ruleRepository;
    
    @InjectMocks
    private RuleEngineService ruleEngineService;
    
    @Test
    void testEvaluateRule() {
        // Given
        RuleRequest request = new RuleRequest("test-rule", Map.of(), "payload");
        Rule rule = new Rule("test-rule", "return true;");
        
        when(ruleRepository.findByName("test-rule")).thenReturn(Optional.of(rule));
        
        // When
        RuleResponse response = ruleEngineService.evaluateRule(request);
        
        // Then
        assertThat(response).isNotNull();
        assertThat(response.getResult()).isEqualTo(true);
        verify(ruleRepository).findByName("test-rule");
    }
}

Example Integration Test:

@SpringBootTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
class RuleEngineIntegrationTest {
    
    @Autowired
    private TestRestTemplate restTemplate;
    
    @Test
    void testRuleEvaluationEndpoint() {
        // Given
        RuleRequest request = new RuleRequest("test-rule", Map.of(), "payload");
        
        // When
        ResponseEntity<RuleResponse> response = restTemplate.postForEntity(
            "/beasre/v1/rule-engine/evaluate",
            request,
            RuleResponse.class
        );
        
        // Then
        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
        assertThat(response.getBody()).isNotNull();
    }
}

# Run all tests
mvn test

# Run specific test class
mvn test -Dtest=RuleEngineServiceTest

# Run tests with coverage
mvn test jacoco:report

# Run integration tests
mvn test -Dtest=*IntegrationTest

Build Docker Image:

# Build the application
mvn clean package

# Build Docker image
docker build -t beas-rule-engine .

# Run container
docker run -d \
  --name beas-rule-engine \
  -p 8070:8070 \
  -e MONGODB_HOST=mongodb \
  -e CRYPTO_KEY=your-key \
  -e CRYPTO_IV=your-iv \
  beas-rule-engine

Kubernetes YAML:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: beas-rule-engine
spec:
  replicas: 3
  selector:
    matchLabels:
      app: beas-rule-engine
  template:
    metadata:
      labels:
        app: beas-rule-engine
    spec:
      containers:
      - name: beas-rule-engine
        image: beas-rule-engine:latest
        ports:
        - containerPort: 8070
        env:
        - name: MONGODB_HOST
          value: "mongodb-service"
        - name: CRYPTO_KEY
          valueFrom:
            secretKeyRef:
              name: beas-secrets
              key: crypto-key