Skip to main content

ElastiCORE Environment Configuration Guide (env.yml)

Overview​

env.yml is the ElastiCORE domain-specific environment configuration file that defines code generation modes, frameworks, namespaces, annotations, and more. Environment configuration information must be defined before DSL-based modeling.

Basic Structure​

elasticore:  # or env: (legacy format)
  enable: true/false
  config:
    domainName: string
    framework: string
    mode: string
    j2ee: string
    # Additional settings per mode
  namespace:
    entity: package.path
    dto: package.path
    # Other namespaces

1. Basic Configuration (config)​

Required Settings​

config:
  domainName: myDomain        # Domain name (used in generated package and file names)
  framework: springboot       # Framework specification
  mode: jpa,uml              # Generation modes (comma-separated)
  j2ee: jakarta              # J2EE stack (jakarta/javax)

Framework Settings​

  • springboot: Latest Spring Boot version (default)

J2EE Stack Selection​

  • jakarta: Jakarta EE (default for Spring Boot 3.x)
  • javax: Java EE (default for Spring Boot 2.x) - This option is deprecated as Spring Boot 2 is no longer supported.

2. Generation Modes (mode)​

2.1 JPA Mode​

mode: jpa

Generated Items:

  • JPA entity classes
  • Spring Data JPA repositories
  • Service classes
  • REST controllers

JPA Mode Detailed Settings:

config:
  mode: jpa
  jpa:
    useQueryMethod: true     # Generate custom query methods
  table:
    prefix: "tbl_"          # Table prefix

2.2 UML Mode (deprecated)​

mode: uml

Generated Items:

  • Mermaid diagrams
  • HTML-format UML documentation
  • Entity relationship diagrams

2.3 MongoDB Mode​

mode: mongo

Generated Items:

  • MongoDB collection entities
  • Spring Data MongoDB repositories
  • MongoDB-specific services

MongoDB Mode Settings:

config:
  mode: mongo
  mongo:
    collection:
      prefix: "col_"        # Collection prefix

2.4 PX (ProductXpress) Mode​

mode: px

Generated Items:

  • Auto-generated PX platform integration model code
  • .pxdpz file-based model processing

PX Mode Settings:

config:
  mode: px
  pxdpz:                    # PX deployment file paths
    - C:\path\to\deployment1.pxdpz
    - C:\path\to\deployment2.pxdpz

3. Annotation Settings​

3.1 Custom Annotations​

config:
  annotations:
    # ID generator annotation
    genid: "genid(io.elasticore.springboot3.util.IdUtils.newId)"

    # Type conversion annotations
    stringarray: "@entity:Convert(converter = io.elasticore.springboot3.util.StringArrayConverter.class)"
    integerarray: "@entity:Convert(converter = io.elasticore.springboot3.util.IntegerArrayConverter.class)"

    # Custom validation annotations
    email: "@field:Email(message = 'Invalid email format')"
    phone: "@field:Pattern(regexp = '^[0-9-]+$', message = 'Invalid phone format')"

3.2 Annotation Usage Examples​

# Usage in model.yml
entity:
  User:
    fields:
      id: string @genid              # Apply genid annotation
      tags: string[] @env:stringarray # Apply stringarray annotation
      coords: int[] @env:integerarray # Apply integerarray annotation
      email: string @env:email        # Apply email validation annotation
      phone: string @env:phone        # Apply phone validation annotation

3.3 Annotation Scope​

  • @entity:: Entity class-level annotations
  • @field:: Field-level annotations
  • @method:: Method-level annotations

4. Template Settings​

4.1 Custom Template Configuration​

config:
  template:
    entity: custom/entity.tmpl      # Custom entity template
    dto: custom/dto.tmpl           # Custom DTO template
    service: custom/service.tmpl    # Custom service template
    repository: custom/repository.tmpl
    controller: custom/controller.tmpl

4.2 Test Code Generation Settings​

ElastiCORE can auto-generate JUnit 5-based unit tests for the service layer.

config:
  testCode:
    enabled: true                   # Enable test code generation (default: true)
    framework: junit5               # Test framework (default: junit5)
    mockFramework: mockito          # Mock framework (default: mockito)

Generated Test Code Features:

  • JUnit 5 + Mockito-based unit tests
  • Composite key entity auto-handling (composite key detection)
  • Auto sample data generation (supports all field types)
  • CRUD method full test coverage
  • Search method tests (supports both List and Page results)
  • Performance tests and integration-style tests included

Generated Test Method Example:

