/*_############################################################################
  _##
  _##  SNMP4J-Agent 3 - FileAuditEvent.java
  _##
  _##  Copyright (C) 2005-2026  Frank Fock (SNMP4J.org)
  _##
  _##  Licensed under the Apache License, Version 2.0 (the "License");
  _##  you may not use this file except in compliance with the License.
  _##  You may obtain a copy of the License at
  _##
  _##      http://www.apache.org/licenses/LICENSE-2.0
  _##
  _##  Unless required by applicable law or agreed to in writing, software
  _##  distributed under the License is distributed on an "AS IS" BASIS,
  _##  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  _##  See the License for the specific language governing permissions and
  _##  limitations under the License.
  _##
  _##########################################################################*/

package org.snmp4j.agent.audit;

import java.io.File;
import java.util.EventObject;

/**
 * The {@code FileAuditEvent} describes a file system operation that is about to be executed (or, for
 * {@link FileOperation#DELETE}, has been executed) by the SNMP4J-Agent. It is passed to all
 * registered {@link FileAuditListener}s, which lets the listeners monitor (audit) and optionally
 * prevent (deny) read, write, create, and delete access to files.
 * <p>
 * This event and its {@link FileAuditListener} are the file system equivalent of the
 * {@link org.snmp4j.transport.TransportAuditEvent} and
 * {@link org.snmp4j.transport.TransportAuditListener} used for transport level auditing.
 *
 * @author Frank Fock
 * @version 3.12.0
 * @since 3.12.0
 */
public class FileAuditEvent extends EventObject {

    private static final long serialVersionUID = 1L;

    /**
     * The {@code FileOperation} enumerates the file system operations that can be audited.
     */
    public enum FileOperation {
        /**
         * The contents of an existing file are about to be read.
         */
        READ,
        /**
         * The contents of a (new or existing) file are about to be written or modified.
         */
        WRITE,
        /**
         * A new file is about to be created.
         */
        CREATE,
        /**
         * A file is about to be (or has been) deleted.
         */
        DELETE
    }

    private final FileOperation operation;
    private final File file;

    /**
     * Creates a {@code FileAuditEvent}.
     *
     * @param source
     *    the object that fired this event (i.e. the component that is about to access the file).
     * @param operation
     *    the audited {@link FileOperation}.
     * @param file
     *    the {@link File} the operation refers to.
     */
    public FileAuditEvent(Object source, FileOperation operation, File file) {
        super(source);
        this.operation = operation;
        this.file = file;
    }

    /**
     * Creates a {@code FileAuditEvent}.
     *
     * @param source
     *    the object that fired this event (i.e. the component that is about to access the file).
     * @param operation
     *    the audited {@link FileOperation}.
     * @param file
     *    the filename the operation refers to.
     */
    public FileAuditEvent(Object source, FileOperation operation, String file) {
        super(source);
        this.operation = operation;
        this.file = new File(file);
    }

    /**
     * Gets the audited file operation.
     * @return
     *    the {@link FileOperation}.
     */
    public FileOperation getOperation() {
        return operation;
    }

    /**
     * Gets the file the audited operation refers to.
     * @return
     *    the {@link File} instance.
     */
    public File getFile() {
        return file;
    }

    @Override
    public String toString() {
        return "FileAuditEvent[" +
                "operation=" + operation +
                ", file=" + file +
                ", source=" + source +
                ']';
    }
}
