[MNG-8547] Introduce Event/Listener hierarchy with ExecutionEvent and ExecutionListener

api/maven-api-core/src/main/java/org/apache/maven/api/Event.java

@@ -21,54 +21,98 @@
 import java.util.Optional;
 
 import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Immutable;
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
- * Event sent by maven during various phases of the build process.
- * Such events can be listened to using {@link Listener}s objects
- * registered in the {@link Session}.
+ * Base interface for all Maven events.
+ * Specific event families extend this interface to provide typed event data.
+ * Events can be listened to using {@link Listener} objects registered in the {@link Session}.
  *
+ * @see ExecutionEvent
+ * @see Listener
  * @since 4.0.0
  */
 @Experimental
+@Immutable
 public interface Event {
 
     /**
-     * Gets the type of the event.
+     * Gets the session from which this event originates.
      *
-     * @return the type of the event, never {@code null}
+     * @return the current session, never {@code null}
      */
     @Nonnull
-    EventType getType();
+    Session session();
 
     /**
      * Gets the session from which this event originates.
      *
      * @return the current session, never {@code null}
+     * @deprecated Use {@link #session()} instead.
+     */
+    @Deprecated(since = "4.1.0", forRemoval = true)
+    @Nonnull
+    default Session getSession() {
+        return session();
+    }
+
+    /**
+     * Gets the type of the event.
+     *
+     * @return the type of the event, never {@code null}
+     * @deprecated Use {@link ExecutionEvent#type()} instead.
      */
+    @Deprecated(since = "4.1.0", forRemoval = true)
     @Nonnull
-    Session getSession();
+    default EventType getType() {
+        if (this instanceof ExecutionEvent ee) {
+            return EventType.fromExecutionEventType(ee.type());
+        }
+        throw new UnsupportedOperationException("getType() is only supported on ExecutionEvent instances");
+    }
 
     /**
      * Gets the current project (if any).
      *
      * @return the current project or {@code empty()} if not applicable
+     * @deprecated Use {@link ExecutionEvent#project()} instead.
      */
+    @Deprecated(since = "4.1.0", forRemoval = true)
     @Nonnull
-    Optional<Project> getProject();
+    default Optional<Project> getProject() {
+        if (this instanceof ExecutionEvent ee) {
+            return ee.project();
+        }
+        return Optional.empty();
+    }
 
     /**
      * Gets the current mojo execution (if any).
      *
      * @return the current mojo execution or {@code empty()} if not applicable
+     * @deprecated Use {@link ExecutionEvent#mojoExecution()} instead.
      */
+    @Deprecated(since = "4.1.0", forRemoval = true)
     @Nonnull
-    Optional<MojoExecution> getMojoExecution();
+    default Optional<MojoExecution> getMojoExecution() {
+        if (this instanceof ExecutionEvent ee) {
+            return ee.mojoExecution();
+        }
+        return Optional.empty();
+    }
 
     /**
      * Gets the exception that caused the event (if any).
      *
      * @return the exception or {@code empty()} if none
+     * @deprecated Use {@link ExecutionEvent#exception()} instead.
      */
-    Optional<Exception> getException();
+    @Deprecated(since = "4.1.0", forRemoval = true)
+    default Optional<Exception> getException() {
+        if (this instanceof ExecutionEvent ee) {
+            return ee.exception();
+        }
+        return Optional.empty();
+    }
 }

api/maven-api-core/src/main/java/org/apache/maven/api/EventType.java

@@ -24,7 +24,9 @@
  * The possible types of execution events.
  *
  * @since 4.0.0
+ * @deprecated Use {@link ExecutionEventType} instead.
  */
+@Deprecated(since = "4.1.0", forRemoval = true)
 @Experimental
 public enum EventType {
     PROJECT_DISCOVERY_STARTED,
@@ -43,5 +45,24 @@ public enum EventType {
     FORK_FAILED,
     FORKED_PROJECT_STARTED,
     FORKED_PROJECT_SUCCEEDED,
-    FORKED_PROJECT_FAILED,
+    FORKED_PROJECT_FAILED;
+
+    /**
+     * Converts this deprecated {@code EventType} to the new {@link ExecutionEventType}.
+     *
+     * @return the corresponding {@link ExecutionEventType}, never {@code null}
+     */
+    public ExecutionEventType toExecutionEventType() {
+        return ExecutionEventType.values()[ordinal()];
+    }
+
+    /**
+     * Converts an {@link ExecutionEventType} to the deprecated {@code EventType}.
+     *
+     * @param type the {@link ExecutionEventType} to convert, must not be {@code null}
+     * @return the corresponding {@code EventType}, never {@code null}
+     */
+    public static EventType fromExecutionEventType(ExecutionEventType type) {
+        return values()[type.ordinal()];
+    }
 }

api/maven-api-core/src/main/java/org/apache/maven/api/ExecutionEvent.java

@@ -0,0 +1,70 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.apache.maven.api;
+
+import java.util.Optional;
+
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Immutable;
+import org.apache.maven.api.annotations.Nonnull;
+
+/**
+ * Event sent by Maven during various phases of the build lifecycle (session, project, mojo).
+ * Such events can be listened to using {@link ExecutionListener} objects registered in the {@link Session}.
+ *
+ * @see ExecutionListener
+ * @see ExecutionEventType
+ * @since 4.1.0
+ */
+@Experimental
+@Immutable
+public interface ExecutionEvent extends Event {
+
+    /**
+     * Gets the type of the execution event.
+     *
+     * @return the type of the event, never {@code null}
+     */
+    @Nonnull
+    ExecutionEventType type();
+
+    /**
+     * Gets the current project (if any).
+     *
+     * @return the current project or {@code empty()} if not applicable
+     */
+    @Nonnull
+    Optional<Project> project();
+
+    /**
+     * Gets the current mojo execution (if any).
+     *
+     * @return the current mojo execution or {@code empty()} if not applicable
+     */
+    @Nonnull
+    Optional<MojoExecution> mojoExecution();
+
+    /**
+     * Gets the exception that caused the event (if any).
+     *
+     * @return the exception or {@code empty()} if none
+     */
+    @Nonnull
+    Optional<Exception> exception();
+}

api/maven-api-core/src/main/java/org/apache/maven/api/ExecutionEventType.java

@@ -0,0 +1,50 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.apache.maven.api;
+
+import org.apache.maven.api.annotations.Experimental;
+
+/**
+ * The possible types of execution events during the Maven build lifecycle.
+ *
+ * @see ExecutionEvent
+ * @see ExecutionListener
+ * @since 4.0.0
+ * @since 4.1.0 (renamed from {@link EventType})
+ */
+@Experimental
+public enum ExecutionEventType {
+    PROJECT_DISCOVERY_STARTED,
+    SESSION_STARTED,
+    SESSION_ENDED,
+    PROJECT_SKIPPED,
+    PROJECT_STARTED,
+    PROJECT_SUCCEEDED,
+    PROJECT_FAILED,
+    MOJO_SKIPPED,
+    MOJO_STARTED,
+    MOJO_SUCCEEDED,
+    MOJO_FAILED,
+    FORK_STARTED,
+    FORK_SUCCEEDED,
+    FORK_FAILED,
+    FORKED_PROJECT_STARTED,
+    FORKED_PROJECT_SUCCEEDED,
+    FORKED_PROJECT_FAILED,
+}