Apart from the configuration of the File Adapter (file name, directory, mode), each plug-in may have its own configuration, used to tune the way it processes the data. Not all plug-ins need custom configuration. For example, the Text plug-in only writes the string it is given, and no configuration is needed.
One of the requirements for the custom Log Format plug-in we are creating is to provide some level of customization of the format of the messages stored in the logfile. This can be achieved by providing a format string that will match each record stored in the file, such as:
[D] M
D - M
M [D]
where M is the message, and D is the date/time when this message was logged.
The plug-in configuration is maintained by the File Adapter and can be any serializable object. However, using a String object for plug-in configuration has some advantages and is highly recommended. If the configuration of your plug-in is relatively simple, we recommend that you devise some mechanism to store it as a string. If the configuration is more complex, we recommend that you define a configuration wrapper object that can produce XML string, and can be initialized from XML string. This will make the configuration files more readable, and will also provide some performance advantages over simply using serializable objects.
In case of the Log Format Plug-in, the configuration can consist simply of the format string.
Every Format Plug-in must have its own configurator class. The configurator class may or may not have a GUI for configuration, but the configurator class is mandatory. If the configurator class extends the java.swing.JDialog class, the GUI is enabled; otherwise, the GUI is disabled.
The configurator class must implement the FormatConfigPlugin interface, as described below:
public interface com.savvion.sbm.adapters.file.FormatConfigPlugin {
public void setMode(int mode) throws Exception;
public void setFormatConfig(Object formatConfig) throws Exception;
public Object getFormatConfig() throws Exception;
public Vector getParameters() throws Exception;
}
The setMode() method is called at design time when the user selects an adapter mode, or at run time, when the File Adapter is invoked. The values passed to setMode() are one of the following constants, defined in the com.savvion.sbm.adapters.file.FileAdapterConfig class:
MODE_READ
MODE_WRITE
MODE_APPEND
The setFormatConfig()method is executed at design time or at run time, when the format configurator is initialized. The formatConfig parameter is the custom plug-in configuration object, which is the message format string for the Log Plug-in.
The getFormatConfig() method is used only at design time, to generate the custom format configuration object. In case there is a GUI associated with adapter configurator, the formatConfig will be generated from the values of the GUI controls set by the user. In case the File Adapter does not require GUI configuration, this method may return "null", or any static configuration object.
The getParameters() method is the most important method. It must return a Vector of the com.savvion.sbm.adapters.file.Parameter objects, each one representing an adapter input or output parameter that defines the set of values your File Adapter accepts as input, and the set of values it generates as output. For complete information on the Parameter class, refer to APIs for custom format plug-in section in the Progress OpenEdge Business Process Server: Mnagaed Adapters Guide.
The source of the custom File Adapter configurator is described below:
package com.savvion.sbm.adapters.file.plugins;
import com.savvion.sbm.adapters.file.*;
import java.util.*;
import java.awt.*;
import javax.swing.*;
public class LogConfig extends JPanel
implements com.savvion.sbm.adapters.file.FormatConfigPlugin
{ JTextField formatField = new JTextField();
public LogConfig() {
this.setLayout(new GridBagLayout());
GridBagConstraints c = new GridBagConstraints(); c.gridy=0;
c.gridx=0; this.add(new JLabel("Message format:"),c);
c.gridx=1; this.add(formatField,c);
formatField.setColumns(10);
}
public void setMode(int mode) {}
public void setFormatConfig(Object formatConfig) {
if (formatConfig instanceof String) {
formatField.setText((String)formatConfig);
} else {
formatField.setText("[D] M"); // default format
}
}
public Object getFormatConfig() {
return formatField.getText();
}
public Vector getParameters() {
Vector rtn = new Vector();
rtn.add(
new Parameter(
"MSG", // parameter name
null, // access (use mode default)
"Message", // parameter title
"java.lang.String", // parameter type
null, // default value
"true" // mandatory
)
);
return rtn;
}
}
Note that the File Adapter Configurator extends from the class javax.swing.JPanel, indicating that the plug-in has a GUI interface where the user can define the log message format. The GUI interface defined in the LogConfig() constructor is shown in the following figure.
Figure 7. File Adapter - Custom format plug-in GUI
The user enters the format string in this GUI.
The setMode() method is not used for the Log Format Plug-in, since the adapter is expected to work in either Write or Append mode, and not in any single default mode.
In the setFormatConfig() method, the text field is initialized with the message format string. In case of invalid values, the format string is set to the default format [D]M.
The getFormatConfig() method simply returns the format string entered by the user in the text field.
The getParameters() method is used to return the list of input and output parameters for the plug-in. The Log Plug-in receives one single string parameter — the message to be logged, so in the getParameters() method one single parameter is returned, named "MSG". The "access" field of this parameter can be either "I", "O", or "IO" (Input, Output, and Input/Output parameter), or it can be "null", which will use the default for the given adapter mode.
Note: Giving "null" for a parameter access, means that the access will be determined by the FileAdapter configurator based on the selected adapter mode. For example, if the mode is Write or Append, the default access would be "I", because in this mode the File Adapter is expected to receive some input values from your Business Process Server installation and store them in file. For the Read mode, the default value will be "0", because the content of the file is expected to be presented to Business Process Server as a set of outputs for the adapter parameters. You can use "null" access in most cases when writing custom format configurators.
The parameter title, "Message" is for display purposes, and will be used when defining dataslot mapping.
The parameter type is the fully qualified Java class type that you expect to receive from Business Process Server. For the list of supported types, see the "Supported Data Types" section in the "Custom Managed Adapters" chapter in the Customization Guide.
The "mandatory" attribute is set to either "true" or "false" to denote whether or not the given parameter is essential for the work of the plug-in. In our case, we must have the message string in order to log anything in the log file, so we set "mandatory" to "true". In other situations, when the plug-in may work successfully with incomplete data, you can set this attribute to "false". The difference between mandatory and non-mandatory parameters will appear when the user defines the dataslot mapping — if a mandatory parameter is left unmapped, a warning message will pop-up.
Note: For a number of reasons, the "mandatory" attribute has effect only on input and input/output parameters.
When one of your business processes using the Log Format Plug-in is configured, the format configurator will be embedded in the File Adapter Configurator GUI.
