Sven Ruppert

What has happened so far

In the first part, the focus was deliberately on the user interface’s structural realignment. The previously grown, increasingly monolithic OverviewView was analysed and specifically streamlined by outsourcing key functional areas to independent UI components. With the introduction of the BulkActionsBar and the SearchBar, clearly defined building blocks were created, each assuming a specific responsibility and freeing the view from operational details.

This refactoring was not a cosmetic step but a conscious investment in the application’s long-term maintainability. By separating presentation, interaction, and logic, a modular foundation was created that is not only easier to test but also significantly simplifies future extensions. The OverviewView transformed from a function-overloaded central element into an orchestrating instance that brings components together instead of controlling their internal processes.

The second part now builds upon this foundation. While Part 1 highlighted the motivation, goals, and initial extractions, the focus now shifts consistently to the new structure of the OverviewView itself: how its role has changed, how event flows have been simplified and how the interaction of the extracted components leads to a clearer, more stable architecture.

The source code for this article can be found on GitHub at: https://github.com/svenruppert/url-shortener/tree/feature/advent-2025-day-11

Here is a screenshot of the current development status from the user’s perspective.

The focus is on dividing the previously monolithic OverviewView into clearly defined, reusable components such as the BulkActionsBar and the SearchBar. This separation improves maintainability, increases clarity and makes it easier to test individual functional areas. At the same time, this will pave the way for further UI optimisations and interaction patterns to be implemented gradually in the coming days.

New structure of the OverviewView

After removing the subcomponents, the new OverviewView appears in a much more streamlined, clearer form. While previously a large number of elements, event handlers and logic fragments were spread across the entire class, the View is now limited to a few, clearly defined tasks: the initialisation of the core components, the setup of the grid and the orchestration of the interactions between the SearchBar, BulkActionsBar and the backend.

This new structure follows a simple but powerful principle: the OverviewView focuses on bringing the components together rather than on how they work internally. It defines which building blocks are displayed, how they work together, and when they need to be updated. The internal structure of the individual elements – whether it be the handling of filter changes, the management of bulk actions, or the technical logic of the DataProvider – lies entirely within the respective components.

This clear layout makes the OverviewView look much tidier. The previously lush sections, with interspersed event listeners, complex UI layouts, and manual error handling, have largely disappeared, either merged into outsourced components or removed. They are replaced by short, easy-to-understand methods that control the flow of the view and connect its various building blocks.

This reduction not only makes the OverviewView easier to maintain but also easier to expand. New functions can be integrated at appropriate points without risking damage to existing logic. At the same time, an easily testable structure is created, as the dependencies are clearly defined and the responsibilities are clearly separated.

A central element of the new structure is the initialisation of the view, which is now clearly structured and largely free of embedded logic. This new distribution of roles can already be clearly seen in the constructor:

public OverviewView() {
  setSizeFull();
  setPadding(true);
  setSpacing(true);
  add(new H2("URL Shortener – Overview"));
  initDataProvider();

  var pagingBar = new HorizontalLayout(prevBtn, nextBtn, pageInfo, btnSettings);
  pagingBar.setDefaultVerticalComponentAlignment(CENTER);
  HorizontalLayout bottomBar = new HorizontalLayout(new Span(), pagingBar);
  bottomBar.setWidthFull();
  bottomBar.expand(bottomBar.getComponentAt(0));
  bottomBar.setAlignItems(CENTER);
  VerticalLayout container = new VerticalLayout(searchBar, bottomBar);
  container.setPadding(false);
  container.setSpacing(true);
  container.setWidthFull();
  add(container);

  add(bulkBar);
  add(grid);
  configureGrid();
  addListeners();
  addShortCuts();

  try (var _ = withRefreshGuard(false)) {
    searchBar.setPageSize(25);
    searchBar.setSortBy("createdAt");
    searchBar.setDirValue("desc");
  } catch (Exception e) {
    throw new RuntimeException(e);
  }
}

Here it becomes clear: The OverviewView only instantiates its components, inserts them into a layout and delegates all details to specialised classes. Neither filter logic nor bulk operations are included here – the view only orchestrates.

Another example of the streamlined structure is the way selection is handled in the grid. In the past, there was extensive logic for buttons, states and actions here; today, the view only controls the visibility and status of the BulkActionsBar:

grid.addSelectionListener(event -> {
  var all = event.getAllSelectedItems();
  boolean hasSelection = !all.isEmpty();

  bulkBar.setVisible(hasSelection);

  if (hasSelection) {
    int count = all.size();
    String label = count == 1 ? "link selected" : "links selected";
    bulkBar.selectionInfoText(count + " " + label + " on page " + currentPage);
  } else {
    bulkBar.selectionInfoText("");
  }

  bulkBar.setButtonsEnabled(hasSelection);
});

So the view only handles showing or hiding the BulkActionsBar. The actual logic for executing the actions lies entirely in the component itself.

The refresh mechanic is now clearly defined as well. Instead of repeating refresh calls in many places in the code, the safeRefresh() method has been created, which centrally defines how updates are performed:

public void safeRefresh() {
  logger().info("safeRefresh");
  if (!suppressRefresh) {
    logger().info("refresh");
    dataProvider.refreshAll();
  }
}

This design not only makes updating cleaner, but also prevents duplicate refreshes and unwanted infinite loops.

The new clarity is also reflected in the configuration of the grid, which remains complex in terms of content, but is clearly delineated and outsourced to its own methods:

private void configureGrid() {
  logger().info("configureGrid..");
  grid.addThemeVariants(GridVariant.LUMO_ROW_STRIPES, GridVariant.LUMO_COMPACT);
  grid.setHeight("70vh");
  grid.setSelectionMode(Grid.SelectionMode.MULTI);

  configureColumShortCode();
  configureColumUrl();
  configureColumCreated();
  configureColumActive();
  configureColumExpires();
  configureColumActions();

  grid.addItemDoubleClickListener(ev -> openDetailsDialog(ev.getItem()));
  grid.addItemClickListener(ev -> {
    if (ev.getClickCount() == 2) openDetailsDialog(ev.getItem());
  });

  GridContextMenu<ShortUrlMapping> menu = new GridContextMenu<>(grid);
  menu.addItem("Show details", e -> e.getItem().ifPresent(this::openDetailsDialog));
  menu.addItem("Open URL", e -> e.getItem().ifPresent(m -> UI.getCurrent().getPage().open(m.originalUrl(), "_blank")));
  menu.addItem("Copy shortcode", e -> e.getItem().ifPresent(m -> UI.getCurrent().getPage().executeJs("navigator.clipboard.writeText($0)", m.shortCode())));
  menu.addItem("Delete...", e -> e.getItem().ifPresent(m -> confirmDelete(m.shortCode())));
}

This structure makes it clear which areas of the view have which tasks. The multi-outsourced logic ensures that each method fulfils a clearly defined function.

Simplified event pipeline after refactoring

Refactoring has significantly reduced this complexity. The event pipeline now follows a linear, predictable flow: users interact with the UI components, which trigger clearly defined actions; the OverviewView responds with manageable control signals and finally updates the grid via a uniform refresh mechanism. Critical is the introduction of safeRefresh() and withRefreshGuard(), which prevent unnecessary or recursive updates.

The result is an architecture in which events are no longer propagated across the view, but run along a handful of defined interfaces in a structured manner. This is already clearly visible in the central listener setup of the OverviewView:

private void addListeners() {
  ComponentUtil.addListener(UI.getCurrent(),
                            MappingCreatedOrChanged.class,
                            _ -> {
                              logger().info("Received MappingCreatedOrChanged -> refreshing overview");
                              refreshPageInfo();
                              safeRefresh();
                            });

  grid.addSelectionListener(event -> {
    var all = event.getAllSelectedItems();
    boolean hasSelection = !all.isEmpty();

    bulkBar.setVisible(hasSelection);

    if (hasSelection) {
      int count = all.size();
      String label = count == 1 ? "link selected" : "links selected";
      bulkBar.selectionInfoText(count + " " + label + " on page " + currentPage);
    } else {
      bulkBar.selectionInfoText("");
    }

    bulkBar.setButtonsEnabled(hasSelection);
  });

  btnSettings.addClickListener(_ -> new ColumnVisibilityDialog<>(grid, columnVisibilityService).open());
  prevBtn.addClickListener(_ -> {
    if (currentPage > 1) {
      currentPage--;
      refreshPageInfo();
      safeRefresh();
    }
  });

  nextBtn.addClickListener(_ -> {
    int size = Optional.ofNullable(searchBar.getPageSize()).orElse(25);
    int maxPage = Math.max(1, (int) Math.ceil((double) totalCount / size));
    if (currentPage < maxPage) {
      currentPage++;
      refreshPageInfo();
      safeRefresh();
    }
  });
}

This is where the new clarity becomes apparent: External events such as MappingCreatedOrChanged trigger a targeted refresh; the grid selection only affects the BulkActionsBar; the paging buttons only control page and refresh. The complex logic from earlier days is clearly divided.

The keyboard shortcuts also integrate seamlessly into this simplified pipeline and use the encapsulated bulk logic:

private void addShortCuts() {
  var current = UI.getCurrent();

  current.addShortcutListener(_ -> {
                                if (!grid.getSelectedItems().isEmpty()) {
                                  bulkBar.confirmBulkDeleteSelected();
                                }
                              },
                              Key.DELETE);
}

On the SearchBar side, event processing is also greatly relieved and follows a clear pattern. Changes to filters or settings always lead to the OverviewView and its uniform refresh mechanism:

activeState.addValueChangeListener(_ -> {
  holdingComponent.setCurrentPage(1);
  holdingComponent.safeRefresh();
});

pageSize.addValueChangeListener(e -> {
  holdingComponent.setCurrentPage(1);
  holdingComponent.setGridPageSize(e.getValue());
  holdingComponent.safeRefresh();
});

resetBtn.addClickListener(_ -> {
  try (var _ = withRefreshGuard(true)) {
    resetElements();
    holdingComponent.setCurrentPage(1);
  } catch (Exception e) {
    throw new RuntimeException(e);
  }
});

The use of withRefreshGuard(true) in combination with safeRefresh() ensures that certain internal state changes do not immediately trigger a cascade refresh, but are triggered in a controlled, conscious manner.

Improvements in the MultiAliasEditorStrict

The MultiAliasEditorStrict is a central UI element in the URL shortener, allowing you to edit and manage multiple alias variants of a shortlink. During the refactoring, this editor was also revised to better integrate with the new component architecture and, at the same time, improve the user experience. Many of the original challenges resulted from tight integration with the OverviewView and from a poorly structured internal logic that had grown over the course of development.

One of the most essential innovations concerns the consistency of his behaviour. The MultiAliasEditorStrict is implemented as a standalone, clearly focused UI element that is solely responsible for capturing and validating aliases:

