com.googlecode.entreri.property.Property Maven / Gradle / Ivy
/*
* Entreri, an entity-component framework in Java
*
* Copyright (c) 2011, Michael Ludwig
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification,
* are permitted provided that the following conditions are met:
*
* Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
* ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
package com.googlecode.entreri.property;
/**
*
* Property represents a generic field or property of a Component definition.
* It's interface allows it's 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.
*
*
* This is an approach to mapped-objects where Components can be mapped onto
* primitive arrays so that iteration sees optimal cache locality. As an
* example, there could be two 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.
*
*
* 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. The Property instances are created by using
* the {@link Parameters} annotation on the declared fields in a type, and
* reflection is used to assign them to a Component instance.
*
*
* @author Michael Ludwig
*/
public interface Property {
/**
*
* Return the IndexedDataStore holding this property's values. The data
* store may also hold other property values if the owning Component is in
* an EntitySystem with many other components of the same type.
*
*
* This should not be used by Component 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()}.
*
*
* @return The current IndexedDataStore used by the property
*/
public IndexedDataStore getDataStore();
/**
*
* Assign a new IndexedDataStore to this Property. If the old values for
* this Property were not copied out of its previous IndexedDataStore into
* the new one, this assignment will change the apparent value of this
* property.
*
*
* This should only be called internally by the EntitySystem. Calling it
* within a Component implementation or otherwise will result in undefined
* consequences.
*
*
* It can be assumed that the new store is not null.
*
*
* @param store The new IndexedDataStore
*/
public void setDataStore(IndexedDataStore store);
}