目录
1.NumberFormatterNodeFactory.java
2.NumberFormatterNodeModel.java
3.NumberFormatterNodeDialog.java (optional)
4.NumberFormatterNodeView.java (optional)
5.NumberFormatterNodeFactory.xml
7.plugin.xml and META-INF/MANIFEST.MF
Number Formatter Node Implementation:
There are four Java classes implementing
what the node should do,
how the dialog and the view looks like,
one XML file that contains the node description,
and an image which is used as the node icon (in this case a default icon) displayed in the workflow view of KNIME Analytics Platform.
Generally, a node implementation comprises of the following classes: NodeFactory
, NodeModel
, NodeDialog
, NodeView
.
1.NumberFormatterNodeFactory.java
The NodeFactory
bundles all parts that make up a node. Thus, the factory provides creation methods for the NodeModel
, NodeDialog
, and NodeView
. Furthermore, the factory will be registered via a KNIME extension point such that the node is discoverable by the framework and will be displayed in the node repository view of KNIME Analytics Platform. The registration of this file happens in the plugin.xml
(see description of the plugin.xml
file below).
2.NumberFormatterNodeModel.java
The NodeModel
contains the actual implementation of what the node is supposed to do. Furthermore, it specifies the number of inputs and outputs of a node. In this case the node model implements the actual number formatting.
3.NumberFormatterNodeDialog.java
(optional)
The NodeDialog
provides the dialog window that opens when you configure (double click) a node in KNIME Analytics Platform. It provides the user with a GUI to adjust node specific configuration settings. In the case of the Number Formatter node this is just a simple text box where the user can enter a format String. Another example would be the file path for a file reader node.
4.NumberFormatterNodeView.java
(optional)
The NodeView provides a view of the output of the node. In the case of the Number Formatter node there will be no view as the output is a simple table. Generally, an example for a view could be a tree view of a node creating a decision tree model.
5.NumberFormatterNodeFactory.xml
This XML file contains the node description and some metadata of the node. The root element must be a <knimeNode> … </knimeNode>
tag. The attributes of this tag further specify the location of the node icon (icon=”…”
) and the type of the node (type=”…”
). Note that this is the type you selected in the dialog of the Node Wizard earlier. The most common types are Source
, Manipulator
, Predictor
, Learner
, Sink
, Viewer
, and Loop
. The description of the node is specified in the children of the root tag. Have a look at the contents of the file for some examples. The .xml
must be located in the same package as the NodeFactory
and it has to have the same name (only the file ending differs).
6.default.png
This is the icon of the node displayed in the workflow editor. The path to the node icon is specified in the NumberFormatterNodeFactory.xml
(icon
attribute of the knimeNode
tag). In this case the icon is just a placeholder displaying a question mark. For your own node, replace it with an appropriate image representative of what the node does. It should have a resolution of 16x16 pixels.
Apart from the Java classes and the factory .xml
, which define the node implementation, there are two files that specify the project configuration:
7.plugin.xml
and META-INF/MANIFEST.MF
These files contain important configuration data about the extension project, like dependencies to other plug-ins and the aforementioned extension points. You can double click on the plugin.xml
to open an Eclipse overview and review some of the configuration options (e.g. the values we entered in KNIME Node Wizard are shown on the overview page under General Information
on the left). However, you do not have to change any values at the moment.
Number Formatter Node Implementation:
Once you have reviewed the project structure, we have a look at some implementation details. We will cover the most important parts as the example code in the project you created earlier already contains detailed comments in the code of the implemented methods (also have a look at the reference implementation in the org.knime.examples.numberformatter
folder of the knime-examples
repository).
Generally, the Number Formatter node takes a data table as input and applies a user specified format String to each Double
column of the input table. For simplicity, the output table only contains the formatted numeric columns as String columns. This basically wraps the functionality of the Java String.format(…)
function applied to a list of Double
values into a node usable in KNIME Analytics Platform.
Let’s work through the most important methods that each node has to implement. The functionality of the node is implemented in the NumberFormatterNodeModel.java
class:
protected NumberFormatterNodeModel() {
super(1, 1);
}
The super(1, 1)
call in the constructor of the node model specifies the number of output and input tables the node should have. In this case it is one input and one output table.
BufferedDataTable[] execute(final BufferedDataTable[] inData, final ExecutionContext exec)
The actual algorithm of the node is implemented in the execute
method. The method is invoked only after all preceding nodes have been successfully executed and all data is therefore available at the input ports. The input table will be available in the given array inData
which contains as many data tables as specified in the constructor. Hence, the index of the array corresponds to the port index of the node. The type of the input is BufferedDataTable
, which is the standard type of all tabular data in KNIME Analytics Platform. The persistence of the table (e.g. when the workflow is saved) is automatically handled by the framework. Furthermore, a BufferedDataTable
is able to handle data larger than the size of the main memory as the data will be automatically flushed to disk if necessary. A table contains DataRow
objects, which in turn contain DataCell
objects. DataCell
s provide the actual access to the data. There are a lot of DataCell
implementation for all types of data, e.g. a DoubleCell
containing a floating point number in double precision (for a list of implementations have a look at the type hierarchy of the DataCell
class). Additionally, each DataCell
implements one or multiple DataValue
interfaces. These define which access methods the cell has i.e. which types it can be represented as. For example, a BooleanCell
implements IntValue
as a Boolean
can be easily represented as 0 and 1. Hence, for each DataValue
there could be several compatible DataCell
classes.
The second argument exec
of the method is the ExecutionContext
which provides means to create/modify BufferedDataTable
objects and report the execution status to the user. The most straightforward way to create a new DataTable
is via the createDataContainer(final DataTableSpec spec)
method of the ExecutionContext
. This will create an empty container where you can add rows to. The added rows must comply with the DataTableSpec
the data container was created with. E.g. if the container was created with a table specification containing two Double
columns, each row that is added to the container must contain two DoubleCells
. After you are finished adding rows to the container close it via the close()
method and retrieve the BufferedDataTable
with getTable()
. This way of creating tables is also used in the example code (see NumberFormatterNodeModel.java
). Apart from creating a new data container, there are more powerful ways to modify already existing input tables. However, these are not in the scope of this quickstart guide, but you can have a look at the methods of the ExecutionContext
.
The execute
method should return an array of output BufferedDataTable
objects with the length of the number of tables as specified in the constructor. These tables contain the output of the node.
DataTableSpec[] configure(final DataTableSpec[] inSpecs)
The configure
method has two responsibilities. First, it has to check if the incoming data table specification is suitable for the node to execute with respect to the user supplied settings. For example, a user may disallow a certain column type in the node dialog, then we need to check if there are still applicable columns in the input table according to this setting. Second, to calculate the table specification of the output of the node based on the inputs. For example: imagine the Number Formatter node gets a table containing two Double
columns and one String
column as input. Then this method should return a DataTableSpec
(do not forget to wrap it in an array) containing two DataColumnSpec
of type String
(the Double
columns will be formatted to String
, all other columns are ignored). Analogously to the execute
method, the configure
method is called with an array of input DataTableSpec
objects and outputs an array of output DataTableSpec
objects containing the calculated table specification. If the incoming table specification is not suitable for the node to execute or does not fit the user provided configuration, throw an InvalidSettingsException
with an informative message for the user.
saveSettingsTo(final NodeSettingsWO settings)
and
loadValidatedSettingsFrom(final NodeSettingsRO settings)
These methods handle the loading and saving of settings that control the behaviour of the node, i.e. the settings entered by the user in the node dialog. This is used for communication between the node model and the node dialog and to persist the user settings when the workflow is saved. Both methods are called with a NodeSettings
object (in a read only (RO) and write only (WO) version) that stores the settings and manages writing or reading them to or from a file. The NodeSettings
object is a key-value storage, hence it is easy to write or read to or from the settings object. Just have a look at the provided methods of the NodeSettings
object in your Eclipse editor. In our example, we do not write settings directly to the NodeSettings
object as we are using a SettingsModel
object to store the user defined format String. SettingsModel
objects already know how to write and read settings from the NodeSettings
(via methods that accept NodeSettings
) and help to keep settings synchronization between the model and dialog simple. Furthermore, they can be used to create simple dialogs where the loading and saving of settings is already taken care of.
You can find the actual algorithm of the Number Formatter node in the execute
method in the NumberFormatterNodeModel.java
class. We encourage you to read through the code of the above mentioned classes to get a deeper understanding of all parts of a node. For a more thorough explanation about how a node should behave consult the KNIME Noding Guidelines.