Protege Wiki - User contributions [en]

CompileProtege4InEclipseFromSvn

2011-04-20T13:37:48Z

Swartik: Fixed some lower-case button names.

= Instructions for Compiling and Running Protege 4.1 in Eclipse using the sources from SVN =

These instructions will help you set up the Eclipse environment for Protege 4.1. In the first part, we will check out from SVN a Eclipse workspace already configured for Protege 4.1 and its plugins, then in the second part, we will show how to add your own plugin in Eclipse.

__TOC__

== Prerequisites ==

To follow these directions you will need the following tools:
* Eclipse (of course) with
** the Plugin Development tools included. As indicated [http://www.eclipse.org/downloads/packages/compare-packages here], the plugin development environment comes with the Java EE or the RCP/Plugin versions of eclipse.
** the [http://www.eclipse.org/subversive/documentation/gettingStarted/aboutSubversive/install.php Eclipse Subversive] plugin, though this is only required if you want to do svn updates using eclipse. Note that there is another similar but different plugin (from Tigris I believe). I don't know if these plugins interfere with one another if they are both loaded.
* A tool for extracting a zip file into a directory.
* A tool for checking out a repository from subversion (e.g. tortoise or the svn command line client).
These directions are based on a preconfigured workspace which you can use for the build.

== Configuring Eclipse ==

'''Step 1: Checking out the workspace''' Use subversion to checkout the following workspace:
<pre>
http://smi-protege.stanford.edu/repos/protege/protege4/ide/eclipse/protege4.1/trunk
</pre>
If you are using command line tools you can do this with the svn command
<pre>
svn checkout http://smi-protege.stanford.edu/repos/protege/protege4/ide/eclipse/protege4.1/trunk protege4.1
</pre>
This creates an eclipse workspace but some of the metadata is still missing.

''Tortoise svn Users:'' Note that when using Tortoise svn, you need to do a full recursive checkout. It may appear that there is only one file in the repository but the svn checkout needs to also checkout the external references.

''Using Eclipse svn:'' It is possible to checkout this directory using eclipse but eclipse developers need to understand that they are checking out a workspace and not a project. If the developer has an alternative method of checking out the directory that method would probably be less confusing.

'''Step 2: Install the Eclipse metadata''' Inside the directory that you just checked out is a file called metadata.zip. Extract this file into the created directory. Now the eclipse workspace is ready for eclipse. Note that on the mac, double-clicking the metadata.zip file does not do the right thing; it does not simple extract the files into the current directory. So on the mac the command line unzip is probably recommended:
<pre>
unzip metadata.zip
</pre>

'''Step 3: Load the Workspace''' Start eclipse and choose the newly created directory as the workspace. Since this is a new workspace, eclipse comes up with a welcome screen which you can dismiss. We now import the projects. Go to the file menu and click "File->Import". You should get a window as shown below and can open the "General" tree to see and select the "Existing Projects into Workspace".

[[File:EasyP4EclipseImportProjects.png|frame|none|]]

Once "Existing Projects into Workspace" has been selected click Next. This should give you the window shown below.

[[File:EasyP4EclipseImportProjects02.png|frame|none]]

Click the Browse button to select the workspace directory.

[[File:EasyP4EclipseImportProjects03.png|frame|none]]

Once you have selected the workspace you should see the window below that includes the projects that you want to import.

[[File:EasyP4EclipseImportProjects04.png|frame|none]]

Click Finish and the files should be imported.

[[File:EasyP4EclipseProjectsImported.png|frame|none]]

Now all the projects have been loaded into eclipse.

'''Step 4a: Run Protege (The easy and better way)''' This step can be a bit problematic on the mac but works for linux and windows machines. Just recently this method seems to have started working with Snow Leopard and the latest eclipse (Helios).

Click on the down arrow just to the right of the little bug (near the top of the eclipse window perhaps just under the Refactor menu). Select ''Protege'' (not ''Protege.From.Build''). This should start Protege.

Note that when starting Protege in this way, the mechanism by which the plugins are found is different than the mechanism that Protege uses when it is distributed. When Protege is distributed, it scans the plugin directory and find the plugins there. When Protege is started in this manner, eclipse is loading the plugins for Protege. In fact, Protege will report "No Plugins Found" because it does not find a plugin directory and thus did not find any plugins to load. But if you enter "status" in the console you will see a detailed description of the state of the run including a description of what plugins have been found.

'''Step 4b: Run Protege the Harder Way (use only if the easy way 4a did not work)''' The second icon to the right of the little bug is a run icon with a suitcase. Click the little down arrow beside this icon and run the following scripts in this order:
# Build.Protege.Infrastructure
# Build.Common
# Build.Core
# Build.Jaxb.Lib
# Build.Owlapi.Lib
# Build.Owl.Editor
# Build.OwlViz

If the projects are marked with red in the left project tree view, refresh them all.

Now we have built a Protege distribution. This distribution is in the Protege directory in the eclipse workspace. Having created this distribution, we can run the other runnable in the bug menu. Click the down arrow beside the little bug and select run ''Protege from build''.

== Add your own plugin ==

Just make your plugin into a plugin development project.

'''Easy way'''. If you are able to run protege the easy way (4a) then your plugin will be included. Hotspot replace works (some of the time as always).

'''Harder way'''. If you run protege the harder way (4b) then you will need to install your plugin into the protege distribution that we have created. To do this you will need an ant build file. We have provided a [http://smi-protege.stanford.edu/repos/protege/protege4/protege-base/trunk/etc/template-plugin-build.xml template build file] that can easily be filled in. We will now describe how this script is added as an eclipse build script. We will turn the fact that I forgot to install the dlquery build script in eclipse into an advantage by showing how this is added here.

To create this new eclipse build script, click on the down arrow to the right of the suitcase runnable and click on "External Tool Configurations". Select "Ant Build" and click the "New Launch Configuration" just above the selected "Ant Build" option. In the resulting window, set the name to "Build.DlQuery" and browse the workspace for the DLQuery build.xml file. The result should look like this:

[[File:Protege4.1InEclipseWIthSvnExternalTools.png|frame|none|]]

Now go to the targets tab and make sure that the install target is chosen.

[[File:Protege4.1InEclipseWIthSvnAntSetTarget.png|frame|none|]]

Finally go to the Environment tab and make sure that PROTEGE_HOME is set to ${workspace_loc}/Protege.

[[File:Protege4.1InEclipseWIthSvnAntEnvironment.png|frame|none|]]

Now the new build script can be saved (Apply) and run. Running this script will install your plugin (DLQuery in this case) into the Protege distribution that we have been making.

CompileProtege4InEclipseFromSvn

2011-04-20T13:20:18Z

Swartik: Removed an extra "and".

= Instructions for Compiling and Running Protege 4.1 in Eclipse using the sources from SVN =

These instructions will help you set up the Eclipse environment for Protege 4.1. In the first part, we will check out from SVN a Eclipse workspace already configured for Protege 4.1 and its plugins, then in the second part, we will show how to add your own plugin in Eclipse.

__TOC__

== Prerequisites ==

To follow these directions you will need the following tools:
* Eclipse (of course) with
** the Plugin Development tools included. As indicated [http://www.eclipse.org/downloads/packages/compare-packages here], the plugin development environment comes with the Java EE or the RCP/Plugin versions of eclipse.
** the [http://www.eclipse.org/subversive/documentation/gettingStarted/aboutSubversive/install.php Eclipse Subversive] plugin, though this is only required if you want to do svn updates using eclipse. Note that there is another similar but different plugin (from Tigris I believe). I don't know if these plugins interfere with one another if they are both loaded.
* A tool for extracting a zip file into a directory.
* A tool for checking out a repository from subversion (e.g. tortoise or the svn command line client).
These directions are based on a preconfigured workspace which you can use for the build.

== Configuring Eclipse ==

'''Step 1: Checking out the workspace''' Use subversion to checkout the following workspace:
<pre>
http://smi-protege.stanford.edu/repos/protege/protege4/ide/eclipse/protege4.1/trunk
</pre>
If you are using command line tools you can do this with the svn command
<pre>
svn checkout http://smi-protege.stanford.edu/repos/protege/protege4/ide/eclipse/protege4.1/trunk protege4.1
</pre>
This creates an eclipse workspace but some of the metadata is still missing.

''Tortoise svn Users:'' Note that when using Tortoise svn, you need to do a full recursive checkout. It may appear that there is only one file in the repository but the svn checkout needs to also checkout the external references.

''Using Eclipse svn:'' It is possible to checkout this directory using eclipse but eclipse developers need to understand that they are checking out a workspace and not a project. If the developer has an alternative method of checking out the directory that method would probably be less confusing.

'''Step 2: Install the Eclipse metadata''' Inside the directory that you just checked out is a file called metadata.zip. Extract this file into the created directory. Now the eclipse workspace is ready for eclipse. Note that on the mac, double-clicking the metadata.zip file does not do the right thing; it does not simple extract the files into the current directory. So on the mac the command line unzip is probably recommended:
<pre>
unzip metadata.zip
</pre>

'''Step 3: Load the Workspace''' Start eclipse and choose the newly created directory as the workspace. Since this is a new workspace, eclipse comes up with a welcome screen which you can dismiss. We now import the projects. Go to the file menu and click "File->Import". You should get a window as shown below and can open the "General" tree to see and select the "Existing Projects into workspace".

[[File:EasyP4EclipseImportProjects.png|frame|none|]]

Once "Existing Projects into Workspace" has been selected click next. This should give you the window shown below.

[[File:EasyP4EclipseImportProjects02.png|frame|none]]

Click the browse button to select the workspace directory.

[[File:EasyP4EclipseImportProjects03.png|frame|none]]

Once you have selected the workspace you should see the window below that includes the projects that you want to import.

[[File:EasyP4EclipseImportProjects04.png|frame|none]]

Click finish and the files should be imported.

[[File:EasyP4EclipseProjectsImported.png|frame|none]]

Now all the projects have been loaded into eclipse.

'''Step 4a: Run Protege (The easy and better way)''' This step can be a bit problematic on the mac but works for linux and windows machines. Just recently this method seems to have started working with Snow Leopard and the latest eclipse (Helios).

Click on the down arrow just to the right of the little bug (near the top of the eclipse window perhaps just under the Refactor menu). Select ''Protege'' (not ''Protege.From.Build''). This should start Protege.

Note that when starting Protege in this way, the mechanism by which the plugins are found is different than the mechanism that Protege uses when it is distributed. When Protege is distributed, it scans the plugin directory and find the plugins there. When Protege is started in this manner, eclipse is loading the plugins for Protege. In fact, Protege will report "No Plugins Found" because it does not find a plugin directory and thus did not find any plugins to load. But if you enter "status" in the console you will see a detailed description of the state of the run including a description of what plugins have been found.

'''Step 4b: Run Protege the Harder Way (use only if the easy way 4a did not work)''' The second icon to the right of the little bug is a run icon with a suitcase. Click the little down arrow beside this icon and run the following scripts in this order:
# Build.Protege.Infrastructure
# Build.Common
# Build.Core
# Build.Jaxb.Lib
# Build.Owlapi.Lib
# Build.Owl.Editor
# Build.OwlViz

If the projects are marked with red in the left project tree view, refresh them all.

Now we have built a Protege distribution. This distribution is in the Protege directory in the eclipse workspace. Having created this distribution, we can run the other runnable in the bug menu. Click the down arrow beside the little bug and select run ''Protege from build''.

== Add your own plugin ==

Just make your plugin into a plugin development project.

'''Easy way'''. If you are able to run protege the easy way (4a) then your plugin will be included. Hotspot replace works (some of the time as always).

'''Harder way'''. If you run protege the harder way (4b) then you will need to install your plugin into the protege distribution that we have created. To do this you will need an ant build file. We have provided a [http://smi-protege.stanford.edu/repos/protege/protege4/protege-base/trunk/etc/template-plugin-build.xml template build file] that can easily be filled in. We will now describe how this script is added as an eclipse build script. We will turn the fact that I forgot to install the dlquery build script in eclipse into an advantage by showing how this is added here.

To create this new eclipse build script, click on the down arrow to the right of the suitcase runnable and click on "External Tool Configurations". Select "Ant Build" and click the "New Launch Configuration" just above the selected "Ant Build" option. In the resulting window, set the name to "Build.DlQuery" and browse the workspace for the DLQuery build.xml file. The result should look like this:

[[File:Protege4.1InEclipseWIthSvnExternalTools.png|frame|none|]]

Now go to the targets tab and make sure that the install target is chosen.

[[File:Protege4.1InEclipseWIthSvnAntSetTarget.png|frame|none|]]

Finally go to the Environment tab and make sure that PROTEGE_HOME is set to ${workspace_loc}/Protege.

[[File:Protege4.1InEclipseWIthSvnAntEnvironment.png|frame|none|]]

Now the new build script can be saved (Apply) and run. Running this script will install your plugin (DLQuery in this case) into the Protege distribution that we have been making.

PluginAnatomy

2011-04-06T15:14:47Z

Swartik: Removed spurious "."

== Introduction ==

The purpose of this web page is to describe some of the key ingredients of a plugin. The page will be directed by
the quick development of a plugin and can indeed be used as a quick start guide. In order to focus attention on the core plugin
concepts we will use the lowest common denominator of Java development tools and this tutorial will not use a Java IDE.
We will assume that the
reader has an understanding of Java development and knows how to follow along in his favorite IDE. For more information about
how to work with protege 4 in an IDE I will direct the reader to [[Protege4DevDocs#Using_an_Integrated_Development_Environment|this page]]. It is possible for an experienced developer to skip the ant scripts simply follow along in an IDE but we would still recommend a build file for the final version.

The sources for the first plugin (the example tab) can be found [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/plugin/trunk/org.protege.editor.owl.examples.tab here]. You can either check these out from svn and use this as a guide for reading the text or build this project in a series of step by step stages as described below. If you start from the checked out version then you can build the project by following the directions [[#Compile and Run|here]].

==The vacuous plugin in five minutes==

I created a (vacuous) plugin from scratch, installed it and ran it in just under [[Protege4 Plugin In Four Minutes|four minutes]].

The simplest (trivial) plugin can be built from sources in the following layout:<pre>
build.xml
META-INF
MANIFEST.MF
lib
resources
src
</pre> As we will see - even without any java sources - this is a sufficient basis for building a plugin that is recognized by Protege 4. There are only two files in this source tree - the build.xml file and the MANIFEST.MF. These files can be quickly put together from templates.

===Build.xml===

The template for the build.xml file can be downloaded from [http://smi-protege.stanford.edu/repos/protege/protege4/protege-base/trunk/etc/template-plugin-build.xml here]. Only two things need to be changed in this build file. They can be found by searching for the string "CHANGE ME" in the file. The first thing to change is the name of the project. I will call the project the plugin tutoiral project:<pre>
<project name = "plugin tutorial" default = "install" basedir = ".">
</pre>
The next setting that must almost always be changed is the name of the plugin. In this case, the build.xml already has the right name for the plugin but this is the only plugin for which this will be true:<pre>
<property name = "plugin" value = "org.protege.editor.owl.examples.tab"/>
</pre>
With these adjustments the build.xml file is ready.

===MANIFEST.MF===

The template for the MANIFEST.MF file can be downloaded from [http://smi-protege.stanford.edu/repos/protege/protege4/protege-base/trunk/etc/template-manifest.mf here]. Only five things need to be changed in this file to make it useable and two are optional. These can be found by searching for the string "CHANGE ME" in the file. The first change is to set the display name for the plugin:<pre>
Bundle-Name: Tutorial Plugin
</pre> This is the name that is seen when Protege 4 starts up and in several plugin configuration screens.
The seccond thing to change is the symbolic name of the plugin. The usual default is to uses the same name as the plugin name in the build.xml file:<pre>
Bundle-SymbolicName: org.protege.editor.owl.examples.tab;singleton:=true
</pre>
Note the "singleton:=true" line - this is important since most Protege 4 plugins will only work if they are instantiated exactly once. The next things to change are the bundle description, the vendor and the documentation url:<pre>
Bundle-Description: A simple plugin for a plugin development tutorial
Bundle-Vendor: The Protege Development Team
Bundle-DocURL: www.perhaps.i.donthaveoneyet.com
</pre>
Actually the vendor and the docurl are optional and can be deleted. The MANIFEST.MF file is now ready.

===Compile and Run===

Before we can start, we must set the PROTEGE_HOME environment variable to point to a Protege 4 distribution. [[ConfiguringAntBuildFiles|This page]] has directions on how to do this in different operating systems but for now I will assume that we are on a unix (or os x) system. In that case, the system variable can be set with a simple command <pre>
export PROTEGE_HOME=/Users/tredmond/Desktop/Protege_4.1_beta
</pre>

This vacuous plugin is now ready to compile and run. Assuming that the PROTEGE_HOME environment variable is set correctly, this plugin can be compiled with the simple command <pre>
ant install
</pre>
The full text of the build session is as follows:<pre>
[tredmond@Andromeda org.protege.editor.owl.examples.tab]$ ant install
Buildfile: build.xml

init:
[mkdir] Created dir: /private/tmp/org.protege.editor.owl.examples.tab/build
[mkdir] Created dir: /private/tmp/org.protege.editor.owl.examples.tab/build/classes
[mkdir] Created dir: /private/tmp/org.protege.editor.owl.examples.tab/build/classes/lib
[mkdir] Created dir: /private/tmp/org.protege.editor.owl.examples.tab/build/lib

checkProtegeLibs:
[echo] Using Protege Home = /Andromeda/Users/tredmond/dev/workspaces/protege4/owleditor/build/dist/equinox to find protege jars

checkProtegeLibsAndReport:

buildlibs:
[unjar] Expanding: /Andromeda/Users/tredmond/dev/workspaces/protege4/owleditor/build/dist/equinox/bundles/org.protege.common.jar into /private/tmp/org.protege.editor.owl.examples.tab/build

compile:

build.manifest:
[copy] Copying 1 file to /private/tmp/org.protege.editor.owl.examples.tab/build

copy.resources:
[mkdir] Created dir: /private/tmp/org.protege.editor.owl.examples.tab/build/classes/META-INF
[copy] Copying 1 file to /private/tmp/org.protege.editor.owl.examples.tab/build/classes/META-INF

jar:
[jar] Building jar: /private/tmp/org.protege.editor.owl.examples.tab/build/org.protege.editor.owl.examples.tab.jar

install:
[delete] Deleting directory /Andromeda/Users/tredmond/dev/workspaces/protege4/owleditor/build/dist/equinox/configuration/org.eclipse.core.runtime
[delete] Deleting directory /Andromeda/Users/tredmond/dev/workspaces/protege4/owleditor/build/dist/equinox/configuration/org.eclipse.osgi
[copy] Copying 1 file to /Andromeda/Users/tredmond/dev/workspaces/protege4/owleditor/build/dist/equinox/plugins

BUILD SUCCESSFUL
Total time: 2 seconds
[tredmond@Andromeda org.protege.editor.owl.examples.tab]$
</pre>
If the PROTEGE_HOME environment variable is not set correctly the user will instead see the following:<pre>
BUILD FAILED
/private/tmp/org.protege.editor.owl.examples.tab/build.xml:74: missing protege libraries
</pre>

We can now look at what the build has done by exploring the project directory tree.
[[File:AnatomyBuildTreeAnnotated.png]]

We see the following elements:
* '''The Class Tree''' is (approximately) a flattened view of the plugin (the jar file). Generally this largely consists of the .class files that have been compiled from the java. But since we have not written any java yet this is not found. In addition, this will contain resources needed by the plugin and libraries that the plugin needs but which cannot be found in other Protege plugins.
* '''The Generated Libraries''' which are extracted from Protege plugins. This is needed because of a difference between how Java and OSGi get resources out of Jar files. OSGi allows a [[PluginAnatomy#Some_Nomenclature|bundle]] (which is a implemented as a jar file) to contain other jar files. If the bundle classpath is configured correctly, OSGi will load classes from those jars in jars. But Java does not have this capability. So the build script extracts the jar files out of the OSGi bundles that will be needed to compile the bundle. Note that these jar files are not copied to the class tree because the Protege 4/OSGi environment will make the classes and resources of these jar files available.
* '''The Protege 4 Plugin''' this is the final artifact of the build process. Because we have run "ant install" it has also been installed in the Protege distribution.

If the developer is still with me then he is now ready to run the plugin. Go to the Protege distribution (the one pointed to by the PROTEGE_HOME environment variable) and run it. We are particularly interested in the console output because this is going to be the only indication that this plugin is recognized at all. The console output should look like this:<pre>
Starting Protege 4 OWL Editor (Version 4.1.111)
Platform:
Java: JVM 1.5.0_16-b06-284 Memory: 207M
Language: en, Country: US
Framework: Eclipse (1.4.0)
OS: MacOSX (10.5.6)
Processor: ppc
Installed plugin Pellet Reasoner
Installed plugin DL Query Tab
Installed plugin Owlviz Plug-in
Installed plugin owleditor
Installed plugin Tutorial Plugin
Installed plugin The OWL API
Installed plugin Factplusplus Plug-in
Tutorial Plugin Plugin has no plugin.xml resource
</pre>
In this output we see that the Tutorial Plugin has been recognized and installed. In addition there is a informational message that the plugin.xml file has not been found. This is almost always indicates a problem because most Protege 4 plugins depend on a plugin.xml resource. We will describe how the plugin.xml file is generated in the next sections.

== Writing View and Tab Plugins ==

The previous plugin added no functionality to Protege 4. We are now going to describe how to remedy this situtaion. So far we have not missed the Java IDE but it is now when we start writing a bit of Java code that the Java IDE would really shine. But to illustrate the main concepts, we will continue to show how to build the plugin without any development environment other than that provided by the core Java tools.

===Adding a View Plugin to the Plugin.xml file===

Recall that previously when we ran our plugin, Protege 4 complained that there was no plugin.xml file. The plugin.xml file contains a declaration of the ways in which the plugin will extend the Protege 4 capabilities and (more advanced) the ways in which the plugin capabilities can be extended by other plugins. We will start by adding a declaration that this plugin will implement a Protege View.

So first we will give a definition of a Protege view. The purpose of a Protege view is to provide a view of some aspect of an ontology. In the Protege interface, a Protege view is easily recognized. It has a clearly defined border. At the top of a Protege view is a title bar and a collection of buttons allowing the user to
* split the protege view into two copies of the same view one above the other,
* split the protege view into two copies of the same view one beside the other,
* float the view above the Protege client so that it is visible in any context,
* close the view removing it from the tab that contains it.
An example of a typical Protege view is shown below.
[[File:AnatomyView.png]]

In order to declare our intent that this plugin implement a Protege view, we add the following pluxin.xml file to the root of the project tree:
<pre>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<?eclipse version="3.0"?>

<plugin>
<extension id="ExampleViewComponent"
point="org.protege.editor.core.application.ViewComponent">
<label value="Example View Component"/>
<class value="org.protege.editor.owl.examples.tab.ExampleViewComponent"/>
<category value="@org.protege.ontologycategory"/>
</extension>
</plugin>
</pre>

This plugin.xml file states that this plugin is making a single extension to the Protege 4 capabilities. We will cover the meaning of the parts of this extension declaration line by line. The first line defines the id of the extension. This particular extension is called the ExampleViewComponent. The second decleration,
<pre>
point="org.protege.editor.core.application.ViewComponent",
</pre>
states what the extension is trying to do. This extension is attempting to implement the functionality represented by the extension point with the name
<pre>
org.protege.editor.core.application.ViewComponent.
</pre>
The label declaration tells Protege what to put in the title bar of the view. The class declaration indicates which class implements the functionality needed by this view. We will go into the implementation of that class shortly. Finally the category declaration tells Protege which menu under the View menu should contain this view.

A very simple view can be written by extending the class AbstractOWLViewComponent and implementing the methods initialiseOWLView and disposeOWLView. A very simple such implementation can be found
[http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/plugin/trunk/org.protege.editor.owl.examples.tab/src/org/protege/editor/owl/examples/tab/ExampleViewComponent.java here].
Now this plugin depends on a library that can be found
[http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/plugin/trunk/org.protege.editor.owl.examples.tab/lib/examplelib.jar here]. This library should be deposited in the lib directory of the project. This library is trivial and its only purpose is to show how to use a library in a plugin. The directory tree of the project should now look like this:
[[File:AnatomyTreeDoesView.png]]

At this point the ant install operation will compile, build and install the new plugin with the "ant install" command.
But the installed plugin won't run correctly and we will show how to fix this below.

===Libraries and the Bundle Classpath===

After we install the plugin, we can start Protege to try to use the "Example View Component". If you click on the View menu and then select "Ontology Views" you will see the "Example View Component" listed there. However on selecting this view and trying to place on the Protege screen, the following error will arise:
<pre>
Error logged
java.lang.NoClassDefFoundError: org/protege/owl/example/Metrics
at java.lang.Class.getDeclaredConstructors0(Native Method)
at java.lang.Class.privateGetDeclaredConstructors(Class.java:2357)
at java.lang.Class.getConstructor0(Class.java:2671)
at java.lang.Class.newInstance0(Class.java:321)
at java.lang.Class.newInstance(Class.java:303)
...
</pre>
If we look at the plugin contents with the "jar -tf " command then we will see that the build file correctly put the examplelib.jar into the plugin:
<pre>
[tredmond@BlackHole org.protege.editor.owl.examples.tab]$ jar -tf build/org.protege.editor.owl.examples.tab.jar
META-INF/
META-INF/MANIFEST.MF
lib/
org/
org/protege/
org/protege/owl/
org/protege/owl/examples/
org/protege/owl/examples/tab/
lib/examplelib.jar
org/protege/owl/examples/tab/ExampleViewComponent.class
plugin.xml
[tredmond@BlackHole org.protege.editor.owl.examples.tab]$
</pre>

The problem at this point is in the MANIFEST.MF file. The Bundle-Classpath line is as follows:
<pre>
Bundle-ClassPath: .
</pre>
To include the examplelib.jar in the jar file, the Bundle-Classpath line must be modified to include this library:
<pre>
Bundle-ClassPath: .,lib/examplelib.jar
</pre>
Note that using a colon or a semi-colon instead of the comma does not work. Also entering ./lib/examplib.jar does not work either. This is the osgi mechanism for making this library available to this plugin. Note that since the MANIFEST.MF file does not have an Export-Package declaration, these classes will only be visible within the plugin and will not be exported to any other plugin in the Protege 4 environmeht. This is part of the plugin isolation provided by OSGi that allows different plugins to use different libraries without conflicts.

Now the plugin works correctly and I can install the view into the Active Ontology Tab:
[[File:AnoyomyViewSuccessful.png]].

===Tab Plugins and the Viewconfig.xml File===

The other most common plugin type is the Protege tab. In order to make a Protege tab, the developer needs to generate and use a viewconfig.xml file for the project. In this section we will show how to do this. It turns out that a tab can usually be put together without writing any Java code. The steps for writing a tab plugin are
# add a declaration of the tab plugin in the plugin.xml file.
# start Protege and graphically configure the tab in question.
# save the configuration and include it with the source files for the tab.
# test by restarting Protege and running the tab with the default configuration.
These steps are described in more detail below.

==== Step 1: Declare the plugin ====

The first thing that that needs to be done is to declare the tab in the plugin.xml file.
<pre>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<?eclipse version="3.0"?>

<plugin>
<extension id="ExampleViewComponent"
point="org.protege.editor.core.application.ViewComponent">
<label value="Example View Component"/>
<class value="org.protege.editor.owl.examples.tab.ExampleViewComponent"/>
<category value="@org.protege.ontologycategory"/>
</extension>
<extension id="ExampleWorkspaceTab"
point="org.protege.editor.core.application.WorkspaceTab">
<label value="Example Tab"/>
<class value="org.protege.editor.owl.ui.OWLWorkspaceViewsTab"/>
<index value="X"/>
<editorKitId value="OWLEditorKit"/>
<defaultViewConfigFileName value="viewconfig-exampleTab.xml"/>
</extension>
</plugin>
</pre>

An important line in the above declaration of the tab is the defaultViewConfigFileName. This names a resource that the protege plugin will look for to create the default layout of the tab.

==== Step 2: Layout the views in the plugin ====

We can now compile this plugin and install it as before. Now when we run Protege 4, we will see a new tab called the "Example Tab" in the tabs menu (Window->Tabs). Enable this tab. Since we have not yet created the viewconfig-exampleTab.xml file, you will see that the tab is empty.

Now install and layout some views into this tab. In my case I made the views look like this:

[[File:AnatomyViewLayout.png]]

==== Step 3: Save a configuration file ====

Now in the Window menu select "Export Current Tab" and save the file as
<pre>
viewconfig-exampleTab.xml
</pre>
in the project directory. In my case the viewconfig-exampleTab file looked like this:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<layout>
<VSNode splits="0.5 0.5">
<CNode>
<Component label="Asserted class hierarchy">
<Property id="pluginId" value="org.protege.editor.owl.OWLAssertedClassHierarchy"/>
</Component>
</CNode>
<CNode>
<Component label="Example View Component">
<Property id="pluginId" value="org.protege.editor.owl.examples.tab.ExampleViewComponent"/>
</Component>
</CNode>
</VSNode>
</layout>
</pre>

Now before we complete this Protege session, go to the Window menu and click "Reset selected tab to default state". You will see that the tab is now empty again. Now exit Protege.

The directory tree of the project should now look like this:

[[File:AnatomyTreeDoesViewWithConfig.png]]

==== Step 4: Test the results ====

Install the plugin again. Note that the build script automatically found the viewconfig-exampleTab.xml file and put it into the plugin:
<pre>
[tredmond@BlackHole org.protege.editor.owl.examples.tab]$ jar -tf build/org.protege.editor.owl.examples.tab.jar
META-INF/
META-INF/MANIFEST.MF
lib/
org/
org/protege/
org/protege/owl/
org/protege/owl/examples/
org/protege/owl/examples/tab/
lib/examplelib.jar
org/protege/owl/examples/tab/ExampleViewComponent.class
plugin.xml
viewconfig-exampleTab.xml
[tredmond@BlackHole org.protege.editor.owl.examples.tab]$
</pre>

Run Protege and go to the Example Tab. It is empty? The reason for this is that the tab has been customized to have nothing in it from the last session. Click on the tabs menu and click on "Reset selected tab to default state". Now you will see the views that we configured in the tab before. This is now the default state for the tab and it will be what other users see when they use this plugin for the first time.

== Adding Menu Plugins ==

I have created a small menu project [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/org.protege.example.menu/trunk here] that shows how to create several different menu types. Later we will use this project as the example that drives this wiki page.

Adding a new menu to Protege 4.1 is very easy. The two things that the developer needs to accomplish are to
write the code for the menu action and to add an entry to the plugin.xml. I will take a real world example to illustrate the process. In this example, I am writing a plugin that causes Protege to display an ontology that is stored in a database format. I want to put this in the file menu of Protege 4.1 just under other items such as "New", "Open", "Open Recent" and "Open from URL".

To write the code for the menu plugin, the developer merely needs to extend ProtegeOWLAction. The three methods that the developer needs to write are initialise, dispose and actionPerformed. I think that the meaning of these three methods is pretty clear and this can be a very easy task.

Now the developer needs to add an entry to the [http://smi-protege/repos/protege/protege4/incubator/v3/org.protege.owlapi.bridge/trunk/plugin.xml plugin.xml] file. In my case the entry looks like this:
<pre>
<extension id="loadDatabase"
point="org.protege.editor.core.application.EditorKitMenuAction">
<name value="Load Database Ontology"/>
<class value="org.protege.owlapi.bridge.LoadDatabaseProjectMenu"/>
<toolTip value="Loads ontologies from a database into Protege"/>
<path value="org.protege.editor.core.application.menu.FileMenu/SlotAA-Z"/>
<editorKitId value="OWLEditorKit"/>
</extension>
</pre>
The "id" attribute of loadDatabase is simply a short identifier for the plugin that is not seen by the user. The "point" attribute indicates that the plugin being declared here is a menu plugin. The
<pre>
<class value="org.protege.owlapi.bridge.LoadDatabaseProjectMenu"/>
</pre>
line indicates the class that implements the action that this menu performs and the
<pre>
<editorKitId value="OWLEditorKit"/>
</pre>
line indicates that the menu is to be used in the context of the owl editor. The only other line in this [http://smi-protege/repos/protege/protege4/incubator/v3/org.protege.owlapi.bridge/trunk/plugin.xml plugin.xml] that is a bit mysterious is the line that says:
<pre>
<path value="org.protege.editor.core.application.menu.FileMenu/SlotAA-Z"/>
</pre>
The purpose of this line is to indicate exactly where the menu should be placed. The first part of the value,
<pre>
org.protege.editor.core.application.menu.FileMenu
</pre>
indicates that the parent of my "Load Database Ontology" menu is the file menu. The string is making a reference to the file menu declaration
<pre>
<extension
id="menu.FileMenu"
name="FileMenu"
point="org.protege.editor.core.application.EditorKitMenuAction">
<name value="File"/>
<toolTip value="File menu tool tip!"/>
<path value="/SlotA-A"/>
<editorKitId value="any"/>
</extension>
</pre>
from the [http://smi-protege/repos/protege/protege4/plugins/org.protege.editor.core.application/trunk/plugin.xml plugin.xml] file for the org.protege.editor.core.application plugin. The first part of the string
<pre>
org.protege.editor.core.application.menu.FileMenu
</pre>
is
<pre>
org.protege.editor.core.application
</pre>
which is the identifier of the plugin declaring the menu and "menu.FileMenu" is the id of the plugin from the plugin.xml file.

But now I need to explain the meaning of the SlotAA-Z portion of the path in my original menu declaration:
<pre>
<extension id="loadDatabase"
point="org.protege.editor.core.application.EditorKitMenuAction">
<name value="Load Database Ontology"/>
<class value="org.protege.owlapi.bridge.LoadDatabaseProjectMenu"/>
<toolTip value="Loads ontologies from a database into Protege"/>
<path value="org.protege.editor.core.application.menu.FileMenu/SlotAA-Z"/>
<editorKitId value="OWLEditorKit"/>
</extension>
</pre>
The SlotAA-Z string indicates exactly where the "Load Database Ontology" should appear in the File menu. This string (SlotAA-Z) is parsed as a group (Slot-AA) and an index (Z). First the group and the index are used to sort the children of the File menu. The children are sorted first by group but when two children have the same group they are then sorted by group index. In addition to this, children with the same group are grouped together in the menu.

In particular, if I track down the declarations of the "New", "Open", "Open Recent" and "Open from URL" menus I find that they all have a group identifier of SlotAA. This is why they appear in the file menu together followed by a separator bar. By specifying that my menu should have a group of SlotAA, I am telling Protege that I want my menu to be grouped with these menus. By giving my menu an index of Z I am telling Protege that I want my menu to go at the end of the list.

The algorithm used by Protege to determine the location of the plugin can be observed by turning on logging for the menu builder. This can easily be done by editing the log4j.xml in the Protege installation directory. First modify the section that says
<pre>
<appender name="console" class="org.apache.log4j.ConsoleAppender">
<param name="Threshold" value="INFO"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%m%n"/>
</layout>
</appender>
</pre>
to say
<pre>
<appender name="console" class="org.apache.log4j.ConsoleAppender">
<param name="Threshold" value="INFO"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%m%n"/>
</layout>
</appender>
</pre>
This allows the console to show debug messages. Then add the lines
<pre>
<category name="org.protege.editor.core.ui.menu">
<priority value="debug"/>
</category>
</pre>
This will cause Protege to generate somewhat verbose logs to the console (these logs also show up in a log file in ${home directory}/.Protege/logs/protege-###.log). The relevant lines for my menu plugin are as follows. First
<pre>
Parsed: [Menu: Load Database Ontology -- <SlotAA, Z>] parentId = org.protege.editor.core.application.menu.FileMenu
</pre>
indicates that Protege was able to parse the path for my menu plugin and determine that the id of the parent is
<pre>
org.protege.editor.core.application.menu.FileMenu
</pre>
the group is SlotAA and the group index is Z. Next we see the line
<pre>
[Menu: File -- <SlotA, A>] parent of [Menu: Load Database Ontology -- <SlotAA, Z>]
</pre>
which indicates that Protege was successfully able to find a declared menu with the right id to be the parent of my menu. This line also indicates that Protege successfully deciphered the group (SlotAA) and the index (Z). Finally there are the lines:
<pre>
Adding [Menu: File -- <SlotA, A>] to menu bar
Giving File the child[Menu: New... -- <SlotAA, E>]
Giving File the child[Menu: Open... -- <SlotAA, F>]
Giving File the child[Menu: Open recent -- <SlotAA, G>]
Giving File the child[Menu: Open from URL... -- <SlotAA, G>]
Giving File the child[Menu: Load Database Ontology -- <SlotAA, Z>]
Giving File the child[Menu: Save -- <SlotAB, A>]
Giving File the child[Menu: Save as... -- <SlotAB, B>]
Giving File the child[Menu: Gather ontologies... -- <SlotAB, C>]
Giving File the child[Menu: Export inferred axioms as ontology... -- <SlotAB, D>]
Giving File the child[Menu: Ontology libraries... -- <SlotD, A>]
Giving File the child[Menu: Loaded ontology sources... -- <SlotD, B>]
Giving File the child[Menu: Check for plugins... -- <SlotP, A>]
Giving File the child[Menu: Close -- <SlotY, M>]
</pre>
that indicate that the File menu was successfully populated.

== Advanced Topics ==
=== Adding New Plugin Types ===

'''Work in Progress'''

One of the advantages of using the OSGi/Eclipse framework is that it naturally allows developers to
define their own plugin types.. For example, the SWRL tab, being written by
Martin O'Connor, delegates the work of executing the SWRL rules to a rule engine plugin. It is anticipated that
there will be two rule engine plugins that are are compatible with the SWRL tab. One of these plugins will
be based on the Jess rule engine and the other plugin will be based on the DROOLS rule engine.

We will illustrate how this is done with two Protege bundles. The sources for these bundles can be found
<pre>
http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer
</pre>
and
<pre>
http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/producer
</pre>
Both bundles can be quickly installed through the included [[ConfiguringAntBuildFiles|ant scripts]].

The consumer bundle behaves as follows. It adds a menu item to a running Protege environment. This menu is found at the bottom of the edit menu. When the user clicks on this menu item, the consumer bundle performs the following actions:
# it looks for all custom_extension_point plugins in the running Protege environment,
# it instantiates each plugin found and finally
# it calls the doSomething() method on that plugin instance.

This behavior is provided through the interaction of four components:
* the '''consumer code''' that is responsible for looping through a set of plugins and invoking them.
* the '''plugin loader''' that is responsible for calculating and returning a set of plugins that match a specifiction.
* the '''plugin''' that is a java encoding of data encoded in plugin.xml files provided by the bundles.
* the '''plugin instance''' that is an instantiation of a plugin that does the actual work of the plugin.

==== The Plugin Consumer ====

The Plugin consumer essentially uses the plugin loader (described below) to loop through a series of plugins and instantiate and invoke them.
The code that does this work can be found in the [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/src/org/protege/example/extension/point/MyPluginConsumer.java MyPluginConsumer] class and looks like the following:
<pre>
public void actionPerformed(ActionEvent e) {
MyPluginLoader loader = new MyPluginLoader(getOWLModelManager());
for (MyPlugin plugin : loader.getPlugins()) {
try {
MyPluginInstance i = plugin.newInstance();
i.doSomething();
}
catch (Exception ex) {
ProtegeApplication.getErrorLog().logError(ex);
}
}
}
</pre>
This is a typical example of how a plugin consumer will work. It uses a plugin loader to find a set of plugins that are then instantiated (plugin.newInstance()) and then invoked (i.doSomething()). For the most part, the plugin consumer does not have to worry too much about the details of the Protege plugin infrastructure. The logic of the Plugin consumer is defined by the task at hand.

==== The Plugin Loader ====

The [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/src/org/protege/example/extension/point/MyPluginLoader.java plugin loader] is responsible for searching for plugins of the custom_extension_point type. The plugin loader extends the AbstractPluginLoader class which handles most of the logic of creating and finding plugins. Minimally, all the developer needs to do to implement the plugin loader is to implement a constructor and a create instance method. The constructor looks like this:
<pre>
public MyPluginLoader(OWLModelManager owlModelManager) {
super(MyPlugin.CONSUMER_ID, MyPlugin.ID);
this.owlModelManager = owlModelManager;
}
</pre>
and this is typical. The significance of the two arguments to the super constructor will be explained when I describe the Plugin implementation. Essentially they define which type of plugin is being searched for by this loader. In addition, the constructor for this plugin loader takes an owlModelManager argument so that he can pass this argument to the constructor for the plugins. The createInstance method then is responsible for constructing the plugin:
<pre>
protected MyPlugin createInstance(IExtension extension) {
return new MyPlugin(owlModelManager, extension);
}
</pre>
In addition there is a getExtensionMatcher method that can be used to restrict the set of plugins that are returned by this plugin loader. Generally it is not necessary to implement the getExtensionMatcher interface.

==== The Plugin ====

Essentially the [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/src/org/protege/example/extension/point/MyPlugin.java plugin] is a POJO representing a declaration of a plugin in a plugin.xml file. To understand this we need to look at the two declarations in two separate plugin.xml files. The first declaration is found in the bundle for the consumer plugin. This declaration represents a request for a particular type of service. In our case the [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/plugin.xml declaration] looks like this:
<pre>
<extension-point id="custom_extension_point"
name="Custom Extension Point"
schema="schema/custom_extension_point.exsd"/>
</pre>

This declaration defines
* the identifier of the plugin type, custom_extension_point, which is the name by which plugin developers refer to this plugin type, This string corresponds to the MyPlugin.ID that we passed to the AbstractPluginLoader constructor above. Note that it is possible for different bundles to declare an extension point
* the user friendly name of the plugin type and
* a pointer to the xml schema for the plugin type.
I believe that the last item, [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/schema/custom_extension_point.exsd the schema], is not mandatory but it is extremely useful for developers and it is created naturally when plugins are developed using the eclipse IDE.

The plugin producer provided a [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/producer/plugin.xml declaration] for his extension that matches the extension point declaration above. In our example the extension declaration looks like this:
<pre>
<extension id="SimpleImplementation"
point="org.protege.example.extension.point.custom_extension_point">
<class value="org.protege.example.extension.PluginImplementation"/>
<type value="Logger Type"/>
</extension>
</pre>

The plugin class, [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/src/org/protege/example/extension/point/MyPlugin.java MyPlugin], extends the AbstractProtegePlugin class. The AbstractProtegePlugin class provides many utilities that make it easy to write the plugin class. In particular, to get the "type" field the MyPlugin class provides an accessor:
<pre>
/**
* gets the declared type field for the plugin
*/
public String getType() {
return getPluginProperty(TYPE_PARAM, "null type");
}
</pre>

In addition, the AbstractProtegePlugin class does the tricky aspects of instantiating the plugin leaving only the task of initializing the instantiated plugin to the MyPlugin class:
<pre>
/**
* Creates an instance of the plugin. It is expected that
* this instance will be "setup", but the instance's
* initialise method will not have been called in the instantiation
* process.
*/
public MyPluginInstance newInstance() throws ClassNotFoundException, IllegalAccessException,
InstantiationException {
MyPluginInstance mpi = super.newInstance();
mpi.setup(modelManager, getType());
return mpi;
}
</pre>

==== The Plugin Instance ====

The [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/src/org/protege/example/extension/point/api/MyPluginInstance.java plugin instance class] is responsible for performing whatever task it is that the plugin is supposed to perform. In our case the plugin instance will implement the doSomething() method. This class must implement the ProtegePluginInstance interface though it is not clear that this is really needed anymore. The ProtegePluginInstance interface has only one method, initialise(), but many plugins, such as the one in this example, have their own initailization methods that are called by the Plugin Loader.

=== Frames, Frame Sections, and Rows ===

'''In Progress'''

It is not clear that this needs to be here but this is an extremely central Protege concept. In general plugin developers will not need to build custom Frame lists and can simply use the top level OWL Frame List concepts.

Most of the discussion will focus on a smaller and smaller section of the the following Protege 4.1 screen. This diagram shows the standard Protege 4.1 classes tab as it displays some information about the selected class which is the Country class in the pizza ontology.

[[File:FrameInClassesTab.png||A Classes Tab showing a standard frame in the right bottom]]

==== FrameLists and Frames ====

The diagram below shows a FrameList showing a description of the Country class. The OWLFrameList is the swing object that is responsible for displaying some object called the root object for the OWLFrameList. In this case, the root object for this frame list is the Country OWL class. Frequently the root object of the for a frame list is an OWL entity but this is not required. The constructor for the OWLFrameList object takes an OWLFrame object which manages the content model of the OWLFrameList. The associated OWLFrame object also has a root object and in this case the root object is the Country class.

While it may not be visually immediately apparent, the information being displayed is actually a rendition of a list of axioms. Thus for instance, the class expression represented in the section underneath ''Equivalent Classes'' represents the axiom
<pre>
Country SubClassOf DomainConcept and {America, England, France, Germany, Italy}.
</pre>
Similarly the first individual displayed under ''Members'' represents the axiom
<pre>
America Type Country.
</pre>

The fact that these are not displayed simply as the associated axioms is an key part of the purpose of the OWLFrameList. The task of the OWLFrameList below is to describe the Country class. For a user it makes sense that in the Members section of that OWLFrameList he would see a list of the individuals in that class. It would make less sense to the user if a set of axioms was displayed there.

[[File:FrameList.png||Frame List]]

==== Frame Sections ====

OWLFrames are grouped into a series of sections each of which shows a particular type of axioms. In the diagram below we have a frame section that is rendering a list of class assertion axioms.

[[File:FrameSection.png|Frame Section]]

==== Frame Section Rows ====

[[File:FrameSectionRow.png|Frame Section]]

[[File:FrameSectionRowAlt.png|Frame Section]]

== Glossary ==

There are some terms that come up naturally in the discussion of Protege 4 plugin development that require a bit of explanation. The Protege 4 plugin mechanism has three layers and the terms used to describe plugins is slightly different at each of these layers:
* '''Extension Point''' is the eclipse term for what Protege folk often call a plugin.
* '''[http://www.osgi.org/Main/HomePage OSGi]''' is the bottom layer of the Protege plugin architecture. It is a powerful industry standard framework which provides modularity and services beyond that provided by the Java specifications. In OSGi, the term OSGi bundle is used to represent a self-contained unit of code that can be introduced into the OSGi framework and which will import and export classes and resources in a controlled way.
* '''An OSGi Bundle''' is collection of software grouped into a single jar file. When this software runs in the OSGi environment, it runs in a protected space where it can define exactly what java classes from the surrounding environment are needed and what java classes are incompatible with its operation. Bundles have names, version numbers, developer contact information and activation entry points.
* '''A Plugin''' is a declared service that implements some functionality of use to the Protege platform. The Protege Plugin mechanism is based on the Eclipse plugin mechanism where plugins are declared in a file called plugin.xml.
* '''[http://wiki.eclipse.org/index.php/Rich_Client_Platform The Eclipse Rich Client Platform]''' is an environment built on top of OSGi which provides additional features to ease the building of a "Rich" client. Protege 4 only uses some of the features of this rich client platform. In particular, Protege 4 does not use SWT and many of the graphical related capabilities. But Protege 4 does use the declarative plugin capabilities provided by eclipse. It is here that some of the power of the OSGi platform becomes manifest, because we have been able to use only those bundles from the eclipse Rich Client platform that we need. In this setting, OSGi bundles created according to certain conventions become Eclipse Plugins.
* '''The Protege 4 Plugin layer''' provides some additional convenience methods over the Eclipse Plugin framework. Certain eclipse plugins that extend Protege 4 capabilities are called Protege 4 plugins.

PluginTypes

2011-04-04T20:11:43Z

Swartik: Fixed reference to wrong class

<div class="orangeBox">
Protege 4 Plugin types 
This page summarises the default types of plugin that can be implemented for Protege 4.
</div> 

Back to [[Protege4DevDocs]]

__TOC__

== Existing Plugin Types ==

This is a snapshot of the existing types of plugins that can be added to Protege4.0.
The current set of plugin types can always be found in the code by looking at the plugin.xml file for the core.application and the owl bundles.
Just look for the extension-points in these files – these point to the schemas that are used for describing each type of plugin.
Plenty of examples can be found in the plugin.xml files themselves.

=== Core Plugins ===

==== ViewComponent ====

<hr>

The most common plugin type – implements views (the building blocks of workspace tabs).

Implementation of this plugin is demonstrated in the [http://www.co-ode.org/downloads/protege-x/plugin-code-example.php '''TabbedHierarchyView''' example].

There are many abstract implementations of this plugin to use as a base, for example each entity type (Class, Property and Individual) has an abstract base.

* Implement: '''org.protege.editor.core.ui.view.ViewComponent'''
* Example: '''org.protege.editor.owl.ui.clshierarchy.ToldOWLClassHierarchyViewComponent'''

<hr>

==== EditorKitMenuAction ====

Create an entry in a [[#menu.window|menu]] (and supply a mnemonic) and its associated action.

* Implement: '''org.protege.editor.core.ui.action.ProtegeAction'''
* Example: '''org.protege.editor.owl.ui.action.RemoveAllDisjointAxiomsAction'''

<extension id="menu.RemoveAllDisjointAxioms"
point="org.protege.editor.core.application.EditorKitMenuAction">
<name value="Remove all disjoint axioms..."/>
<toolTip value="Removes all of the disjoint axioms."/>
<class value="org.protege.editor.owl.ui.action.RemoveAllDisjointAxiomsAction"/>
<path value="org.protege.editor.core.application.menu.EditMenu/SlotM-H"/>
<editorKitId value="OWLEditorKit"/>
</extension>

''id'' = an ID for this plugin

''point'' = the type of plugin

''name'' = the name as it appears in the menu

''toolTip'' = a description of the action shown in a tooltip

''class'' = the implementing class (full package name)

''path'' = the relative position in the menu (section pos, subsection pos)

''editorKitId'' = the type of editor kit this plugin works with

===== Open URL in browser action =====

An addition has been made to the EditorKitMenuAction that allows a menu item that opens a specified page in a web browser.
This has been used to implement help items, but could be useful for lots of different reasons.

The best thing is '''this requires no coding whatsoever'''.
* ''url'' should be specified in the action descriptor instead of ''class''.
* The value should be the full URL of the webpage you wish to open.

Specifying a ''class'' element will cause the ''url'' to be ignored.

<extension id="menu.PluginsMenuItem" point="org.protege.editor.core.application.EditorKitMenuAction">
<name value="Protege-OWL plugins"/>
<toolTip value="Protege 4.0 OWL plugins"/>
<url value="http://protegewiki.stanford.edu/index.php/Protege-OWL_4.0"/>
<path value="org.protege.editor.core.application.menu.HelpMenu/SlotF-B"/>
<editorKitId value="any"/>
</extension>

<hr>

==== preferencespanel ====

Create a panel that will be loaded into the preferences dialog.

This should be for controlling a particular aspect of Protege4.0 in general or can be used as part of a bundle to control the behaviour of other plugins.

Preferences should be used to persist over sessions.

The '''applyChanges()''' method should be used to update the appropriate values in Protege's '''PreferencesManager'''.

* Implement: '''org.protege.editor.owl.ui.preferences.OWLPreferencesPanel'''
* Example: '''org.protege.editor.owl.ui.tree.OWLTreePreferencesPanel'''

<hr>

==== WorkspaceTab ====

Unless your tab requires some special handling for events or non-standard layout you will probably not need to implement a class for this plugin.
You can just point the plugin.xml configuration to WorkspaceViewsTab (or OWLWorkspaceViewsTab) implementation and the rest of the plugin description
should be enough to customise the tab – i.e., give it a name and point to a default layout (see below).

* Implement: '''org.protege.editor.core.ui.workspace.WorkspaceTab'''
* Example: '''org.protege.editor.owl.ui.OWLClassesTab'''

===== Creating a tabbed view layout =====
* First, create or decide on which views you wish to have on your tab - make sure these are all implemented
* Open Protege 4.0
* Create a new tab ('''Window | Create new tab...''')
* Select your new tab and start customising it by adding views (see [[Protege4GettingStarted#Reconfigure_the_User_Interface|Reconfigure the user interface]])
* Select '''Window | Save current layout''' or quit Protege
* Find the new layout in the Protege installation directory ''Data/ViewConfigurations/viewconfig-custom-YOUR_TAB_NAME.xml''
* Rename this without the ''custom'' and copy to somewhere in your plugin source like a ''resources/'' folder
* Make sure this folder is on your classpath and that it gets added to you compiler output path
* Add the layout ('''defaultViewConfigFileName''') to the plugin description in plugin.xml

<extension id="OWLOntologyTab"
point="org.protege.editor.core.application.WorkspaceTab">
<label value="Active Ontology"/>
<class value="org.protege.editor.core.ui.workspace.WorkspaceViewsTab"/>
<defaultViewConfigFileName value="viewconfig-ontologytab.xml"/>
<index value="A"/>
<editorKitId value="OWLEditorKit"/>
</extension>

<hr>

==== EditorKitFactory ====

An EditorKit is the access point for a particular type of model (or ontology) and a GUI to handle that model.

Currently, there is just one implementation - the OWLEditorKit

Implement this type of plugin if you require a new type of model to be supported (eg a Frames-based model).

There is obviously considerable work needed to implement a new editor kit (along with its model manager and workspace).

* Implement: '''org.protege.editor.core.editorkit.EditorKitFactory'''
* Example: '''org.protege.editor.owl.OWLEditorKitFactory'''

<hr>

==== menu.window ====

Create a new menu into which [[#EditorKitMenuAction|EditorKitMenuActions]] can be added.
No need for any implementation. The plugin description gives enough detail for full customisation.

<extension id="menu.EditMenu"
point="org.protege.editor.core.application.EditorKitMenuAction">
<name value="Edit"/>
<toolTip value=""/>
<path value="/SlotB-A"/>
<editorKitId value="any"/>
</extension>

<hr>

==== OntologyRepositoryFactory ====

Create a source from which ontologies can be loaded. This plugin will create an entry on the welcome screen that allows the user to get ontologies from any number of places (a repository, a web service etc).

* Implement '''org.protege.editor.core.OntologyRepositoryFactory'''
* Example '''org.protege.editor.owl.model.repository.TONESRepositoryFactory'''

<extension id="TONESRepository" point="org.protege.editor.core.application.OntologyRepositoryFactory">
<class value="org.protege.editor.owl.model.repository.TONESRepositoryFactory"/>
</extension>

<hr>

==== EditorKitHook ====

Perform some actions when an editing session is started.
The initialise() method gets called when the EditorKit has been initialised.
This can be used to perform some special configuration or replace default behaviour.

* Implement '''org.protege.editor.core.editorkit.plugin.EditorKitHook''' (or org.protege.editor.owl.model.OWLEditorKitHook)
* Extension point '''org.protege.editor.core.application.EditorKitHook'''

<hr>

==== ToolBarAction ====

Not currently used - will be implemented to allow view actions to be customised

<hr>

==== ViewAction ====

Not currently used - will be implemented to allow view actions to be customised

=== OWL Plugins ===

==== inference.reasonerfactory ====

<hr>

==== ui.renderer.entitycolorprovider ====

<hr>

==== model.libraryfactory ====

<hr>

==== moveaxiomskit ====

Methods of selecting axioms for copying, moving or deleting (see [[P4MoveAxioms|Refactor | Copy/move/delete axioms]]) are pluggable.

You can choose to implement pages to add to the wizard to control how your kit works.

* Implement: '''org.protege.editor.owl.ui.ontology.wizard.move.MoveAxiomsKit'''
* Example: '''org.protege.editor.owl.ui.ontology.wizard.move.byreference.MoveAxiomsByReferenceKit'''

<extension id="MoveAxiomsByReference"
point="org.protege.editor.owl.moveaxiomskit">
<name value="Axioms by reference (select entities from the ontology)" />
<class value="org.protege.editor.owl.ui.ontology.wizard.move.byreference.MoveAxiomsByReferenceKit" />
</extension>

<hr>

==== ui.editor.description (from build 109) ====

[[Image:Class-expression-editor.png|400px|right]]

When adding/editing superclasses, equivalent classes, property domains, individual types etc a class description editor is brought up.

Each tab on the editor is a plugin capable of creating/editing (possibly a subset) OWL class descriptions

* Implement: '''org.protege.editor.owl.ui.editor.AbstractOWLDescriptionEditor'''
* Example: '''org.protege.editor.owl.ui.editor.OWLClassSelectorWrapper'''

<extension id="OWLClassSelectorWrapper"
point="org.protege.editor.owl.ui.editor.description">
<label value="Asserted class hierarchy"/>
<class value="org.protege.editor.owl.ui.editor.OWLClassSelectorWrapper"/>
<index value="B"/>
</extension>

Protege4DevDocs

2011-03-25T15:33:05Z

Swartik: Spelling correction

<div class="orangeBox">
Protege 4 Developer Documentation 
Pointers for developers of plugins and understanding the core APIs of Protege 4.
</div> 

__TOC__

== Guidelines ==

Protege 4.1 will be compatible with both Java 5 and Java 6. Unfortunately we need to continue supporting Java 5 because of problems with Java on the older Apple platforms (the PowerPC and 32 bit Macs). If you are writing a plugin and you want to be available on all OS X platforms, then you must use Java 5. Otherwise Java 6 works as long as you understand that you are excluding a subset of the Apple platforms.

'''Please consider writing any P4 code as a plugin'''. 
If you cannot do this for various reasons, please let us
know as we may be able to improve the core design in order to support you. 
Protege 4.0 has been written specifically to be modular. It uses the [http://www.osgi.org/About/Technology '''OSGi framework'''] as a plugin infrastructure.

'''Please share.''' 
It is surprising how many people have written plugins for P4 that we just don't hear about. 
If you wish to publish to the community, please see our notes on [[Protege4Contributing#Code_submissions|code contributions]].

== Using an Integrated Development Environment ==

=== Protege 4 OWL editor in Eclipse or IntelliJ ===

* [[CompileProtege4InEclipseFromSvn|Setting up eclipse with Protege 4.1]] '''(Recommended for Protege 4.1)''' This page gives directions for compiling and running Protege 4.1 using Eclipse's plugin development framework. It includes the OS X workaround as well.
* [[CompileProtege4InIntelliJFromSvn|Setting up IntelliJ IDEA with Protege 4.1]] '''(Recommended for Protege 4.1)''' This page gives directions for compiling and running Protege 4.1 using IDEA's Osmorc plug-in.

=== Protege 4 OWL editor in a Other IDEs ===

There is no longer a page that describes how to set up an IDE other than eclipse or IntelliJ. We welcome contributions from the community for directions on how to set up other developement environments. In particular NetBeans seems to have a following and it would be useful to have a page describing how to set up for that IDE.
For an experienced Java developer, the [[#Building_Protege4.1_from_scratch_using_ant|ant build steps]] will probably provide enough hints to put together an arbitrary ide environment for Protege 4.1.

== Writing A Plugin ==

The following links are focussed on the problems of writing a plugin and are not focused on how your build environment should be configured. For information about configuring your build environment go to [[Protege4DevDocs#Using_an_Integrated_Development_Environment|Using an IDE]].

[[PluginAnatomy|This page]] gives a quick start to writing a plugin for Protege 4. It starts with a guide to writing the empty (trivial) plugin in five minutes. Then it describes how some additional content can be added to the plugin.

=== Additional Information ===

In addition to this there are some other useful sources on plugin development:
* [[PluginTypes|plugin types]] provides a list of plugin types that you can implement in Protege 4.
* Once you have written a plugin you want people to use it. Some very simple steps allow you to advertise your plugin and [[EnablePluginAutoUpdate|enable auto-update]].
* A short guide to [http://www.co-ode.org/downloads/protege-x/plugin-code-example.php writing a plug-in] to show the class hierarchy. This page is not supported by the Protege team and may indeed not be actively updated any more. It has some very useful information but will quite likely slowly go out of date.

== Misc ==

=== Protege APIs ===

Here is a summary of the main parts of the [[P4APIOverview|Protege 4 API]] for gaining access to the model and various utilities.

Also see the [http://protege.stanford.edu/protege/4.0/docs/api/ javadoc for Protege 4.0 code].

=== UI components ===

The Protege core and the OWL editor kit both provide a large number of [[P4UiComponentSummary|reuseable components]] and utilities for generating user interfaces for ontologies.

=== Updating to Protege 4.1 ===

A short [[P4_1PortingGuide|guide]] to migrating plugins from Protege4.0 to Protege4.1 (in progress).

=== Building Protege4.1 from scratch using ant ===

The Protege 4.1 build process has been refactored since Protege 4.0. This means that the locations of the various Protege 4.1 plugins is different than the corresponding locations in Protege 4.0. There are several advantages of the new scheme:
* the build files are independent so that changes to one plugin can be propagated to the distribution by compiling just the plugin rather than the redoing an entire Protege build.
* the build files autodetect the format of the protege distribution. This means that a single build file for the os x application bundle (Protege.app) and a felix based distribution.
* the new build process is much simpler allowing us to more easily update the various components.
Although many readers of this section will not be planning on doing an ant build, these directions clarify the location of the various Protege 4.1 plugins in svn.

A very quick build (40 seconds) can be done with the following steps:
# ''svn checkout http://smi-protege.stanford.edu/repos/protege/protege4/misc/society/protege4/trunk protege4''
# cd protege4
# ant install
# cd build/Protege
# run protege (e.g. sh run.sh)

The manual steps are as follows.
First you must set the PROTEGE_HOME environment variable which is described [[ConfiguringAntBuildFiles|here]]. Then you can build Protege 4.1 by following the following steps.
# ''svn checkout http://smi-protege.stanford.edu/repos/protege/protege4/protege-base/trunk protege-base''
# ''cd protege-base'' and ''ant install'' and ''cd ..''. '''Warning:''' this step deletes the existing contents of ${PROTEGE_HOME}.
# ''svn checkout http://smi-protege.stanford.edu/repos/protege/protege4/plugins/org.protege.common/trunk org.protege.common''
# ''cd org.protege.common'' and ''ant install' and ''cd ..'''
# ''svn checkout http://smi-protege.stanford.edu/repos/protege/protege4/plugins/org.protege.jaxb/trunk org.protege.jaxb''
# ''cd org.protege.jaxb'' and ''ant install'' and ''cd ..''
# ''svn checkout http://smi-protege.stanford.edu/repos/protege/protege4/plugins/org.protege.editor.core.application/trunk org.protege.editor.core.application''
# ''cd org.protege.editor.core.application'' and ''ant install'' and ''cd ..''
# ''svn checkout http://smi-protege.stanford.edu/repos/protege/protege4/plugins/org.semanticweb.owl.owlapi/trunk org.semanticweb.owl.owlapi''
# ''cd org.semanticweb.owl.owlapi'' and ''ant install'' and ''cd ..''
# ''svn checkout http://smi-protege.stanford.edu/repos/protege/protege4/plugins/org.protege.editor.owl/trunk org.protege.editor.owl''
# ''cd org.protege.editor.owl'' and ''ant install'' and ''cd ..''
This will give a minimal installation and other plugins can be added as desired. In addition, protege-base comes with a run target that can be used to run Protege and a debug target that can be used to debug Protege using java's remote debugging support. Source plugins can be created by adding ''ant add.source'' before the ''ant install'' step. A full run on an extremely slow machine is shown [[Protege41FullBuild|here]].

===Embedded OSGi===

For people embedding Protege 4 services inside a non-OSGi based applications [[Embedding OSGi|here]] is a short example showing how this can work.

===Database Backends===

There are now two database backends for the OWL API. Very soon we expect to have a Protege plugin that enables both backend mechanisms. We have put together a [[Loading A DatabaseProject|document]] describing how both database backends can be used with the owl api.

===Client-Server===

You will only find extreme bleeding edge stuff here. I am writing a new [[Protege 4 Development Environment|page]] describing how to setup a development environment for the client server.

== Troubleshooting ==
* [[SolvingClassLoaderProblems|Troubleshooting class loader issues]]
* [[DealingWithJava5CompilerIssues|Troubleshooting and fixing problems with the Java 5 compiler]]

PluginAnatomy

2011-03-09T21:14:15Z

Swartik: Typo: Further correction to last change: the Java class hierarchy shouldn't contain "editor".

== Introduction ==

The purpose of this web page is to describe some of the key ingredients of a plugin. The page will be directed by
the quick development of a plugin and can indeed be used as a quick start guide. In order to focus attention on the core plugin
concepts we will use the lowest common denominator of Java development tools and this tutorial will not use a Java IDE.
We will assume that the
reader has an understanding of Java development and knows how to follow along in his favorite IDE. For more information about
how to work with protege 4 in an IDE I will direct the reader to [[Protege4DevDocs#Using_an_Integrated_Development_Environment|this page]]. It is possible for an experienced developer to skip the ant scripts simply follow along in an IDE but we would still recommend a build file for the final version.

==The vacuous plugin in five minutes==

I just did it in just over [[Protege4 Plugin In Four Minutes|four minutes]].

The simplest (trivial) plugin can be built from sources in the following layout:<pre>
build.xml
META-INF
MANIFEST.MF
lib
resources
src
</pre> As we will see - even without any java sources - this is a sufficient basis for building a plugin that is recognized by Protege 4. There are only two files in this source tree - the build.xml file and the MANIFEST.MF. These files can be quickly put together from templates.

===Build.xml===

The template for the build.xml file can be downloaded from [http://smi-protege.stanford.edu/repos/protege/protege4/protege-base/trunk/etc/template-plugin-build.xml here]. Only two things need to be changed in this build file. They can be found by searching for the string "CHANGE ME" in the file. The first thing to change is the name of the project. I will call the project the plugin tutoiral project:<pre>
<project name = "plugin tutorial" default = "install" basedir = ".">
</pre>
The next setting that must almost always be changed is the name of the plugin. In this case, the build.xml already has the right name for the plugin but this is the only plugin for which this will be true:<pre>
<property name = "plugin" value = "org.protege.owl.examples.tab"/>
</pre>
With these adjustments the build.xml file is ready.

===MANIFEST.MF===

The template for the MANIFEST.MF file can be downloaded from [http://smi-protege.stanford.edu/repos/protege/protege4/protege-base/trunk/etc/template-manifest.mf here]. Only five things need to be changed in this file to make it useable and two are optional. These can be found by searching for the string "CHANGE ME" in the file. The first change is to set the display name for the plugin:<pre>
Bundle-Name: Tutorial Plugin
</pre> This is the name that is seen when Protege 4 starts up and in several plugin configuration screens.
The seccond thing to change is the symbolic name of the plugin. The usual default is to uses the same name as the plugin name in the build.xml file:<pre>
Bundle-SymbolicName: org.protege.owl.examples.tab;singleton:=true
</pre>
Note the "singleton:=true" line - this is important since most Protege 4 plugins will only work if they are instantiated exactly once. The next things to change are the bundle description, the vendor and the documentation url:<pre>
Bundle-Description: A simple plugin for a plugin development tutorial
Bundle-Vendor: The Protege Development Team
Bundle-DocURL: www.perhaps.i.donthaveoneyet.com
</pre>
Actually the vendor and the docurl are optional and can be deleted. The MANIFEST.MF file is now ready.

===Compile and Run===

Before we can start, we must set the PROTEGE_HOME environment variable to point to a Protege 4 distribution. [[ConfiguringAntBuildFiles|This page]] has directions on how to do this in different operating systems but for now I will assume that we are on a unix (or os x) system. In that case, the system variable can be set with a simple command <pre>
export PROTEGE_HOME=/Users/tredmond/Desktop/Protege_4.0_beta
</pre>
If for any reason, using a environment variable is difficult, one can also achieve the same effect by creating a local.properties file with the single line
<pre>
protege.home=/Users/tredmond/Desktop/Protege_4.0_beta
</pre>

This vacuous plugin is now ready to compile and run. Assuming that the PROTEGE_HOME environment variable is set correctly, this plugin can be compiled with the simple command <pre>
ant install
</pre>
The full text of the build session is as follows:<pre>
[tredmond@Andromeda org.protege.editor.owl.examples.tab]$ ant install
Buildfile: build.xml

init:
[mkdir] Created dir: /private/tmp/org.protege.editor.owl.examples.tab/build
[mkdir] Created dir: /private/tmp/org.protege.editor.owl.examples.tab/build/classes
[mkdir] Created dir: /private/tmp/org.protege.editor.owl.examples.tab/build/classes/lib
[mkdir] Created dir: /private/tmp/org.protege.editor.owl.examples.tab/build/lib

checkProtegeLibs:
[echo] Using Protege Home = /Andromeda/Users/tredmond/dev/workspaces/protege4/owleditor/build/dist/equinox to find protege jars

checkProtegeLibsAndReport:

buildlibs:
[unjar] Expanding: /Andromeda/Users/tredmond/dev/workspaces/protege4/owleditor/build/dist/equinox/bundles/org.protege.common.jar into /private/tmp/org.protege.editor.owl.examples.tab/build

compile:

build.manifest:
[copy] Copying 1 file to /private/tmp/org.protege.editor.owl.examples.tab/build

copy.resources:
[mkdir] Created dir: /private/tmp/org.protege.editor.owl.examples.tab/build/classes/META-INF
[copy] Copying 1 file to /private/tmp/org.protege.editor.owl.examples.tab/build/classes/META-INF

jar:
[jar] Building jar: /private/tmp/org.protege.editor.owl.examples.tab/build/org.protege.owl.examples.tab.jar

install:
[delete] Deleting directory /Andromeda/Users/tredmond/dev/workspaces/protege4/owleditor/build/dist/equinox/configuration/org.eclipse.core.runtime
[delete] Deleting directory /Andromeda/Users/tredmond/dev/workspaces/protege4/owleditor/build/dist/equinox/configuration/org.eclipse.osgi
[copy] Copying 1 file to /Andromeda/Users/tredmond/dev/workspaces/protege4/owleditor/build/dist/equinox/plugins

BUILD SUCCESSFUL
Total time: 2 seconds
[tredmond@Andromeda org.protege.editor.owl.examples.tab]$
</pre>
If the PROTEGE_HOME environment variable is not set correctly the user will instead see the following:<pre>
BUILD FAILED
/private/tmp/org.protege.editor.owl.examples.tab/build.xml:74: missing protege libraries
</pre>

We can now look at what the build has done by exploring the project directory tree.
[[File:AnatomyBuildTreeAnnotated.png]]

We see the following elements:
* '''The Class Tree''' is (approximately) a flattened view of the plugin (the jar file). Generally this largely consists of the .class files that have been compiled from the java. But since we have not written any java yet this is not found. In addition, this will contain resources needed by the plugin and libraries that the plugin needs but which cannot be found in other Protege plugins.
* '''The Generated Libraries''' which are extracted from Protege plugins. This is needed because of a difference between how Java and OSGi get resources out of Jar files. OSGi allows a [[PluginAnatomy#Some_Nomenclature|bundle]] (which is a implemented as a jar file) to contain other jar files. If the bundle classpath is configured correctly, OSGi will load classes from those jars in jars. But Java does not have this capability. So the build script extracts the jar files out of the OSGi bundles that will be needed to compile the bundle. Note that these jar files are not copied to the class tree because the Protege 4/OSGi environment will make the classes and resources of these jar files available.
* '''The Protege 4 Plugin''' this is the final artifact of the build process. Because we have run "ant install" it has also been installed in the Protege distribution.

If the developer is still with me then he is now ready to run the plugin. Go to the Protege distribution (the one pointed to by the PROTEGE_HOME environment variable) and run it. We are particularly interested in the console output because this is going to be the only indication that this plugin is recognized at all. The console output should look like this:<pre>
Starting Protege 4 OWL Editor (Version 4.0.111)
Platform:
Java: JVM 1.5.0_16-b06-284 Memory: 207M
Language: en, Country: US
Framework: Eclipse (1.4.0)
OS: MacOSX (10.5.6)
Processor: ppc
Installed plugin Pellet Reasoner
Installed plugin DL Query Tab
Installed plugin Owlviz Plug-in
Installed plugin owleditor
Installed plugin Tutorial Plugin
Installed plugin The OWL API
Installed plugin Factplusplus Plug-in
Tutorial Plugin Plugin has no plugin.xml resource
</pre>
In this output we see that the Tutorial Plugin has been recognized and installed. In addition there is a informational message that the plugin.xml file has not been found. This is almost always indicates a problem because most Protege 4 plugins depend on a plugin.xml resource. We will describe how the plugin.xml file is generated in the next sections.

== Writing View and Tab Plugins ==

The previous plugin added no functionality to Protege 4. We are now going to describe how to remedy this situtaion. So far we have not missed the Java IDE but it is now when we start writing a bit of Java code that the Java IDE would really shine. But to illustrate the main concepts, we will continue to show how to build the plugin without any development environment other than that provided by the core Java tools.

===Adding a View Plugin to the Plugin.xml file===

Recall that previously when we ran our plugin, Protege 4 complained that there was no plugin.xml file. The plugin.xml file contains a declaration of the ways in which the plugin will extend the Protege 4 capabilities and (more advanced) the ways in which the plugin capabilities can be extended by other plugins. We will start by adding a declaration that this plugin will implement a Protege View.

So first we will give a definition of a Protege view. The purpose of a Protege view is to provide a view of some aspect of an ontology. In the Protege interface, a Protege view is easily recognized. It has a clearly defined border. At the top of a Protege view is a title bar and a collection of buttons allowing the user to
* split the protege view into two copies of the same view one above the other,
* split the protege view into two copies of the same view one beside the other,
* float the view above the Protege client so that it is visible in any context,
* close the view removing it from the tab that contains it.
An example of a typical Protege view is shown below.
[[File:AnatomyView.png]]

In order to declare our intent that this plugin implement a Protege view, we add the following pluxin.xml file to the root of the project tree:
<pre>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<?eclipse version="3.0"?>

<plugin>
<extension id="ExampleViewComponent"
point="org.protege.editor.core.application.ViewComponent">
<label value="Example View Component"/>
<class value="org.protege.owl.examples.tab.ExampleViewComponent"/>
<category value="@org.protege.ontologycategory"/>
</extension>
</plugin>
</pre>

This plugin.xml file states that this plugin is making a single extension to the Protege 4 capabilities. We will cover the meaning of the parts of this extension declaration line by line. The first line defines the id of the extension. This particular extension is called the ExampleViewComponent. The second decleration,
<pre>
point="org.protege.editor.core.application.ViewComponent",
</pre>
states what the extension is trying to do. This extension is attempting to implement the functionality represented by the extension point with the name
<pre>
org.protege.editor.core.application.ViewComponent.
</pre>
The label declaration tells Protege what to put in the title bar of the view. The class declaration indicates which class implements the functionality needed by this view. We will go into the implementation of that class shortly. Finally the category declaration tells Protege which menu under the View menu should contain this view.

A very simple view can be written by extending the class AbstractOWLViewComponent and implementing the methods initialiseOWLView and disposeOWLView. A very simple such implementation can be found
[http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/plugin/tags/protege.4.0-2009-12-02/org.protege.editor.owl.examples.tab/src/org/protege/owl/examples/tab/ExampleViewComponent.java here for Protege 4.0.*] or
[http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/plugin/trunk/org.protege.editor.owl.examples.tab/src/org/protege/owl/examples/tab/ExampleViewComponent.java here for Protege 4.1].
Now this plugin depends on a library that can be found
[http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/plugin/tags/protege.4.0-2009-12-02/org.protege.editor.owl.examples.tab/lib/examplelib.jar here for Protege 4.0]
or
[http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/plugin/trunk/org.protege.editor.owl.examples.tab/lib/examplelib.jar here for Protege 4.1]. This library should be deposited in the lib directory of the project. This library is trivial and its only purpose is to show how to use a library in a plugin. The directory tree of the project should now look like this:
[[File:AnatomyTreeDoesView.png]]

At this point the ant install operation will compile, build and install the new plugin with the "ant install" command.
But the installed plugin won't run correctly and we will show how to fix this below.

===Libraries and the Bundle Classpath===

After we install the plugin, we can start Protege to try to use the "Example View Component". If you click on the View menu and then select "Ontology Views" you will see the "Example View Component" listed there. However on selecting this view and trying to place on the Protege screen, the following error will arise:
<pre>
Error logged
java.lang.NoClassDefFoundError: org/protege/owl/example/Metrics
at java.lang.Class.getDeclaredConstructors0(Native Method)
at java.lang.Class.privateGetDeclaredConstructors(Class.java:2357)
at java.lang.Class.getConstructor0(Class.java:2671)
at java.lang.Class.newInstance0(Class.java:321)
at java.lang.Class.newInstance(Class.java:303)
...
</pre>
If we look at the plugin contents with the "jar -tf " command then we will see that the build file correctly put the examplelib.jar into the plugin:
<pre>
[tredmond@BlackHole org.protege.owl.examples.tab]$ jar -tf build/org.protege.owl.examples.tab.jar
META-INF/
META-INF/MANIFEST.MF
lib/
org/
org/protege/
org/protege/owl/
org/protege/owl/examples/
org/protege/owl/examples/tab/
lib/examplelib.jar
org/protege/owl/examples/tab/ExampleViewComponent.class
plugin.xml
[tredmond@BlackHole org.protege.owl.examples.tab]$
</pre>

The problem at this point is in the MANIFEST.MF file. The Bundle-Classpath line is as follows:
<pre>
Bundle-ClassPath: .
</pre>
To include the examplelib.jar in the jar file, the Bundle-Classpath line must be modified to include this library:
<pre>
Bundle-ClassPath: .,lib/examplelib.jar
</pre>
Note that using a colon or a semi-colon instead of the comma does not work. Also entering ./lib/examplib.jar does not work either. This is the osgi mechanism for making this library available to this plugin. Note that since the MANIFEST.MF file does not have an Export-Package declaration, these classes will only be visible within the plugin and will not be exported to any other plugin in the Protege 4 environmeht. This is part of the plugin isolation provided by OSGi that allows different plugins to use different libraries without conflicts.

Now the plugin works correctly and I can install the view into the Active Ontology Tab:
[[File:AnoyomyViewSuccessful.png]].

===Tab Plugins and the Viewconfig.xml File===

The other most common plugin type is the Protege tab. In order to make a Protege tab, the developer needs to generate and use a viewconfig.xml file for the project. In this section we will show how to do this. It turns out that a tab can usually be put together without writing any Java code. The steps for writing a tab plugin are
# add a declaration of the tab plugin in the plugin.xml file.
# start Protege and graphically configure the tab in question.
# save the configuration and include it with the source files for the tab.
# test by restarting Protege and running the tab with the default configuration.
These steps are described in more detail below.

==== Step 1: Declare the plugin ====

The first thing that that needs to be done is to declare the tab in the plugin.xml file.
<pre>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<?eclipse version="3.0"?>

<plugin>
<extension id="ExampleViewComponent"
point="org.protege.editor.core.application.ViewComponent">
<label value="Example View Component"/>
<class value="org.protege.owl.examples.tab.ExampleViewComponent"/>
<category value="@org.protege.ontologycategory"/>
</extension>
<extension id="ExampleWorkspaceTab"
point="org.protege.editor.core.application.WorkspaceTab">
<label value="Example Tab"/>
<class value="org.protege.editor.owl.ui.OWLWorkspaceViewsTab"/>
<index value="X"/>
<editorKitId value="OWLEditorKit"/>
<defaultViewConfigFileName value="viewconfig-exampleTab.xml"/>
</extension>
</plugin>
</pre>

An important line in the above declaration of the tab is the defaultViewConfigFileName. This names a resource that the protege plugin will look for to create the default layout of the tab.

==== Step 2: Layout the views in the plugin ====

We can now compile this plugin and install it as before. Now when we run Protege 4, we will see a new tab called the "Example Tab" in the tabs menu. Enable this tab. Since we have not yet created the viewconfig-exampleTab.xml file, you will see that the tab is empty.

Now install and layout some views into this tab. In my case I made the views look like this:

[[File:AnatomyViewLayout.png]]

==== Step 3: Save a configuration file ====

Now in the tabs menu select "Export Current Tab" and save the file as
<pre>
viewconfig-exampleTab.xml
</pre>
in the project directory. In my case the viewconfig-exampleTab file looked like this:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<layout>
<VSNode splits="0.5 0.5">
<CNode>
<Component label="Asserted class hierarchy">
<Property id="pluginId" value="org.protege.editor.owl.OWLAssertedClassHierarchy"/>
</Component>
</CNode>
<CNode>
<Component label="Example View Component">
<Property id="pluginId" value="org.protege.owl.examples.tab.ExampleViewComponent"/>
</Component>
</CNode>
</VSNode>
</layout>
</pre>

Now before we complete this Protege session, go to the tabs menu and click "Reset selected tab to default state". You will see that the tab is now empty again. Now exit Protege.

The directory tree of the project should now look like this:

[[File:AnatomyTreeDoesViewWithConfig.png]]

==== Step 4: Test the results ====

Install the plugin again. Note that the build script automatically found the viewconfig-exampleTab.xml file and put it into the plugin:
<pre>
[tredmond@BlackHole org.protege.owl.examples.tab]$ jar -tf build/org.protege.owl.examples.tab.jar
META-INF/
META-INF/MANIFEST.MF
lib/
org/
org/protege/
org/protege/owl/
org/protege/owl/examples/
org/protege/owl/examples/tab/
lib/examplelib.jar
org/protege/owl/examples/tab/ExampleViewComponent.class
plugin.xml
viewconfig-exampleTab.xml
[tredmond@BlackHole org.protege.owl.examples.tab]$
</pre>

Run Protege and go to the Example Tab. It is empty? The reason for this is that the tab has been customized to have nothing in it from the last session. Click on the tabs menu and click on "Reset selected tab to default state". Now you will see the views that we configured in the tab before. This is now the default state for the tab and it will be what other users see when they use this plugin for the first time.

== Adding Menu Plugins ==

I have created a small menu project [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/org.protege.example.menu/trunk here] that shows how to create several different menu types. Later we will use this project as the example that drives this wiki page.

Adding a new menu to Protege 4.1 is very easy. The two things that the developer needs to accomplish are to
write the code for the menu action and to add an entry to the plugin.xml. I will take a real world example to illustrate the process. In this example, I am writing a plugin that causes Protege to display an ontology that is stored in a database format. I want to put this in the file menu of Protege 4.1 just under other items such as "New", "Open", "Open Recent" and "Open from URL".

To write the code for the menu plugin, the developer merely needs to extend ProtegeOWLAction. The three methods that the developer needs to write are initialise, dispose and actionPerformed. I think that the meaning of these three methods is pretty clear and this can be a very easy task.

Now the developer needs to add an entry to the [http://smi-protege/repos/protege/protege4/incubator/v3/org.protege.owlapi.bridge/trunk/plugin.xml plugin.xml] file. In my case the entry looks like this:
<pre>
<extension id="loadDatabase"
point="org.protege.editor.core.application.EditorKitMenuAction">
<name value="Load Database Ontology"/>
<class value="org.protege.owlapi.bridge.LoadDatabaseProjectMenu"/>
<toolTip value="Loads ontologies from a database into Protege"/>
<path value="org.protege.editor.core.application.menu.FileMenu/SlotAA-Z"/>
<editorKitId value="OWLEditorKit"/>
</extension>
</pre>
The "id" attribute of loadDatabase is simply a short identifier for the plugin that is not seen by the user. The "point" attribute indicates that the plugin being declared here is a menu plugin. The
<pre>
<class value="org.protege.owlapi.bridge.LoadDatabaseProjectMenu"/>
</pre>
line indicates the class that implements the action that this menu performs and the
<pre>
<editorKitId value="OWLEditorKit"/>
</pre>
line indicates that the menu is to be used in the context of the owl editor. The only other line in this [http://smi-protege/repos/protege/protege4/incubator/v3/org.protege.owlapi.bridge/trunk/plugin.xml plugin.xml] that is a bit mysterious is the line that says:
<pre>
<path value="org.protege.editor.core.application.menu.FileMenu/SlotAA-Z"/>
</pre>
The purpose of this line is to indicate exactly where the menu should be placed. The first part of the value,
<pre>
org.protege.editor.core.application.menu.FileMenu
</pre>
indicates that the parent of my "Load Database Ontology" menu is the file menu. The string is making a reference to the file menu declaration
<pre>
<extension
id="menu.FileMenu"
name="FileMenu"
point="org.protege.editor.core.application.EditorKitMenuAction">
<name value="File"/>
<toolTip value="File menu tool tip!"/>
<path value="/SlotA-A"/>
<editorKitId value="any"/>
</extension>
</pre>
from the [http://smi-protege/repos/protege/protege4/plugins/org.protege.editor.core.application/trunk/plugin.xml plugin.xml] file for the org.protege.editor.core.application plugin. The first part of the string
<pre>
org.protege.editor.core.application.menu.FileMenu
</pre>
is
<pre>
org.protege.editor.core.application
</pre>
which is the identifier of the plugin declaring the menu and "menu.FileMenu" is the id of the plugin from the plugin.xml file.

But now I need to explain the meaning of the SlotAA-Z portion of the path in my original menu declaration:
<pre>
<extension id="loadDatabase"
point="org.protege.editor.core.application.EditorKitMenuAction">
<name value="Load Database Ontology"/>
<class value="org.protege.owlapi.bridge.LoadDatabaseProjectMenu"/>
<toolTip value="Loads ontologies from a database into Protege"/>
<path value="org.protege.editor.core.application.menu.FileMenu/SlotAA-Z"/>
<editorKitId value="OWLEditorKit"/>
</extension>
</pre>
The SlotAA-Z string indicates exactly where the "Load Database Ontology" should appear in the File menu. This string (SlotAA-Z) is parsed as a group (Slot-AA) and an index (Z). First the group and the index are used to sort the children of the File menu. The children are sorted first by group but when two children have the same group they are then sorted by group index. In addition to this, children with the same group are grouped together in the menu.

In particular, if I track down the declarations of the "New", "Open", "Open Recent" and "Open from URL" menus I find that they all have a group identifier of SlotAA. This is why they appear in the file menu together followed by a separator bar. By specifying that my menu should have a group of SlotAA, I am telling Protege that I want my menu to be grouped with these menus. By giving my menu an index of Z I am telling Protege that I want my menu to go at the end of the list.

The algorithm used by Protege to determine the location of the plugin can be observed by turning on logging for the menu builder. This can easily be done by editing the log4j.xml in the Protege installation directory. First modify the section that says
<pre>
<appender name="console" class="org.apache.log4j.ConsoleAppender">
<param name="Threshold" value="INFO"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%m%n"/>
</layout>
</appender>
</pre>
to say
<pre>
<appender name="console" class="org.apache.log4j.ConsoleAppender">
<param name="Threshold" value="INFO"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%m%n"/>
</layout>
</appender>
</pre>
This allows the console to show debug messages. Then add the lines
<pre>
<category name="org.protege.editor.core.ui.menu">
<priority value="debug"/>
</category>
</pre>
This will cause Protege to generate somewhat verbose logs to the console (these logs also show up in a log file in ${home directory}/.Protege/logs/protege-###.log). The relevant lines for my menu plugin are as follows. First
<pre>
Parsed: [Menu: Load Database Ontology -- <SlotAA, Z>] parentId = org.protege.editor.core.application.menu.FileMenu
</pre>
indicates that Protege was able to parse the path for my menu plugin and determine that the id of the parent is
<pre>
org.protege.editor.core.application.menu.FileMenu
</pre>
the group is SlotAA and the group index is Z. Next we see the line
<pre>
[Menu: File -- <SlotA, A>] parent of [Menu: Load Database Ontology -- <SlotAA, Z>]
</pre>
which indicates that Protege was successfully able to find a declared menu with the right id to be the parent of my menu. This line also indicates that Protege successfully deciphered the group (SlotAA) and the index (Z). Finally there are the lines:
<pre>
Adding [Menu: File -- <SlotA, A>] to menu bar
Giving File the child[Menu: New... -- <SlotAA, E>]
Giving File the child[Menu: Open... -- <SlotAA, F>]
Giving File the child[Menu: Open recent -- <SlotAA, G>]
Giving File the child[Menu: Open from URL... -- <SlotAA, G>]
Giving File the child[Menu: Load Database Ontology -- <SlotAA, Z>]
Giving File the child[Menu: Save -- <SlotAB, A>]
Giving File the child[Menu: Save as... -- <SlotAB, B>]
Giving File the child[Menu: Gather ontologies... -- <SlotAB, C>]
Giving File the child[Menu: Export inferred axioms as ontology... -- <SlotAB, D>]
Giving File the child[Menu: Ontology libraries... -- <SlotD, A>]
Giving File the child[Menu: Loaded ontology sources... -- <SlotD, B>]
Giving File the child[Menu: Check for plugins... -- <SlotP, A>]
Giving File the child[Menu: Close -- <SlotY, M>]
</pre>
that indicate that the File menu was successfully populated.

== Advanced Topics ==
=== Adding New Plugin Types ===

'''Work in Progress'''

One of the advantages of using the OSGi/Eclipse framework is that it naturally allows developers to
define their own plugin types.. For example, the SWRL tab, being written by
Martin O'Connor, delegates the work of executing the SWRL rules to a rule engine plugin. It is anticipated that
there will be two rule engine plugins that are are compatible with the SWRL tab. One of these plugins will
be based on the Jess rule engine and the other plugin will be based on the DROOLS rule engine.

We will illustrate how this is done with two Protege bundles. The sources for these bundles can be found
<pre>
http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer.
</pre>
and
<pre>
http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/producer
</pre>
These two examples will only work with Protege 4.1 though it would not be too difficult to adapt them to work with
Protege 4.0 as well. Both bundles can be quickly installed through the included [[ConfiguringAntBuildFiles|ant scripts]].

The consumer bundle behaves as follows. It adds a menu item to a running Protege environment. This menu is found at the bottom of the edit menu. When the user clicks on this menu item, the consumer bundle performs the following actions:
# it looks for all custom_extension_point plugins in the running Protege environment,
# it instantiates each plugin found and finally
# it calls the doSomething() method on that plugin instance.

This behavior is provided through the interaction of four components:
* the '''consumer code''' that is responsible for looping through a set of plugins and invoking them.
* the '''plugin loader''' that is responsible for calculating and returning a set of plugins that match a specifiction.
* the '''plugin''' that is a java encoding of data encoded in plugin.xml files provided by the bundles.
* the '''plugin instance''' that is an instantiation of a plugin that does the actual work of the plugin.

==== The Plugin Consumer ====

The Plugin consumer essentially uses the plugin loader (described below) to loop through a series of plugins and instantiate and invoke them.
The code that does this work can be found in the [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/src/org/protege/example/extension/point/MyPluginConsumer.java MyPluginConsumer] class and looks like the following:
<pre>
public void actionPerformed(ActionEvent e) {
MyPluginLoader loader = new MyPluginLoader(getOWLModelManager());
for (MyPlugin plugin : loader.getPlugins()) {
try {
MyPluginInstance i = plugin.newInstance();
i.doSomething();
}
catch (Exception ex) {
ProtegeApplication.getErrorLog().logError(ex);
}
}
}
</pre>
This is a typical example of how a plugin consumer will work. It uses a plugin loader to find a set of plugins that are then instantiated (plugin.newInstance()) and then invoked (i.doSomething()). For the most part, the plugin consumer does not have to worry too much about the details of the Protege plugin infrastructure. The logic of the Plugin consumer is defined by the task at hand.

==== The Plugin Loader ====

The [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/src/org/protege/example/extension/point/MyPluginLoader.java plugin loader] is responsible for searching for plugins of the custom_extension_point type. The plugin loader extends the AbstractPluginLoader class which handles most of the logic of creating and finding plugins. Minimally, all the developer needs to do to implement the plugin loader is to implement a constructor and a create instance method. The constructor looks like this:
<pre>
public MyPluginLoader(OWLModelManager owlModelManager) {
super(MyPlugin.CONSUMER_ID, MyPlugin.ID);
this.owlModelManager = owlModelManager;
}
</pre>
and this is typical. The significance of the two arguments to the super constructor will be explained when I describe the Plugin implementation. Essentially they define which type of plugin is being searched for by this loader. In addition, the constructor for this plugin loader takes an owlModelManager argument so that he can pass this argument to the constructor for the plugins. The createInstance method then is responsible for constructing the plugin:
<pre>
protected MyPlugin createInstance(IExtension extension) {
return new MyPlugin(owlModelManager, extension);
}
</pre>
In addition there is a getExtensionMatcher method that can be used to restrict the set of plugins that are returned by this plugin loader. Generally it is not necessary to implement the getExtensionMatcher interface.

==== The Plugin ====

Essentially the [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/src/org/protege/example/extension/point/MyPlugin.java plugin] is a POJO representing a declaration of a plugin in a plugin.xml file. To understand this we need to look at the two declarations in two separate plugin.xml files. The first declaration is found in the bundle for the consumer plugin. This declaration represents a request for a particular type of service. In our case the [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/plugin.xml declaration] looks like this:
<pre>
<extension-point id="custom_extension_point"
name="Custom Extension Point"
schema="schema/custom_extension_point.exsd"/>
</pre>

This declaration defines
* the identifier of the plugin type, custom_extension_point, which is the name by which plugin developers refer to this plugin type, This string corresponds to the MyPlugin.ID that we passed to the AbstractPluginLoader constructor above. Note that it is possible for different bundles to declare an extension point
* the user friendly name of the plugin type and
* a pointer to the xml schema for the plugin type.
I believe that the last item, [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/schema/custom_extension_point.exsd the schema], is not mandatory but it is extremely useful for developers and it is created naturally when plugins are developed using the eclipse IDE.

The plugin producer provided a [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/producer/plugin.xml declaration] for his extension that matches the extension point declaration above. In our example the extension declaration looks like this:
<pre>
<extension id="SimpleImplementation"
point="org.protege.example.extension.point.custom_extension_point">
<class value="org.protege.example.extension.PluginImplementation"/>
<type value="Logger Type"/>
</extension>
</pre>

The plugin class, [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/src/org/protege/example/extension/point/MyPlugin.java MyPlugin], extends the AbstractProtegePlugin class. The AbstractProtegePlugin class provides many utilities that make it easy to write the plugin class. In particular, to get the "type" field the MyPlugin class provides an accessor:
<pre>
/**
* gets the declared type field for the plugin
*/
public String getType() {
return getPluginProperty(TYPE_PARAM, "null type");
}
</pre>

In addition, the AbstractProtegePlugin class does the tricky aspects of instantiating the plugin leaving only the task of initializing the instantiated plugin to the MyPlugin class:
<pre>
/**
* Creates an instance of the plugin. It is expected that
* this instance will be "setup", but the instance's
* initialise method will not have been called in the instantiation
* process.
*/
public MyPluginInstance newInstance() throws ClassNotFoundException, IllegalAccessException,
InstantiationException {
MyPluginInstance mpi = super.newInstance();
mpi.setup(modelManager, getType());
return mpi;
}
</pre>

==== The Plugin Instance ====

The [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/src/org/protege/example/extension/point/api/MyPluginInstance.java plugin instance class] is responsible for performing whatever task it is that the plugin is supposed to perform. In our case the plugin instance will implement the doSomething() method. This class must implement the ProtegePluginInstance interface though it is not clear that this is really needed anymore. The ProtegePluginInstance interface has only one method, initialise(), but many plugins, such as the one in this example, have their own initailization methods that are called by the Plugin Loader.

=== Frames, Frame Sections, and Rows ===

'''In Progress'''

It is not clear that this needs to be here but this is an extremely central Protege concept. In general plugin developers will not need to build custom Frame lists and can simply use the top level OWL Frame List concepts.

Most of the discussion will focus on a smaller and smaller section of the the following Protege 4.1 screen. This diagram shows the standard Protege 4.1 classes tab as it displays some information about the selected class which is the Country class in the pizza ontology.

[[File:FrameInClassesTab.png||A Classes Tab showing a standard frame in the right bottom]]

==== FrameLists and Frames ====

The diagram below shows a FrameList showing a description of the Country class. The OWLFrameList is the swing object that is responsible for displaying some object called the root object for the OWLFrameList. In this case, the root object for this frame list is the Country OWL class. Frequently the root object of the for a frame list is an OWL entity but this is not required. The constructor for the OWLFrameList object takes an OWLFrame object which manages the content model of the OWLFrameList. The associated OWLFrame object also has a root object and in this case the root object is the Country class.

While it may not be visually immediately apparent, the information being displayed is actually a rendition of a list of axioms. Thus for instance, the class expression represented in the section underneath ''Equivalent Classes'' represents the axiom
<pre>
Country SubClassOf DomainConcept and {America, England, France, Germany, Italy}.
</pre>
Similarly the first individual displayed under ''Members'' represents the axiom
<pre>
America Type Country.
</pre>

The fact that these are not displayed simply as the associated axioms is an key part of the purpose of the OWLFrameList. The task of the OWLFrameList below is to describe the Country class. For a user it makes sense that in the Members section of that OWLFrameList he would see a list of the individuals in that class. It would make less sense to the user if a set of axioms was displayed there.

[[File:FrameList.png||Frame List]]

==== Frame Sections ====

OWLFrames are grouped into a series of sections each of which shows a particular type of axioms. In the diagram below we have a frame section that is rendering a list of class assertion axioms.

[[File:FrameSection.png|Frame Section]]

==== Frame Section Rows ====

[[File:FrameSectionRow.png|Frame Section]]

[[File:FrameSectionRowAlt.png|Frame Section]]

== Glossary ==

There are some terms that come up naturally in the discussion of Protege 4 plugin development that require a bit of explanation. The Protege 4 plugin mechanism has three layers and the terms used to describe plugins is slightly different at each of these layers:
* '''Extension Point''' is the eclipse term for what Protege folk often call a plugin.
* '''[http://www.osgi.org/Main/HomePage OSGi]''' is the bottom layer of the Protege plugin architecture. It is a powerful industry standard framework which provides modularity and services beyond that provided by the Java specifications. In OSGi, the term OSGi bundle is used to represent a self-contained unit of code that can be introduced into the OSGi framework and which will import and export classes and resources in a controlled way.
* '''An OSGi Bundle''' is collection of software grouped into a single jar file. When this software runs in the OSGi environment, it runs in a protected space where it can define exactly what java classes from the surrounding environment are needed and what java classes are incompatible with its operation. Bundles have names, version numbers, developer contact information and activation entry points.
* '''A Plugin''' is a declared service that implements some functionality of use to the Protege platform. The Protege Plugin mechanism is based on the Eclipse plugin mechanism where plugins are declared in a file called plugin.xml.
* '''[http://wiki.eclipse.org/index.php/Rich_Client_Platform The Eclipse Rich Client Platform]''' is an environment built on top of OSGi which provides additional features to ease the building of a "Rich" client. Protege 4 only uses some of the features of this rich client platform. In particular, Protege 4 does not use SWT and many of the graphical related capabilities. But Protege 4 does use the declarative plugin capabilities provided by eclipse. It is here that some of the power of the OSGi platform becomes manifest, because we have been able to use only those bundles from the eclipse Rich Client platform that we need. In this setting, OSGi bundles created according to certain conventions become Eclipse Plugins.
* '''The Protege 4 Plugin layer''' provides some additional convenience methods over the Eclipse Plugin framework. Certain eclipse plugins that extend Protege 4 capabilities are called Protege 4 plugins.

PluginAnatomy

2011-03-09T21:01:50Z

Swartik: Typo: Changed "example" to "examples" in the Bundle-Symbolic-Name

== Introduction ==

The purpose of this web page is to describe some of the key ingredients of a plugin. The page will be directed by
the quick development of a plugin and can indeed be used as a quick start guide. In order to focus attention on the core plugin
concepts we will use the lowest common denominator of Java development tools and this tutorial will not use a Java IDE.
We will assume that the
reader has an understanding of Java development and knows how to follow along in his favorite IDE. For more information about
how to work with protege 4 in an IDE I will direct the reader to [[Protege4DevDocs#Using_an_Integrated_Development_Environment|this page]]. It is possible for an experienced developer to skip the ant scripts simply follow along in an IDE but we would still recommend a build file for the final version.

==The vacuous plugin in five minutes==

I just did it in just over [[Protege4 Plugin In Four Minutes|four minutes]].

The simplest (trivial) plugin can be built from sources in the following layout:<pre>
build.xml
META-INF
MANIFEST.MF
lib
resources
src
</pre> As we will see - even without any java sources - this is a sufficient basis for building a plugin that is recognized by Protege 4. There are only two files in this source tree - the build.xml file and the MANIFEST.MF. These files can be quickly put together from templates.

===Build.xml===

The template for the build.xml file can be downloaded from [http://smi-protege.stanford.edu/repos/protege/protege4/protege-base/trunk/etc/template-plugin-build.xml here]. Only two things need to be changed in this build file. They can be found by searching for the string "CHANGE ME" in the file. The first thing to change is the name of the project. I will call the project the plugin tutoiral project:<pre>
<project name = "plugin tutorial" default = "install" basedir = ".">
</pre>
The next setting that must almost always be changed is the name of the plugin. In this case, the build.xml already has the right name for the plugin but this is the only plugin for which this will be true:<pre>
<property name = "plugin" value = "org.protege.owl.examples.tab"/>
</pre>
With these adjustments the build.xml file is ready.

===MANIFEST.MF===

The template for the MANIFEST.MF file can be downloaded from [http://smi-protege.stanford.edu/repos/protege/protege4/protege-base/trunk/etc/template-manifest.mf here]. Only five things need to be changed in this file to make it useable and two are optional. These can be found by searching for the string "CHANGE ME" in the file. The first change is to set the display name for the plugin:<pre>
Bundle-Name: Tutorial Plugin
</pre> This is the name that is seen when Protege 4 starts up and in several plugin configuration screens.
The seccond thing to change is the symbolic name of the plugin. The usual default is to uses the same name as the plugin name in the build.xml file:<pre>
Bundle-SymbolicName: org.protege.editor.owl.examples.tab;singleton:=true
</pre>
Note the "singleton:=true" line - this is important since most Protege 4 plugins will only work if they are instantiated exactly once. The next things to change are the bundle description, the vendor and the documentation url:<pre>
Bundle-Description: A simple plugin for a plugin development tutorial
Bundle-Vendor: The Protege Development Team
Bundle-DocURL: www.perhaps.i.donthaveoneyet.com
</pre>
Actually the vendor and the docurl are optional and can be deleted. The MANIFEST.MF file is now ready.

===Compile and Run===

Before we can start, we must set the PROTEGE_HOME environment variable to point to a Protege 4 distribution. [[ConfiguringAntBuildFiles|This page]] has directions on how to do this in different operating systems but for now I will assume that we are on a unix (or os x) system. In that case, the system variable can be set with a simple command <pre>
export PROTEGE_HOME=/Users/tredmond/Desktop/Protege_4.0_beta
</pre>
If for any reason, using a environment variable is difficult, one can also achieve the same effect by creating a local.properties file with the single line
<pre>
protege.home=/Users/tredmond/Desktop/Protege_4.0_beta
</pre>

This vacuous plugin is now ready to compile and run. Assuming that the PROTEGE_HOME environment variable is set correctly, this plugin can be compiled with the simple command <pre>
ant install
</pre>
The full text of the build session is as follows:<pre>
[tredmond@Andromeda org.protege.editor.owl.examples.tab]$ ant install
Buildfile: build.xml

init:
[mkdir] Created dir: /private/tmp/org.protege.editor.owl.examples.tab/build
[mkdir] Created dir: /private/tmp/org.protege.editor.owl.examples.tab/build/classes
[mkdir] Created dir: /private/tmp/org.protege.editor.owl.examples.tab/build/classes/lib
[mkdir] Created dir: /private/tmp/org.protege.editor.owl.examples.tab/build/lib

checkProtegeLibs:
[echo] Using Protege Home = /Andromeda/Users/tredmond/dev/workspaces/protege4/owleditor/build/dist/equinox to find protege jars

checkProtegeLibsAndReport:

buildlibs:
[unjar] Expanding: /Andromeda/Users/tredmond/dev/workspaces/protege4/owleditor/build/dist/equinox/bundles/org.protege.common.jar into /private/tmp/org.protege.editor.owl.examples.tab/build

compile:

build.manifest:
[copy] Copying 1 file to /private/tmp/org.protege.editor.owl.examples.tab/build

copy.resources:
[mkdir] Created dir: /private/tmp/org.protege.editor.owl.examples.tab/build/classes/META-INF
[copy] Copying 1 file to /private/tmp/org.protege.editor.owl.examples.tab/build/classes/META-INF

jar:
[jar] Building jar: /private/tmp/org.protege.editor.owl.examples.tab/build/org.protege.owl.examples.tab.jar

install:
[delete] Deleting directory /Andromeda/Users/tredmond/dev/workspaces/protege4/owleditor/build/dist/equinox/configuration/org.eclipse.core.runtime
[delete] Deleting directory /Andromeda/Users/tredmond/dev/workspaces/protege4/owleditor/build/dist/equinox/configuration/org.eclipse.osgi
[copy] Copying 1 file to /Andromeda/Users/tredmond/dev/workspaces/protege4/owleditor/build/dist/equinox/plugins

BUILD SUCCESSFUL
Total time: 2 seconds
[tredmond@Andromeda org.protege.editor.owl.examples.tab]$
</pre>
If the PROTEGE_HOME environment variable is not set correctly the user will instead see the following:<pre>
BUILD FAILED
/private/tmp/org.protege.editor.owl.examples.tab/build.xml:74: missing protege libraries
</pre>

We can now look at what the build has done by exploring the project directory tree.
[[File:AnatomyBuildTreeAnnotated.png]]

We see the following elements:
* '''The Class Tree''' is (approximately) a flattened view of the plugin (the jar file). Generally this largely consists of the .class files that have been compiled from the java. But since we have not written any java yet this is not found. In addition, this will contain resources needed by the plugin and libraries that the plugin needs but which cannot be found in other Protege plugins.
* '''The Generated Libraries''' which are extracted from Protege plugins. This is needed because of a difference between how Java and OSGi get resources out of Jar files. OSGi allows a [[PluginAnatomy#Some_Nomenclature|bundle]] (which is a implemented as a jar file) to contain other jar files. If the bundle classpath is configured correctly, OSGi will load classes from those jars in jars. But Java does not have this capability. So the build script extracts the jar files out of the OSGi bundles that will be needed to compile the bundle. Note that these jar files are not copied to the class tree because the Protege 4/OSGi environment will make the classes and resources of these jar files available.
* '''The Protege 4 Plugin''' this is the final artifact of the build process. Because we have run "ant install" it has also been installed in the Protege distribution.

If the developer is still with me then he is now ready to run the plugin. Go to the Protege distribution (the one pointed to by the PROTEGE_HOME environment variable) and run it. We are particularly interested in the console output because this is going to be the only indication that this plugin is recognized at all. The console output should look like this:<pre>
Starting Protege 4 OWL Editor (Version 4.0.111)
Platform:
Java: JVM 1.5.0_16-b06-284 Memory: 207M
Language: en, Country: US
Framework: Eclipse (1.4.0)
OS: MacOSX (10.5.6)
Processor: ppc
Installed plugin Pellet Reasoner
Installed plugin DL Query Tab
Installed plugin Owlviz Plug-in
Installed plugin owleditor
Installed plugin Tutorial Plugin
Installed plugin The OWL API
Installed plugin Factplusplus Plug-in
Tutorial Plugin Plugin has no plugin.xml resource
</pre>
In this output we see that the Tutorial Plugin has been recognized and installed. In addition there is a informational message that the plugin.xml file has not been found. This is almost always indicates a problem because most Protege 4 plugins depend on a plugin.xml resource. We will describe how the plugin.xml file is generated in the next sections.

== Writing View and Tab Plugins ==

The previous plugin added no functionality to Protege 4. We are now going to describe how to remedy this situtaion. So far we have not missed the Java IDE but it is now when we start writing a bit of Java code that the Java IDE would really shine. But to illustrate the main concepts, we will continue to show how to build the plugin without any development environment other than that provided by the core Java tools.

===Adding a View Plugin to the Plugin.xml file===

Recall that previously when we ran our plugin, Protege 4 complained that there was no plugin.xml file. The plugin.xml file contains a declaration of the ways in which the plugin will extend the Protege 4 capabilities and (more advanced) the ways in which the plugin capabilities can be extended by other plugins. We will start by adding a declaration that this plugin will implement a Protege View.

So first we will give a definition of a Protege view. The purpose of a Protege view is to provide a view of some aspect of an ontology. In the Protege interface, a Protege view is easily recognized. It has a clearly defined border. At the top of a Protege view is a title bar and a collection of buttons allowing the user to
* split the protege view into two copies of the same view one above the other,
* split the protege view into two copies of the same view one beside the other,
* float the view above the Protege client so that it is visible in any context,
* close the view removing it from the tab that contains it.
An example of a typical Protege view is shown below.
[[File:AnatomyView.png]]

In order to declare our intent that this plugin implement a Protege view, we add the following pluxin.xml file to the root of the project tree:
<pre>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<?eclipse version="3.0"?>

<plugin>
<extension id="ExampleViewComponent"
point="org.protege.editor.core.application.ViewComponent">
<label value="Example View Component"/>
<class value="org.protege.owl.examples.tab.ExampleViewComponent"/>
<category value="@org.protege.ontologycategory"/>
</extension>
</plugin>
</pre>

This plugin.xml file states that this plugin is making a single extension to the Protege 4 capabilities. We will cover the meaning of the parts of this extension declaration line by line. The first line defines the id of the extension. This particular extension is called the ExampleViewComponent. The second decleration,
<pre>
point="org.protege.editor.core.application.ViewComponent",
</pre>
states what the extension is trying to do. This extension is attempting to implement the functionality represented by the extension point with the name
<pre>
org.protege.editor.core.application.ViewComponent.
</pre>
The label declaration tells Protege what to put in the title bar of the view. The class declaration indicates which class implements the functionality needed by this view. We will go into the implementation of that class shortly. Finally the category declaration tells Protege which menu under the View menu should contain this view.

A very simple view can be written by extending the class AbstractOWLViewComponent and implementing the methods initialiseOWLView and disposeOWLView. A very simple such implementation can be found
[http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/plugin/tags/protege.4.0-2009-12-02/org.protege.editor.owl.examples.tab/src/org/protege/owl/examples/tab/ExampleViewComponent.java here for Protege 4.0.*] or
[http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/plugin/trunk/org.protege.editor.owl.examples.tab/src/org/protege/owl/examples/tab/ExampleViewComponent.java here for Protege 4.1].
Now this plugin depends on a library that can be found
[http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/plugin/tags/protege.4.0-2009-12-02/org.protege.editor.owl.examples.tab/lib/examplelib.jar here for Protege 4.0]
or
[http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/plugin/trunk/org.protege.editor.owl.examples.tab/lib/examplelib.jar here for Protege 4.1]. This library should be deposited in the lib directory of the project. This library is trivial and its only purpose is to show how to use a library in a plugin. The directory tree of the project should now look like this:
[[File:AnatomyTreeDoesView.png]]

At this point the ant install operation will compile, build and install the new plugin with the "ant install" command.
But the installed plugin won't run correctly and we will show how to fix this below.

===Libraries and the Bundle Classpath===

After we install the plugin, we can start Protege to try to use the "Example View Component". If you click on the View menu and then select "Ontology Views" you will see the "Example View Component" listed there. However on selecting this view and trying to place on the Protege screen, the following error will arise:
<pre>
Error logged
java.lang.NoClassDefFoundError: org/protege/owl/example/Metrics
at java.lang.Class.getDeclaredConstructors0(Native Method)
at java.lang.Class.privateGetDeclaredConstructors(Class.java:2357)
at java.lang.Class.getConstructor0(Class.java:2671)
at java.lang.Class.newInstance0(Class.java:321)
at java.lang.Class.newInstance(Class.java:303)
...
</pre>
If we look at the plugin contents with the "jar -tf " command then we will see that the build file correctly put the examplelib.jar into the plugin:
<pre>
[tredmond@BlackHole org.protege.owl.examples.tab]$ jar -tf build/org.protege.owl.examples.tab.jar
META-INF/
META-INF/MANIFEST.MF
lib/
org/
org/protege/
org/protege/owl/
org/protege/owl/examples/
org/protege/owl/examples/tab/
lib/examplelib.jar
org/protege/owl/examples/tab/ExampleViewComponent.class
plugin.xml
[tredmond@BlackHole org.protege.owl.examples.tab]$
</pre>

The problem at this point is in the MANIFEST.MF file. The Bundle-Classpath line is as follows:
<pre>
Bundle-ClassPath: .
</pre>
To include the examplelib.jar in the jar file, the Bundle-Classpath line must be modified to include this library:
<pre>
Bundle-ClassPath: .,lib/examplelib.jar
</pre>
Note that using a colon or a semi-colon instead of the comma does not work. Also entering ./lib/examplib.jar does not work either. This is the osgi mechanism for making this library available to this plugin. Note that since the MANIFEST.MF file does not have an Export-Package declaration, these classes will only be visible within the plugin and will not be exported to any other plugin in the Protege 4 environmeht. This is part of the plugin isolation provided by OSGi that allows different plugins to use different libraries without conflicts.

Now the plugin works correctly and I can install the view into the Active Ontology Tab:
[[File:AnoyomyViewSuccessful.png]].

===Tab Plugins and the Viewconfig.xml File===

The other most common plugin type is the Protege tab. In order to make a Protege tab, the developer needs to generate and use a viewconfig.xml file for the project. In this section we will show how to do this. It turns out that a tab can usually be put together without writing any Java code. The steps for writing a tab plugin are
# add a declaration of the tab plugin in the plugin.xml file.
# start Protege and graphically configure the tab in question.
# save the configuration and include it with the source files for the tab.
# test by restarting Protege and running the tab with the default configuration.
These steps are described in more detail below.

==== Step 1: Declare the plugin ====

The first thing that that needs to be done is to declare the tab in the plugin.xml file.
<pre>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<?eclipse version="3.0"?>

<plugin>
<extension id="ExampleViewComponent"
point="org.protege.editor.core.application.ViewComponent">
<label value="Example View Component"/>
<class value="org.protege.owl.examples.tab.ExampleViewComponent"/>
<category value="@org.protege.ontologycategory"/>
</extension>
<extension id="ExampleWorkspaceTab"
point="org.protege.editor.core.application.WorkspaceTab">
<label value="Example Tab"/>
<class value="org.protege.editor.owl.ui.OWLWorkspaceViewsTab"/>
<index value="X"/>
<editorKitId value="OWLEditorKit"/>
<defaultViewConfigFileName value="viewconfig-exampleTab.xml"/>
</extension>
</plugin>
</pre>

An important line in the above declaration of the tab is the defaultViewConfigFileName. This names a resource that the protege plugin will look for to create the default layout of the tab.

==== Step 2: Layout the views in the plugin ====

We can now compile this plugin and install it as before. Now when we run Protege 4, we will see a new tab called the "Example Tab" in the tabs menu. Enable this tab. Since we have not yet created the viewconfig-exampleTab.xml file, you will see that the tab is empty.

Now install and layout some views into this tab. In my case I made the views look like this:

[[File:AnatomyViewLayout.png]]

==== Step 3: Save a configuration file ====

Now in the tabs menu select "Export Current Tab" and save the file as
<pre>
viewconfig-exampleTab.xml
</pre>
in the project directory. In my case the viewconfig-exampleTab file looked like this:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<layout>
<VSNode splits="0.5 0.5">
<CNode>
<Component label="Asserted class hierarchy">
<Property id="pluginId" value="org.protege.editor.owl.OWLAssertedClassHierarchy"/>
</Component>
</CNode>
<CNode>
<Component label="Example View Component">
<Property id="pluginId" value="org.protege.owl.examples.tab.ExampleViewComponent"/>
</Component>
</CNode>
</VSNode>
</layout>
</pre>

Now before we complete this Protege session, go to the tabs menu and click "Reset selected tab to default state". You will see that the tab is now empty again. Now exit Protege.

The directory tree of the project should now look like this:

[[File:AnatomyTreeDoesViewWithConfig.png]]

==== Step 4: Test the results ====

Install the plugin again. Note that the build script automatically found the viewconfig-exampleTab.xml file and put it into the plugin:
<pre>
[tredmond@BlackHole org.protege.owl.examples.tab]$ jar -tf build/org.protege.owl.examples.tab.jar
META-INF/
META-INF/MANIFEST.MF
lib/
org/
org/protege/
org/protege/owl/
org/protege/owl/examples/
org/protege/owl/examples/tab/
lib/examplelib.jar
org/protege/owl/examples/tab/ExampleViewComponent.class
plugin.xml
viewconfig-exampleTab.xml
[tredmond@BlackHole org.protege.owl.examples.tab]$
</pre>

Run Protege and go to the Example Tab. It is empty? The reason for this is that the tab has been customized to have nothing in it from the last session. Click on the tabs menu and click on "Reset selected tab to default state". Now you will see the views that we configured in the tab before. This is now the default state for the tab and it will be what other users see when they use this plugin for the first time.

== Adding Menu Plugins ==

I have created a small menu project [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/org.protege.example.menu/trunk here] that shows how to create several different menu types. Later we will use this project as the example that drives this wiki page.

Adding a new menu to Protege 4.1 is very easy. The two things that the developer needs to accomplish are to
write the code for the menu action and to add an entry to the plugin.xml. I will take a real world example to illustrate the process. In this example, I am writing a plugin that causes Protege to display an ontology that is stored in a database format. I want to put this in the file menu of Protege 4.1 just under other items such as "New", "Open", "Open Recent" and "Open from URL".

To write the code for the menu plugin, the developer merely needs to extend ProtegeOWLAction. The three methods that the developer needs to write are initialise, dispose and actionPerformed. I think that the meaning of these three methods is pretty clear and this can be a very easy task.

Now the developer needs to add an entry to the [http://smi-protege/repos/protege/protege4/incubator/v3/org.protege.owlapi.bridge/trunk/plugin.xml plugin.xml] file. In my case the entry looks like this:
<pre>
<extension id="loadDatabase"
point="org.protege.editor.core.application.EditorKitMenuAction">
<name value="Load Database Ontology"/>
<class value="org.protege.owlapi.bridge.LoadDatabaseProjectMenu"/>
<toolTip value="Loads ontologies from a database into Protege"/>
<path value="org.protege.editor.core.application.menu.FileMenu/SlotAA-Z"/>
<editorKitId value="OWLEditorKit"/>
</extension>
</pre>
The "id" attribute of loadDatabase is simply a short identifier for the plugin that is not seen by the user. The "point" attribute indicates that the plugin being declared here is a menu plugin. The
<pre>
<class value="org.protege.owlapi.bridge.LoadDatabaseProjectMenu"/>
</pre>
line indicates the class that implements the action that this menu performs and the
<pre>
<editorKitId value="OWLEditorKit"/>
</pre>
line indicates that the menu is to be used in the context of the owl editor. The only other line in this [http://smi-protege/repos/protege/protege4/incubator/v3/org.protege.owlapi.bridge/trunk/plugin.xml plugin.xml] that is a bit mysterious is the line that says:
<pre>
<path value="org.protege.editor.core.application.menu.FileMenu/SlotAA-Z"/>
</pre>
The purpose of this line is to indicate exactly where the menu should be placed. The first part of the value,
<pre>
org.protege.editor.core.application.menu.FileMenu
</pre>
indicates that the parent of my "Load Database Ontology" menu is the file menu. The string is making a reference to the file menu declaration
<pre>
<extension
id="menu.FileMenu"
name="FileMenu"
point="org.protege.editor.core.application.EditorKitMenuAction">
<name value="File"/>
<toolTip value="File menu tool tip!"/>
<path value="/SlotA-A"/>
<editorKitId value="any"/>
</extension>
</pre>
from the [http://smi-protege/repos/protege/protege4/plugins/org.protege.editor.core.application/trunk/plugin.xml plugin.xml] file for the org.protege.editor.core.application plugin. The first part of the string
<pre>
org.protege.editor.core.application.menu.FileMenu
</pre>
is
<pre>
org.protege.editor.core.application
</pre>
which is the identifier of the plugin declaring the menu and "menu.FileMenu" is the id of the plugin from the plugin.xml file.

But now I need to explain the meaning of the SlotAA-Z portion of the path in my original menu declaration:
<pre>
<extension id="loadDatabase"
point="org.protege.editor.core.application.EditorKitMenuAction">
<name value="Load Database Ontology"/>
<class value="org.protege.owlapi.bridge.LoadDatabaseProjectMenu"/>
<toolTip value="Loads ontologies from a database into Protege"/>
<path value="org.protege.editor.core.application.menu.FileMenu/SlotAA-Z"/>
<editorKitId value="OWLEditorKit"/>
</extension>
</pre>
The SlotAA-Z string indicates exactly where the "Load Database Ontology" should appear in the File menu. This string (SlotAA-Z) is parsed as a group (Slot-AA) and an index (Z). First the group and the index are used to sort the children of the File menu. The children are sorted first by group but when two children have the same group they are then sorted by group index. In addition to this, children with the same group are grouped together in the menu.

In particular, if I track down the declarations of the "New", "Open", "Open Recent" and "Open from URL" menus I find that they all have a group identifier of SlotAA. This is why they appear in the file menu together followed by a separator bar. By specifying that my menu should have a group of SlotAA, I am telling Protege that I want my menu to be grouped with these menus. By giving my menu an index of Z I am telling Protege that I want my menu to go at the end of the list.

The algorithm used by Protege to determine the location of the plugin can be observed by turning on logging for the menu builder. This can easily be done by editing the log4j.xml in the Protege installation directory. First modify the section that says
<pre>
<appender name="console" class="org.apache.log4j.ConsoleAppender">
<param name="Threshold" value="INFO"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%m%n"/>
</layout>
</appender>
</pre>
to say
<pre>
<appender name="console" class="org.apache.log4j.ConsoleAppender">
<param name="Threshold" value="INFO"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%m%n"/>
</layout>
</appender>
</pre>
This allows the console to show debug messages. Then add the lines
<pre>
<category name="org.protege.editor.core.ui.menu">
<priority value="debug"/>
</category>
</pre>
This will cause Protege to generate somewhat verbose logs to the console (these logs also show up in a log file in ${home directory}/.Protege/logs/protege-###.log). The relevant lines for my menu plugin are as follows. First
<pre>
Parsed: [Menu: Load Database Ontology -- <SlotAA, Z>] parentId = org.protege.editor.core.application.menu.FileMenu
</pre>
indicates that Protege was able to parse the path for my menu plugin and determine that the id of the parent is
<pre>
org.protege.editor.core.application.menu.FileMenu
</pre>
the group is SlotAA and the group index is Z. Next we see the line
<pre>
[Menu: File -- <SlotA, A>] parent of [Menu: Load Database Ontology -- <SlotAA, Z>]
</pre>
which indicates that Protege was successfully able to find a declared menu with the right id to be the parent of my menu. This line also indicates that Protege successfully deciphered the group (SlotAA) and the index (Z). Finally there are the lines:
<pre>
Adding [Menu: File -- <SlotA, A>] to menu bar
Giving File the child[Menu: New... -- <SlotAA, E>]
Giving File the child[Menu: Open... -- <SlotAA, F>]
Giving File the child[Menu: Open recent -- <SlotAA, G>]
Giving File the child[Menu: Open from URL... -- <SlotAA, G>]
Giving File the child[Menu: Load Database Ontology -- <SlotAA, Z>]
Giving File the child[Menu: Save -- <SlotAB, A>]
Giving File the child[Menu: Save as... -- <SlotAB, B>]
Giving File the child[Menu: Gather ontologies... -- <SlotAB, C>]
Giving File the child[Menu: Export inferred axioms as ontology... -- <SlotAB, D>]
Giving File the child[Menu: Ontology libraries... -- <SlotD, A>]
Giving File the child[Menu: Loaded ontology sources... -- <SlotD, B>]
Giving File the child[Menu: Check for plugins... -- <SlotP, A>]
Giving File the child[Menu: Close -- <SlotY, M>]
</pre>
that indicate that the File menu was successfully populated.

== Advanced Topics ==
=== Adding New Plugin Types ===

'''Work in Progress'''

One of the advantages of using the OSGi/Eclipse framework is that it naturally allows developers to
define their own plugin types.. For example, the SWRL tab, being written by
Martin O'Connor, delegates the work of executing the SWRL rules to a rule engine plugin. It is anticipated that
there will be two rule engine plugins that are are compatible with the SWRL tab. One of these plugins will
be based on the Jess rule engine and the other plugin will be based on the DROOLS rule engine.

We will illustrate how this is done with two Protege bundles. The sources for these bundles can be found
<pre>
http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer.
</pre>
and
<pre>
http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/producer
</pre>
These two examples will only work with Protege 4.1 though it would not be too difficult to adapt them to work with
Protege 4.0 as well. Both bundles can be quickly installed through the included [[ConfiguringAntBuildFiles|ant scripts]].

The consumer bundle behaves as follows. It adds a menu item to a running Protege environment. This menu is found at the bottom of the edit menu. When the user clicks on this menu item, the consumer bundle performs the following actions:
# it looks for all custom_extension_point plugins in the running Protege environment,
# it instantiates each plugin found and finally
# it calls the doSomething() method on that plugin instance.

This behavior is provided through the interaction of four components:
* the '''consumer code''' that is responsible for looping through a set of plugins and invoking them.
* the '''plugin loader''' that is responsible for calculating and returning a set of plugins that match a specifiction.
* the '''plugin''' that is a java encoding of data encoded in plugin.xml files provided by the bundles.
* the '''plugin instance''' that is an instantiation of a plugin that does the actual work of the plugin.

==== The Plugin Consumer ====

The Plugin consumer essentially uses the plugin loader (described below) to loop through a series of plugins and instantiate and invoke them.
The code that does this work can be found in the [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/src/org/protege/example/extension/point/MyPluginConsumer.java MyPluginConsumer] class and looks like the following:
<pre>
public void actionPerformed(ActionEvent e) {
MyPluginLoader loader = new MyPluginLoader(getOWLModelManager());
for (MyPlugin plugin : loader.getPlugins()) {
try {
MyPluginInstance i = plugin.newInstance();
i.doSomething();
}
catch (Exception ex) {
ProtegeApplication.getErrorLog().logError(ex);
}
}
}
</pre>
This is a typical example of how a plugin consumer will work. It uses a plugin loader to find a set of plugins that are then instantiated (plugin.newInstance()) and then invoked (i.doSomething()). For the most part, the plugin consumer does not have to worry too much about the details of the Protege plugin infrastructure. The logic of the Plugin consumer is defined by the task at hand.

==== The Plugin Loader ====

The [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/src/org/protege/example/extension/point/MyPluginLoader.java plugin loader] is responsible for searching for plugins of the custom_extension_point type. The plugin loader extends the AbstractPluginLoader class which handles most of the logic of creating and finding plugins. Minimally, all the developer needs to do to implement the plugin loader is to implement a constructor and a create instance method. The constructor looks like this:
<pre>
public MyPluginLoader(OWLModelManager owlModelManager) {
super(MyPlugin.CONSUMER_ID, MyPlugin.ID);
this.owlModelManager = owlModelManager;
}
</pre>
and this is typical. The significance of the two arguments to the super constructor will be explained when I describe the Plugin implementation. Essentially they define which type of plugin is being searched for by this loader. In addition, the constructor for this plugin loader takes an owlModelManager argument so that he can pass this argument to the constructor for the plugins. The createInstance method then is responsible for constructing the plugin:
<pre>
protected MyPlugin createInstance(IExtension extension) {
return new MyPlugin(owlModelManager, extension);
}
</pre>
In addition there is a getExtensionMatcher method that can be used to restrict the set of plugins that are returned by this plugin loader. Generally it is not necessary to implement the getExtensionMatcher interface.

==== The Plugin ====

Essentially the [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/src/org/protege/example/extension/point/MyPlugin.java plugin] is a POJO representing a declaration of a plugin in a plugin.xml file. To understand this we need to look at the two declarations in two separate plugin.xml files. The first declaration is found in the bundle for the consumer plugin. This declaration represents a request for a particular type of service. In our case the [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/plugin.xml declaration] looks like this:
<pre>
<extension-point id="custom_extension_point"
name="Custom Extension Point"
schema="schema/custom_extension_point.exsd"/>
</pre>

This declaration defines
* the identifier of the plugin type, custom_extension_point, which is the name by which plugin developers refer to this plugin type, This string corresponds to the MyPlugin.ID that we passed to the AbstractPluginLoader constructor above. Note that it is possible for different bundles to declare an extension point
* the user friendly name of the plugin type and
* a pointer to the xml schema for the plugin type.
I believe that the last item, [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/schema/custom_extension_point.exsd the schema], is not mandatory but it is extremely useful for developers and it is created naturally when plugins are developed using the eclipse IDE.

The plugin producer provided a [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/producer/plugin.xml declaration] for his extension that matches the extension point declaration above. In our example the extension declaration looks like this:
<pre>
<extension id="SimpleImplementation"
point="org.protege.example.extension.point.custom_extension_point">
<class value="org.protege.example.extension.PluginImplementation"/>
<type value="Logger Type"/>
</extension>
</pre>

The plugin class, [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/src/org/protege/example/extension/point/MyPlugin.java MyPlugin], extends the AbstractProtegePlugin class. The AbstractProtegePlugin class provides many utilities that make it easy to write the plugin class. In particular, to get the "type" field the MyPlugin class provides an accessor:
<pre>
/**
* gets the declared type field for the plugin
*/
public String getType() {
return getPluginProperty(TYPE_PARAM, "null type");
}
</pre>

In addition, the AbstractProtegePlugin class does the tricky aspects of instantiating the plugin leaving only the task of initializing the instantiated plugin to the MyPlugin class:
<pre>
/**
* Creates an instance of the plugin. It is expected that
* this instance will be "setup", but the instance's
* initialise method will not have been called in the instantiation
* process.
*/
public MyPluginInstance newInstance() throws ClassNotFoundException, IllegalAccessException,
InstantiationException {
MyPluginInstance mpi = super.newInstance();
mpi.setup(modelManager, getType());
return mpi;
}
</pre>

==== The Plugin Instance ====

The [http://smi-protege.stanford.edu/repos/protege/protege4/misc/examples/custom.extension/trunk/consumer/src/org/protege/example/extension/point/api/MyPluginInstance.java plugin instance class] is responsible for performing whatever task it is that the plugin is supposed to perform. In our case the plugin instance will implement the doSomething() method. This class must implement the ProtegePluginInstance interface though it is not clear that this is really needed anymore. The ProtegePluginInstance interface has only one method, initialise(), but many plugins, such as the one in this example, have their own initailization methods that are called by the Plugin Loader.

=== Frames, Frame Sections, and Rows ===

'''In Progress'''

It is not clear that this needs to be here but this is an extremely central Protege concept. In general plugin developers will not need to build custom Frame lists and can simply use the top level OWL Frame List concepts.

Most of the discussion will focus on a smaller and smaller section of the the following Protege 4.1 screen. This diagram shows the standard Protege 4.1 classes tab as it displays some information about the selected class which is the Country class in the pizza ontology.

[[File:FrameInClassesTab.png||A Classes Tab showing a standard frame in the right bottom]]

==== FrameLists and Frames ====

The diagram below shows a FrameList showing a description of the Country class. The OWLFrameList is the swing object that is responsible for displaying some object called the root object for the OWLFrameList. In this case, the root object for this frame list is the Country OWL class. Frequently the root object of the for a frame list is an OWL entity but this is not required. The constructor for the OWLFrameList object takes an OWLFrame object which manages the content model of the OWLFrameList. The associated OWLFrame object also has a root object and in this case the root object is the Country class.

While it may not be visually immediately apparent, the information being displayed is actually a rendition of a list of axioms. Thus for instance, the class expression represented in the section underneath ''Equivalent Classes'' represents the axiom
<pre>
Country SubClassOf DomainConcept and {America, England, France, Germany, Italy}.
</pre>
Similarly the first individual displayed under ''Members'' represents the axiom
<pre>
America Type Country.
</pre>

The fact that these are not displayed simply as the associated axioms is an key part of the purpose of the OWLFrameList. The task of the OWLFrameList below is to describe the Country class. For a user it makes sense that in the Members section of that OWLFrameList he would see a list of the individuals in that class. It would make less sense to the user if a set of axioms was displayed there.

[[File:FrameList.png||Frame List]]

==== Frame Sections ====

OWLFrames are grouped into a series of sections each of which shows a particular type of axioms. In the diagram below we have a frame section that is rendering a list of class assertion axioms.

[[File:FrameSection.png|Frame Section]]

==== Frame Section Rows ====

[[File:FrameSectionRow.png|Frame Section]]

[[File:FrameSectionRowAlt.png|Frame Section]]

== Glossary ==

There are some terms that come up naturally in the discussion of Protege 4 plugin development that require a bit of explanation. The Protege 4 plugin mechanism has three layers and the terms used to describe plugins is slightly different at each of these layers:
* '''Extension Point''' is the eclipse term for what Protege folk often call a plugin.
* '''[http://www.osgi.org/Main/HomePage OSGi]''' is the bottom layer of the Protege plugin architecture. It is a powerful industry standard framework which provides modularity and services beyond that provided by the Java specifications. In OSGi, the term OSGi bundle is used to represent a self-contained unit of code that can be introduced into the OSGi framework and which will import and export classes and resources in a controlled way.
* '''An OSGi Bundle''' is collection of software grouped into a single jar file. When this software runs in the OSGi environment, it runs in a protected space where it can define exactly what java classes from the surrounding environment are needed and what java classes are incompatible with its operation. Bundles have names, version numbers, developer contact information and activation entry points.
* '''A Plugin''' is a declared service that implements some functionality of use to the Protege platform. The Protege Plugin mechanism is based on the Eclipse plugin mechanism where plugins are declared in a file called plugin.xml.
* '''[http://wiki.eclipse.org/index.php/Rich_Client_Platform The Eclipse Rich Client Platform]''' is an environment built on top of OSGi which provides additional features to ease the building of a "Rich" client. Protege 4 only uses some of the features of this rich client platform. In particular, Protege 4 does not use SWT and many of the graphical related capabilities. But Protege 4 does use the declarative plugin capabilities provided by eclipse. It is here that some of the power of the OSGi platform becomes manifest, because we have been able to use only those bundles from the eclipse Rich Client platform that we need. In this setting, OSGi bundles created according to certain conventions become Eclipse Plugins.
* '''The Protege 4 Plugin layer''' provides some additional convenience methods over the Eclipse Plugin framework. Certain eclipse plugins that extend Protege 4 capabilities are called Protege 4 plugins.

Protege-OWL 4 FAQ

2011-02-28T19:08:19Z

Swartik: Added a link to the Error Classes page

Protege-OWL 4.x Frequently Asked Questions

This page is the FAQ for the '''4.x version of the Protege-OWL editor'''. We provide the following alternative FAQ pages for other Protege versions and Protege-related topics:

* [http://protege.stanford.edu/doc/owl-faq.html Protege-OWL 3.x FAQ]
* [http://protege.stanford.edu/doc/faq.html Protege-Frames FAQ]

__TOC__

=== How do I install Protege-OWL? ===
Protege-OWL is [http://protege.stanford.edu/download/download.html available for download] from the main Protege website. If you are new to Protege-OWL, we ask that you read about the three different installation options currently available to determine which best suits your needs:

* '''InstallyAnywhere platform independent installer program''' - this is the recommended method of installation for beginners and also for users that want a "double-clickable" executable file. The primary reason we recommend this method for beginners is that Protege-OWL requires a 1.5 version of the Java Virtual Machine to be present. The installer makes it very easy for you to install the correct version of the Java VM - or - if you already have Java installed, you can indicate the location during the install process. The installer also provides an executable file that you can double-click to launch Protege-OWL, e.g., "Protege.exe" on Windows, etc.

* '''ZIP file''' - we provide a ZIP file for more advanced users that are familiar with how to make sure the proper version of Java is present. This is also a convenient installation for users that do not require an executable file to launch Protege-OWL.

* '''Application bundle file''' - this is a new offering in Protege 4.1 that we hope will be an improvement for OS X users.

Note that if you are new user, we ask that you register before downloading Protege-OWL. If you have already registered, simply click on the [http://protege.stanford.edu/download/registered.html download link] and navigate to the [http://protege.stanford.edu/download/registered.html#p4.1 Protege 4 section] of the download page.

=== Where can I find user documentation for the Protege-OWL editor? ===
Please refer to the [[Protege4UserDocs#Protege-OWL_Editor|Protege 4 documentation page]] on this wiki for a list of available documentation.

=== Where do I ask questions and report bugs? ===
Please post comments, questions, and bug reports about Protege-OWL on the [http://mailman.stanford.edu/mailman/listinfo/p4-feedback p4-feedback mailing list]. Note that you must be subscribed to this list in order to post messages. Instructions for subscribing to Protege mailing lists are [http://protege.stanford.edu/doc/faq.html#01a.02 available on the main Protege website]. If you have difficulties subscribing or unsubscribing from p4-feedback, please contact the [mailto:p4-feedback-owner@lists.stanford.edu list owners].

=== Where can I look at a list known bugs and feature requests? ===
* View [https://bmir-gforge.stanford.edu/gf/project/owleditor/tracker/?action=TrackerItemBrowse&tracker_id=118 bug database]
* View [https://bmir-gforge.stanford.edu/gf/project/owleditor/tracker/?action=TrackerItemBrowse&tracker_id=121 feature request list]

=== Why am I getting "An error related to DOT has occurred" when trying to use the OWLViz plug-in? ===
If you see this error when trying to use OWLViz, it means that you have not completed some of the necessary steps to configure this plug-in. Complete documentation for fixing this error is available in the [http://protegewiki.stanford.edu/index.php/OWLViz#Troubleshooting troubleshooting section] of the OWLViz documentation.

=== How do I change the name of an entity (class, property, individual) in my ontology? ===
Select the Refactor | Change entity URI... menu item. In the resulting Change entity URI dialog box, enter the new name in the text box, and click the OK button.

=== Why does my ontology contain classes named Error1, Error2, ...? ===
See the [[Protege4ErrorClasses|Error Classes]] page for a description of this new OWL API feature.

Protege4ErrorClasses

2011-02-28T19:04:30Z

Swartik: Description of Error classes

== Error Classes ==

You may open an ontology and find subclasses of owl:Thing named Error1, Error2, etc.
These classes are created by [http://owlapi.sourceforge.net/ the OWL API] as of version 3.2.2.
Your document is a valid RDF document,
but it is ''not'' a valid OWL document.
Your document will be parsed and loaded,
and Protégé 4 still displays your asserted class hierarchy
(subclass assertions are part of RDFS, not OWL).
However, you will probably encounter errors if you use a reasoner.

As of version 4.1 beta (build 218),
Protégé 4 reports the error only through its GUI.
No diagnostic message is displayed in the console.
If you save your ontology,
it will contain references to the Error classes.

When the OWL API detects an error,
it provides some clue about the cause by asserting an equivalence between
an Error''i'' class and an expression involving offending entities.
In other words, you can diagnose an error by selecting one of the Error''i'' classes
in a class hierarchy window and clicking the Class Usage display.
Examining the displayed usages will help you understand your error.

PluginTypes

2011-02-25T21:06:34Z

Swartik: Grammar and typography fixes

<div class="orangeBox">
Protege 4 Plugin types 
This page summarises the default types of plugin that can be implemented for Protege 4.
</div> 

Back to [[Protege4DevDocs]]

__TOC__

== Existing Plugin Types ==

This is a snapshot of the existing types of plugins that can be added to Protege4.0.
The current set of plugin types can always be found in the code by looking at the plugin.xml file for the core.application and the owl bundles.
Just look for the extension-points in these files – these point to the schemas that are used for describing each type of plugin.
Plenty of examples can be found in the plugin.xml files themselves.

=== Core Plugins ===

==== ViewComponent ====

<hr>

The most common plugin type – implements views (the building blocks of workspace tabs).

Implementation of this plugin is demonstrated in the [http://www.co-ode.org/downloads/protege-x/plugin-code-example.php '''TabbedHierarchyView''' example].

There are many abstract implementations of this plugin to use as a base, for example each entity type (Class, Property and Individual) has an abstract base.

* Implement: '''org.protege.editor.core.ui.view.ViewComponent'''
* Example: '''org.protege.editor.owl.ui.clshierarchy.ToldOWLClassHierarchyViewComponent'''

<hr>

==== EditorKitMenuAction ====

Create an entry in a [[#menu.window|menu]] (and supply a mnemonic) and its associated action.

* Implement: '''org.protege.editor.core.ui.action.ProtegeAction'''
* Example: '''org.protege.editor.owl.ui.action.RemoveAllDisjointAxiomsAction'''

<extension id="menu.RemoveAllDisjointAxioms"
point="org.protege.editor.core.application.EditorKitMenuAction">
<name value="Remove all disjoint axioms..."/>
<toolTip value="Removes all of the disjoint axioms."/>
<class value="org.protege.editor.owl.ui.action.RemoveAllDisjointAxiomsAction"/>
<path value="org.protege.editor.core.application.menu.EditMenu/SlotM-H"/>
<editorKitId value="OWLEditorKit"/>
</extension>

''id'' = an ID for this plugin

''point'' = the type of plugin

''name'' = the name as it appears in the menu

''toolTip'' = a description of the action shown in a tooltip

''class'' = the implementing class (full package name)

''path'' = the relative position in the menu (section pos, subsection pos)

''editorKitId'' = the type of editor kit this plugin works with

===== Open URL in browser action =====

An addition has been made to the EditorKitMenuAction that allows a menu item that opens a specified page in a web browser.
This has been used to implement help items, but could be useful for lots of different reasons.

The best thing is '''this requires no coding whatsoever'''.
* ''url'' should be specified in the action descriptor instead of ''class''.
* The value should be the full URL of the webpage you wish to open.

Specifying a ''class'' element will cause the ''url'' to be ignored.

<extension id="menu.PluginsMenuItem" point="org.protege.editor.core.application.EditorKitMenuAction">
<name value="Protege-OWL plugins"/>
<toolTip value="Protege 4.0 OWL plugins"/>
<url value="http://protegewiki.stanford.edu/index.php/Protege-OWL_4.0"/>
<path value="org.protege.editor.core.application.menu.HelpMenu/SlotF-B"/>
<editorKitId value="any"/>
</extension>

<hr>

==== preferencespanel ====

Create a panel that will be loaded into the preferences dialog.

This should be for controlling a particular aspect of Protege4.0 in general or can be used as part of a bundle to control the behaviour of other plugins.

Preferences should be used to persist over sessions.

The '''applyChanges()''' method should be used to update the appropriate values in Protege's '''PreferencesManager'''.

* Implement: '''org.protege.editor.owl.ui.preferences.PreferencesPanel'''
* Example: '''org.protege.editor.owl.ui.tree.OWLTreePreferencesPanel'''

<hr>

==== WorkspaceTab ====

Unless your tab requires some special handling for events or non-standard layout you will probably not need to implement a class for this plugin.
You can just point the plugin.xml configuration to WorkspaceViewsTab (or OWLWorkspaceViewsTab) implementation and the rest of the plugin description
should be enough to customise the tab – i.e., give it a name and point to a default layout (see below).

* Implement: '''org.protege.editor.core.ui.workspace.WorkspaceTab'''
* Example: '''org.protege.editor.owl.ui.OWLClassesTab'''

===== Creating a tabbed view layout =====
* First, create or decide on which views you wish to have on your tab - make sure these are all implemented
* Open Protege 4.0
* Create a new tab ('''Window | Create new tab...''')
* Select your new tab and start customising it by adding views (see [[Protege4GettingStarted#Reconfigure_the_User_Interface|Reconfigure the user interface]])
* Select '''Window | Save current layout''' or quit Protege
* Find the new layout in the Protege installation directory ''Data/ViewConfigurations/viewconfig-custom-YOUR_TAB_NAME.xml''
* Rename this without the ''custom'' and copy to somewhere in your plugin source like a ''resources/'' folder
* Make sure this folder is on your classpath and that it gets added to you compiler output path
* Add the layout ('''defaultViewConfigFileName''') to the plugin description in plugin.xml

<extension id="OWLOntologyTab"
point="org.protege.editor.core.application.WorkspaceTab">
<label value="Active Ontology"/>
<class value="org.protege.editor.core.ui.workspace.WorkspaceViewsTab"/>
<defaultViewConfigFileName value="viewconfig-ontologytab.xml"/>
<index value="A"/>
<editorKitId value="OWLEditorKit"/>
</extension>

<hr>

==== EditorKitFactory ====

An EditorKit is the access point for a particular type of model (or ontology) and a GUI to handle that model.

Currently, there is just one implementation - the OWLEditorKit

Implement this type of plugin if you require a new type of model to be supported (eg a Frames-based model).

There is obviously considerable work needed to implement a new editor kit (along with its model manager and workspace).

* Implement: '''org.protege.editor.core.editorkit.EditorKitFactory'''
* Example: '''org.protege.editor.owl.OWLEditorKitFactory'''

<hr>

==== menu.window ====

Create a new menu into which [[#EditorKitMenuAction|EditorKitMenuActions]] can be added.
No need for any implementation. The plugin description gives enough detail for full customisation.

<extension id="menu.EditMenu"
point="org.protege.editor.core.application.EditorKitMenuAction">
<name value="Edit"/>
<toolTip value=""/>
<path value="/SlotB-A"/>
<editorKitId value="any"/>
</extension>

<hr>

==== OntologyRepositoryFactory ====

Create a source from which ontologies can be loaded. This plugin will create an entry on the welcome screen that allows the user to get ontologies from any number of places (a repository, a web service etc).

* Implement '''org.protege.editor.core.OntologyRepositoryFactory'''
* Example '''org.protege.editor.owl.model.repository.TONESRepositoryFactory'''

<extension id="TONESRepository" point="org.protege.editor.core.application.OntologyRepositoryFactory">
<class value="org.protege.editor.owl.model.repository.TONESRepositoryFactory"/>
</extension>

<hr>

==== EditorKitHook ====

Perform some actions when an editing session is started.
The initialise() method gets called when the EditorKit has been initialised.
This can be used to perform some special configuration or replace default behaviour.

* Implement '''org.protege.editor.core.editorkit.plugin.EditorKitHook''' (or org.protege.editor.owl.model.OWLEditorKitHook)
* Extension point '''org.protege.editor.core.application.EditorKitHook'''

<hr>

==== ToolBarAction ====

Not currently used - will be implemented to allow view actions to be customised

<hr>

==== ViewAction ====

Not currently used - will be implemented to allow view actions to be customised

=== OWL Plugins ===

==== inference.reasonerfactory ====

<hr>

==== ui.renderer.entitycolorprovider ====

<hr>

==== model.libraryfactory ====

<hr>

==== moveaxiomskit ====

Methods of selecting axioms for copying, moving or deleting (see [[P4MoveAxioms|Refactor | Copy/move/delete axioms]]) are pluggable.

You can choose to implement pages to add to the wizard to control how your kit works.

* Implement: '''org.protege.editor.owl.ui.ontology.wizard.move.MoveAxiomsKit'''
* Example: '''org.protege.editor.owl.ui.ontology.wizard.move.byreference.MoveAxiomsByReferenceKit'''

<extension id="MoveAxiomsByReference"
point="org.protege.editor.owl.moveaxiomskit">
<name value="Axioms by reference (select entities from the ontology)" />
<class value="org.protege.editor.owl.ui.ontology.wizard.move.byreference.MoveAxiomsByReferenceKit" />
</extension>

<hr>

==== ui.editor.description (from build 109) ====

[[Image:Class-expression-editor.png|400px|right]]

When adding/editing superclasses, equivalent classes, property domains, individual types etc a class description editor is brought up.

Each tab on the editor is a plugin capable of creating/editing (possibly a subset) OWL class descriptions

* Implement: '''org.protege.editor.owl.ui.editor.AbstractOWLDescriptionEditor'''
* Example: '''org.protege.editor.owl.ui.editor.OWLClassSelectorWrapper'''

<extension id="OWLClassSelectorWrapper"
point="org.protege.editor.owl.ui.editor.description">
<label value="Asserted class hierarchy"/>
<class value="org.protege.editor.owl.ui.editor.OWLClassSelectorWrapper"/>
<index value="B"/>
</extension>