Overview

Please make sure you know common Glossary and SpEL (especially the Data types section) before proceeding further.

This part of the documentation describes various ways of customizing Nussknacker - from adding own Components to adding listeners for various Designer actions. The main way of adding customizations to Nussknacker is ServiceLoader

Please make sure to put jars with custom code on right classpath

• Customizations of model (in particular ComponentProviders) should be configured in Model config in `modelConfig.classPath.
• Code of Designer customizations should go to the main designer classpath (e.g. put the jars in the lib folder)

Types

Types of expressions are based on Java types. Nussknacker provides own abstraction of type, which can contain more information about given type than pure Java class - e.g. object type (like in Typescript) is represented in runtime as Java Map, but during compilation we know the structure of this map. We also handle union types (again, similar to Typescript) and we have Unknown type which is represented as Java Object in runtime, but behaves a bit like Typescript any (please note that Unknown should be avoided as default Security settings settings prohibit omitting typechecking with Unknown.

TypingResult is the main class (sealed trait) that represents type of expression in Nussknacker. Typed object has many methods for constructing TypingResult

Components and ComponentProviders

Components are main method of customizing Nussknacker. Components are created by configured ComponentProvider instances. There are following types of components:

• SourceFactory
• SinkFactory
• CustomStreamTransformer - types of transformations depend on type of Engine
• Service - mainly for defining stateless enrichments

Other SPIs for Nussknacker customization (documentation will follow soon...)

Model customization

• Flink specific
  • FlinkEspExceptionConsumerProvider
  • FlinkCompatibilityProvider
  • SerializersRegistrar
  • TypingResultAwareTypeInformationCustomisation
  • TypeInformationDetection
• NodeAdditionalInfoProvider
• ToJsonEncoder
• ObjectNamingProvider
• ModelConfigLoader
• ProcessMigrations
• DictServicesFactory

Designer customization

• ProcessChangeListenerFactory

• Security

  • AuthenticationProvider
  • OAuth2ServiceFactory

• CountsReporterCreator

Contents of customization packages.

Customization code should be placed in jar files on correct classpath:

• Customizations of model (in particular ComponentProviders) should be configured in Model config in modelConfig.classPath.
• Code of Designer customizations should go to the main designer classpath (e.g. put the jars in the lib folder)

The jar file should be fatjar containing all libraries necessary for running your customization, except for dependencies provided by execution engine. In particular, for custom component implementation, following dependencies should be marked as provided and not be part of customization jar:

• All Nussknacker modules with names ending in -api, e.g. nussknacker-api, nussknacker-flink-api, nussknacker-lite-api
• nussknacker-util, nussknacker-flink-util
• Basic Flink dependencies: flink-streaming-scala, flink-runtime, flink-statebackend-rocksdb etc. for Flink components
• nussknacker-kafka-util for Streaming-Lite components

Please remember that provided dependency are not transitive, i.e. if you depend on e.g. nussknacker-flink-kafka-util you still have to declare dependency on nussknacker-flink-util explicitly (see Maven documentation for further info).

Your code should ideally depend only on nussknacker-xxx-api packages and not on implementation modules, like nussknacker-interpreter, nussknacker-flink-executor, nussknacker-lite-runtime. They should only be needed in test scope. If you find you need to depend on those modules, please bear in mind that:

• they should be provided and not included in fatjar.
• they contain implementation details and their API should not be considered stable.

The nussknacker-xxx-util modules should be used with caution, they provide utility classes that are often needed when implementing own components, but their API is subject to change.