!!! FAQ

What... ? and Why...? Questions

This Page is supposed to help you getting started with the development of KnowWE. Feel free to add your Solutions to this page. If you don't find the Informations you need here, you can post it in the [Forum|http://sourceforge.net/projects/knowwe/forums].

[{TableOfContents }]
!! What is a Plugin?A simple and configurable code management.
For a smooth connection between the main application and the plugins the directory path of a developed plugin need to be known by the main application. 
The simplest possibility is the use of a designated directory.
For KnowWE the directory "WEB-INF\lib" is used. In this directory all libraries are stored. The plugins are recognized by their Plugin.xml. A plugin is installed by adding its artifact id to the .


!! Management of Plugins
 
Their management is provided by the {{PluginManager}}, which is an abstract class that itself holds a singleton instance. 
The singleton has to initialized by an inheriting class; an implementation is provided by the class {{JPFPluginManager}}, which is based on the [Java Plugin Frameworks|http://jpf.sourceforge.net] (JPF).

One of the static methods {{init(String dir)}} or {{init(File[] pluginFiles)}} initializes the {{PluginManager}}. 
The passed parameter {{dir}} of the first method specifies the path of the directory including the plugins. The parameter of the second method directly contains the plugin files.
KnowWE uses the second method, because it filters the files from "WEB-INF/lib".
It is required to copy the developed plugin into the specified directory; this is described in more detail in [Build process].

!! Extension Points

A plugin consists of an XML file and a collection of class files (compiled source code).
The XML file specifies, which points in the source code are extended by the classes. 
Also, new points in code can be defined that are extensible. 
We call these points within the code {{ExtensionPoints}}, and we call the classes extending these points {{Extensions}}. 
The structure of the XML file is described in more detail in [plugin.xml|Meaning of pluginxml].

For each {{ExtensionPoint}} there exists an interface, that have to be implemented by the class extending the {{ExtensionPoint}}. 
Then, the {{PluginManager}} provides an array of instances, that define this {{ExtensionPoint}}. 
The array is sorted according to the priority of the extensions. 
The priority is defined in the XML file as well as the name and the description of the extension.

In addition, it is possible to define further attributes for an {{ExtensionPoint}}. 
These attributes have to be included in the XML file of the implementing extensions. 
<tags>plugin extension jpf </tags>

!!Creating new projects

Every new project has to be allocated to one of the three main repositories: __d3web-core, d3web-KnowWE or Research.__

!Creating the project in Eclipse

* Do a right click on the main project (one of the three projects mentioned above) → New → Other…. In the window, in the Maven folder, select "Maven Module"
* Check the checkbox called "Skip Archetype selection", give the project a name and hit Next.
* Enter a human-readable name into the field "Name", fill in "Description" as needed.
* Click "Finish".

Now you will see the new project in the Eclipse Project Explorer. Now you can start creating or copying source files. Using the __UTF-8 encoding__ is __mandatory.__
 
! License header

Every {{.java}} file __must__ contain the license header, starting in the first line. Be sure to have an empty line between the license and the {{package}} declaration.

The license is to look like this:
{{{
/*
 * Copyright (C) 2010 Chair of Artificial Intelligence and Applied Informatics
 *                    Computer Science VI, University of Wuerzburg
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 3 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
 
}}}
You can do this automatically by adding [codetemplates.xml] in Eclipse: ''Window'' -> ''Preferences'' -> ''Java'' -> ''Code Style'' -> ''Code Templates'' 
!First check-in

You have to perform the first check-in using the chosen main repository (c.f. above).
* Right click the main project → Team → Commit.
* Now __exclude the folders {{target/}} and {{.settings/}}__! (Uncheck the check boxes)
* Enter your commit message → Commit.

Now you can enable SVN access directly for your newly created project: Perform a right click on the new project → Team → Share.
Select SVN, you will find the repository location already set up. Hit Finish.

To complete the process, you have to ignore {{target/}} and {{.settings}} permanently. Select both folders in the Project Explorer with Ctrl/Command, right click → Team → Add to svn:ignore. Click OK in the window that opens.

Finally, commit the ignore settings: right click → Team → Commit. Done.

!!Why isn't Plugin X included in my Build?
[{Image src='attach/Developer%20FAQ/m2eclipse-plugins.png' width='232' height='202' align='right' link='http://d3webwiki.informatik.uni-wuerzburg.de/attach/FAQ/m2eclipse-plugins.png'}]

You need to enable the plug-ins you want to build into KnowWE when using Eclipse. Here's how:

Open your Run Configuration for the KnowWE build and add parameters for the plug-ins you want to have in the goals section.

For instance: You want to enable the Comment plug-in. Here, you have to add a {{comment-plugin}} parameter. List all the profile names for the Plug-ins you want to add in the Profiles Section and build KnowWE.

See the screenshot on the right for another example.

!!Why does Eclipse not catch breakpoints?
This Issue is caused by an outdated JDK. Please update your JDK to the [latest Version | http://www.oracle.com/technetwork/java/javaee/downloads/index.html].

<tags>workspace problems FAQ </tags>

!!Why do i get a java.util.MissingResourceException: Can't find bundle for base name Exception?
This happens after cleaning the workspace.

Solution: For each of the two maven super projects (d3web, d3web-KnowWE), select the project, right click on it, "Run as...", "Maven package".

!!!What do I need to do after I change a .java file?
Usually you only have to refresh your browser page. Hot Code Replacement makes your changes effective at runtime. 


!I'm done editing. How to make my changes permanent?
You don't have to worry that you changes will be lost after you shut down KnowWE. To make the changes effective for the next restart, you have to perform Maven Install on KnowWE-App.

!Hot Code Replacement failed. What to do?
Sometimes, especially when doing major changes to a .java file, Hot Code Replacement fails. In this case you have to 
*Quit Tomcat
*Perform a Maven Install on KnowWE-App and
*Start Tomcat again.


!!!What do I need to do after I change a Non-Java file?
Unfortunately, there is no Hot Code Replacement for Non-Java files. However, there is a [How-To for developing Javascript at runtime|http://denkbares.dyndns.org/d3web/Wiki.jsp?page=How-To%20Develop%20JavaScript%20in%20KnowWE], which may be useful for you.

How to make changes to Non-Java files effective:
*Quit Tomcat
*Perform Maven Install on your plugin aswell as KnowWE-App
*Restart Tomcat

!!!Tomcat successfully starts, but the wiki pages are not loaded. What to do?
This can happen when you perform a Maven Install while Tomcat is still running. To fix this, you have to follow these steps:
*Right click on KnowWE-App in Eclipse and select
{{{Tomcat > Update Tomcat Context}}}
*Start Tomcat

!!Offline Build (if Artifactory is not available or you have no Internet connection)

Create a second runtime configuration for building KnowWE, just like shown here: [http://d3webwiki.informatik.uni-wuerzburg.de/Wiki.jsp?page=Workspace#section-Workspace-CreateARunConfigurationForBuildingTheWiki], just check the "Offline" checkbox. __Note__: Do not enable this option for your regular build, only use it if Artifactory is down or you are not connected to the internet!

!! Why are Umlauts viewed uncorrectly?

Tomcat can be configured in UTF-8 to handle Umlauts correctlty. Look at [http://www.jspwiki.org/wiki/BugProblemsWithGermanUmlaute]
//End Old

What... ? and Why...? Questions\\
Coordinate with How-To

%%Todo 
Set this page up, add table of contents and some introductory words. Every question is its own small headline with the answer directly below.

@user: Christian Henniger
%

%%Todo 
Developer FAQ
* Define questions
* Answer questions, get the information if unkown
* Get and update/improve stuff from old pages: [http://d3webwiki.informatik.uni-wuerzburg.de/Wiki.jsp?page=FAQ]

@user: Christian Henniger
%

%%Todo 
Developer FAQ
* Some examples:
** What do I need do mvn install, after I change a java file or non-java file?
** Tomcat starts, but wikipages are not loaded -> update Tomcat-Context... this happens when mvn installing while tomcat is running...
** What is an plugin, what is an extension, what is an extension point ([http://d3webwiki.informatik.uni-wuerzburg.de/Wiki.jsp?page=Plugins%20and%20Extensions])
** What is the Scope of an extension

@user: Daniel Zügner
%