This is version 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 . It is not the current version, and thus it cannot be edited.

Back to current version Restore this version

Prerequisites#

• Java Development Kit (JDK), choose the latest Version of Java 8.
• Apache Tomcat 7
  Use the "Binary Distribution" - "Core" - .tar.gz or .zip. Do not use the installer. Do not use Tomcat 8

• IntelliJ IDEA
  You might get a community key for the Ultimate Edition. Please ask via dev list.

or

• Eclipse IDE for Java EE Developers

IntelliJ IDEA#

First time starting IDEA#

When you first start IDEA you can choose which plugins to enable/disable. Just leave everything enabled to be on the safe side.
After that choose "New Project" and then "Empty Project". Give it a name and hit "Ok".

Auto-Import Maven Modules#

Set IntelliJ to automatically import checked-out or created maven modules: Settings -> "Maven" -> "Importing" -> activate "import maven projects automatically"

Import Repositories#

Select "VCS -> Checkout from Version Control -> Subversion".

Add following repositories by clicking on the "+"-Symbol: Read/write access (account necessary):

To get an account, please contact info@d3web.de. Accounts on d3web.de are independent from the SVN accounts.

Anonymous access (read only):

Select the three main projects (d3web, KnowWE, and Research) as well as KnowWE-App from inside the trunks of the three repositories. They are in the trunk/folders respectively. One by one, right click one the projects and select Check out and choose your Idea project folder. After that, select the following path $yourprojectname/$projectparent (usually the one in the middle). When IDEA has finished checking everything out, select "File -> Import module" and choose your project path. You get asked which module to import, choose "Maven" and hit "Next". In the next screen select "local" and "core-plugins" and hit "Next. Select your Java SDK and click "Finish".

Building and starting KnowWE#

Select "Run -> Edit Configurations" and add "Tomcat Server -> local". Hit configure and choose your tomcat path. In den bottom pane click "+" and choose "Build Artifacts". Select "KnowWE-App:war exploded". Click on the "Deployment" tab and add "KnowWE-App:war exploded". Select as Application Context "/KnowWE" and click on "Ok". Build KnowWE by clicking on the green arrow right next to our new tomcat configuration.

Transitioning from Eclipse to IntelliJ IDEA#

The d3web/KnowWE community started developing with Eclipse, but recently some of our developers are transitioning to IntelliJ IDEA. If you are considering to transition yourself, you might find the following article helpful: IntelliJ FAQ

Eclipse#

To make Eclipse work with Subversion, Tomcat and Maven, you will need a few additional plug-ins.

Installing Plugins#

Navigate to Help -> Eclipse Marketplace. Search for "Subversive" and install the most recent "Subversive - SVN Team Provider", e.g. 2.0.1. Click "Install" and follow the instructions. Accept the licenses, and finish the installation. Restart Eclipse when you are asked to.

Java 8 Support#

For eclipse versions Kepler (and later?!), you need to install Java 8 support manually. Do so by following the instructions here: https://wiki.eclipse.org/JDT/Eclipse_Java_8_Support_For_Kepler

Selecting the SVN implementation#

After restarting Eclipse, click on Window -> Open Perspective -> SVN Repository Exploring. A dialog window will be opened asking you to select an SVN connector implementation. Select SVNKit 1.8.7 (or the latest available SVNKit version of the 1.8 branch, not 1.7 ) and finish the installation wizard.

You need to accept installing unsigned software, and restart Eclipse again when asked.

Sysdeo Tomcat Plug-in

The Sysdeo Tomcat Plug-in allows you to start Tomcat directly from within Eclipse. You can find it at http://www.eclipsetotale.com/tomcatPlugin.html.

To perform the installation, download the .zip file provided at the author's homepage and unpack it into the plugins/ folder inside your Eclipse installation.

The KnowWE-App project is preconfigured for use with this plug-in.

Preparing your workspace#

Eclipse settings#

Start arguments:
Maven needs Eclipse to run in a JDK, not in a JRE. Start Eclipse with the -vm parameter, for example:
"C:\Program Files\eclipse\eclipse.exe" -vm "C:\Program Files\Java\jdk1.8_xxx\bin\javaw.exe"

You can find the following Eclipse settings in the main menu at Window -> Preferences.

Encoding: General -> Workspace -> Text file encoding: "UTF-8"

Comment format:

Get the codetemplates.xml attached to this page and import it: Java -> Code Style -> Code Templates

Enable: Automatically add comments for new methods and types

(If your login name is not meaningful, you have to change the comment template for Type, as your login name is used as author name)

Code format settings:
Get the code_conventions.xml attached to this page and import it: Java -> Code Style -> Formatter

To enable automatic formatting, certain actions have to be carried out on saving: Java -> Editor -> Save Actions

The screenshot on the right shows the actions, that have to be activated.

Tomcat plug-in:
Tomcat -> Tomcat Version: Select your Tomcat version here
Tomcat -> Tomcat Home: Choose the directory where you unpacked the Tomcat zip
Tomcat -> Context declaration mode: "Context files" (do not select server.xml!)
Tomcat -> JVM Settings -> JRE: check that the correct JRE is selected

optional: Set larger heap size for tomcat:
Window -> Preferences -> Tomcat -> JVM Settings -> add to JVM parameters -> set for example: -Xmx1g
Read for your exact personal settings: http://javahowto.blogspot.com/2006/06/6-common-errors-in-setting-java-heap.html

recommended: Set Tomcat to use UTF-8 (necessary for special characters like german umlauts in page names for example):
You have to edit server.xml of Tomcat (is in the conf-directory of Tomcat). Please add to

