Cobol Migration Analyzer

COBOL Migration Analyzer

Analyze legacy COBOL programs and JCL scripts for migration to Java. Extract business logic, data structures, and dependencies to generate actionable migration strategies.

Core Capabilities

1. COBOL Program Analysis

Extract COBOL divisions (IDENTIFICATION, ENVIRONMENT, DATA, PROCEDURE), Working-Storage variables, file definitions (FD), business logic paragraphs, PERFORM statements, CALL hierarchies, embedded SQL, and error handling patterns.

2. JCL Job Analysis

Parse JCL job steps, program invocations, data dependencies (DD statements), conditional logic (COND, IF/THEN/ELSE), return codes, and resource requirements.

3. Copybook Processing

Extract record layouts with level numbers, REDEFINES clauses, group items, OCCURS clauses, and picture clauses. Generate Java POJOs from copybook structures.

4. Dependency Mapping

Build complete dependency graphs showing CALL hierarchies, copybook usage, file dependencies, database table access, and shared utility references across the codebase.

Workflow

Step 1: Discover COBOL Assets

Find COBOL programs, JCL jobs, and copybooks:

find . -name "*.cbl" -o -name "*.CBL" -o -name "*.cob"
find . -name "*.jcl" -o -name "*.JCL"
find . -name "*.cpy" -o -name "*.CPY"

Use scripts/analyze-dependencies.sh or scripts/analyze-dependencies.ps1 to generate dependency graph.

Step 2: Extract Structure

Use scripts/extract-structure.py to parse COBOL programs and extract divisions, variables, paragraphs, and dependencies in JSON format.

Step 3: Generate Java Code

Use scripts/generate-java-classes.py to convert copybooks to Java POJOs with appropriate data types and Bean Validation annotations.

Step 4: Estimate Complexity

Use scripts/estimate-complexity.py to calculate migration complexity based on LOC, external calls, file operations, SQL statements, and control flow.

Step 5: Create Migration Strategy

Document program overview, dependencies, data structures, business logic patterns, proposed Java design, migration estimate, and action items.

Quick Reference

COBOL to Java Type Mapping

Common Pattern Conversions

• File I/O: READ...AT END → BufferedReader with try-with-resources or NIO streams
• File updates: REWRITE → Update operations in DB or file systems
• Table lookup: SEARCH → Linear search with streams
• Binary search: SEARCH ALL → Collections.binarySearch() or stream().filter().findFirst()
• String operations: STRING/UNSTRING → StringBuilder or String.split()
• Inspection: INSPECT → String.replace(), replaceAll(), or regex
• CALL statements: → Method calls or service invocations
• EVALUATE: → switch statement (Java 14+ with enhanced switch)
• Date arithmetic: FUNCTION INTEGER-OF-DATE → LocalDate operations
• ACCEPT DATE/TIME: → LocalDate.now(), LocalTime.now()
• Condition names (Level 88): → enum or typed constants
• Computed GO TO: → Strategy pattern or switch statement
• REDEFINES: → Union types, ByteBuffer views, or separate accessor classes
• COPY statements: → Package imports or shared entity classes

Example: Copybook to Java POJO

COBOL Copybook:

01  EMPLOYEE-RECORD.
    05  EMP-ID        PIC 9(6).
    05  EMP-NAME      PIC X(30).
    05  EMP-SALARY    PIC S9(7)V99 COMP-3.

Generated Java:

public class EmployeeRecord {
    private int empId;
    private String empName;
    private BigDecimal empSalary;
    // getters/setters
}

Migration Considerations

Critical Patterns:

1. ALWAYS use BigDecimal for COMP-3 and numeric with decimals (never float/double) 2. Preserve precision: Use BigDecimal with exact scale for financial calculations 3. 1-based indexing: Document that COBOL arrays start at 1, Java at 0 4. Implicit conversions: Make COBOL's automatic numeric↔string conversions explicit 5. REDEFINES: Model as union type, ByteBuffer overlay, or separate view classes 6. Computed GO TO: Refactor to strategy pattern or switch statement 7. ALTER statement: Refactor to structured control flow (if/while/switch) 8. PERFORM THRU: Map to single method containing full paragraph range 9. BY REFERENCE vs BY CONTENT: Document parameter passing semantics 10. Test rigorously: Validate with production data samples, especially for COMP-3

Output Requirements:

• Program overview and type classification
• Complete dependency graph (CALL tree, copybooks, files, DB tables)
• Data structure mapping (copybooks → Java classes)
• Business logic summary (key paragraphs → methods)
• Proposed Java architecture (services, repositories, entities)
• Migration effort estimate (complexity score, LOC, risk factors)
• Prioritized action items

Advanced Topics

For detailed conversion rules and patterns, see:

• [pseudocode-cobol-rules.md](references/pseudocode-cobol-rules.md) - Comprehensive COBOL to pseudocode conversion rules including data types, statements, file operations, string operations, table operations, program control, translation patterns, and common gotchas
• [pseudocode-common-rules.md](references/pseudocode-common-rules.md) - Common pseudocode syntax and conventions applicable to all languages
• [transaction-handling.md](references/transaction-handling.md) - Transaction management and rollback strategies for CICS/IMS to Java
• [messaging-integration.md](references/messaging-integration.md) - Message queue and async patterns (MQ, CICS queues to JMS/Kafka)
• [performance-patterns.md](references/performance-patterns.md) - Batch processing optimization and memory management
• [testing-strategy.md](references/testing-strategy.md) - Comprehensive testing including unit, integration, parallel validation, and data-driven testing

Tools and Scripts

All scripts support cross-platform execution (Windows PowerShell, bash):

• analyze-dependencies.sh/ps1 - Generate dependency graph
• extract-structure.py - Parse COBOL structure to JSON
• generate-java-classes.py - Convert copybooks to Java POJOs
• estimate-complexity.py - Calculate migration complexity score

Scripts use standard libraries only and output JSON for easy integration with CI/CD pipelines.

COBOL Program Migration Report

Program: {{PROGRAM_NAME}} Migration Date: {{MIGRATION_DATE}} Analyst: {{ANALYST_NAME}} Status: {{STATUS}}

---

1. Executive Summary

Program Overview

• Purpose: {{PROGRAM_PURPOSE}}
• Type: {{PROGRAM_TYPE}} (Batch/Online/Utility)
• Lines of Code: {{LOC}}
• Complexity: {{COMPLEXITY_LEVEL}}
• Estimated Effort: {{EFFORT_DAYS}} person-days

Migration Recommendation

{{RECOMMENDATION}}

---

2. Source Analysis

Program Structure

Divisions

• IDENTIFICATION DIVISION: Line {{ID_DIV_LINE}}
• ENVIRONMENT DIVISION: Line {{ENV_DIV_LINE}}
• DATA DIVISION: Line {{DATA_DIV_LINE}}
• PROCEDURE DIVISION: Line {{PROC_DIV_LINE}}

Key Data Structures

{{DATA_STRUCTURES_TABLE}}

Copybooks Used

{{COPYBOOKS_TABLE}}

Business Logic Summary

{{BUSINESS_LOGIC_SUMMARY}}

Control Flow

{{CONTROL_FLOW_DESCRIPTION}}

---

3. Dependencies

Program Calls

{{PROGRAM_CALLS_TABLE}}

File Operations

{{FILE_OPERATIONS_TABLE}}

Database Operations

{{DATABASE_OPERATIONS_TABLE}}

Dependency Graph

{{DEPENDENCY_GRAPH}}

---

4. Java Design

Proposed Architecture

Package Structure

{{PACKAGE_STRUCTURE}}

Class Design

{{CLASS_DESIGN_TABLE}}

Method Signatures

{{METHOD_SIGNATURES}}

Data Model

{{DATA_MODEL_DESCRIPTION}}

Service Layer

{{SERVICE_LAYER_DESCRIPTION}}

---

5. Complexity Assessment

