# 📐 Java Architecture Patterns

![Java Architecture Banner](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/java-architecture-banner.png)

This page documents the shared architectural patterns used across all Java projects in this monorepo. These patterns also align with Patrick's professional work on the ADP Germany Paisy payroll system.

## JSF MVC Pattern

All projects use JavaServer Faces (JSF) with the MVC pattern:

```
Browser (HTTP) → FacesServlet → XHTML View (Facelets)
                                      │
                                      ▼
                              CDI Backing Bean (@Named)
                                      │
                                      ▼
                              Service Layer (EJB / CDI)
                                      │
                                      ▼
                              JPA Repository / EntityManager
                                      │
                                      ▼
                              Database (MySQL / H2)
```

## JPA Entity Mapping

Standard JPA annotation patterns used across projects:

```java
@Entity
@Table(name = "users")
public class User implements Serializable {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(name = "username", nullable = false, unique = true)
    private String username;
    
    @OneToMany(mappedBy = "user", cascade = CascadeType.ALL, fetch = FetchType.LAZY)
    private List<Order> orders = new ArrayList<>();
    
    // getters/setters
}
```

## Backing Bean Pattern

CDI backing beans power the JSF views:

```java
@Named
@ViewScoped  // or @SessionScoped / @RequestScoped
public class UserBean implements Serializable {

    @Inject
    private UserService userService;
    
    private User currentUser;
    
    public String login() {
        currentUser = userService.authenticate(username, password);
        return currentUser != null ? "/user/welcome?faces-redirect=true" : null;
    }
    
    // getters/setters
}
```

## Security Layers

### Legacy: JAAS (wellmann-shop)

```xml
<!-- web.xml -->
<security-constraint>
    <web-resource-collection>
        <web-resource-name>Admin Pages</web-resource-name>
        <url-pattern>/admin/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>admin</role-name>
    </auth-constraint>
</security-constraint>
```

### Modern: Soteria / Jakarta Security (mss-failsafe)

```java
@ApplicationScoped
public class ApplicationSecurityConfig implements HttpAuthenticationMechanism {
    // Soteria CDI-based authentication
}
```

## Maven Multi-Module Pattern (mss-failsafe)

```xml
<!-- Parent pom.xml -->
<modules>
    <module>mssfailsafe.datalayer</module>
    <module>userdata</module>
    <module>userManagement</module>
</modules>

<!-- Dependency ordering: datalayer → userdata → userManagement -->
```

## XHTML Facelets Templating

```xml
<!-- Template: resources/layout/template.xhtml -->
<h:body>
    <ui:insert name="content">Default Content</ui:insert>
</h:body>

<!-- Page using template -->
<ui:composition template="/resources/layout/template.xhtml">
    <ui:define name="content">
        <p:dataTable var="item" value="#{bean.items}">
            <p:column headerText="Name">#{item.name}</p:column>
        </p:dataTable>
    </ui:define>
</ui:composition>
```

## Deployment Descriptor Pattern

All projects target JBoss/WildFly with consistent descriptor files:

| File | Purpose |
|---|---|
| `WEB-INF/web.xml` | Servlet config, security constraints, welcome files |
| `WEB-INF/jboss-web.xml` | Context root, security domain mapping |
| `WEB-INF/jboss-app.xml` | JBoss application descriptor |
| `META-INF/persistence.xml` | JPA datasource JNDI reference |

## persistence.xml Pattern

```xml
<persistence-unit name="mss-failsafe-PU" transaction-type="JTA">
    <jta-data-source>java:jboss/datasources/MySQLDS</jta-data-source>
    <properties>
        <property name="eclipselink.ddl-generation" value="create-tables"/>
        <property name="eclipselink.logging.level" value="FINE"/>
    </properties>
</persistence-unit>
```

## Patrick's Java Specializations

Based on professional and homelab experience:

| Domain | Depth | Notes |
|---|---|---|
| JPA / EclipseLink | ⭐⭐⭐⭐⭐ | Authored custom annotation parsers |
| JSF / PrimeFaces | ⭐⭐⭐⭐⭐ | Built wellmann-shop solo |
| JAXB | ⭐⭐⭐⭐ | XML binding for payroll formats |
| Maven | ⭐⭐⭐⭐ | Multi-module, plugins |
| Jakarta EE | ⭐⭐⭐⭐ | CDI, Security, JTA |
| Spring Boot | ⭐⭐⭐ | CannaManage SaaS target stack |