Michael Ludwig avatar Michael Ludwig committed 1bd1dcd

Add documentation for ownership.

Comments (0)

Files changed (6)

src/main/java/com/lhkbob/entreri/Component.java

  * specific components. ComponentData's can change which component they
  * reference multiple times throughout their life time.
  * </p>
+ * <p>
+ * Component implements both {@link Ownable} and {@link Owner}. This can be used
+ * to create hierarchies of both components and entities that share a lifetime.
+ * When a component is removed from an entity, all of its owned objects are
+ * disowned. If any of them were entities or components, they are also removed
+ * from the system.
+ * </p>
  * 
  * @author Michael Ludwig
  * @param <T> The ComponentData type defining the data of this component
     }
 
     /**
-     * @return The TypeId of the ComponentData for this Component
+     * @return The class type of the ComponentData for this Component
      */
     public Class<T> getType() {
         return owner.getType();

src/main/java/com/lhkbob/entreri/ComponentData.java

  * created and configured by a {@link ComponentDataFactory}. These factories may
  * impose certain restrictions or requirements in what constructors or fields
  * are valid. ComponentData implementations can define a default
- * ComponentDataFactory type with the {@link DefaultFactory} annoation. By
+ * ComponentDataFactory type with the {@link DefaultFactory} annotation. By
  * default ComponentData implementations are created using The
  * {@link ReflectionComponentDataFactory}
  * </p>

src/main/java/com/lhkbob/entreri/Entity.java

  * Entities use instance equality, just like {@link Component}. Once created the
  * Entity object will not change its identity.
  * </p>
+ * <p>
+ * Entity implements both {@link Ownable} and {@link Owner}. This can be used to
+ * create hierarchies of both components and entities that share a lifetime.
+ * When an entity is removed from the system, all of its owned objects are
+ * disowned. If any of them were entities or components, they are also removed
+ * from the system.
+ * </p>
  * 
  * @author Michael Ludwig
  */

src/main/java/com/lhkbob/entreri/Ownable.java

 package com.lhkbob.entreri;
 
+/**
+ * <p>
+ * An interface that designates something is ownable. Both entities and
+ * components can be ownable. This can be used to create hierarchies of
+ * components. As an example, a ParticleSystem component might own the Geometry
+ * component that a task prepares for it.
+ * <p>
+ * The Ownable interface is the main entry-point for programmers to manage their
+ * inter-entity/component relationships, and not {@link Owner}. The Owner
+ * interface exists so that Ownable implementations can notify owners of
+ * changes.
+ * 
+ * @author Michael Ludwig
+ * 
+ */
 public interface Ownable {
+    /**
+     * <p>
+     * Set the new owner of the given object. If the current owner before this
+     * call is non-null, it must be first notified that its ownership has been
+     * revoked, before granting ownership to the new owner.
+     * <p>
+     * If the new owner is null, the object becomes un-owned by anything.
+     * 
+     * @param owner The new owner
+     */
     public void setOwner(Owner owner);
 
+    /**
+     * Get the current owner of this object. If null is returned, the object is
+     * not owned by anything.
+     * 
+     * @return The current owner
+     */
     public Owner getOwner();
 }

src/main/java/com/lhkbob/entreri/Owner.java

 package com.lhkbob.entreri;
 
-
+/**
+ * Owner is a listener and tag interface so that {@link Ownable} implementations
+ * can report ownership changes to their owners. This is used by both Components
+ * and Entities to track which objects they own and disown them when they are
+ * removed from the EntitySystem.
+ * 
+ * @author Michael Ludwig
+ * 
+ */
 public interface Owner {
+    /**
+     * Notify this Owner that it is now <tt>obj</tt>'s owner. This must only be
+     * called by {@link Ownable} implementations in response to calls to
+     * {@link Ownable#setOwner(Owner)}.
+     * 
+     * @param obj The newly owned object
+     */
     public void notifyOwnershipGranted(Ownable obj);
 
+    /**
+     * <p>
+     * Notify this Owner that it is no longer <tt>obj</tt>'s owner. This must
+     * only be called by {@link Ownable} implementations in response to calls to
+     * {@link Ownable#setOwner(Owner)}.
+     * <p>
+     * Ownership is revoked when the Ownable is assigned a new owner, or the
+     * null owner but was previously owned by this instance.
+     * 
+     * @param obj The disowned object
+     */
     public void notifyOwnershipRevoked(Ownable obj);
 }

src/main/java/com/lhkbob/entreri/OwnerSupport.java

 import java.util.HashSet;
 import java.util.Set;
 
+/**
+ * Utility for shared implementation of {@link Ownable} and {@link Owner}
+ * 
+ * @author Michael Ludwig
+ * 
+ */
 class OwnerSupport {
     private final Ownable target;
     private final Set<Ownable> ownedObjects;
     private Owner currentOwner;
 
+    /**
+     * Create a new OwnerSupport that functions as both the {@link Owner} and
+     * {@link Ownable} implementation for <tt>target</tt>
+     * 
+     * @param target The actual ownable
+     */
     public OwnerSupport(Ownable target) {
+        if (target == null) {
+            throw new NullPointerException("Ownable cannot be null");
+        }
         this.target = target;
         ownedObjects = new HashSet<Ownable>();
         currentOwner = null;
     }
 
+    /**
+     * @see Owner#notifyOwnershipGranted(Ownable)
+     * @param obj
+     */
     public void notifyOwnershipGranted(Ownable obj) {
         ownedObjects.add(obj);
     }
 
+    /**
+     * @see Owner#notifyOwnershipRevoked(Ownable)
+     * @param obj
+     */
     public void notifyOwnershipRevoked(Ownable obj) {
         ownedObjects.remove(obj);
     }
 
+    /**
+     * @see Ownable#setOwner(Owner)
+     * @param owner
+     */
     public void setOwner(Owner owner) {
         if (currentOwner != null) {
             currentOwner.notifyOwnershipRevoked(target);
         }
     }
 
+    /**
+     * @see Ownable#getOwner()
+     * @return
+     */
     public Owner getOwner() {
         return currentOwner;
     }
 
+    /**
+     * Set the owner of all currently owned children to null. If any of the
+     * children are entities or components, they are removed from their creating
+     * system or entity, respectively.
+     */
     public void disownAndRemoveChildren() {
         // Mark all owned objects as not owned
         // if they are an entity or component, recurse and remove them as well
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.