程序包 com.darra.ethercat.sugar

类 MasterStreams

java.lang.Object
com.darra.ethercat.sugar.MasterStreams
public final class MasterStreams extends Object
Java 8+ Stream API + Optional 语法糖.

Java SDK 主线 EtherCATMaster.Slaves() 返回 List<Slave>, 可 直接 .stream() 但缺少常见过滤/分组/索引 helper. 本类以静态工厂方法暴露 这些常用操作, 不修改主类、不持有状态、不破坏 API 兼容性.

典型用法:

 // 1. 过滤 OP 状态的从站
 List<Slave> opSlaves = MasterStreams.slavesInState(master, EcState.OP)
         .collect(Collectors.toList());

 // 2. Optional 风格的查询 (避免 IndexOutOfBoundsException)
 MasterStreams.slaveOpt(master, 5).ifPresent(s -> System.out.println(s.Name()));

 // 3. 把从站按 1-based 序号组织成 Map (供随机访问)
 Map<Integer, Slave> idx = MasterStreams.slavesAsMap(master);
 Slave s3 = idx.get(3);

 // 4. 按 Group 字节聚合
 Map<Byte, List<Slave>> byGrp = MasterStreams.slavesByGroup(master);

所有方法对 null/越界/已释放的主站都返回**空** Stream/Optional/Map, 不抛异常 — 调用者无需自己 try-catch.

从以下版本开始:
2026-05

  • 方法详细资料

    • slaves

      public static Stream<Slave> slaves(EtherCATMaster master)
      从 Master 获取从站 Stream. 等价于 master.Slaves().stream(), 但额外做 null/disposed 防御.

      对应任务"Stream<Slave>: master.slaves().stream()".

      返回:
      从站 Stream, master == null 时返回空 Stream

    • slavesInState

      public static Stream<Slave> slavesInState(EtherCATMaster master, EcState state)
      过滤指定 EtherCAT 状态的从站.

      典型用法: 监控全网 OP 后哪些没进入 OP — 

       MasterStreams.slavesInState(m, EcState.SAFE_OP).forEach(s ->
     System.err.println("Stuck in SafeOp: " + s.Name()));
      参数:
      state - 期望状态 (NONE 时返回空 Stream — 业务上 NONE 通常表示掉线)

    • slavesNotInState

      public static Stream<Slave> slavesNotInState(EtherCATMaster master, EcState state)
      过滤**不在**指定状态的从站. 与 slavesInState(com.darra.ethercat.master.EtherCATMaster, com.darra.ethercat.data.EcState) 互补.

    • slavesByVendor

      public static Stream<Slave> slavesByVendor(EtherCATMaster master, int vendorId)
      过滤指定 VendorId 的从站. 用于多厂商混布场景按品牌分类.
      参数:
      vendorId - 厂商 ID (0 即匹配所有, 行为同 slaves(com.darra.ethercat.master.EtherCATMaster))

    • slavesByName

      public static Stream<Slave> slavesByName(EtherCATMaster master, String namePart)
      过滤包含指定子串的从站名 (大小写敏感).

    • lostSlaves

      public static Stream<Slave> lostSlaves(EtherCATMaster master)
      过滤已经丢失/掉线的从站.

    • dcCapableSlaves

      public static Stream<Slave> dcCapableSlaves(EtherCATMaster master)
      过滤所有支持 DC 的从站.

    • slaveOpt

      public static Optional<Slave> slaveOpt(EtherCATMaster master, int slaveIndex)
      安全获取指定 1-based 编号的从站, 返回 Optional.

      主线 master.getSlave(idx) 越界时抛 IndexOutOfBoundsException. 此 helper 用 Optional 包装, 适合不确定从站是否存在的轮询逻辑.

      参数:
      slaveIndex - 从站 1-based 索引

    • findByName

      public static Optional<Slave> findByName(EtherCATMaster master, String name)
      按名称 (精确等于) 查找首个匹配从站.

    • findByConfigAddr

      public static Optional<Slave> findByConfigAddr(EtherCATMaster master, short configAddr)
      按配置地址查找 (config_addr 在 EtherCAT 网络上唯一).

    • findByIdentity

      public static Optional<Slave> findByIdentity(EtherCATMaster master, int vendorId, int productCode)
      按 (vendorId, productCode) 查找首个从站. Stream 方式做的, 短路.

    • slavesAsMap

      public static Map<Integer,Slave> slavesAsMap(EtherCATMaster master)
      把所有从站按 1-based 序号组织成 Map, 适合需要 O(1) 随机访问的场景.

      对应任务"Map<Integer, Slave> 字典视图". 返回的是不可变快照, 后续 master 拓扑变化不会反映. 如需实时, 调用方自己缓存并重新拉.

      返回:
      不可变 Map, 主站为空时返回空 Map

    • slavesByGroup

      public static Map<Byte,List<Slave>> slavesByGroup(EtherCATMaster master)
      按 Group 字节分组. Group 通常 0..7, 业务可用 group 0 / group 1 区分快慢任务.
      返回:
      不可变 Map<Byte, List<Slave>>

    • slavesByState

      public static Map<EcState,List<Slave>> slavesByState(EtherCATMaster master)
      按 EcState 分组, 用于一次性诊断 "网络上有多少从站卡在哪个状态".

    • stateCounts

      public static Map<EcState,Long> stateCounts(EtherCATMaster master)
      按 EcState 计数. 配合 UI 仪表盘.

    • slavesAsNavigableMap

      public static NavigableMap<Integer,Slave> slavesAsNavigableMap(EtherCATMaster master)
      按 1-based 序号排序的 NavigableMap, 支持 firstKey/lastKey/floor/ceiling. 适合游标式遍历 "找下一个 OP 从站" 这种业务.

    • slavesByVendorId

      public static Map<Integer,List<Slave>> slavesByVendorId(EtherCATMaster master)
      按 vendorId 分组. 多厂商混布快速诊断.