Menu
▾
▴
[Davinspector-svn] SF.net SVN: davinspector:[157] trunk/Documents/PluginDevelopment_Howto
|
From: <wu...@us...> - 2008-08-20 14:42:29
|
Revision: 157
http://davinspector.svn.sourceforge.net/davinspector/?rev=157&view=rev
Author: wuest
Date: 2008-08-20 14:42:25 +0000 (Wed, 20 Aug 2008)
Log Message:
-----------
Added and updated the plugin development howto.
Added a screenshot of the example plugin.
Modified Paths:
--------------
trunk/Documents/PluginDevelopment_Howto/DAVInspector_plugin_develement_howto.tex
Added Paths:
-----------
trunk/Documents/PluginDevelopment_Howto/gui-plugin.png
Modified: trunk/Documents/PluginDevelopment_Howto/DAVInspector_plugin_develement_howto.tex
===================================================================
--- trunk/Documents/PluginDevelopment_Howto/DAVInspector_plugin_develement_howto.tex 2008-08-19 12:11:16 UTC (rev 156)
+++ trunk/Documents/PluginDevelopment_Howto/DAVInspector_plugin_develement_howto.tex 2008-08-20 14:42:25 UTC (rev 157)
@@ -6,10 +6,22 @@
\usepackage{color}
\usepackage{caption}
\usepackage{exscale}
- \usepackage[dvips]{graphicx}
+ \usepackage[pdftex]{graphicx}
\pagestyle{headings}
\usepackage{longtable}
+%% Formatierung Listings %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\usepackage{listings} % Paket zur Formatierung von listings
+%\lstset{numbers=left} % zeilennummern links
+\lstset{numberstyle=\scriptsize} % zeilennummern größe
+\lstset{numbersep=10pt} % abstand zeilennummern -> listing
+\lstset{frame=single} % (rahmen für abstand zum text)
+\lstset{framerule=0.5pt} % (rahmen für abstand zum text)
+\lstset{aboveskip=12pt} % abstand über dem listing 12pt
+%\lstset{backgroundcolor=\color[rgb]{0.95,0.95,0.95}} % Hintergrund grau
+\lstset{language=Java} % Sprache des HL
+\lstset{captionpos=b} % Beschriftung ist unterhalb
+\lstset{basicstyle=\footnotesize\ttfamily} % kleine schriftart
\author{Markus Litz}
\title{DAVInspector Plugin-development Howto}
@@ -31,18 +43,19 @@
\vspace{0.5cm}
\Large
- \textsc{Howto to write plugins for Davinspector}
+ \textsc{How to write plugins for Davinspector}
\vspace{0.5cm}
\large
18.04.2008 - Markus Litz \\
+ 18.08.2008 - Jochen Wuest \\
DLR (German Aerospace Center) \\
Simulation and Software Technology \\
\end{center}
\normalsize
-This is a updated brief explanation about writing plugins for DAVInspector. If you are just looking for a user guide please take a look at the DAVInspector website at \textit{<http://davinspector.sourceforge.net/>}. This explains what this version of DAVInspector is and how you could add new features to DAVInspector without knowledge of the core program. Just some experiences in java programming are needed.
+This is a updated brief explanation about writing plugins for DAVInspector. If you are just looking for a user guide please take a look at the DAVInspector website at \textit{<http://davinspector.sourceforge.net/>}. This explains what this version of DAVInspector is and how you could add new features to DAVInspector without knowledge of the core program. Just some experiences in Java programming are needed.
\end{titlepage}
@@ -57,38 +70,42 @@
% \mainmatter
+%##################################################################################################
+% What is DAVInspector?
+%##################################################################################################
\section{What is DAVInspector?}
-DAVInpector is a tool for debugging and monitoring HTTP and WebDAV capable applications. It is mainly written to help developers creating HTTP/WebDAV clients or servers, but could also be used by sysadmins. The open plugin technology makes it possible that in future other network protocols will be support too.
+DAVInpector is a tool for debugging and monitoring HTTP and WebDAV capable applications. It is mainly written to help developers creating HTTP/WebDAV clients or servers, but could also be used by sysadmins. Also the open plugin technology enables the application to support other network protocols in the future.
-DAVInspector is developed by employees of the the institution "Simulation and Software Technology" (SISTEC) at the German Aerospace Center DLR.
+DAVInspector is developed by employees of the institution "Simulation and Software Technology" (SISTEC) at the German Aerospace Center DLR.
We are happy about any support for this project - for example you might participate as a developer, bug reporter or simply by telling us your needs. Just visit our forums or join our mailing-lists on Sourceforge.
\subsection{What do I need?}
-You need :
+In order to create your own DAVInspector plugins at least the following software is required:
\begin{itemize}
- \item A stable version of DAVInspector - get latest stable release build of DAVInspector from SF.NET download page: \textit{<http://davinspector.sourceforge.net>}.
- \item Java version 1.5.0 or higher.
- \item Jakarta Ant
+ \item A stable version of DAVInspector - get the latest stable release of DAVInspector from SF.NET download page: \textit{<http://davinspector.sourceforge.net>}.
+ \item Java 2 Runtime Environment (JRE) or Java 2 Developer Kit (JDK) both version 1.5.0 or higher.
\end{itemize}
-To build or run DAVInspector you need a Java 2 Runtime Environment (JRE) with a version number 1.5.0 and higher. You can download the JRE for a number of platforms from \textit{<http://java.sun.com>}.
-If you want to build DAVInspector you additionally need a recent version of the Jakarta Ant build tool. You can download Ant from \textit{<http://jakarta.apache.org>}.
+To build or run DAVInspector you need either JRE or JDK version 1.5.0 or higher. You can download the JRE or JDK for various platforms from \textit{<http://java.sun.com>}.
+If you want to build DAVInspector you additionally need a recent version of the Apache Ant build tool. You can download Ant from \textit{<http://ant.apache.org>}.
+%##################################################################################################
+% Writing Plugins
+%##################################################################################################
\section{Writing Plugins}
-There are 2 types of plugins. ViewPlugins and EditPlugins. The ViewPlugins only shows the transfert data and gives you the possibility to change the way how to display these data, e.g. highling. Through EditPlugins DAVInspector gives you the capability to change the transfered data like body or header informations.
-The two types of plugins are represented by the two interfaces IViewPlugin and IEditPlugin. Your own plugin has to implement one of these interfaces.
+There are two types of plugins: ViewPlugins and EditPlugins. ViewPlugins only display the transfered data and provide the possibility to change the presentation of the data, e.g. highlighting. EditPlugins enable you to change the data before it is transfered. For example you may change the header information of a message. The two types of plugins are represented by the two interfaces \textit{IViewPlugin} and \textit{IEditPlugin}. Your own plugin has to implement one of these interfaces.
+\subsection{Constructor}\label{subsec:contructor}
+Since the plugins are loaded dynamically, there is no constructor we can use to set things up. Instead each plugin has to implement the method \textit{init()}, which acts like a constructor. For example the \textit{init()} of the ExampleView plugin:
-\subsection{Constructor}
-Since the plugins are loaded dynamically, there is no constructor we can use to set things up. Instead each plugin has to implement the method init(), which acts like a constructor. For example the init() of the ExampleView plugin:
-
-\begin{verbatim}
-public void init(PluginManager pluginManager, PluginDirection direction) {
+\begin{lstlisting}[caption={init() method of ExampleView plugin}, label=code:init]
+public void init(PluginManager pluginManager,
+ PluginDirection direction) {
myPlugInDirection = direction;
if (myJScrollPane == null) {
myJTextPane = new JTextPane();
@@ -98,16 +115,14 @@
myJTextPane.setText("");
Util.setUIDesign();
}
-\end{verbatim}
+\end{lstlisting}
-
\subsection{Naming conventions}
+To write your own plugin you have to follow some naming conventions. Otherwise DAVInspector is not able to load your plugin. The main class of your plugin has to belong to the package \textit{de.dlr.davinspector.plugins.<Main Class>}.\\
+Let's assume you are writing a plugin named \textit{ExampleViewPlugin}. The first few lines of code have to look like this:
-To write your own plugin you have to follow some naming conventions. Otherwise DAVInspector is not able to load your plugin. The main class of your plugin has to belong to a package de.dlr.davinspector.plugins.<Main Class>.\\
-So, let's assume to write a plugin named ExampleViewPlugin. The first few lines of code have to look like this:
-
-\begin{verbatim}
+\begin{lstlisting}[caption={Naming conventions}, label=code:naming]
package de.dlr.davinspector.plugins.exampleviewplugin;
import de.dlr.davinspector.common.Util;
@@ -118,58 +133,118 @@
public class ExampleViewPlugin implements IViewPlugin {
...
}
-\end{verbatim}
+\end{lstlisting}
-If you think, you are ready to test your plugin, create a jar file of it named like the main class. In our example that would be ExampleViewPlugin.jar. Copy it to the plugin directory of DAVInspector and start DAVInspector. Now you should see you plugin in the plugin-configuration window.
+If you think, you are ready to test your plugin, create a JAR file named like the main class. In our example the JAR file would be named \textit{ExampleViewPlugin.jar}. Copy this file to the plugin directory of DAVInspector and start DAVInspector. Now your plugin should be listed in the plugin-configuration window and you can test the proper functioning of your plugin.
\subsection{GUI}
-Ne gui is wat feines...\\
-Muffi-Schlumpf sagt: \textit{``Ich hasse GUI!''}
+If you want to create a plugin with a graphical user interface (GUI) you can use all provided by the Java Swing framework.
+As shown in listing \ref{code:gui} the method \textit{getUI()} of the interface \textit{IViewPlugin} returns the top component of your GUI to the DAVInspector plugin manager. This top component has to be of the type \textit{JComponent} or a subclass of \textit{JComponent}. It is recommended to initialize the GUI components in the \textit{init()} method of your class, see section \ref{subsec:contructor}.
+\begin{lstlisting}[caption={GUI method of ExampleView plugin}, label=code:gui]
+/** The scroll pane of the view. */
+private JScrollPane myJScrollPane = null;
+...
+public JComponent getUI() {
+ return myJScrollPane;
+}
+\end{lstlisting}
+\begin{figure}
+ \centering
+ \includegraphics[width=0.75\textwidth]{gui-plugin.png}
+ \caption{Screenshot GUI ExampleViewPlugin (german version)}
+ \label{fig:gui-plugin}
+\end{figure}
+
+Figure \ref{fig:gui-plugin} shows the GUI of the described \textit{ExampleView} plugin from above.
+
+
+%##################################################################################################
+% Internationalization
+%##################################################################################################
\section{Internationalization (I18N)}
+In order to provide a localized version of your plugin you need to:
+\begin{itemize}
+ \item Provide localized language files.
+ \item Use a translate method to get the localized text for labels and so on.
+ \item Name all files correctly and place them proper in the JAR file.
+\end{itemize}
-To make your plugin multilingual, you have to .....
+\begin{lstlisting}[caption={Using translation your source}, label=code:i18n-use-translate]
+public String getName() {
+ return translate("name");
+}
+\end{lstlisting}
+Listing \ref{code:i18n-use-translate} shows the use of the translation method to get the localized version of a text. An implementation of the translation method is shown in listing \ref{code:i18n-translate-method}. Each text is identified by a key. This key is used to look up the localized version of the text in the appropriate language file.
+Listing \ref{code:i18n-language-file} shows, as an example, the content of the default language file of the \textit{ExampleView} plugin. This file is named \textit{TextBundle.properties}. \textit{TextBundle\_de\_DE.properties} would be the proper name of a german language file. Further information regarding Java and internationalization can be found at \cite{java-i18n-res} and \cite{java-i18n-tut}.
+\begin{lstlisting}[caption={Language file definition for example plugin}, label=code:i18n-language-file]
+name=Example Plugin
+description=This is an example plugin
+\end{lstlisting}
+\begin{lstlisting}[caption={Source code of translate() method}, label=code:i18n-translate-method]
+public static String translate(String key) {
+ final String bundleName =
+ "de.dlr.davinspector.plugins.exampleviewplugin.TextBundle";
+
+ /** The resource bundle. */
+ ResourceBundle resourceBundle =
+ ResourceBundle.getBundle(bundleName,
+ Locale.getDefault());
+ return resourceBundle.getString(key);
+}
+\end{lstlisting}
+
+
+%##################################################################################################
+% Logging
+%##################################################################################################
\section{Logging}
+You should use the Logging system of DAVInspector to log debug and error messages. All you have to do is to create a logging object for each class:
-You should use the Logging system of DAVInspector to log debug and error messages. All you have to do is, to create a logging object for each class:
-
-\begin{verbatim}
+\begin{lstlisting}[caption={Logging}, label=code:logging]
public class ExampleViewPlugin implements IViewPlugin {
/** Logger, Apache log4j. */
- private static Logger myLogger = Logger.getLogger(ExampleViewPlugin.class);
+ private static Logger myLogger =
+ Logger.getLogger(ExampleViewPlugin.class);
+
+ myLogger.debug("This is a debug message");
}
-\end{verbatim}
+\end{lstlisting}
-Then you can use the five logging methods debug(), info(), warn(), error() and fatal()\\
-For example: \textit{logger.debug("This is a debug message");}\\
-All messages should appear on stdout / the logging file.
+Now you can use the five logging methods \textit{debug()}, \textit{info()}, \textit{warn()}, \textit{error()} and \textit{fatal()}. An example on how to obtain the logger and using the different logging methods is given in listing \ref{code:logging}. All messages should appear in StdOut / the log file. Further information on logging with log4j is available at \cite{log4j}.
-
\subsection{Troubleshooting}
-If your plugin doesn't load and java is saying something about invalid class version numbers or something like that, make sure, that you have compiled DAVInspector and your plugin with the same JDK version.
-You could also write to the DAVInspector development mailinglist \cite{ml}.
+If your plugin does not load and Java is reporting something about invalid class version numbers or something like that, make sure you have compiled DAVInspector and your plugin with the same JDK version. You could also write to the DAVInspector development mailing list \cite{ml}.
+%##################################################################################################
+% Conclusion
+%##################################################################################################
\section{Conclusion}
-The DAVInspector development has just started, so please support us with potential error descriptions. We hope DAVInspector and this HOWTO could help your development environment.
+The development of DAVInspector has just started, so please support us with potential error descriptions. We hope DAVInspector and this HOWTO may help you to improve your development environment.
\subsection{Call for participation}
-DAVInspector is open source project under Apache2 License. So anybody is welcome to the project. Please join our development mailing list : \textit{<dav...@li...>} \cite{ml}, if you have interest.
+DAVInspector is an open source project published under Apache 2.0 License. Anybody is welcome to the project. If you are interested, feel free to join our development mailing list at \cite{ml}.
-
-\addcontentsline{toc}{chapter}{References}
-
+%##################################################################################################
+% the bibliography
+%##################################################################################################
+\begin{flushleft}
\begin{thebibliography}{12}
\bibitem{ml} DAVInspector Development mailing list - https://lists.sourceforge.net/lists/listinfo/davinspector-developers
+\bibitem{java-i18n-res} Java Internationalization homepage - http://java.sun.com/javase/technologies/core/basic/intl/
+\bibitem{java-i18n-tut} Tutorial on core internationalization functionality - http://java.sun.com/docs/books/tutorial/i18n/index.html
+\bibitem{log4j} Short introduction to log4j - http://logging.apache.org/log4j/1.2/manual.html
\end{thebibliography}
+\end{flushleft}
\end{document}
Property changes on: trunk/Documents/PluginDevelopment_Howto/gui-plugin.png
___________________________________________________________________
Added: svn:mime-type
+ application/octet-stream
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
