001/*
002 * jPOS Project [http://jpos.org]
003 * Copyright (C) 2000-2026 jPOS Software SRL
004 *
005 * This program is free software: you can redistribute it and/or modify
006 * it under the terms of the GNU Affero General Public License as
007 * published by the Free Software Foundation, either version 3 of the
008 * License, or (at your option) any later version.
009 *
010 * This program is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
013 * GNU Affero General Public License for more details.
014 *
015 * You should have received a copy of the GNU Affero General Public License
016 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
017 */
018
019package org.jpos.jfr;
020
021import jdk.jfr.*;
022
023/**
024 * Base JFR event emitted from the jPOS channel layer.
025 *
026 * <p>Concrete subclasses (declared as static inner classes) tag specific
027 * channel lifecycle moments — connect, accept, send, receive, disconnect,
028 * and their exceptional variants.
029 */
030@Category("jPOS")
031@Name("jpos.Channel")
032@StackTrace
033public class ChannelEvent extends Event {
034    /** Free-form event detail, recorded as the JFR field {@code detail}. */
035    @Name("detail")
036    protected String detail;
037
038    /** Constructs an empty event with no detail. */
039    public ChannelEvent() {}
040    /**
041     * Constructs an event with the given detail string.
042     *
043     * @param detail event detail text
044     */
045    public ChannelEvent(String detail) {
046        this.detail = detail;
047    }
048
049    /**
050     * Replaces the event detail.
051     *
052     * @param detail event detail text
053     */
054    public void setDetail(String detail) {
055        this.detail = detail;
056    }
057
058    /**
059     * Returns the current event detail.
060     *
061     * @return event detail text, or {@code null} if not set
062     */
063    public String getDetail() {
064        return detail;
065    }
066
067    /**
068     * Appends additional information to the existing detail string,
069     * separated by a comma.
070     *
071     * @param additionalDetail text to append
072     * @return this event for chaining
073     */
074    public ChannelEvent append (String additionalDetail) {
075        detail = detail != null ?
076          "%s, %s".formatted (detail, additionalDetail) : additionalDetail;
077        return this;
078    }
079
080    /** JFR event recorded for a successful channel send. */
081    @Name("jpos.Channel.Send")
082    public static class Send extends ChannelEvent {
083        /** Creates an empty Send event with no detail. */
084        public Send() {}
085    }
086
087    /** JFR event recorded for a successful channel receive. */
088    @Name("jpos.Channel.Receive")
089    public static class Receive extends ChannelEvent {
090        /** Creates an empty Receive event with no detail. */
091        public Receive() {}
092    }
093
094    /** JFR event recorded when an outbound channel completes its connect handshake. */
095    @Name("jpos.Channel.Connect")
096    public static class Connect extends ChannelEvent {
097        /** Creates an empty Connect event with no detail. */
098        public Connect() {}
099    }
100
101    /** JFR event recorded when a server channel accepts a new client. */
102    @Name("jpos.Channel.Accept")
103    public static class Accept extends ChannelEvent {
104        /** Creates an empty Accept event with no detail. */
105        public Accept() {}
106    }
107
108    /** JFR event recorded when a channel disconnects. */
109    @Name("jpos.Channel.Disconnect")
110    public static class Disconnect extends ChannelEvent {
111        /** Creates an empty Disconnect event with no detail. */
112        public Disconnect() {}
113    }
114
115    /** JFR event recorded when an outbound connect attempt fails. */
116    @Name("jpos.Channel.ConnectionException")
117    public static class ConnectionException extends ChannelEvent {
118        /**
119         * Constructs the event with a description of the failure.
120         *
121         * @param detail failure description
122         */
123        public ConnectionException(String detail) {
124            super(detail);
125        }
126    }
127
128    /** JFR event recorded when accepting an inbound connection fails. */
129    @Name("jpos.Channel.AcceptException")
130    public static class AcceptException extends ChannelEvent {
131        /**
132         * Constructs the event with a description of the failure.
133         *
134         * @param detail failure description
135         */
136        public AcceptException(String detail) {
137            super(detail);
138        }
139    }
140
141    /** JFR event recorded when sending a message on a channel fails. */
142    @Name("jpos.Channel.SendException")
143    public static class SendException extends ChannelEvent {
144        /**
145         * Constructs the event with a description of the failure.
146         *
147         * @param detail failure description
148         */
149        public SendException(String detail) {
150            super(detail);
151        }
152    }
153
154}