Metrics

• Cyclomatic Complexity: {{CYCLOMATIC_COMPLEXITY}}
• Number of Paragraphs: {{PARAGRAPH_COUNT}}
• External Dependencies: {{DEPENDENCY_COUNT}}
• File Operations: {{FILE_OP_COUNT}}
• Database Operations: {{DB_OP_COUNT}}
• Complexity Score: {{COMPLEXITY_SCORE}}

Risk Factors

{{RISK_FACTORS_LIST}}

Technical Challenges

1. {{CHALLENGE_1}} 2. {{CHALLENGE_2}} 3. {{CHALLENGE_3}}

---

6. Migration Strategy

Approach

{{MIGRATION_APPROACH}}

Phase 1: Preparation ({{PHASE1_DAYS}} days)

• [ ] {{PREP_TASK_1}}
• [ ] {{PREP_TASK_2}}
• [ ] {{PREP_TASK_3}}

Phase 2: Implementation ({{PHASE2_DAYS}} days)

• [ ] {{IMPL_TASK_1}}
• [ ] {{IMPL_TASK_2}}
• [ ] {{IMPL_TASK_3}}

Phase 3: Testing ({{PHASE3_DAYS}} days)

• [ ] {{TEST_TASK_1}}
• [ ] {{TEST_TASK_2}}
• [ ] {{TEST_TASK_3}}

Phase 4: Deployment ({{PHASE4_DAYS}} days)

• [ ] {{DEPLOY_TASK_1}}
• [ ] {{DEPLOY_TASK_2}}
• [ ] {{DEPLOY_TASK_3}}

---

7. Testing Plan

Unit Testing

{{UNIT_TEST_PLAN}}

Integration Testing

{{INTEGRATION_TEST_PLAN}}

Parallel Run Testing

{{PARALLEL_RUN_PLAN}}

Performance Testing

{{PERFORMANCE_TEST_PLAN}}

---

8. Data Migration

Data Structures to Migrate

{{DATA_MIGRATION_STRUCTURES}}

Migration Scripts Required

• [ ] {{MIGRATION_SCRIPT_1}}
• [ ] {{MIGRATION_SCRIPT_2}}
• [ ] {{MIGRATION_SCRIPT_3}}

Validation Approach

{{VALIDATION_APPROACH}}

---

9. Implementation Notes

Special Considerations

{{SPECIAL_CONSIDERATIONS}}

Code Patterns

{{CODE_PATTERNS}}

Performance Optimization

{{PERFORMANCE_NOTES}}

---

10. Timeline and Resources

Schedule

Resource Requirements

• Java Developers: {{JAVA_DEV_COUNT}}
• COBOL Analysts: {{COBOL_ANALYST_COUNT}}
• QA Engineers: {{QA_COUNT}}
• DevOps: {{DEVOPS_COUNT}}

Dependencies

• [ ] {{EXTERNAL_DEPENDENCY_1}}
• [ ] {{EXTERNAL_DEPENDENCY_2}}
• [ ] {{EXTERNAL_DEPENDENCY_3}}

---

11. Success Criteria

Functional

• [ ] All business logic correctly migrated
• [ ] 100% test coverage for critical paths
• [ ] Parallel run matches COBOL output (99.9%+)

Non-Functional

• [ ] Performance meets or exceeds COBOL
• [ ] Response time < {{RESPONSE_TIME_TARGET}}ms
• [ ] Throughput >= {{THROUGHPUT_TARGET}} TPS

Quality

• [ ] Code review completed
• [ ] Documentation complete
• [ ] Knowledge transfer completed

---

12. Appendices

A. COBOL Source Reference

{{COBOL_SOURCE_EXCERPTS}}

B. Generated Java Code Samples

{{JAVA_CODE_SAMPLES}}

C. Test Cases

{{TEST_CASES}}

D. References

• COBOL Program: {{COBOL_FILE_PATH}}
• Design Document: {{DESIGN_DOC_PATH}}
• Test Data: {{TEST_DATA_PATH}}

---

Report Generated: {{REPORT_DATE}} Tool: COBOL Migration Analyzer Agent Skill v1.0.0

Messaging Integration Patterns

Guide for migrating mainframe messaging patterns (MQ, CICS transient data) to modern Java messaging.

Overview

Mainframe systems use IBM MQ, CICS queues, and transient data for asynchronous communication. This guide shows how to migrate these patterns to modern Java messaging frameworks.

Common Mainframe Patterns

1. IBM MQ Messages

COBOL Example:

EXEC CICS WRITEQ TS
    QUEUE('ORDERQ')
    FROM(ORDER-MESSAGE)
    LENGTH(ORDER-LENGTH)
END-EXEC.

EXEC CICS READQ TS
    QUEUE('ORDERQ')
    INTO(ORDER-MESSAGE)
    LENGTH(ORDER-LENGTH)
END-EXEC.

2. CICS Transient Data

EXEC CICS WRITEQ TD
    QUEUE('LOGG')
    FROM(LOG-MESSAGE)
    LENGTH(LOG-LENGTH)
END-EXEC.

Java Messaging Patterns

Pattern 1: Spring JMS with ActiveMQ

Configuration:

@Configuration
@EnableJms
public class JmsConfig {
    
    @Bean
    public ConnectionFactory connectionFactory() {
        return new ActiveMQConnectionFactory("tcp://localhost:61616");
    }
    
    @Bean
    public JmsTemplate jmsTemplate(ConnectionFactory connectionFactory) {
        JmsTemplate template = new JmsTemplate(connectionFactory);
        template.setDefaultDestinationName("order.queue");
        return template;
    }
}

Sender (equivalent to WRITEQ):

@Service
public class OrderMessageSender {
    
    @Autowired
    private JmsTemplate jmsTemplate;
    
    public void sendOrder(Order order) {
        jmsTemplate.convertAndSend("order.queue", order, message -> {
            message.setStringProperty("orderType", order.getType());
            message.setStringProperty("priority", order.getPriority());
            return message;
        });
    }
}

Receiver (equivalent to READQ):

@Service
public class OrderMessageReceiver {
    
    @JmsListener(destination = "order.queue")
    public void receiveOrder(Order order) {
        log.info("Received order: {}", order.getId());
        processOrder(order);
    }
    
    // Manual receive (blocking)
    public Order receiveOrderManually() {
        return (Order) jmsTemplate.receiveAndConvert("order.queue");
    }
}

Pattern 2: Spring AMQP with RabbitMQ

Configuration:

@Configuration
public class RabbitConfig {
    
    @Bean
    public Queue orderQueue() {
        return new Queue("order.queue", true); // durable
    }
    
    @Bean
    public Exchange orderExchange() {
        return new TopicExchange("order.exchange");
    }
    
    @Bean
    public Binding binding(Queue queue, Exchange exchange) {
        return BindingBuilder
            .bind(queue)
            .to(exchange)
            .with("order.#")
            .noargs();
    }
    
    @Bean
    public RabbitTemplate rabbitTemplate(ConnectionFactory connectionFactory) {
        RabbitTemplate template = new RabbitTemplate(connectionFactory);
        template.setMessageConverter(new Jackson2JsonMessageConverter());
        return template;
    }
}

Sender:

@Service
public class RabbitOrderSender {
    
    @Autowired
    private RabbitTemplate rabbitTemplate;
    
    public void sendOrder(Order order) {
        rabbitTemplate.convertAndSend(
            "order.exchange",
            "order.new",
            order
        );
    }
}

Receiver:

@Service
public class RabbitOrderReceiver {
    
    @RabbitListener(queues = "order.queue")
    public void handleOrder(Order order) {
        processOrder(order);
    }
}

Pattern 3: Spring Kafka

Configuration:

@Configuration
public class KafkaConfig {
    
