Tivoli Confidential

com.tivoli.tec.event_delivery
Class TECEvent

java.lang.Object
  extended bycom.tivoli.tec.event_delivery.TECEvent

public final class TECEvent
extends Object

TECEvent encapsulates the code for parsing event strings into a class name and name/value pairs. Unfortunately there is not a clearly documented formal specification of the event string syntax.

Below is the syntax this class will accept. First here are the token definitions:

   Tokens
   ------
  SEMICLN := ";"

   EQUALS := "="

  CNTRL_A := "\001"

       ID := Any non-empty sequence of characters from the set
                 a-z,A-Z,0-9,_,-,.
             containing at least one character from
                 a-z,A-Z

   STRING := Begins and ends with either single quotes or double quotes
             Any embedded quotes that are the same as beign used to delimitnate the string
             must be escaped with  the same quote character.
             For example:
               - 'embedded single(')' would be written 'embedded single('')'
               - "embedded double(")" would be written "embedded double("")"
               - "embedded single(')" would be written "embedded single(')"
             Other than that the only other restriction on STRING tokens
             is that they can't contain the NUL character ('\000') or
             control-A ('\001').

    VALUE := Any non-empty sequence of characters excluding all ASCII control
             characters ("" - ""), the space character (" "), the
             single quote ("'"), the equals sign ("="), and the semi-colon
             (";").

 EMPTY_STRING := This token represents either an empty string. No quotes are needed for this value.
 
One oddball token in the above is the CNTRL_A character. This character is used to terminate event data when sent over the wire and life is easier if allow it to appear as a terminating character in event strings here. Another oddball token in the above is VALUE and there is an ambiguity because all ID tokens are also valid VALUE tokens. Given these tokens, a legal event string has the following form:
      ID SEMICLN ( ID = (STRING | VALUE | EMPTY_STRING) SEMICLN )* "END" [CNTRL_A]
 
The first ID token is the class name, the sequence of instances of "ID=(STRING|VALUE);" specify the slot/value pairs, and "END" marks the end of the event. The teminating character ^A is optional. Each ID used as a slot name must be unique with respect to all the other IDs used as slot names and the slot name can't be "END". Before and after any of the tokens in an event string, there can be an arbitrary amount of whitespace (characters " ", "\t", "\r", "\n") with one exception. Nothing can appear after the terminating ^A if it's present. Here are some examples of valid event strings:
    Class1;
       msg='embedded quote ''.' ;
       hostname=artemis;
    END

    Class2;END^A

    Class3;  msg = theMessage ; END

    Class4;
       msg='Here''s a newline
 rest of msg';
    END
 

Since:
TEC 3.8
Version:
1.23 6/5/06
Author:
Andrea Chiavegatto, Joe Kerr

Field Summary
static char MIN_EVENT_LEN
          Minimum length an event string can have and still have the possibility of being syntactically correct.
static char TECAD_EVENT_END_CHAR
          Character used to terminate event data when it's sent over the wire.
 
Constructor Summary
TECEvent()
           
 
Method Summary
 String className()
          Retrieves The class name of the TECEvent object.
static TECEvent[] convert(String events, com.ibm.logging.ILogger edLogger, com.ibm.logging.ILogger edTrace)
           
static String convert(TECEvent[] events)
           
 String getSlot(String slotName)
          Retrieves the value for the slot named slotName.
 boolean init(String event)
          Parse the string event into the class name and slot/value pairs.
static void main(String[] argv)
          Main program for debug testing only.
Usage "TECEvent ".
static String normalizeEvEnd(String event)
          Returns a string defining the same event as event, but you are guaranteed that the string ends w/ a newline followed by the character TECAD_EVENT_END_CHAR.
 boolean setClassName(String name)
          Sets the class name of the TECEvent object.
 void setFilterEvent()
           
 boolean setSlot(String slot, String value)
          Sets the slot name slot to value.
 boolean skippedWhitespace()
          After calling init() you can call this function to find out if the event string parsed by init() contained any extraneous whitespace characters (' ', '\t', '\r', and '\n') that were skipped over during the parse.
 Enumeration slots()
          Returns an Enumeration of the slot names in the event.
 String toString()
          Produces the same result as calling toString(false).
 String toString(boolean compact)
          Produces a string representation of the event in valid TEC event syntax (as defined in the class comments above).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

TECAD_EVENT_END_CHAR

public static final char TECAD_EVENT_END_CHAR
Character used to terminate event data when it's sent over the wire. This character is not allowed in the body of an event definition.

See Also:
Constant Field Values

MIN_EVENT_LEN

public static final char MIN_EVENT_LEN
Minimum length an event string can have and still have the possibility of being syntactically correct. For example, "A;END".

See Also:
Constant Field Values
Constructor Detail

TECEvent

public TECEvent()
Method Detail

init

public boolean init(String event)
Parse the string event into the class name and slot/value pairs. If the parse is successful, these values can be accessed using the methods getClass() and getSlot().

Parameters:
event - the event string to be parsed.
Returns:
true/false on parsing success/failure.

skippedWhitespace

public boolean skippedWhitespace()
After calling init() you can call this function to find out if the event string parsed by init() contained any extraneous whitespace characters (' ', '\t', '\r', and '\n') that were skipped over during the parse.


className

public String className()
Retrieves The class name of the TECEvent object.


setClassName

public boolean setClassName(String name)
Sets the class name of the TECEvent object.

Returns:
True if name is a valid class name and false otherwise. If false is returned then the class name wasn't modified.

getSlot

public String getSlot(String slotName)
Retrieves the value for the slot named slotName.

Returns:
The value for slotName if any, otherwise null.

setSlot

public boolean setSlot(String slot,
                       String value)
Sets the slot name slot to value. If slot already has a value then the old value is lost.

Returns:
True if slot is a valid slot name and value doesn't contain any illegal chars, and false otherwise. If false is returned then the TECEvent object was not modified.

slots

public Enumeration slots()
Returns an Enumeration of the slot names in the event.


toString

public String toString(boolean compact)
Produces a string representation of the event in valid TEC event syntax (as defined in the class comments above).

Parameters:
compact - If true then no extra whitespace is in formatting the String representing the event. If false, then spaces and newlines are used to make the String representation of the event "pretty".

toString

public String toString()
Produces the same result as calling toString(false).


normalizeEvEnd

public static String normalizeEvEnd(String event)
Returns a string defining the same event as event, but you are guaranteed that the string ends w/ a newline followed by the character TECAD_EVENT_END_CHAR. This is helpful because the TEC server rejects events strings that don't have whitespace between "END" and TECAD_EVENT_END_CHAR. In addition it's the form we want to use when writing to the event buffer file in order to be consistent w/ the C version of the EIF. I didn't note the whitespace as a requirement in the event string syntax above because I consider it a bug in the event parser of the TEC server rather than an intuitive and consistent policy on whitespace.


convert

public static TECEvent[] convert(String events,
                                 com.ibm.logging.ILogger edLogger,
                                 com.ibm.logging.ILogger edTrace)

convert

public static String convert(TECEvent[] events)

main

public static void main(String[] argv)
Main program for debug testing only.
Usage "TECEvent ".


setFilterEvent

public void setFilterEvent()

Tivoli Confidential