Package lumis.portal.monitor

Interface IMonitor

  • All Superinterfaces:
    AutoCloseable
    @StableMinor(version="14.0",
             sinceVersion="9.0")
public interface IMonitor
extends AutoCloseable
    A monitor that allows the collection of data related to a specific event. The monitor implementation is not thread safe and its instance should not be cached between event occurrences. But the same instance should be used during a single event occurrence.

    The monitoring data will be saved:

    • If this monitor is not bound to a transaction, when this monitor is closed.
    • If this monitor is bound to a transaction, when this monitor is closed and the transaction ends (either by a successful commit or by a rollback).

    Either way, the save action will be a non-thread-blocking action (it will happen in a background processing). Also, the save action might not be performed immediately.

    Example for monitoring an event that is unbound to a transaction: 

     try(IMonitor monitor = ManagerFactory.getMonitorManager().monitor("myEventKey"))
 {
        // add some monitoring values
        monitor.addValues("myField", value);
        monitor.addValues("myOtherField", otherValue);
 }
    In this case, the monitoring data will be saved when the monitor is closed.

    Example including duration measure and transaction awareness: 

     try(ITransaction transaction = ...)
 {
        transaction.begin();
        ...
        try(IMonitor monitor = ManagerFactory.getMonitorManager().monitor("myEventKey", transaction);
        {
                monitor.start();
 
                ...
 
                // if wanted, other monitoring values may be added:
                monitor.addValues("myField", value);
        }
        transaction.commit();
 }
    In this case, the monitoring data will be saved when the transaction is commited (or rolledback) and the monitor is closed.

    The monitoring data is stored in the form of value providers, which are responsible for providing monitor data when required.
    Thus, even when calling methods for adding raw values (addValues(String, Serializable...), for example), they will be stored in the form of value providers.

    Since:
    9.0.0
    Version:
    $Revision: 24477 $ $Date: 2021-04-28 11:30:36 -0300 (Wed, 28 Apr 2021) $
    See Also:
    IMonitorValuesProvider

    • Method Detail

      • start

        IMonitor start()
        Method used to indicate that the monitored event has started. This method is used to fill duration field. The duration is calculated by the difference of this call and the call to either stop() or close() (the first to be called). The stop() method must be called to indicate the end of the event. If stop() isn't called, it will be called automatically in close().
        Returns:
        this monitor for chaining calls.
        Since:
        9.0.0
        See Also:
        stop()

      • stop

        IMonitor stop()
        Method used to indicate that the monitored event has ended. The start() must have been called previously.

        This method calls setDuration(long, long) to add duration value relative to the use between the start and stop calls.

        Returns:
        this monitor for chaining calls.
        Since:
        9.0.0
        See Also:
        addValues(Map), start()

      • setDuration

        default IMonitor setDuration​(long startMillis,
                             long endMillis)
        Adds value of duration field.
        Parameters:
        startMillis - the start of the event in milliseconds since midnight January 1, 1970 GMT.
        endMillis - the end of the event in milliseconds since midnight January 1, 1970 GMT.
        Returns:
        this monitor for chaining calls.
        Since:
        9.0.0

      • setDuration

        default IMonitor setDuration​(long duration)
        Adds value of duration field.
        Parameters:
        startMillis - the start of the event in milliseconds since midnight January 1, 1970 GMT.
        endMillis - the end of the event in milliseconds since midnight January 1, 1970 GMT.
        Returns:
        this monitor for chaining calls.
        Since:
        9.0.0

      • addValues

        default IMonitor addValues​(String fieldId,
                           Serializable... values)
        Adds a values provider that returns the given values for the specified field.
        Parameters:
        fieldId - the field identifier.
        values - the values for the field. Any null value in these values will be discarded. If all given values are null or if it is an empty array, the provider will return no value (empty list) for the field.
        Returns:
        this monitor for chaining calls.
        Throws:
        NullPointerException - if values is a null array.
        Since:
        9.0.0

      • addValues

        default IMonitor addValues​(String fieldId,
                           List<? extends Serializable> values)
        Adds a values provider that returns the given values for the specified field.
        Parameters:
        fieldId - the field identifier.
        values - the values for the field. Any null value in this list will be discarded. If all given values are null or if it is an empty list, the provider will return no value (empty list) for the field.
        Returns:
        this monitor for chaining calls.
        Throws:
        NullPointerException - if values is null.
        Since:
        9.0.0

      • addValues

        default IMonitor addValues​(Map<String,​List<? extends Serializable>> fieldValues)
        Adds a IMonitorValuesProvider that returns values for fields as specified in the given map.
        Parameters:
        fieldValues - the map of field values, where the map entry key is the field identifier and the map entry values is a list of the values for the corresponding field. Any null in the list of values will be ignored. If for a field all values in the list are null or if it is an empty list, the provider will return no value (empty list) for that field.
        Returns:
        this monitor for chaining calls.
        Throws:
        NullPointerException - if fieldValues is null.
        Since:
        9.0.0

      • addValues

        IMonitor addValues​(IMonitorValuesProvider... values)
        Adds the given value providers in this monitor. When necessary, the providers are queried for field values in the order they are added in this monitor. If a provider returns some value for a field (even if an empty value), it will prevent further providers to be queried.
        Parameters:
        values - the value providers.
        Returns:
        this monitor for chaining calls.
        Since:
        9.0.0
        See Also:
        IMonitorValuesProvider

      • close

        void close()
        Closes this monitor instance.
        If this monitor is not bound to a transaction, the collected data will be saved in this moment.
        If this monitor is bound to a transaction, the data will be saved either:
        • If the transaction this monitor is bound to has already been closed, the data will be saved in this moment.
        • Otherwise, the data will be saved in the moment the transaction is closed.
        If start() has been called but stop() hasn't, stop() will be called automatically.
        Specified by:
        close in interface AutoCloseable
        Since:
        9.0.0