@Test
@DisplayName("findById - should return entity when found")
void findById_ShouldReturnEntityWhenFound() {
    // Auto-generated test logic
}

@Test
@DisplayName("save - should save and return new entity")
void save_ShouldSaveAndReturnNewEntity() {
    // Auto-generated test logic
}

// For composite key entities, composite key handling logic is auto-generated
@Test
@DisplayName("update - should update existing entity")
void update_ShouldUpdateExistingEntity() {
    ContractDriverId id = new ContractDriverId(contractNo, seqNo);
    // ... test logic
}

5. Namespace Settings​

5.1 Basic Namespaces​

namespace:
  entity: io.company.domain.entity           # Entity package
  dto: io.company.domain.dto                # DTO package
  enumeration: io.company.domain.enums      # Enumeration package
  repository: io.company.domain.repository   # Repository package
  service: io.company.domain.service        # Service package
  control: io.company.domain.controller     # Controller package
  port: io.company.domain.port              # Port package
  proto: io.company.proto                   # Protocol Buffer package

5.2 Namespace Naming Conventions​

Standard Pattern:

  • {basePackage}.{domain}.{type}
  • e.g., io.elasticore.blueprint.domain.bbs.entity

Recommended Structure:

namespace:
  entity: com.company.{domain}.entity
  dto: com.company.{domain}.dto
  enumeration: com.company.{domain}.enums
  repository: com.company.{domain}.repository
  service: com.company.{domain}.service
  control: com.company.{domain}.controller

6. DataSource Settings​

6.1 Multiple DataSources​

config:
  datasources:
    main:                                    # Default datasource
      driver: org.h2.Driver
      url: jdbc:h2:mem:testdb
      username: sa
      password: ""
    
    legacy:                                  # Legacy datasource
      driver: com.mysql.cj.jdbc.Driver
      url: jdbc:mysql://localhost:3306/legacy
      username: root
      password: password
    
    analytics:                               # Analytics datasource
      driver: org.postgresql.Driver
      url: jdbc:postgresql://localhost:5432/analytics
      username: analyst
      password: secret

6.2 DataSource Usage​

# Usage in transaction ports
transaction:
  port:
    MainService:
      meta: dbms @datasource("main")         # Use main datasource
      
    LegacyService:
      meta: dbms @datasource("legacy")       # Use legacy datasource

7. Environment-Specific Configuration Examples​

7.1 Spring Boot 3 + JPA Environment​

elasticore:
  enable: true
  config:
    domainName: userManagement
    framework: springboot
    mode: jpa,uml
    j2ee: jakarta
    lombok: true
    
    jpa:
      useQueryMethod: true
      showSql: true
    
    table:
      prefix: "um_"
    
    testCode:
      enabled: true
      framework: junit5
      mockFramework: mockito
    
    interface:
      pageable: "com.company.common.CustomPageable"
      sortable: "com.company.common.CustomSortable"
    
    annotations:
      genid: "genid(io.elasticore.springboot3.util.IdUtils.newId)"
      audit: "@entity:EntityListeners(AuditingEntityListener.class)"
  
  namespace:
    entity: com.company.user.entity
    dto: com.company.user.dto
    enumeration: com.company.user.enums
    repository: com.company.user.repository
    service: com.company.user.service
    control: com.company.user.controller

7.2 MongoDB Environment​

env:
  config:
    mode: mongo,uml
    framework: springboot
    lombok: true
    domainName: dataStore
    j2ee: jakarta
    
    mongo:
      collection:
        prefix: "ds_"
      connection:
        database: datastore
        host: localhost
        port: 27017
  
  namespace:
    entity: com.company.data.entity
    dto: com.company.data.dto
    enumeration: com.company.data.enums
    repository: com.company.data.repository
    service: com.company.data.service

7.3 PX Platform Integration Environment​

env:
  config:
    mode: px
    framework: springboot:2.7
    lombok: true
    domainName: calculation
    
    pxdpz:
      - C:\px\deployments\CalculationDeployment_0_0@_0_1_Operation.pxdpz
      - C:\px\deployments\CalculationDeployment_0_0@_0_1_traditional.pxdpz
    
    template:
      entity: custom/px_entity.tmpl
      dto: elasticore-template/px/dto.tmpl
  
  namespace:
    entity: io.company.px.entity
    dto: io.company.px.dto
    enumeration: io.company.px.enums

7.4 Microservice Environment​