public class MultiAliasEditorStrict
    extends VerticalLayout {

  private static final String RX = "^[A-Za-z0-9_-]{3,64}$";
  private final Grid<Row> grid = new Grid<>(Row.class, false);
  private final TextArea bulk = new TextArea("Aliases (comma/space/newline)");
  private final Button insertBtn = new Button("Take over");
  private final Button validateBtn = new Button("Validate all");
  private final String baseUrl;
  private final Function<String, Boolean> isAliasFree;   Server check (true = free)

  public MultiAliasEditorStrict(String baseUrl,
                                Function<String, Boolean> isAliasFree) {
    this.baseUrl = baseUrl;
    this.isAliasFree = isAliasFree;
    build();
  }

It is already clear here that the editor has a well-defined task: it knows the preview baseUrl prefix, manages its own UI elements, and provides an isAliasFree function to check for alias conflicts on the server side.

The structurinterface’s interface is entirely contained within the build() method. This is where text input, toolbar and grid are assembled:

private void build() {
  setPadding(false);
  setSpacing(true);

  bulk.setWidthFull();
  bulk.setMinHeight("120px");
  bulk.setValueChangeMode(ValueChangeMode.LAZY);
  bulk.setClearButtonVisible(true);
  bulk.setPlaceholder("e.g.\nnews-2025\npromo_x\nabc123");

  insertBtn.addClickListener(_ -> parseBulk());
  validateBtn.addClickListener(_ -> validateAll());

  var toolbar = new HorizontalLayout(insertBtn, validateBtn);
  toolbar.setSpacing(true);

  configureGrid();

  add(bulk, toolbar, grid);
}

This makes the user interface clear: First, aliases are entered in the bulk field, then transferred to the grid via “Take over” and finally checked via “Validate all”.

The MultiAliasEditorStrict has also been improved in terms of structure and internal architecture. Instead of distributing logic fragments across validation, synchronisation, and UI updates in an unstructured way, these areas were clearly separated and moved to dedicated methods. This is particularly evident in the grid structure and in the validation logic.

The grid itself displays the alias lines, a preview and the status in a compact form:

private void configureGrid() {
  grid.addComponentColumn(row -> {
    var tf = new TextField();
    tf.setWidthFull();
    tf.setMaxLength(64);
    tf.setPattern(RX);
    tf.setValue(Objects.requireNonNullElse(row.getAlias(), ""));
    tf.setEnabled(row.getStatus() != Status.SAVED);
    tf.addValueChangeListener(ev -> {
      row.setAlias(ev.getValue());
      validateRow(row);
      grid.getDataProvider().refreshItem(row);
    });
    return tf;
  }).setHeader("Alias").setFlexGrow(1);

  grid.addColumn(r -> baseUrl + Objects.requireNonNullElse(r.getAlias(), ""))
      .setHeader("Preview").setAutoWidth(true);

  grid.addComponentColumn(row -> {
    var lbl = switch(row.getStatus()) {
      case NEW -> "New";
      case VALID -> "Valid";
      case INVALID_FORMAT -> "Format";
      case CONFLICT -> "Taken";
      case ERROR -> "Error";
      case SAVED -> "Saved";
    };
    var badge = new Span(lbl);
    var theme = switch (row.getStatus()) {
      case VALID, SAVED -> "badge success";
      case CONFLICT, INVALID_FORMAT, ERROR -> "badge error";
      default -> "badge";
    };
    badge.getElement().getThemeList().add(theme);
    if (row.getMsg() != null && !row.getMsg().isBlank()) badge.setTitle(row.getMsg());
    return badge;
  }).setHeader("Status").setAutoWidth(true);

  grid.addComponentColumn(row -> {
    var del = new Button("✕", e -> {
      var items = new ArrayList<>(grid.getListDataView().getItems().toList());
      items.remove(row);
      grid.setItems(items);
    });
    del.getElement().setProperty("title", "Remove");
    return del;
  }).setHeader("").setAutoWidth(true);

  grid.setItems(new ArrayList<>());
  grid.setAllRowsVisible(false);
  grid.setHeight("320px");
}

Here, it is clearly visible how all relevant information – alias, preview URL, status, and deletion action – converges in a separate, self-contained table. The status display plays a central role in providing the user with feedback on format errors, conflicts, successful validation or entries that have already been saved.

The real intelligence of the editor lies in the parseBulk() and validateRow() logic. parseBulk() takes over the task of processing the free text input, detecting duplicates and creating new lines in the grid:

private void parseBulk() {
  var text = Objects.requireNonNullElse(bulk.getValue(), "");
  var tokens = Arrays.stream(text.split("[,;\\s]+"))
      .map(String::trim)
      .filter(s -> !s.isBlank())
      .distinct()
      .toList();

  if (tokens.isEmpty()) {
    Notification.show("No aliases to insert", 2000, Notification.Position.TOP_CENTER);
    return;
  }

  Set<String> existing = grid.getListDataView().getItems()
      .map(Row::getAlias)
      .filter(Objects::nonNull)
      .collect(Collectors.toCollection(() -> new TreeSet<>(String.CASE_INSENSITIVE_ORDER)));

  var view = grid.getListDataView();
  int added = 0;
  for (String tok : tokens) {
    if (existing.contains(tok)) continue;
    var r = new Row(tok);
    validateRow(r);
    view.addItem(r);
    existing.add(tok);
    added++;
  }
  grid.getDataProvider().refreshAll();
  bulk.clear();

  Notification.show("Inserted: " + added, 2000, Notification.Position.TOP_CENTER);
}

The validation of individual rows is encapsulated in validateRow() and follows a clear step-by-step model of format checking, duplicate checking, and optional server querying:

private void validateRow(Row r) {
  var a = Objects.requireNonNullElse(r.getAlias(), "");
  if (!a.matches(RX)) {
    r.setStatus(Status.INVALID_FORMAT);
    r.setMsg("3–64: A–Z a–z 0–9 - _");
    return;
  }

  long same = grid.getListDataView().getItems()
      .filter(x -> x != r && Objects.equals(a, x.getAlias()))
      .count();
  if (same > 0) {
    r.setStatus(Status.CONFLICT);
    r.setMsg("Duplicate in list");
    return;
  }

  if (isAliasFree != null) {
    try {
      if (!isAliasFree.apply(a)) {
        r.setStatus(Status.CONFLICT);
        r.setMsg("Alias taken");
        return;
      }
    } catch (Exception ex) {
      r.setStatus(Status.ERROR);
      r.setMsg("Check failed");
      return;
    }
  }
  r.setStatus(Status.VALID);
  r.setMsg("");
}

Together with the status enum and the inner row class, this results in a self-contained, easily comprehensible state machine for each alias:

public enum Status { NEW, VALID, INVALID_FORMAT, CONFLICT, ERROR, SAVED }

public static final class Row {
  private string alias;
  private status status = Status.NEW;
  private String msg = "";

  Row(String a) {
    this.alias = a;
  }

  public String getAlias() { return alias; }
  public void setAlias(String a) { this.alias = a; }

  public Status getStatus() { return status; }
  public void setStatus(Status s) { this.status = s; }

  public String getMsg() { return msg; }
  public void setMsg(String m) { this.msg = m; }
}

Overall, the revision of the MultiAliasEditorStrict shows how even smaller UI components can benefit significantly from a clean structure, clear responsibilities and consistent behaviour. The component is now more stable, more comprehensible and easier to integrate – ideal conditions for future extensions or adjustments.

Cheers Sven

Today marks a crucial step in the evolution of the URL shortener’s user interface. After the focus in the past few days was mainly on functional enhancements – from filter and search functions to bulk operations – this day is dedicated to a structural fine-tuning: the refactoring of central UI components. This refactoring not only serves to clean up the code but also creates a clear, modular basis for future extensions as well as a significantly improved developer experience.

The source code for this article can be found on GitHub at: https://github.com/svenruppert/url-shortener/tree/feature/advent-2025-day-11

Here is a screenshot of the current development state from the user’s perspective.

The focus is on dividing the previously monolithic OverviewView into clearly defined, reusable components such as the BulkActionsBar and the SearchBar. This separation improves maintainability, increases clarity and makes it easier to test individual functional areas. At the same time, this will pave the way for further UI optimisations and interaction patterns to be implemented gradually in the coming days.

Motivation for refactoring

As an application’s functionality increases, so does its source code complexity. Especially in a UI that is continuously expanded and adapted to new requirements, this quickly leads to monolithic structures in which presentation, logic and state management are closely interwoven. This is precisely the situation that had developed in the OverviewView over the past few days of development: a central view that had to take on more and more tasks and thus became increasingly difficult to understand, extend, and test.

Refactoring today, therefore, starts at a fundamental point. The goal is not to introduce new features, but to create a clear, modular foundation that makes future expansions much easier. Individual UI building blocks are removed from the overloaded view and formed into independent components, with responsibility-specific tasks, clear communication channels, and significantly improved reusability. This not only reduces the complexity within the view itself, but also makes the entire architecture more robust to change.

At the same time, this refactoring strengthens the developer experience: The structure of the code becomes more comprehensible, components can be improved in isolation, and future changes – such as to the search logic or bulk operations – can be made in the right place in a targeted manner. The result is a UI design that is more stable, more flexible and easier to maintain in the long term.

Why is this step a turning point today

Today marks a critical moment in the development of the URL shortener’s user interface, as the focus shifts for the first time from new features to the code’s structural quality. While the previous steps were primarily aimed at delivering visible improvements for the user, it is now a matter of ensuring the foundation on which these functions remain solid and scalable over the long term. Such refactoring creates clarity in areas that had previously grown instead of planned – and that’s precisely what makes this day a turning point.

By separating the central UI building blocks, an architecture emerges that no longer consists of a single, heavyweight view but of clearly defined components that perform precisely defined tasks. This structural realignment opens up new possibilities for expansion, halts progress on technical debt reduction, and ensures that upcoming features no longer have to be integrated into a confusing block. Instead, each feature can be implemented in the right place without destabilising existing areas.

This step thus makes a decisive contribution to long-term development: reduced friction in the code, fewer side effects, and greater clarity. So today it’s not about visible innovations, but about the quality of the foundation – and that’s exactly what makes working on upcoming expansions much more efficient, stable and enjoyable.

Overview of the most important changes

Today, the focus is on replacing the previously central OverviewView, which had increasingly assumed responsibility over the course of development and had become correspondingly confusing. By extracting independent components, this complexity is decomposed into clearly defined building blocks.

An essential part of this restructuring is the introduction of the new BulkActionsBar, which bundles all mass operations, making both the code and the user interface more straightforward. The new SearchBar also creates a dedicated area that includes search and filter functions, making it easier to expand. Both components not only simplify the view but also provide a foundation for consistent design and recurring interaction patterns throughout the user interface.

In addition, the internal logic of the overview has been streamlined: state management, event handling, and grid interactions have been rearranged to reduce unwanted dependencies and enable targeted future changes. Minor improvements, such as the unified formatting of specific UI components, also contribute to the overall impression of a clean, structured codebase.

Why are UI components removed from views?

In mature user interfaces, a close interlocking of layout, interaction logic and state management often arises. As a result, central views become increasingly extensive over time and lose their original character. A clear entry point of the application becomes a complex block whose internal logic is difficult to understand. This is exactly where the separation of independent components comes in: It serves to clearly separate responsibilities and shift complexity to where it belongs – into small, clearly defined building blocks.

By extracting UI components, the view is reduced to its core task: orchestrating the interaction of several well-defined elements. Each component takes on a clearly defined role – be it managing search filters, triggering bulk operations, or displaying individual UI sections. This modular approach improves readability, fosters a more natural understanding of the architecture, and significantly reduces side effects during refactoring.

Another advantage is reusability. Components that are only loosely coupled to the overall view can be used flexibly elsewhere, expanded, or improved in isolation. This not only creates a robust structure but also enables more sustainable development practices, allowing new functions to be implemented without major interventions in existing areas. The separation of UI components is, therefore, an essential step in keeping a growing project stable and clear in the long term.

The new BulkActionsBar

Bulk operations are a function that plays an increasingly important role in the daily use of a URL shortener. As the number of entries grows, the need to edit several items at the same time increases – for example, to deactivate expired links, delete outdated campaigns or manage a larger number of new entries together. Such operations are not only a convenience feature but also an essential part of efficient workflows.

In many projects, bulk operations are first integrated directly into the main view. This works well at first, but in the long run, it causes view overload. Buttons, health checks, and more complex interaction logics begin to blend between Grid and View. The result is a structure that is difficult to maintain and in which extensions always carry the risk of unwanted side effects.

The decision to outsource bulk operations to a separate component creates a clear separation: the BulkActionsBar takes over the entire UI-related part of mass actions and thus forms a dedicated functional area. It bundles all relevant actions in one place, ensures a consistent user experience, and reduces complexity in the higher-level view. This clear delineation makes it much easier to add new actions, extend existing ones, or adapt the presentation to future design requirements.

In this way, outsourcing bulk operations makes a decisive contribution to a more stable and flexible architecture – and ensures that the user interface remains clear and intuitive even as requirements grow.

Structure of the BulkActionsBar component

The BulkActionsBar is an independent UI component that bundles all mass actions and presents them in a clearly structured way. Their structure follows the principle that an element should cover exactly one area of responsibility: In this case, the initiation of collection actions without itself containing logic for data processing. This keeps it easy to understand and flexible to use.

The central component of the BulkActionsBar is a clearly defined collection of interaction elements – typically buttons or icons – each of which triggers a specific action. These elements are compactly arranged in a horizontal layout, making them highly visible and intuitively accessible in the user interface. This is complemented by a mechanism that controls the visibility and activability of actions based on whether and how many entries are selected in the grid. In this way, the component not only remains clear but also guides the user through clear interaction instructions.

Another essential aspect of the structure is the abstraction of event processing. The component itself does not perform any operations; instead, it signals to the higher-level view via events or callback functions which action to trigger. This creates loose coupling between the UI and the logic, which both facilitates testing and allows adjustments to individual areas without unintentionally affecting other components.

A practical example of this is the basic structure of the class that defines the BulkActionsBar:

public class BulkActionsBar
    extends Composite<HorizontalLayout>
    implements HasLogger {

  private final URLShortenerClient urlShortenerClient;
  private final Grid<ShortUrlMapping> grid;
  private final OverviewView holdingComponent;

  private final Button bulkDeleteBtn = new Button(new Icon(VaadinIcon.TRASH));
  private final Button bulkSetExpiryBtn = new Button(new Icon(VaadinIcon.CLOCK));
  private final Button bulkClearExpiryBtn = new Button(new Icon(VaadinIcon.CLOSE_CIRCLE));
  private final Button bulkActivateBtn = new Button(new Icon(VaadinIcon.PLAY));
  private final Button bulkDeactivateBtn = new Button(new Icon(VaadinIcon.STOP));

  private final Span selectionInfo = new Span();

  public BulkActionsBar(URLShortenerClient urlShortenerClient,
                        Grid<ShortUrlMapping> grid,
                        OverviewView holdingComponent) {
    this.urlShortenerClient = urlShortenerClient;
    this.grid = grid;
    this.holdingComponent = holdingComponent;

    buildBulkBar();
    addListeners();
  }
}

Here, it becomes clear how the component encapsulates all elements relevant to mass actions: It knows the URLShortenerClient, the underlying Grid<ShortUrlMapping>, and the higher-level OverviewView, yet remains clearly delimited as an independent component. All buttons and the selection information area are defined within the class and are initialised in the constructor.

The actual visual structure of the BulkActionsBar is encapsulated in its own method:

private void buildBulkBar() {

  --- Common style ---
  bulkBar().getStyle()
      .set("background", "var(--lumo-contrast-5pct)")
      .set("padding", "0.4rem 0.8rem")
      .set("border-radius", "var(--lumo-border-radius-m)")
      .set("border-bottom", "1px solid var(--lumo-contrast-20pct)");

  --- button setup ---
  setupIconButton(bulkDeleteBtn, VaadinIcon.TRASH, "Delete selected links", "var(--lumo-error-color)");
  setupIconButton(bulkSetExpiryBtn, VaadinIcon.CALENDAR_CLOCK, "Set expiry for selected", "var(--lumo-primary-color)");
  setupIconButton(bulkClearExpiryBtn, VaadinIcon.CALENDAR_CLOCK, "Clear expiry for selected", "var(--lumo-secondary-text-color)");
  setupIconButton(bulkActivateBtn, VaadinIcon.CHECK_CIRCLE, "Activate selected", "var(--lumo-success-color)");
  setupIconButton(bulkDeactivateBtn, VaadinIcon.CLOSE_CIRCLE, "Deactivate selected", "var(--lumo-error-color)");

  bulkBar().removeAll();

  selectionInfo.getStyle().set("opacity", "0.7");
  selectionInfo.getStyle().set("font-size", "var(--lumo-font-size-s)");
  selectionInfo.getStyle().set("margin-right", "var(--lumo-space-m)");

  bulkBar().add(
      selectionInfo,
      bulkDeleteBtn,
      bulkSetExpiryBtn,
      bulkClearExpiryBtn,
      bulkActivateBtn,
      bulkDeactivateBtn
  );

  bulkBar().setWidthFull();
  bulkBar().setSpacing(true);
  bulkBar().setDefaultVerticalComponentAlignment(FlexComponent.Alignment.CENTER);
  bulkBar().setVisible(false);
}

The method shows how style, layout and interaction elements are brought together in a central place. The BulkActionsBar thus defines its own visual and functional cluster within the interface, while the URLShortenerClient and the OverviewView still handle the actual execution of the actions.

Overall, this setup enables a clean separation of display and behaviour, provides a robust foundation for future expansion, and integrates seamlessly with the application’s modular architecture.

Using the BulkActionsBar in the OverviewView

The BulkActionsBar is only valuable for interaction with the OverviewView, because there it becomes clear how much outsourcing mass actions simplifies the user interface structure. While these actions were previously implemented directly in the view itself, mixing a large number of event handlers, UI elements, and logic, the BulkActionsBar now handles this entire functional area. The OverviewView only needs to define when the bar becomes visible, which entries are selected, and how to respond to the triggered actions.

The integration follows a clear pattern: As soon as the user selects one or more rows in the grid, the view displays the BulkActionsBar and passes it the current selection state. The component itself does not perform any operations, but signals which action has been triggered via clearly defined methods and events. This creates loose coupling, which increases clarity and significantly improves visibility.

Another advantage is evident when handling status changes. The OverviewView no longer has to activate or deactivate buttons individually or control complex UI dependencies. Instead, a single central feedback to the BulkActionsBar is sufficient; it updates itself. This interaction not only makes the code leaner, but also prevents errors that could easily occur with multiple scattered logics.

A central entry point for the integration is to initialise the BulkActionsBar directly as a field of the OverviewView:

private final BulkActionsBar bulkBar = new BulkActionsBar(urlShortenerClient, grid, this);

This provides the view with a fully configured instance that knows the URLShortenerClient, the grid, and the view itself. The component is then integrated into the constructor:

add(bulkBar);
add(grid);

Significant is the interaction with the grid’s selection listener. Here, the view decides whether the BulkActionsBar is visible and what information it should display:

grid.addSelectionListener(event -> {
  var all = event.getAllSelectedItems();
  boolean hasSelection = !all.isEmpty();

  bulkBar.setVisible(hasSelection);

  if (hasSelection) {
    int count = all.size();
    String label = count == 1 ? "link selected" : "links selected";
    bulkBar.selectionInfoText(count + " " + label + " on page " + currentPage);
  } else {
    bulkBar.selectionInfoText("");
  }

  bulkBar.setButtonsEnabled(hasSelection);
});

This section clarifies the precise distribution of roles: the view recognises the current selection state, updates the visibility of the BulkActionsBar, and forwards relevant status information. The component itself remains completely free of logic for selection management.

The triggering of the actual actions also remains bundled in the view. An example of this is deleting using keyboard shortcuts:

current.addShortcutListener(_ -> {
      if (!grid.getSelectedItems().isEmpty()) {
        bulkBar.confirmBulkDeleteSelected();
      }
    },
    Key.DELETE);

This once again shows the interplay of clearly defined responsibilities: the BulkActionsBar encapsulates the action UI, and the OverviewView determines the context in which it is executed.

Overall, the use of the BulkActionsBar in the OverviewView clearly demonstrates how a clear separation of responsibilities improves the architecture of a Vaadin application. The View refocuses on its core task – presenting and updating the data – while the component encapsulates and consistently delivers all the interaction around mass actions. The BulkActionsBar in the OverviewView demonstrates how a clear separation of responsibilities improves the architecture of a Vaadin application. The View refocuses on its core task – presenting and updating the data – while the component encapsulates and consistently delivers all the interaction around mass actions.

Code Comparison: Before vs. After

The difference between the previous implementation of bulk operations and the new, component-based structure is immediately apparent. Whereas previously all elements, buttons and dialogues were anchored directly in the OverviewView, distributed over numerous event handlers and UI areas, the code is now much more modular. The BulkActionsBar is a standalone component that encapsulates the entire UI for bulk actions. As a result, the OverviewView not only had to accommodate less logic but also gained overall clarity.

The difference is evident in the reduction of responsibilities within the view. Before the refactoring, the OverviewView handled all aspects: providing the buttons, displaying the bar, handling selection, opening and executing dialogues, and providing user feedback. This resulted in an extensive, tightly coupled block of code that was difficult to maintain and error-prone.

After the refactoring, the structure has improved significantly. All UI-related logic of bulk operations is now exclusively in the BulkActionsBar. The OverviewView is limited to recognising the selection and forwarding the necessary information. The component itself still triggers the actions, but the view is no longer involved in the UI’s visual or structural layout. This change improves readability, as each functional area is now located where it belongs. In addition, the risk of unintended side effects is significantly reduced, as changes to the BulkActionsBar no longer require direct intervention in the OverviewView. To clarify the difference, it is worth reviewing typical places that were previously located directly in the OverviewView and are now outsourced. A classic example is the handling of the bulk deletion operation. In the past, the OverviewView itself handled dialogue, loops, error handling, and refresh. Today, the entire logic can be found clearly closed in the BulkActionsBar:

New structure – outsourced bulk delete logic:

public void confirmBulkDeleteSelected() {
    var selected = grid.getSelectedItems();
    if (selected.isEmpty()) {
      Notifications.noSelection();
      return;
    }

    Dialog dialog = new Dialog();
    dialog.setHeaderTitle("Delete " + selected.size() + " short links?");

    var exampleCodes = selected.stream()
        .map(ShortUrlMapping::shortCode)
        .sorted()
        .limit(5)
        .toList();

    if (!exampleCodes.isEmpty()) {
      String preview = String.join(", ", exampleCodes);
      if (selected.size() > 5) preview += ", ...";
      dialog.add(new Text("Examples: " + preview));
    } else {
      dialog.add(new Text("Delete selected short links?"));
    }

    Button confirm = new Button("Delete", _ -> {
      int success = 0;
      int failed = 0;

      for (var m : selected) {
        try {
          boolean ok = urlShortenerClient.delete(m.shortCode());
          if (ok) success++;
          else failed++;
        } catch (IOException ex) {
          logger().error("Bulk delete failed for {}", m.shortCode(), ex);
          failed++;
        }
      }

      dialog.close();
      grid.deselectAll();
      holdingComponent.safeRefresh();
      Notifications.deletedAndNotDeleted(success, failed);
    });
    confirm.addThemeVariants(ButtonVariant.LUMO_PRIMARY, LUMO_ERROR);

    Button cancel = new Button("Cancel", _ -> dialog.close());

    dialog.getFooter().add(new HorizontalLayout(confirm, cancel));
    dialog.open();
}

Here you can see that the entire interaction – from the UI to the error handling to the update – now takes place within the component and no longer burdens the OverviewView.

New structure – View only signals the selection:

grid.addSelectionListener(event -> {
    var all = event.getAllSelectedItems();
    boolean hasSelection = !all.isEmpty();

    bulkBar.setVisible(hasSelection);

    if (hasSelection) {
      int count = all.size();
      String label = count == 1 ? "link selected" : "links selected";
      bulkBar.selectionInfoText(count + " " + label + " on page " + currentPage);
    } else {
      bulkBar.selectionInfoText("");
    }

    bulkBar.setButtonsEnabled(hasSelection);
});

This shows the new role distribution: the OverviewView only controls visibility and status display. In the past, the entire operation logic would have been implemented here as well. Another example is opening the bulk set expiry dialogues. This logic is now also completely in the component and no longer distributed across the View:

bulkSetExpiryBtn.addClickListener(_ -> openBulkSetExpiryDialog());

The entire dialogue logic is then located in:

private void openBulkSetExpiryDialog() { ... }

Result:
The clear separation of responsibilities results in:

• significantly fewer lines of code in the OverviewView,
• a more structured, modular architecture,
• less coupling,
• improved maintainability and expandability.

Overall, this results in a more maintenance-friendly, extensible and clear structured architecture.

Search requirements

A practical search function is a central part of any administrative interface, especially when the number of entries is continuously growing. In the context of URL shorteners, this means that users can quickly and specifically access specific short links – regardless of whether they are looking for a particular shortcode, a URL fragment, the active status or time criteria. The previous implementation offered only simple filter options and was tightly coupled to the OverviewView, making both extensibility and maintenance difficult.

However, the requirements for a modern search component go far beyond a simple text field. It must support multiple filter criteria, respond flexibly to new fields, and adapt dynamically to the backend data structure. At the same time, it should offer the user an intuitive, consistent and clutter-free interface. This includes clear input fields, understandable labels, sensible default values, and the ability to change or reset search parameters quickly.

Technical reliability is just as crucial as user-friendliness: the search function must not burden the backend unnecessarily, support high-performance queries, and use server-side filters efficiently. A clean separation between UI, filter logic and data retrieval not only enables a better overview, but also later extensions – such as additional filter fields, sorting options or advanced functions such as combining several criteria.

The introduction of the new SearchBar addresses these requirements. It serves as the comprehensive filter and control centre for the overview and ensures that the view itself is decoupled from the filter logic. In doing so, it lays the foundation for a scalable and user-friendly search and filtering experience.

Structure and internal logic of the SearchBar

The SearchBar is designed as an independent UI component that aggregates all filter and search parameters from the OverviewView and presents them in a clearly structured format. This component aims to centralise previously scattered filter logic and significantly improve view clarity. Whereas previously individual input fields and sorting parameters were defined directly in the OverviewView, the SearchBar now assumes full responsibility for their management.

Its structure follows a modular concept: Each input – be it a text filter, a sorting criterion, the number of displayed elements or filtering by properties such as active status or expiration date – is clearly demarcated within the component and is processed independently. This not only ensures better logical separation but also enables flexible expansion with additional filters without requiring adjustments to the view itself.

The internal logic of the SearchBar works closely with the backend. Based on the user-selected parameters, the component creates structured filter objects that can be passed to the server consistently. Instead of collecting individual parameters loosely or combining them in the view, they are merged in a clearly defined process: validated, normalised, and then transferred to a backend request.

The central method buildFilter, which creates a UrlMappingListRequest object from the UI inputs, shows what this process looks like in concrete terms:

public UrlMappingListRequest buildFilter(Integer page, Integer size) {
  UrlMappingListRequest.Builder b = UrlMappingListRequest.builder();

  ActiveState activeStateValue = activeState.getValue();
  logger().info("buildFilter - activeState == {}", activeStateValue);
  if (activeStateValue != null && activeStateValue.isSet()) {
    b.active(activeStateValue.toBoolean());
  }
  if (codePart.getValue() != null && !codePart.getValue().isBlank()) {
    b.codePart(codePart.getValue());
  }

  if (urlPart.getValue() != null && !urlPart.getValue().isBlank()) {
    b.urlPart(urlPart.getValue());
  }

  if (fromDate.getValue() != null && fromTime.getValue() != null) {
    var zdt = ZonedDateTime.of(fromDate.getValue(), fromTime.getValue(), ZoneId.systemDefault());
    b.from(zdt.toInstant());
  } else if (fromDate.getValue() != null) {
    var zdt = fromDate.getValue().atStartOfDay(ZoneId.systemDefault());
    b.from(zdt.toInstant());
  }

  if (toDate.getValue() != null && toTime.getValue() != null) {
    var zdt = ZonedDateTime.of(toDate.getValue(), toTime.getValue(), ZoneId.systemDefault());
    b.to(zdt.toInstant());
  } else if (toDate.getValue() != null) {
    var zdt = toDate.getValue().atTime(23, 59).atZone(ZoneId.systemDefault());
    b.to(zdt.toInstant());
  }

  if (sortBy.getValue() != null && !sortBy.getValue().isBlank()) b.sort(sortBy.getValue());
  if (dir.getValue() != null && !dir.getValue().isBlank()) b.dir(dir.getValue());

  if (page != null && size != null) {
    b.page(page).size(size);
  }

  var filter = b.build();
  logger().info("buildFilter - {}", filter);
  return filter;
}

The code shows how all relevant filter fields – active status, shortcode and URL parts, time windows, and sorting and paging information – are consolidated in a single place. The SearchBar thus serves as a translator between UI inputs and the domain-specific filter structure in the backend. This creates a robust interface that both reduces errors and facilitates future expansions. At the same time, the SearchBar ensures a consistent user experience. Changes to a field automatically update the results list, while sensible default values and a consistent display ensure a familiar user experience. This combination of structural clarity, technical precision, and ease of use makes the SearchBar a central building block of the project’s modern UI architecture.

Improvements compared to the previous solution

From a technical standpoint, the new solution offers greater robustness. The processing is now handled entirely in the SearchBar, using structured data objects that are transmitted directly to the backend. This minimises errors caused by inconsistent or incomplete filter parameters. At the same time, the clear structure makes it easy to add new filters without jeopardising existing functionality.

A key example of the improvements is how changes to the SearchBar filter are handled. Whereas previously the OverviewView had to check and react to each value, the SearchBar now handles this task independently. This is already evident in the ValueChange listeners of the individual input fields:

codePart.addValueChangeListener(_ -> holdingComponent.safeRefresh());
urlPart.addValueChangeListener(_ -> holdingComponent.safeRefresh());
activeState.addValueChangeListener(_ -> {
  holdingComponent.setCurrentPage(1);
  holdingComponent.safeRefresh();
});
pageSize.addValueChangeListener(e -> {
  holdingComponent.setCurrentPage(1);
  holdingComponent.setGridPageSize(e.getValue());
  holdingComponent.safeRefresh();
});

These listeners make it clear that the SearchBar takes complete control of the filters’ behaviour and automatically updates the view. Previously, this logic was distributed in the OverviewView. Global search has also been significantly improved. It used to be a standalone input field with no real integration, but now it dynamically controls the specific search fields and ensures consistent filters:

globalSearch.addValueChangeListener(e -> {
  var v = Optional.ofNullable(e.getValue()).orElse("");
  if (searchScope.getValue().equals("Shortcode")) {
    codePart.setValue(v);
    urlPart.clear();
  } else {
    urlPart.setValue(v);
    codePart.clear();
  }
});

As a result, global search has become a real entry point for filter logic, rather than being an additional field with no straightforward integration.

Another big step forward is the introduction of the reset mechanism, which resets all filters in a targeted manner while ensuring that the UI returns to a consistent state:

resetBtn.addClickListener(_ -> {
  try (var _ = withRefreshGuard(true)) {
    resetElements();
    holdingComponent.setCurrentPage(1);
  } catch (Exception e) {
    throw new RuntimeException(e);
  }
});

Finally, switching between simple and advanced search also shows the new structural quality of the SearchBar:

advanced.addOpenedChangeListener(ev -> {
  boolean nowClosed = !ev.isOpened();
  if (nowClosed) {
    applyAdvancedToSimpleAndReset();
  } else {
    setSimpleSearchEnabled(false);
  }
});

Overall, the new SearchBar is far superior in both functionality and architecture. Their listeners, control logic, and consistent handling of filter elements form the basis for a modern, scalable, and maintenance-friendly search architecture. It is not only functionally better, but also forms the basis for a modern, scalable and maintenance-friendly search architecture.

Interaction of the SearchBar with grid and backend

The SearchBar only shows its full strength when interacting with the grid and the backend that powers it. While it serves as a central input component for all search and filter parameters on the interface, it technically forms the link between user interaction and server-side data supply. It is precisely in this role that it becomes clear how crucial the decoupling of the filter logic from the actual view is for performance, maintainability and extensibility.

In the first step, the SearchBar accepts all user input – from global search texts to specific shortcode or URL parts to date ranges, sort fields and the active status. These values are no longer processed ad hoc in the OverviewView, but collected, validated and harmonised in a structured form within the SearchBar. This keeps filter states consistent and traceable, even when multiple input fields are changed simultaneously.

The second step is the interaction with the grid. As soon as a relevant filter value changes, the SearchBar notifies the OverviewView of the updated state. This, in turn, triggers a grid update without requiring the individual filter criteria to be known or processed. The grid then calls the backend via its DataProvider and receives a filtered subset of the data based on the SearchBar’s requirements. This creates a clearly separated yet closely interlinked system of input, data retrieval and presentation.

On the backend, the advantage of a structured filter is particularly evident in how the OverviewView configures its DataProvider. The SearchBar always provides a consistent filter object that is passed directly to the backend calls. Central to this is the initialisation of the DataProvider in the OverviewView:

private void initDataProvider() {
  dataProvider = new CallbackDataProvider<>(
      q -> {
        final int uiSize = Optional.ofNullable(searchBar.getPageSize()).orElse(25);
        final int pageStart = (currentPage - 1) * uiSize;

        final int vLimit = q.getLimit();
        final int vOffset = q.getOffset();

        final int effectiveLimit = (vLimit > 0) ? vLimit: uiSize;
        final int effectiveOffset = pageStart + vOffset;

        final int page = (effectiveLimit > 0) ? (effectiveOffset / effectiveLimit) + 1 : 1;
        final int size = (effectiveLimit > 0) ? effectiveLimit: uiSize;

        final UrlMappingListRequest req = searchBar.buildFilter(page, size);
        try {
          final List<ShortUrlMapping> items = urlShortenerClient.list(req);
          return items.stream();
        } catch (IOException ex) {
          logger().error("Error fetching (page={}, size={})", page, size, ex);
          Notifications.loadingFailed();
          return Stream.empty();
        }
      },

      _ -> {
        try {
          final UrlMappingListRequest base = searchBar.buildFilter(null, null);
          totalCount = urlShortenerClient.listCount(base);

          final int uiSize = Optional.ofNullable(searchBar.getPageSize()).orElse(25);
          final int pageStart = (currentPage - 1) * uiSize;
          final int remaining = Math.max(0, totalCount - pageStart);
          final int pageCount = Math.min(uiSize, remaining);

          refreshPageInfo();
          return pageCount;
        } catch (IOException ex) {
          logger().error("Error counting", ex);
          totalCount = 0;
          refreshPageInfo();
          return 0;
        }
      }
  );

  grid.setPageSize(Optional.ofNullable(searchBar.getPageSize()).orElse(25));
  grid.setDataProvider(dataProvider);
}

This makes it clear how closely the grid, SearchBar, and backend interact: the DataProvider calculates the effective query parameters from the current paging information and page size, then builds a UrlMappingListRequest from the SearchBar and passes it directly to the URLShortenerClient. The SearchBar is also used for the counting function, this time without paging parameters, to determine the total number of entries.

The advantage of this structure is that the OverviewView itself does not need to know the details of the filter fields. It delegates the entire filter configuration to the SearchBar and focuses solely on controlling the grid and paging. Changes to the filters – such as additional criteria or changed default values – can be made entirely in the SearchBar without having to adjust the DataProvider or the View.

Overall, the interaction among SearchBar, Grid, and the backend shows a cleanly orchestrated data-flow model: Users change a filter, the SearchBar generates a unique search query, the DataProvider requests the appropriate data via the URLShortenerClient, and the Grid presents the results. This consistent, clearly structured process makes the entire interface much more stable, understandable and responsive.

Cheers Sven

What has happened so far?

In the first part of this article, the new active/inactive model for shortlinks was introduced and anchored at the architectural level. Based on the technical rationale, it was shown that a pure expiration date is insufficient for modern use cases and that an explicit activity status is required.

Based on this, the technical foundations were laid: the core domain model was extended with an active flag, the DTOs were adapted accordingly, and the serialisation was designed to ensure backward compatibility. In addition, the administrative REST endpoints have been expanded to enable targeted setting, querying, and filtering of activity status. The redirect behaviour has also been clarified so that deactivated and expired shortlinks can be distinguished by clearly defined HTTP status codes.

The structural basis of the active/inactive model is thus fully established. In the second part, the focus is on practical use: how the Java client maps these new capabilities, how users can conveniently control activity status via the Vaadin interface, and how this results in consistent, efficient workflows in everyday use.

The source code for this project‘s status can be found on GitHub at the following URL: https://github.com/svenruppert/url-shortener/tree/feature/advent-2025-day-10

Java Client Enhancements

After the server API had been extended to include functions for activating and deactivating shortlinks, the Java client also had to be adapted accordingly. After all, it is the primary interface for many users to work programmatically with the URL shortener – whether in the context of desktop tools, automations, CI/CD pipelines or embedded systems.

Chapter 5 details how new capabilities have been added to the client to support the active/inactive model fully. These include:

• the targeted switching of the activity status,
• the initial setting of the activity and expiration date when creating a shortlink,
• as well as editing existing mappings, including the new activity field.

The extensions are based on a consistent design approach: simple parameters, clear method focus, strict validation, and traceable error handling. For users, this creates an API that is not only complete, but also intuitive to use – regardless of whether individual values are changed or complete mappings are rebuilt.

New API: toggleActive(shortCode, active)

To allow the user to control the activity status of a shortlink not only via the REST API, but also conveniently via the Java client, a new method has been added to the client API. This method is the functional equivalent of the toggle endpoint on the server side and allows shortlinks to be enabled or disabled directly from applications, scripts, or automations.

The new API method toggleActive(shortCode, active) does exactly this. It ensures that all relevant information is transmitted to the server in the correct structure and that the server’s response is converted into a suitable representation. With a clear focus on switching activity status, the user eliminates the need to build full update objects or send unnecessary data.

Another advantage of this method is its simplicity: the user only needs to specify the shortcode of the link to be changed as well as the desired new status. The client’s internal logic takes care of everything else – from creating the appropriate request payload to interpreting the server response. This makes it particularly intuitive to use and reduces potential sources of error.

In the next step, we will look at the concrete implementation of this method using the source code. The following implementation comes directly from the URLShortenerClient:

public boolean toggleActive(String shortCode, boolean active)
      throws IOException {
    logger().info("Toggle Active shortCode='{}' active='{}'", shortCode, active);
    if (shortCode == null || shortCode.isBlank()) {
      throw new IllegalArgumentException("shortCode must not be null/blank");
    }
    final URI uri = serverBaseAdmin.resolve(PATH_ADMIN_TOGGLE_ACTIVE + "/" + shortCode);
    final URL url = uri.toURL();
    logger().info("Toggle Active - {}", url);

    final HttpURLConnection con = (HttpURLConnection) url.openConnection();
    con.setRequestMethod("PUT");
    con.setDoOutput(true);
    con.setRequestProperty(CONTENT_TYPE, JSON_CONTENT_TYPE);
    con.setRequestProperty(ACCEPT, APPLICATION_JSON);
    con.setConnectTimeout(CONNECT_TIMEOUT);
    con.setReadTimeout(READ_TIMEOUT);

    var req = new ToggleActiveRequest(shortCode, active);

    final String body = toJson(req);
    logger().info("Toggle Active - request body - '{}'", body);
    try (OutputStream os = con.getOutputStream()) {
      os.write(body.getBytes(UTF_8));
    }

    final int code = con.getResponseCode();
    logger().info("Toggle Active - responseCode {}", code);

    if (code == 200 || code == 204 || code == 201) {
      drainQuietly(con.getInputStream());
      return true;
    }

    if (code == 404) {
      logger().info("shortCode not found.. {}", shortCode);
      drainQuietly(con.getErrorStream());
      return false;
    }
    final String err = readAllAsString(con.getErrorStream());
    throw new IOException("Unexpected response: " + code + ", body=" + err);
}

The method starts with basic validation and logging. The shortCode parameter must be set because it uniquely identifies the shortlink to change. If the value is null or empty, the client throws an IllegalArgumentException even before an HTTP call is made.

The next step is to create the destination URL for the API call. The server’s administrative base path (serverBaseAdmin) is combined with the toggle endpoint path segment. Thanks to this dynamic composition, the client remains flexible in different deployment environments.

The client then opens an HTTP connection and configures it for a PUT request. The method sets the expected header fields, including Content-Type (for JSON) and Accept, to define the expected response type. setDoOutput(true) indicates that a request body is included in the request.

For the actual payload, an instance of ToggleActiveRequest is created, which consists of a shortCode and the desired new active state. This structure is serialized using toJson and then written to the output stream of the connection.

After the request is sent, the method reads the HTTP status code via con.getResponseCode().  The implementation distinguishes between three main cases:

1. Successful state change (200, 204, or 201): The method flushes the InputStream via drainQuietly and returns true. This signals to the user that the shortlink has been updated successfully.
2. Shortlink not found (404): Again, the ErrorStream is emptied. However, the method returns false to make it clear to the user that the shortlink does not exist and therefore cannot be updated.
3. All other error cases: In the event of unexpected or erroneous responses, the ErrorStream is read and packaged together with the HTTP status code in an IOException. This forces the calling code to handle unforeseen errors and prevents such states from being silently ignored.

Thus, toggleActive provides a clearly defined, robust API for switching activity status via the Java client. It follows the same design principles as the client’s other methods: clear validation, consistent error handling, meaningful logging, and lean, JSON-based communication. The implementation thus integrates seamlessly into the existing client architecture and provides a simple yet effective extension of functionality.

Advanced createCustomMapping(...)

In addition to the possibility to activate or deactivate existing shortlinks afterwards, the process for creating new shortlinks has also been expanded. To allow users to determine whether a shortlink is active when making it, the createCustomMapping(...) method is used in the Java client.

Before this adjustment, a shortlink could be created using only its fundamental properties – shortcode, original URL, and optional expiration date. The activity status was set implicitly or could only be controlled via later processing steps. With the new extension, the user can determine during creation whether a shortlink is active or inactive.

The method follows the same principles as the client’s other functions: it focuses on clear, simple, and reliable communication with the server. The user only provides the required input values. At the same time, the client takes care of the entire technical processing of the request – from creating the request object to JSON serialisation and interpreting the server response.

This expansion allows new use cases to be realised. For example, a shortlink can already be created, but only activated later – for example, synchronously with a release time, a marketing campaign or automatically in CI/CD pipelines. At the same time, the uniform data structure ensures that the activity status of a shortlink is treated consistently both when creating and editing.

In the next step, we examine the concrete implementation of this method using the relevant source code sections and analyse how the extended parameters are integrated into the creation process.

The extension appears in the URLShortenerClient in the form of two overloaded methods: a simple variant and an extended version with expiration and activity parameters:

public ShortUrlMapping createCustomMapping(String alias, String url)
      throws IOException {
    logger().info("Create custom mapping alias='{}' url='{}'", alias, url);
    return createCustomMapping(alias, url, null, null);
  }

public ShortUrlMapping createCustomMapping(String alias, String url, Instant expiredAtOrNull, Boolean activeOrNull)
      throws IOException {
    logger().info("Create custom mapping alias='{}' url='{}' expiredAt='{}' active='{}'", alias, url, expiredAtOrNull, activeOrNull);
    var result = UrlValidator.validate(url);
    if (!result.valid()) {
      throw new IllegalArgumentException("Invalid URL: " + result.message());
    }

    if (alias != null && !alias.isBlank()) {
      var validate = AliasPolicy.validate(alias);
      if (!validate.valid()) {
        var reason = validate.reason();
        throw new IllegalArgumentException(reason.defaultMessage);
      }
    }
    var shortenRequest = new ShortenRequest(url, alias, expiredAtOrNull, activeOrNull);
    String body = toJson(shortenRequest);
    logger().info("createCustomMapping - body - '{}'", body);

    URL shortenUrl = serverBaseAdmin.resolve(PATH_ADMIN_SHORTEN).toURL();
    logger().info("connecting to .. shortenUrl {} (custom)", shortenUrl);
    HttpURLConnection connection = (HttpURLConnection) shortenUrl.openConnection();
    connection.setRequestMethod("POST");
    connection.setDoOutput(true);
    connection.setRequestProperty(CONTENT_TYPE, JSON_CONTENT_TYPE);

    try (OutputStream os = connection.getOutputStream()) {
      os.write(body.getBytes(UTF_8));
    }

    int status = connection.getResponseCode();
    logger().info("Response Code from Server - {}", status);
    if (status == 200 || status == 201) {
      try (InputStream is = connection.getInputStream()) {
        String jsonResponse = new String(is.readAllBytes(), UTF_8);
        logger().info("createCustomMapping - jsonResponse - {}", jsonResponse);
        ShortUrlMapping shortUrlMapping = fromJson(jsonResponse, ShortUrlMapping.class);
        logger().info("shortUrlMapping .. {}", shortUrlMapping);
        return shortUrlMapping;
      }
    }
    if (status == 409) {
      final String err = readAllAsString(connection.getErrorStream());
      throw new IllegalArgumentException("Alias already in use: '" + alias + "'. " + err);
    }
    if (status == 400) {
      final String err = readAllAsString(connection.getErrorStream());
      throw new IllegalArgumentException("Bad request: " + err);
    }
    throw new IOException("Server returned status " + status);
  }

The simple variant of createCustomMapping serves as a convenience method: it accepts only an alias and a URL and delegates to the extended version, setting expiration date and activity status to zero. This keeps the API lean for simple use cases, while allowing complete control over the shortlink via the overloaded method.

The extended method first assumes responsibility for validating the input data. UrlValidator.validate(url) checks whether the specified destination URL meets the expected criteria. If this is not the case, an IllegalArgumentException is  thrown with a comprehensible error message. If an alias is set, the alias policy is then checked. This ensures that custom shortcodes comply with the set rules and, for example, do not contain unwanted special characters or prohibited patterns.

If the URL and alias are valid, a ShortenRequest is created that includes expiredAtOrNull and activeOrNull, in addition to URL and alias. In this way, the user can control whether the shortlink has an expiration date and whether it should be initially active or inactive when creating it. The request is then serialised in JSON format and sent to the PATH_ADMIN_SHORTEN endpoint.

The HTTP configuration follows the familiar pattern: A POST request is created with a JSON body, the Content-Type is set accordingly, and the body is transmitted via the OutputStream. The server’s response is first checked against the HTTP status code. If successful (200 or 201), the client reads the response body, converts it to a ShortUrlMapping object, and returns it to the user.

Two special paths are provided for error cases: If the alias reservation fails because the alias is already assigned (409 Conflict), an IllegalArgumentException is thrown with a clear description. General validation errors (400 Bad Request) also throw a meaningful IllegalArgumentException. All other unexpected status codes result in an IOException that includes the exact status code and error message from the server.

Overall, the advanced createCustomMapping method fits seamlessly into the existing API design. It allows users to create shortlinks in one step with an alias, expiration date, and activity status, combining strict validation with precise, predictable error handling.

Adjustments to edit(...) – Processing with activity status

In addition to creating new shortlinks, users often need to customise existing listings. This may involve updating the target URL, adjusting an expiration date, or, in the context of the new functionality, activating or deactivating an existing shortlink.

To cover these requirements, the existing edit(...) method of the Java client has been extended. It now also supports the optional activity status parameter, so the user no longer needs to change this value via a downstream toggle API; they can control it directly during editing.

This approach facilitates workflows in which multiple properties of a shortlink are edited simultaneously. Instead of making various API calls in sequence, the entire change process can be combined into a single edit operation. This means that the API remains efficient, consistent and can be easily integrated into various application scenarios – from manual editing to the UI to automated processes in scripts or backend systems.

In the next step, we will discuss the implementation of the extended edit(...) method.

The following implementation comes from the URLShortenerClient and shows how the activity state was incorporated into the editing process:

public boolean edit(String shortCode, String newUrl, Instant expiresAtOrNull, Boolean activeOrNull)
      throws IOException {
    logger().info("Edit mapping alias='{}' url='{}' expiredAt='{}' active='{}'", shortCode, newUrl, expiresAtOrNull, activeOrNull);
    if (shortCode == null || shortCode.isBlank()) {
      throw new IllegalArgumentException("shortCode must not be null/blank");
    }
    if (newUrl == null || newUrl.isBlank()) {
      throw new IllegalArgumentException("newUrl must not be null/blank");
    }

    final URI uri = serverBaseAdmin.resolve(PATH_ADMIN_EDIT + "/" + shortCode);
    final URL url = uri.toURL();
    logger().info("edit - {}", url);

    final HttpURLConnection con = (HttpURLConnection) url.openConnection();
    con.setRequestMethod("PUT");
    con.setDoOutput(true);
    con.setRequestProperty(CONTENT_TYPE, JSON_CONTENT_TYPE);
    con.setRequestProperty(ACCEPT, APPLICATION_JSON);
    con.setConnectTimeout(CONNECT_TIMEOUT);
    con.setReadTimeout(READ_TIMEOUT);

    final ShortenRequest req = new ShortenRequest(newUrl, shortCode, expiresAtOrNull, activeOrNull);
    final String body = toJson(req);
    logger().info("edit - request body - '{}'", body);

    try (OutputStream os = con.getOutputStream()) {
      os.write(body.getBytes(UTF_8));
    }

    final int code = con.getResponseCode();
    logger().info("edit - responseCode {}", code);

    if (code == 200 || code == 204 || code == 201) {
      drainQuietly(con.getInputStream());
      return true;
    }

    if (code == 404) {
      logger().info("shortCode not found.. {}", shortCode);
      drainQuietly(con.getErrorStream());
      return false;
    }

    final String err = readAllAsString(con.getErrorStream());
    throw new IOException("Unexpected response: " + code + ", body=" + err);
  }

The method accepts four parameters: the shortcode to change, the new destination URL, an optional expiration date, and an optional activity status. Right from the start, we check whether the necessary fields – especially shortCode and newUrl – are valid. An IllegalArgumentException immediately catches invalid inputs.

The request is then sent as a PUT to the corresponding edit endpoint. The payload consists of a ShortenRequest that contains all editable attributes of a shortlink – including the activity specification activeOrNull. This allows the user to update the URL, expiration date, and activity status in a single process.

The client then processes the HTTP response. Success cases (200, 201, 204) return true, while a 404 clearly indicates that the shortlink does not exist. Unexpected status codes cause an IOException, which allows the user to provide precise fault diagnoses.

This extension makes the edit(...) method fully capable of updating all relevant properties of a shortlink in a single step, including the activity state, which was previously only controllable via a separate toggle endpoint.

User interactions and UI logic in the Vaadin interface

After the previous chapters covered server-side REST handlers, client APIs, and persistence, this chapter focuses on the application’s UI layer. The OverviewView is the central administration tool for users to search, filter, edit, and manage shortlinks in bulk.

Chapter 6, therefore, sheds light on the most critical user interactions in the frontend, in particular:

• The interaction of Vaadin-Grid, CallbackDataProvider and dynamic filter parameters
• the integration of single actions (e.g. activating/deactivating a link by clicking on an icon)
• Implement more complex bulk operations , including dialogues, error handling, and visual feedback
• The connection between UI inputs and the REST endpoints via the URLShortenerClient

Switching the active state directly in the grid

To allow users to change the active or inactive status of a shortlink not only via the API, but also conveniently in the user interface, the grid of the administration view has been extended. The goal is to create the most direct, intuitive, and low-risk way possible to switch the status of a shortlink without opening separate dialogues or editing masks.

At the centre of each table row is a clearly recognisable visual button. With a single click, the user can toggle a shortlink’s status between active and inactive. The interface immediately signals the current state of the shortlink and the action that will be taken when clicked.

This enlargement has three main objectives:

• Speed – frequent switching does not require navigation into additional masks.
• Transparency – the user can see at all times which shortlinks are currently active.
• Robustness – possible error situations are clearly communicated and do not affect the rest of the application.

The core of the implementation lies in configuring the grid and the new “Active” column. The relevant snippet from the OverviewView looks like this:

grid.addComponentColumn(m -> {
      Icon icon = m.active()
          ? VaadinIcon.CHECK_CIRCLE.create()
          : VaadinIcon.CLOSE_CIRCLE.create();

      icon.setColor(m.active()
                        ? "var(--lumo-success-color)"
                        : "var(--lumo-error-color)");
      icon.getStyle().set("cursor", "pointer");
      icon.getElement().setProperty("title",
                                    m.active() ? "Deactivate": "Activate");

      icon.addClickListener(_ -> {
        boolean newValue = !m.active();

        try {
          urlShortenerClient.toggleActive(m.shortCode(), newValue);
          Notification.show("Status updated", 2000, Notification.Position.TOP_CENTER);
          safeRefresh();
        } catch (Exception ex) {
          Notification.show("Error updating active status: " + ex.getMessage(),
                            3000, Notification.Position.TOP_CENTER);
        }
      });
      return icon;
    })
    .setHeader("Active")
    .setKey("active")
    .setAutoWidth(true)
    .setResizable(true)
    .setSortable(true)
    .setFlexGrow(0);

Instead of a plain text field, a component column is used here, displaying a separate icon for each row. The choice of icon depends directly on the current activity status of the respective shortlink:

• If m.active() is true, a CHECK_CIRCLE icon is displayed.
• If m.active()is false, a CLOSE_CIRCLE icon is used.

The colour scheme (success for active, error for inactive) allows the user to recognise the state at a glance. In addition, the title attribute on the icon tells you which action is triggered by a click (“Activate” or “Deactivate”).

The toggle mechanism is implemented in the icon’s click listener. When clicked, the desired new status is first calculated:

boolean newValue = !m.active();

The Java client is then called, which delegates the state change to the server via the REST API:

urlShortenerClient.toggleActive(m.shortCode(), newValue);

If the call succeeds, the user receives a short, unobtrusive confirmation notification, and the grid is reloaded via safeRefresh(). This means that subsequent changes (e.g. filtering by active status) are also displayed correctly immediately.

Error handling follows the same pattern as in the client API: If an exception occurs – whether due to network problems, unexpected HTTP status codes or server errors – it is communicated in the UI via a clearly visible notification:

} catch (Exception ex) {
  Notification.show("Error updating active status: " + ex.getMessage(),
                    3000, Notification.Position.TOP_CENTER);
}