    @Bean
    public ProducerFactory<String, Order> producerFactory() {
        Map<String, Object> config = new HashMap<>();
        config.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
        config.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class);
        config.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, JsonSerializer.class);
        return new DefaultKafkaProducerFactory<>(config);
    }
    
    @Bean
    public KafkaTemplate<String, Order> kafkaTemplate() {
        return new KafkaTemplate<>(producerFactory());
    }
    
    @Bean
    public ConsumerFactory<String, Order> consumerFactory() {
        Map<String, Object> config = new HashMap<>();
        config.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
        config.put(ConsumerConfig.GROUP_ID_CONFIG, "order-processor");
        config.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class);
        config.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, JsonDeserializer.class);
        config.put(JsonDeserializer.TRUSTED_PACKAGES, "*");
        return new DefaultKafkaConsumerFactory<>(config);
    }
}

Producer:

@Service
public class KafkaOrderProducer {
    
    @Autowired
    private KafkaTemplate<String, Order> kafkaTemplate;
    
    public void sendOrder(Order order) {
        kafkaTemplate.send("order-topic", order.getId(), order)
            .addCallback(
                success -> log.info("Order sent: {}", order.getId()),
                failure -> log.error("Failed to send order", failure)
            );
    }
}

Consumer:

@Service
public class KafkaOrderConsumer {
    
    @KafkaListener(topics = "order-topic", groupId = "order-processor")
    public void consume(Order order) {
        log.info("Consumed order: {}", order.getId());
        processOrder(order);
    }
}

Migration Patterns

Pattern 1: Request-Reply

COBOL/MQ:

* Send request
MOVE 'TEMP-REPLY-Q' TO MQMD-REPLYTOQ
CALL 'MQPUT' USING ...

* Wait for reply
CALL 'MQGET' USING MQMD MQGMO REPLYQ-NAME ...

Java/JMS:

@Service
public class RequestReplyService {
    
    @Autowired
    private JmsTemplate jmsTemplate;
    
    public Response sendRequest(Request request) {
        return (Response) jmsTemplate.convertSendAndReceive(
            "request.queue",
            request,
            message -> {
                message.setJMSReplyTo(
                    new ActiveMQQueue("reply.queue")
                );
                return message;
            }
        );
    }
}

Pattern 2: Dead Letter Queue

Configuration:

@Bean
public ReplyingKafkaTemplate<String, Order, OrderResult> replyingKafkaTemplate(
        ProducerFactory<String, Order> pf,
        KafkaMessageListenerContainer<String, OrderResult> container) {
    return new ReplyingKafkaTemplate<>(pf, container);
}

@Bean
public DeadLetterPublishingRecoverer deadLetterPublishingRecoverer(
        KafkaTemplate<String, Order> template) {
    return new DeadLetterPublishingRecoverer(template);
}

Usage:

@KafkaListener(topics = "order-topic")
public void processOrder(Order order) {
    try {
        validateAndProcess(order);
    } catch (ValidationException e) {
        // Will be sent to DLQ automatically
        throw new RuntimeException("Invalid order", e);
    }
}

Pattern 3: Message Retry

Configuration:

@Configuration
public class RetryConfig {
    
    @Bean
    public ErrorHandler errorHandler(KafkaTemplate<String, Order> template) {
        // Retry 3 times with exponential backoff
        DefaultErrorHandler handler = new DefaultErrorHandler(
            new DeadLetterPublishingRecoverer(template),
            new FixedBackOff(1000L, 3L)
        );
        
        handler.addNotRetryableExceptions(ValidationException.class);
        return handler;
    }
}

Message Format Conversion

COBOL Fixed-Length to JSON

COBOL Message:

01  ORDER-MESSAGE.
    05  ORDER-ID        PIC X(10).
    05  CUSTOMER-ID     PIC X(10).
    05  AMOUNT          PIC 9(7)V99 COMP-3.
    05  ORDER-DATE      PIC 9(8).

Java DTO:

@Data
public class OrderMessage {
    private String orderId;
    private String customerId;
    private BigDecimal amount;
    private LocalDate orderDate;
    
    // Converter from COBOL format
    public static OrderMessage fromCobolBytes(byte[] bytes) {
        // Parse fixed-length format
        String orderId = new String(bytes, 0, 10).trim();
        String customerId = new String(bytes, 10, 10).trim();
        BigDecimal amount = CobolConverter.fromPackedDecimal(bytes, 20, 5);
        LocalDate orderDate = CobolConverter.fromCobolDate(bytes, 25, 8);
        
        return new OrderMessage(orderId, customerId, amount, orderDate);
    }
}

Transaction Management

XA Transactions with Messaging

@Configuration
@EnableTransactionManagement
public class XAMessagingConfig {
    
    @Bean
    public JmsTransactionManager transactionManager(
            ConnectionFactory connectionFactory) {
        return new JmsTransactionManager(connectionFactory);
    }
}

@Service
public class TransactionalMessagingService {
    
    @Transactional
    public void processWithTransaction(Order order) {
        // Save to database
        orderRepository.save(order);
        
        // Send message (part of same transaction)
        jmsTemplate.convertAndSend("order.processed", order);
        
        // Both commit or rollback together
    }
}

Monitoring and Error Handling

Message Metrics

@Component
public class MessagingMetrics {
    
    private final Counter messagesReceived;
    private final Counter messagesFailed;
    private final Timer processingTime;
    
    public MessagingMetrics(MeterRegistry registry) {
        this.messagesReceived = registry.counter("messages.received");
        this.messagesFailed = registry.counter("messages.failed");
        this.processingTime = registry.timer("messages.processing.time");
    }
    
    @Around("@annotation(JmsListener)")
    public Object monitorMessageProcessing(ProceedingJoinPoint pjp) throws Throwable {
        messagesReceived.increment();
        Timer.Sample sample = Timer.start();
        
        try {
            Object result = pjp.proceed();
            sample.stop(processingTime);
            return result;
        } catch (Exception e) {
            messagesFailed.increment();
            throw e;
        }
    }
}

Error Handling

@Service
public class MessagingErrorHandler {
    
    @JmsListener(destination = "order.queue")
    public void handleOrder(Order order, @Header("JMSRedelivered") boolean redelivered) {
        try {
            processOrder(order);
        } catch (Exception e) {
            if (redelivered) {
                // Already retried, send to DLQ
                sendToDeadLetterQueue(order, e);
            } else {
                // First failure, throw to trigger redelivery
                throw new RuntimeException("Processing failed", e);
            }
        }
    }
}

Migration Checklist

• [ ] Identify all MQ queue usages
• [ ] Map CICS transient data queues
• [ ] Choose appropriate messaging technology (JMS/AMQP/Kafka)
• [ ] Design message formats (JSON vs. binary)
• [ ] Implement message converters
• [ ] Configure error handling and DLQ
• [ ] Set up monitoring and alerting
• [ ] Test message ordering guarantees
• [ ] Verify transaction behavior
• [ ] Performance test under load
• [ ] Document migration patterns

Performance Patterns for Migrated Code

This document provides guidance on optimizing Java code migrated from COBOL, addressing common performance challenges.

Overview

COBOL programs often process large volumes of data efficiently using mainframe-optimized patterns. When migrating to Java, it's important to maintain or improve performance while adapting to modern architectures.

Common Performance Patterns

1. Batch Processing with Streams

COBOL Pattern: Sequential file processing Java Solution: Use Java Streams for efficient batch processing

// Instead of loading all records into memory
List<Record> records = loadAllRecords(); // DON'T

// Use streaming
try (Stream<String> lines = Files.lines(path)) {
    lines.map(this::parseRecord)
         .filter(this::isValid)
         .forEach(this::processRecord);
}

2. Database Batch Operations

COBOL Pattern: Cursor processing with commits every N records Java Solution: JDBC batch updates

try (PreparedStatement pstmt = conn.prepareStatement(sql)) {
    for (Record record : records) {
        pstmt.setString(1, record.getId());
        pstmt.setString(2, record.getName());
        pstmt.addBatch();
        
        if (++count % 1000 == 0) {
            pstmt.executeBatch();
            conn.commit();
        }
    }
    pstmt.executeBatch();
    conn.commit();
}

