Commits

Michael Ludwig  committed 3b6e9c5

Update line length style settings.
Add getCanonical() to Component (closes issue #50)

  • Participants
  • Parent commits 8556f04

Comments (0)

Files changed (71)

-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.lhkbob.entreri</groupId>
     <artifactId>entreri</artifactId>
                     </reportSet>
                     <reportSet>
                         <id>aggregate</id>
-                        <reports />
+                        <reports/>
                     </reportSet>
                 </reportSets>
             </plugin>
                     </reportSet>
                     <reportSet>
                         <id>aggregate</id>
-                        <reports />
+                        <reports/>
                     </reportSet>
                 </reportSets>
             </plugin>

File src/it/InvalidFactoryComponent/src/main/java/com/lhkbob/entreri/components/InvalidFactoryComponent.java

 import com.lhkbob.entreri.property.Factory;
 
 /**
- * A test component that mis-configures a component so that the property factory has the
- * incorrect type.
+ * A test component that mis-configures a component so that the property factory has the incorrect type.
  *
  * @author Michael Ludwig
  */

File src/it/InvalidSharedObjectComponent/src/main/java/com/lhkbob/entreri/components/InvalidSharedObjectComponent.java

 import com.lhkbob.entreri.property.SharedInstance;
 
 /**
- * Invalid component definition that double checks that we fail when using a shared
- * instance annotation with a object properties.
+ * Invalid component definition that double checks that we fail when using a shared instance annotation with a
+ * object properties.
  */
 public interface InvalidSharedObjectComponent extends Component {
     @SharedInstance

File src/it/InvalidSharedPrimitiveComponent/src/main/java/com/lhkbob/entreri/components/InvalidSharedPrimitiveComponent.java

 import com.lhkbob.entreri.property.SharedInstance;
 
 /**
- * Invalid component type that tries to have a shared instance from a property that
- * doesn't support it. Note that this failure also extends to any other property type that
- * isn't ObjectProperty that doesn't implement ShareableProperty.
+ * Invalid component type that tries to have a shared instance from a property that doesn't support it. Note
+ * that this failure also extends to any other property type that isn't ObjectProperty that doesn't implement
+ * ShareableProperty.
  */
 public interface InvalidSharedPrimitiveComponent extends Component {
     @SharedInstance

File src/it/MismatchedNameComponent/src/main/java/com/lhkbob/entreri/components/MismatchedNameComponent.java

 import com.lhkbob.entreri.property.Named;
 
 /**
- * A component type that uses mismatched Named annotations to break an otherwise valid
- * definition.
+ * A component type that uses mismatched Named annotations to break an otherwise valid definition.
  */
 public interface MismatchedNameComponent extends Component {
     @Named("right")

File src/it/MissingGetterComponent/src/main/java/com/lhkbob/entreri/components/MissingGetterComponent.java

 import com.lhkbob.entreri.Component;
 
 /**
- * A test component that has a mismatched property definition by missing a getter for the
- * setter.
+ * A test component that has a mismatched property definition by missing a getter for the setter.
  *
  * @author Michael Ludwig
  */

File src/it/MissingPropertyGetComponent/src/main/java/com/lhkbob/entreri/components/MissingPropertyGetComponent.java

 import com.lhkbob.entreri.property.PropertyFactory;
 
 /**
- * Invalid component type because it references a property type that doesn't have the
- * expected get method.
+ * Invalid component type because it references a property type that doesn't have the expected get method.
  */
 public interface MissingPropertyGetComponent extends Component {
     @Factory(MissingGetterFactory.class)
         }
     }
 
-    public static class MissingGetterFactory
-            implements PropertyFactory<MissingGetterProperty> {
+    public static class MissingGetterFactory implements PropertyFactory<MissingGetterProperty> {
         @Override
         public MissingGetterProperty create() {
             return new MissingGetterProperty();
         }
 
         @Override
-        public void clone(MissingGetterProperty src, int srcIndex,
-                          MissingGetterProperty dst, int dstIndex) {
+        public void clone(MissingGetterProperty src, int srcIndex, MissingGetterProperty dst, int dstIndex) {
         }
     }
 }

File src/it/MissingPropertySetComponent/src/main/java/com/lhkbob/entreri/components/MissingPropertySetComponent.java

 import com.lhkbob.entreri.property.PropertyFactory;
 
 /**
- * Invalid component type because it references a property type that doesn't have the
- * expected set method.
+ * Invalid component type because it references a property type that doesn't have the expected set method.
  */
 public interface MissingPropertySetComponent extends Component {
     @Factory(MissingSetterFactory.class)
         }
     }
 
-    public static class MissingSetterFactory
-            implements PropertyFactory<MissingSetterProperty> {
+    public static class MissingSetterFactory implements PropertyFactory<MissingSetterProperty> {
         @Override
         public MissingSetterProperty create() {
             return new MissingSetterProperty();
         }
 
         @Override
-        public void clone(MissingSetterProperty src, int srcIndex,
-                          MissingSetterProperty dst, int dstIndex) {
+        public void clone(MissingSetterProperty src, int srcIndex, MissingSetterProperty dst, int dstIndex) {
         }
     }
 }

File src/it/MissingSetterComponent/src/main/java/com/lhkbob/entreri/components/MissingSetterComponent.java

 import com.lhkbob.entreri.Component;
 
 /**
- * A test component that has a mismatched property definition by missing a setter for the
- * getter.
+ * A test component that has a mismatched property definition by missing a setter for the getter.
  *
  * @author Michael Ludwig
  */

File src/it/NonBeanComponent/src/main/java/com/lhkbob/entreri/components/NonBeanComponent.java

 import com.lhkbob.entreri.Component;
 
 /**
- * Test component that declares a method that doesn't follow the bean conventions and is
- * thus invalid.
+ * Test component that declares a method that doesn't follow the bean conventions and is thus invalid.
  */
 public interface NonBeanComponent extends Component {
     public void thisCantPossiblyBeABeanMethod();

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

 package com.lhkbob.entreri;
 
 /**
+ * Component represents a grouping of reusable and related states that are added to an {@link Entity}. An
+ * Entity's behavior is defined by the union of all components attached to it, and the system's configured
+ * tasks that process the entities. Tasks must be implemented and used in order to take advantage of a
+ * particular component configuration.
  * <p/>
- * Component represents a grouping of reusable and related states that are added to an
- * {@link Entity}. An Entity's behavior is defined by the union of all components attached
- * to it, and the system's configured tasks that process the entities. Tasks must be
- * implemented and used in order to take advantage of a particular component
- * configuration.
+ * An entity can be considered as a collection of aspects represented by component instances. An entity can
+ * have at most one instance of a component type at a time, although over its lifetime the specific component
+ * instance may change.
  * <p/>
- * An entity can be considered as a collection of aspects represented by component
- * instances. An entity can have at most one instance of a component type at a time,
- * although over its lifetime the specific component instance may change.
+ * Logically a component definition is a set of named and typed properties, and a method-based API to get and
+ * set the values of each property. Specific types of component are defined by creating a sub-interface of
+ * Component. Using the {@link com.lhkbob.entreri.property.Named Named}, {@link
+ * com.lhkbob.entreri.property.SharedInstance SharedInstance}, {@link com.lhkbob.entreri.property.Factory
+ * Factory} and custom {@link com.lhkbob.entreri.property.Attribute Attribute} annotations defined by {@link
+ * com.lhkbob.entreri.property.Property Property} implementations, the data properties of the component type
+ * are specified in the sub-interface. A declaration model similar to the Java Bean model is used and is
+ * outlined below:
  * <p/>
- * Logically a component definition is a set of named and typed properties, and a
- * method-based API to get and set the values of each property. Specific types of
- * component are defined by creating a sub-interface of Component. Using the {@link
- * com.lhkbob.entreri.property.Named Named}, {@link com.lhkbob.entreri.property.SharedInstance
- * SharedInstance}, {@link com.lhkbob.entreri.property.Factory Factory} and custom {@link
- * com.lhkbob.entreri.property.Attribute Attribute} annotations defined by {@link
- * com.lhkbob.entreri.property.Property Property} implementations, the data properties of
- * the component type are specified in the sub-interface. A declaration model similar to
- * the Java Bean model is used and is outlined below:
+ * <ol> <li>Non-void, zero-argument methods starting with 'get', 'is', and 'has' declare a property. The
+ * property type is inspected from the return type of the method. The property name is the method name minus
+ * the 'get'/'is'/'has' prefix with its first letter made lower-case. The {@link
+ * com.lhkbob.entreri.property.Named Named} annotation can be used to override the name.</li>
+ * <li>Single-argument methods starting with 'set' are assumed to be a setter corresponding to a property. The
+ * single parameter's type must equal the type the getter. The {@link com.lhkbob.entreri.property.Named Named}
+ * annotation can be applied to either the setter or the parameter to specify the property name.</li>
+ * <li>Multi-argument methods starting with 'set' are assumed to be a setter that assigns values to multiple
+ * property, one for each argument. Each argument must be annotated with {@link
+ * com.lhkbob.entreri.property.Named Named} to specify the property, and the argument type must equal the type
+ * of the matching property.</li> <li>Setter methods must return void or return the components type, in which
+ * case the proxy will return itself to allow for method chaining.</li> <li>Getters with void return types or
+ * more than 0 arguments, setters with an invalid return type or no arguments, and any other method not
+ * matching the conventions above will cause the system to throw an {@link IllegalComponentDefinitionException}.</li>
+ * </ol>
  * <p/>
- * <ol> <li>Non-void, zero-argument methods starting with 'get', 'is', and 'has' declare a
- * property. The property type is inspected from the return type of the method. The
- * property name is the method name minus the 'get'/'is'/'has' prefix with its first
- * letter made lower-case. The {@link com.lhkbob.entreri.property.Named Named} annotation
- * can be used to override the name.</li> <li>Single-argument methods starting with 'set'
- * are assumed to be a setter corresponding to a property. The single parameter's type
- * must equal the type the getter. The {@link com.lhkbob.entreri.property.Named Named}
- * annotation can be applied to either the setter or the parameter to specify the property
- * name.</li> <li>Multi-argument methods starting with 'set' are assumed to be a setter
- * that assigns values to multiple property, one for each argument. Each argument must be
- * annotated with {@link com.lhkbob.entreri.property.Named Named} to specify the property,
- * and the argument type must equal the type of the matching property.</li> <li>Setter
- * methods must return void or return the components type, in which case the proxy will
- * return itself to allow for method chaining.</li> <li>Getters with void return types or
- * more than 0 arguments, setters with an invalid return type or no arguments, and any
- * other method not matching the conventions above will cause the system to throw an
- * {@link IllegalComponentDefinitionException}.</li> </ol>
- * <p/>
- * Internally, the entity system will generate proxy implementations of the component
- * interfaces that implement the property getters and setters but store all of the values
- * in {@link com.lhkbob.entreri.property.Property} instances of a compatible type. This
- * allows iteration over components to have much better cache locality if the component is
- * defined in terms of primitives or types that have specialized Property implementations
- * that can pack and unpack an instance. The {@link com.lhkbob.entreri.property.SharedInstance
- * SharedInstance} annotation can be added to the getter method of a property to specify
- * that the {@link com.lhkbob.entreri.property.ShareableProperty ShareableProperty} API
+ * Internally, the entity system will generate proxy implementations of the component interfaces that
+ * implement the property getters and setters but store all of the values in {@link
+ * com.lhkbob.entreri.property.Property} instances of a compatible type. This allows iteration over components
+ * to have much better cache locality if the component is defined in terms of primitives or types that have
+ * specialized Property implementations that can pack and unpack an instance. The {@link
+ * com.lhkbob.entreri.property.SharedInstance SharedInstance} annotation can be added to the getter method of
+ * a property to specify that the {@link com.lhkbob.entreri.property.ShareableProperty ShareableProperty} API
  * should be leveraged by the generated class.
  * <p/>
- * Additional attribute annotations can be added to the getter method to influence the
- * behavior of the {@link com.lhkbob.entreri.property.PropertyFactory PropertyFactory}
- * used for each property in the component definition. Besides using the Factory
- * annotation to specify the factory type, a property implementation can be associated
- * with a type with canonical name <var>C</var> by adding the file
- * META-INF/entreri/mapping/C to the classpath, where its contents must be:
+ * Additional attribute annotations can be added to the getter method to influence the behavior of the {@link
+ * com.lhkbob.entreri.property.PropertyFactory PropertyFactory} used for each property in the component
+ * definition. Besides using the Factory annotation to specify the factory type, a property implementation can
+ * be associated with a type with canonical name <var>C</var> by adding the file META-INF/entreri/mapping/C to
+ * the classpath, where its contents must be:
  * <pre>
  *     &lt;BINARY NAME OF PROPERTY&gt;
  * </pre>
  * where the value is suitable for passing into {@link Class#forName(String)}.
  * <p/>
- * Attribute annotations provided by the default property implementations are outlined
- * below: <ul> <li>{@link com.lhkbob.entreri.property.BooleanProperty.DefaultBoolean
- * DefaultBoolean} - set value for boolean properties</li> <li>{@link
- * com.lhkbob.entreri.property.ByteProperty.DefaultByte DefaultByte} - set value for byte
- * properties</li> <li>{@link com.lhkbob.entreri.property.ShortProperty.DefaultShort
- * DefaultShort} - set value for short properties</li> <li>{@link
- * com.lhkbob.entreri.property.IntProperty.DefaultInt DefaultInt} - set value for int
- * properties</li> <li>{@link com.lhkbob.entreri.property.LongProperty.DefaultLong
- * DefaultLong} - set value for long properties</li> <li>{@link
- * com.lhkbob.entreri.property.FloatProperty.DefaultFloat DefaultFloat} - set value for
- * float properties</li> <li>{@link com.lhkbob.entreri.property.DoubleProperty.DefaultDouble
- * DefaultDouble} - set value for double properties</li> <li>{@link
- * com.lhkbob.entreri.property.CharProperty.DefaultChar DefaultChar} - set value for char
- * properties</li> <li>{@link com.lhkbob.entreri.property.Clone Clone} - specify clone
- * policy used with entity or component templates</li> </ul> Note that there are no
- * annotations that work with general object types. This is because the scope of that
- * problem is intractable. The default ObjectProperty implementation assumes null values
- * are allowed and that the default value is null.
+ * Attribute annotations provided by the default property implementations are outlined below: <ul> <li>{@link
+ * com.lhkbob.entreri.property.BooleanProperty.DefaultBoolean DefaultBoolean} - set value for boolean
+ * properties</li> <li>{@link com.lhkbob.entreri.property.ByteProperty.DefaultByte DefaultByte} - set value
+ * for byte properties</li> <li>{@link com.lhkbob.entreri.property.ShortProperty.DefaultShort DefaultShort} -
+ * set value for short properties</li> <li>{@link com.lhkbob.entreri.property.IntProperty.DefaultInt
+ * DefaultInt} - set value for int properties</li> <li>{@link com.lhkbob.entreri.property.LongProperty.DefaultLong
+ * DefaultLong} - set value for long properties</li> <li>{@link com.lhkbob.entreri.property.FloatProperty.DefaultFloat
+ * DefaultFloat} - set value for float properties</li> <li>{@link com.lhkbob.entreri.property.DoubleProperty.DefaultDouble
+ * DefaultDouble} - set value for double properties</li> <li>{@link com.lhkbob.entreri.property.CharProperty.DefaultChar
+ * DefaultChar} - set value for char properties</li> <li>{@link com.lhkbob.entreri.property.Clone Clone} -
+ * specify clone policy used with entity or component templates</li> </ul> Note that there are no annotations
+ * that work with general object types. This is because the scope of that problem is intractable. The default
+ * ObjectProperty implementation assumes null values are allowed and that the default value is null.
  * <p/>
- * The generated proxies will implement equals() and hashCode() based on their type and
- * the id of their owning entity. The {@link ComponentIterator} class creates flyweight
- * component instances whose identity changes as iteration proceeds; equals() and
- * hashCode() will behave appropriately. This means that flyweight components should not
- * be stored in collections that depend on equality or hashes. Flyweight components are
- * used for performance reasons when iterating over the entities in a system with specific
- * component configurations because the JVM does not need to load each unique component
- * instance into the cache.
+ * The generated proxies will implement equals() and hashCode() based on their type and the id of their owning
+ * entity. The {@link ComponentIterator} class creates flyweight component instances whose identity changes as
+ * iteration proceeds; equals() and hashCode() will behave appropriately. This means that flyweight components
+ * should not be stored in collections that depend on equality or hashes. Flyweight components are used for
+ * performance reasons when iterating over the entities in a system with specific component configurations
+ * because the JVM does not need to load each unique component instance into the cache.
  * <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.
+ * 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.
  *
  * @author Michael Ludwig
  */
     public EntitySystem getEntitySystem();
 
     /**
-     * Get the entity that this component is attached to. If the component has been
-     * removed from the entity, or is otherwise not live, this will return null.
+     * Get the entity that this component is attached to. If the component has been removed from the entity,
+     * or is otherwise not live, this will return null.
      *
      * @return The owning entity, or null
      */
     public Entity getEntity();
 
     /**
-     * <p/>
-     * Get whether or not the component is still attached to an alive entity in an entity
-     * system. This will return false if it or its entity has been removed. If the
-     * component is a flyweight object used in iteration, it can also return false when
-     * iteration has terminated.
+     * Get whether or not the component is still attached to an alive entity in an entity system. This will
+     * return false if it or its entity has been removed. If the component is a flyweight object used in
+     * iteration, it can also return false when iteration has terminated.
      * <p/>
      * Using property getters or setters on a dead component produces undefined behavior.
      *
-     * @return True if the component is still attached to an entity in the entity system,
-     *         or false if it or its entity has been removed
+     * @return True if the component is still attached to an entity in the entity system, or false if it or
+     *         its entity has been removed
      */
     public boolean isAlive();
 
     /**
+     * Get whether or not this particular instance is a flyweight component object. A flyweight instance is
+     * used by ComponentIterators to efficiently view the underlying component data iteratively. It is safe to
+     * set the owner of a flyweight component or to set the flyweight as an owner of another object. It will
+     * correctly register the canonical component as the owner.
      * <p/>
-     * Get whether or not this particular instance is a flyweight component object. A
-     * flyweight instance is used by ComponentIterators to efficiently view the underlying
-     * component data iteratively. It is safe to set the owner of a flyweight component or
-     * to set the flyweight as an owner of another object. It will correctly register the
-     * canonical component as the owner.
-     * <p/>
-     * Components returned by {@link Entity#add(Class)}, {@link Entity#get(Class)}, and
-     * its other component returning functions will always return non-flyweight
-     * components. These components are the 'canonical' instances for that component type
-     * and entity.
+     * Components returned by {@link Entity#add(Class)}, {@link Entity#get(Class)}, and its other component
+     * returning functions will always return non-flyweight components. These components are the 'canonical'
+     * instances for that component type and entity.
      *
-     * @return True if this component is a flyweight instance iterating over a list of
-     *         components
+     * @return True if this component is a flyweight instance iterating over a list of components
      */
     public boolean isFlyweight();
 
     /**
+     * Get the canonicla Component reference for this component. If {@link #isFlyweight()} returns false, then
+     * this just returns itself. If it returns true, this will return the canonical reference corresponding to
+     * this component's identity, i.e. {@code foo.getEntity().get(Foo.class)}.
      * <p/>
-     * Get the underlying index of this component used to access its properties. For most
-     * uses, you should not need to use this method.  As an EntitySystem manages and
-     * compacts the component data storage, a component's index can change. The index
-     * should be used to access decorated properties, which will be kept in-sync with any
-     * compactions.
+     * Behavior is undefined for components that are dead.
+     *
+     * @return The canonical component
+     */
+    public Component getCanonical();
+
+    /**
+     * Get the underlying index of this component used to access its properties. For most uses, you should not
+     * need to use this method.  As an EntitySystem manages and compacts the component data storage, a
+     * component's index can change. The index should be used to access decorated properties, which will be
+     * kept in-sync with any compactions.
      * <p/>
-     * Additionally, some component instances may be flyweight objects used for iteration.
-     * In this case, every iteration will update its index and the component object's
-     * identity will change as well. See {@link ComponentIterator} for more information.
+     * Additionally, some component instances may be flyweight objects used for iteration. In this case, every
+     * iteration will update its index and the component object's identity will change as well. See {@link
+     * ComponentIterator} for more information.
      *
      * @return The current index of component
      */
     public int getIndex();
 
     /**
+     * Get the current version of the data of this component. When a component's data is mutated,
+     * implementations increment its version so comparing a previously cached version number can be used to
+     * determine when changes have been made.
      * <p/>
-     * Get the current version of the data of this component. When a component's data is
-     * mutated, implementations increment its version so comparing a previously cached
-     * version number can be used to determine when changes have been made.
-     * <p/>
-     * Within a component type for an entity system, version values will be unique across
-     * component instances. Thus, {@code entity.as(T.class).getVersion() != cachedVersion}
-     * will correctly detect changes to the original component instance as well as the
-     * removal and replacement by a new component of type T.
+     * Within a component type for an entity system, version values will be unique across component instances.
+     * Thus, {@code entity.as(T.class).getVersion() != cachedVersion} will correctly detect changes to the
+     * original component instance as well as the removal and replacement by a new component of type T.
      *
      * @return The current version, or a negative number if the data is invalid
      */
     public int getVersion();
 
     /**
-     * Increment the version of the component accessed by this instance. This will be
-     * automatically called by all exposed setters by the generated proxies, but if
-     * necessary it can be invoked manually as well.
+     * Increment the version of the component accessed by this instance. This will be automatically called by
+     * all exposed setters by the generated proxies, but if necessary it can be invoked manually as well.
      *
      * @see #getVersion()
      */
     public void updateVersion();
 
     /**
-     * Get the class identifier for this component. This will be the specific
-     * sub-interface of Component that this object is an instance of. getType() should be
-     * used instead of {@link Object#getClass()} because that will return a specific and
-     * most likely generated proxy implementation of the component type.
+     * Get the class identifier for this component. This will be the specific sub-interface of Component that
+     * this object is an instance of. getType() should be used instead of {@link Object#getClass()} because
+     * that will return a specific and most likely generated proxy implementation of the component type.
      *
      * @return The component type
      */

File src/main/java/com/lhkbob/entreri/ComponentIterator.java

 
 /**
  * <p/>
- * ComponentIterator is an {@link Iterator}-like class used for quickly iterating over
- * subsets of entities within an EntitySystem with direct access to the components you're
- * interested in. You specify the component classes using {@link #addRequired(Class)} and
- * {@link #addOptional(Class)}, which return flyweight component instances that are
- * updated as the iterator is looped through. These determine the constraints on the
- * entities reported by the iterator. ComponentIterator is reset-able, so the same
- * instance and created components can be reused for multiple iterations.
+ * ComponentIterator is an {@link Iterator}-like class used for quickly iterating over subsets of entities
+ * within an EntitySystem with direct access to the components you're interested in. You specify the component
+ * classes using {@link #addRequired(Class)} and {@link #addOptional(Class)}, which return flyweight component
+ * instances that are updated as the iterator is looped through. These determine the constraints on the
+ * entities reported by the iterator. ComponentIterator is reset-able, so the same instance and created
+ * components can be reused for multiple iterations.
  * <p/>
- * The ComponentIterator will skip all entities that do not have components of the
- * required component types. This is very useful in Tasks because often there related
- * component types that you want to fetch and process at the same time. Optional
- * Component's will be set to the entity if present otherwise they'll be marked as dead.
+ * The ComponentIterator will skip all entities that do not have components of the required component types.
+ * This is very useful in Tasks because often there related component types that you want to fetch and process
+ * at the same time. Optional Component's will be set to the entity if present otherwise they'll be marked as
+ * dead.
  * <p/>
- * The basic workflow for using a ComponentIterator is shown below. In the example, the
- * iterator is used to iterate over all entities that have both an A and a B component,
- * while optionally loading a C component if available.
+ * The basic workflow for using a ComponentIterator is shown below. In the example, the iterator is used to
+ * iterate over all entities that have both an A and a B component, while optionally loading a C component if
+ * available.
  * <pre>
  * // create iterator
  * ComponentIterator it = new ComponentIterator(system);
  */
 public interface ComponentIterator {
     /**
-     * Add the given Component type as a required component for this iterator. The
-     * returned flyweight instance must be used to access the data for the component at
-     * each iteration. Every call to {@link #next()} will update its identity to be the
-     * corresponding component of type T whose entity has all required components.
+     * Add the given Component type as a required component for this iterator. The returned flyweight instance
+     * must be used to access the data for the component at each iteration. Every call to {@link #next()} will
+     * update its identity to be the corresponding component of type T whose entity has all required
+     * components.
      *
      * @return A flyweight instance to access the current values for the component type
      *
     public <T extends Component> T addRequired(Class<T> type);
 
     /**
-     * Add the given Component type as an optional component for this iterator. The
-     * returned flyweight instance must be used to access the data for the component at
-     * each iteration. Every call to {@link #next()} will update its identity to be the
-     * corresponding component of type T if the entity has a component of type T.
+     * Add the given Component type as an optional component for this iterator. The returned flyweight
+     * instance must be used to access the data for the component at each iteration. Every call to {@link
+     * #next()} will update its identity to be the corresponding component of type T if the entity has a
+     * component of type T.
      * <p/>
-     * If it does not then the component will be marked as dead until a future iteration
-     * has a T component
+     * If it does not then the component will be marked as dead until a future iteration has a T component
      *
      * @return A flyweight instance to access the current values for the component type
      *
 
     /**
      * <p/>
-     * Advance the iterator to the next Entity that has components of all required types.
-     * Every flyweight component returned by previous calls to {@link #addRequired(Class)}
-     * will be updated to point to that entity. The optional flyweight components will be
-     * updated to the entity if a component exists. They may not be, in which case they
-     * will be flagged as invalid.
+     * Advance the iterator to the next Entity that has components of all required types. Every flyweight
+     * component returned by previous calls to {@link #addRequired(Class)} will be updated to point to that
+     * entity. The optional flyweight components will be updated to the entity if a component exists. They may
+     * not be, in which case they will be flagged as invalid.
      * <p/>
-     * It can be assumed that when an Entity is found that all required components are
-     * valid and reference that entity's components of the appropriate type.
+     * It can be assumed that when an Entity is found that all required components are valid and reference
+     * that entity's components of the appropriate type.
      * <p/>
-     * True is returned if an Entity was found. False is returned if there were no more
-     * entities matching the requirements in the system. Additionally, if there has been
-     * no call to {@link #addRequired(Class)} false is always returned. The iterator must
-     * be constrained by at least one required type.
+     * True is returned if an Entity was found. False is returned if there were no more entities matching the
+     * requirements in the system. Additionally, if there has been no call to {@link #addRequired(Class)}
+     * false is always returned. The iterator must be constrained by at least one required type.
      *
-     * @return True if another entity was found and the required components (and any
-     *         present optional components) have been updated to that entity
+     * @return True if another entity was found and the required components (and any present optional
+     *         components) have been updated to that entity
      */
     public boolean next();
 
     /**
-     * Reset this ComponentIterator to the beginning of the system to perform another
-     * complete iteration. This does not change the identities of the created flyweight
-     * components until the next call to {@link #next()} is made, at which point they are
-     * updated to first valid matching components.
+     * Reset this ComponentIterator to the beginning of the system to perform another complete iteration. This
+     * does not change the identities of the created flyweight components until the next call to {@link
+     * #next()} is made, at which point they are updated to first valid matching components.
      */
     public void reset();
 }

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

 
 /**
  * <p/>
- * An Entity represents a collection of Components within an EntitySystem. Entities are
- * created by calling {@link com.lhkbob.entreri.EntitySystem#addEntity()} or the similar
- * function that takes another Entity as a template.
+ * An Entity represents a collection of Components within an EntitySystem. Entities are created by calling
+ * {@link com.lhkbob.entreri.EntitySystem#addEntity()} or the similar function that takes another Entity as a
+ * template.
  * <p/>
- * Once created the Entity object will not change its identity. There are no flyweight
- * entities, unlike components which do use that design pattern.
+ * Once created the Entity object will not change its identity. There are no flyweight entities, unlike
+ * components which do use that design pattern.
  * <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.
+ * 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.
  *
  * @author Michael Ludwig
  */
     public EntitySystem getEntitySystem();
 
     /**
-     * @return True if this Entity is still in its EntitySystem, or false if it has been
-     *         removed
+     * @return True if this Entity is still in its EntitySystem, or false if it has been removed
      */
     public boolean isAlive();
 
     /**
      * <p/>
-     * Get the Component instance of the given type that's attached to this Entity. A null
-     * value is returned if the component type has not been attached to the entity.
+     * Get the Component instance of the given type that's attached to this Entity. A null value is returned
+     * if the component type has not been attached to the entity.
      *
      * @param <T>           The parameterized type of ComponentData of the component
      * @param componentType The given type
 
     /**
      * <p/>
-     * Add a new Component with a data type T to this Entity. If there already exists a
-     * component of type T, it is removed first, and a new one is instantiated.
+     * Add a new Component with a data type T to this Entity. If there already exists a component of type T,
+     * it is removed first, and a new one is instantiated.
      *
      * @param <T>           The parameterized type of component being added
      * @param componentType The component type
 
     /**
      * <p/>
-     * Add a new Component with a of type T to this Entity, but the new component's state
-     * will be cloned from the given Component instance. The <var>toClone</var> instance
-     * must still be live. If there already exists a component of type T, it is removed
-     * first, and a new one is instantiated.
+     * Add a new Component with a of type T to this Entity, but the new component's state will be cloned from
+     * the given Component instance. The <var>toClone</var> instance must still be live. If there already
+     * exists a component of type T, it is removed first, and a new one is instantiated.
      * <p/>
-     * The new component is initialized by cloning the property values from
-     * <var>toClone</var> into the values of the new component.
+     * The new component is initialized by cloning the property values from <var>toClone</var> into the values
+     * of the new component.
      *
      * @param <T>     The parameterized type of component to add
      * @param toClone The existing T to clone when attaching to this component
     public <T extends Component> T add(T toClone);
 
     /**
-     * Get the canonical component instance of type <var>T</var> on this Entity. Unlike
-     * {@link #get(Class)}, this will add the component if it is not present. Thus, this
-     * is a convenience for getting the component, and adding it if the get returned
-     * null.
+     * Get the canonical component instance of type <var>T</var> on this Entity. Unlike {@link #get(Class)},
+     * this will add the component if it is not present. Thus, this is a convenience for getting the
+     * component, and adding it if the get returned null.
      *
      * @param type The class interface of the component to add
      * @param <T>  The parameterized type of component
      *
-     * @return The component of type T, potentially new if it wasn't already on the
-     *         entity
+     * @return The component of type T, potentially new if it wasn't already on the entity
      */
     public <T extends Component> T as(Class<T> type);
 
     /**
-     * Check whether or not the a component of the given type is attached to this entity.
-     * This is a convenience for getting the component and then checking if it's null.
+     * Check whether or not the a component of the given type is attached to this entity. This is a
+     * convenience for getting the component and then checking if it's null.
      *
      * @param type The component type to check for
      *
-     * @return True if the entity currently has the attached type, in which case get()
-     *         will return a non-null alive component
+     * @return True if the entity currently has the attached type, in which case get() will return a non-null
+     *         alive component
      */
     public boolean has(Class<? extends Component> type);
 
     /**
      * <p/>
-     * Remove any attached Component with the data type from this Entity. True is returned
-     * if a component was removed, and false otherwise. If a component is removed, the
-     * component should no longer be used and it will return false from {@link
-     * Component#isAlive()}.
+     * Remove any attached Component with the data type from this Entity. True is returned if a component was
+     * removed, and false otherwise. If a component is removed, the component should no longer be used and it
+     * will return false from {@link Component#isAlive()}.
      * <p/>
-     * When a Component is removed, it will set its owner to null, and disown all of its
-     * owned objects. If any of those owned objects are entities or components, they are
-     * removed from the system as well.
+     * When a Component is removed, it will set its owner to null, and disown all of its owned objects. If any
+     * of those owned objects are entities or components, they are removed from the system as well.
      *
      * @param componentType The component type
      *
 
     /**
      * <p/>
-     * Return an iterator over the components currently attached to the Entity. The
-     * iterator supports the remove operation and will detach the component from the
-     * entity just like a call to {@link #remove(Class)}.
+     * Return an iterator over the components currently attached to the Entity. The iterator supports the
+     * remove operation and will detach the component from the entity just like a call to {@link
+     * #remove(Class)}.
      * <p/>
      * Components reported by the iterator are not flyweight.
      *

File src/main/java/com/lhkbob/entreri/EntitySystem.java

 
 /**
  * <p/>
- * EntitySystem is the main container for the entities within a logical system such as a
- * game or physics world. It contains all entities needed for processing the scene or
- * data. Entities are created with {@link #addEntity()} or {@link #addEntity(Entity)}.
- * They can be removed (and effectively destroyed) with {@link #removeEntity(Entity)}.
+ * EntitySystem is the main container for the entities within a logical system such as a game or physics
+ * world. It contains all entities needed for processing the scene or data. Entities are created with {@link
+ * #addEntity()} or {@link #addEntity(Entity)}. They can be removed (and effectively destroyed) with {@link
+ * #removeEntity(Entity)}.
  * <p/>
- * After an Entity is created, Components can be added to it to store domain-specific data
- * and configure its behaviors. The specifics of the data and behavior depends on the
- * Component implementations and Tasks used to process your data.
+ * After an Entity is created, Components can be added to it to store domain-specific data and configure its
+ * behaviors. The specifics of the data and behavior depends on the Component implementations and Tasks used
+ * to process your data.
  * <p/>
- * The {@link Scheduler} of an EntitySystem can be used to create {@link
- * com.lhkbob.entreri.task.Job Jobs} composed of {@link Task Tasks} that will process the
- * entities within an entity system in an organized fashion. Generally, the processing of
- * all controllers through their different phases constitutes a complete "frame".
+ * The {@link Scheduler} of an EntitySystem can be used to create {@link com.lhkbob.entreri.task.Job Jobs}
+ * composed of {@link Task Tasks} that will process the entities within an entity system in an organized
+ * fashion. Generally, the processing of all controllers through their different phases constitutes a complete
+ * "frame".
  * <p/>
- * When Entities are created by an EntitySystem, the created instance is assigned an ID
- * which represents its true identity.
+ * When Entities are created by an EntitySystem, the created instance is assigned an ID which represents its
+ * true identity.
  * <p/>
  * Use {@link Factory#create()} to get a new instance of an EntitySystem.
  *
  * @see Component
  */
 public interface EntitySystem extends Iterable<Entity> {
-    public static class Factory {
+    public static final class Factory {
+        private Factory() {
+        }
+
         /**
          * Create a new EntitySystem using the default implementation with entreri
          *
     }
 
     /**
-     * Get all Component types within this EntitySystem that have types assignable to the
-     * input <var>type</var>.
+     * Get all Component types within this EntitySystem that have types assignable to the input
+     * <var>type</var>.
      *
      * @param type The query type
      *
-     * @return All Component interfaces that have components in this EntitySystem that are
-     *         subclasses of the input component data type
+     * @return All Component interfaces that have components in this EntitySystem that are subclasses of the
+     *         input component data type
      *
      * @throws NullPointerException if type is null
      */
-    public <T extends Component> Collection<Class<? extends T>> getComponentTypes(
-            Class<T> type);
+    public <T extends Component> Collection<Class<? extends T>> getComponentTypes(Class<T> type);
 
     /**
-     * Get all Component interfaces currently used by the EntitySystem. If a type has had
-     * all of its components removed, it will still be returned here.
+     * Get all Component interfaces currently used by the EntitySystem. If a type has had all of its
+     * components removed, it will still be returned here.
      *
      * @return All TypeIds at one point used by this system
      */
     public Collection<Class<? extends Component>> getComponentTypes();
 
     /**
-     * Return the Scheduler for this EntitySystem that can be used to organize processing
-     * of the system using {@link Task} implementations.
+     * Return the Scheduler for this EntitySystem that can be used to organize processing of the system using
+     * {@link Task} implementations.
      *
      * @return The Scheduler for this system
      */
     public Scheduler getScheduler();
 
     /**
-     * Return an iterator over all of the entities within the system. The returned
-     * iterator's remove() method will remove the entity from the system with behavior
-     * identical to calling {@link #removeEntity(Entity)}.
+     * Return an iterator over all of the entities within the system. The returned iterator's remove() method
+     * will remove the entity from the system with behavior identical to calling {@link
+     * #removeEntity(Entity)}.
      *
      * @return An iterator over the entities of the system
      */
     public Iterator<Entity> iterator();
 
     /**
-     * Return an iterator over all components of with the given type. The returned
-     * iterator uses a single flyweight Component instance of T, so it is a fast iterator.
-     * This effectively wraps a {@link ComponentIterator} in a standard {@link Iterator}
-     * with a single required component type.
+     * Return an iterator over all components of with the given type. The returned iterator uses a single
+     * flyweight Component instance of T, so it is a fast iterator. This effectively wraps a {@link
+     * ComponentIterator} in a standard {@link Iterator} with a single required component type.
      *
      * @param type The type of component to iterate over
      *
     public <T extends Component> Iterator<T> iterator(Class<T> type);
 
     /**
-     * Return a new ComponentIterator that must be configured with required and optional
-     * components before use.
+     * Return a new ComponentIterator that must be configured with required and optional components before
+     * use.
      *
      * @return A new iterator over the components in this system
      */
 
     /**
      * <p/>
-     * Compact the entity and component data so that iteration is more efficient. In the
-     * life time of an entity system, entities and components are added and removed,
-     * possibly causing the list of components for a given type to be in a different order
-     * than the list of entities. This is due to implementation details needed to make
-     * additions and removals constant time.
+     * Compact the entity and component data so that iteration is more efficient. In the life time of an
+     * entity system, entities and components are added and removed, possibly causing the list of components
+     * for a given type to be in a different order than the list of entities. This is due to implementation
+     * details needed to make additions and removals constant time.
      * <p/>
-     * Invoking compact() after a large number of additions or removals to the system is a
-     * good idea. Alternatively, invoking it every few frames in a game works as well. An
-     * entity system that has no additions or removals of entities (or their components)
-     * gains no benefit from compacting, except potentially freeing excess memory.
+     * Invoking compact() after a large number of additions or removals to the system is a good idea.
+     * Alternatively, invoking it every few frames in a game works as well. An entity system that has no
+     * additions or removals of entities (or their components) gains no benefit from compacting, except
+     * potentially freeing excess memory.
      * <p/>
-     * Compacting is not overly fast or slow, so it should not cause noticeably drops in
-     * frame rate. As an example, on a test system with 20,000 entities compact() took
-     * ~2ms on an Intel i5 processor. Of course, mileage may very.
+     * Compacting is not overly fast or slow, so it should not cause noticeably drops in frame rate. As an
+     * example, on a test system with 20,000 entities compact() took ~2ms on an Intel i5 processor. Of course,
+     * mileage may very.
      */
     public void compact();
 
     /**
-     * Add a new Entity to this EntitySystem. The created Entity will not have any
-     * attached Components. You can create a new entity from a template by calling {@link
-     * #addEntity(Entity)}.
+     * Add a new Entity to this EntitySystem. The created Entity will not have any attached Components. You
+     * can create a new entity from a template by calling {@link #addEntity(Entity)}.
      *
      * @return A new Entity in the system, without any components
      */
 
     /**
      * <p/>
-     * Add a new Entity to this EntitySystem. If <var>template</var> is not null, the
-     * components attached to the template will have their state cloned onto the new
-     * entity. The semantics of cloning is defined by {@link com.lhkbob.entreri.property.PropertyFactory#clone(com.lhkbob.entreri.property.Property,
-     * int, com.lhkbob.entreri.property.Property, int)}, but by default it follows Java's
-     * reference/value rule.
+     * Add a new Entity to this EntitySystem. If <var>template</var> is not null, the components attached to
+     * the template will have their state cloned onto the new entity. The semantics of cloning is defined by
+     * {@link com.lhkbob.entreri.property.PropertyFactory#clone(com.lhkbob.entreri.property.Property, int,
+     * com.lhkbob.entreri.property.Property, int)}, but by default it follows Java's reference/value rule.
      * <p/>
      * Specifying a null template makes this behave identically to {@link #addEntity()}.
      *
 
     /**
      * <p/>
-     * Remove the given entity from this system. The entity and its attached components
-     * are removed from the system. This will cause the entity and its components to no
-     * longer be alive. Any ComponentData's referencing the entity's components will
-     * become invalid until assigned to a new component.
+     * Remove the given entity from this system. The entity and its attached components are removed from the
+     * system. This will cause the entity and its components to no longer be alive. Any ComponentData's
+     * referencing the entity's components will become invalid until assigned to a new component.
      * <p/>
-     * When an entity is removed, it will set its owner to null, and disown all of its
-     * owned objects. If any of those owned objects are entities or components, they are
-     * removed from the system as well.
+     * When an entity is removed, it will set its owner to null, and disown all of its owned objects. If any
+     * of those owned objects are entities or components, they are removed from the system as well.
      *
      * @param e The entity to remove
      *
      * @throws NullPointerException     if e is null
-     * @throws IllegalArgumentException if the entity was not created by this system, or
-     *                                  already removed
+     * @throws IllegalArgumentException if the entity was not created by this system, or already removed
      */
     public void removeEntity(Entity e);
 
     /**
      * <p/>
-     * Dynamically update the available properties of the given Component type by adding a
-     * Property created by the given PropertyFactory. The property will be managed by the
-     * system as if it was a declared property of the component type.
+     * Dynamically update the available properties of the given Component type by adding a Property created by
+     * the given PropertyFactory. The property will be managed by the system as if it was a declared property
+     * of the component type.
      * <p/>
-     * All components, current and new, will initially have their starting values for the
-     * decorated property be the default as defined by the factory. The returned property
-     * can be accessed and used by Tasks to add dynamic runtime data to statically defined
-     * component types.
+     * All components, current and new, will initially have their starting values for the decorated property
+     * be the default as defined by the factory. The returned property can be accessed and used by Tasks to
+     * add dynamic runtime data to statically defined component types.
      *
      * @param <P>     The created property type
      * @param type    The component type to mutate
      *
      * @throws NullPointerException if type or factory are null
      */
-    public <T extends Component, P extends Property> P decorate(Class<T> type,
-                                                                PropertyFactory<P> factory);
+    public <T extends Component, P extends Property> P decorate(Class<T> type, PropertyFactory<P> factory);
 }

File src/main/java/com/lhkbob/entreri/IllegalComponentDefinitionException.java

 package com.lhkbob.entreri;
 
 /**
- * IllegalComponentDefinitionException is an exception thrown if a Component
- * implementation does not follow the class hierarchy or field rules defined in {@link
- * Component}.
+ * IllegalComponentDefinitionException is an exception thrown if a Component implementation does not follow
+ * the class hierarchy or field rules defined in {@link Component}.
  *
  * @author Michael Ludwig
  */
     private final String componentTypeName;
 
     /**
-     * Create an exception that specifies the leaf-level class in a Component type
-     * hierarchy has some problem with its definition
+     * Create an exception that specifies the leaf-level class in a Component type hierarchy has some problem
+     * with its definition
      *
      * @param componentTypeName The canonical class name of the component type
-     * @param problem           A generic error message to be tacked to the end of the
-     *                          final error message
+     * @param problem           A generic error message to be tacked to the end of the final error message
      */
     public IllegalComponentDefinitionException(String componentTypeName, String problem) {
         super(componentTypeName + " is invalid, error: " + problem);

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

 
 /**
  * <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.
+ * 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.
+ * 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.
+     * 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.
      *
     public void setOwner(Owner owner);
 
     /**
-     * Get the current owner of this object. If null is returned, the object is not owned
-     * by anything.
+     * Get the current owner of this object. If null is returned, the object is not owned by anything.
      *
      * @return The current owner
      */

File 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.
+ * 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 <var>obj</var>'s owner. This must only be called
-     * by {@link Ownable} implementations in response to calls to {@link
-     * Ownable#setOwner(Owner)}.
+     * Notify this Owner that it is now <var>obj</var>'s owner. This must only be called by {@link Ownable}
+     * implementations in response to calls to {@link Ownable#setOwner(Owner)}.
      * <p/>
-     * This method returns the true Owner instance, to allow for flyweight objects to act
-     * as Owners. In this case, they will return the canonical owner for the datum they
-     * represent. In regular cases, this will return itself after recording ownership.
+     * This method returns the true Owner instance, to allow for flyweight objects to act as Owners. In this
+     * case, they will return the canonical owner for the datum they represent. In regular cases, this will
+     * return itself after recording ownership.
      *
      * @param obj The newly owned object
      *
 
     /**
      * <p/>
-     * Notify this Owner that it is no longer <var>obj</var>'s owner. This must only be
-     * called by {@link Ownable} implementations in response to calls to {@link
-     * Ownable#setOwner(Owner)}.
+     * Notify this Owner that it is no longer <var>obj</var>'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.
+     * 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
      */

File src/main/java/com/lhkbob/entreri/Requires.java

 
 /**
  * <p/>
- * The Requires annotation can be used to specify dependencies within a package of
- * components. If one component requires the use of another, such as a scene or light
- * component needing a transform, this can be a convenient way to specify this
- * relationship and reduce the amount of explicit configuration during entity
+ * The Requires annotation can be used to specify dependencies within a package of components. If one
+ * component requires the use of another, such as a scene or light component needing a transform, this can be
+ * a convenient way to specify this relationship and reduce the amount of explicit configuration during entity
  * initialization.
  * <p/>
- * If a component type extends an additional abstract component type that also is
- * annotated with Requires, the union of the required types is the effective set of
- * types.
+ * If a component type extends an additional abstract component type that also is annotated with Requires, the
+ * union of the required types is the effective set of types.
  * <p/>
- * When a component type that has been annotated with this annotation is added to an
- * entity, all required component types that are not already attached to the entity are
- * added. All newly added components have their owner set to the initial component so that
- * when it's removed, the required components are cleaned up as well.
+ * When a component type that has been annotated with this annotation is added to an entity, all required
+ * component types that are not already attached to the entity are added. All newly added components have
+ * their owner set to the initial component so that when it's removed, the required components are cleaned up
+ * as well.
  *
  * @author Michael Ludwig
  */

File src/main/java/com/lhkbob/entreri/impl/AbstractComponent.java

 import java.lang.reflect.Method;
 
 /**
- * AbstractComponent is the base class used for all generated proxy implementations of
- * component subtypes. It provides an implementation for all of the declared methods in
- * Component as well as equals() and hashCode(). It should not be subclassed or extended
- * directly, but is used as the parent class of generated proxies. As specified in {@link
- * com.lhkbob.entreri.Component}, all component type definitions are sub-interfaces of
+ * AbstractComponent is the base class used for all generated proxy implementations of component subtypes. It
+ * provides an implementation for all of the declared methods in Component as well as equals() and hashCode().
+ * It should not be subclassed or extended directly, but is used as the parent class of generated proxies. As
+ * specified in {@link com.lhkbob.entreri.Component}, all component type definitions are sub-interfaces of
  * Component.
  *
  * @param <T> The type of component the AbstractComponent is safely cast-able to
     protected final ComponentRepository<T> owner;
 
     /**
-     * The current index of the component. Subclasses must not modify directly, but should
-     * call setIndex(). This is provided to avoid the virtual getIndex() call.
+     * The current index of the component. Subclasses must not modify directly, but should call setIndex().
+     * This is provided to avoid the virtual getIndex() call.
      */
     protected int index;
     private int id;
     }
 
     @Override
+    public T getCanonical() {
+        return owner.getComponent(index);
+    }
+
+    @Override
     public int hashCode() {
         if (isAlive()) {
             return (getType().hashCode() + 17 * (getEntity().getId() + 31));

File src/main/java/com/lhkbob/entreri/impl/CachingDelegatingFactoryProvider.java

 import java.util.Map;
 
 /**
- * CachingDelegatingFactoryProvider implements the ComponentFactoryProvider interface to
- * delegate to a list of factory providers and caches their created factories in a thread
- * safe manner so that actual implementations can be implemented simpler.
+ * CachingDelegatingFactoryProvider implements the ComponentFactoryProvider interface to delegate to a list of
+ * factory providers and caches their created factories in a thread safe manner so that actual implementations
+ * can be implemented simpler.
  *
  * @author Michael Ludwig
  */
         }
 
         throw new UnsupportedOperationException(
-                "Unable to find or generate a component implementation for " +
-                componentType);
+                "Unable to find or generate a component implementation for " + componentType);
     }
 }

File src/main/java/com/lhkbob/entreri/impl/CompiledFactoryProvider.java

 import java.lang.reflect.Type;
 
 /**
- * CompiledFactoryProvider searches the classpath for existing class definitions of the
- * component types. This is suitable for generating component implementations as part of a
- * project build in conjunction with the {@link ComponentImplementationProcessor}.
+ * CompiledFactoryProvider searches the classpath for existing class definitions of the component types. This
+ * is suitable for generating component implementations as part of a project build in conjunction with the
+ * {@link ComponentImplementationProcessor}.
  *
  * @author Michael Ludwig
  */
         @SuppressWarnings("unchecked")
         public CompiledFactory(Class<T> type) throws ClassNotFoundException {
             specification = ComponentSpecification.Factory.fromClass(type);
-            String implName = ComponentFactoryProvider
-                    .getImplementationClassName(specification, true);
+            String implName = ComponentFactoryProvider.getImplementationClassName(specification, true);
 
             Class<?> loaded = Class.forName(implName);
             // although the compiled classes should have been produced from the same
             // of the component type
             if (!loaded.getSuperclass().equals(AbstractComponent.class)) {
                 throw new IllegalStateException(
-                        "Discovered impl. class does not extend AbstractComponent for " +
-                        type);
+                        "Discovered impl. class does not extend AbstractComponent for " + type);
             }
-            Type paramType = ((ParameterizedType) loaded.getGenericSuperclass())
-                    .getActualTypeArguments()[0];
+            Type paramType = ((ParameterizedType) loaded.getGenericSuperclass()).getActualTypeArguments()[0];
             if (!paramType.equals(type)) {
                 throw new IllegalStateException(
                         "Discovered impl. uses wrong type parameter for AbstractComponent, was " +
             }
             if (!type.isAssignableFrom(loaded)) {
                 throw new IllegalStateException(
-                        "Discovered impl. does not implement the expected interface: " +
-                        type);
+                        "Discovered impl. does not implement the expected interface: " + type);
             }
 
             // at this point it's a safe cast
                 ctor = implType.getConstructor(ComponentRepository.class);
             } catch (NoSuchMethodException e) {
                 throw new IllegalStateException(
-                        "Discovered impl. does not have mandated constructor for component: " +
-                        type);
+                        "Discovered impl. does not have mandated constructor for component: " + type);
             }
         }
 
             try {
                 return ctor.newInstance(forRepository);
             } catch (InstantiationException | IllegalAccessException | InvocationTargetException e) {
-                throw new RuntimeException(
-                        "Exception instantiating compiled component impl", e);
+                throw new RuntimeException("Exception instantiating compiled component impl", e);
             }
         }
 

File src/main/java/com/lhkbob/entreri/impl/ComponentFactoryProvider.java

 import java.util.*;
 
 /**
- * ComponentFactoryProvider provides Factory instances that can create instances of
- * components on demand.  The provider encapsulates the strategy used to create or
- * generate the component implementations. The two current approaches are to generate the
- * source at build time and look them up using reflection, and to use Janino to
- * dynamically generate and compile classes, although a Janino factory is not provided
- * currently because the annotation processor works sufficiently well.
+ * ComponentFactoryProvider provides Factory instances that can create instances of components on demand.  The
+ * provider encapsulates the strategy used to create or generate the component implementations. The two
+ * current approaches are to generate the source at build time and look them up using reflection, and to use
+ * Janino to dynamically generate and compile classes, although a Janino factory is not provided currently
+ * because the annotation processor works sufficiently well.
  *
  * @author Michael Ludwig
  */
 public abstract class ComponentFactoryProvider {
     /**
-     * Factory is a factory specification for creating proxy implementations of a
-     * particular component interface. Additionally, to be compatible with the underlying
-     * details of Entreri, all implementations must be AbstractComponents in addition to
-     * implementing whatever required component type.
+     * Factory is a factory specification for creating proxy implementations of a particular component
+     * interface. Additionally, to be compatible with the underlying details of Entreri, all implementations
+     * must be AbstractComponents in addition to implementing whatever required component type.
      *
-     * @param <T> The component interface all created interfaces implement from this
-     *            factory
+     * @param <T> The component interface all created interfaces implement from this factory
      */
     public static interface Factory<T extends Component> {
         /**
-         * Create a new instance that will be managed by the given ComponentRepository.
-         * Depending on how it's used by the repository, it may or may not be flyweight.
-         * The created component must be an AbstractComponent, and be cast-able to an
-         * instance of T.
+         * Create a new instance that will be managed by the given ComponentRepository. Depending on how it's
+         * used by the repository, it may or may not be flyweight. The created component must be an
+         * AbstractComponent, and be cast-able to an instance of T.
          *
          * @param forRepository The repository using the instance
          *
         public AbstractComponent<T> newInstance(ComponentRepository<T> forRepository);
 
         /**
-         * Get the property specification used by this factory. The list will be immutable
-         * and not change during runtime.  The ordering must be consistent and ordered by
-         * PropertySpecification's natural ordering.
+         * Get the property specification used by this factory. The list will be immutable and not change
+         * during runtime.  The ordering must be consistent and ordered by PropertySpecification's natural
+         * ordering.
          *
          * @return The property specification used by the factory
          */
     }
 
     /**
-     * Create or lookup the factory capable of creating the given component type. In many
-     * cases the factory will have a comparatively expensive creation time and should be
-     * cached and reused to mitigate this cost. Actual instance creation will likely be as
-     * cheap as a reflection-based constructor invocation.
+     * Create or lookup the factory capable of creating the given component type. In many cases the factory
+     * will have a comparatively expensive creation time and should be cached and reused to mitigate this
+     * cost. Actual instance creation will likely be as cheap as a reflection-based constructor invocation.
      * <p/>
-     * This method is thread-safe and will guarantee there is at most a single factory
-     * instance for each type. However, the {@link CachingDelegatingFactoryProvider}
-     * implements this logic so that actual factory providers can have a simpler
-     * implementation (where it is acceptable to allocate a new factory when their
-     * getFactory() method is called).
+     * This method is thread-safe and will guarantee there is at most a single factory instance for each type.
+     * However, the {@link CachingDelegatingFactoryProvider} implements this logic so that actual factory
+     * providers can have a simpler implementation (where it is acceptable to allocate a new factory when
+     * their getFactory() method is called).
      *
      * @param componentType The component type of the returned factory
      * @param <T>           The component type
     public abstract <T extends Component> Factory<T> getFactory(Class<T> componentType);
 
     /**
-     * Get the singleton thread-safe factory provider that can be used to create factories
-     * for each component type.  This is intended for internal use only.
+     * Get the singleton thread-safe factory provider that can be used to create factories for each component
+     * type.  This is intended for internal use only.
      *
      * @return The singleton provider
      */
     private static final ComponentFactoryProvider INSTANCE = new CachingDelegatingFactoryProvider();
 
     /**
-     * Get the unique implementation name that should be used when generating source files
-     * or looking for an existing proxy class that implements the given component type. If
-     * <var>includePackage</var> is true, the returned string will include the package
-     * name to create a valid, absolute type name.
+     * Get the unique implementation name that should be used when generating source files or looking for an
+     * existing proxy class that implements the given component type. If <var>includePackage</var> is true,
+     * the returned string will include the package name to create a valid, absolute type name.
      *
      * @param spec           The component specification
      * @param includePackage True if the package should be included
      *
-     * @return The class name that corresponds to the generated proxy implmentation for
-     *         the given type
+     * @return The class name that corresponds to the generated proxy implmentation for the given type
      */
-    public static String getImplementationClassName(ComponentSpecification spec,
-                                                    boolean includePackage) {
+    public static String getImplementationClassName(ComponentSpecification spec, boolean includePackage) {
         // first get the simple name, concatenating all types in the hierarchy
         // (e.g. if its an inner class the name is Foo.Blah and this converts it to FooBlah)
         String scrubbed = spec.getType().replace("[\\.]", "");
     private static final Charset CHARSET = Charset.forName("UTF-8");
 
     /**
-     * Generate valid Java source code for a proxy implementation of the given component
-     * type. The name and package of the generated class are consistent with the results
-     * of calling {@link #getImplementationClassName(ComponentSpecification, boolean)}. It
-     * is assumed (and not validated) that the property specification is valid and
-     * corresponds to the component type. The new class will also extend from
-     * AbstractComponent and has a single constructor that takes a ComponentRepository.
+     * Generate valid Java source code for a proxy implementation of the given component type. The name and
+     * package of the generated class are consistent with the results of calling {@link
+     * #getImplementationClassName(ComponentSpecification, boolean)}. It is assumed (and not validated) that
+     * the property specification is valid and corresponds to the component type. The new class will also
+     * extend from AbstractComponent and has a single constructor that takes a ComponentRepository.
      * <p/>
-     * The target source version generates two different outputs based on whether or not
-     * it should take advantage of post 1.5 features.
+     * The target source version generates two different outputs based on whether or not it should take
+     * advantage of post 1.5 features.
      *
      * @param spec          The component specification that must be implemented
      * @param targetVersion The Java source version to target
      *
      * @return Source code of a valid implementation for the component type
      */
-    public static String generateJavaCode(ComponentSpecification spec,
-                                          SourceVersion targetVersion) {
+    public static String generateJavaCode(ComponentSpecification spec, SourceVersion targetVersion) {
         boolean use15 = targetVersion.compareTo(SourceVersion.RELEASE_5) >= 0;
         String implName = getImplementationClassName(spec, false);
 
             String nowAsISO = df.format(new Date());
 
             sb.append("import javax.annotation.Generated;\n\n");
-            sb.append("@Generated(value={\"")
-              .append(ComponentFactoryProvider.class.getCanonicalName())
+            sb.append("@Generated(value={\"").append(ComponentFactoryProvider.class.getCanonicalName())
               .append("\"}, date=\"").append(nowAsISO).append("\")\n");
             sb.append("@SuppressWarnings(\"unchecked\")\n");
         }
 
-        sb.append("public class ").append(implName).append(" extends ")
-          .append(ABSTRACT_COMPONENT_NAME);
+        sb.append("public class ").append(implName).append(" extends ").append(ABSTRACT_COMPONENT_NAME);
         if (use15) {
             sb.append('<').append(spec.getType()).append('>');
         }
         // time a property is accessed, and add any shared instance field declarations
         int property = 0;
         for (PropertyDeclaration s : spec.getProperties()) {
-            sb.append("\tprivate final ").append(s.getPropertyImplementation())
-              .append(' ').append(PROPERTY_FIELD_PREFIX).append(property).append(";\n");
+            sb.append("\tprivate final ").append(s.getPropertyImplementation()).append(' ')
+              .append(PROPERTY_FIELD_PREFIX).append(property).append(";\n");
             if (s.isShared()) {
-                sb.append("\tprivate final ").append(s.getType()).append(' ')
-                  .append(SHARED_FIELD_PREFIX).append(property).append(";\n");
+                sb.append("\tprivate final ").append(s.getType()).append(' ').append(SHARED_FIELD_PREFIX)
+                  .append(property).append(";\n");
             }
             property++;
         }
             sb.append('<').append(spec.getType()).append('>');
         }
 
-        sb.append(" ").append(REPO_FIELD_NAME).append(") {\n").append("\t\tsuper(")
-          .append(REPO_FIELD_NAME).append(");\n");
+        sb.append(" ").append(REPO_FIELD_NAME).append(") {\n").append("\t\tsuper(").append(REPO_FIELD_NAME)
+          .append(");\n");
         property = 0;
         for (PropertyDeclaration s : spec.getProperties()) {
-            sb.append("\t\t").append(PROPERTY_FIELD_PREFIX).append(property)
-              .append(" = (").append(s.getPropertyImplementation()).append(") ")
-              .append(REPO_FIELD_NAME).append('.').append(GET_PROPERTY_METHOD).append('(')
-              .append(property).append(");\n");
+            sb.append("\t\t").append(PROPERTY_FIELD_PREFIX).append(property).append(" = (")
+              .append(s.getPropertyImplementation()).append(") ").append(REPO_FIELD_NAME).append('.')
+              .append(GET_PROPERTY_METHOD).append('(').append(property).append(");\n");
             if (s.isShared()) {
-                sb.append("\t\t").append(SHARED_FIELD_PREFIX).append(property)
-                  .append(" = ").append(PROPERTY_FIELD_PREFIX).append(property)
-                  .append('.').append(CREATE_SHARE_METHOD).append("();\n");
+                sb.append("\t\t").append(SHARED_FIELD_PREFIX).append(property).append(" = ")
+                  .append(PROPERTY_FIELD_PREFIX).append(property).append('.').append(CREATE_SHARE_METHOD)
+                  .append("();\n");
             }
             property++;
         }
     }
 
     // magic constants used to produce the component implementation source files
-    private static final String ABSTRACT_COMPONENT_NAME = AbstractComponent.class
-            .getName();
+    private static final String ABSTRACT_COMPONENT_NAME = AbstractComponent.class.getName();
     private static final String COMPONENT_REPO_NAME = ComponentRepository.class.getName();
     private static final String OBJECT_PROP_NAME = ObjectProperty.class.getName();
 
      * @param index       The index of the property in the overall spec
      * @param sb          The buffer to append to
      */
-    private static void appendGetter(PropertyDeclaration forProperty, int index,
-                                     StringBuilder sb) {
+    private static void appendGetter(PropertyDeclaration forProperty, int index, StringBuilder sb) {
         // method signature
         sb.append("\n\tpublic ").append(forProperty.getType()).append(" ")
           .append(forProperty.getGetterMethod()).append("() {\n\t\t");
 
         // implementation body, depending on if we use a shared instance variable or not
         if (forProperty.isShared()) {
-            sb.append(PROPERTY_FIELD_PREFIX).append(index).append(".get(")
-              .append(INDEX_FIELD_NAME).append(", ").append(SHARED_FIELD_PREFIX)
-              .append(index).append(");\n\t\treturn ").append(SHARED_FIELD_PREFIX)
-              .append(index).append(";");
+            sb.append(PROPERTY_FIELD_PREFIX).append(index).append(".get(").append(INDEX_FIELD_NAME)
+              .append(", ").append(SHARED_FIELD_PREFIX).append(index).append(");\n\t\treturn ")
+              .append(SHARED_FIELD_PREFIX).append(index).append(";");
         } else {
             if (forProperty.getPropertyImplementation().equals(OBJECT_PROP_NAME)) {
                 // special case where we allow ObjectProperty to have more permissive getters
                 // and setters to support any type under the sun, but that means we have
                 // to cast the object we get back
-                sb.append("return (").append(forProperty.getType()).append(") ")
-                  .append(PROPERTY_FIELD_PREFIX).append(index).append(".get(")
+                sb.append("return (").append(forProperty.getType()).append(") ").append(PROPERTY_FIELD_PREFIX)
+                  .append(index).append(".get(").append(INDEX_FIELD_NAME).append(");");
+            } else {
+                sb.append("return ").append(PROPERTY_FIELD_PREFIX).append(index).append(".get(")
                   .append(INDEX_FIELD_NAME).append(");");
-            } else {
-                sb.append("return ").append(PROPERTY_FIELD_PREFIX).append(index)
-                  .append(".get(").append(INDEX_FIELD_NAME).append(");");
             }
         }
 
     }
 
     /**
-     * Append the setter method definition given the property declarations that correspond
-     * to the method and its parameters.
+     * Append the setter method definition given the property declarations that correspond to the method and
+     * its parameters.
      *
-     * @param params The properties mutated and that define the parameters of the setter
-     *               method
+     * @param params The properties mutated and that define the parameters of the setter method
      * @param spec   The spec for the component type being generated
      * @param sb     The buffer to append to
      */
-    private static void appendSetter(List<PropertyDeclaration> params,
-                                     ComponentSpecification spec, StringBuilder sb) {
+    private static void appendSetter(List<PropertyDeclaration> params, ComponentSpecification spec,
+                                     StringBuilder sb) {
         // order by parameter index
         Collections.sort(params, new Comparator<PropertyDeclaration>() {
             @Override
             } else {
                 sb.append(", ");
             }
-            sb.append(p.getType()).append(' ').append(SETTER_PARAM_PREFIX)
-              .append(properties.indexOf(p));
+            sb.append(p.getType()).append(' ').append(SETTER_PARAM_PREFIX).append(properties.indexOf(p));
         }
         sb.append(") {\n");
 
         for (PropertyDeclaration p : params) {
             int idx = properties.indexOf(p);
             sb.append("\t\t").append(PROPERTY_FIELD_PREFIX).append(idx).append(".set(")
-              .append(INDEX_FIELD_NAME).append(", ").append(SETTER_PARAM_PREFIX)
-              .append(idx).append(");\n");
+              .append(INDEX_FIELD_NAME).append(", ").append(SETTER_PARAM_PREFIX).append(idx).append(");\n");
         }
 
-        sb.append("\t\t").append(REPO_FIELD_NAME).append('.')
-          .append(UPDATE_VERSION_METHOD).append("(").append(INDEX_FIELD_NAME)
-          .append(");\n");
+        sb.append("\t\t").append(REPO_FIELD_NAME).append('.').append(UPDATE_VERSION_METHOD).append("(")
+          .append(INDEX_FIELD_NAME).append(");\n");
 
         // return this component if we're not a void setter
         if (returnComponent) {

File src/main/java/com/lhkbob/entreri/impl/ComponentImplementationProcessor.java

 import java.util.Set;
 
 /**
- * ComponentImplementationProcessor is an annotation processor to use with Java 6
- * compilers or APT to generate component proxy implementations for all component
- * sub-interfaces encountered in the build class path. These will then be dynamically
- * loaded at runtime instead of using something such as Janino to generate classes from
- * scratch.
+ * ComponentImplementationProcessor is an annotation processor to use with Java 6 compilers or APT to generate
+ * component proxy implementations for all component sub-interfaces encountered in the build class path. These
+ * will then be dynamically loaded at runtime instead of using something such as Janino to generate classes
+ * from scratch.
  *
  * @author Michael Ludwig
  */
 @SupportedSourceVersion(SourceVersion.RELEASE_7)
 public class ComponentImplementationProcessor extends AbstractProcessor {
     @Override
-    public boolean process(Set<? extends TypeElement> annotations,
-                           RoundEnvironment roundEnv) {
+    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
         Types tutil = processingEnv.getTypeUtils();
         Elements eutil = processingEnv.getElementUtils();
         for (Element e : roundEnv.getRootElements()) {
             if (e.getKind().equals(ElementKind.INTERFACE)) {
                 // we have an interface
                 TypeElement t = (TypeElement) e;
-                if (tutil.isAssignable(t.asType(), eutil.getTypeElement(
-                        Component.class.getCanonicalName()).asType())) {
+                if (tutil.isAssignable(t.asType(),
+                                       eutil.getTypeElement(Component.class.getCanonicalName()).asType())) {
 
                     try {
-                        ComponentSpecification spec = ComponentSpecification.Factory
-                                                                            .fromTypeElement(
-                                                                                    t,
-                                                                                    processingEnv);
-                        String name = ComponentFactoryProvider
-                                .getImplementationClassName(spec, true);
+                        ComponentSpecification spec = ComponentSpecification.Factory.fromTypeElement(t,
+                                                                                                     processingEnv);
+                        String name = ComponentFactoryProvider.getImplementationClassName(spec, true);
                         String code = ComponentFactoryProvider
                                 .generateJavaCode(spec, processingEnv.getSourceVersion());
                         try {
-                            Writer w = processingEnv.getFiler().createSourceFile(name, t)
-                                                    .openWriter();
+                            Writer w = processingEnv.getFiler().createSourceFile(name, t).openWriter();
                             w.write(code);
                             w.flush();
                             w.close();
                         } catch (IOException ioe) {
                             processingEnv.getMessager()
-                                         .printMessage(Diagnostic.Kind.ERROR,
-                                                       ioe.getMessage(), t);
+                                         .printMessage(Diagnostic.Kind.ERROR, ioe.getMessage(), t);
                         }
                     } catch (IllegalComponentDefinitionException ec) {
                         String typePrefix = t.asType().toString();
                         if (msg.startsWith(typePrefix)) {
                             msg = msg.substring(typePrefix.length());
                         }
-                        processingEnv.getMessager()
-                                     .printMessage(Diagnostic.Kind.ERROR, msg, t);
+                        processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, msg, t);
                     }
                 }
             }