GUACAMOLE-1224: Extract base interface for events affecting objects stored in a Directory.

guacamole-ext/src/main/java/org/apache/guacamole/net/event/DirectoryEvent.java

@@ -24,13 +24,14 @@ import org.apache.guacamole.net.auth.Identifiable;
 
 /**
  * Abstract basis for events which involve a modification made to the objects
- * within a {@link Directory}.
+ * within a {@link Directory} through the operations exposed by the Directory
+ * interface.
  *
  * @param <ObjectType>
  *     The type of object stored within the {@link Directory}.
  */
 public interface DirectoryEvent<ObjectType extends Identifiable>
-        extends AuthenticationProviderEvent, UserEvent {
+        extends DirectoryObjectEvent<ObjectType> {
 
     /**
      * The types of directory operations that may be represented by a
@@ -70,15 +71,6 @@ public interface DirectoryEvent<ObjectType extends Identifiable>
 
     }
 
-    /**
-     * Returns the type of objects stored within the {@link Directory}
-     * affected by the operation.
-     *
-     * @return
-     *     The type of objects stored within the {@link Directory}.
-     */
-    Directory.Type getDirectoryType();
-
     /**
      * Returns the operation that was performed/attempted.
      *
@@ -88,24 +80,25 @@ public interface DirectoryEvent<ObjectType extends Identifiable>
     Operation getOperation();
 
     /**
-     * Returns the identifier of the object affected by the operation. If the
-     * object was just created, this will be the identifier of the new object.
-     *
-     * @return
-     *     The identifier of the object affected by the operation.
+     * {@inheritDoc}
+     * <p>
+     * If the object was just created, this will be the identifier of the new
+     * object.
      */
+    @Override
     String getObjectIdentifier();
 
     /**
-     * Returns the object affected by the operation, if available. For
-     * deletions, there is no guarantee that the affected object will be
-     * available within this event. If the object is not available, null is
-     * returned.
-     *
-     * @return
-     *     The object affected by the operation performed, or null if that
-     *     object is not available in the context of this event.
+     * {@inheritDoc}
+     * <p>
+     * Currently, for object creation ({@link Operation#ADD}), retrieval
+     * ({@link Operation#GET}), modification and ({@link Operation#UPDATE}),
+     * it can be expected that the affected object will be available, however
+     * the caller should verify this regardless. For deletions
+     * ({@link Operation#REMOVE}), the object can only be made available for
+     * single deletions, and cannot be made available for batch deletions.
      */
+    @Override
     ObjectType getObject();
 
 }

guacamole-ext/src/main/java/org/apache/guacamole/net/event/DirectoryObjectEvent.java

@@ -0,0 +1,65 @@
+/*
+ * 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.guacamole.net.event;
+
+import org.apache.guacamole.net.auth.Directory;
+import org.apache.guacamole.net.auth.Identifiable;
+
+/**
+ * Abstract basis for events which affect or directly relate to objects that
+ * may be stored within a {@link Directory}.
+ *
+ * @param <ObjectType>
+ *     The type of object stored within the {@link Directory}.
+ */
+public interface DirectoryObjectEvent<ObjectType extends Identifiable>
+        extends AuthenticationProviderEvent, UserEvent {
+
+    /**
+     * Returns the type of {@link Directory} that contains the object affected
+     * by the operation.
+     *
+     * @return
+     *     The type of objects stored within the {@link Directory}.
+     */
+    Directory.Type getDirectoryType();
+
+    /**
+     * Returns the identifier of the object affected by the operation.
+     *
+     * @return
+     *     The identifier of the object affected by the operation.
+     */
+    String getObjectIdentifier();
+
+    /**
+     * Returns the object affected by the operation, if available. Whether the
+     * affected object is available is context- and implementation-dependent.
+     * There is no general guarantee across all implementations of this event
+     * that the affected object will be available. If the object is not
+     * available, null is returned.
+     *
+     * @return
+     *     The object affected by the operation performed, or null if that
+     *     object is not available in the context of this event.
+     */
+    ObjectType getObject();
+
+}