one.world.core
Class Component

java.lang.Object
  |
  +--one.world.core.Component

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

Application, AudioPlayer, AudioReceiver, AudioSender, AudioSink, AudioSource, BenchmarkDatagramIO, BenchmarkDatagramIOLatency, BenchmarkDatagramIOReceiver, BenchmarkDatagramIOSender, BenchmarkNetworkIO, BenchmarkNetworkIOLatency, BenchmarkNetworkIOReceiver, BenchmarkNetworkIOSender, BenchmarkREPEcho, BenchmarkREPLatency, BenchmarkREPReceiver, BenchmarkREPSender, BenchmarkTupleStore, Counter, DatagramIO, DiscoveryClient, DiscoveryServer, Environment, Fink, HttpServer, LeaseManager, Logger, Minimum, Mover, NetworkIO, NetworkStats, PendingInputRequests, PendingInputRequests.Wrapper, RemoteManager, RemoteReceiver, RemoteSender, RequestManager, Responder, TestEnvironment.Comp, TestWrapper.Comp, Timer, TupleStore

public abstract class Component

extends Object

implements Serializable

The superclass of all components. Components implement services and export as well as import event handlers. Components are always instantiated within a specified environment and can be linked against components in the same environment as well as other environments.

Note that events passed between components cannot reference components.

Version:

$Revision: 1.31 $

See Also:

Serialized Form

Inner Class Summary

static class	Component.HandlerReference The record for an exported handler that is linked to an imported event handler.
class	Component.Importer The manager for imported event handlers.

Constructor Summary

Component(Environment env)
Create a new component.

Method Summary

protected EventHandler	declareExported(ExportedDescriptor descriptor, EventHandler handler) Declare the specified exported event handler.
protected Component.Importer	declareImported(ImportedDescriptor descriptor) Declare the specified imported event handler.
boolean	equals(Object o) Determine whether this component equals the specified object.
List	eventHandlers() Get a list of the names of the event handlers for this component.
abstract ComponentDescriptor	getDescriptor() Get the component descriptor for this component.
EventHandlerDescriptor	getDescriptor(String name) Get the event handler descriptor for the event handler with the specified name.
Environment	getEnvironment() Get the environment for this component.
List	getLinkedHandlers(String name) Get a list of event handlers currently linked to the imported event handler with the specified name.
int	getLinkedNumber(String name) Get the number of event handlers currently linked to the imported event handler with the specified name.
protected Timer	getTimer() Get the timer for this component's environment.
boolean	hasEventHandler(String name) Determine whether this component has an event handler with the specified name.
int	hashCode() Get a hash code for this component.
boolean	isFullyLinked() Determine whether this component is fully linked.
boolean	isLinked(String name) Determine whether the specified imported event handler is linked.
boolean	isSealed() Determine whether this component is sealed.
void	link(String imported, String exported, Component component) Link the specified event handler imported by this component with the specified event handler exported by the specified component.
void	link(String imported, String exported, Component component, boolean forced) Link the specified event handler imported by this component with the specified event handler exported by the specified component.
protected void	run(Runnable r) Execute the specified runnable in a new thread.
void	seal() Seal this component.
protected Object	unbox(Box box) Unbox the specified box.
protected void	undeclare(String name) Undeclare the event handler with the specified name.
void	unlink(String imported, String exported, Component component) Unlink the specified event handler exported by the specified component from the event handler imported by this component.
protected EventHandler	wrap(EventHandler handler) Wrap the specified event handler.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Component

public Component(Environment env)

Create a new component.

Parameters:

env - The environment for this component.

Throws:

NullPointerException - Signals that env is null.

IllegalArgumentException - Signals that the specified environment is multi-threaded, even though components of this class are not thread safe, or that the protection domain for this component is not the environment's protection domain.

IllegalStateException - Signals that the specified environment is being or has been destroyed, or that the system has shut down.

Method Detail

equals

public final boolean equals(Object o)

Determine whether this component equals the specified object. A component equals another object if and only if that object is the same object as the component. This restriction is necessary for internal book-keeping and reasonable because components implement services and not data structures.

Overrides:

equals in class Object

hashCode

public final int hashCode()

Get a hash code for this component.

Overrides:

hashCode in class Object

getDescriptor

public abstract ComponentDescriptor getDescriptor()

Get the component descriptor for this component.

Returns:

The component descriptor for this component.

getEnvironment

public final Environment getEnvironment()

Get the environment for this component.

Returns:

The environment for this component.

declareImported

protected final Component.Importer declareImported(ImportedDescriptor descriptor)

