[MNG-8547] Expose repository events through the Maven API

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

@@ -21,54 +21,100 @@
 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 RepositoryEvent
+ * @see Listener
  * @since 4.0.0
  */
 @Experimental
+@Immutable
 public interface Event {
 
     /**
-     * Gets the type of the event.
+     * Returns 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 execution event type, never {@code null}; only meaningful when this event is an {@link ExecutionEvent}
+     * @throws UnsupportedOperationException if this event is not an {@link ExecutionEvent}
+     * @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.valueOf(ee.type().name());
+        }
+        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/ExecutionEvent.java

@@ -0,0 +1,54 @@
+/*
+ * 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;
+
+/**
+ * A build execution event with noun-style accessors.
+ * Extends {@link Event} so existing execution listeners can consume the same event.
+ *
+ * @see ExecutionListener
+ * @see ExecutionEventType
+ * @since 4.1.0
+ */
+@Experimental
+@Immutable
+public interface ExecutionEvent extends Event {
+
+    /** {@return the kind of execution operation} */
+    @Nonnull
+    ExecutionEventType type();
+
+    /** {@return the current project, if applicable} */
+    @Nonnull
+    Optional<Project> project();
+
+    /** {@return the current mojo execution, if applicable} */
+    @Nonnull
+    Optional<MojoExecution> mojoExecution();
+
+    /** {@return the failure associated with this event, if any} */
+    @Nonnull
+    Optional<Exception> exception();
+}

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

@@ -0,0 +1,47 @@
+/*
+ * 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 build execution events.
+ *
+ * @since 4.1.0
+ */
+@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,
+}