For the user, this means that the active status of a shortlink can be changed directly in the overview with a click. The UI combines clear visual cues (icon, colour, tooltip) with immediate feedback and robust error handling. This reduces the need for separate processing dialogues and makes typical administrative tasks around active/inactive much more efficient.

Filter by active and inactive status

In addition to the ability to switch a shortlink’s active status directly in the grid, the user interface has been enhanced with a precise filter system. This allows the user to search specifically for active, inactive, or all shortlinks – without manual searches or complex queries.

The goal is to provide the user with a tool that allows them to control the visibility of entries flexibly. This improves both the clarity of large datasets and the efficiency of routine administrative tasks, such as detecting expired or disabled shortlinks.

A unified selection element controls the new filter and affects both data retrieval and paging. If the user sets the filter to Active, Inactive, or Not set, the query parameters are updated to load and display only relevant records in the grid.

Central to this is the Select field for the active status, which is defined in the OverviewView:

private final Select<ActiveState> activeState = new Select<>();

This UI element is configured in the search bar and displayed alongside other search and paging elements. Initialisation is done in the buildSearchBar() block:

activeState.setLabel("Active state");
activeState.setItems(ActiveState.values());
activeState.setItemLabelGenerator(state -> switch (state) {
  case ACTIVE -> "Active";
  case INACTIVE -> "Inactive";
  case NOT_SET -> "Not set";
});
activeState.setEmptySelectionAllowed(false);
activeState.setValue(ActiveState.NOT_SET);
HorizontalLayout topBar = new HorizontalLayout(globalSearch, searchScope, pageSize, activeState, resetBtn);

