org.jenkinsci.plugins.pubsub

Class Message<T extends Message>

java.lang.Object

java.util.Dictionary<K,V>

java.util.Hashtable<Object,Object>

java.util.Properties

org.jenkinsci.plugins.pubsub.Message<T>

All Implemented Interfaces:

Serializable, Cloneable, Map<Object,Object>

Direct Known Subclasses:

EventFilter, JobChannelMessage, SimpleMessage

public abstract class Message<T extends Message>
extends Properties

PubsubBus message instance.

Light-weight messages

We purposely chose a very simple Properties based 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 (the default bus implementation is not distributed, but one could implement one) asynchronous libraries. 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.

Note the AccessControlledMessage subtype.

Event property namespaces

Event property names are opaque Strings. Any String is valid, but we do recommend using valid underscores to namespace e.g. "a_b_c". This will help to avoid name collisions.

NOTE that the "jenkins" namespace prefix of reserved e.g. "jenkins_channel".

Author:

tom.fennelly@gmail.com

See Also:

Serialized Form

Field Summary

Fields inherited from class java.util.Properties

defaults

Method Summary

Modifier and Type	Method and Description
Message	clone() Clone this Message instance.
boolean	containsAll(Properties properties) Does this message contain all of the properties supplied in the properties argument.
String	get(Enum name) Get the named message property value (by enum).
String	get(String name) Get the named message property value.
String	getChannelName() Get the channel name for the message.
String	getEventName() Get the event name for the message.
String	getEventUUID() Get the event UUID for the message.
String	getJenkinsInstanceId() Get the Jenkins instance identity of the master from which the event was published.
String	getJenkinsInstanceUrl() Get the Jenkins instance URL of the master from which the event was published.
protected String	getObjectId() Get the Jenkins domain model object Id that this message instance is associated with.
protected String	getObjectName() Get the Jenkins domain model object name (full name) that this message instance is associated with.
protected String	getObjectType() Get the Jenkins domain model object type that this message instance is associated with.
String	getTimestamp() Get the event timestamp for the message.
Long	getTimestampMillis() Get the event timestamp for the message, as a long.
T	set(Enum name, String value) Fluent property setter (by enum).
T	set(String name, String value) Fluent property setter.
T	setChannelName(String name) Set the channel name for the message.
T	setEventName(Enum name) Set the event name for the message.
T	setEventName(String name) Set the event name for the message.
protected T	setItemProps(hudson.model.Item item) Set Item propertis on the message instance.
T	setJenkinsInstanceId() Set the Jenkins instance identity of the master from which the event was published.
String	toJSON() Write the message properties to JSON.
void	toJSON(Writer writer) Write the message properties as JSON to a Writer.
String	toString() Same as toJSON().

Methods inherited from class java.util.Properties

getProperty, getProperty, list, list, load, load, loadFromXML, propertyNames, save, setProperty, store, store, storeToXML, storeToXML, stringPropertyNames

Methods inherited from class java.util.Hashtable

clear, compute, computeIfAbsent, computeIfPresent, contains, containsKey, containsValue, elements, entrySet, equals, forEach, get, getOrDefault, hashCode, isEmpty, keys, keySet, merge, put, putAll, putIfAbsent, rehash, remove, remove, replace, replace, replaceAll, size, values

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

getObjectName

@CheckForNull
protected String getObjectName()

Get the Jenkins domain model object name (full name) that this message instance is associated with.

Returns:

The Jenkins domain model object name (full name) that this message instance is associated with.

See Also:

EventProps.Jenkins.jenkins_object_name

getObjectType

@CheckForNull
protected String getObjectType()

Get the Jenkins domain model object type that this message instance is associated with.

Returns:

The Jenkins domain model object type that this message instance is associated with.

See Also:

EventProps.Jenkins.jenkins_object_type

getObjectId

@CheckForNull
protected String getObjectId()

Get the Jenkins domain model object Id that this message instance is associated with.

Returns:

The Jenkins domain model object Id that this message instance is associated with, or null if no id was set on this message instance.

See Also:

EventProps.Jenkins.jenkins_object_id

set

public T set(String name,
             String value)

Fluent property setter.

Same as Properties.setProperty(String, String), but returns this. Also checks for null name and value args.

Parameters:

name - Property name.

value - Property value.

Returns:

this message instance.

set

public T set(Enum name,
             String value)

Fluent property setter (by enum).

Parameters:

name - Property name enum.

value - Property value.

Returns:

this message instance.

get

public String get(String name)

Get the named message property value.

Parameters:

name - Propery name.

Returns:

The property value, or null if not defined.

get

public String get(Enum name)

Get the named message property value (by enum).

Parameters:

name - Propery name enum.

Returns:

The property value, or null if not defined.

getChannelName

public String getChannelName()

Get the channel name for the message.

Returns:

The channel name for the message, or null if none set.

setChannelName

public T setChannelName(String name)

Set the channel name for the message.

Parameters:

name - The channel name for the message.

getEventName

public String getEventName()

Get the event name for the message.

Returns:

The event name for the message, or null if none set.

setEventName

public T setEventName(String name)

Set the event name for the message.

Parameters:

name - The event name for the message.

setEventName

public T setEventName(Enum name)

Set the event name for the message.

Parameters:

name - The event name for the message.

getJenkinsInstanceUrl

public String getJenkinsInstanceUrl()

Get the Jenkins instance URL of the master from which the event was published.

Returns:

The Jenkins instance identity.

See Also:

getJenkinsInstanceId()

getJenkinsInstanceId

public String getJenkinsInstanceId()

Get the Jenkins instance identity of the master from which the event was published.

Note that this is not automatically added to every event since the identity key is quite large, adding a lot of weight to each event. To add the identity to all messages, simply implement a MessageEnricher and use it to call setJenkinsInstanceId().

Maybe getJenkinsInstanceUrl() will do the trick for you in terms of working out the origin of an event.

Returns:

The Jenkins instance identity.

See Also:

getJenkinsInstanceUrl()

setJenkinsInstanceId

public T setJenkinsInstanceId()

Set the Jenkins instance identity of the master from which the event was published.

getTimestamp

public String getTimestamp()

Get the event timestamp for the message.

Returns:

The event timestamp for the message, or null if none set.

getTimestampMillis

public Long getTimestampMillis()

Get the event timestamp for the message, as a long.

Returns:

The event timestamp for the message, or null if none set.

getEventUUID

public String getEventUUID()

Get the event UUID for the message.

Returns:

The event UUID for the message, or null if none set.

setItemProps

protected T setItemProps(@Nonnull
                         hudson.model.Item item)

Set Item propertis on the message instance.

Parameters:

item - The Jenkins Item.

clone

public Message clone()

Clone this Message instance.

Base implementation creates a SimpleMessage instance.

Overrides:

clone in class Hashtable<Object,Object>

Returns:

The clone.

containsAll

public boolean containsAll(@Nonnull
                           Properties properties)

Does this message contain all of the properties supplied in the properties argument.

Parameters:

properties - The properties to check for.

Returns:

true if this message contain all of the properties supplied in the properties argument, otherwise false.

toJSON

@Nonnull
public final String toJSON()

Write the message properties to JSON.

Returns:

The message properties as a String.

toJSON

public final void toJSON(@Nonnull
                         Writer writer)
                  throws IOException

Write the message properties as JSON to a Writer.

Parameters:

writer - The Writer instance.

Throws:

IOException - Error writing to the Writer.

toString

public final String toString()

Same as toJSON().

Overrides:

toString in class Hashtable<Object,Object>

Returns:

The message properties as a JSON String.