Client Browsing

Use references to discover nodes, and browse paths to locate a known model member. Start from a connected client and a known NodeId such as NodeIds.ObjectsFolder.

Milo 1.2.0-SNAPSHOT, Java 17. Source baseline 7faaf4f0516c.

Browse with AddressSpace and UaNode

client.getAddressSpace().browse(nodeId) returns ReferenceDescription entries. getNode(nodeId).browse() provides the same operation from a node wrapper. These helpers collect continuation pages, but stop on a non-Good Browse/BrowseNext operation status and return the references collected so far. An unknown starting node can therefore yield an empty list without an exception. Use client.browse(...) and browseNext(...) when completeness or per-node status matters. browseNodes() also constructs client-side wrappers, which can require additional service reads; it logs and omits references whose wrapper creation fails. Use reference descriptions when names and NodeIds are sufficient.

A reference supplies direction, reference type, BrowseName, DisplayName, NodeClass, target ExpandedNodeId, and type definition according to the result mask. BrowseName is namespace-qualified; DisplayName is localized presentation text and is not a durable key. A target may be remote or use a namespace URI. Resolve an ExpandedNodeId with the client's namespace/server context instead of discarding those qualifiers.

The default browse options use forward hierarchical references including subtypes. Use BrowseOptions to select direction, reference type, subtype inclusion, node-class mask, result mask, and maximum references per node. This helper requests properties of the standard Server Object and asks for one reference per response page. The returned list includes all pages.

static List<ReferenceDescription> browseProperties(OpcUaClient client) throws UaException {
  AddressSpace.BrowseOptions options =
      AddressSpace.BrowseOptions.builder()
          .setReferenceType(NodeIds.HasProperty)
          .setIncludeSubtypes(true)
          .setMaxReferencesPerNode(uint(1))
          .build();
  return client.getAddressSpace().getNode(NodeIds.Server).browse(options);
}

Own continuation points at the service level

Use client.browse(view, maxReferencesPerNode, descriptions) when you need page-by-page control. Validate the service response and each BrowseResult.statusCode. Read its references and opaque continuationPoint; a successful empty reference array does not justify ignoring a nonempty continuation point.

Pass outstanding points to client.browseNext(false, points) and repeat until each point is empty. Track each starting node separately when browsing a batch. A response can replace a point, so retain the latest returned point rather than reusing the original indefinitely.

If traversal stops early, call browseNext(true, points) in cleanup and inspect the release service result. BrowseNext release responses do not provide ordinary per-node browse data. Points consume server resources and belong to a Session. Do not persist them or transfer them to another client. After Bad_ContinuationPointInvalid, restart the affected browse if appropriate and deduplicate already processed results. Limit traversal depth, total references, and concurrent points; the address space is a graph, so following references recursively needs a visited set.

Translate a browse path

Build a BrowsePath from a starting NodeId and a RelativePath. Each RelativePathElement specifies the reference type, inverse/forward direction, subtype inclusion, and namespace-qualified target BrowseName. Submit paths with client.translateBrowsePaths(...) or its async counterpart.

For example, from NodeIds.Server, a forward HasProperty step to namespace-zero BrowseName NamespaceArray locates NodeIds.Server_NamespaceArray. This relationship is exercised by the local fixture. A nonexistent BrowseName produces Bad_NoMatch.

Inspect every BrowsePathResult and its targets. Paths can resolve to multiple targets or be only partially resolved. remainingPathIndex indicates an unresolved suffix; the maximum UInt32 sentinel means the whole path was resolved. Check it before treating a target as the final node. Qualified names for vendor nodes require the server's current namespace indexes. Translation follows references and BrowseNames, not a slash-separated NodeId string.

Errors and ownership

An unknown starting node, inaccessible node, or unsupported view can fail an operation while another succeeds. Blocking helpers throw UaException; async helpers complete exceptionally for service/helper failures. AddressSpace browsing can still return partial or empty lists for operation failures; the raw response APIs retain per-operation statuses and give explicit cursor control. High-level service calls set ReturnDiagnostics=0. To request DiagnosticInfos, build a request with a RequestHeader diagnostics mask and use sendRequest(...) or sendRequestAsync(...); a server may still omit diagnostics. AddressSpace node wrappers are client cache entries, not server resources; explicit service continuation points remain your responsibility.

Examples and reference

• BrowseExample: Browse raw references on the local ExampleServer.

• BrowseNodeExample: Browse using client node wrappers.

• TranslateBrowsePathExample: Translate a modeled browse path to its NodeId.

• Runnable fixture: WikiClientGuideTest

• AddressSpace and browse options

• Browse and TranslateBrowsePaths APIs

• BrowseHelper paging

Related pages

Client SDK · Client nodes · OPC UA concepts