This gives the user a clearly labeled drop-down selection with three states:

• Active – only active shortlinks
• Inactive – only inactive shortlinks
• Not set – no filtering by active status

The filter is set to NOT_SET by default , so all shortlinks are displayed first. The ItemLabelGenerator function determines the label displayed in the drop-down for each enum value.

For the filter to be functionally effective, the view reacts to changes in the selection field. A corresponding listener is registered in the addListeners() block:

activeState.addValueChangeListener(_ -> {
  currentPage = 1;
  safeRefresh();
});

As soon as the user changes the active state, the current page is reset to 1 and the data provider is reloaded. This makes the filter changes directly visible and prevents the user from being on an invalid page (for example, if there are fewer entries due to filtering).

The actual connection to the REST API is created in the buildFilter(...)method block that creates a UrlMappingListRequest from the UI  :

private UrlMappingListRequest buildFilter(Integer page, Integer size) {
  UrlMappingListRequest.Builder b = UrlMappingListRequest.builder();

  ActiveState activeStateValue = activeState.getValue();
  logger().info("buildFilter - activeState == {}", activeStateValue);
  if (activeStateValue != null && activeStateValue.isSet()) {
    b.active(activeStateValue.toBoolean());
  }
  // ... Other filters (codePart, urlPart, time periods, sorting, paging)

  if (page != null && size != null) {
    b.page(page).size(size);
  }

  var filter = b.build();
  logger().info("buildFilter - {}", filter);
  return filter;
}