elasticore:
  enable: true
  config:
    domainName: orderService
    framework: springboot
    mode: jpa,uml,java
    j2ee: jakarta
    
    microservice:
      enabled: true
      port: 8080
      contextPath: /api/v1/orders
    
    jpa:
      useQueryMethod: true
      database: mysql
    
    annotations:
      genid: "genid(io.company.common.util.IdGenerator.generate)"
      trace: "@method:Traced"
      cache: "@method:Cacheable(value = 'default')"
  
  namespace:
    entity: io.company.order.entity
    dto: io.company.order.dto
    enumeration: io.company.order.enums
    repository: io.company.order.repository
    service: io.company.order.service
    control: io.company.order.controller
    port: io.company.order.port

8. Advanced Settings​

8.1 Environment Variable References​

config:
  domainName: ${DOMAIN_NAME:defaultDomain}
  framework: ${FRAMEWORK:springboot}
  
namespace:
  entity: ${BASE_PACKAGE:io.elasticore}.${DOMAIN_NAME:domain}.entity

8.2 Conditional Configuration​

config:
  mode: jpa,uml
  dev:
    mode: jpa,uml,java
  prod:
    mode: jpa

8.3 Plugin Settings​

config:
  plugins:
    swagger:
      enabled: true
      version: 3.0
    mapstruct:
      enabled: true
      componentModel: spring
    querydsl:
      enabled: true

8.4 Custom Interface Settings​

ElastiCORE allows customization of the Pageable and SortableObject interfaces used in SearchDTOs.

config:
  interface:
    pageable: "com.company.common.MyPageable"
    sortable: "com.company.common.MySortableObject"

Default Behavior (when not configured):

  • io.elasticore.springboot3.dto.PageableObject auto-generated
  • io.elasticore.springboot3.dto.SortableObject auto-generated

When using custom interfaces:

  • Imports and uses the specified interfaces
  • Does not generate the default interface classes
  • SearchDTO uses the custom interface types

Usage Example:

config:
  interface:
    pageable: "com.company.common.CustomPageable"
    sortable: "com.company.common.CustomSortable"

Custom Interface Implementation Example:

public interface CustomPageable {
    Pageable getPageable();
    void setPageable(Pageable pageable);
}

public interface CustomSortable {
    Sort getSort();
    void setSort(Sort sort);
}

Use Case Scenarios:

  • Using enterprise standard interfaces
  • Maintaining compatibility with existing projects
  • Extending additional pagination/sorting functionality

9. Best Practices​

9.1 Domain Separation​

  • Principle: Maintain an independent env.yml for each domain
  • Naming: Use names with clear business meaning for domain names
  • Packages: Independent package structure per domain

9.2 Environment-Specific Settings​

# Development settings
elasticore:
  enable: true
  config:
    domainName: ${DOMAIN_NAME:testDomain}
    mode: jpa,uml,java  # Generate all artifacts during development
    
# Production settings  
elasticore:
  enable: true
  config:
    domainName: ${DOMAIN_NAME:prodDomain}
    mode: jpa          # Generate only what's needed in production

9.3 Performance Optimization​

config:
  jpa:
    batchSize: 100
    fetchSize: 50
    useQueryMethod: false    # Prevent unnecessary query method generation

10. Troubleshooting Guide​

10.1 Activation Issues​

elasticore:
  enable: true  # Code generation is disabled when set to false

10.2 Version Compatibility​

# Spring Boot 3.x environment  
config:
  framework: springboot
  j2ee: jakarta

10.3 Namespace Conflicts​

# Bad example
namespace:
  entity: com.company.entity  # Too generic
  
# Good example
namespace:
  entity: com.company.order.entity  # Separated by domain

10.4 Legacy Format Support​

# Old format (still supported)
env:
  config:
    # Configuration content

# New format (recommended)
elasticore:
  config:
    # Configuration content

11. Configuration Validation​

11.1 Required Items Checklist​

  • domainName configured
  • framework specified
  • mode selected
  • j2ee stack specified
  • All necessary namespace entries defined
  • lombok: true configured (code simplification)
  • Environment-specific settings separated
  • Meaningful domain name used
  • Consistent package naming

11.3 New Features Checklist​

  • testCode.enabled: true configured (auto test code generation)
  • Composite key entity tests verified
  • Custom Interface utilized (when needed)
  • Test coverage confirmed

11.4 Testing Recommendations​

  • Composite key entities: Verify the composite key handling logic in auto-generated test code
  • Sample data: Review whether auto-generated sample data is appropriate for business logic
  • Test execution: Confirm auto-generated test code runs properly with ./gradlew test
  • Customization: Modify generated test code to fit business requirements as needed