danbikel.parser
Class SexpEvent

java.lang.Object
  danbikel.parser.AbstractEvent
      danbikel.parser.SexpEvent

All Implemented Interfaces:

SexpConvertible, Event, MutableEvent, Externalizable, Serializable

Direct Known Subclasses:

SexpSubcatEvent

public class SexpEvent
extends AbstractEvent
implements MutableEvent, SexpConvertible, Externalizable

Represents an event composed of one or more Sexp objects. For efficiency reasons, this class treats as equal a backing Sexp that is a symbol and a backing Sexp that is a list whose sole element is the same symbol. As per the guidelines of MutableEvent, this class implements the ensureCapacity methods, so that a single SexpEvent object may be re-used for efficiency.

See Also:

Serialized Form

Field Summary

protected Sexp	event The event stored by this instance.
static Symbol	sexpLabel Initial symbol used in the string representation of SexpEvent objects.

Constructor Summary

SexpEvent()
Constructs a SexpEvent that contains no data.

SexpEvent(int initialCapacity)
Constructs a SexpEvent that contains no data, but whose ensureCapacity(int) method has been called with the specified value.

SexpEvent(Sexp event)
Creates a new SexpEvent using the specified S-expression.

Method Summary

MutableEvent	add(int type, Object obj) Identical to add(obj).
MutableEvent	add(Object obj) Adds the specified object, which must be a Sexp instance, to this event.
int	canonicalize(Map canonical) Since events are typically read-only, this method will allow for canonicalization (or "unique-ifying") of the information contained in this event.
void	clear() Clears the data stored in this complex event object.
Event	copy() Returns a deep copy of this event, which really just means creating a new instance with a deep copy of the backing Sexp, using the Sexp.deepCopy method.
protected Sexp	copySexpEvent() Returns a deep copy of the underlying Sexp of this event.
void	ensureCapacity(int size) If size is greater than 1, this method ensures that the underlying Sexp is a SexpList (creating a new SexpList if necessary) and pre-allocates space in that SexpList.
void	ensureCapacity(int type, int size) Since there is only one type supported by this class, this method simply calls ensureCapacity(size).
boolean	equals(Object o) Returns true if o is an instance of Event and if the backing Sexp of o is equal to the backing Sexp of this object; also, this method treats backing Sexp of the two objects equal when one is a symbol and the other is a list of length 1 containing that symbol.
Object	get(int type, int index) Returns the indexth component of this event.
Class	getClass(int type) Returns Sexp.class if the specified type is 0.
int	hashCode() Returns the hash code of the backing Sexp object.
int	numComponents() Returns the number of components of this event: 1 if the backing Sexp is a symbol, or the length of the list otherwise.
int	numComponents(int type) An alias for numComponents(), as this Event implementation supports only one type.
int	numTypes() Returns 1, as this Event implementation supports only one type.
void	readExternal(ObjectInput in) Reconstructs the SexpEvent object that was serialized using writeExternal(ObjectOutput).
void	setSexp(Sexp event) Sets the backing Sexp of this object to be the specified Sexp.
Sexp	toSexp() Returns the Sexp contained in this event.
String	toString() Returns a string representation of this object of the form (sexpLabel event) where event is string representation of the Sexp held by this object.
int	typeIndex(Class cl) Returns 0 if the specified class is Sexp.class, -1 otherwise.
void	writeExternal(ObjectOutput out) Writes a representation of this object to the specified object output stream.

Methods inherited from class danbikel.parser.AbstractEvent

genericEquals

Methods inherited from class java.lang.Object

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

Field Detail

sexpLabel

public static final Symbol sexpLabel

Initial symbol used in the string representation of SexpEvent objects.

See Also:

toString()

event

protected Sexp event

The event stored by this instance.

Constructor Detail

SexpEvent

public SexpEvent()

Constructs a SexpEvent that contains no data.

SexpEvent

public SexpEvent(int initialCapacity)

Constructs a SexpEvent that contains no data, but whose ensureCapacity(int) method has been called with the specified value.

SexpEvent

public SexpEvent(Sexp event)

Creates a new SexpEvent using the specified S-expression.

Parameters:

event - the Sexp representing an arbitrary event.

Method Detail

getClass

public Class getClass(int type)

Returns Sexp.class if the specified type is 0.

Specified by:

getClass in interface Event

Returns:

the type (Class) associated with the specified type index

Throws:

IndexOutOfBoundsException - if the specified type is not 0

typeIndex

public int typeIndex(Class cl)

Returns 0 if the specified class is Sexp.class, -1 otherwise.

Specified by:

typeIndex in interface Event

numTypes

public int numTypes()

Returns 1, as this Event implementation supports only one type.

Specified by:

numTypes in interface Event

numComponents

public int numComponents()

Returns the number of components of this event: 1 if the backing Sexp is a symbol, or the length of the list otherwise.

Specified by:

numComponents in interface Event

numComponents

public int numComponents(int type)

An alias for numComponents(), as this Event implementation supports only one type.

Specified by:

numComponents in interface Event

get

public Object get(int type,
                  int index)

Returns the index^th component of this event. If the backing Sexp is a symbol, then index must be 0; otherwise, it must be not be outside the acceptable index range of the backing SexpList.

Specified by:

get in interface Event

Parameters:

