Writing the Adapter Configurator

If an adapter is going to be used often, it is not convenient each time to manually edit the "config.xml" file in order to change the adapter configuration. Developing a custom adapter configurator GUI solves this problem and also allows more complex configurations to be used.

A custom adapter configurator for the Math adapter should allow the user to select the operation and to turn on and off the rounding of the result. A simple GUI that does this is shown in the following figure:

Figure 12. MathAdapter Configurator GUI

The task of an adapter configurator is to generate the config.xml file according to the user’s inputs. A managed adapter configurator is a class that extends the "com.savvion.sbm.adapters.framework.AdapterConfiguratorBase" class and overwrites the following methods:

public void init(JPanel panel). This method creates the GUI. An empty JPanel is passed by the framework and the custom adapter configurator is expected to populate it with GUI elements. Those must not include the OK and Cancel button, which are placed automatically on every adapter configurator dialog. In the case of the MathAdapter configurator, the init() method should place in the JPanel the operation and rounding labels and check boxes, as shown in the above figure.

public void setConfig(AdapterConfig ac). This method is called by the adapter framework if there is an existing configuration (for example, if the adapter configuration for an already existing Business Process Server process is edited). The "ac" parameter is a "com.savvion.sbm.adapter.framework.AdapterConfig" object – a wrapper around the config.xml format. It allows you, as an adapter developer, to avoid parsing XML format and shields you for any future changes in the XML DTD.

public AdapterConfig getConfig(). This method is called by the adapter framework when the user (OpenEdge Business Process Server process developer) presses the OK button on the adapter configurator. The adapter configurator is expected to return a "com.savvion.sbm.adapters.framework.AdapterConfig" object, describing the config.xml file. Your code does not have to worry when, how, and where this information is stored. See the comments regarding the AdapterConfig object in the description of the setConfig() method above.

Following is a listing of the MathAdapter configurator implementing these three methods:

01 package demo;
02
03 import com.savvion.sbm.adapters.framework.AdapterConfig;
04 import com.savvion.sbm.adapters.framework.AdapterConfiguratorBase;
05
06 import java.awt.GridBagConstraints;
07 import java.awt.GridBagLayout;
08 import java.awt.Insets;
09 import javax.swing.JComboBox;
10 import javax.swing.JLabel;
11 import javax.swing.JPanel;
12 import javax.swing.JTextField;
13
14 public class MathAdapterConfigurator extends AdapterConfiguratorBase
15 implements MathAdapterConstants
16 {
17
18 private JLabel OPERATION_LABEL;
19 private JLabel ROUNDING_LABEL;
20 private JComboBox OPERATION_COMBO_BOX;
21 private JComboBox ROUNDING_COMBO_BOX;
22
23 public void init(JPanel panel) throws Exception {
24
25 setTitle("MathAdapter Config");
26
27 OPERATION_LABEL = new JLabel("Operation");
28 ROUNDING_LABEL = new JLabel("Rounding");
29 OPERATION_COMBO_BOX = new JComboBox(
30 new String[] {
31 OPERATION_ADD,
32 OPERATION_SUB,
33 OPERATION_MUL,
34 OPERATION_DIV
35 });
36 ROUNDING_COMBO_BOX = new JComboBox(
37 new String[]{"false", "true"}
38 );
39
40 panel.setLayout(new GridBagLayout());
41 GridBagConstraints cs = new GridBagConstraints();
42 cs.insets = new Insets(5,5,5,5);
43 cs.fill = cs.HORIZONTAL;
44 cs.weightx = 0.0;
45 cs.gridx = cs.gridy = 0;
46 panel.add(OPERATION_LABEL, cs);
47 cs.gridy = 1;
48 panel.add(ROUNDING_LABEL, cs);
49 cs.weightx = 1.0;
50 cs.gridx = 1; cs.gridy = 0;
51 panel.add(OPERATION_COMBO_BOX, cs);
52 cs.gridy = 1;
53 panel.add(ROUNDING_COMBO_BOX, cs);
54 }
55
56 public void setConfig(AdapterConfig ac) throws Exception {
57 OPERATION_COMBO_BOX.setSelectedIndex(0);
58 ROUNDING_COMBO_BOX.setSelectedIndex(0);
59 if (ac!=null) {
60 String operation = ac.getParameterValue(PARAM_OPERATION);
61 if (operation!=null)
62 OPERATION_COMBO_BOX.setSelectedItem(operation);
63 String rounding = ac.getParameterValue(PARAM_ROUNDING);
64 if (rounding!=null)
65 ROUNDING_COMBO_BOX.setSelectedItem(rounding);
66 }
67 }
68
69 public AdapterConfig getConfig() throws Exception {
70 AdapterConfig ac = new AdapterConfig();
71
72 String operation = (String)OPERATION_COMBO_BOX.getSelectedItem();
73 String rounding = (String)ROUNDING_COMBO_BOX.getSelectedItem();
74
75 ac.addBlock("Config", "Config", true);
76 ac.addParameter("Config",
77 PARAM_OPERATION,
78 AdapterConfig.ACCESS_HIDDEN,
79 PARAM_OPERATION,
80 "java.lang.String",
81 operation,
82 "true");
83 ac.addParameter("Config",
84 PARAM_ROUNDING,
85 AdapterConfig.ACCESS_HIDDEN,
86 PARAM_ROUNDING,
87 "java.lang.String",
88 rounding,
89 "true");
90
91 ac.addBlock("Inputs", "Inputs", false);
92 ac.addParameter("Inputs",
93 PARAM_X,
94 AdapterConfig.ACCESS_I,
95 PARAM_X,
96 "java.lang.Double",
97 "",
98 "true");
99 ac.addParameter("Inputs",
100 PARAM_Y,
101 AdapterConfig.ACCESS_I,
102 PARAM_Y,
103 "java.lang.Double",
104 "",
105 "true");
106
107 ac.addBlock("Outputs", "Outputs", false);
108 ac.addParameter("Outputs",
109 PARAM_RESULT,
110 AdapterConfig.ACCESS_O,
111 PARAM_RESULT,
112 "java.lang.Double",
113 "",
114 "false");
115
116 return ac;
117 }
118
119 }

In the init() method, lines 25-38 initialize the GUI elements. Those are then placed in the JPanel at lines 40-53. Again, note that this does not include the OK and Cancel buttons – OK and Cancel are placed under the JPanel by the adapter framework.

The setConfig() method, on lines 57-58 initializes the check boxes with their default values. If the AdapterConfig parameter is not null, the check boxes are reset with the values from this existing configuration (lines 59-66).

The longest method in this class, getConfig(), generates a new AdapterConfig object, based on the user’s (the OpenEdge Business Process Server process designer) entries in the configurator. A fresh AdapterConfig is created and the values for the "OPERATION" and "ROUNDING" parameters are obtained on lines 70-73.

Next, each of the blocks in the adapter configuration, and the parameters in each block, are added in turn. Refer to the section on config.xml. Note that this method defines not only the "OPERATION" and "ROUNDING" configuration parameters, but also specifies all adapter inputs and outputs – in this case, the "X", "Y" and "RETURN" parameters. The difference is that the "X", "Y", and "RETURN" parameters do not have default value, and are made visible for mapping to dataslots by the user.