3. Memory Management

Challenge: COBOL's fixed memory model vs. Java's heap Solution: Process in chunks, use pagination

public void processLargeFile(Path file) {
    int batchSize = 1000;
    List<Record> batch = new ArrayList<>(batchSize);
    
    try (Stream<String> lines = Files.lines(file)) {
        lines.forEach(line -> {
            batch.add(parseRecord(line));
            if (batch.size() >= batchSize) {
                processBatch(new ArrayList<>(batch));
                batch.clear();
            }
        });
        if (!batch.isEmpty()) {
            processBatch(batch);
        }
    }
}

4. Parallel Processing

COBOL Pattern: Single-threaded sequential processing Java Solution: Parallel streams for CPU-bound operations

// For independent record processing
records.parallelStream()
       .map(this::transform)
       .forEach(this::save);

// Control parallelism
ForkJoinPool customPool = new ForkJoinPool(4);
customPool.submit(() ->
    records.parallelStream()
           .forEach(this::process)
).get();

5. String Operations

COBOL Pattern: Fixed-length strings with spaces Java Solution: Efficient string handling

// Avoid creating many temporary strings
StringBuilder sb = new StringBuilder();
for (Record r : records) {
    sb.append(r.getId()).append('|')
      .append(r.getName()).append('\n');
}
String output = sb.toString();

// For fixed-length COBOL fields
String padded = String.format("%-20s", value); // Left-padded
String numeric = String.format("%010d", number); // Zero-padded

6. Caching Lookup Tables

COBOL Pattern: In-memory tables loaded at startup Java Solution: Use efficient caching

// Simple cache
private final Map<String, RateEntry> rateCache = new HashMap<>();

// Caffeine cache with eviction
LoadingCache<String, RateEntry> cache = Caffeine.newBuilder()
    .maximumSize(10_000)
    .expireAfterWrite(1, TimeUnit.HOURS)
    .build(key -> loadRate(key));

7. File I/O Optimization

COBOL Pattern: Blocked records for efficient I/O Java Solution: Buffered I/O with appropriate buffer sizes

// Reading
try (BufferedReader reader = new BufferedReader(
        new FileReader(file), 8192 * 4)) { // 32KB buffer
    String line;
    while ((line = reader.readLine()) != null) {
        processLine(line);
    }
}

// Writing
try (BufferedWriter writer = new BufferedWriter(
        new FileWriter(file), 8192 * 4)) {
    for (Record r : records) {
        writer.write(r.toLine());
        writer.newLine();
    }
}

Performance Testing

Benchmark Template

@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.MILLISECONDS)
@State(Scope.Thread)
public class MigrationBenchmark {
    
    @Param({"1000", "10000", "100000"})
    private int recordCount;
    
    @Setup
    public void setup() {
        // Initialize test data
    }
    
    @Benchmark
    public void testProcessing() {
        // Your processing logic
    }
}

Best Practices

1. Profile Before Optimizing: Use JProfiler, YourKit, or JFR 2. Set Realistic Goals: Match or exceed COBOL performance 3. Test with Production Volumes: Use representative data sizes 4. Monitor JVM Metrics: Heap, GC, thread pools 5. Use Appropriate Data Structures: ArrayList vs. LinkedList, HashMap vs. TreeMap 6. Minimize Object Creation: Reuse objects in tight loops 7. Consider Parallel Processing: But measure - not always faster 8. Optimize Database Access: Use connection pooling, prepared statements

Common Pitfalls

❌ DON'T: Load entire files into memory ✅ DO: Stream and process incrementally

❌ DON'T: Use + for string concatenation in loops ✅ DO: Use StringBuilder or StringJoiner

❌ DON'T: Create new SimpleDateFormat in loops (not thread-safe) ✅ DO: Use DateTimeFormatter (thread-safe) or ThreadLocal

❌ DON'T: Ignore connection pooling ✅ DO: Use HikariCP or similar

❌ DON'T: Assume parallel is always faster ✅ DO: Benchmark and measure

Monitoring Migration Performance

// Add metrics
public class ProcessingService {
    private final Timer processingTimer;
    private final Counter recordCounter;
    
    public void processRecords(List<Record> records) {
        Timer.Sample sample = Timer.start();
        try {
            records.forEach(this::process);
            recordCounter.increment(records.size());
        } finally {
            sample.stop(processingTimer);
        }
    }
}

COBOL Translation Rules

Prerequisites: Read PSEUDOCODE-COMMON-RULES.md for syntax, naming, and structure.

---

Division Mapping

Data Types

Statement Mapping

File Operations

| CString Operations

Table/Array Operations

Program Control

Translation Patterns

REDEFINES → Union/Overlay

01 DATA-FIELD PIC X(10).
01 DATA-NUMERIC REDEFINES DATA-FIELD PIC 9(10).

→

STRUCTURE DataOverlay:
    UNION:
        dataField: STRING[10]
        dataNumeric: INTEGER  // Same memory location
    END UNION
END STRUCTURE
// Document: dataField and dataNumeric share same storage

OCCURS DEPENDING ON → Dynamic Array

01 TABLE-RECORD.
   05 ITEM-COUNT PIC 9(3).
   05 ITEMS OCCURS 1 TO 100 DEPENDING ON ITEM-COUNT.
      10 ITEM-CODE PIC X(5).

→

STRUCTURE TableRecord:
    itemCount: INTEGER, 30=I/O error)
5. **ROUNDED**: Use `ROUND(expr, decimals)` with HALF_UP
6. **REDEFINES**: Document memory overlay with UNION or comments
7. **Group moves**: `MOVE group1 TO group2` copies entire structure by bytes
8. **Numeric moves**: Automatic alignment and truncation - document conversions
9. **Reference modification**: `field(start:length)` → `SUBSTRING(field, start, length)`
10. **CORRESPONDING**: Only moves fields with matching names
11. **Nested programs**: Map to nested procedures or separate modules
12. **GOBACK vs STOP RUN**: GOBACK returns to caller, STOP RUN terminates
13. **BY REFERENCE vs BY CONTENT**: Document parameter passing modes
14. **USAGE differences**: DISPLAY (character), COMP (binary), COMP-3 (packed)
15.Special Considerations

### Working-Storage vs Linkage Section

WORKING-STORAGE SECTION. → Local variables/data structures LINKAGE SECTION. → Parameters passed to program

→ Document parameter lists separately from local variables

### Picture Editing Characters

| COBOL Picture | Meaning | Pseudocode Note |
| ------------- | ------- | --------------- |
| `PIC Z(5)9` | Zero suppression | Format for display only |
| `PIC $(5)9.99` | Floating currency | Format for display only |
| `PIC 9(5).99CR` | Credit indicator | Format for display only |
| `PIC +9(5).99` | Sign indicator | Format for display only |

→ Use `FORMAT(value, pattern)` for display logic

### Date Handling

ACCEPT WS-DATE FROM DATE → WS-DATE = 'YYMMDD' ACCEPT WS-DATE FROM DATE YYYYMMDD → WS-DATE = 'YYYYMMDD' ACCEPT WS-DATETIME FROM DATETIME → 'YYYYMMDDHHMMSSnnnnnn'

→ Use `CURRENT_DATE()` with format specification

### SORT/MERGE Operations

SORT SORT-FILE ON ASCENDING KEY SORT-KEY USING INPUT-FILE GIVING OUTPUT-FILE

→

SORT_FILE(inputFile, outputFile, sortKeys=[{field: 'sortKey', order: ASCENDING}])

## Translation Workflow