type - the type index of the component to be retrieved (which must be zero, since SexpEvent objects only have one possible type)

index - the index of the component to be retrieved

Throws:

IndexOutOfBoundsException - if type != 0 or if index < 0 or if index >= numComponents(type)

copy

public Event copy()

Returns a deep copy of this event, which really just means creating a new instance with a deep copy of the backing Sexp, using the Sexp.deepCopy method. As a special exception, if the underlying Sexp of this event is a list with only one element that is a symbol, the copy will contain a Sexp that is that symbol (the "canonical" version of lists containing a single symbol, as far as this class is concerned). This transforms a time-efficient lookup object using a pre-allocated underlying list into a space-efficient object suitable for persistent storage.

Specified by:

copy in interface Event

See Also:

copySexpEvent(), equals(Object), ensureCapacity(int)

copySexpEvent

protected final Sexp copySexpEvent()

Returns a deep copy of the underlying Sexp of this event. If the underlying Sexp is a single-element list containing a symbol, the symbol is returned instead of a copy of the list.

hashCode

public int hashCode()

Returns the hash code of the backing Sexp object. As a special case, if the backing Sexp is a list with a single symbol, the hash code returned is that of the single symbol. This behavior is consistent with this class' semantics of treating a symbol and a list containing that symbol as equivalent.

Specified by:

hashCode in interface Event

Overrides:

hashCode in class Object

Returns:

the hash code for this event

equals

public boolean equals(Object o)

Returns true if o is an instance of Event and if the backing Sexp of o is equal to the backing Sexp of this object; also, this method treats backing Sexp of the two objects equal when one is a symbol and the other is a list of length 1 containing that symbol.

As per the general contract of Event.equals(Object), the specified object need not be of type SexpEvent, but merely support the same types as this Event, namely Sexp objects, and store the same number of equal Sexp objects in the same order.

Specified by:

equals in interface Event

Overrides:

equals in class Object

toString

public String toString()

Returns a string representation of this object of the form (sexpLabel event) where event is string representation of the Sexp held by this object.

Overrides:

toString in class Object

setSexp

public void setSexp(Sexp event)

Sets the backing Sexp of this object to be the specified Sexp.

toSexp

public Sexp toSexp()

Returns the Sexp contained in this event.

Specified by:

toSexp in interface SexpConvertible

Returns:

the S-expression that represents an instance of an implementor of this class

add

public MutableEvent add(Object obj)

Adds the specified object, which must be a Sexp instance, to this event.

Specified by:

add in interface MutableEvent

Parameters:

obj - a Sexp instance to add to this event

Returns:

this SexpEvent object

add

public MutableEvent add(int type,
                        Object obj)

Identical to add(obj).

Specified by:

add in interface MutableEvent

Parameters:

type - an ignored parameter

obj - an event to add to this complex event object

Returns:

this SexpEvent object

See Also:

add(Object)

canonicalize

public int canonicalize(Map canonical)

Since events are typically read-only, this method will allow for canonicalization (or "unique-ifying") of the information contained in this event. Use of this method is intended to conserve memory by removing duplicate copies of event information in different event objects.

Specified by:

canonicalize in interface Event

Parameters:

canonical - a reflexive map of objecs representing event information: for each unique key-value pair, the value is a reference to the key

Returns:

1 if the backing Sexp was a list and was therefore canonicalized, 0 if it was a list but was not canonicalized (and had to be added to canonical) or -1 if this event was a Symbol and was therefore not even eligible for canonicalization

ensureCapacity

public void ensureCapacity(int size)

If size is greater than 1, this method ensures that the underlying Sexp is a SexpList (creating a new SexpList if necessary) and pre-allocates space in that SexpList. For efficiency when creating lookup SexpEvent objects, once the underlying Sexp is a SexpList, it will remain as such, even if cleared and only one symbol is added. However, when the copy method is invoked, if the underlying Sexp of this SexpEvent object is a list with a single symbol sym, the returned SexpEvent object will have a "canonicalized" underlying Sexp that is sym (that is, the list of a single symbol will be turned into the symbol itself). This scheme allows a lookup object using a pre-allocated list for time efficiency to be transformed into a space-efficient object suitable for persistent storage.

Specified by:

ensureCapacity in interface MutableEvent

Parameters:

size - the amount of space to pre-allocate for the underlying list of Sexp components

See Also:

copy()

ensureCapacity

public void ensureCapacity(int type,
                           int size)

Since there is only one type supported by this class, this method simply calls ensureCapacity(size).

Specified by:

ensureCapacity in interface MutableEvent

Parameters:

type - the type of underlying abstract list for which to pre-allocate space

size - the size to pre-allocate for the specified type of abstract list

clear

public void clear()

Clears the data stored in this complex event object.

Specified by:

clear in interface MutableEvent

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Writes a representation of this object to the specified object output stream.

Specified by:

writeExternal in interface Externalizable

Parameters:

out - the stream to which to write a representation of this object

Throws:

IOException - if there is a problem writing to the specified output stream

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Reconstructs the SexpEvent object that was serialized using writeExternal(ObjectOutput).

Specified by:

readExternal in interface Externalizable

Parameters:

in - the input stream from which to reconstruct a SexpEvent object

Throws:

IOException - if there is a problem reading from the specified input stream

ClassNotFoundException - if the concrete type of the serialized object read from the specified input stream cannot be found