Parsing Engine

danbikel.parser
Class SexpEvent

java.lang.Object
  extended bydanbikel.parser.AbstractEvent
      extended bydanbikel.parser.SexpEvent
All Implemented Interfaces:
Event, Externalizable, MutableEvent, Serializable, SexpConvertible
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 indexth 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

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

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.


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

Parsing Engine

Author: Dan Bikel.