Develop JMS

JMS Application Development

This guide shows how to build a JMS application that subscribes to content from Elastic MDS. Elastic MDS is a JMS provider: you use the standard JMS API - either the javax.jms or the jakarta.jms namespace is supported - and the MetaFluent provider supplies the connection factory, connection, session, and subscriptions.

Audience: Java developers (the same model applies to the .NET and C bindings). No prior MetaFluent knowledge assumed.

Applications written for MetaFluent v5 run unchanged - see Compatibility with v5.

---

The SDK

The provider and the example applications ship in the MetaFluent JMS SDK (jms-sdk). The default clone gives the latest release:

git clone --depth 1 git@github.com:MetaFluent/jms-sdk.git

To use a specific release, clone its tag instead - for example -b RELEASE-v6.0.0. Release tagging conventions are described in Release Notes & Compatibility.

The SDK contains:

• lib/metafluent.jms.jar - the JMS provider. Add this one jar to your classpath to build against Elastic MDS. It includes both the javax.jms and jakarta.jms interfaces, so you do not need a separate JMS API jar and can develop against either namespace.
• examples/src/... - the source for the example applications, including SimpleSubscriber. A jakarta.jms version of SimpleSubscriber is also provided.
• bin/*.jar - the examples prebuilt, so you can run them without building.

---

A first subscription

SimpleSubscriber (in the SDK) is a complete, console-based subscriber. Its structure is the standard JMS pattern:

1. Create a TopicConnectionFactory from the MetaFluent provider, given the address of the session server.
2. Set the context the session will use (see Addressing content).
3. Create a TopicConnection and a TopicSession.
4. For each topic, create a Topic and a TopicSubscriber, and register a MessageListener.
5. Start the connection.

Run the prebuilt subscriber against a running deployment, subscribing to one instrument:

java -cp "bin/SimpleSubscriberApplication.jar:lib/*" \
     com.metafluent.examples.simplesub.SimpleSubscriber \
     -connect mf-session:8900 -context com.metafluent.jms_context.mds RDF.VOD.L

mf-session is the conventional name for the session server your application connects to. Map it to your deployment's session host - the same way the Quick Start maps mf-api-gateway - or use the host:port your operator gives you. (On the single-host Quick Start the session server runs on your own machine, so localhost:8900 works there.)

The subscriber prints an Image: line (the initial field values) followed by UPDATE: lines as the values change. Read SimpleSubscriber.java for the full, commented source.

---

Addressing content: contexts and topic names

An application names the content it wants with a JMS topic. How a topic name is interpreted is decided by the context the application selects - the value passed as -context (or set as the com.metafluent.jms.client.Properties.ContextName system property). There are two contexts.

The v5 context (default, compatible)

Pass com.metafluent.jms_context.mds (or leave the context unset - the provider's built-in default is com.metafluent.jms_context.mds-2). Topic names use the v5 feed.symbol form, and the Quotes schema is implied:

Topic	Resolves to
RDF.VOD.L	schema Quotes, feed RDF, key VOD.L
chain.RDF.0#.FTSE	schema Chains, feed RDF, chain 0#.FTSE

This is exactly the v5 grammar. Existing applications keep working with no change.

The MarketData context (explicit, generic)

Pass MarketData-6.0.0. Topic names are schema-qualified - you name the schema explicitly - in exchange for a more general addressing model.

Two capabilities are worth calling out. First, you can subscribe to a whole table or view by name - for example a saved portfolio view - and receive every row it contains, rather than naming a single instrument. Second, a single subscription can name several keys at once (a multi-key, or multi-stream, subscription), so one topic delivers a set of instruments. Both appear in the examples below.

Topic	Resolves to
Quotes.RDF.VOD.L	schema Quotes, table RDF, key VOD.L (a single instrument)
Quotes.MyPortfolioView	every row of the MyPortfolioView view (table-level subscription)
Quotes.RDF.?KEY_=VOD.L,BT.A,BARC.L	one subscription over several keys (multi-stream)
Chains.RDF.0#.FTSE	schema Chains, table RDF, chain 0#.FTSE

Note. The bare-feed shorthand (RDF.VOD.L, chain.RDF.0#.FTSE) is understood only under the v5 context. Under MarketData-6.0.0 you must write the schema-qualified form (Quotes.RDF.VOD.L); the bare form would be read as schema.table.key and would not name the same content.

---

Selectors

A subscription can carry a selector that controls what you receive. With a selector, an application receives only the fields it needs, which reduces the bandwidth used and the CPU consumed on both the server and the client. The selector is passed when the subscriber is created (the -selector option in SimpleSubscriber) - for example -selector "BID, ASK" to receive just the bid and ask.

A selector can do more than choose fields:

• Rename a field with AS - -selector "BID,ASK,TRDPRC_1 AS LAST".
• Compute a derived field with an expression - -selector "BID,ASK,ASK-BID AS SPREAD".
• Constrain the update stream with a WHERE clause, so an update is delivered only when the condition holds - -selector "BID,ASK,TRDPRC_1 WHERE TRDVOL_1 > 10000".

Selectors work the same way under either context, so a v5 application on the com.metafluent.jms_context.mds context can use them without moving to the MarketData context.

---

Message types

Content is delivered as JMS MapMessages. Each message carries a type, which the application reads from a message property and dispatches on (as SimpleSubscriber does):

• Image - the initial, complete set of field values for a topic, sent when the subscription is established.
• Update - a subsequent change to one or more field values.
• Status - a change in the state of the data stream: OK, STALE (the source may be disconnected), CLOSED, DENIED (not entitled), or INVALID (the request could not be satisfied).

Interpreting these messages correctly - the field and property conventions, the message-type and state codes, and how to read the field values - is covered in detail in Dynamic Data Conventions. The com.metafluent.jms.common.DynamicDataConventions class defines the property names and type codes used throughout.

---

Entitlements

Access to content is governed by entitlements. Elastic MDS makes no change to the entitlements model - an application's access is controlled exactly as it was in v5, including the separate entitlements context used for access-control. See Security & Entitlements.

---

Compatibility with v5

Applications written for MetaFluent v5 run unchanged. Keep passing the com.metafluent.jms_context.mds context (or leave it unset) and the v5 feed.symbol topic grammar applies exactly as before. There is one parser, and the v5 grammar is a strict part of it - it does not drift.

What Elastic MDS (v6) adds is available on your terms:

• Selectors work with the v5 context, so you can adopt them without changing anything else.
• The MarketData context is an explicit opt-in for schema-qualified, generic addressing (arbitrary schemas, tables, views, and multi-key subscriptions).

---

Where to go next

• Dynamic Data Conventions - interpreting the data in the messages you receive.
• Architecture: Basics - the model behind the API.
• Glossary - definitions of the terms used here.
• JDBC Application Development - query the same content over JDBC.