Structural Design Patterns in Java: Complete Guide with Spring Boot Scenarios

Structural design patterns address one of the most persistent challenges in enterprise Java development: how to compose objects and classes into larger, flexible structures without creating brittle inheritance hierarchies or tight coupling. The GoF's seven structural patterns — Adapter, Decorator, Proxy, Facade, Composite, Bridge, and Flyweight — appear throughout every mature Spring Boot application, often without developers recognizing them. This guide walks through each pattern with production-grade Java code, real Spring Boot scenarios, and practical guidance on when to use each one.

• Adapter bridges incompatible interfaces — use it for legacy integration without touching existing code.
• Decorator adds cross-cutting behavior (logging, auth) at runtime — the basis of Spring AOP.
• Proxy controls access and adds lazy-loading or caching — Spring's @Transactional is a proxy.
• Facade hides subsystem complexity behind a single entry point — your @Service orchestrators.
• Composite treats trees and leaves uniformly — ideal for category hierarchies and menus.
• Bridge decouples abstraction from implementation — prevents subclass explosion in report generators.
• Flyweight shares intrinsic state to reduce memory — critical for rendering thousands of map markers.

Table of Contents

1. What Are Structural Patterns?
2. Adapter Pattern — Legacy Integration
3. Decorator Pattern — Adding Behavior Dynamically
4. Proxy Pattern — Controlled Access
5. Facade Pattern — Simplifying Complex Systems
6. Composite Pattern — Tree Structures
7. Bridge Pattern — Abstraction vs Implementation
8. Flyweight Pattern — Memory Optimization
9. Spring Boot Real-World Uses
10. Comparison Table & When to Use Each

// Modern interface all services expect
public interface PaymentGateway {
    PaymentResult charge(String customerId, Money amount, String currency);
    void refund(String transactionId, Money amount);
}

// Legacy class — cannot be modified (third-party or acquired code)
public class LegacyStripeClient {
    public StripeCharge createCharge(long amountCents, String curr, String custId) {
        // legacy Stripe v1 API call
        return new StripeCharge(UUID.randomUUID().toString(), amountCents, "succeeded");
    }
    public void issueRefund(String chargeId, long amountCents) {
        // legacy refund logic
    }
}

// Adapter: wraps legacy, exposes modern interface
@Component
public class LegacyStripeAdapter implements PaymentGateway {

    private final LegacyStripeClient legacyClient;

    public LegacyStripeAdapter(LegacyStripeClient legacyClient) {
        this.legacyClient = legacyClient;
    }

    @Override
    public PaymentResult charge(String customerId, Money amount, String currency) {
        long cents = amount.getAmount().multiply(BigDecimal.valueOf(100)).longValue();
        StripeCharge charge = legacyClient.createCharge(cents, currency, customerId);
        return new PaymentResult(charge.getId(), charge.getStatus());
    }

    @Override
    public void refund(String transactionId, Money amount) {
        long cents = amount.getAmount().multiply(BigDecimal.valueOf(100)).longValue();
        legacyClient.issueRefund(transactionId, cents);
    }
}

// Client — only knows PaymentGateway, unaware of legacy implementation
@Service
@RequiredArgsConstructor
public class CheckoutService {
    private final PaymentGateway paymentGateway; // Spring injects LegacyStripeAdapter

    public OrderConfirmation checkout(Cart cart, String customerId) {
        PaymentResult result = paymentGateway.charge(customerId, cart.total(), "USD");
        return new OrderConfirmation(result.getTransactionId());
    }
}

• Zero changes to legacy code — safe for acquired or third-party libraries.
• Clients are fully decoupled from the legacy implementation detail.
• Swapping to a new native implementation later requires only removing the adapter.
• Spring's @Component makes adapter registration automatic via classpath scanning.

// Component interface
public interface RequestHandler {
    ApiResponse handle(ApiRequest request);
}

// Core handler — pure business logic, no cross-cutting concerns
@Component
public class OrderRequestHandler implements RequestHandler {
    @Override
    public ApiResponse handle(ApiRequest request) {
        // process order business logic
        return ApiResponse.ok("Order placed: " + request.getOrderId());
    }
}

// Decorator 1: logging
public class LoggingDecorator implements RequestHandler {
    private final RequestHandler delegate;
    private static final Logger log = LoggerFactory.getLogger(LoggingDecorator.class);

    public LoggingDecorator(RequestHandler delegate) {
        this.delegate = delegate;
    }

