pi_mcps/docs/wiki/pages/Java-Architecture.md

📐 Java Architecture Patterns

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:

@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:

@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)

<!-- 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)

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

Maven Multi-Module Pattern (mss-failsafe)

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

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

XHTML Facelets Templating

<!-- 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

<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