1. Map IDENTIFICATION → Program Overview
2. Extract DATA DIVISION → Data Structures (preserve COMP-3!)
3. Identify copybooks → Document includes
4. Map 88-levels → ENUMs/BOOLEANs
5. Convert paragraphs → Procedures  
6. Translate PROCEDURE DIVISION → Main Algorithm
7. Handle special cases (REDEFINES, ODO, SEARCH)
8. Generate Mermaid flowchart
9. Document implicit conversions
10. Verify precision preserved
11. Document file status codes and error handling

## Common Gotchas

1. **Implicit type conversions**: Make all numeric↔string conversions explicit
2. **Truncation in moves**: Document when data may be truncated/padded
3. **PERFORM ranges**: Map THRU carefully - includes all paragraphs in range
4. **GO TO elimination**: Restructure as procedures/loops with proper exits
5. **CALL by reference**: All parameters shared unless BY CONTENT specified
6. **Index vs subscript**: INDEX is optimized pointer, subscript is computed offset
7. **Condition names**: Single 88-level may test multiple values (VALUE 'A' 'B' 'C')
8. **Computational fields**: Different USAGE affects storage and performance
9. **Sign handling**: SIGN LEADING/TRAILING SEPARATE affects storage format
10. **Floating-point**: COMP-1/COMP-2 NOT suitable for financial - document risks
EVALUATE TRUE
   WHEN STATUS-CODE = '00'
      PERFORM SUCCESS-ROUTINE
   WHEN STATUS-CODE = '10'
      PERFORM EOF-ROUTINE
   WHEN OTHER
      PERFORM ERROR-ROUTINE
END-EVALUATE

→

SWITCH statusCode:
    CASE '00':
        CALL SuccessRoutine()
        BREAK
    CASE '10':
        CALL EofRoutine()
        BREAK
    DEFAULT:
        CALL ErrorRoutine()
END SWITCH

SEARCH → Linear Search

SET IDX TO 1
SEARCH TABLE-ENTRY
   AT END PERFORM NOT-FOUND
   WHEN KEY-FIELD(IDX) = SEARCH-KEY
      PERFORM FOUND-ROUTINE
END-SEARCH

→

found = FALSE
FOR idx FROM 1 TO tableSize DO
    IF keyField[idx] == searchKey THEN
        CALL FoundRoutine()
        found = TRUE
        BREAK
    END IF
END FOR
IF NOT found THEN
    CALL NotFound()
END IF

SEARCH ALL → Binary Search

SEARCH ALL TABLE-ENTRY
   AT END PERFORM NOT-FOUND
   WHEN KEY-FIELD(IDX) = SEARCH-KEY
      PERFORM FOUND-ROUTINE
END-SEARCH

→

idx = BINARY_SEARCH(tableEntry, 'keyField', searchKey)
IF idx > 0 THEN
    CALL FoundRoutine()
ELSE
    CALL NotFound()
END IF
// Note: Table must be sorted on keyField

COPY/Copybook → Include

COPY CUSTOMER-REC.

→

INCLUDE "CustomerRecord.pseudo"
// Or inline the structure definition with comment:
// FROM COPYBOOK: CUSTOMER-REC
STRUCTURE CustomerRecord:
    ...
END STRUCTURE

PERFORM THRU → Procedure Sequence

PERFORM 1000-INIT THRU 1000-INIT-EXIT.

→

PROCEDURE InitSequence()  // Represents 1000-INIT through 1000-INIT-EXIT
BEGIN
    // All logic from 1000-INIT paragraph
    // ... through 1000-INIT-EXIT paragraph
END PROCEDURE
CALL InitSequence()

| ------- | ----------- | | OPEN INPUT file | file = OPEN(path) FOR READING | | OPEN OUTPUT file | file = OPEN(path) FOR WRITING | | READ file AT END | TRY: record = READ_RECORD(file) CATCH EndOfFile: | | WRITE record | WRITE_RECORD(file, record) | | CLOSE file | CLOSE(file) |

Translation Patterns

88-Level → ENUM

01 RECORD-TYPE PIC X.
   88 TYPE-HEADER VALUE 'H'.
IF TYPE-HEADER THEN ...

→

ENUM RecordType: HEADER='H', DETAIL='D' END ENUM
IF recordType == RecordType.HEADER THEN ...

Paragraph → Procedure

CALC-TOTAL.
    COMPUTE TOTAL = QTY * PRICE.
PERFORM CALC-TOTAL.

→

PROCEDURE CalcTotal()
BEGIN
    total = qty * price
END PROCEDURE
CALL CalcTotal()

File Loop

PERFORM UNTIL eof = 'Y'
    READ file AT END MOVE 'Y' TO eof
    NOT AT END PERFORM PROCESS-REC
    END-READ
END-PERFORM

→

eof = FALSE
WHILE NOT eof DO
    TRY:
        record = READ_RECORD(file)
        CALL ProcessRecord(record)
    CATCH EndOfFile:
        eof = TRUE
    END TRY
END WHILE

Critical Rules

1. 1-based indexing: COBOL starts at 1 → document in comments 2. COMP-3 precision: MUST preserve exactly using DECIMAL(n,m) 3. 88-levels: Convert to ENUM or BOOLEAN 4. File status: Map to exceptions (00=OK, 10=EOF, 23=not found) 5. ROUNDED: Use ROUND(expr, decimals) with HALF_UP

Translation Workflow

1. Map IDENTIFICATION → Program Overview 2. Extract DATA DIVISION → Data Structures (preserve COMP-3!) 3. Convert paragraphs → Procedures 4. Translate PROCEDURE DIVISION 5. Generate Mermaid flowchart 6. Verify precision preserved

Reference: ISO/IEC 1989:2014 (COBOL Standard)

Pseudocode Common Rules - All Languages

Naming Conventions

• Variables: camelCase (inputCount, customerName)
• Types/Structures: PascalCase (CustomerRecord, OrderDetail)
• Constants: UPPER_SNAKE_CASE (MAX_RECORDS, TAX_RATE)
• Functions/Procedures: PascalCase with verb (ProcessRecord, CalculateTotal)

Data Types

• INTEGER - whole numbers
• DECIMAL(n,m) - financial precision (n digits, m decimals)
• STRING[n] - text (max n characters)
• BOOLEAN - true/false
• DATE / DATETIME - dates/times
• ARRAY[n] OF TYPE - arrays
• STRUCTURE - composite types

Pseudocode Syntax

Structure Definition

STRUCTURE StructureName:
    field: TYPE[length]    // Description
END STRUCTURE

Constants

CONSTANTS:
    NAME = value
END CONSTANTS

Functions/Procedures

FUNCTION Name(param: TYPE) RETURNS TYPE
BEGIN
    RETURN value
END FUNCTION

PROCEDURE Name(param: TYPE)
BEGIN
    statements
END PROCEDURE

Control Flow

IF condition THEN ... ELSE ... END IF
WHILE condition DO ... END WHILE
FOR i FROM start TO end BY step DO ... END FOR
SWITCH expr: CASE val: ... BREAK; DEFAULT: ... END SWITCH

File Operations

file = OPEN(path) FOR READING|WRITING|APPENDING
record = READ_RECORD(file)
WRITE_RECORD(file, record)
CLOSE(file)
IF END_OF_FILE(file) THEN ...

Error Handling

TRY:
    statements
CATCH ExceptionType:
    handler
FINALLY:
    cleanup
END TRY

Financial Precision Rule

CRITICAL: Always use DECIMAL(n,m) for money. Never use floating point.

amount: DECIMAL(15,2)
result = ROUND(calculation, 2)  // Use HALF_UP rounding

Mermaid Flowchart Template

````mermaid flowchart TD Start([Start]) Process[Process Step] Decision{Condition?} End([End])

Start --> Process Process --> Decision Decision -->|Yes| End Decision -->|No| Process ````

Document Structure Template

# [PROGRAM-NAME] - Description

## Program Overview
- Purpose, Input, Output, Original Source

## Data Structures
[Structures and constants]

## Main Algorithm
[High-level flow]

