public interface FunctionContext
| Modifier and Type | Method and Description |
|---|---|
void |
addClassLibraries(java.lang.String[] libraries)
Add class libraries to the functional class loader.
|
void |
createCustomMetric(java.lang.String name,
java.lang.String description,
java.lang.String kind,
java.util.function.LongSupplier value)
Create a custom metric.
|
int |
getChannel()
Get the index of the parallel channel the function is on.
|
FunctionContainer |
getContainer()
Get the container hosting a function
|
java.util.Set<java.lang.String> |
getCustomMetricNames()
Get the set of custom metric names created in this context.
|
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.
|
FunctionContainer getContainer()
java.util.concurrent.ScheduledExecutorService getScheduledExecutorService()
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 truekeepAliveTime set to 5 secondscorePoolSize 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.
java.util.concurrent.ThreadFactory getThreadFactory()
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.
int getChannel()
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.
int getMaxChannels()
void addClassLibraries(java.lang.String[] libraries)
throws java.net.MalformedURLException
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.
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.java.net.MalformedURLExceptionvoid createCustomMetric(java.lang.String name,
java.lang.String description,
java.lang.String kind,
java.util.function.LongSupplier value)
long value and has a kind of:
counter - A counter metric observes a value that
represents a count of an occurrence.gauge - A gauge metric observes a value that is continuously variable with time.
time - A time metric represents a point in time. It is recommended that the
value represents the number of milliseconds since the 1970/01/01 epoch, i.e. a
value consistent with System.currentTimeMillis().
value.getAsLong() during this
method call. Subsequently, periodically value.getAsLong() will be called
to get the current value of the metric so that it can be reported through the monitoring APIs.
A lambda expression can be used as the supplier, for example to monitor the length
of a queue (or any collection) items a metric can be created from
Initializable.initialize(FunctionContext) as:
this.items = new PriorityQueue();
functionContext.createCustomMetric("queuedItems", "Number of queued items.",
"gauge", () -> this.items.size());
The metric will now automatically track the length of the queue (subject to the
periodic collection cycle).
A java.util.concurrent.atomic.AtomicLong can be used as a metric's value,
for example a counter where no other natural value exists, e.g.:
this.nFailedRequests = new AtomicLong();
functionContext.createCustomMetric("nFailedRequests", "Number of failed requests.",
"counter", this.nFailedRequests::get);
Subsequently the counter is incremented using:
this.nFailedRequests.incrementAndGet();
name - Name of the metric.description - Description of the metric.kind - Kind of the metric.value - function that returns the value of the metricjava.lang.IllegalStateException - A metric with name already exists or kind is
not valid.java.util.Set<java.lang.String> getCustomMetricNames()