java.lang.Object
net.i2p.router.web.GraphGroups
public final class GraphGroupsextends Object
Registry of graph groupings: sets of stats that answer the same question and share a unit, so they can be drawn as one multi-series plot instead of several small ones.

Every member of a group is either a count or a duration or a rate, and the members of one group always agree on which. That constraint is the whole point. Combining stats whose units differ produces a plot that looks meaningful and is not: a count against a byte count, or a per-second rate against a total, flattens the smaller series into the baseline and reads as "nothing happening". Members were therefore checked against their declaring code rather than their names.

Grouping is opt-in via PROP_COMBINE and only takes effect where at least two members are already enabled, so enabling a single stat of a group is never silently changed into a combined plot.

  • Field Details

    • PROP_COMBINE

      public static final String PROP_COMBINE
      Opt-in property; when false every stat renders on its own as before.
      See Also:

    • MAX_SERIES

      public static final int MAX_SERIES
      Most series drawn on one plot.

      Every group is now at or under MAX_SERIES: no frame combines more than two, because a tile is too small to read a third line and two hues are all the palette needs. This stays as a hard cap so a group added later cannot silently exceed it, and GraphGroupsTest asserts the current groups all comply.

      See Also:

    • PAIR_PREFIX

      private static final String PAIR_PREFIX
      Marker at the head of a group id built from an In/Out bandwidth pair rather than declared in the registry.

      Pool names come from configuration, so the two rates a pool publishes cannot be listed in advance: an HTTP proxy is only there if the user named it one. The marker keeps such an id recognisable, and keeps members(String) from treating an arbitrary string as a group.

      Not a plausible stat prefix: rate names are dotted subsystem paths (netDb.successTime) or, for pools, bracketed.

      See Also:

    • IN_SUFFIX

      private static final String IN_SUFFIX
      Suffix of a pool's inbound rate, as built by TunnelPool.
      See Also:

    • OUT_SUFFIX

      private static final String OUT_SUFFIX
      Suffix of a pool's outbound rate, as built by TunnelPool.
      See Also:

    • PAIR_SUBSYSTEM

      private static final String PAIR_SUBSYSTEM
      Subsystem a generated pair sorts under. A pool's rates answer how much traffic that service is carrying, so they sort with the other service graphs rather than under the tunnel jobs.
      See Also:

    • TITLES

      private static final Map<String,String> TITLES
      Display name per group. A combined plot shows several stats, so naming it after the primary series alone ("Number of NTCP Pumper loops/s") is misleading; these say what the plot as a whole covers.

    • GROUPS

      private static final Map<String, List<String>> GROUPS
      Group id to member stat names, in legend order.

    • SUBSYSTEMS

      private static final Map<String,String> SUBSYSTEMS
      Subsystem each group belongs to, used to build the [Subsystem] prefix that makes the graph list sort by area.

      Deliberately untranslated and kept out of TITLES: a title is a translation key (Translate returns the key for English and falls back to it when a bundle lookup misses), so folding a prefix into the title would silently untranslate every group in every locale. A prefix is also only useful for sorting if it is stable, which a translated string is not.

  • Constructor Details

    • GraphGroups

      private GraphGroups()
      Utility class, not intended for instantiation.

  • Method Details

    • displayPrefixOf

      public static String displayPrefixOf(String groupId)
      The sort prefix for a group, ready to prepend to a title.

      Untranslated by design, see SUBSYSTEMS.

      Parameters:
      groupId - a group id, or null
      Returns:
      "[Peers] " including the trailing space, or the empty string when the group has no subsystem or the id is unknown

    • subsystemOf

      public static String subsystemOf(String groupId)
      The subsystem a group belongs to.

      A generated In/Out pair is not in SUBSYSTEMS; it is a pool rate and answers "how much is this service carrying", so it sorts with the other service graphs under the pool subsystem.

      Parameters:
      groupId - a group id, or null
      Returns:
      the subsystem name, or null when the group has none

    • titleOf

      public static String titleOf(String groupId)
      The display name of a group, for use as a combined graph title.

      A generated pair is named after the directionless half the two rates share, with the brackets a pool name carries dropped: [skank.i2p] is already a name, and nesting it inside the title's own brackets reads as markup.

      Parameters:
      groupId - a group id
      Returns:
      the title, never null; an unknown id yields the id itself

    • allGroupsTitled

      public static boolean allGroupsTitled()
      Whether every group has a display name of its own.
      Returns:
      true when the title map covers the registry exactly

    • members

      public static List<String> members(String groupId)
      List the stat names making up a graph group.
      Parameters:
      groupId - a group id, or null
      Returns:
      the member stat names in legend order, or an empty list if unknown

    • groupIds

      public static Set<String> groupIds()
      List every known graph group id.
      Returns:
      every known group id, in display order

    • isPairId

      public static boolean isPairId(String groupId)
      Whether an id names a generated In/Out pair rather than a registry group.
      Parameters:
      groupId - a group id, or null
      Returns:
      true for a generated pair id

    • pairKeyOf

      public static String pairKeyOf(String statName)
      The directionless name the two rates of a pair share.
      Parameters:
      statName - a stat name such as [skank.i2p] InBps
      Returns:
      the shared name, brackets included, or null when the stat is not half of a bandwidth pair

    • counterpartOf

      public static String counterpartOf(String statName)
      The other half of a bandwidth pair, spelled exactly as a stat name.
      Parameters:
      statName - a stat name such as [skank.i2p] InBps
      Returns:
      the counterpart's full stat name, or null when the stat is not half of a bandwidth pair

    • pairGroupIds

      public static Set<String> pairGroupIds(Set<String> enabledStats)
      The In/Out pairs the enabled stats form.

      Only pairs the user has switched on both halves of are returned: a group id for a half-enabled pair would render as an empty tile, and pairing must never turn a single enabled stat into a combined plot. Stats the registry already claims are skipped, so a declared group and a generated one can never cover the same rate.

      Parameters:
      enabledStats - stat names enabled by the user, without period suffixes; null yields no pairs
      Returns:
      the pair ids, in name order; never null

    • allGroupIds

      public static Set<String> allGroupIds(Set<String> enabledStats)
      Every group id that may render for an enabled set: the registry, plus the In/Out pairs those stats form.
      Parameters:
      enabledStats - stat names enabled by the user; may be null
      Returns:
      group ids in display order; never null

    • keyOfPairId

      private static String keyOfPairId(String groupId)
      The group id with the pair prefix removed.
      Parameters:
      groupId - the id to strip
      Returns:
      the rest of the id

    • suffixOf

      private static String suffixOf(String statName)
      The in or out suffix of a stat name.
      Parameters:
      statName - the name to test
      Returns:
      the suffix, null if there is none

    • groupOf

      public static String groupOf(String statName)
      Find the group a stat belongs to.
      Parameters:
      statName - a stat name such as "router.fastPeers"
      Returns:
      the owning group id, or null when the stat is not in any group

    • enabledMembers

      public static List<String> enabledMembers(String groupId, Set<String> enabledStats)
      The enabled members of a group, capped at MAX_SERIES.

      Never null; an empty list means the group has too few enabled members to be worth combining.

      Parameters:
      groupId - a group id
      enabledStats - stat names the user has switched on, without any period suffix
      Returns:
      members that are enabled, in legend order

    • shouldCombine

      public static boolean shouldCombine(List<String> enabledMembers, boolean combine, boolean showEvents)
      Whether a group should be drawn as one plot.

      Requires the opt-in, at least two enabled members, and no event-graph mode: events change what a datasource means, so they are not combined.

      Parameters:
      enabledMembers - result of enabledMembers(String, Set)
      combine - value of PROP_COMBINE
      showEvents - whether the graph page is in event mode
      Returns:
      true when the members collapse into one graph

    • isSuppressed

      public static boolean isSuppressed(String statName, String combined)
      Whether an individual stat's own graph is replaced by its group.
      Parameters:
      statName - the stat being rendered on its own
      combined - the stat name that stands for its group, or null when not combining
      Returns:
      true when this stat must be suppressed in favour of the group plot

    • combinedRepresentatives

      public static Map<String,String> combinedRepresentatives(Set<String> enabledStats, boolean combine, boolean showEvents)
      Work out which stat, if any, stands for each group given the enabled set.
      Parameters:
      enabledStats - stat names enabled by the user
      combine - value of PROP_COMBINE
      showEvents - whether the graph page is in event mode
      Returns:
      group id to the member chosen to carry the group's graph; groups that do not qualify are absent

    • suppressedStats

      public static Set<String> suppressedStats(Set<String> enabledStats, boolean combine, boolean showEvents)
      Every stat drawn on its own after grouping: the enabled stats, minus the members that their group's plot already covers.
      Parameters:
      enabledStats - stat names enabled by the user
      combine - value of PROP_COMBINE
      showEvents - whether the graph page is in event mode
      Returns:
      stats to render individually, order unspecified