Creating a New DPU in UnifiedViews

This section contains a short guide on how to create a DPU using the IntelliJ IDE.

After the project has been generated, you may still need to change these settings:

For further explanation of the generated files, please refer to: Explaining the Core DPU Files Generated by the DPU Template

You can also build the DPU (as it is) and try to import it to UnifiedViews' UI, see: Creating a New DPU Using IntelliJ

This section contains a short guide on how to use the Netbeans IDE for DPU development.

In order to set up the Netbeans IDE, follow these steps:

For further explanation of the generated files, please see: Explaining the Core DPU Files Generated by the DPU Template

You can also build the DPU (as it is) and try to import it to UnifiedViews UI, see: Creating a New DPU Using the Netbeans IDE

This section contains a short guide on files that are being created by the DPU archetype.

The previous section explained how the skeleton for a new DPU may be prepared.

This section describes the files generated by the DPU template. Let’s start with a short list to deliver the general idea, afterward more important files will be explained in detail.

Source code file, class: MyDpu.java, further referred to simply as 'MyDpu' class.

The generated MyDpu class looks as follows (imports are skipped):

@DPU.AsTransformer
public class MyDpu extends AbstractDpu<MyDpuConfig_V1> {
    private static final Logger LOG = LoggerFactory.getLogger(MyDpu.class);
                
    @ExtensionInitializer.Init
    public FaultTolerance faultTolerance;
        public MyDpu() {
                super(MyDpuVaadinDialog.class, ConfigHistory.noHistory(MyDpuConfig_V1.class));
        }
                
    @Override
    protected void innerExecute() throws DPUException {
        ContextUtils.sendShortInfo(ctx, "MyDpu.message");        
    }
}

AbstractDpu class, this DPU class inherits from, provides two important variables.

They can be used inside of the main execution method innerExecute():

The innerExecute method can throw a DPUException.

This exception should be used in case the DPU developer would like to express failure of the DPU due to error in the DPU execution or due to cancellation of the DPU's execution. Some helpers and other classes also throw this exception. In general this exception is considered to be a non-recovery failure, which means, the DPU should fail.

ContextUtils also provides other methods for message sending and a method for creation of DPUException.

Every string passed (besides args) to ContextUtils goes through the localization process. The second parameter of sendShortInfo() method in Line 11 actually points to the file with resources. Translations of the message, so the method sendShortInfo()automatically supports localization. For this reason, developers are encouraged to use ContextUtils for message sending and creation of DPUException.

This can be done by using the following code fragment:

if (ctx.canceled()) {
    log.info("DPU execution was cancelled.");
    break;
}

Source code file, class: MyDpuVaadinDialog.java, further referred to simply as 'MyDpuVaadinDialog' class.

The generated MyDpuVaadinDialog class looks as follows, imports are skipped:

public class MyDpuVaadinDialog extends AbstractDialog<MyDpuConfig_V1> {

    public MyDpuVaadinDialog() {
        super(MyDpu.class);
    }
    
        @Override
    public void setConfiguration(MyDpuConfig_V1 c) throws DPUConfigException {
    }
    
        @Override
    public MyDpuConfig_V1 getConfiguration() throws DPUConfigException {
        final MyDpuConfig_V1 c = new MyDpuConfig_V1();
        return c;
    }
    
        @Override
    public void buildDialogLayout() {
        final VerticalLayout mainLayout = new VerticalLayout();
        mainLayout.setWidth("100%");
        mainLayout.setHeight("-1px");
        mainLayout.setMargin(true);
        
                mainLayout.addComponent(new Label(ctx.tr("MyDpu.dialog.label")));
        
                setCompositionRoot(mainLayout);
    }
}

For more information about Vaadin component’s and layouts, please refer to the Vaadin homepage, where you can find the excellent Book of Vaadin.

