ENTITYs have a dual nature. From a user's point of view, ENTITYs are the fundamental bricks of the data-manager, they store the data and build larger structures with attributes, etc. From the programmer's point of view, ENTITYs are responsible for persistence and event generation. Putting all of this functionality in a single class would be both a programming headache and a maintenance nightmare. For this reason, ENTITYs are support by a cast of several collaborating classes.
The main collaborating classes are:
Any reference of type Entity that escapes the inner workings of the Kernel is actually a reference of type EntityProxy. The key motivation behind the ENTITYPROXY is that ENTITYs should be protected from malicious and/or thread-unsafe use. The indirection to an ENTITYPROXY gives Hydrogen the (as of yet unused) ability to check permissions for the access to the ENTITY. This also allows Simpletons and other actors to keep entity IDENTIFIERs, with out forcing the (possibly memory intense) back end entity to actually be in memory.
The EntityProxy class is nearly as weightless in design as the Entity class. It contains an Identifier, which uniquely specifies the entity (whatever class is suitable for the current back end) for which it is proxying. It uses this IDENTIFIER to communicate with the EntityManager, which gives a reference to the appropriate back end entity. The proxy then uses this reference to pass on the method request to its intended target. This indirection is used so that the call can be wrapped with code checking permissions, etc.
A diagram showing how what a Simpleton or other actor does to the EntityProxy it receives from Kernel actually gets mapped to an action on a back end entity can be seen in Figure 2.1.
The job of the ENTITYMANAGER is to manage the relationships between in-memory entities and their on-disk counterparts. These relationships can be arbitrarily complex. The job of the EntityManager class is to create and initialize an instance of the class that implements the actual management of these relationships. Currently there is only one such implementation:
The VerySimpleEntityManager is just that, a very simple entity manager. It gains persistence through serialization. This is one of the weaker spots in the kernel implementation currently, as it relies on a block of static code in the EntityManager class to initialize an ObjectInputStream and load the ENTITYs into memory, and the deprecated java.lang.System.runFinalizersOnExit to call a finalizer method that writes them out to disk.
It keeps all the VerySimpleEntitys in memory at all times, relying on the Java Virtual Machine and operating system to provide a reasonable caching scheme. It contains HashTables relating EntityProxy to Identifier (which at the moment is not necessary -- EntityProxys use their Identifiers as hash codes -- but is included for flexibilities sake) and Identifier to VerySimpleEntity. These HashTables facilitate the lookup methods which the PROXYs use to get a reference to the proper back end entity and any given time.
VerySimpleEntitys are also very simple. They reference each other (i.e., as attributes and bases) by Identifier, as that is guaranteed to be the same between sessions. Otherwise they are inert, as the Java serialization does all of the persistence work.
The demands of the EventGenerator interface can add a lot of complexity to a class. To avoid this unnecessary complexity, an EVENTGENERATOR should delegate the responsibility. This is a kernel implementation to that end.
ENTITYVALUEs come in two flavors: Passive (see Chapter 3) and Active (see Chapter 4). These two flavors are fundamentally different, as described in the design document and the API. Each receives a formal treatment in its individual chapter.
The EntityValue interface serves as a marker for all ENTITYVALUEs and extends the java.io.Serializable interface to facilitate easy dumping of their data to disk. For hackers writing new ENTITYVALUEs, this means that it is important to think about using the transient keyword wisely in their designs.