001/*
002 * ============================================================================
003 *  Copyright © 2002-2026 by Thomas Thrien.
004 *  All Rights Reserved.
005 * ============================================================================
006 *  Licensed to the public under the agreements of the GNU Lesser General Public
007 *  License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *       http://www.gnu.org/licenses/lgpl.html
010 *
011 *  Unless required by applicable law or agreed to in writing, software
012 *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
013 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 *  License for the specific language governing permissions and limitations
015 *  under the License.
016 */
017
018package org.tquadrat.foundation.perflog.client;
019
020import static org.apiguardian.api.API.Status.STABLE;
021
022import javax.management.Notification;
023import java.util.Optional;
024
025import org.apiguardian.api.API;
026import org.tquadrat.foundation.annotation.ClassVersion;
027
028/**
029 *  <p>{@summary An implementation of
030 *  {@link PerfLogClientBase}.}</p>
031 *  <p>This class provides a simple API for a client for the Foundation
032 *  Performance Logging and Monitoring. Basically, this is a recipient for the
033 *  {@link Notification}
034 *  messages that are sent each time a
035 *  {@linkplain org.tquadrat.foundation.perflog.PerformanceSection performance
036 *  section} was left.</p>
037 *  <p>It can be used like this</p>
038 *  {@include ${javadoc}/sample5.txt:SOURCE}
039 *
040 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
041 *  @version $Id: PerfLogClientSupport.java 1248 2026-05-17 11:08:34Z tquadrat $
042 *  @since 0.25.0
043 *
044 *  @UMLGraph.link
045 */
046@ClassVersion( sourceVersion = "$Id: PerfLogClientSupport.java 1248 2026-05-17 11:08:34Z tquadrat $" )
047@API( status = STABLE, since = "0.25.0" )
048public final class PerfLogClientSupport extends PerfLogClientBase
049{
050        /*--------------*\
051    ====** Constructors **=====================================================
052        \*--------------*/
053    /**
054     *  Creates a new instance of {@code PerfLogClientSupport}.
055     */
056    public PerfLogClientSupport()
057    {
058        super();
059    }   //  PerfLogClientSupport()
060
061        /*---------*\
062    ====** Methods **==========================================================
063        \*---------*/
064    /**
065     *  Waits for an incoming message.
066     *
067     *  @return The message.
068     *  @throws InterruptedException    An interrupt occurred while waiting.
069     */
070    public final String awaitMessage() throws InterruptedException
071    {
072        final var retValue = getQueue().take();
073
074        //---* Done *----------------------------------------------------------
075        return retValue;
076    }   //  awaitMessage()
077
078    /**
079     *  <p>{@summary Pulls an incoming message.}</p>
080     *  <p>Returns
081     *  {@linkplain Optional#empty() emtpy}
082     *  if there is currently no message.</p>
083     *
084     *  @return An instance of
085     *      {@link Optional}
086     *      that holds the message.
087     */
088    public final Optional<String> retrieveMessage()
089    {
090        final var retValue = Optional.ofNullable( getQueue().poll() );
091
092        //---* Done *----------------------------------------------------------
093        return retValue;
094    }   //  retrieveMessage()
095}
096//  class PerfLogClientSupport
097
098/*
099 *  End of File
100 */