Source code file, class: eu.mycompany.uv.dpu.transformer.mydpu.MyDpuConfig_V1.java, further referred to simply as 'MyDpuConfig_V' class.

The generated MyDpuConfig_V1 class looks as follows (imports are skipped):

public class MyDpuConfig_V1 {
    public MyDpuConfig_V1() {
    }
}

The DPU template generates the following three files:

The generated file looks as follows; the file follows Markdown syntax:

MyDpu
----------

### Documentation

* see [Plugin Documentation](./doc/About.md)

### Technical notes

* May be used instead of DPU X, it also replaces DPY Y.

### Version history

* see [Changelog](./CHANGELOG.md)

The generated file looks as follows; the file follows Markdown syntax:

MyDpu
----------

v1.0.0-SNAPSHOT
---
* Initial version of the DPU

Basically for each new version you have to add the following fragment to the start:

v1.1
---
* Description of the bugfix/feature 1
* Description of the bugfix/feature 2

The content of the About.md file contains the user documentation. As the DPU is built, it is converted to About.html file, which is then displayed in the UnifiedViews frontend in the DPU detail as user documentation.

The file generated by the template looks as follows; the file follows the Markdown syntax:

### Description

Description of the DPU intended for the user of the DPU. 

### Configuration parameters

| Name | Description |
|:----|:----|
|**Param** | Param which ...|

### Inputs and outputs

|Name |Type | DataUnit | Description | Mandatory |
|:--------|:------:|:------:|:-------------|:---------------------:|
|input |i |FilesDataUnit |Input files |x|
|output |o |RdfDataUnit |Produced RDF data |x|

A sample file converted to HTML looks as follows:

If you want to support also user documentation in a language other than English, you can create more such user documentation files and store them as doc/About_{languageTag}.md, where {languageTag} is for example 'sk' for Slovak localization.

UnifiedViews automatically ensures that the proper user documentation is loaded based on the localization of the whole application.

The file generated by the template looks as follows, it contains key=value pairs:

# Contains localization of used string in dialog and events. To avoid property collision all values
# must be prefixed by '{dpu name}.' for DPU execution and '{dpu name}.dialog' for configuration dialog!
# Additional prefix in form of dpu name is optional.

# DPU execution.
MyDpu.message = DPU is running ...

# DPU's dialog.
MyDpu.dialog.label = DPU's configuration

This section contains a short guide on how to develop JavaScript dialogues based on the Vaadin Framework.

Basic idea is described in https://vaadin.com/blog/vaadin-7-loves-javascript-components.

Step 1: Define server part of your JavaScript component (see SparqlEditorComponent for more details).

package eu.unifiedviews.plugins.transformer.sparql.construct.editor;
 
@JavaScript({"vaadin://js/sparqleditor/sparqleditor.js", "vaadin://js/sparqleditor/jquery-v1.11.1.min.js", "vaadin://js/sparqleditor/yasqe.bundled.min.js"})
public class SparqlEditorComponent extends AbstractJavaScriptComponent {
 
        ...
        @Override
        protected SparqlEditorState getState() {
        return (SparqlEditorState) super.getState();
        }
 
}

Step 2: Prepare class holding the state object being exchanged between JS part of the component and server part.

In the example below, it just exchanges one string variable.

public class SparqlEditorState extends JavaScriptComponentState {
    public String query = "";
}

There is a way how to define new callbacks for JavaScript in Java (to e.g. report status change back to the server): addFunction on the SparqlEditorComponent

Step 3: Prepare JS part - which has to define the controller, which is bind to the server part component based on its full name (including package).

So in the example above the following would be done:

eu_unifiedviews_plugins_transformer_sparql_construct_editor_SparqlEditorComponent = function() {

    // Create the component
    var mycomponent = new mylibrary.MyComponent(this.getElement());

    // Handle changes from the server-side - whenewher the query is changed, this function is called
    this.onStateChange = function() {
        //access the state object and get the value for query via this.getState().query;
    };

}

