JAM - examples

Despite its inner complexity and the multifaceted possibilities the JAM framework provides, its usage is in most cases as quick and easy as simply calling any regular method. It is designed for convenience and ease, performance and power and complexity kept under the hood. JAM can mediate defined announcements as well as any arbitrary object from any place in your system to any other place in your system, allowing your system to react in one place directly on events that happen in another place, with full flexibility and high performance. JAM can speed up your system in many cases.

Note: the mediation from a publisher to a subscriber will circumvent a traditional n-tier architecture in most cases - on purpose. This does not mean the information flow through JAM is unstructured or less orchestrated. Its the opposite. With JAM you can use complex topics with endless possibilites to orchestrate your information flows, but topics provide a way way higher flexibility and ease than tiers.

Let's see first a few very simple examples here, how to use JAM in practice. First we see how we can publish simple stuff. JAM comes with several API with different flavors (and we can extend JAM with our own API if we like). On the publishers side we can use e.g.

• Publish (static methods, single threaded), best for simple cases
• PublishParallel (static methods, multithreaded), best for simple concurrent cases
• Composition (fluent API, single threaded), best for complex cases
• ParallelComposition (fluent API, multithreaded), best for complex concurrent cases
• MessageQuery, API to retrieve complex messages for individual processing
• Specification, complementary API to specify a required compliance and demanded objects
• Ref, API for direct value change propagation, including value change vetos
• Distribute, specialized API to pull or push data as chunks and on demand
• DistributeParallel, specialized API to pull or push data concurrently as chunks and on demand
• etc.

We can publish a simple text like this:

Publish.text("Hello world!");

We can add a severity (aka log level) like INFO:

Publish.info("Hello world!");

Which is the same as:

Publish.text("Hello world!", Severity.INFO);

In all 3 examples above the topic will be choosen automatically. For the first one its the RootTopic.TEXT, for example 2 and 3 its the RootTopic.INFO_TEXT. To choose a topic manually we have to use a fluent API (Composition, ParallelComposition) which we discuss later on.

Note: JAM provides more topic classes with automatic topic detection, including dynamic and generic topics.
 

If we wish that JAM mediates concurrently, we simply replace Publish by PublishParallel:

PublishParallel.text("Hello world!");

It is important to know that the topic choosen for a concurrent process is never the same as the topic choosen for a single threaded process, even if the topic name is the same!

Note: depending on our use case and architecture we might have to configure the concurrency in JAM to make it work as we expect. That is too complex to discuss it at this stage.

Before proceeding to complex messages and more complex stuff, let's see already how we can receive our simple text announcements on the other side, the side of the subscribers.

By default, JAM is already initialized with a few subscriptions, so for some basic functionalities JAM works out of the box, but for our examples above the only relevant subscriber is the AnnouncementPrinter. The AnnouncementPrinter simply writes all announcements he receives to the "standard" output stream (usually the console). The AnnouncementPrinter accepts the following announcement types:

• TextOffer (asynchronous announcement of simple text)
• MessageOffer (asynchronous announcement of complex messages)
• ThrowableOffer (asynchronous announcement of Throwable objects)