Difference between revisions of "Database Inclusion Plugin Devlopers Notes"

From Protege Wiki
Jump to: navigation, search
Line 1: Line 1:
 +
<div style="background:#F0E6CA; border:1px solid #AE5B08; padding:10px 15px 10px 20px; margin:2em 0 0 0;">
 +
<span class="orangeBoxTitle">Developers' notes for migrating plug-ins to Protege 3.4 beta 500 (and newer versions)</span><br /><br />
 +
 +
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 [http://protege.stanford.edu/download/release_notes/release_notes_beta.html 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
 +
 +
</div><br />
 +
 
__TOC__
 
__TOC__
  
Line 15: Line 25:
 
== Renaming Frames or OWL Entities ==
 
== Renaming Frames or OWL Entities ==
  
The single biggest change in this version is is that Protege frames 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.
+
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.
+
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.
  
Second, 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 editting 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:
+
The code for renaming a frame (OWL entity) should look like:
 +
 
 +
Frame frame = ...;
 +
frame = frame.rename(newName);
 +
 
 +
The code above applied both for frames and OWL.
 +
 
 +
 
 +
== 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) {
 
     public void directSubclassMoved(ClsEvent event) {
Line 44: Line 64:
  
 
== setName() is gone (Mainly Protege Core Developers) ==  
 
== setName() is gone (Mainly Protege Core Developers) ==  
 +
 +
Use instead Frame.rename. See ''Renaming Frames or OWL Entities'' section above.
  
 
== Use getSystemFrames() ==  
 
== Use getSystemFrames() ==  
  
 
== Parser.run() ==
 
== Parser.run() ==

Revision as of 10:26, June 3, 2008

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 applied both for frames and OWL.


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() is gone (Mainly Protege Core Developers)

Use instead Frame.rename. See Renaming Frames or OWL Entities section above.

Use getSystemFrames()

Parser.run()