## Core Processing Logic
[Detailed procedures]

## Flowchart (Mermaid)
[Diagram]

## Decision Logic / Special Cases / Error Handling
[Business rules and edge cases]

## Example Traces / Testing / Integration Points
[Walkthroughs and dependencies]

Testing Strategy for COBOL to Java Migration

Comprehensive testing approach to ensure functional equivalence and quality during migration.

Testing Pyramid for Migration

                    /\
                   /  \
                  / E2E\
                 /------\
                /  Integ \
               /----------\
              /    Unit    \
             /--------------\

1. Unit Testing

Testing Converted Business Logic

Goal: Verify each Java method matches COBOL paragraph behavior

@Test
void testCalculateBonus_seniorEmployee() {
    // Given
    Employee emp = new Employee();
    emp.setYearsOfService(12);
    emp.setSalary(new BigDecimal("50000"));
    
    // When
    BigDecimal bonus = bonusCalculator.calculate(emp);
    
    // Then
    assertEquals(new BigDecimal("7500.00"), bonus);
}

@Test
void testCalculateBonus_midLevelEmployee() {
    Employee emp = new Employee();
    emp.setYearsOfService(7);
    emp.setSalary(new BigDecimal("40000"));
    
    BigDecimal bonus = bonusCalculator.calculate(emp);
    
    assertEquals(new BigDecimal("4000.00"), bonus);
}

@Test
void testCalculateBonus_juniorEmployee() {
    Employee emp = new Employee();
    emp.setYearsOfService(2);
    emp.setSalary(new BigDecimal("30000"));
    
    BigDecimal bonus = bonusCalculator.calculate(emp);
    
    assertEquals(new BigDecimal("1500.00"), bonus);
}

Testing Data Transformations

@Test
void testCobolToJavaDataConversion() {
    // COBOL PIC S9(7)V99 COMP-3
    String cobolPackedDecimal = "0000012345C"; // 123.45
    
    BigDecimal result = converter.fromPackedDecimal(cobolPackedDecimal);
    
    assertEquals(new BigDecimal("123.45"), result);
}

@Test
void testDateConversion() {
    // COBOL date format: YYYYMMDD
    String cobolDate = "20260113";
    
    LocalDate result = converter.fromCobolDate(cobolDate);
    
    assertEquals(LocalDate.of(2026, 1, 13), result);
}

Parameterized Tests for Edge Cases

@ParameterizedTest
@CsvSource({
    "0, 0.00",
    "1, 1500.00",
    "5, 2000.00",
    "6, 4000.00",
    "10, 4000.00",
    "11, 7500.00",
    "20, 7500.00"
})
void testBonusCalculation_allRanges(int years, String expectedBonus) {
    Employee emp = new Employee();
    emp.setYearsOfService(years);
    emp.setSalary(new BigDecimal("50000"));
    
    BigDecimal bonus = bonusCalculator.calculate(emp);
    
    assertEquals(new BigDecimal(expectedBonus), bonus);
}

2. Integration Testing

Database Operations

@SpringBootTest
@Transactional
class CustomerRepositoryTest {
    
    @Autowired
    private CustomerRepository customerRepo;
    
    @Test
    void testSaveAndRetrieve() {
        // Given
        Customer customer = new Customer();
        customer.setId("CUST001");
        customer.setName("Test Customer");
        
        // When
        customerRepo.save(customer);
        entityManager.flush();
        entityManager.clear();
        
        // Then
        Optional<Customer> retrieved = customerRepo.findById("CUST001");
        assertTrue(retrieved.isPresent());
        assertEquals("Test Customer", retrieved.get().getName());
    }
}

File Processing

@SpringBootTest
class FileProcessorTest {
    
    @Autowired
    private FileProcessor processor;
    
    @TempDir
    Path tempDir;
    
    @Test
    void testProcessInputFile() throws IOException {
        // Given
        Path inputFile = tempDir.resolve("input.txt");
        Files.write(inputFile, Arrays.asList(
            "CUST001John Doe      00012345",
            "CUST002Jane Smith   00067890"
        ));
        
        // When
        ProcessingResult result = processor.process(inputFile);
        
        // Then
        assertEquals(2, result.getProcessedCount());
        assertEquals(0, result.getErrorCount());
    }
}

3. Parallel Run Testing

Strategy: Run Both Systems in Parallel

Goal: Prove functional equivalence with production data

@Service
public class ParallelRunService {
    
    @Autowired
    private LegacySystemAdapter legacyAdapter;
    
    @Autowired
    private NewJavaService newService;
    
    @Autowired
    private ResultComparator comparator;
    
    public ProcessingResult processWithComparison(InputData input) {
        // Run new system
        Result newResult = newService.process(input);
        
        // Run legacy system (asynchronously)
        CompletableFuture<Result> legacyFuture = 
            CompletableFuture.supplyAsync(() -> legacyAdapter.process(input));
        
        // Compare results
        legacyFuture.thenAccept(legacyResult -> {
            ComparisonResult comparison = comparator.compare(newResult, legacyResult);
            if (!comparison.isMatch()) {
                logDiscrepancy(input, newResult, legacyResult, comparison);
            }
        });
        
        // Return new result (legacy is shadow)
        return newResult;
    }
}

Result Comparison

@Service
public class ResultComparator {
    
    public ComparisonResult compare(Result actual, Result expected) {
        ComparisonResult result = new ComparisonResult();
        
        // Compare numeric fields with tolerance
        if (!compareDecimal(actual.getAmount(), expected.getAmount(), 0.01)) {
            result.addDifference("amount", expected.getAmount(), actual.getAmount());
        }
        
        // Compare strings (trim for COBOL spaces)
        if (!actual.getName().trim().equals(expected.getName().trim())) {
            result.addDifference("name", expected.getName(), actual.getName());
        }
        
        // Compare dates
        if (!actual.getDate().equals(expected.getDate())) {
            result.addDifference("date", expected.getDate(), actual.getDate());
        }
        
        return result;
    }
    
    private boolean compareDecimal(BigDecimal a, BigDecimal b, double tolerance) {
        return a.subtract(b).abs().doubleValue() <= tolerance;
    }
}

4. End-to-End Testing

Full Workflow Testing

@SpringBootTest
@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
class OrderWorkflowE2ETest {
    
    @Test
    @Order(1)
    void test_completeOrderWorkflow() {
        // Step 1: Create order
        OrderRequest request = new OrderRequest();
        request.setCustomerId("CUST001");
        request.addItem("ITEM001", 2);
        
        Order order = orderService.createOrder(request);
        assertNotNull(order.getId());
        
        // Step 2: Process payment
        PaymentResult payment = paymentService.process(order);
        assertEquals(PaymentStatus.APPROVED, payment.getStatus());
        
        // Step 3: Ship order
        ShipmentResult shipment = shippingService.ship(order);
        assertEquals(ShipmentStatus.SHIPPED, shipment.getStatus());
        
        // Step 4: Verify final state
        Order finalOrder = orderService.getOrder(order.getId());
        assertEquals(OrderStatus.COMPLETED, finalOrder.getStatus());
    }
}

5. Performance Testing

Baseline Comparison

@State(Scope.Thread)
@BenchmarkMode(Mode.Throughput)
@OutputTimeUnit(TimeUnit.SECONDS)
public class PerformanceBenchmark {
    
    private List<Record> testData;
    
    @Setup
    public void setup() {
        testData = generateTestData(10000);
    }
    
    @Benchmark
    public void testJavaImplementation() {
        javaService.process(testData);
    }
    
    // Compare with baseline from COBOL system
    // Target: >= 90% of COBOL throughput
}

Load Testing

@SpringBootTest
class LoadTest {
    
