streamcruncher.api
Class StreamCruncher

java.lang.Object
  streamcruncher.api.StreamCruncher

public final class StreamCruncher
extends java.lang.Object

The main class provided by the Kernel to - register/unregister Event Streams, Queries, hooks etc. It also provides methods to start and stop the Kernel.

Author:

Ashwin Jayaprakash, Copyright 2005-2007. All Rights Reserved.

Constructor Summary

StreamCruncher()
Any number of these instances can be created.

Method Summary

void	clearStartupShutdownHook() Removes the Listener from the Kernel.
java.sql.Connection	createConnection()
InputSession	createInputSession(java.lang.String name) Creates a helper object for the Input Event Stream.
OutputSession	createOutputSession(java.lang.String queryName) Creates a helper object for the Output Event Stream.
java.lang.String	getDBSchema()
QueryConfig	getQueryConfig(java.lang.String queryName) Each Query has a unique config-object and this method returns a handle to the same.
ResultSetCacheConfig	getResultSetCacheConfig(java.lang.String cachedSql)
java.util.Collection<java.lang.String>	getResultSetCacheConfigKeys()
StartupShutdownHook	getStartupShutdownHook()
long	getTimeBiasMsecs()
void	keepRunning() Once the Kernel has started, this method can be invoked, where the invoking Thread blocks and waits for the stop-instruction to be typed at the System Console.
ParsedQuery	parseQuery(ParserParameters parserParameters) The "Running Query" that will execute on the Event Stream has to be parsed by the Kernel first.
void	registerAggregator(AbstractAggregatorHelper helper) Registers an Aggregator function.
void	registerInStream(java.lang.String name, RowSpec rowSpec) Register an Input Event Stream as described by the RowSpec and default Block size of 1024.
void	registerInStream(java.lang.String name, RowSpec rowSpec, int blockSize) Register an Input Event Stream as described by the RowSpec.
void	registerProvider(java.lang.String providerName, java.lang.Class<? extends Provider> providerClass) Registers a Provider.
void	registerQuery(ParsedQuery parsedQuery) Registers the Query that was parsed using parseQuery(ParserParameters).
void	setStartupShutdownHook(StartupShutdownHook hook) Sets the lifecycle Listener.
void	setTimeBiasMsecs(long timeBiasMsecs) Forces the Kernel to add the number provided to the time it obtains from the System clock.
void	start(java.lang.String configFilePath) Starts the Kernel.
void	stop() This is an alternative way of stopping the Kernel (also see keepRunning())
void	unregisterAggregator(java.lang.String functionName) An Aggregator must be unregistered only after all the Queries that use it have been unregistered.
void	unregisterInStream(java.lang.String name) Unregisters the Input Event Stream.
void	unregisterProvider(java.lang.String providerName) A Provider must be unregistered only after all the Queries that use it have been unregistered.
void	unregisterQuery(java.lang.String name) Stops and unregisters the Query that is running on the Kernel.

Methods inherited from class java.lang.Object

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

Constructor Detail

StreamCruncher

public StreamCruncher()

Any number of these instances can be created. However, the instances are not Thread-safe.

Method Detail

setStartupShutdownHook

public void setStartupShutdownHook(StartupShutdownHook hook)

Sets the lifecycle Listener. Must be invoked before invoking the start(String) method if the intention is to listen to Startup events and/or before invoking the stop() or before the Kernel is issued a stop command via keepRunning() if the intention is to listen to Shutdown events.

Parameters:

hook -

clearStartupShutdownHook

public void clearStartupShutdownHook()

Removes the Listener from the Kernel.

getStartupShutdownHook

public StartupShutdownHook getStartupShutdownHook()

Returns:

The Listener currently attached to the Kernel.

start

public void start(java.lang.String configFilePath)
           throws StreamCruncherException

Starts the Kernel. Successful return from this method invocation indicates that the Kernel has started and is ready to register, unregister artifacts etc. If the Kernel is being restarted, then any Queries that were registered in a previous run, will start executing.

The Kernel must be started first using this method, before invoking any method on any of the API Classes.

Parameters:

configFilePath - The path, including the name of the Kernel configuration file.

Throws:

StreamCruncherException

keepRunning

public void keepRunning()
                 throws StreamCruncherException

Once the Kernel has started, this method can be invoked, where the invoking Thread blocks and waits for the stop-instruction to be typed at the System Console. On receiving the correct instruction, the Kernel will be stopped and the Thread will return from the method.

Throws:

StreamCruncherException

stop

public void stop()
          throws StreamCruncherException

This is an alternative way of stopping the Kernel (also see keepRunning())

Throws:

StreamCruncherException

registerInStream

public void registerInStream(java.lang.String name,
                             RowSpec rowSpec,
                             int blockSize)
                      throws StreamCruncherException

Register an Input Event Stream as described by the RowSpec.

Parameters:

name -

rowSpec -

blockSize - This number is used by the Kernel to allocate blocks in memory to accomodate the incoming Events. Input Streams with very high rates of arrivals must use larger numbers (multiples of 1024).