sparqlEditorComponent = new SparqlEditorComponent();
sparqlEditorComponent.setStyleName("SparqlEditor");
sparqlEditorComponent.setSizeFull();
sparqlEditorComponent.setImmediate(true);


// Process a value input by the user from the client-side
sparqlEditorComponent.addValueChangeListener(
        new SparqlEditorComponent.CustomValueChangeListener() {
            @Override
            public void valueChange() {
                ...
            }
        });

(Server part - value change listeners)

public interface CustomValueChangeListener extends Serializable {
    void valueChange();
}

List<CustomValueChangeListener> listeners = new ArrayList<CustomValueChangeListener>();

public void addValueChangeListener(CustomValueChangeListener listener) {
    listeners.add(listener);
}

https://vaadin.com/blog/vaadin-7-loves-javascript-components

https://dzone.com/articles/integrating-html-and-0

https://vaadin.com/docs/v8/framework/gwt/gwt-javascript/#gwt.javascript.example

JS to JAVA: https://vaadin.com/forum/thread/4690491

https://vaadin.com/api/com/vaadin/ui/AbstractJavaScriptComponent.html

@Override
public void buildDialogLayout() {

        final VerticalLayout mainLayout = new VerticalLayout();
        mainLayout.setWidth("100%");
        mainLayout.setMargin(true);
        mainLayout.setSpacing(true);

        mainLayout.addComponent(new Label(ctx.tr("MyDpu.dialog.label")));

        tfConfigSample = new TextField(ctx.tr("MyDpu.dialog.tfSample.caption"));
        tfConfigSample.setWidth("100%");
        tfConfigSample.setNullRepresentation("");
        tfConfigSample.setRequired(false);
        tfConfigSample.setImmediate(true);
        mainLayout.addComponent(tfConfigSample); 

    setCompositionRoot(mainLayout);
}

A value is required. When the configuration is saved, it displays a custom error. This does not provide inline validation.

@Override
public void buildDialogLayout() {
    final VerticalLayout mainLayout = new VerticalLayout();
    mainLayout.setWidth("100%");
    mainLayout.setMargin(true);
    mainLayout.setSpacing(true);

    mainLayout.addComponent(new Label(ctx.tr("MyDpu.dialog.label")));

    tfConfigSample = new TextField(ctx.tr("MyDpu.dialog.tfSample.caption"));
    tfConfigSample.setWidth("100%");
    tfConfigSample.setNullRepresentation("");
    tfConfigSample.setRequired(true);
        tfConfigSample.setImmediate(true);
    mainLayout.addComponent(tfConfigSample);

    setCompositionRoot(mainLayout);
}


 @Override
    public MyDpuConfig_V1 getConfiguration() throws DPUConfigException {
        final MyDpuConfig_V1 c = new MyDpuConfig_V1();

                if (!tfConfigSample.isValid()) {
            throw new DPUConfigException(ctx.tr("MyDpu.dialog.label.notValid"));
        }

        c.setConfigSample(tfConfigSample.getValue());
        return c;
    }

When the configuration is saved, it displays a custom error. Also it provides inline validation, as the user is editing the configuration

@Override
public void buildDialogLayout() {
    final VerticalLayout mainLayout = new VerticalLayout();
    mainLayout.setWidth("100%");
    mainLayout.setMargin(true);
    mainLayout.setSpacing(true);

    mainLayout.addComponent(new Label(ctx.tr("MyDpu.dialog.label")));

    tfConfigSample = new TextField(ctx.tr("MyDpu.dialog.tfSample.caption"));
    tfConfigSample.setWidth("100%");
    tfConfigSample.setNullRepresentation("");
    tfConfigSample.setRequired(true);
        tfConfigSample.setImmediate(true);
    tfConfigSample.addValidator(value -> {
        if (tfConfigSample.getValue().isEmpty() || tfConfigSample.getValue().length() < 3) {
            throw new Validator.InvalidValueException(ctx.tr("MyDpu.dialog.label.notValid"));
        }
    });
    mainLayout.addComponent(tfConfigSample);

    setCompositionRoot(mainLayout);
}


 @Override
    public MyDpuConfig_V1 getConfiguration() throws DPUConfigException {
        final MyDpuConfig_V1 c = new MyDpuConfig_V1();

        try {
                tfConfigSample.validate();
                } catch (Validator.InvalidValueException e) {
                throw new DPUConfigException(e.getMessage(), e);
                }

        c.setConfigSample(tfConfigSample.getValue());
        return c;
    }

