001/*
002 * ============================================================================
003 * Copyright © 2002-2026 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 *
007 * Licensed to the public under the agreements of the GNU Lesser General Public
008 * License, version 3.0 (the "License"). You may obtain a copy of the License at
009 *
010 *      http://www.gnu.org/licenses/lgpl.html
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
014 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015 * License for the specific language governing permissions and limitations
016 * under the License.
017 */
018
019package org.tquadrat.foundation.perflog;
020
021import static org.apiguardian.api.API.Status.STABLE;
022
023import javax.management.NotificationEmitter;
024import java.util.Optional;
025
026import org.apiguardian.api.API;
027import org.tquadrat.foundation.annotation.ClassVersion;
028
029/**
030 *  <p>{@summary This interface describes the MBean for the Foundation
031 *  Performance Logging and Monitoring.}</p>
032 *
033 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
034 *  @version $Id: PerfLogMBean.java 1258 2026-06-04 18:33:06Z tquadrat $
035 *  @since 0.25.0
036 *
037 *  @UMLGraph.link
038 */
039@ClassVersion( sourceVersion = "$Id: PerfLogMBean.java 1258 2026-06-04 18:33:06Z tquadrat $" )
040@API( status = STABLE, since = "0.25.0" )
041public interface PerfLogMBean extends NotificationEmitter
042{
043        /*-----------*\
044    ====** Constants **========================================================
045        \*-----------*/
046    /**
047     *  The MBean description: {@value}.
048     *
049     *  @see javax.management.MBeanInfo#getDescription()
050     */
051    public static final String DESCRIPTION = "tquadrat Foundation Performance Logging and Monitoring";
052
053    /**
054     *  The description for the
055     *  {@link javax.management.Notification}
056     *  instances emitted by this MBean: {@value}.
057     */
058    public static final String NOTIFICATION_Description = "The execution Notification for a Performance Section";
059
060        /*---------*\
061    ====** Methods **==========================================================
062        \*---------*/
063    /**
064     *  Adds the definition for a performance section.
065     *
066     *  @param  definition  The definition for the performance section.
067     */
068    public void addPerformanceSection( final PerformanceSection definition );
069
070    /**
071     *  <p>{@summary Disables the performance section.}</p>
072     *  <p>This is an operation for the MBean.</p>
073     *
074     *  @param  name    The name of the performance section.
075     *  @return A message indicating success or failure of the operation, as a
076     *  JSON String.
077     */
078    public String disablePerformanceSection( final String name );
079
080    /**
081     *  <p>{@summary Enables the performance section.}</p>
082     *  <p>This is an operation for the MBean.</p>
083     *
084     *  @param  name    The name of the performance section.
085     *  @return A message indicating success or failure of the operation, as a
086     *  JSON String.
087     */
088    public String enablePerformanceSection( final String name );
089
090    /**
091     *  Returns the exceptions that caused a notification thread to abort.
092     *
093     *  @return A list of exceptions that let a notification thread go down.
094     */
095    public String[] getNotificationExceptions();
096
097    /**
098     *  Returns the notification sequence number.
099     *
100     *  @return The last used sequence number.
101     */
102    public long getNotificationSequenceNumber();
103
104    /**
105     *  <p>{@summary Returns the performance section specified by the given
106     *  name.}</p>
107     *
108     *  @param  name    The name of the performance section.
109     *  @return An instance of
110     *      {@link Optional}
111     *      that holds the retrieved performance section.
112     */
113    public Optional<PerformanceSection> getPerformanceSection( final PerformanceSectionName name );
114
115    /**
116     *  <p>{@summary Returns a list of the currently defined performance
117     *  sections.}</p>
118     *  <p>This is an attribute for the MBean.</p>
119     *
120     *  @return The list of the performance section names.
121     */
122    public String [] getPerformanceSections();
123
124    /**
125     *  <p>{@summary Retrieves the performance section for the given name.}</p>
126     *  <p>If there is no performance section for the given name, a new one is
127     *  created, with the
128     *  {@linkplain PerformanceSection#getThreshold() threshold}
129     *  and the
130     *  {@linkplain PerformanceSection#getTimeout() timeout}
131     *  disabled. Obviously, it should not be ignored.</p>
132     *
133     *  @param  name    The name of the performance section.
134     *  @return The performance section; will never be {@null}.
135     */
136    public PerformanceSection retrievePerformanceSection( final PerformanceSectionName name );
137
138    /**
139     *  Takes the performance report and transfers it further.
140     *
141     *  @param  report  The performance report.
142     */
143    public void receivePerformanceReport( final PerformanceReport report );
144
145    /**
146     *  <p>{@summary Shows the performance section status.}</p>
147     *  <p>This is an operation for the MBean.</p>
148     *
149     *  @param  name    The name of the performance section.
150     *  @return The status of the performance section, or a message indicating
151     *      what failed in case of error, as a JSON String.
152     */
153    public String showPerformanceSection( final String name );
154}
155//  interface PerfLogMBean
156
157/*
158 *  End of File
159 */