    @Override
    public ApiResponse handle(ApiRequest request) {
        log.info("Handling request: orderId={}", request.getOrderId());
        long start = System.currentTimeMillis();
        ApiResponse response = delegate.handle(request);
        log.info("Request completed in {}ms, status={}", System.currentTimeMillis() - start, response.getStatus());
        return response;
    }
}

// Decorator 2: authentication
public class AuthDecorator implements RequestHandler {
    private final RequestHandler delegate;
    private final TokenValidator tokenValidator;

    public AuthDecorator(RequestHandler delegate, TokenValidator tokenValidator) {
        this.delegate = delegate;
        this.tokenValidator = tokenValidator;
    }

    @Override
    public ApiResponse handle(ApiRequest request) {
        if (!tokenValidator.isValid(request.getAuthToken())) {
            return ApiResponse.unauthorized("Invalid token");
        }
        return delegate.handle(request);
    }
}

// Composition — build the pipeline in a @Configuration class
@Configuration
public class HandlerConfig {
    @Bean
    public RequestHandler requestHandler(OrderRequestHandler core, TokenValidator tokenValidator) {
        // outer → AuthDecorator → LoggingDecorator → core handler
        return new AuthDecorator(new LoggingDecorator(core), tokenValidator);
    }
}

• Each decorator has a single responsibility — easy to unit-test in isolation.
• Concerns can be combined and reordered without modifying existing classes (OCP).
• Avoids deep inheritance hierarchies (no LoggingAuthOrderHandler extends ...).
• Runtime composition means different clients can get different decorator stacks.

// Subject interface
public interface UserService {
    UserProfile getProfile(UUID userId);
    void deleteUser(UUID userId);   // admin only
    List<UserProfile> listAllUsers(); // expensive — lazy-load
}

// Real subject
@Service
public class UserServiceImpl implements UserService {
    private final UserRepository userRepository;

    @Override
    public UserProfile getProfile(UUID userId) {
        return userRepository.findById(userId).orElseThrow();
    }

    @Override
    public void deleteUser(UUID userId) {
        userRepository.deleteById(userId);
    }

    @Override
    public List<UserProfile> listAllUsers() {
        return userRepository.findAll(); // potentially thousands of records
    }
}

// Protection + Virtual Proxy
@Component
@Primary  // Spring injects this wherever UserService is requested
public class UserServiceProxy implements UserService {

    private final UserServiceImpl realService;
    private final SecurityContext securityContext;
    private List<UserProfile> cachedUserList; // lazy cache

    public UserServiceProxy(UserServiceImpl realService, SecurityContext securityContext) {
        this.realService = realService;
        this.securityContext = securityContext;
    }

    @Override
    public UserProfile getProfile(UUID userId) {
        return realService.getProfile(userId); // no restriction
    }

    @Override
    public void deleteUser(UUID userId) {
        if (!securityContext.currentUser().hasRole("ADMIN")) {
            throw new AccessDeniedException("Admin role required to delete users");
        }
        cachedUserList = null; // invalidate cache
        realService.deleteUser(userId);
    }

    @Override
    public List<UserProfile> listAllUsers() {
        if (cachedUserList == null) {           // lazy initialization
            cachedUserList = realService.listAllUsers();
        }
        return cachedUserList;
    }
}

• Access control and lazy loading added transparently — client code unchanged.
• Use @Primary to make Spring inject the proxy everywhere automatically.
• Proxies are independently testable — inject mock real-service and mock security context.
• Supports cache invalidation, audit logging, or circuit-breaking at the proxy layer.

// Four independent subsystem services
@Service public class InventoryService {
    public ReservationId reserve(UUID productId, int qty) { /* ... */ return new ReservationId(); }
    public void release(ReservationId reservationId) { /* ... */ }
}

@Service public class PaymentService {
    public PaymentResult charge(String customerId, Money amount) { /* ... */ return new PaymentResult(); }
}

@Service public class ShippingService {
    public ShippingLabel createLabel(Order order) { /* ... */ return new ShippingLabel(); }
}

@Service public class NotificationService {
    public void sendOrderConfirmation(Order order, ShippingLabel label) { /* ... */ }
}

// Facade — single entry point for the entire order placement workflow
@Service
@RequiredArgsConstructor
public class OrderFacade {

    private final InventoryService inventoryService;
    private final PaymentService paymentService;
    private final ShippingService shippingService;
    private final NotificationService notificationService;
    private final OrderRepository orderRepository;