ComboBox cbMode = new ComboBox(ctx.tr("BatchLinkingDbpedia.dialog.processingmode.caption"));
cbMode.addItem(BatchLinkingDbpediaConfig_V1.Mode.OPTIMISTIC);
cbMode.setItemCaption(BatchLinkingDbpediaConfig_V1.Mode.OPTIMISTIC, ctx.tr("BatchLinkingDbpedia.dialog.processingmode.optimistic"));
cbMode.addItem(BatchLinkingDbpediaConfig_V1.Mode.CONSERVATIVE);
cbMode.setItemCaption(BatchLinkingDbpediaConfig_V1.Mode.CONSERVATIVE, ctx.tr("BatchLinkingDbpedia.dialog.processingmode.conservative"));
cbMode.setInvalidAllowed(false);
cbMode.setNullSelectionAllowed(false);
cbMode.setImmediate(true);
mainLayout.addComponent(cbMode);


# Set value to config object
c.setLinkingMode((BatchLinkingDbpediaConfig_V1.Mode)cbMode.getValue());


# Get value from config object
cbMode.setValue(c.getLinkingMode());

This concerns items, which are not simple strings.

See the code below, important is the 'cbTypeOfLinkProduced.setNewItemsAllowed(true);' option, plus 'newItemHandler' to process new entries (if they are not just simple strings)

ComboBox cbTypeOfLinkProduced  = new ComboBox(ctx.tr("BatchLinkingDbpedia.dialog.linkprooduced.caption"));
cbTypeOfLinkProduced.setInvalidAllowed(false);
cbTypeOfLinkProduced.setNullSelectionAllowed(false);
cbTypeOfLinkProduced.setNewItemsAllowed(true);
cbTypeOfLinkProduced.setTextInputAllowed(true);
cbTypeOfLinkProduced.setImmediate(true);
cbTypeOfLinkProduced.addValidator(value -> {
    if (!isValidIri(value)) {
        throw new Validator.InvalidValueException(ctx.tr("BatchLinkingDbpedia.dialog.linkprooduced.invalid"));
    }
});
// Custom handling for new items
cbTypeOfLinkProduced.setNewItemHandler(new AbstractSelect.NewItemHandler() {
    @Override
    public void addNewItem(String newItemCaption) {
        try {
                        IRI newLink = VF.createIRI(newItemCaption);
                        cbTypeOfLinkProduced.addItem(newLink);

                        // Remember to set the selection to the new item
                        cbTypeOfLinkProduced.select(newLink);            
        } catch (Exception e) {
            throw new Validator.InvalidValueException(ctx.tr("BatchLinkingDbpedia.dialog.linkprooduced.invalid"));
        }
    }
});
mainLayout.addComponent(cbTypeOfLinkProduced);


# Saving the configuration to the config object - in "getConfiguration" method:
cbTypeOfLinkProduced.validate();
c.setLinkUri((IRI)cbTypeOfLinkProduced.getValue());


# Reading the configuration from the config object - in "setConfiguration" method:
comboBox.addItem(SAMEAS);
..
comboBox.addItem(c.getLinkUri());
comboBox.select(c.getLinkUri());

When creating a new button, use the following additional styles:

button.addStyleName("Button Button--sm Button--primary");