    @Test
    void testConcurrentProcessing() throws InterruptedException {
        int threadCount = 10;
        int iterationsPerThread = 100;
        ExecutorService executor = Executors.newFixedThreadPool(threadCount);
        
        List<Future<?>> futures = new ArrayList<>();
        
        for (int i = 0; i < threadCount; i++) {
            futures.add(executor.submit(() -> {
                for (int j = 0; j < iterationsPerThread; j++) {
                    orderService.processOrder(createTestOrder());
                }
            }));
        }
        
        // Wait for completion
        for (Future<?> future : futures) {
            future.get();
        }
        
        executor.shutdown();
        
        // Verify results
        long totalOrders = orderRepository.count();
        assertEquals(threadCount * iterationsPerThread, totalOrders);
    }
}

6. Data Migration Testing

Data Validation

@SpringBootTest
class DataMigrationTest {
    
    @Test
    void validateMigratedCustomers() {
        // Load from legacy system
        List<LegacyCustomer> legacyCustomers = legacyDataSource.getAllCustomers();
        
        // Compare with migrated data
        for (LegacyCustomer legacy : legacyCustomers) {
            Customer migrated = customerRepo.findById(legacy.getId())
                .orElseThrow(() -> new AssertionError("Customer not migrated: " + legacy.getId()));
            
            assertEquals(legacy.getName().trim(), migrated.getName());
            assertEquals(legacy.getBalance(), migrated.getBalance());
            // ... more assertions
        }
    }
    
    @Test
    void verifyDataIntegrity() {
        // Check referential integrity
        List<Order> orders = orderRepo.findAll();
        for (Order order : orders) {
            assertTrue(customerRepo.existsById(order.getCustomerId()),
                "Order references non-existent customer: " + order.getId());
        }
    }
}

7. Regression Testing

Automated Regression Suite

@SpringBootTest
@Tag("regression")
class RegressionTestSuite {
    
    @Nested
    @DisplayName("Customer Management")
    class CustomerTests {
        
        @Test
        void testCreateCustomer() { /* ... */ }
        
        @Test
        void testUpdateCustomer() { /* ... */ }
        
        @Test
        void testDeleteCustomer() { /* ... */ }
    }
    
    @Nested
    @DisplayName("Order Processing")
    class OrderTests {
        // ... order tests
    }
}

Test Data Strategy

Using Production-Like Data

@TestConfiguration
public class TestDataConfig {
    
    @Bean
    public TestDataGenerator testDataGenerator() {
        return TestDataGenerator.builder()
            .withCustomerCount(1000)
            .withOrderCount(5000)
            .withProductCount(100)
            .withRealisticDistribution(true)
            .build();
    }
}

Anonymizing Production Data

public class DataAnonymizer {
    
    public Customer anonymize(Customer customer) {
        Customer anonymized = new Customer();
        anonymized.setId(customer.getId());
        anonymized.setName(generateFakeName());
        anonymized.setEmail(generateFakeEmail());
        anonymized.setBalance(customer.getBalance()); // Keep financial data
        return anonymized;
    }
}

Test Automation

CI/CD Integration

# .github/workflows/test.yml
name: Migration Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v2
      
      - name: Set up JDK
        uses: actions/setup-java@v2
        with:
          java-version: '17'
      
      - name: Run Unit Tests
        run: ./mvnw test
      
      - name: Run Integration Tests
        run: ./mvnw verify -P integration-tests
      
      - name: Run E2E Tests
        run: ./mvnw verify -P e2e-tests
      
      - name: Generate Coverage Report
        run: ./mvnw jacoco:report

Coverage Goals

• Unit Test Coverage: ≥ 80% line coverage
• Integration Test Coverage: All APIs and database operations
• E2E Coverage: All critical business workflows
• Parallel Run Coverage: 100% of transactions for 30 days

Test Documentation

Test Case Template

/**
 * Test: Calculate bonus for senior employee
 * 
 * Legacy Reference: PROGRAM_NAME.cbl, paragraph CALCULATE-BONUS
 * 
 * Business Rule: Employees with >10 years service get 15% bonus
 * 
 * Test Data:
 * - Years of service: 12
 * - Salary: $50,000
 * 
 * Expected Result: $7,500 bonus
 */
@Test
void testCalculateBonus_seniorEmployee() {
    // Test implementation
}

Monitoring Test Results

@ExtendWith(TestResultLogger.class)
class MonitoredTest {
    
    @Test
    void testWithMonitoring() {
        // Test execution metrics logged automatically
    }
}

class TestResultLogger implements TestWatcher {
    
    @Override
    public void testSuccessful(ExtensionContext context) {
        log.info("Test passed: {}", context.getDisplayName());
        metricsService.recordTestSuccess(context);
    }
    
    @Override
    public void testFailed(ExtensionContext context, Throwable cause) {
        log.error("Test failed: {}", context.getDisplayName(), cause);
        metricsService.recordTestFailure(context, cause);
    }
}

Checklist

• [ ] Unit tests for all business logic methods
• [ ] Integration tests for data access
• [ ] E2E tests for critical workflows
• [ ] Performance tests vs. baseline
• [ ] Parallel run for 30 days minimum
• [ ] Data migration validation
• [ ] Regression suite automated
• [ ] Test data anonymized
• [ ] CI/CD pipeline configured
• [ ] Coverage reports generated
• [ ] Test documentation complete

Transaction Handling in Migrated Applications

This document explains how to handle transactions when migrating from CICS/mainframe environments to Java.

Overview

COBOL programs running under CICS or IMS use implicit transaction management. In Java, transactions must be explicitly managed using appropriate frameworks and patterns.

CICS Transaction Concepts

CICS Transaction Model

Key Characteristics:

• Implicit transaction boundaries
• SYNCPOINT for explicit commits
• Automatic rollback on ABEND
• Resource coordination (files, databases, queues)
• Conversational vs. pseudo-conversational

Common CICS Commands

EXEC CICS SYNCPOINT END-EXEC.
EXEC CICS SYNCPOINT ROLLBACK END-EXEC.
EXEC CICS LINK PROGRAM(name) END-EXEC.
EXEC CICS RETURN END-EXEC.

Java Transaction Patterns

1. Programmatic Transactions

For simple cases, use JDBC transactions:

Connection conn = dataSource.getConnection();
try {
    conn.setAutoCommit(false);
    
    // Perform operations
    updateCustomer(conn, customer);
    insertOrder(conn, order);
    
    conn.commit();
} catch (Exception e) {
    conn.rollback();
    throw e;
} finally {
    conn.close();
}

2. Declarative Transactions (Spring)

For most migrations, use Spring's declarative approach:

@Service
@Transactional
public class OrderService {
    
    @Autowired
    private CustomerRepository customerRepo;
    
    @Autowired
    private OrderRepository orderRepo;
    
    @Transactional
    public void processOrder(OrderRequest request) {
        // All operations in one transaction
        Customer customer = customerRepo.findById(request.getCustomerId())
            .orElseThrow(() -> new CustomerNotFoundException());
        
        Order order = new Order();
        order.setCustomer(customer);
        order.setAmount(request.getAmount());
        
        orderRepo.save(order);
        
        // Transaction commits automatically on success
        // Rolls back on unchecked exceptions
    }
    
    @Transactional(readOnly = true)
    public Order getOrder(Long orderId) {
        // Read-only optimization
        return orderRepo.findById(orderId)
            .orElseThrow(() -> new OrderNotFoundException());
    }
}

3. Transaction Propagation

Map CICS patterns to Spring propagation:

// CICS: New transaction (like EXEC CICS LINK SYNCONRETURN)
@Transactional(propagation = Propagation.REQUIRES_NEW)
public void processInNewTransaction() {
    // Runs in separate transaction
}

// CICS: Join existing transaction
@Transactional(propagation = Propagation.REQUIRED)
public void processInCurrentTransaction() {
    // Joins existing or creates new
}

// CICS: No transaction coordination
@Transactional(propagation = Propagation.NOT_SUPPORTED)
public void processWithoutTransaction() {
    // Suspends any existing transaction
}

4. Isolation Levels