Here, the enum value of the activeState select is read and, if it is considered “set,” converted to a Boolean (true for active, false for inactive). The request builder takes over this value and later transmits it to the server by the client (URLShortenerClient) as a query parameter. If the state is NOT_SET, no active value is set, so there is no active-status restriction on the server side.

Together, these building blocks form a consistent filter concept:

• The Select<ActiveState> provides a clear, three-level selection.
• The ValueChangeListener ensures that filter changes take effect immediately.
• buildFilter(...) translates the UI selection into a typed request to the backend API.

For users, this creates a seamless interaction: Switching from “Active” to “Inactive” immediately leads to only the corresponding shortlinks appearing in the grid – without this logic having to be duplicated in the frontend or filtered on the client side.

Mass operations based on active status.

In addition to single editing, the interface offers convenient bulk operations that let users enable or disable multiple shortlinks at once. This is especially helpful in scenarios where large amounts of data need to be managed, such as temporarily shutting down campaign links or reactivating an entire group of previously disabled shortlinks.

In this extension, bulk handling has been designed to integrate seamlessly with the existing grid and the integrated selection mechanisms. The user can select as many rows as they want in the grid and then trigger appropriate actions via clearly recognisable buttons in the bulk bar at the bottom of the screen.

The process always follows the same pattern:

