Developers View of Scenarios

XML scenarios provide execution support for XML files

Author: Asgeir Orn Asgeirsson,

1. Introduction

The concept of Scenarios was introduced to make XML files executable. When an XML file contains a scenario, it can be executed using the Execute action in Netbeans. What execution means depends on the scenario type.

A scenario has a user interface which allows the user to control the Execution. What kind of user interface is displayed depends on the scenario's type.

2. Using scenarios

When the User wants to execute an XML file, the first thing to do is to open the scenario editor. This is done by performing the "Edit scenarios" action, which can be done from the popup menu or by using the Scenario dropdown on the Editor toolbar. When a new scenario is added in the scenario editor, the user must select the type and the name of the scenario. The type of the scenario determines what kind of user interface is displayed to edit the scenario, and what is done when that scenario is executed.

Each XML file can have many scenarios and they do not have to be of the same type. But only one scenario is active at a time. The active scenario is used when the Execute action is performed. The user can select the active scenario using the Scenario dropdown on the Editor toolbar.

3. Create a new scenario type

If a developer wants to create a new type of scenario he must do the following:

  • Create a java class which implements the ScenarioFactory interface.
  • Register the factory, using XML layers, at the folder Plugins->XML->ScenarioFactories

The ScenarioFactory class can be seen on the Class diagram of Scenarios. ScenarioFactory has the method createScenario() which returns a scenario instance. Developer of the new scenario type will thus also create a java class which implements the Scenario interface, and instance of that class will then be returned by createScenario().

The process of creating scenario type will be described in more detail in the following section.

4. Image XML tutorial

Let's take an example of a developer which has created some XML type which describes images. He wants to be able to Execute an Image XML file, which results in converting the XML data to an image file (gif, jpg, ...).

The first thing to do is to create ImageScenario class which implements Scenario. The execute() method starts a process which uses the information in the XML file to create an image data, and writes the image data to an output file. The only thing the execution needs, apart from the XML file, is the path of the output file. The getUIComponent() method returns a panel which might look like the image below.

The next step is creation of ImageScenarioFactory class which implements ScenarioFactory. The createScenario() method returns a new instance of ImageScenario. The isEnabled method should check if the DataObject contains an Image XML file, and return true only if it is. Thus the ImageScenario will only be available for Image XML files.

Finally ImageScenarioFactory must be registered using XML layers. This can be done by adding the following lines to the layer file of the implementing module, assuming that ImageScenarioFactory is in package org.blu.

<folder name="Plugins">
    <folder name="XML">
        <folder name="ScenarioFactories">
            <file name="org-blu-ImageScenarioFactory.instance"/>


5. Scenarios and XSL

The concept of Scenarios was first introduced because XSL related features needed a way to tie XML source to the XSL file. The XML source is the XML which will be transformed by the XSL during execution. Knowledge of the XML source is useful for more than being an input into the transformation. XPath autocompletion in attribute values use the XML source and XPaths might be generated in a customizer which allows picking of nodes from the XML source. (Such a customizer has actually been implemented by my company, Dimon Software, but we have decided not to contribute it. At least not yet.)

The Scenario interface must be extended to make the XML source available to the XPath generating features. The XSLScenario interface extends Scenario and adds a single method getSourceDocument(). Scenarios that define XML sources for XSL files should extend XSLScenario rather than Scenario. FileXSLScenario is an example of such a scenaro.

Now the other way around. What if are writing an XML source and wanted to tie an XSL to it for previewing? We need a new type of scenario, XSLTransScenario, which has a UI panel which allows the user to select a stylesheet. That scenario should be enabled for all XML files, even for stylesheets (if one would like to transform his stylesheet).

6. Future of scenarios

For historical reasons, Scenarios are implemented in the XSL module. As described in this document, Scenarios are far from being bound to XSL only. Thus we have to decide what should be done to the scenario related classes.

The scenario related classed can be divided into two categories, API classes and internal classes. The API classes are: Scenario and ScenarioFactory. The internal classes are: ScenarioAction, ScenarioCookie, ScenarioData, ScenarioExecSupport, ScenarioSupport, NewScenarioPanel and ScenarioPanel.

I recommend that the API classes will be put into the core. The internal classes might either be put into the core or in a new module.

Project Features

About this Project

XML was started in November 2009, is owned by dstrupl, and has 62 members.
By use of this website, you agree to the NetBeans Policies and Terms of Use (revision 20160708.bf2ac18). © 2014, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo
Please Confirm