    @Transactional
    public OrderConfirmation placeOrder(PlaceOrderRequest request) {
        // 1. Reserve inventory (throws if out of stock)
        ReservationId reservation = inventoryService.reserve(
                request.getProductId(), request.getQuantity());
        try {
            // 2. Charge payment
            PaymentResult payment = paymentService.charge(
                    request.getCustomerId(), request.getTotal());

            // 3. Persist order
            Order order = orderRepository.save(Order.from(request, payment));

            // 4. Create shipping label
            ShippingLabel label = shippingService.createLabel(order);

            // 5. Notify customer (async — fire and forget)
            notificationService.sendOrderConfirmation(order, label);

            return new OrderConfirmation(order.getId(), label.getTrackingNumber());

        } catch (PaymentException ex) {
            inventoryService.release(reservation); // compensate
            throw ex;
        }
    }
}

// REST controller — knows nothing about subsystem internals
@RestController
@RequestMapping("/api/orders")
@RequiredArgsConstructor
public class OrderController {
    private final OrderFacade orderFacade;

    @PostMapping
    public ResponseEntity<OrderConfirmation> placeOrder(@RequestBody PlaceOrderRequest req) {
        return ResponseEntity.ok(orderFacade.placeOrder(req));
    }
}

• Controllers stay thin — one call, one result, no subsystem awareness.
• Business workflow is captured in one place — easy to read, review, and change.
• Compensation logic (rollback of partial operations) lives in the facade, not scattered.
• Subsystems can evolve independently; only the facade needs updating when APIs change.

// Component interface — both leaf and composite implement this
public interface CatalogComponent {
    String getName();
    BigDecimal getPrice();
    void display(String indent);
}

// Leaf — a single product
public class Product implements CatalogComponent {
    private final String name;
    private final BigDecimal price;

    public Product(String name, BigDecimal price) {
        this.name = name;
        this.price = price;
    }

    @Override public String getName() { return name; }
    @Override public BigDecimal getPrice() { return price; }

    @Override
    public void display(String indent) {
        System.out.println(indent + "📦 " + name + " ($" + price + ")");
    }
}

// Composite — a category that can contain other categories or products
public class Category implements CatalogComponent {
    private final String name;
    private final List<CatalogComponent> children = new ArrayList<>();

    public Category(String name) { this.name = name; }

    public void add(CatalogComponent component) { children.add(component); }
    public void remove(CatalogComponent component) { children.remove(component); }

    @Override public String getName() { return name; }

    @Override
    public BigDecimal getPrice() {
        return children.stream()
                .map(CatalogComponent::getPrice)
                .reduce(BigDecimal.ZERO, BigDecimal::add);
    }

    @Override
    public void display(String indent) {
        System.out.println(indent + "📁 " + name + " (total: $" + getPrice() + ")");
        children.forEach(child -> child.display(indent + "   "));
    }
}

// Usage — client treats leaves and composites identically
Category electronics = new Category("Electronics");
Category smartphones = new Category("Smartphones");
smartphones.add(new Product("iPhone 16", new BigDecimal("999.00")));
smartphones.add(new Product("Galaxy S25", new BigDecimal("849.00")));
Category laptops = new Category("Laptops");
laptops.add(new Product("MacBook Pro M4", new BigDecimal("2499.00")));
electronics.add(smartphones);
electronics.add(laptops);

electronics.display(""); // recursively prints entire tree

• Client code is simple — always calls the same interface whether operating on a leaf or a whole tree.
• Adding new leaf types (e.g., Bundle, DigitalProduct) requires no changes to traversal code.
• Recursive operations (price calculation, permission checks) are naturally expressed.
• Maps directly to JPA parent-child relationships with @OneToMany(mappedBy="parent").

// Implementor interface — "what format to produce"
public interface ReportFormat {
    byte[] render(ReportData data);
    String getContentType();
}

// Concrete implementors
@Component("pdfFormat")
public class PdfReportFormat implements ReportFormat {
    @Override
    public byte[] render(ReportData data) {
        // iText / Apache PDFBox PDF generation
        return PdfBuilder.build(data);
    }
    @Override public String getContentType() { return "application/pdf"; }
}

@Component("excelFormat")
public class ExcelReportFormat implements ReportFormat {
    @Override
    public byte[] render(ReportData data) {
        // Apache POI Excel generation
        return ExcelBuilder.build(data);
    }
    @Override public String getContentType() { return "application/vnd.ms-excel"; }
}

// Abstraction — "how to deliver"
public abstract class ReportGenerator {
    protected final ReportFormat format; // bridge to implementor

