001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2026 the original author or authors.
004//
005// This library is free software; you can redistribute it and/or
006// modify it under the terms of the GNU Lesser General Public
007// License as published by the Free Software Foundation; either
008// version 2.1 of the License, or (at your option) any later version.
009//
010// This library 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 GNU
013// Lesser General Public License for more details.
014//
015// You should have received a copy of the GNU Lesser General Public
016// License along with this library; if not, write to the Free Software
017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
018///////////////////////////////////////////////////////////////////////////////////////////////
019
020package com.puppycrawl.tools.checkstyle.api;
021
022/**
023 * Raw event for audit.
024 *
025 * <p>
026 * <i>
027 * I'm not very satisfied about the design of this event since there are
028 * optional methods that will return null in most of the case. This will
029 * need some work to clean it up especially if we want to introduce
030 * a more sequential reporting action rather than a packet
031 * reporting. This will allow for example to follow the process quickly
032 * in an interface or a servlet (yep, that's cool to run a check via
033 * a web interface in a source repository ;-)
034 * </i>
035 * </p>
036 *
037 * @see AuditListener
038 * @noinspection ClassCanBeRecord
039 * @noinspectionreason We can not break compatibility with previous versions.
040 */
041public final class AuditEvent {
042
043    /** The object on which the Event initially occurred. */
044    private final Object source;
045    /** Filename event associated with. */
046    private final String fileName;
047    /** Violation associated with the event. */
048    private final Violation violation;
049
050    /**
051     * Creates a new instance.
052     *
053     * @param source the object that created the event
054     */
055    public AuditEvent(Object source) {
056        this(source, null);
057    }
058
059    /**
060     * Creates a new {@code AuditEvent} instance.
061     *
062     * @param src source of the event
063     * @param fileName file associated with the event
064     */
065    public AuditEvent(Object src, String fileName) {
066        this(src, fileName, null);
067    }
068
069    /**
070     * Creates a new {@code AuditEvent} instance.
071     *
072     * @param src source of the event
073     * @param fileName file associated with the event
074     * @param violation the actual violation
075     * @throws IllegalArgumentException if {@code src} is {@code null}.
076     */
077    public AuditEvent(Object src, String fileName, Violation violation) {
078        if (src == null) {
079            throw new IllegalArgumentException("null source");
080        }
081
082        source = src;
083        this.fileName = fileName;
084        this.violation = violation;
085    }
086
087    /**
088     * The object on which the Event initially occurred.
089     *
090     * @return the object on which the Event initially occurred
091     */
092    public Object getSource() {
093        return source;
094    }
095
096    /**
097     * Returns name of file being audited.
098     *
099     * @return the file name currently being audited or null if there is no relation to a file.
100     */
101    public String getFileName() {
102        return fileName;
103    }
104
105    /**
106     * Return the line number on the source file where the event occurred.
107     * This may be 0 if there is no relation to a file content.
108     *
109     * @return an integer representing the line number in the file source code.
110     */
111    public int getLine() {
112        return violation.getLineNo();
113    }
114
115    /**
116     * Return the violation associated to the event.
117     *
118     * @return the event violation
119     */
120    public String getMessage() {
121        return violation.getViolation();
122    }
123
124    /**
125     * Gets the column associated with the violation.
126     *
127     * @return the column associated with the violation
128     */
129    public int getColumn() {
130        return violation.getColumnNo();
131    }
132
133    /**
134     * Gets the audit event severity level.
135     *
136     * @return the audit event severity level
137     */
138    public SeverityLevel getSeverityLevel() {
139        SeverityLevel severityLevel = SeverityLevel.INFO;
140        if (violation != null) {
141            severityLevel = violation.getSeverityLevel();
142        }
143        return severityLevel;
144    }
145
146    /**
147     * Returns id of module.
148     *
149     * @return the identifier of the module that generated the event. Can return null.
150     */
151    public String getModuleId() {
152        return violation.getModuleId();
153    }
154
155    /**
156     * Gets the name of the source for the violation.
157     *
158     * @return the name of the source for the violation
159     */
160    public String getSourceName() {
161        return violation.getSourceName();
162    }
163
164    /**
165     * Gets the violation.
166     *
167     * @return the violation
168     */
169    public Violation getViolation() {
170        return violation;
171    }
172
173}