Match CICS resource locking to SQL isolation:

// CICS UPDATE (exclusive lock)
@Transactional(isolation = Isolation.SERIALIZABLE)
public void updateWithExclusiveLock() {
    // Prevents concurrent access
}

// CICS READ (shared lock)
@Transactional(isolation = Isolation.REPEATABLE_READ)
public void readWithConsistency() {
    // Consistent reads within transaction
}

Migration Patterns

Pattern 1: Batch SYNCPOINT

COBOL/CICS:

PERFORM VARYING WS-COUNTER FROM 1 BY 1
    UNTIL WS-COUNTER > 1000
    
    PERFORM PROCESS-RECORD
    
    IF WS-COUNTER = 100
        EXEC CICS SYNCPOINT END-EXEC
        MOVE 0 TO WS-COUNTER
    END-IF
END-PERFORM.

Java:

@Service
public class BatchProcessor {
    
    @Autowired
    private TransactionTemplate transactionTemplate;
    
    public void processBatch(List<Record> records) {
        int batchSize = 100;
        List<Record> batch = new ArrayList<>();
        
        for (Record record : records) {
            batch.add(record);
            
            if (batch.size() >= batchSize) {
                processBatchInTransaction(new ArrayList<>(batch));
                batch.clear();
            }
        }
        
        if (!batch.isEmpty()) {
            processBatchInTransaction(batch);
        }
    }
    
    private void processBatchInTransaction(List<Record> batch) {
        transactionTemplate.execute(status -> {
            batch.forEach(this::processRecord);
            return null;
        });
    }
}

Pattern 2: Compensating Transactions

Challenge: Multi-system transactions without XA Solution: Saga pattern

@Service
public class OrderSagaService {
    
    public void processOrder(OrderRequest request) {
        String sagaId = UUID.randomUUID().toString();
        
        try {
            // Step 1: Reserve inventory
            String reservationId = inventoryService.reserve(request.getItems());
            
            // Step 2: Charge payment
            String paymentId = paymentService.charge(request.getPayment());
            
            // Step 3: Create order
            Order order = orderService.create(request, reservationId, paymentId);
            
            // Success - commit all
            inventoryService.confirm(reservationId);
            paymentService.confirm(paymentId);
            
        } catch (Exception e) {
            // Compensate in reverse order
            if (paymentId != null) {
                paymentService.refund(paymentId);
            }
            if (reservationId != null) {
                inventoryService.release(reservationId);
            }
            throw new OrderProcessingException("Order failed", e);
        }
    }
}

Pattern 3: Distributed Transactions (XA)

For true 2-phase commit across resources:

@Configuration
public class XAConfig {
    
    @Bean
    public PlatformTransactionManager transactionManager() {
        JtaTransactionManager tm = new JtaTransactionManager();
        tm.setTransactionManager(atomikosTransactionManager());
        return tm;
    }
    
    @Bean
    public DataSource xaDataSource1() {
        AtomikosDataSourceBean ds = new AtomikosDataSourceBean();
        ds.setUniqueResourceName("db1");
        ds.setXaDataSourceClassName("org.postgresql.xa.PGXADataSource");
        // ... configuration
        return ds;
    }
    
    @Bean
    public DataSource xaDataSource2() {
        AtomikosDataSourceBean ds = new AtomikosDataSourceBean();
        ds.setUniqueResourceName("db2");
        // ... configuration
        return ds;
    }
}

@Service
public class DistributedService {
    
    @Transactional
    public void updateBothDatabases() {
        // Both updates in same XA transaction
        db1Repository.update(data1);
        db2Repository.update(data2);
        // Atomikos coordinates 2PC
    }
}

Error Handling

CICS ABEND → Java Exception

COBOL/CICS:

IF ERROR-CONDITION
    EXEC CICS ABEND ABCODE('APPL') END-EXEC
END-IF.

Java:

@Transactional
public void process() {
    if (errorCondition) {
        // Unchecked exception triggers rollback
        throw new ApplicationException("APPL");
    }
}

// For checked exceptions that should rollback
@Transactional(rollbackFor = BusinessException.class)
public void processWithChecked() throws BusinessException {
    if (errorCondition) {
        throw new BusinessException("Error occurred");
    }
}

Testing Strategies

Unit Testing with Transactions

@SpringBootTest
@Transactional
class OrderServiceTest {
    
    @Autowired
    private OrderService orderService;
    
    @Test
    @Rollback  // Default behavior
    void testOrderProcessing() {
        // Test runs in transaction
        // Automatically rolled back after test
        Order order = orderService.processOrder(request);
        assertNotNull(order.getId());
    }
    
    @Test
    @Commit  // Explicitly commit for verification
    void testOrderPersistence() {
        Order order = orderService.processOrder(request);
        // Verify in separate transaction
    }
}

Integration Testing

@SpringBootTest
@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_EACH_TEST_METHOD)
class TransactionIntegrationTest {
    
    @Test
    void testRollbackOnError() {
        assertThrows(BusinessException.class, () -> {
            orderService.processInvalidOrder(invalidRequest);
        });
        
        // Verify rollback
        assertFalse(orderRepository.findById(orderId).isPresent());
    }
}

Configuration Best Practices

Spring Boot Configuration

spring:
  datasource:
    hikari:
      auto-commit: false
      maximum-pool-size: 20
      connection-timeout: 30000
  jpa:
    properties:
      hibernate:
        connection:
          isolation: 2  # READ_COMMITTED
        jdbc:
          batch_size: 50
        order_inserts: true
        order_updates: true

Transaction Manager Tuning

@Configuration
public class TransactionConfig {
    
    @Bean
    public PlatformTransactionManager transactionManager(EntityManagerFactory emf) {
        JpaTransactionManager tm = new JpaTransactionManager(emf);
        tm.setDefaultTimeout(30);  // 30 seconds
        return tm;
    }
}

Monitoring and Debugging

Enable Transaction Logging

logging:
  level:
    org.springframework.transaction: DEBUG
    org.springframework.orm.jpa: DEBUG
    org.hibernate.engine.transaction: DEBUG

Transaction Events

@Component
public class TransactionEventListener {
    
    @TransactionalEventListener(phase = TransactionPhase.BEFORE_COMMIT)
    public void beforeCommit(OrderCreatedEvent event) {
        log.info("About to commit order: {}", event.getOrderId());
    }
    
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMPLETION)
    public void afterCompletion(OrderCreatedEvent event) {
        log.info("Transaction completed for order: {}", event.getOrderId());
    }
}

Common Issues and Solutions

Issue: Lost Updates

Problem: Concurrent modifications Solution: Use optimistic or pessimistic locking

@Entity
public class Account {
    @Id
    private Long id;
    
    @Version  // Optimistic locking
    private Long version;
    
    private BigDecimal balance;
}

// Or pessimistic locking
@Lock(LockModeType.PESSIMISTIC_WRITE)
Account findById(Long id);

Issue: Long-Running Transactions

Problem: Locks held too long Solution: Minimize transaction scope

// Bad: Transaction spans user interaction
@Transactional
public void processOrderBad(OrderRequest request) {
    Order order = createOrder(request);
    sendEmail(order);  // Slow!
    updateInventory(order);
}

// Good: Transaction only for data operations
public void processOrderGood(OrderRequest request) {
    Order order;
    
    // Transaction scope
    order = transactionTemplate.execute(status -> {
        Order o = createOrder(request);
        updateInventory(o);
        return o;
    });
    
    // Outside transaction
    sendEmail(order);
}

Migration Checklist

• [ ] Identify all SYNCPOINT locations
• [ ] Map CICS transaction boundaries
• [ ] Determine isolation requirements
• [ ] Plan for distributed transactions
• [ ] Define compensating actions
• [ ] Implement error handling
• [ ] Add transaction monitoring
• [ ] Test rollback scenarios
• [ ] Performance test with load
• [ ] Document transaction flows