Java node recommendations - Latest

Property visibility

If you want to create a Java node to implement some complex functionality, and allow this functionality to be configured by setting the node properties, you can create a Java library node. For more information on creating library nodes, see Creating library nodes. It is recommended that you hide the following Java-specific properties so that they are not visible to the end user of the node:

• NodeClass
• Classpaths
• JavaPackage
• JavaClass
• CompileJavaClass
• JavaCode

However, in advanced use cases the end user of the node may be expected to provide their own Java code. In such cases, it may be appropriate to expose the Java-specific properties.

Property base and run time property names

It is recommended that you set the property base to reflect the name of the node, for example on a node named SumExample, the property base is ls.brain.node.sumExample.

Experienced users will be aware that the structure of the node property hierarchy is important because the property resolution rules use the dot-separated property name as a search hierarchy.

If a search is performed for the property ls.brain.node.sumExample.foo, then

• If it exists, it is returned
• If it does not exist, a search is performed for ls.brain.node.foo, then
  • If this property exists, it is returned.
  • If it does not exist, a search is performed for ls.brain.foo, then
    • If this property exists, it is returned.
    • If it does not exist, a search is performed for ls.foo then
      • If this property exists, it is returned.
      • If it does not exist, a search is performed for foo.
        • If this property exists, it is returned, otherwise an error occurs.

Therefore, it is recommended that you ensure that the node hierarchy is mirrored in the run time property name hierarchy. The String returned from the propertyBase method should also be maintained correctly, such that a property with the name "propertyName" on a parent node, with the correct run time property name hierarchy can be obtained using the following line:

properties().getProperty( propertyBase() + ".propertyName");

Package, class and node names

It is recommended that you change the name of your node and the class name to reflect the name or purpose of the node. This will help you to understand error logs.

If you plan to use the node only once within a specific data flow, you can use the default value for the JavaPackage property. However, if you are creating a library node (see Creating library nodes), rename the JavaPackage property to something related to the node.

The name of the class should be changed in the JavaClass property to reflect the node name.

For these property changes to be effective, you must reference them via the textual substitution (see Advanced substitutions) in the JavaCode property and in the NodeClass property. As the JavaPackage and JavaClass properties are to be inserted as the Java package name and Java class name, they must be valid package and class names.

Code documentation and maintenance

Please keep in mind the following recommendations:

• Comment any complex logic in the code for clarity for future users.
• Provide sufficient information to the logs such that errors have sensible and understandable error messages that allow for node errors to be easily resolved.

Working with external files

In general, it is sufficient to use the node inputs and outputs for all required processing. Where permanent storage is required, then standard Java I/O mechanisms can be used to create files on the server.

There is sometimes a need to create temporary files which only exist for the lifetime of the node. Mechanisms are provided within the Java node to allow for temp file management.

Using the temporary directory

When nodes run, they can create temporary files which are stored within a temporary directory specific to the user, run and data flow. Within the node, it is possible to obtain access to a FileManager to take care of temporary file management. To obtain the FileManager, the following code can be used:

com.lavsatorm.brain.node.io.FileManager manager = fileManager();

Once the FileManager has been obtained, the following method can be used to create a temporary file with the specified suffix:

public URI temporaryFile(String suffix, boolean deleteOnDestroy)

throws LoggableException;

When set to true, the deleteOnDestroy argument specifies to the FileManager that the temporary file will only exist so long as the node exists, and then will be deleted. Currently, the deleteOnDestroy argument needs to be true for this method to succeed.

If deleteOnDestroy is set to false, an UnsupportedOperationException error occurs.

If the temporary file cannot be created, this method will throw a LoggableException. The method returns a URI object which can easily be used to obtain the File to write to. The following example shows the standard use case for creating a temporary .txt file within the temporary directory specific to the data flow, user and run.

File f = null;

try {

File f = new File(

fileManager().temporaryFile("txt", true).getPath());

}

catch (LoggableException le) {

logger().error(le);

throw fail();

}

Registering external temporary files

If you want to create temporary files to use outside of the temporary directory specific to the user, data flow and run, you can do this by using the standard Java I/O mechanisms, and by registering the file with the FileManager to be deleted once the node has terminated, as follows:

public void register(URI uri, boolean deleteOnDestroy);

The deleteOnDestroy argument needs to be set to true for this method to work.

An example of how this could be used to create a temporary file called "myFile.txt" in the directory "c:\tmp" is shown below:

File f = new File("c:\\tmp\\myFile.txt");

try {

f.createNewFile();

fileManager().register(new com.lavastorm.net.URI(f));

}

catch (IOException ioe) {

logger().error(ioe, “Error creating temp file”);

throw fail();

}

Writing to external BRD files

It may be useful in certain situations to output data to an external BRD file. In most cases, you can do this by connecting an Output BRD File node to the output pin of the Java node. However, if the numbers and names of the outputs are not known prior to running the node then BRD output files can be created as follows:

If the BRD file is to be temporary, then it can always be created by or registered with the FileManager . Once the file has been created, a RecordOutput can be obtained for the file. This RecordOutput can then be used in the same manner as the RecordOutputs which operate on the node inputs.

The method which needs to be used to obtain the RecordOutput is shown below:

public RecordOutput createRecordOutput(URI uri) throws NodeFailedException

For example:

RecordOutput output = createRecordOutput(fileManager().createTemporaryFile("brd", true));

This creates a temporary ".brd" file within the temporary directory for the node, registers it to be deleted once the node has finished running, then constructs a RecordOutput over the created file.

Note that all of the usual steps when working with RecordOutputs still need to be followed, e.g. setup the output metadata, write the records, close the output.