redb Route XML

Editor support for redb.Route XML routes in VS Code: completion and validation from the format's schema, a route tree, composite skeletons, bean reference hints and a graph editor over the XML text.

The format does not need an editor. A route file is plain XML that the runtime loads as it is; this extension only makes writing and reading it easier.

Features

Schema: completion and validation

Completion of elements, attributes and enum values, and validation as you type, for every element of the format and for the typed options of every connector (<kafka topic>, <sql dataSource>, <as4 path> and so on). The schema also knows which side an option belongs to: an option that only a consumer takes is accepted inside <from> and refused inside <to>.

The work is done by Red Hat XML reading the schema this extension ships. The binding goes by namespace, not by file name: a document gets the schema because its root element declares urn:redb:route:1.0. Any other XML file, including someone else's route.xml, is left alone.

Skeletons

Composite inserts the schema cannot offer, served only in redb route documents and only where a new element may start:

Single elements come from the schema completion.

Bean references

Typing # where a value names a registry object lists the <bean name> declarations of the current document. This works in three places: the whole attribute value (dataSource="#"), the path right after the scheme (bean:#) and a URI option value (?headerFilterStrategy=#). A # inside other text, such as the SQL parameter :#name, is not a reference and gets no hint.

The list is not filtered by type. A reference to a bean that is not declared, or of the wrong type, is reported by redb-route-xml check and redb-route-xml pack.

Route tree

The redb Routes view in the Explorer lists every routes document of the workspace, with the id and the from endpoint of each route. A click opens the route at its line. The view appears when the workspace has at least one *.route.xml or *.redb-route.xml file.

Route graph

Open With... > redb Route Graph, the graph button in the editor title, or redb Route: Open Route Graph from the Command Palette opens the route file as a graph. The graph is a second view of the same text: every edit in it is an edit of the XML, and undo works as in the text editor.

• Reading. Every step is a tile of one size with a glyph and a short caption (from, bean, sql, set, choice, loop, log...). The tooltip and the properties panel show what the step does: the property name, the condition, the SQL. Wrappers (metered, loop, split, a transaction) put their steps on the route's line between their own tile and an end tile; choice, tryCatch and filter fan out into branches. A run of setHeader or setProperty steps is one tile set ×N.
• Paths. Conditional paths are dashed: orange where a message goes past a step (filter not passed, no match, duplicate), grey with a cross where it is dropped (sample, debounce), red where a step raises (catch, onException, error).
• Colors. Green where a message comes in, blue where it goes out, purple your code (bean), orange data changes, cyan routing, grey observation, red errors.
• Editing. Insert a step from the palette at any + between steps, delete with Delete, drag a step to reorder it or to move it into or out of a container, rename an element, edit attributes and child texts in the properties panel.
• Endpoints. For a step with a URI the panel splits it into the scheme, the path and the options of that connector, with enum values offered as a list. A sensitive option (a password, a key) is masked and cannot be edited from the panel.
• Placeholders. A {{key}} or {{key:default}} value is shown together with what it resolves to, read from context.sample.json and config/*.json found next to the route file or in up to three folders above it. The edit always keeps the placeholder.
• Layout. The toolbar switches left to right or top down, folds or unfolds every container at once, zooms and switches the tile look (glyph over the caption or beside it). A route folds to its title with the arrow before its name.

Mermaid diagram

redb Route: Show Mermaid Diagram renders the current route file as a Mermaid diagram with the redb-route-xml .NET tool:

dotnet tool install -g redb.Route.Xml.CodeGen

This is the only feature that needs .NET on the machine.

Requirements

• Red Hat XML (redhat.vscode-xml). VS Code installs it together with this extension when it has network access.
• The redb-route-xml .NET tool, only for the Mermaid diagram.

Installation

From the Visual Studio Marketplace: in the Extensions view search for redb Route XML and click Install, or open the extension page. From a terminal: code --install-extension redb.redb-route-xml. VS Code then keeps the extension up to date.

Every redb.Route release also carries the extension as a file, for a machine without access to the Marketplace or to pin a version:

1. Open the releases of redb-route, pick the version you use and download redb-route-xml-<version>.vsix from its assets.
2. In VS Code: Extensions view > ... > Install from VSIX... > the downloaded file. From a terminal: code --install-extension redb-route-xml-<version>.vsix.
3. Run Developer: Reload Window. A graph tab opened before an update keeps the old view until it is closed and opened again.

On a machine without network access, download the Red Hat XML .vsix from its Marketplace page and install it first, the same way.

Settings

The extension has no settings of its own. It registers its XML catalog with Red Hat XML through that extension's API. With an older Red Hat XML that has no such API, it adds the catalog to the user setting xml.catalogs once.

Documentation

• redb.Route.Xml: the XML format, elements, endpoints, beans, the context document.
• Schema and editor support and tooling: the schemas, check, pack and the code generator.

Development

npm install
npm run compile
npm test

npm test runs the unit tests with node:test, without VS Code. Press F5 to start an Extension Development Host with the extension loaded.

The files in media/ other than the graph's script and styles are generated by the redb-route-xml tool from the built connector assemblies (catalog, elements and xsd commands). They are not edited by hand.

License

Apache License 2.0.

Credits

The graph glyphs follow the notation of Enterprise Integration Patterns by Gregor Hohpe and Bobby Woolf (enterpriseintegrationpatterns.com, pattern icons under CC BY 4.0), redrawn as 24×24 line icons. Steps the notation has no symbol for are drawn in the same style.