Copilot instructions

1---
2applyTo: "src/main/java/**/*.java"
3---
4 
5## Context
6 
7This instruction file applies to legacy Java modules built on Spring 4.x or 5.x using the traditional XML + annotation configuration model. These modules are servlet-based, use `JdbcTemplate` for data access (not Spring Data JPA), and are packaged as WAR files deployed to an application server (e.g., IBM WebSphere, JBoss EAP, Apache Tomcat). The Java baseline is Java 8 or Java 11. Do not apply Spring Boot auto-configuration assumptions to this code.
8 
9---
10 
11## Coding Standards
12 
13- **Java version:** Java 8 or 11 — do not use records, sealed classes, text blocks, `var` (Java 11 only with care), or any feature requiring Java 14+
14- **Spring version:** Spring 4.x or 5.x — use `org.springframework` imports, not `org.springframework.boot`
15- **No Spring Boot:** Do not generate `@SpringBootApplication`, `@EnableAutoConfiguration`, or any `spring-boot` dependency references
16- **No Spring Data JPA:** Use `JdbcTemplate` or `NamedParameterJdbcTemplate` for all data access
17- **XML config awareness:** Be aware that `applicationContext.xml` and `dispatcher-servlet.xml` may define beans; do not duplicate them in Java config without understanding the existing XML
18- **Transaction management:** Use `@Transactional` with explicit `propagation` and `rollbackFor` — never rely on defaults silently
19- **Constructor or setter injection:** Field injection is legacy-acceptable but constructor injection is preferred for new code
20- **Logging:** SLF4J + Logback (or Log4j2) — never `System.out.println`
21 
22---
23 
24## Preferred Patterns
25 
26### Spring MVC Controller (Legacy)
27 
28```java
29@Controller
30@RequestMapping("/customers")
31public class CustomerController {
32 
33    private static final Logger log = LoggerFactory.getLogger(CustomerController.class);
34 
35    private final CustomerService customerService;
36 
37    public CustomerController(CustomerService customerService) {
38        this.customerService = customerService;
39    }
40 
41    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
42    public String getCustomer(@PathVariable Long id, Model model) {
43        log.debug("Fetching customer with id {}", id);
44        model.addAttribute("customer", customerService.findById(id));
45        return "customer/detail";
46    }
47 
48    @RequestMapping(value = "/", method = RequestMethod.POST)
49    public String createCustomer(@Valid @ModelAttribute CustomerForm form,
50                                 BindingResult result, RedirectAttributes redirect) {
51        if (result.hasErrors()) {
52            return "customer/form";
53        }
54        customerService.create(form);
55        redirect.addFlashAttribute("message", "Customer created successfully");
56        return "redirect:/customers/";
57    }
58}
59```
60 
61### REST Endpoint (Legacy Spring MVC)
62 
63```java
64@Controller
65@RequestMapping("/api/orders")
66public class OrderRestController {
67 
68    private final OrderService orderService;
69 
70    public OrderRestController(OrderService orderService) {
71        this.orderService = orderService;
72    }
73 
74    @RequestMapping(value = "/{id}", method = RequestMethod.GET,
75                    produces = MediaType.APPLICATION_JSON_VALUE)
76    @ResponseBody
77    public OrderDto getOrder(@PathVariable Long id) {
78        return orderService.findById(id);
79    }
80}
81```
82 
83### JdbcTemplate Data Access
84 
85```java
86@Repository
87public class OrderJdbcRepository {
88 
89    private static final Logger log = LoggerFactory.getLogger(OrderJdbcRepository.class);
90 
91    private final NamedParameterJdbcTemplate jdbc;
92 
93    public OrderJdbcRepository(NamedParameterJdbcTemplate jdbc) {
94        this.jdbc = jdbc;
95    }
96 
97    public Optional<Order> findById(Long id) {
98        String sql = "SELECT o.id, o.customer_id, o.status, o.created_at " +
99                     "FROM SCHEMA.ORDERS o WHERE o.id = :id";
100        MapSqlParameterSource params = new MapSqlParameterSource("id", id);
101        try {
102            Order order = jdbc.queryForObject(sql, params, new OrderRowMapper());
103            return Optional.ofNullable(order);
104        } catch (EmptyResultDataAccessException e) {
105            log.debug("Order {} not found", id);
106            return Optional.empty();
107        }
108    }
109}
110```
111 
112### Transaction Management
113 
114```java
115@Service
116@Transactional(readOnly = true)
117public class OrderService {
118 
119    @Transactional(propagation = Propagation.REQUIRED, rollbackFor = Exception.class)
120    public Order createOrder(CreateOrderRequest request) {
121        // transactional write operation
122    }
123 
124    @Transactional(propagation = Propagation.REQUIRES_NEW, rollbackFor = Exception.class)
125    public void processPayment(Long orderId) {
126        // runs in its own transaction — outer transaction is suspended
127    }
128}
129```
130 
131### Exception Handling (Legacy HandlerExceptionResolver)
132 
133```java
134@Component
135public class GlobalExceptionHandler implements HandlerExceptionResolver {
136 
137    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);
138 
139    @Override
140    public ModelAndView resolveException(HttpServletRequest request,
141                                         HttpServletResponse response,
142                                         Object handler, Exception ex) {
143        log.error("Unhandled exception on {} {}", request.getMethod(), request.getRequestURI(), ex);
144        response.setStatus(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
145        return new ModelAndView("error/500");
146    }
147}
148```
149 
150### Maven Multi-Module Structure
151 
152```xml
153<!-- Parent pom.xml -->
154<project>
155    <groupId>com.example</groupId>
156    <artifactId>my-app</artifactId>
157    <version>1.0.0-SNAPSHOT</version>
158    <packaging>pom</packaging>
159 
160    <modules>
161        <module>my-app-core</module>
162        <module>my-app-web</module>
163        <module>my-app-service</module>
164    </modules>
165 
166    <dependencyManagement>
167        <dependencies>
168            <!-- Centralize versions here -->
169        </dependencies>
170    </dependencyManagement>
171</project>
172```
173 
174### MapStruct Mapper (Legacy)
175 
176```java
177@Mapper(componentModel = "spring")
178public interface CustomerMapper {
179 
180    CustomerDto toDto(Customer customer);
181 
182    Customer toEntity(CustomerDto dto);
183 
184    List<CustomerDto> toDtoList(List<Customer> customers);
185}
186```
187 
188---
189 
190## Anti-Patterns — Do NOT Generate
191 
192```java
193// WRONG: Spring Boot annotations in a legacy module
194@SpringBootApplication
195public class MyApp { ... }
196 
197// WRONG: Spring Data JPA in a JdbcTemplate project
198public interface OrderRepository extends JpaRepository<Order, Long> { ... }
199 
200// WRONG: javax.persistence imports where JdbcTemplate is the pattern
201import javax.persistence.Entity;
202 
203// WRONG: @Autowired field injection (prefer constructor injection)
204@Autowired
205private CustomerService customerService;
206 
207// WRONG: raw JDBC Statement with string concatenation (SQL injection risk)
208Statement stmt = conn.createStatement();
209stmt.execute("SELECT * FROM ORDERS WHERE ID = " + id);
210 
211// WRONG: new Java features incompatible with Java 8 target
212record Customer(Long id, String name) {}  // Java 16+ — not available
213 
214// WRONG: silently swallowing exceptions
215try {
216    service.process(request);
217} catch (Exception e) {
218    // do nothing
219}
220```
221 
222---
223 
224## Dependencies & Versions
225 
226| Library | Version | Notes |
227|---------|---------|-------|
228| Spring Framework | 4.3.x or 5.3.x | `org.springframework` |
229| Spring Security | 4.x or 5.x | `WebSecurityConfigurerAdapter` still valid |
230| JdbcTemplate | (with Spring) | `org.springframework.jdbc` |
231| MapStruct | 1.5.x | Annotation processor — declare in `<build><plugins>` |
232| Jackson | 2.x | `com.fasterxml.jackson` |
233| SLF4J + Logback | 1.7.x / 1.2.x | `org.slf4j`, `ch.qos.logback` |
234| Java | 8 or 11 | No records, no sealed classes |
235 
236---
237 
238## Test Conventions
239 
240- Use `@RunWith(SpringJUnit4ClassRunner.class)` or `@ExtendWith(SpringExtension.class)` (JUnit 5)
241- Spring MVC tests: `MockMvc` with `standaloneSetup` or `@WebMvcTest`
242- JdbcTemplate tests: Use an embedded H2 database with a test schema script
243- Test configuration: Use `@ContextConfiguration` pointing to test-specific XML or `@TestConfiguration` classes
244- Name unit tests `*Test.java`, integration tests `*IT.java`
245- Avoid starting the full application context in unit tests — use `Mockito` mocks
246