What is a Pluggable Entry Editor?
Pluggable entry editors are like the pluggable attribute editors of the last chapter, except that they are triggered on an entire entry, rather than just an attribute of an entry. They take up the entire right hand editing pane, and can suppress the normal html and table display if desired, giving a 'custom application' look.
As mentioned before, there may be no need to write a pluggable editor. If all you
need to do is give a custom look-and-feel to your data, you may find it easier to
use the html templates and forms, in which case you won't need to write a line of code!
But if you need to do any complex client-side processing (wizards, form validation,
etc.) it may be useful to write your own editors.
Editor Names and locations
The name of the editor must be the same as the object class of the type of entry it
is to be used for. So if the editor is to be used for 'people', the name of the
class is simply 'people.class'. The editors can be placed in the 'plugins'
directory (in the correct path; plugins/com/ca/directory/jxplorer/viewer) or can be packaged
in a jar file (which is often easier to deploy). If packaged in a jar, the
JXplorer classpath will need to be modified, either in the console.bat file, or
however JXplorer is being invoked. Entry editors must be completely in lower case,
and there is no suffix.
The PluggableEditor Interface
The Pluggable Editor interface (see the API Reference)
defines a number of methods that allow the Pluggable Editor to take control of the
entirety of JXplorer. Most of the time you will only want to use a handful of these.
The DataSink Interface
The DataSink interface is used internally in JXplorer for transferring data to
data consumers. Since the Pluggable Editor class does this, a PluggableEditor must
also implement the DataSink interface (which has only two methods).
Extending BasicPluggableEditor
Most editor writers will probably simply extend BasicPluggableEditor, which has default implementations of all the required methods. BasicPluggableEditor simply displays the entry passed to it as text in a JPanel. The following shows a trivial extension of BasicPluggableEditor (which in fact does exactly the same thing - simply displays the entry in a text pane).
---------------------------------------------------------------------
import Javax.swing.*;
import com.ca.directory.jxplorer.viewer.BasicPluggableEditor;
import com.ca.directory.naming.DXEntry;
import com.ca.directory.jxplorer.DataSource;
public class person extends BasicPluggableEditor
{
JEditorPane basicDisplay;
/**
* The Constructor sets up the JEditorPane GUI
*/
public person()
{
basicDisplay = new JEditorPane("text/plain", "");
}
/**
* This method is called by JXplorer when a new 'person' entry
* needs to be displayed.
*/
public void displayEntry(DXEntry entry, DataSource ds)
{
basicDisplay.setText(entry.toString());
}
/**
* This method returns a GUI component to JXplorer to display
* in the right hand pane.
*/
public JComponent getDisplayComponent()
{
return basicDisplay;
}
}
---------------------------------------------------------------------
This results in the following (fairly boring) editor pane:
The 'person.class' editor
This is pretty much all that is required for your own pluggable editor - a
GUI and some code to handle the 'displayEntry(..)' method. Check
the API for the methods of the DXEntry object - it is an extension of the
standard JNDI 'Attributes' object and supports all its methods, as well as
a large number of utility extension methods (such as the entry.toString() method above).
Sending Changes to the Directory
When your user has registered changes in your custom pluggable editor GUI, you'll
need to submit them to the directory. The core pluggable editor method is public void displayEntry(DXEntry entry, DataSource ds). The entry parameter is the data to display, while the DataSource parameter is a link to a data source (usually a directory) that you can use to
submit changes. The simplest call in DataSource is modifyEntry(..), which
takes the original entry and the new entry, and makes the necessary calls to the
directory to efficiently convert the old entry to its new state.
There are a large number of other data related operations you might want to make with the directory, ranging from reading more data, searching, modifying the directory tree structure, and reading schema details.
DataSource is actually the front end to a queued, multi-threaded directory connection. As a pluggable Editor writer you shouldn't normally need to worry about that; it just means that your GUI won't freeze up when you make a directory request! However if you need to know the result of a directory operation you'll need to know about the data event model. When a directory operation is completed (successfully or otherwise) your editor can find out by registering itself as a 'DataListener' (this metaphor will be familiar to Java programmers who have worked with GUI listeners). The details of doing this are covered in the next chapter.