Declare the specified imported event handler.

Actual components, that is, concrete implementations of this class, use this method to declare an imported event handler. The specified descriptor must be a valid event handler descriptor and should be statically allocated within the actual component, yet not be visible outside that class.

While the returned event handler implements the queued event handler interface, not all of the linked event handlers need to be queued event handlers. If not all of the linked event handlers are queued event handlers, invoking the handleFirst() or handleForced() methods results in an illegal state exception.

The returned event handler throws a NotLinkedException on invocation of its event handling methods if this event handler has not been linked against an exported event handler.

Furthermore, the returned event handler may also throw the following runtime exceptions on invocation of its event handling methods:

• A NoBufferSpaceException if the event is being sent to an environment whose event queue is full.
• A NotActiveException if the event is being sent to an environment that is not currently active.
• An IllegalStateException if the event is being sent to an environment that has no loaded code (for example, because it has been unloaded).

For each of these exceptional conditions, one.world always attempts to deliver the exceptional condition as an exceptional event to the source of the event. However, if the exceptional event cannot be delivered, for example, because the originating environment's event queue is also full, the exceptional condition is signaled directly through a regular Java exception.

Parameters:

descriptor - The descriptor for the imported event handler.

Returns:

The event handler for invoking the imported event handler.

Throws:

NullPointerException - Signals that descriptor is null.

IllegalArgumentException - Signals that descriptor is invalid or that this component already has an event handler with the specified name.

IllegalStateException - Signals that this method has been invoked on a sealed component.

See Also:

undeclare(java.lang.String)

declareExported

protected final EventHandler declareExported(ExportedDescriptor descriptor,
                                             EventHandler handler)

Declare the specified exported event handler.

Actual components, that is, concrete implementations of this class, use this method to declare an exported event handler. The specified descriptor must be a valid event handler descriptor and should be statically allocated within the actual component, yet not be visible outside that class.

Parameters:

descriptor - The descriptor for the exported event handler.

handler - The actual exported event handler.

Returns:

handler.

Throws:

NullPointerException - Signals that descriptor or handler is null.

IllegalArgumentException - Signals that descriptor is invalid or that this component already has an event handler with the specified name.

IllegalStateException - Signals that this method has been invoked on a sealed component.

See Also:

undeclare(java.lang.String)

undeclare

protected final void undeclare(String name)

Undeclare the event handler with the specified name. This method removes a previously declared imported or exported event handler from this component.

Parameters:

name - The name of the event handler to undeclare.

Throws:

NullPointerException - Signals that name is null.

IllegalArgumentException - Signals that this component has no imported or exported event handler with the specified name.

IllegalStateException - Signals that this method has been invoked on a sealed component.

See Also:

declareImported(one.world.core.ImportedDescriptor), declareExported(one.world.core.ExportedDescriptor, one.world.core.EventHandler)

eventHandlers

public final List eventHandlers()

Get a list of the names of the event handlers for this component. This method returns a list of the names of the event handlers imported and exported by this component.

Returns:

A list of the names of the event handlers for this component.

hasEventHandler

public final boolean hasEventHandler(String name)

Determine whether this component has an event handler with the specified name.

Returns:

true if this component has an event handler with the specified name.

getDescriptor

public final EventHandlerDescriptor getDescriptor(String name)

Get the event handler descriptor for the event handler with the specified name.

Parameters:

name - The name of the event handler.

Returns:

The corresponding event handler descriptor.

Throws:

NullPointerException - Signals that name is null.

IllegalArgumentException - Signals that this component does not have an event handler with the specified name.

link

public final void link(String imported,
                       String exported,
                       Component component)

Link the specified event handler imported by this component with the specified event handler exported by the specified component. Linking an imported event handler with an exported event handler it is already linked with to has no effect.

Parameters:

imported - The name of the event handler imported by this component.

exported - The name of the event handler exported by component.

component - The component exporting event handler exported.

Throws:

LinkingException - Signals that an event handler does not exist, that an environment is not being linked against a component within the same environment, that an event handler is not imported/exported when an exported/imported event handler is required, that imported has already been linked and cannot be linked again, or that this component is sealed.

link

public final void link(String imported,
                       String exported,
                       Component component,
                       boolean forced)

Link the specified event handler imported by this component with the specified event handler exported by the specified component. Linking an imported event handler with an exported event handler it is already linked with has no effect.

If the component exporting the exported event handler is in a different concurrency domain than this component, all invocations to the exported event handler must go through the animator for the exported event handler's concurrency domain. If forced is true, invocations to the exported event handler always go through an animator, even if both the imported and exported event handlers are in the same concurrency domain.

