Michael Ludwig avatar Michael Ludwig committed 5ed43d7

Update documentation within the property package

Comments (0)

Files changed (4)

src/main/java/com/lhkbob/entreri/property/Factory.java

 
 /**
  * <p/>
- * The Factory annotation can be declared on a Property field in a ComponentData
- * definition to specify the type of PropertyFactory to use when creating instances of the
- * Property for the component. The factory type must have a no-argument constructor in
- * order to be instantiated correctly. This annotation should be used if Property does not
- * provide a default factory with sufficient flexibility with annotation attributes (e.g.
- * {@link DefaultInt} for the Properties defined in com.lhkbob.entreri.property).
+ * The Factory annotation can be placed on a Property implementation or the getter method
+ * in a Component definition to specify the type of PropertyFactory to use when creating
+ * instances of the Property for the component. The factory type must have a no-argument
+ * constructor or a constructor that takes a single {@link Attributes} instance in order
+ * to be instantiated correctly. This annotation can be used if Property does not provide
+ * a default factory with sufficient flexibility with annotation attributes (e.g. {@link
+ * DefaultInt} for the Properties defined in com.lhkbob.entreri.property).
  * <p/>
- * <p/>
- * Factory can also be placed at the type level on a Property implementation to declare
- * the default PropertyFactory to use. When using the {@link ReflectionComponentDataFactory},
- * it checks for a constructor taking a single {@link com.lhkbob.entreri.property.Attributes}
- * object, or the default constructor.
+ * Every Property implementation must be annotated with this annotation
  *
  * @author Michael Ludwig
- * @see ReflectionComponentDataFactory
+ * @see PropertyFactory
+ * @see Property
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.METHOD, ElementType.TYPE })

src/main/java/com/lhkbob/entreri/property/Property.java

 
 /**
  * <p/>
- * Property represents a generic field or property of a ComponentData definition. It's
- * interface allows it's values and underlying data store to be packed together with the
+ * Property represents a generic field or property of a Component definition. Its
+ * interface allows its values and underlying data store to be packed together with the
  * corresponding property instances of all the other Components of the same type in an
  * EntitySystem.
  * <p/>
  * instances of type A, with properties a and b. The two 'a' properties would share the
  * same data store, and the two 'b' properties would share a separate store.
  * <p/>
+ * All property implementations must expose two methods: <code>T get(int)</code> and
+ * <code>void set(T, int)</code> to get and set values at a particular index. To support
+ * primitives without boxing, they are not part of the interface definition but are
+ * required.
+ * <p/>
  * Property instances are carefully managed by an EntitySystem. There is ever only one
  * property instance per defined property in a component type for a system. Every
  * component of that type uses their index into the property's IndexedDataStore to access
  * their data. This helps keep memory usage low and simplifies system maintenance.
  * <p/>
- * Property instances are created by {@link PropertyFactory PropertyFactories}, which are
- * created by {@link ComponentDataFactory ComponentDataFactories}. ComponentDataFactory
- * implementations define how property factories are declared.
+ * Property instances are created by {@link PropertyFactory PropertyFactories}. Every
+ * concrete Property class must be annotated with {@link Factory} to specify the
+ * PropertyFactory class that constructs it. That PropertyFactory must expose a
+ * no-argument constructor, or a constructor that takes an {@link Attributes} instance as
+ * its only argument.
  *
  * @author Michael Ludwig
- * @see ReflectionComponentDataFactory
  */
 public interface Property {
     /**
      * hold other property values if the owning ComponentData is in an EntitySystem with
      * many other components of the same type.
      * <p/>
-     * This should not be used by ComponentData implementations, and manipulating the
-     * IndexedDataStore outside of the EntitySystem code could cause unexpected behavior.
-     * Instead Property implementations should expose other ways to access their data; as
-     * an example see {@link FloatProperty#getIndexedData()}.
+     * This should not be used externally, and manipulating the IndexedDataStore outside
+     * of the EntitySystem code could cause unexpected behavior. Instead Property
+     * implementations should expose other ways to access their data; as an example see
+     * {@link FloatProperty#getIndexedData()}.
      * <p/>
      * The returned data store must always have at least 1 element in it.
      *

src/main/java/com/lhkbob/entreri/property/PropertyFactory.java

  * Additionally, it is used when decorating a ComponentData type in an EntitySystem to
  * ensure that each decoration event gets a unique property instance.
  * <p/>
- * <p/>
- * When using the {@link ReflectionComponentDataFactory}, PropertyFactory implementations
- * must have a no-argument constructor or a constructor that takes an {@link Attributes}
- * as its only argument. The constructor does not need to be public.
+ * PropertyFactory implementations must have a no-argument constructor or a constructor
+ * that takes an {@link Attributes} as its only argument. The constructor does not need to
+ * be public.
  *
  * @param <T> The Property type created
  *
     /**
      * Copy the value from <var>src</var> at component index, <var>srcIndex</var> to
      * <var>dst</var> at <var>dstIndex</var>. This is used when a component is created and
-     * cloned from a template with {@link com.lhkbob.entreri.Entity#add(com.lhkbob.entreri.Component)}. For
-     * many cases a plain copy-by-value or copy-by-reference is sufficient, but some
+     * cloned from a template with {@link com.lhkbob.entreri.Entity#add(com.lhkbob.entreri.Component)}.
+     * For many cases a plain copy-by-value or copy-by-reference is sufficient, but some
      * component types might require more complicated cloning rules.
      *
      * @param src      The source property that is being cloned

src/main/java/com/lhkbob/entreri/property/ShareableProperty.java

  */
 package com.lhkbob.entreri.property;
 
-import com.lhkbob.entreri.property.Property;
+/**
+ * ShareableProperty designates a special type of property that can mutate a shared
+ * instance to a specific component's value, instead of returning internal references.
+ * Often, shareable properties are capable of actually unpacking the type into primitive
+ * arrays and restoring the value into the shared instance for improved cache coherence.
+ * <p/>
+ * Because simple primitives cannot be shared, ShareableProperty declares the required
+ * methods using generics.
+ *
+ * @param <T> The type stored by the property
+ *
+ * @author Michael Ludwig
+ */
+public interface ShareableProperty<T> extends Property {
+    /**
+     * Create a new instance of type T for use by components that need a shareable
+     * instance to pass into {@link #get(int, Object)}.
+     *
+     * @return A new instance of type T
+     */
+    public T createShareableInstance();
 
-/**
- *
- */
-public interface ShareableProperty extends Property {
+    /**
+     * Get the property value at <var>index</var>, but instead of returning a new instance
+     * or the value, the <var>result</var> parameter is mutated to equal the property
+     * value. It can be assumed the instance was previously created by a call to {@link
+     * #createShareableInstance()}.
+     *
+     * @param index  The index to access
+     * @param result The instance of T to modify
+     */
+    public void get(int index, T result);
 }
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.