    protected ReportGenerator(ReportFormat format) {
        this.format = format;
    }

    public abstract ReportResult generate(ReportRequest request);
}

// Refined abstraction 1 — web download
public class WebReportGenerator extends ReportGenerator {
    public WebReportGenerator(ReportFormat format) { super(format); }

    @Override
    public ReportResult generate(ReportRequest request) {
        ReportData data = fetchData(request);
        byte[] content = format.render(data);
        return ReportResult.forDownload(content, format.getContentType(),
                "report-" + request.getId() + ".download");
    }
}

// Refined abstraction 2 — API response
public class ApiReportGenerator extends ReportGenerator {
    public ApiReportGenerator(ReportFormat format) { super(format); }

    @Override
    public ReportResult generate(ReportRequest request) {
        ReportData data = fetchData(request);
        byte[] content = format.render(data);
        return ReportResult.forApi(Base64.getEncoder().encodeToString(content),
                format.getContentType());
    }
}

// Spring wiring — compose any combination without new subclasses
@Configuration
public class ReportConfig {
    @Bean public ReportGenerator webPdfReport(@Qualifier("pdfFormat") ReportFormat fmt) {
        return new WebReportGenerator(fmt);
    }
    @Bean public ReportGenerator apiExcelReport(@Qualifier("excelFormat") ReportFormat fmt) {
        return new ApiReportGenerator(fmt);
    }
    // Add CSV format tomorrow: zero changes to existing classes
}

• N formats + M environments = N + M classes, not N × M subclasses.
• Formats and delivery channels can be tested, swapped, and deployed independently.
• Spring's @Qualifier enables precise injection of any format into any generator.

// Flyweight — shared intrinsic state (immutable, thread-safe)
public final class MarkerType {
    private final String type;       // "RESTAURANT", "HOTEL", "HOSPITAL"
    private final String iconUrl;    // shared icon resource
    private final String color;      // shared color code
    private final byte[] iconBytes;  // pre-loaded icon — expensive to load

    public MarkerType(String type, String iconUrl, String color) {
        this.type = type;
        this.iconUrl = iconUrl;
        this.color = color;
        this.iconBytes = IconLoader.load(iconUrl); // loaded once, shared
    }

    // Render using extrinsic state (coordinates) passed by caller
    public void render(double lat, double lng) {
        System.out.printf("Rendering %s marker at (%.4f, %.4f) with color %s%n",
                type, lat, lng, color);
    }

    public String getType() { return type; }
}

// Flyweight Factory — ensures one MarkerType instance per type
@Component
public class MarkerFactory {
    private final Map<String, MarkerType> cache = new ConcurrentHashMap<>();

    public MarkerType getMarkerType(String type) {
        return cache.computeIfAbsent(type, t -> switch (t) {
            case "RESTAURANT" -> new MarkerType(t, "/icons/restaurant.png", "#FF5722");
            case "HOTEL"      -> new MarkerType(t, "/icons/hotel.png",      "#2196F3");
            case "HOSPITAL"   -> new MarkerType(t, "/icons/hospital.png",   "#F44336");
            default           -> throw new IllegalArgumentException("Unknown type: " + t);
        });
    }

    public int getCacheSize() { return cache.size(); }
}

// Marker — only stores extrinsic state (coordinates + reference to flyweight)
public class MapMarker {
    private final double latitude;
    private final double longitude;
    private final MarkerType markerType; // shared flyweight reference

    public MapMarker(double lat, double lng, MarkerType markerType) {
        this.latitude = lat;
        this.longitude = lng;
        this.markerType = markerType;
    }

    public void render() {
        markerType.render(latitude, longitude);
    }
}

// Service — creates 10,000 markers but only 3 MarkerType instances
@Service
@RequiredArgsConstructor
public class MapRenderService {
    private final MarkerFactory markerFactory;

    public List<MapMarker> buildMarkers(List<PoiData> pois) {
        return pois.stream()
                .map(poi -> new MapMarker(
                        poi.getLat(), poi.getLng(),
                        markerFactory.getMarkerType(poi.getType())))
                .toList();
    }
}

• Dramatic memory reduction when many objects share common state (icons, fonts, styles).
• ConcurrentHashMap.computeIfAbsent provides thread-safe factory caching with no locking overhead.
• Java's String.intern() and Integer.valueOf() are built-in JVM flyweight implementations.
• Use when profiling shows high memory pressure from many similarly-structured objects.

Leave a Comment

Related Posts