Package org.jenkinsci.plugins.pubsub

Class Message<T extends Message>

java.lang.Object
java.util.Dictionary<Object,Object>
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:

  • Method Details

    • 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:

    • 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:

    • 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:

    • 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 controller from which the event was published.
      Returns:
      The Jenkins instance identity.
      See Also:

    • getJenkinsInstanceId

      public String getJenkinsInstanceId()
      Get the Jenkins instance identity of the controller 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:

    • setJenkinsInstanceId

      public T setJenkinsInstanceId()
      Set the Jenkins instance identity of the controller 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 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 Properties
      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 Properties
      Returns:
      The message properties as a JSON String.