1. The user marks the desired short links.
2. A confirmation dialogue ensures that the mass change is deliberately triggered.
3. The action is performed for each selected entry, regardless of potential errors.
4. The result is displayed to the user in a compact success/failure overview.

This approach enables robust yet user-friendly bulk editing. The interface remains responsive, and error handling ensures that a failure on a single shortlink does not affect the entire operation.

The following snippet is taken directly from the OverviewView and shows the central method that enables or disables a set of shortlinks in one pass:

private void bulkSetActive(Set<ShortUrlMapping> selected, boolean activate) {
  int success = 0;
  int failed = 0;

  for (var m : selected) {
    try {
      var ok = urlShortenerClient.toggleActive(m.shortCode(), activate);
      if (ok) {
        success++;
      } else {
        failed++;
      }
    } catch (IOException ex) {
      logger().error("Toggle active state failed for {}", m.shortCode(), ex);
      failed++;
    }
  }

  grid.deselectAll();
  safeRefresh();

  var actionLabel = activate ? "Activate" : "Deactivate";
  Notification.show(
      actionLabel + " – Success: " + success + " • Failed: " + failed
  );
}

This method is central to mass activation. It receives the shortlinks currently selected in the grid, as well as the target status (activate = true or false). For each entry, the corresponding request is sent to the server API via the Java client. The approach is deliberately designed to be fault-tolerant: a failure of one entry does not affect the rest of the processing.

The UI is not updated until the loop is complete. This keeps the operation clear and efficient, even with many shortlinks. The result is displayed to the user in a compact summary.

The user triggers this operation via a confirmation dialogue. This is implemented in confirmBulkSetActiveSelected(boolean activate ):