Note that if either the imported event handler or the exported event handler specify that they need to be forcibly linked, invocations to the exported event handler will always go through an animator, even if this method is invoked with false for forced.

Parameters:

imported - The name of the event handler imported by this component.

exported - The name of the event handler exported by component.

component - The component exporting event handler exported.

forced - Flag to indicate whether the exported event handler should forcibly be accessed through the corresponding animator.

Throws:

LinkingException - Signals that an event handler does not exist, that an environment is not being linked against a component within the same environment, that an event handler is not imported/exported when an exported/imported event handler is required, that imported has already been linked and cannot be linked again, or that this component is sealed.

See Also:

EventHandlerDescriptor.linkForced

unlink

public final void unlink(String imported,
                         String exported,
                         Component component)

Unlink the specified event handler exported by the specified component from the event handler imported by this component. Unlinking an imported event handler from an exported event handler it is not linked with has no effect.

Parameters:

imported - The name of the event handler imported by this component.

exported - The name of the event handler exported by component.

component - The component exporting event handler exported.

Throws:

LinkingException - Signals that an event handler does not exist, that an event handler is not imported/exported when an exported/imported event handler is required, that imported has not been linked against exported, or that this component is sealed.

isSealed

public final boolean isSealed()

Determine whether this component is sealed.

Returns:

true if this component is sealed.

See Also:

seal()

seal

public final void seal()

Seal this component. A sealed component cannot be linked or unlinked again. Sealing an already sealed component has no effect.

Throws:

LinkingException - Signals that this component is not fully linked.

isLinked

public final boolean isLinked(String name)

Determine whether the specified imported event handler is linked.

Parameters:

name - The name of the imported event handler.

Returns:

true if the imported event handler is linked.

Throws:

IllegalArgumentException - Signals that this component does not have an event handler with the specified name or that the specified event handler is exported.

isFullyLinked

public final boolean isFullyLinked()

Determine whether this component is fully linked. This component is fully linked if every imported event handler is linked against at least one exported event handler.

Returns:

true if this component is fully linked.

getLinkedNumber

public final int getLinkedNumber(String name)

Get the number of event handlers currently linked to the imported event handler with the specified name.

Parameters:

name - The name of the imported event handler.

Returns:

The number of event handlers currently linked to the imported event handler.

Throws:

NullPointerException - Signals that name is null.

IllegalArgumentException - Signals that this component does not have an event handler with the specified name or that the the event handler with the specified name is exported.

getLinkedHandlers

public final List getLinkedHandlers(String name)

Get a list of event handlers currently linked to the imported event handler with the specified name. The returned list is a list of references to exported event handlers.

Parameters:

name - The name of the imported event handler.

Returns:

A list of handler references.

Throws:

NullPointerException - Signals that name is null.

IllegalArgumentException - Signals that this component does not have an event handler with the specified name or that the the event handler with the specified name is exported.

See Also:

Component.HandlerReference

wrap

protected final EventHandler wrap(EventHandler handler)

Wrap the specified event handler. If the specified event handler has not yet been wrapped, this method returns a wrapped version of the specified event handler that uses this component's concurrency domain. If the specified event handler has already been wrapped, it is simply returned.

Parameters:

handler - The event handler to be wrapped.

Returns:

The wrapped event handler.

getTimer

protected final Timer getTimer()

Get the timer for this component's environment. Each environment has its own timer component, which is allocated on demand. Note that the implementation of this method is not just returning the value of a field. Components that use the timer repeatedly should probably call this method once in their constructor and then store the returned reference in a private field.

Returns:

The timer for this component's environment.

run

protected final void run(Runnable r)

Execute the specified runnable in a new thread. Some applications (such as a HTTP server supporting persistent connections) have a legitimate need to spawn their own threads. While this practice is generally discouraged, this method lets applications spawn a new thread if they have the proper permission.

Parameters:

r - The runnable.

Throws:

NullPointerException - Signals that r is null.

SecurityException - Signals that the caller does not have permission to spawn new threads.

unbox

protected final Object unbox(Box box)
                      throws IOException,
                             ClassNotFoundException

Unbox the specified box. This method returns the object embedded in the specified box. Calling this method on the same box twice results in distinct objects.

Parameters:

box - The box to unbox.

Returns:

The embedded object.

Throws:

IOException - Signals an exceptional condition while deserializing the embedded object.

ClassNotFoundException - Signals that a class necessary for instantiating the embedded object could not be found.