Throws:

StreamCruncherException

registerInStream

public void registerInStream(java.lang.String name,
                             RowSpec rowSpec)
                      throws StreamCruncherException

Register an Input Event Stream as described by the RowSpec and default Block size of 1024.

Parameters:

name -

rowSpec -

Throws:

StreamCruncherException

See Also:

registerInStream(String, RowSpec, int)

unregisterInStream

public void unregisterInStream(java.lang.String name)
                        throws StreamCruncherException

Unregisters the Input Event Stream. This operation will succeed only if all the Queries that were using this Stream have been unregistered.

Parameters:

name -

Throws:

StreamCruncherException

parseQuery

public ParsedQuery parseQuery(ParserParameters parserParameters)
                       throws StreamCruncherException

The "Running Query" that will execute on the Event Stream has to be parsed by the Kernel first.

Parameters:

parserParameters -

Returns:

The handle to the parsed "Running Query" as the output of successful parsing.

Throws:

StreamCruncherException

registerQuery

public void registerQuery(ParsedQuery parsedQuery)
                   throws StreamCruncherException

Registers the Query that was parsed using parseQuery(ParserParameters). The Query execution will start after this registration (based on the configurations provided using the QueryConfig).

Parameters:

parsedQuery -

Throws:

StreamCruncherException

getQueryConfig

public QueryConfig getQueryConfig(java.lang.String queryName)

Each Query has a unique config-object and this method returns a handle to the same. It can also be accessed using the ParsedQuery.getQueryConfig() method. This object must be retrieved (if needed) afresh after every Kernel restart.

Parameters:

queryName -

Returns:

null if there is no Query that has been registered with this name.

unregisterQuery

public void unregisterQuery(java.lang.String name)

Stops and unregisters the Query that is running on the Kernel.

Parameters:

name - As provided in ParserParameters.getQueryName().

createConnection

public java.sql.Connection createConnection()
                                     throws java.sql.SQLException

Returns:

A pooled Connection. Must be closed explicitly when not required anymore.

Throws:

java.sql.SQLException

getDBSchema

public java.lang.String getDBSchema()

Returns:

The Database Schema which the Kernel has been configured to use.

getResultSetCacheConfigKeys

public java.util.Collection<java.lang.String> getResultSetCacheConfigKeys()

Returns:

All the SQL Sub-Queries that have been cached by the Kernel.

getResultSetCacheConfig

public ResultSetCacheConfig getResultSetCacheConfig(java.lang.String cachedSql)

Parameters:

cachedSql -

Returns:

The config-object for the Cached SQL Query provided as the parameter. If the Query that uses the SQL that is provided as the parameter, has not been registered with the Kernel yet, then the return value might be null. Since there could be multiple Queries that use the same SQL as a Sub-Query, the Kernel maintains only one cache that will be shared by all the referrers.

createInputSession

public InputSession createInputSession(java.lang.String name)
                                throws StreamCruncherException

Creates a helper object for the Input Event Stream.

Parameters:

name -

Returns:

Throws:

StreamCruncherException

createOutputSession

public OutputSession createOutputSession(java.lang.String queryName)
                                  throws StreamCruncherException

Creates a helper object for the Output Event Stream.

Parameters:

queryName -

Returns:

Throws:

StreamCruncherException

registerAggregator

public void registerAggregator(AbstractAggregatorHelper helper)
                        throws StreamCruncherException

Registers an Aggregator function. If a Query uses a custom Aggregator, then that Aggregator must be registered before the Query is registered.

Parameters:

helper -

Throws:

StreamCruncherException

unregisterAggregator

public void unregisterAggregator(java.lang.String functionName)

An Aggregator must be unregistered only after all the Queries that use it have been unregistered. This method will unregister the Aggregator without checking if Queries are still using it.

Parameters:

functionName - As provided in AbstractAggregatorHelper.getFunctionName()

registerProvider

public void registerProvider(java.lang.String providerName,
                             java.lang.Class<? extends Provider> providerClass)
                      throws StreamCruncherException

Registers a Provider. If a Query uses a custom Provider, then that Provider must be registered before the Query is registered.

Parameters:

providerName -

providerClass -

Throws:

StreamCruncherException

unregisterProvider

public void unregisterProvider(java.lang.String providerName)

A Provider must be unregistered only after all the Queries that use it have been unregistered. This method will unregister the Provider without checking if Queries are still using it.

Parameters:

providerName - As provided in registerProvider(String, Class)

setTimeBiasMsecs

public void setTimeBiasMsecs(long timeBiasMsecs)

Forces the Kernel to add the number provided to the time it obtains from the System clock. It affects Query execution times, Event expiry times, Event generation timestamps etc. This operation is Thread-safe.

Parameters:

timeBiasMsecs - Bias in milliseconds (+ve or -ve).

getTimeBiasMsecs

public long getTimeBiasMsecs()

Returns:

The current bias (default is 0) being used by the Kernel.