Difference between revisions of "PluginAnatomy"

From Protege Wiki
Jump to: navigation, search
(→‎Compile and Run)
(→‎Compile and Run)
Line 100: Line 100:
 
We see the following elements:
 
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 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 plugin (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 plugin.
+
* '''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 plugin (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 plugins that will be needed to compile the plugin.
 
* '''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.
 
* '''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.
  

Revision as of 08:13, May 21, 2009

In Progress!

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. However, 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 this page.

The vacuous plugin in one minute

Before we can start, we must set the PROTEGE_HOME environment variable to point to a Protege 4 distribution. 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 
   export PROTEGE_HOME=/Users/tredmond/Desktop/Protege_4.0_beta
The simplest (trivial) plugin can be built from sources in the following layout:
   build.xml
   META-INF
      MANIFEST.MF
   lib
   resources
   src
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 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:
<project name = "plugin tutorial" default = "install" basedir = ".">
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:
   <property name = "plugin"          value = "org.protege.owl.examples.tab"/>

With these adjustments the build.xml file is ready.

MANIFEST.MF

The template for the MANIFEST.MF file can be downloaded from 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:
Bundle-Name: Tutorial Plugin
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:
Bundle-SymbolicName: org.protege.editor.owl.example.tab;singleton:=true
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:
Bundle-Description: A simple plugin for a plugin development tutorial
Bundle-Vendor: The Protege Development Team
Bundle-DocURL: www.perhaps.i.donthaveoneyet.com

Actually the vendor and the docurl are optional and can be deleted. The MANIFEST.MF file is now ready.

Compile and Run

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 
  ant install
The full text of the build session is as follows:
[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]$
If the PROTEGE_HOME environment variable is not set correctly the user will instead see the following:
BUILD FAILED
/private/tmp/org.protege.editor.owl.examples.tab/build.xml:74: missing protege libraries

We can now look at what the build has done by exploring the project directory tree. 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 plugin (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 plugins that will be needed to compile the plugin.
  • 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:
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

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.

Adding content to the plugin

The previous plugin added precisely no functionality to Protege 4. We are now going to describe how to remedy this situtaion.

Plugin.xml

Viewconfig.xml

Retrieved from "https://protegewiki.stanford.edu/index.php?title=PluginAnatomy&oldid=5960"