org.eidola.kernel
Class Container

java.lang.Object
  |
  +--org.eidola.kernel.event.EventBroadcaster
        |
        +--org.eidola.kernel.Container

Direct Known Subclasses:

Element, Namespace

public abstract class Container

extends EventBroadcaster

The general structural unit of an Eidola program.

Every container has a structure, which is the set of properties which affect its semantic meaning. Containers notify listeners of changes to their structure by broadcasting StructureChanged events, and keep a modification count of the structure, accessible through getStructureVersion().

Some information about a container, such as its contents or errors, is derived from the fundamental structure, and lives inside a Container.Compilation. Compilations update in a lazy manner designed to make user interfaces as responsive as possible. When some structure change -- in this container or another -- requires a compilation, the container broadcasts a CompileRequired event. A separate thread then takes responsibility for building the new Compilation. For more information on the compile process, see Compiler.

Structure:

• contents

Note on synchronization:

Containers are concurrent-read-safe, meaning that you can safely call any of the get methods without doing any synchronization If a get method returns a data structure, then that structure is immutable and it's safe to keep a reference to it; any subsequent changes to the container will create a new structure.

However, you must always synchronize on a container when calling any of the set methods. This is the caller's responsibility, which helps avoid excessive and redundant synchronization. An attempt to call a set method from an unsynchronized block will thow an exception.

It is safe to use the get methods while a container is being modified, but you must be ready for inconsistent results. If you need to guarantee that a container is not being modified while you work with it, you can either (1) put it in a synchronized block, or (2) check modification counts before and after, as compile() does.

Version:

[Development version]

Author:

Paul Cantrell

Inner Class Summary

class

Container.Compilation Generates and holds potentially computationally expensive derived structures, and checks the lazy rules of the semantics.

Field Summary

static ContainerPart	CONTENTS Part of a container.
static boolean	debugCompile

Fields inherited from class org.eidola.kernel.event.EventBroadcaster

debugEvents

Constructor Summary

Container()
Creates a new empty container.

Method Summary

void	broadcastEvent(Event event) Broadcasts an event concerning changes in this container, incrementing appropriate modification counts.
void	compile() Attachs a new, up-to-date Container.Compilation to this container.
abstract void	dump(int indent) Does a debug dump of this container to System.out.
void	finalize()
Container.Compilation	getCompilation() Returns the last completed compilation.
long	getCompileVersion() Returns a modification count for all changes requiring compilations.
abstract Namespace	getNamespace() Returns the namespace in which this container lives.
long	getStructureVersion() Returns a modification count for this container's structure.
protected void	handleContentEvent(ContainerEvent event) Propagates events from contents and other members.
protected void	handleSelfEvent(ContainerEvent event) Propagates events from this container.
protected abstract Container.Compilation	makeNewCompilation() Creates a new Container.Compilation of an appropriate type for this container.

Methods inherited from class org.eidola.kernel.event.EventBroadcaster

addListener, removeListener, updateBroadcasters

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CONTENTS

public static final ContainerPart CONTENTS

Part of a container.

See Also:

StructureChanged

debugCompile

public static boolean debugCompile

Constructor Detail

Container

public Container()

Creates a new empty container.

Method Detail

finalize

public void finalize()

Overrides:

finalize in class Object

getNamespace

public abstract Namespace getNamespace()

Returns the namespace in which this container lives.

getCompileVersion

public long getCompileVersion()

Returns a modification count for all changes requiring compilations. This is equivalent to the number of CompileRequireds this object has broadcast.

getStructureVersion

public long getStructureVersion()

Returns a modification count for this container's structure. This is equivalent to the number of StructureChangeds this object has broadcast.

broadcastEvent

public void broadcastEvent(Event event)

Broadcasts an event concerning changes in this container, incrementing appropriate modification counts. A StructureChanged increments the structure version, and a CompileRequired increments the compile version.

Overrides:

broadcastEvent in class EventBroadcaster

Parameters:

event - The event to broadcast.

handleSelfEvent

protected void handleSelfEvent(ContainerEvent event)

Propagates events from this container. This handler does nothing by default.

handleContentEvent

protected void handleContentEvent(ContainerEvent event)

Propagates events from contents and other members. This handler broadcasts a CompileRequired event when it receives a a StructureChanged event signaling that a content's owner or name has changed.

compile

public void compile()
             throws CompileAbortedException

Attachs a new, up-to-date Container.Compilation to this container. See Compiler for information about the compile process.

Compilation only happens if the container has changed since it was last compiled, so redundant calls to this method are entirely fine. When compilation is done, this method broadcasts a CompileCompleted event for each CompileRequired event the container has broadcast since the last compilation.

Throws:

CompileAbortedException - If the container's structure is modified during compilation. When this happens, calls to getCompilation() return the old compilation, even if some or all of the compile cycle finished. The proper response to this exception is to call compile() again later -- which is what generally happens, since the same structure change that caused the abort will spawn another compilation!

makeNewCompilation

protected abstract Container.Compilation makeNewCompilation()

Creates a new Container.Compilation of an appropriate type for this container. This method only exists because Java does not use runtime types to resolve inner class names; in other words, there are no virtual inner classes. Under normal circumstances, you will not need to call this method directly; use compile() instead. It is a good idea to synchronize on the container when calling this method.

getCompilation

public Container.Compilation getCompilation()

Returns the last completed compilation. This does not include any more recent compile cycles that are in progress, or were aborted.

dump

public abstract void dump(int indent)

Does a debug dump of this container to System.out.