private void confirmBulkSetActiveSelected(boolean activate) {
  var selected = grid.getSelectedItems();
  if (selected.isEmpty()) {
    Notification.show("No entries selected");
    return;
  }

  var verb = activate ? "activate" : "deactivate";
  var verbCap = activate ? "Activate" : "Deactivate";

  Dialog dialog = new Dialog();
  dialog.setHeaderTitle(verbCap + " all " + selected.size() + " short links?");

  dialog.add(new Text(
      "This will " + verb + " all selected short links. "
          + "They will be " + (activate ? " active" : "inactive") + " afterwards."
  ));

  Button cancel = new Button("Cancel", _ -> dialog.close());
  Button confirm = new Button(verbCap + " All", _ -> {
    dialog.close();
    bulkSetActive(Set.copyOf(selected), activate);
  });
  confirm.addThemeVariants(ButtonVariant.LUMO_PRIMARY);
  dialog.getFooter().add(new HorizontalLayout(cancel, confirm));
  dialog.open();
}

This dialogue ensures that mass changes are not accidentally triggered. This is especially relevant for deactivating actions, as a deactivated shortlink no longer redirects.

The dialogue is activated via the two buttons in the bulk bar:

bulkActivateBtn.addClickListener(_ -> confirmBulkActivateSelected());
bulkDiActivateBtn.addClickListener(_ -> confirmBulkDeactivateSelected());

The associated wrapper methods are:

private void confirmBulkActivateSelected() {
  confirmBulkSetActiveSelected(true);
}

private void confirmBulkDeactivateSelected() {
  confirmBulkSetActiveSelected(false);
}

This means that mass editing is fully integrated into the user interface: selection, confirmation, execution and result feedback follow a clear, consistent process model. For users, an intuitive workflow makes administrative tasks much easier.

Redirect behaviour for end users.

With the introduction of the new active/inactive mechanism and improved handling of expiration times (expiresAt), the URL shortener’s behaviour when calling a shortlink changes fundamentally. While users previously received only a redirect or a generic error, the system now provides more granular HTTP status codes that enable precise conclusions about a link’s status.

Expired Shortlinks (expiresAt) → 410 Gone

If a shortlink has an expiration date and has passed, the user must not be redirected to the original URL when accessed. Instead, the system must clearly signal that this shortlink exists, but is no longer valid. This is precisely what the HTTP status code 410 Gone is used for.

The status code 410 indicates “permanently removed” and makes it unmistakably clear that the shortlink was previously active but is now deliberately unavailable. Unlike 404 Not Found, which means that a resource does not exist, 410 conveys a clear semantic meaning: this shortlink has expired and will never be valid again.

For the user, this means the call results in clear error behaviour that remains comprehensible. For developers, on the other hand, this mechanism creates transparency, as they can clearly distinguish between three situations:

• A shortlink does not exist → 404 Not Found
• A shortlink exists, but is disabled → 404 Not Found
• A shortlink exists and has expired → 410 Gone

The consistent use of the 410 status code also enables better monitoring and cleaner automation processes. Systems such as API gateways, SEO tools, crawlers, or CI/CD pipelines can capture the exact behaviour and thus more precisely explain why a redirect does not occur.

Disabled (active = false) → 404 Not Found

Another central component of the new active/inactive model is how deactivated shortlinks are handled. While expired links are signalled with the HTTP status code 410 Gone, the system deliberately uses a different status code for disabled links: 404 Not Found.

This difference is not accidental, but follows clear safety and operational considerations. A deactivated shortlink should behave as if it no longer exists for the end user, although it remains fully present, visible, and manageable internally.

This creates a behaviour ideal for maintenance phases, temporary blockades, campaign stops, or safety-related shutdowns. Developers and administrators retain complete control over the dataset without inadvertently revealing internal state information.

Cheers Sven

Why an active/inactive model for shortlinks?

For many users – especially those who work in the field of software development – shortlinks are much more than simple URL shorteners. They act as flexible routing mechanisms for campaigns, feature controls, test scenarios, and internal tools. The requirements for transparency, controllability and clean lifecycle management are correspondingly high.

The URL shortener receives an active/inactive model that directly supports these claims. A user can now specify, for each shortlink, whether it should be active, temporarily deactivated, or no longer allowed to reach users due to a planned expiration. At the same time, a clear distinction is made between a disabled and an expired shortlink – both in the UI and in the HTTP behaviour.

For the user, this creates a noticeable gain in control. An entire campaign can be taken offline with a single click, without losing data or having to edit multiple entries manually. The REST API or the Java client can be used to automatically control activity status externally, enabling integrations with existing development and deployment processes.

This introduction outlines the motivation for the new model. The following chapters detail how the UI, API, data model, and redirect logic have been extended, and how users benefit from the new active/inactive mechanism.

The source code for this project‘s status can be found on GitHub at the following URL: https://github.com/svenruppert/url-shortener/tree/feature/advent-2025-day-10

Architecture overview of changes

The new active/inactive model does not work in isolation within a single module; it spans multiple layers of the application. This creates consistent behaviour for the user – regardless of whether a shortlink is edited via the UI, automatically managed via the API or accessed directly in the browser. To understand this interaction, it is worth examining the key areas where adjustments have been made.

The basis is the extended data model, which now includes an additional attribute to store the activity status. This feature serves as the common denominator for all shortlink-related operations. As a result, both the REST endpoints and the internal Java client have been extended to reliably transmit activity status when creating, modifying, or querying a shortlink.

These structural changes are also reflected in the user interface. The activity status can now be set directly when creating a shortlink, in the overview table, or in the detail dialogue. Actions such as activating or deactivating multiple entries simultaneously use the exact mechanisms as the API, creating a consistent application experience.

Last but not least, the redirect behaviour has also been adjusted. While expired shortlinks are clearly indicated, deactivated shortlinks are not. In this way, the user can not only better understand why a shortlink is unreachable, but also receive more precise feedback from both client and monitoring perspectives.

This architectural overview shows that the active/inactive model is not a one-off feature, but a consistent design principle across all layers of the system. In the following chapters, the respective areas are considered in detail and technically explained.

The Advanced Data Model

Before the active/inactive model becomes visible in the user interface, REST API, or redirect behaviour, the basic structure must be defined in the data model. Chapter 3 focuses on this basis and shows how a shortlink’s activity status is anchored in the core of the system.

The data model is the central place where all relevant information converges into a shortlink. Every user action – be it creating, editing, filtering or forwarding a shortlink – sooner or later falls back on this structure. Therefore, it is crucial to introduce an activity status that is consistently and reliably available.

This chapter explains how the new active attribute is mapped to domain objects, how it is transported in DTOs, and the serialisation and backwards-compatibility considerations involved. This clean anchoring in the data model makes the active/inactive model a stable part of the entire application, on which all further technical enhancements are based.

New active flag in the core domain model.

The introduction of the active/inactive model begins at the core domain model level. This defines how a shortlink stores its state and what information is transmitted within the application. The new active attribute lets users check at any time whether a shortlink is currently in use or has been deliberately deactivated.

The central element of this change is the extension of the ShortUrlMapping class. It outlines the essential characteristics of a short link, including the alias, the original destination URL, and the expiration dates. The new attribute enables the unique determination of the activity status within this structure.

In the original implementation, the relevant snippet looks like this:

private boolean active;

public boolean active() {
    return active;
}

public ShortUrlMapping withActive(boolean active) {
    return new ShortUrlMapping(
        this.shortCode,
        this.originalUrl,
        this.createdAt,
        this.expiresAt,
        active
    );
}

This enhancement ensures that activity status is reliably available both in memory and in all downstream layers of the system. The model remains unchanged. The status is not changed in an existing object; instead, it is created as a new instance using the withActive method. This prevents unintended side effects and supports consistent, deterministic data behaviour.

This clear separation between active and inactive states provides a stable foundation for UI, server, and redirect logic. In the following subchapters, we will discuss how this information is mapped to the DTOs and the consequences for serialisation and transport behaviour.

Impact on DTOs (ShortenRequest, ShortUrlMapping)

The active/inactive model not only affects the domain core but must also be transported cleanly across the application boundary. Data Transfer Objects (DTOs) are crucial for this. They serve as the interface between the user interface, REST API, and Java client, ensuring that the activity status of a shortlink is transmitted correctly.

With the expansion of the data model, the DTO ShortUrlMapping also receives an additional attribute that reflects the status of a shortlink. This value is used both in communication from the server to the UI and between the server and the client. A relevant excerpt from the original implementation looks like this:

public record ShortUrlMapping(
    String shortCode,
    String originalUrl,
    Instant createdAt,
    Instant expiresAt,
    boolean active
) {}

This extended DTO enables the user to view activity status in the UI and allows external systems to read the status and respond accordingly. By using a record, structure and serialisation remain lean and clearly defined.

The request to create or change a shortlink has also been adjusted. The ShortenRequest now also includes information on whether a shortlink should be made directly active or initially deactivated. This allows the user to control how the shortlink behaves during creation.

An excerpt from the corresponding record:

public record ShortenRequest(
    String shortCode,
    String originalUrl,
    Instant expiresAt,
    Boolean active
) {}

At this point, it is evident that the request uses a Boolean, whereas the mapping itself uses a primitive Boolean. This difference is deliberate: the value in the request may also be null if the user does not want to set an explicit state. In this case, the server logic decides on a default value. Mapping, on the other hand, always has a defined state, eliminating ambiguity.

Extending DTOs ensures the active/inactive model is uniformly available across all system boundaries. It forms the basis for the UI, API and client to be informed identically about the status of a shortlink, thus creating a consistent user experience.

Serialisation and backward compatibility

For the active/inactive model to function reliably, the new active value must not only be present in the internal data model but also correctly serialised and transported across different components. The extension of serialisation affects two areas in particular: JSON communication via REST and data exchange between the various application modules.

By using Java records in the DTOs, serialisation is primarily handled by the chosen JSON library. Once the active attribute is defined in the record constructors, it is automatically included in the JSON representation. This makes integration straightforward and minimises the need for additional configuration.

An example of the resulting JSON structure of a shortlink as served via the REST API:

{
  "shortCode": "abc123",
  "originalUrl": "https://example.com",
  "createdAt": "2025-05-20T10:15:30Z",
  "expiresAt": "2025-06-01T00:00:00Z",
  "active": true
}

The JSON structure makes it clear that the activity state is immediately visible to the user and can be retrieved without any additional logic. This increase in transparency is central to the new model.

An essential aspect of this change is backward compatibility. Systems or components that use older versions of the API and are not aware of the active field can continue to interact without issues. JSON consumers typically ignore unknown fields to avoid affecting older clients. At the same time, the server can set a sensible default value for requests that do not specify an active value – typically true.

This combination of clear serialisation and high backward compatibility ensures that the active/inactive model can be integrated into existing systems without disruption. At the same time, further development remains open to future extensions, such as more differentiated activity states or audit information.

Enhancements to the Admin REST API

The active/inactive model only unfolds its full effect through the extensions of the administrative REST API. This establishes the connection between the data model, the internal business logic, and the various clients that create, edit, or automatically manage shortlinks. To enable users to effectively use the new activity state, several API endpoints had to be adapted or supplemented.

Chapter 4 examines these extensions in detail. It shows how the new toggle endpoint enables targeted switching of activity status, how inactive entries can be queried via a dedicated list endpoint, and how the ActiveState filter extends existing query operations. It also explains how differentiated HTTP status codes clearly convey the semantic meaning of a deactivated or expired shortlink.

These API customisations create a coherent, well-integrated interface that can map all aspects of the active/inactive model, whether the requests come from a user interface, a Java client, or an automated system.

New Toggle Endpoint

To make the active/inactive shortlink model usable across the application, the server component needs a well-defined mechanism to change the activity status of an existing shortlink. For this purpose, a new toggle endpoint was introduced and implemented on the server side by ToggleActiveHandler. It forms the basis for allowing users to adjust the activity state of a shortlink directly from the REST API – whether from the user interface, automations, or external systems.

The new endpoint has a clear purpose: it enables the targeted switching of the activity status of a specific shortlink. The user can specify, via a simple request, whether a shortlink should be activated or deactivated without changing any other mapping properties. This not only makes the operation more efficient, but also less error-prone, as there is no need for full update payloads.

This endpoint integrates seamlessly with the existing API structure and uses the same transport models and validation mechanisms as other administrative operations. At the same time, it provides a clear separation between changes of activity status and other editing operations, simplifying both implementation and use.

