Jenkins Pub-Sub "light" Bus 1.18 API

A light-weight Publish-Subscribe (async) event notification module for Jenkins.

Light-weight messages

We purposely chose a very simple Properties based (name-value pairs) extension for the message type, so as to avoid marshal/unmarshal issues with more complex message type (the PubsubBus implementation could be distributed). It is also hoped that this approach will promote the use of very light-weight event messages that contain "just enough" information as to allow ChannelSubscribers to decide if they are interested in the event (or not). If they are interested in the event, they can use standard Jenkins mechanisms to gain access to the full domain model object(s) relating to the event.

Note that the use of lose typing is very intentional as complex types are a notorious source of problems in distributed asynchronous messaging middleware. Also consider that this should not be a major inconvenience if you stick with light-weight events i.e. sending complex/bloated events is already considered as being an anti-pattern here.

Pre-defined Events and EventProps

As stated above, this library assumes light-weight Properties based (name-value pairs) messages, where the names and values are opague/untyped Strings.

For this reason, we have defined a few types that we hope will help us to standardize on some of the property names used in the messages.

Please try to use this property name types. If you find you need to create messages that are not covered by the properties defined here, and you think that the properties are likely to be needed by others, then please create a PR on the GitHub repo so we can create a standardized name for the property.

Anti-patterns

The main one is: DO NOT ADD LOTS OF PROPERTIES TO MESSAGE. Please keep them as light-weight events with a small few properties i.e. just enough for the ChannelSubscriber (see below) to be able to determine if it is interested in the event data and to be able to get it (e.g. EventProps.Jenkins.html.jenkins_object_url - see below).

Publishing to an event Channel

PubsubBus bus = PubsubBus.getBus();

bus.publish(new RunMessage(run)
            .setEventName(Events.JobChannel.run_started));

Subscribing to an event Channel

PubsubBus bus = PubsubBus.getBus();

bus.subscribe(Events.JobChannel.NAME, new ChannelSubscriber() {
        
        public void onMessage(@NonNull Message message) {
            if (message instanceof RunMessage) {
                RunMessage jobMessage = (RunMessage)message;
                String jobName = jobMessage.getJobName();
                String runId = message.getId();
                
                // etc etc
            }
        }
    }, 
    User.current(), // Used for authentication 
    new EventFilter().setEventName(Events.JobChannel.run_started) // Event filter (optional)
);
Packages 
Package Description
org.jenkinsci.plugins.pubsub  
org.jenkinsci.plugins.pubsub.listeners
Jenkins Listener implementations.