Database Inclusion Plugin Devlopers Notes

Developers' notes for migrating plug-ins to Protege 3.4 beta 500 (and newer versions)

This is a short guide for plug-in developers to help them migrate their plug-ins to Protege 3.4 beta 500 (and newer versions). This build contains significant changes from previous builds (see Release Notes). Some of the significant changes in this build are:

• Support for database inclusion
• New namespace mechanism in OWL (internal names in Protege-OWL are now the fully qualified name)
• New OWL parser

RDFResource.getName() returns the full name (OWL only)

Previously calling something like

resource.getName()

where resource was an RDFResource would return a qualified name such as owl:Class. Now it will return the full name, e.g.

http://www.w3.org/2002/07/owl#Class.

There are methods to return all the variants

resource.getPrefixedName() -> owl:Class
resource.getNamespacePrefix() -> owl
resource.getNamespace() -> http://www.w3.org/2002/07/owl#

Renaming Frames or OWL Entities

The single biggest change in this version is is that Protege frames (so also OWL entities) cannot be renamed. Previously a rename operation consisted of simply taking an existing frame and assigning a new name to it. In order to support database inclusion properly, we had to change this. The name is now an immutable part of a frame. In order to "rename" a frame, we need to do a shallow copy of the frame to another frame with the new name and then delete the old frame.

This creates two issues for plugin developers. First, the old Frame.setName call has been replaced with Frame.rename. This means that when plugins need to change the names of frames they will need to be updated and recompiled.

The code for renaming a frame (OWL entity) should look like:

Frame frame = ...;
frame = frame.rename(newName);

The code above applies both for frames and OWL.

Listening to frame rename (i.e. replace) events

A new method, frameReplaced in the FrameListener allows you to listen for frame replace events. The getNewFrame method from FrameEvent allows you to get the new frame with the new name. You can get the name of the old frame by calling event.getOldName(). After a frame was replaced, you should NOT use in your code the old frame anymore. The old frame will be destroyed. Your code should use the new frame.

The following code snippet shows an example how to listen for frame rename (i.e. replace) events:

FrameAdapter frameAdapter = new FrameAdapter() {
  @Override
  public void frameReplaced(FrameEvent event) {
     System.out.println("New frame: " + event.getNewFrame());
     System.out.println("Old frame name: " + event.getOldName());
     //don't use the old frame anymore!! 
     System.out.println("Old frame: " + event.getFrame());
  }			
 };

 kb.addFrameListener(frameAdapter);

Plug-in reaction to frame name changed event

The developers may want to change the logic of how their plugins react to a name change. If the plugin is not changed then a rename operation will look like a create, some copy operations and a delete. This logic is internally consistent but it is not always what the user wants to see. For example if the user was editing the frame that was renamed the editing window might disappear because the frame was deleted. So in some cases the plugin may need to maintain the illusion that the newly created frame is the same as the existing frame. Therefore plugins will want to listen for the FrameReplaced event (which indicates that a rename is occuring where one frame is getting replaced with another) with a frame listener. In addition, if the plugin now has logic for listening to the FrameReplaced event, it will probably want to ignore other events like the deletion of the original frame and the creation of the new frame. To support this we have provided a new method called AbstractEvent.isReplacementEvent() that will inform the caller of whether an event is appearing as part of a rename operation. Thus one rename event aware component has a ClsListener with the following code:

   public void directSubclassMoved(ClsEvent event) {
       if (event.isReplacementEvent()) return;
       Cls subclass = event.getSubclass();
       int index = (new ArrayList(getChildObjects())).indexOf(subclass);
       if (index != -1) {
           childRemoved(subclass);
           childAdded(subclass, index);
       }
   }

   public void directInstanceAdded(ClsEvent event) {
      	if (event.isReplacementEvent()) return;
           notifyNodeChanged();
       }
       ...

The point is that all events except occuring for the duration of a rename event except for the Replace Frame event are ignored.

Users of FrameID

Existing code that uses FrameID() probably won't work. FrameID's can still be used to uniquely represent a frame but none of their previously existing structure exists any more.

setName() has been removed from the Frame interface

The setName method has been removed from the interface. Please use instead Frame.rename both for Frames and OWL. See Renaming Frames or OWL Entities section above for more details.