com.ibm.streamsx.topology.function

Interface FunctionContext

public interface FunctionContext

Context for a function executing in a IBM Streams application.

Method Summary

Modifier and Type	Method and Description
void	addClassLibraries(java.lang.String[] libraries) Add class libraries to the functional class loader.
int	getChannel() Get the index of the parallel channel the function is on.
FunctionContainer	getContainer() Get the container hosting a function
int	getMaxChannels() Get the total number of parallel channels for the parallel region that the function is in.
java.util.concurrent.ScheduledExecutorService	getScheduledExecutorService() Return a scheduler to execute background tasks.
java.util.concurrent.ThreadFactory	getThreadFactory() Return a ThreadFactory that can be used by the function with the thread context class loader set correctly.

Method Detail

getContainer

FunctionContainer getContainer()

Get the container hosting a function

Returns:

Container hosting a function.

getScheduledExecutorService

java.util.concurrent.ScheduledExecutorService getScheduledExecutorService()

Return a scheduler to execute background tasks. Functions should utilize this service or getThreadFactory() rather than creating their own threads to ensure that the SPL runtime will wait for any background work before completing an application.

The scheduler will be shutdown when the processing element is to be shutdown. Once the scheduler is shutdown no new tasks will be accepted. Existing scheduled tasks will remain in the scheduler's queue but periodic tasks will canceled.
Functions that implement AutoCloseable that wish to complete any outstanding tasks at close time can call ExecutorService.awaitTermination() to wait for outstanding tasks to complete or wait on the specific Future reference for a task.

The returned scheduler service is guaranteed to be an instance of java.util.concurrent.ScheduledThreadPoolExecutor and initially has this configuration:

• corePoolSize Set to Runtime.availableProcessors() with a minimum of 2 and maximum of 8.
• allowsCoreThreadTimeOut() set to true
• keepAliveTime set to 5 seconds

Threads are created on demand to execute tasks, so that even if the corePoolSize is eight, eight threads will only be created if there are eight concurrent tasks scheduled. Threads will be removed if they are not needed for the keepAliveTime value and allowsCoreThreadTimeOut() returns true.

Returns:

Scheduler service that can be used by the function.

See Also:

"java.util.concurrent.ExecutorService", "java.util.concurrent.Future", "java.util.concurrent.ScheduledThreadPoolExecutor"

getThreadFactory

java.util.concurrent.ThreadFactory getThreadFactory()

Return a ThreadFactory that can be used by the function with the thread context class loader set correctly. Functions should utilize the returned factory to create Threads.

Threads returned by the ThreadFactory have not been started and are set as daemon threads. Functions may set the threads as non-daemon before starting them. The SPL runtime will wait for non-daemon threads before terminating a processing element in standalone mode.

Any uncaught exception thrown by the Runnable passed to the ThreadFactory.newThread(Runnable) will cause the processing element containing the function to terminate.

The ThreadFactory will be shutdown when the processing element is to be shutdown. Once the ThreadFactory is shutdown a call to newThread() will return null.

Returns:

A ThreadFactory that can be used by the function.

getChannel

int getChannel()

Get the index of the parallel channel the function is on.

If the function is in a parallel region, this method returns a value from 0 to N-1, where N is the number of channels in the parallel region; otherwise it returns -1.

Returns:

the index of the parallel channel if the function is executing in a parallel region, or -1 if the function is not executing in a parallel region.

getMaxChannels

int getMaxChannels()

Get the total number of parallel channels for the parallel region that the function is in. If the function is not in a parallel region, this method returns 0.

Returns:

the number of parallel channels for the parallel region that this function is in, or 0 if the function is not in a parallel region.

addClassLibraries

void addClassLibraries(java.lang.String[] libraries)
                throws java.net.MalformedURLException

Add class libraries to the functional class loader. The functional class loader is set as the thread context class loader for thread factory, executor and any method invocation on the function instance.

Functions use this method to add class libraries specific to the invocation in a consistent manner. An example is defining the jar files that contain the JDBC driver to be used by the application.

Each element of libraries is trimmed and then converted into a java.net.URL. If the element cannot be converted to a URL then it is assumed to represent a file system path and is converted into an URL representing that path. If the file path is relative the used location is currently undefined, thus use of relative paths are not recommended.
If a file path ends with /* then it is assumed to be a directory and all jar files in the directory with the extension .jar or .JAR are added to the function class loader.

Parameters:

libraries - String representations of URLs and file paths to be added into the functional class loader. If null then no libraries are added to the class loader.

Throws:

java.net.MalformedURLException