lumis.portal.monitor

Interface IMonitor

All Superinterfaces:

AutoCloseable

@StableMinor(version="12.5",
             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: 24140 $ $Date: 2020-09-14 21:50:42 +0000 (Mon, 14 Sep 2020) $

See Also:

IMonitorValuesProvider

Method Summary

Modifier and Type	Method and Description
IMonitor	addValues(IMonitorValuesProvider... values) Adds the given value providers in this monitor.
default IMonitor	addValues(Map<String,List<? extends Serializable>> fieldValues) Adds the given values for the given fields in this monitor.
default IMonitor	addValues(String fieldId, List<? extends Serializable> values) Adds the given values for the given field in this monitor.
default IMonitor	addValues(String fieldId, Serializable... values) Adds the given values for the given field in this monitor.
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.
default IMonitor	setDuration(long duration) Adds value of duration field.
default IMonitor	setDuration(long startMillis, long endMillis) Adds value of duration field.
IMonitor	start() Method used to indicate that the monitored event has started.
IMonitor	stop() Method used to indicate that the monitored event has ended.

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 the given values for the given field in this monitor. If the field already have values in this monitor, the values will be accumulated.

Parameters:

fieldId - the field identifier.

values - field values.

Returns:

this monitor for chaining calls.

Since:

9.0.0

addValues

default IMonitor addValues(String fieldId,
                           List<? extends Serializable> values)

Adds the given values for the given field in this monitor. If the field already have values in this monitor, the values will be accumulated.

Parameters:

fieldId - the field identifier.

values - field values.

Returns:

this monitor for chaining calls.

Since:

9.0.0

addValues

default IMonitor addValues(Map<String,List<? extends Serializable>> fieldValues)

Adds the given values for the given fields in this monitor.

Parameters:

fieldValues - the field values.

Returns:

this monitor for chaining calls.

Since:

9.0.0

addValues

IMonitor addValues(IMonitorValuesProvider... values)

Adds the given value providers in this monitor.

Parameters:

values - the value providers.

Returns:

this monitor for chaining calls.

Since:

9.0.0

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