All Superinterfaces:

java.lang.AutoCloseable
```
@StableMinor(version="16.1",
             sinceVersion="9.0")
public interface IMonitor
extends java.lang.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: 26156 $ $Date: 2024-01-13 10:26:46 -0300 (Sat, 13 Jan 2024) $

See Also:

IMonitorValuesProvider

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method	Description
`default IMonitor`	`addValues(java.lang.String fieldId, java.io.Serializable... values)`	Adds a values provider that returns the given values for the specified field.
`default IMonitor`	`addValues(java.lang.String fieldId, java.util.List<? extends java.io.Serializable> values)`	Adds a values provider that returns the given values for the specified field.
`default IMonitor`	`addValues(java.util.Map<java.lang.String,java.util.List<? extends java.io.Serializable>> fieldValues)`	Adds a `IMonitorValuesProvider` that returns values for fields as specified in the given map.
`IMonitor`	`addValues(IMonitorValuesProvider... values)`	Adds the given value providers 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(java.lang.String fieldId,
                           java.io.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:
    
    java.lang.NullPointerException - if values is a null array.
    
    Since:
    
    9.0.0
  - addValues
```
default IMonitor addValues(java.lang.String fieldId,
                           java.util.List<? extends java.io.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:
    
    java.lang.NullPointerException - if values is null.
    
    Since:
    
    9.0.0
  - addValues
```
default IMonitor addValues(java.util.Map<java.lang.String,java.util.List<? extends java.io.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:
    
    java.lang.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 java.lang.AutoCloseable
    
    Since:
    
    9.0.0

Interface IMonitor

Method Summary

Method Detail

start

stop

setDuration

setDuration

addValues

addValues

addValues

addValues

close