The core component of this endpoint is the ToggleActiveHandler. It encapsulates the HTTP-specific processing and delegates the actual state change to the UrlMappingStore behind it:

public class ToggleActiveHandler
    implements HttpHandler, HasLogger {

  private final UrlMappingStore store;

  public ToggleActiveHandler(UrlMappingStore store) {
    this.store = store;
  }

  @Override
  public void handle(HttpExchange ex)
      throws IOException {
    logger().info("handle ... {} ", ex.getRequestMethod());
    if (! RequestMethodUtils.requirePut(ex)) return;

    try {
      final String body = readBody(ex.getRequestBody());
      ToggleActiveRequest req = fromJson(body, ToggleActiveRequest.class);
      var shortCode = req.shortCode();
      if (isNullOrBlank(shortCode)) {
        writeJson(ex, BAD_REQUEST, "Missing 'shortCode'");
        return;
      }
      boolean newActiveValue = req.active();
      logger().info("Toggling active status for {} to {}", shortCode, newActiveValue);
      Result<ToggleActiveResponse> mapping = store.toggleActive(shortCode, newActiveValue);

      if (mapping.isPresent()) {
        logger().info("Toggling active status successfully");
        writeJson(ex, OK, toJson(mapping.get()));
      } else {
        Mapping.
            ifFailed(failed -> logger().info("Toggling active status failed: {}", failed));
        writeJson(ex, BAD_REQUEST, "Toggling active status failed");
      }
    } catch (RuntimeException e) {
      logger().warn("catch - {}", e.toString());
      writeJson(ex, INTERNAL_SERVER_ERROR);
    } finally {
      logger().info("ToggleActiveHandler .. finally");
      ex.close();
    }
  }
}

The handler implements the HttpHandler interface and integrates project-specific logging via HasLogger. In the constructor, the dependency is injected into the UrlMappingStore, which is later used to execute the logic that changes the state.

The main logic is in the try block. First, the request body is completely read in via readBody(ex.getRequestBody()) and converted to an instance of ToggleActiveRequest using fromJson. This Request object contains the two relevant pieces of information: the shortCode and the new active value. It then checks whether the shortcode is empty or null. In this case, the handler responds immediately with a 400 Bad Request and a clear error message, preventing the store layer from encountering invalid data.

If the shortcode is valid, the desired new activity value is extracted and logged. The actual status change occurs via “store.toggleActive(shortCode, newActiveValue)". The result is encapsulated in a Result<ToggleActiveResponse> to ensure both success and failure cases are handled consistently.

In case of success (mapping.isPresent()), another success entry is written to the log, and the updated display of the shortlink is returned to the user as JSON with the HTTP status 200 OK. If the store does not return a result, the cause of the error is logged via ifFailed, and the user is sent a response with a 400 Bad Request status code and a generic error message. This clearly defines the error behaviour without revealing too many details internally.

If unexpected runtime errors occur in the handler itself, the catch block catches the exception, logs a warning, and returns a 500 Internal Server Error. The finally block ensures that the connection is closed cleanly via ex.close() in all cases and that a corresponding log entry is created. Overall, this creates a robust, clearly structured endpoint that reliably and comprehensibly updates a shortlink‘s activity status.

Query inactive links

In addition to targeting the activity status of an individual shortlink, the user needs the ability to view collected inactive entries. This provides an overview of shortlinks that have been deliberately or automatically disabled and are currently no longer redirecting.

For this purpose, a special API endpoint was introduced that returns only inactive shortlinks. This endpoint complements the general list endpoint and provides a clear, filtered view of all shortlinks with the “inactive” status.

The focus of this endpoint is on visibility and control. Users can quickly see which shortlinks are currently disabled without having to implement their own filtering logic or evaluate the complete list of shortlinks. This is a notable advantage, especially in larger installations or automated workflows, as inactive entries often require separate management processes.

The endpoint integrates seamlessly with the existing administrative API structure and uses the same data models and return formats as other query operations. It ensures that information about inactive shortlinks is consistently retrievable across all UIs and clients.

The technical implementation of querying inactive shortlinks is integrated into the existing list handler. The following excerpt shows the ListHandler responsible for this, which provides different list variants, including the inactive entries, via a common endpoint:

public class ListHandler
    implements HttpHandler, HasLogger {

  private final UrlMappingLookup store;

  public ListHandler(UrlMappingLookup store) {
    this.store = store;
  }

  SNIPP

  @Override
  public void handle(HttpExchange ex)
      throws IOException {
    if (! RequestMethodUtils.requireGet(ex)) return;
    final String path = ex.getRequestURI().getPath();
    logger().info("List request: {}", path);

    String responseJson;
    if (path.endsWith(PATH_ADMIN_LIST_ALL)) {
      responseJson = listAll();
    } else if (path.endsWith(PATH_ADMIN_LIST_EXPIRED)) {
      responseJson = listExpired();
    } else if (path.endsWith(PATH_ADMIN_LIST_ACTIVE)) {
      responseJson = listActive();
    } else if (path.endsWith(PATH_ADMIN_LIST_INACTIVE)) {
      responseJson = listInActive();
    } else if (path.endsWith(PATH_ADMIN_LIST)) {
      responseJson = listFiltered(ex);
    } else {
      logger().info("undefined path {}", path);
      ex.sendResponseHeaders(404, -1);
      return;
    }
    writeJson(ex, OK, responseJson);
  }

  private String listInActive() {
    final Instant now = Instant.now();
    return filterAndBuild("inactive",
                          m -> {
                            if (!m.active()) return true;
                            return m.expiresAt()
                                .map(exp -> exp.isBefore(now))
                                .orElse(false);
                          });
  }

  private String filterAndBuild(String mode, Predicate<ShortUrlMapping> predicate) {
    final Instant now = Instant.now();
    final var data = store
        .findAll()
        .stream()
        .filter(predicate)
        .map(m -> toDto(m, now))
        .toList();
    return JsonUtils.toJsonListing(mode, data.size(), data);
  }

  private Map<String, String> toDto(ShortUrlMapping m, Instant now) {
    boolean expired = m.
        expiresAt()
        .map(t -> t.isBefore(now))
        .orElse(false);
    return Map.of(
        "shortCode", m.shortCode(),
        "originalUrl", m.originalUrl(),
        "createdAt", m.createdAt().toString(),
        "expiresAt", m.expiresAt().map(Instant::toString).orElse(""),
        "active", m.active() + "",
        "status", expired ? "expired" : "active"
    );
  }
}

The ListHandler, like the toggle handler, implements the HttpHandler interface and uses HasLogger for consistent logging. A UrlMappingLookup is injected into the constructor and used for the data queries. The handle method handles routing based on the request path: Depending on whether the request ends in PATH_ADMIN_LIST_ALL, PATH_ADMIN_LIST_ACTIVE, or PATH_ADMIN_LIST_INACTIVE, a specialised list method is called.

The listInActive() method is responsible for querying inactive shortlinks. It determines the current time and calls filterAndBuild("inactive", ...) with a predicate that selects the desired entries. A shortlink is considered inactive if it is either explicitly marked as inactive (!m.active()) or if it is active but has already expired. The combination of the active flag and the expiration date allows a clean separation between currently usable and no longer usable entries.

The filterAndBuild method reads all entries from the UrlMappingLookup, applies the passed predicate, and converts the remaining mappings into a DTO-like structure. For this purpose, toDto is used to create a map of the most essential attributes from each ShortUrlMapping. In addition to shortCode, originalUrl, createdAt, and expiresAt, the active status and a derived field, status, are set here, which distinguishes between expired and active. This additional information makes it easier for the user to read the entry status directly from the response.

This structure allows queries for inactive links to fit seamlessly into the existing list concept. Instead of introducing a completely independent endpoint, the existing infrastructure is used and expanded to include a targeted view of inactive entries. The result is a precise, reusable mechanism that always gives users a complete overview of all currently inactive shortlinks.

Adjustments in the list request (ActiveState filter)

To allow users to search specifically for active, inactive, or all shortlinks, a dedicated activity status filter has been added to the existing list mechanism. This so-called ActiveState filter complements the previous filter criteria, such as text search, sorting, time periods, or pagination, and enables precise control of the search results via the API.

This extension provides the user with a flexible yet clearly defined way to set the desired status directly via a query parameter. Instead of retrieving the entire list of shortlinks and then filtering it on the client side, the request can now be restricted directly on the server. This saves resources, reduces unnecessary data transfers, and ensures consistent search results.

The ActiveState filter considers three possible states:

• Active – The shortlink is active and, if there is an expiration date, has not yet expired.
• Inactive – The shortlink has been disabled by the user or has expired.
• Not set – The user does not provide a status indication, so the filter is not applied, and all relevant entries are considered.

This distinction is communicated via the active query parameter, which is passed to the standard list endpoint in a GET request. The server evaluates this parameter and creates a corresponding UrlMappingFilter object based on it, which controls entry selection.

The technical implementation of this filter logic is handled in the existing ListHandler, which already handles filtering and sorting shortlinks. The following excerpt shows how to process the active parameter and embed it in the UrlMappingFilter:

var filter = UrlMappingFilter.builder()
    .codePart(first(query, "code"))
    .urlPart(first(query, "url"))
    .createdFrom(parseInstant(first(query, "from"), true).orElse(null))
    .createdTo(parseInstant(first(query, "to"), false).orElse(null))
    .active(parseBoolean(first(query, "active")).orElse(null))
    .offset(offset)
    .limit(size)
    .sortBy(sortBy.orElse(null))
    .direction(dir.orElse(null))
    .build();

The central point is the line:

.active(parseBoolean(first(query, "active")).orElse(null))

Here, the query parameter active is read, interpreted as an optional boolean. The process in detail:

1. first(query, "active") reads the first value of the query parameter active – something like:
   1. active=true
   1. active=false
   1. or the parameter is missing completely.
2. parseBoolean(...) converts this value to an Optional<Boolean> . This means that invalid or missing values can also be caught cleanly.
3. .orElse(null) ensures that if input is missing or cannot be interpreted, the value null is transferred to the filter.

This results in the following meaning:

• active=true → only active shortlinks
• active=false → only inactive shortlinks
• no parameter → no restriction

The UrlMappingLookup then processes the resulting UrlMappingFilter:

int total = store.count(filter);
var results = store.find(filter);

These methods replace the application of the filter to the saved shortlinks. By passing through the active state, the lookup layer can precisely select the entries corresponding to the desired activity state.

Finally, the results are transferred to the DTO structure and returned as a paginated JSON response:

var items = results.stream().map(m -> toDto(m, now)).toList();
return toJsonListingPaged("filtered", items.size(), items, page, size, total, sortBy.orElse(null), dir.orElse(null));

With this extension, the ActiveState filter fits seamlessly into the existing filter system. Users can now target active or inactive shortlinks without additional endpoints or separate calls. This shows how ActiveState is processed and how it affects the final JSON result.

HTTP status code semantics: 410 vs. 404

With the introduction of the active/inactive model, the behaviour of the forwarding logic also changes. For the user, the state of a shortlink must be clearly and unambiguously communicated to the outside world – especially if a redirect cannot be done as expected. For this reason, the system uses two distinct HTTP status codes to distinguish expired and disabled shortlinks.

A shortlink can no longer be reached for two reasons:

1. It has expired. The expiration date has passed, and the shortlink is no longer valid as planned.
2. It has been disabled. The user has manually disabled the shortlink, regardless of the expiration date.

Although both result in no redirect, they differ in meaning. Expired shortlinks are intended to signal that their lifespan is ending clearly. Disabled shortlinks, on the other hand, have been deliberately taken out of service and may be in a temporary state.

Two HTTP status codes represent this semantic separation:

• 410 Gone – for expired short links. This status indicates that the resource is permanently unavailable and will not become available again.
• 404 Not Found – for disabled shortlinks. Although the shortlink exists, its redirect is intentionally not carried out. The 404 status code indicates a temporary or permanent error.

This distinction provides users, API clients, and monitoring systems with more precise feedback on the shortlink’s state. Understandably, a shortlink is not accessible due to a natural process or a manual decision.

Cheers Sven