跳到主要内容

Darra OPC UA Client — Java SDK

Darra OPC UA Client Java 绑定. 跨语言对齐的高级 API, 你在这里学到的概念可以直接迁移到 C# / Python / C++ / Rust / C, 但 API 命名按 Java 惯例 (camelCase 方法 + try-with-resources + java.util.List 集合).

章节导航

安装​

<dependency>
    <groupId>com.darra</groupId>
    <artifactId>darra-opcua-sdk</artifactId>
    <version>0.6.0</version>
</dependency>

依赖通过 JNA 加载本地 Darra.OpcUa.Core.dll (Windows) / libDarra.OpcUa.Core.so (Linux), 已打包进 jar.

系统要求​

项要求
Java11+ (推荐 17 LTS)
OSWindows 10/11, Windows Server 2019+, Linux (Ubuntu 20.04+)
平台x64
协议OPC UA TCP (opc.tcp://)
内存100MB+ (Stack 自身约 30MB)

包结构​

import com.darra.opcua.*;

主要类型:

类型用途
OpcUaSessionClient 主类 (对应 C# DarraOpcUa)
OpcUaSubscription数据订阅容器
OpcUaEventSubscription事件订阅 (Alarms & Conditions)
NodeCollection / OpcUaNodeLazy Load 节点访问
OpcUaVariant / OpcUaDataValue数据封装 (实现 AutoCloseable)
OpcUaDiscovery (静态)GetEndpoints / FindServers
WellKnownNodes (静态)OPC Foundation 标准节点常量
OpcUaExceptionRuntimeException, 携带 StatusCode
Enums.*StatusCode / NodeClass / AttributeId / MessageSecurityMode / UserTokenType / SessionState / BuiltinType / MonitoringMode

跨语言主类映射​

概念C#Java
Client 主类DarraOpcUaOpcUaSession
构造连接using var ua = new DarraOpcUa(url) + ua.Connect()try (OpcUaSession ua = new OpcUaSession(url)) { ua.connect(); }
数据值容器VariantOpcUaVariant (链式 setXxx)
单点读var dv = ua.Read(nid)OpcUaDataValue dv = ua.read(nid)
事件订阅ua.Events.Connected += hua.events.onConnected.add(consumer)
资源管理usingtry-with-resources
时间类型DateTimejava.time.Instant (内部用 FileTime long)
集合返回IReadOnlyList<T>java.util.List<T>

一分钟快速开始​

import com.darra.opcua.*;

try (OpcUaSession ua = new OpcUaSession("opc.tcp://localhost:4840")) {
    ua.connect();

    // 读
    try (OpcUaDataValue dv = ua.read("ns=2;s=Temperature")) {
        System.out.println("Temperature = " + dv.variant().asDouble() + " °C");
    }

    // 写
    try (OpcUaVariant v = new OpcUaVariant().setDouble(42.0)) {
        ua.write("ns=2;s=Setpoint", v);
    }

    // 订阅
    try (OpcUaSubscription sub = ua.createSubscription(500.0)) {
        sub.add("ns=2;s=Counter", e ->
            System.out.println(e.nodeId + " = " + e.valueString));
        Thread.sleep(3000);
    }
}

高级 API 概览​

功能入口 API说明
连接 / 加密new OpcUaSession(...) + connect()None / Sign / SignAndEncrypt + Username / Anonymous / Certificate
单点读写ua.read / write单节点单 Attribute
批量读ua.readMany(nodes, attr)一次 RPC, N 节点
浏览树ua.browse / browseMany / browseWithPaging / browseNext / browseAll完整分页支持
路径解析ua.resolve / translateBrowsePaths浏览路径 → NodeId
注册节点ua.registerNodes / unregisterNodes高频访问加速 30-50%
数据订阅ua.createSubscription + sub.add / addManypublishing / sampling 双层
事件订阅ua.subscribeEvents报警 & 条件
调方法ua.call(objId, mtdId, ...)OPC UA Method 节点
历史读ua.readHistory / readHistoryModified / readHistoryAtTime / readHistoryProcessed / readHistoryEventsRaw / Modified / AtTime / Processed / Events
历史写ua.updateHistory / deleteHistoryRangeInsert / Replace / Update / Delete
心跳ua.setKeepAliveIntervalMs(int)后台周期探测
自动重连(内置, 通过构造参数 autoReconnect=true)检测断线 → Republish 订阅
统一事件ua.events.onAny.add(...)会话 / 订阅 / 数据 / 通讯异常
服务发现OpcUaDiscovery.getEndpoints / findServers不需要 Session

Java 特有约束​

AutoCloseable 必须 close

OpcUaSession / OpcUaSubscription / OpcUaDataValue / OpcUaVariant 都实现 AutoCloseable, 漏 close 会泄漏 native 内存. 永远用 try-with-resources.

JNA 回调保活

任何注册到 native 的 callback (DataChange / Event / StateChange) 必须由 Java 端持有强引用. SDK 内部已用成员列表保活, 用户只要不显式释放 OpcUaSubscription 就安全.

Swing / JavaFX UI 线程

事件回调在 native Publish 线程上调用. UI 操作必须 SwingUtilities.invokeLater / Platform.runLater 切回 UI 线程.

  • Instant ↔ FileTime: SDK 内部用 Windows FileTime (100ns since 1601 UTC); 历史 API 自动转换 Instant. 自定义 DateTime Variant 时用 setDateTime(long fileTime) 直接传 FileTime
  • OpcUaException 是 RuntimeException: 不强制 try-catch, 业务层按需捕获
  • 没有 event += 语法: 用 events.onConnected.add(consumer) / events.onConnected.remove(consumer)

跨语言对齐​

C# SDK 的 API 命名 / 行为是其他语言绑定的参考实现. Java 绑定按 Java 命名惯例 (camelCase, getXxx getter), 但语义一致 (例如 C# ua.Read ↔ Java ua.read ↔ Python ua.read). 选 Java 作为入门, 后续切其他语言时只需查 跨语言映射.

按左侧侧边栏顺序读完即可掌握全部 SDK API.