<Connector port="8080"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" redirectPort="8443" acceptCount="100"
               debug="0" connectionTimeout="20000" 
               disableUploadTimeout="true"/>

the term URIEncoding="UTF-8".
It should look like that:

<Connector port="8080"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" redirectPort="8443" acceptCount="100"
               debug="0" connectionTimeout="20000" 
               disableUploadTimeout="true" 
               URIEncoding="UTF-8"/>

Further information: http://www.jspwiki.org/wiki/BugProblemsWithGermanUmlaute

Adding the SVN repositories#

Window -> Open perspective -> Other… -> SVN Repository Exploring.

Repeat the following step for each of the listed repository URIs:
In the SVN Repositories view, perform a right click, select New -> Repository Location...

Read/write access (account necessary):

To get an account, please contact info@d3web.de. Accounts on d3web.de are independent from the SVN accounts.

Anonymous access (read only):

Checking out the code#

Select the three main projects (d3web, KnowWE, and Research) as well as KnowWE-App from inside the trunks of the three repositories. They are in the trunk/folders respectively. One by one, right click one the projects and select Check out and click Finish.
After downloading, you have to import the downloaded folders as maven projects. Go to File -> Import -> Maven -> Existing Maven Projects. Select the parents with all the child poms and click import. After checking out and importing the maven projects, Eclipse may make some changes to the .classpath-files of the projects, which should be reverted. Switch back to the Java perspective, click the three main projects (d3web, KnowWE, and Research) and select Team and then Revert... . If you now

JSP Problems#

Eclipse EE will find a lot of JSP Problems and display them in the Markers tab. You can ignore them, they are found because of the way we extend JSPWiki. To get rid of them long term, right click on the project KnowWE-Resources and select Properties. Go to Validation and select "Enable project specific settings". Now, deactivate the checkboxes Build for "JSP Syntax/Context Validator". The checkboxes "Manual" can remain checked.
If you now right click on the JSP Problems in the Markers tab, you can delete all of them. They will stay deleted unless you build manually.

Building KnowWE#

Create local preferences for JSPWiki#

Copy KnowWE-App/src/resources/local/WEB-INF/jspwiki.properties.default to jspwiki.properties in the same directory. Do not rename it in Eclipse.
In jspwiki.properties, edit the settings for your local environment. The three most important settings are at the top.

Install KnowWE-Resources#

Right click 'KnowWE-Resources' project -> Run as -> Maven install

Install main projects#

One by one, right click the main projects d3web, KnowWE, Research and select Run As and then "Maven install". Wait for the for the current one to finish before you install on the next one.

Create a run configuration for building the wiki#

Right click on "KnowWE-App", select Run as -> Maven build….
A dialog will show. Set the following settings:
Goals: clean install
Profiles: local core-plugins
Enable checkbox "Resolve Workspace artifacts"

Updating the Tomcat context#

Right click on "KnowWE-App" -> Tomcat project -> Refresh context in Tomcat

Starting KnowWE#

You can now start Tomcat using the Start tomcat toolbar button or menu entry. Open the following URI in your browser:

Troubleshooting#

Slow/unresponsive eclipse and increasing heap space for eclipse#

If you are experiencing a really slow reaction and work speed of eclipse, you can try increasing the heap space of eclipse. This is especially relevant, if you have checked out the complete d3web, KnowWE and Apps projects or use Java 7 for eclipse, which also seems to use more memory. Go to the eclipse.ini in your eclipse installation and add/adapt the lines for the vm arguments. It could look something like this:

-vmargs
-Xms512m
-Xmx2g

The line breaks are important! -Xmx2g says, that eclipse can use up to 2GB of RAM. These 2 GB are recommended, but if you do not have that much to spare, something around 1500m is also ok.

OutOfMemoryError while installing with Maven#

Since Java 7, building parent projects like Research may cause OutOfMemoryErrors:

[ERROR] Consult the following stack trace for details.
[ERROR] java.lang.OutOfMemoryError: PermGen space
[ERROR] at java.lang.ClassLoader.defineClass1(Native Method)
[ERROR] at java.lang.ClassLoader.defineClass(ClassLoader.java:791)
...

To solve this, you have to add some arguments for the Java Virtual Maschine in your run configuration.
In the run configuration explorer (available for example via right click on a project an then "Run As" and "Run configurations...") select the run configuration which produces the error and select the tab "JRE". In the text area "VM arguments" add the following statements:

-Xmx2g -XX:MaxPermSize=512m

Compile errors after first build#

Sometimes you get errors like:

Cannot nest output folder 'd3web-Distributed/target/classes' inside output folder 'd3web-Distributed'	

If this happens, close and open all affected projects. Alternatively, you have to do the following steps:

1. Remove the affected projects from the workspace without deleting them, by selecting 'Delete' from the context menu and unchecking the checkbox.
2. Import the project back to the workspace:
   1. Menu: File->Import...
   2. General: Existing projects into workspace
   3. As root directory select the project directory itself, e.g. <workspacedir>\d3web-KnowWE\d3web-distributed.
   4. Select the project in the list.
   5. Click 'Finish'.
3. Repeat step 2 for every project that was affected.

ClassCastException on startup#

You might encounter the following exception:

java.lang.ClassCastException: org.apache.catalina.util.DefaultAnnotationProcessor cannot be cast to org.apache.AnnotationProcessor 

Workaround: In the folder where you unpacked Tomcat (e.g. /usr/local/apache-tomcat-6.0.20/) you can find a directory called conf. In there is context.xml. Add follwing statement into the <Context> element:

(Related upstream bug)