Protege Wiki - User contributions [en]

Stanford:DeveloperGuide

2011-06-05T08:47:51Z

Johner: /* Maven */

=In a nutshell=
You work as you typically work just using Eclipse to develop and test. There are only a few things you need to consider:
* The initial setup of your Eclipse project is done with Maven.
* Prefer TestNG over JUnit in order to write unit tests.
* We encourage you to write UI tests using the Selenium framework.
* We encourage you to deploy your artifacts not just to the file system (local Maven repository) but also to the central Nexus repository, at least if you have the privileges to do so.

And don’t forget to update and commit to/from on a daily basis.

=How to start from scratch=
==Downloads and Installs==
[[Image:eclipse-jdk.png|thumb|Use the JDK instead of the JRE]]
===JAVA===
* Download and install java.
* Set environment setting <tt>JAVA_HOME</tt> pointing to the java folder, e.g. <tt>C:\Program Files\Java\jdk1.6.0_21\bin</tt>.

===Maven===
* Download Maven from http://maven.apache.org/download.html und chose apache-maven-2.2.1.
* Add system environment variable M2_HOME pointing to new directory apache-maven-2.2.1
* Add to Path <tt>;%M2_HOME%\bin</tt>
* Modify <tt>/conf/settings.xml</tt>: Path to Nexus and you operating system. There is an [[Stanford:SettingsXmlExample|example page for a settings file]].

If you update to Maven 3, there is no need to update the scripts (pom.xml).

===Eclipse===
* Download, extract and start eclipse
* Install subclipse plugin (update site is http://subclipse.tigris.org/update_1.6.x). Check all options, otherwise the SCM handler of Maven will be missing.
* Install GWT plusing (update site is http://dl.google.com/eclipse/plugin/3.6) with Helios 3.6, otherwise 3.5
* Install m2eclipse plugin (Update site is http://m2eclipse.sonatype.org/sites/m2e)
* Optional: Install m2eclipse extra plugin (Update site is http://m2eclipse.sonatype.org/sites/m2e-extras). Select Maven SCM handler for Subclipse and Maven SCM integration.
* Let Eclipse know the location of your installed JDK (nor JRE!)
* Start Eclipse with JDK (not JRE!) as described in http://help.eclipse.org/help33/index.jsp?topic=/org.eclipse.platform.doc.user/tasks/running_eclipse.htm. Example:
"C:\Program Files\eclipse-jee-helios-SR1-win32\eclipse\eclipse.exe" -vm "C:\Programme\Java\jdk1.6.0_21\bin\javaw.exe"

===Firefox & GWT plugin (only for GWT UI testing)===
After download and install of Firefox we recommend adding a new profile. Rationale: Selenium typically initiates a new Firefox profile which is missing the GWT Firefox plugin. Therefore we generate a new one:
* Open command window and go to Firefox directory
* Execute firefox -P. Plugin manager shows up.
* Add new profile and chose a directory, e.g. one Protégé related.
* Start Firefox and start eclipse. Open page http://127.0.0.1:8888/WebProtege.html?gwt.codesvr=127.0.0.1:9997. This prompts you to install the GWT plugin.
* Save the profile

===Selenium (only for GWT UI testing)===
Please refer to chapter in section administration. TODO add link.

Start server with <tt>java –jar selenium-server.jar -firefoxProfileTemplate <Path2Profile></tt>. <Path2Profile> is the folder you were choosing when creating the new profile.

Example:

C:\Users\DrCJ\selenium-server-1.0.3>java -jar selenium-server.jar -firefoxProfileTemplate c:\Users\DrCJ\firefoxprofile

==Start working with a project e.g. with Protégé==
===Option 1: import project using Subclipse (preferred)===
Pretty straight forward
* Import project from repository using Subclipse.
** File > Import > SVN > SVN Projects. Import desired project and branch.
** Use “Create Project wizard”, use “Next” instead of “Finish” button and add a new source folder “src/main/java” and remove “src” from build path.
** Copy imported files from src to “src/main/java” folder. There will be problems, since libraries are missing. Do not tweak build path, this will be done automatically in the next step.
* Execute mvn eclipse:eclipse from command line
* Refresh project (F5)

To update classpath (e.g. if there is a new jar (as defined in the pom.xml)) just repeat these steps.

If there are still libraries missing (which are obviously defined in your pom.xml), please consult with your project manager or upload the artifacts to the respository as described in the project manager guide.

[[Media:Import-Project.flv|import project using Subclipse (video tutorial)]]

{|
| [[Image:eclipse-checkout-maven.png|thumb|upright|alt=Maven can be used to check out the project|Maven can be used to check out the project]]
| [[Image:eclipse-import-project.png|thumb|upright|alt=Or use SVN to download. Then call mvn eclipse:eclipse and import project|Or use SVN to download. Then call mvn eclipse:eclipse and import project]]
| [[Image:eclipse-gwt.png|thumb|upright|alt=make project to become a GWT project|make project to become a GWT project]]
| [[Image:eclipse-gwt-2.png|thumb|upright|alt=Set the webapp folder for the GWT compiled code|Set the webapp folder for the GWT compiled code]]
|}

===Option 2: import project from command line (using a SVN client)===
* Download project from repository with Tortoise or other (command line based) SVN client
* Execute mvn eclipse:eclipse from command line
* Refresh project (F5)

To update classpath (e.g. if there is a new pom.xml) just repeat these steps.

===Option 3: using the m2eclipse plugin===
Chose “Project” from the “File” menu, select Maven and then “Checkout maven Projects from SCM”.

===Configure GWT plugin===
* Select Project Properties and check under Google “Use Google App Engine”
* In project properties set plugin as active and change WAR directory to be /src/main/webapp (there is no longer a /war directory!)

=Questions that may arise during development=
==How do I work with multiple projects in parallel==
To given an example: We work with projects A and B where B depends on A. (An example would be A = Protégé, B = WebProtégé.)

Assuming you would like to make a change to project A which is required to continue working with project B:

# Make the change in project A
# Go to the command line in project A's directory (e.g. in <tt>/home/<USER_NAME>/workspace/projectA</tt>) and enter <tt>mvn install</tt> [1], [2]. This will update your local Maven repository (M2_REPO) which typically is located in <tt>/home/.m2/repository</tt> respectively in <tt>c:\user\<username>\.m2\repository</tt>. [1]
# Go to the command line of project B and enter <tt>mvn eclipse:eclipse</tt> [2]. This will update the classpath and (re)load the artifact of project A.
# Continue developing in project B.

Actually there are two variants:
# Variant 1: you do not change the version number of the artifact of project A. In this case you do not have to modify the version number in project A's pom.xml. This is an advantage, another advantage is that you do not need to update the dependency section in the pom.xml of project B.
# Variant 2: you change the version number of the artifact of project A in the project A' pom.xml. This requires that you update the version in the dependency section in project B's pom.xml. The advantage of this variant is that you easily can switch back to the old version of project A's artifact, you even can have multiple versions in your repository.

The dependency section in the pom.xml the text above is refering to looks like:

<syntaxhighlight lang="xml">
<dependency>
<groupId>protege</groupId>
<artifactId>protege-core</artifactId>
<version>3.4.2</version>
</dependency>
</syntaxhighlight>

[1]: If you want to skip the unit tests use <tt>mvn install -DskipTests=true</tt> instead.

[2]: Alternatively you can use the m2eclipse plugin.

==How do I deploy my artifacts to the (central) Nexus repository==
First you have to have write privileges to BMIR's Nexus repository (http://bmir-hudson1.stanford.edu/nexus). Typically these privileges are only granted to a closed group of developers. Both, these privileges (-> credentials) and the path to the repository have to be entered to your Maven settings file (<tt><MAVEN_INSTALL_DIR>/conf/settings.xml</tt>). There is a [[Stanford:SettingsXmlExample|complete example of this file]] available.

As soon you execute <tt>mvn deploy</tt> the Nexus repository is updated. Please keep in mind that your artifact either is stored in the snapshot or in the release repository dependent on the version number in your pom.xml: If the version number ends with <tt>SNAPSHOT</tt> the snapshot directory is addressed, otherwise the release repository.

Keep in mind that...
* the SNAPSHOT repository allows the redeployment of an artifact (with the same version number), the release repository doesn't,
* a deployment (<tt>mvn deploy</tt>) to the SNAPSHOT repository will autoincrement the version number of your artifact (if not explicitly turned off in the pom.xml), a deployment to the release repository won't.
* there is no autoincrement of the version number during install (<tt>mvn install</tt>),
* there is no need to install a local Nexus repository on your machine.

==How to update classpath==
Just get latest pom.xml and execute mvn eclipse:eclipse. This will update (not overwrite) your classpath. Press refresh in Eclipse. There is not even a restart necessary.

=How to write unit test case (TestNG, JUnit) and UI test cases (FEST, QFS)=
This section is about standard unit tests, i.e. not about writing UI tests/integrations tests using Selenium.
==How to re-use existing JUnit test cases==
===Option 1: Convert JUnit test cases to TestNG test cases===
You either can do that programmatically as described in http://testng.org/doc/migrating.html or you do that manually. TestNG tests look pretty much the same then JUnit tests. What has to be done typically includes:
* Change <tt>import to org.testng.annotations.*;</tt> and <tt>import static org.testng.Assert.*;</tt>
* Add annotation <tt>@BeforeClass</tt> to setup-method.
* Add annotation <tt>@Test</tt> to your test methods

===Option 2: Keep JUnit tests cases as they are and run it from TestNG===
In the <tt>/src/test/resources/unit-tests.xml</tt> there is a section with <tt>junit=true</tt>. Just add your tests there.

Example (mind second set of tests)

<syntaxhighlight lang="xml">
<!DOCTYPE suite SYSTEM "http://testng.org/testng-1.0.dtd" >
<suite name="ProtegeTestSuite" verbose="1">
<test name="TestNG-Tests">
<classes>
<class name="edu.stanford.bmir.protege.web.server.WatchedEntitiesCacheTest"></class>
<class name="client.TestUnitProtege"></class>
</classes>
</test>
<test name="JUnit-Tests (Example)" junit="true">
<classes>
<class name="client.JUnitExample"></class>
</classes>
</test>
</suite>
</syntaxhighlight>

There are (theoretically) two options how to include JUnit tests cases to the continuous integration.
# Make sure that your test classes are in the designated folder /src/test/java and that they are following the naming convention *Test.java
# Specify the classes in the xml file in /src/test/resources
We decided to go for the latter option. All types of specification as test parameters, grouping of tests and running tests in parallel have to be defined in theses TestNG-XML-files (and not(!) in the pom.xml). In the pom.xml we deliberatly disabled the automatic execution of JUnit tests in the line

<syntaxhighlight lang="xml">
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<skip>true</skip>
</configuration>
...
</plugin>
</syntaxhighlight>

==Write new TestNG test cases==
The vest resource to start is http://www.testng.org. Nevertheless the following lines might be helpful:

It is recommended to use the TestNG plugin for Eclipse since it adds all libraries to your classpath. Then writing a new test case is straight forward:
* write a standard Java class. Even there is no naming convention required it is recommended to call the class XXXTest, whereas XXX stands for the class under test.
* Write some test methods. Even there is no naming convention required it is recommended to call the method testXXX, whereas XXX stands for the method to be tested. However the test methods require the annotation @Test.
* Optionally have methods which have to be executed one before the test class is executed respectively which are executed before each test method. Add annotations @BeforeClass, @AfterClass, @BeforeMethod, respectively @AfterMetehod
* Fix imports

<syntaxhighlight lang="java">
import junit.framework.Assert;
import org.testng.annotations.AfterClass;
import org.testng.annotations.BeforeClass;
import org.testng.annotations.Parameters;
import org.testng.annotations.Test;
</syntaxhighlight>

* Optional enhancements
** Add dependencies between methods e.g. <tt>@Test (dependsOnMethods = {"openICDTree"})</tt> where openICDTree is the name of the other method.
** Move test parameters from test code to the configuration file, e.g.

<syntaxhighlight lang="xml">
<test name="Navigation 1">
<parameter name="username" value="protege"/>
<parameter name="username" value="secret"/>
<classes>
<class name="selenium.TestICat"></class>
</classes>
</test>
</syntaxhighlight>

* Refer to these parameters in the Java code
<syntaxhighlight lang="java">
@Test
@Parameters({ "username", "password" })
public void login(String username, String password) throws InterruptedException {...}
</syntaxhighlight>

* Add new test case to the test-configuration xml as shown above.

==How to write UI test cases (web) with Selenium==
===General===
The UI tests use the Selenium test framework. You either can write the tests from scratch or use the Selenium IDE, a Firefox Plugin to record actions and to generate Java Code (TestNG classes).

The biggest challenge with writing UI tests is the identification of UI components since one can not relay on the id of the component. These ids are generated by GWT dynamically.

===Example Code===
s. example.
===How to locate UI elements===
s. example.
===Resources===
* How to locate elements
** General: http://seleniumhq.org/docs/04_selenese_commands.html#locating-elements
** Usefull X-Path patterns: http://seleniumhq.org/docs/appendix_locating_techniques.html#useful-xpath-patterns
** X-Path in general: http://www.w3schools.com/xpath/xpath_examples.asp
** Calendars, Comboboxes, Popup etc: http://www.ibm.com/developerworks/opensource/library/os-webautoselenium/index.html?cmp=dw&cpb=dwope&ct=dwnew&cr=dwnen&ccy=zz&csr=120910

==Comprehensive example==
There is a project that shows everything related to build and testing:
* how to write a pom.xml
* how to write and integrate unit tests (JUnit and TestNG)
* how to write and integrate integration tests (selenium)

Please visit https://bmir-gforge.stanford.edu/svn/hudson-test/Hudson-Test.
==How to write UI test cases (Swing) using FEST==
The tutorial on how to write FEST tests will be written upon decision for/against FEST. So far please refer to the official documentation: http://docs.codehaus.org/display/FEST/Getting+Started

The "Example-Project" (Hudson) also contains a demo application using FEST: https://bmir-gforge.stanford.edu/svn/hudson-test/Hudson-Test

==How to write UI test cases (Swing) using QF-Test==
The tutorial on how to write QFS tests will be written upon decision for/against QFS. So far please refer to the official documentation:
http://www.qfs.de (tutorials in English available).

=Other questions=
==How to switch to ICD11 with all data (database)==
Follow instructions given in http://groups.google.com/group/icat-users/web/accessing-the-icat-content-programmatically?hl=en&_done=%2Fgroup%2Ficat-users%3Fhl%3Den%26&hl=en

On Windows the import command might be slightly different than described in the website. Use instead
mysql --user=protege --password=protege < c:\protege_2010-11-01_04h02m.Monday.sql

In summary you need to
* import database (and check that protege DB acutally exists afterwards)
* add user
* grant rights to the user

In order to do so, make use of the follwing commands:
mysql -u root
mysql> -u root connect to localhost;
mysql> show databases;
mysql> use protege;
mysql> show tables;
mysql> CREATE USER protege IDENTIFIED BY 'protege';
mysql> GRANT SELECT, INSERT, UPDATE, DELETE on *.* to 'protege'@'localhost';

More useful commands: http://www.pantz.org/software/mysql/mysqlcommands.html

[[Category:QualityAssurance]]

ProtegeQAGuide

2011-06-05T08:46:26Z

Johner: /* Contact and further Information */

This is the start page on how to (automatically) build and test all applications/projects related to Protégé.

=Guidance Documents=
[[File:infrastructure-2.png|thumb|Infrastructure with all servers and information flow]]

{| border="1"
| On the <span style="font-variant:small-caps;font-size:1.3em;font-weight:bold">[[Stanford:OverviewPage|Overview Page]]</span>
you find
* some background information describing the rationale for caring about automated builds and testing and for establishing a corresponding infrastructure.
* an overview chart displaying the entire infrastructure landscape.
* a short description of all the relevant tools and the rationale for chosing the selected ones

| The <span style="font-variant:small-caps;font-size:1.3em;font-weight:bold">[[Stanford:AdministratorGuide|Administrator Guide]]</span> (→ Alex)
describes how to install and operate all the servers, among those:
* Nexus repository: http://bmir-hudson1.stanford.edu/nexus
* Hudson Build Sever (build statistics, administration of jobs): http://bmir-hudson1.stanford.edu
* Sonar Server (code and architecture metrics, coverage reports and more): http://bmir-hudson1.stanford.edu/sonar (use link from Hudson to Sonar reports instead)
* Tomcat Server (automated UI testing, not of general interest): http://bmir-hudson1.stanford.edu:8080
* SVN-Repository: http://smi-protege.stanford.edu/repos/protege/

|-
| The <span style="font-variant:small-caps;font-size:1.3em;font-weight:bold">[[Stanford:DeveloperGuide|Developer Guide]]</span> (→ external and Stanford internal)
is the main page for developers. On these pages developers get answers to questions like
* How do I initially set up my tools to work with one or more of the Protégé projects?
* <strong>New:</strong> Please watch video tutorial.
* How do I write test cases?
* How do I get the lastest downloads?

| The <span style="font-variant:small-caps;font-size:1.3em;font-weight:bold">[[Stanford:QaGuide|QA & Project Manager Guide]]</span> (→ Tania, Jennifer, Tim & other)
is the address for everybody interested in the success and quality of builds and code. It gives explanations like
* How to write/adjust the pom.xml?
* What do these metrics tell me?
* What do I have to do in order to add artifacts (e.g. jar-files) to my repository
|}

=Contact and further Information=
The selection, installation and testing of the infrastructure as well as the initial transistion from traditional ANT-based to Maven based projects was done by [mailto://c.faigle@gmx.net Christian Faigle] and [mailto://mail@johner.org Christian Johner]. Please contact either for questions related to
* Selection of tools
* Administration of tools
* Converting projects to MAVEN
* Interpretation and adaptation of reports

This page originally was written by [mailto://christian@johner.org Christian Johner], [http://www.johner-institut.de Institute for Healthcare IT].

The [[Stanford:ToDoPage|Todos]] (for Christian, Alex)

Stanford:QaGuide

2011-01-06T16:32:07Z

Johner: /* My build fails since the sonar plugin was not found! What can I do? */

=How-to for architects, test and project managers=
==Target audience and scope==
In this section you find how tos which are related to convert projects from ANT to Maven, to write pom.xml files etc.
==Comprehensive example==
There is a project that shows everything related to build and testing:
* how to write a pom.xml
* how to write and integrate unit tests (JUnit and TestNG)
* how to write and integrate integration tests (selenium)

Please visit https://bmir-gforge.stanford.edu/svn/hudson-test/Hudson-Test.

=How to create a new or convert an existing project =
This steps steps have to be done once per project)
==Establish or change to Maven directory structure==
The following is copied from http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html. It documents the directory layout expected by Maven and the directory layout created by Maven. Please try to conform to this structure as much as possible; however, if you can't these settings can be overridden via the project descriptor.
{| border="1"
!Path
!Description
|-
|'''src/main/java'''
| Application/Library sources
|-
|'''src/main/resources'''
| Application/Library resources
|-
|src/main/filters
| Resource filter files
|-
|src/main/assembly
| Assembly descriptors
|-
|src/main/config
| Configuration files
|-
|'''src/main/webapp'''
| Web application sources
|-
|'''src/test/java'''
| Test sources
|-
|'''src/test/resources'''
| Test resources
|-
|src/test/filters
| Test resource fiter files
|-
|src/site
| Site
|-
|LICENSE.txt
| Project's license
|-
|NOTICE.txt
| Notices and attributions required by libraries that the project depends on
|-
|README.txt
| Project's readme
|-
|}

In the table the most relevant paths are marked bold.

Additionally there are at the top level
* pom.xml
* other optional files as properties, maven.xml or build.xml (if using Ant).

In order to get to the new file structure:
* Add folder inside /src: <tt>/src/main/java and /src/test/java</tt>
* Move <tt>/src/edu</tt> respectively <tt>/test/edu</tt> folders into new folders.
* Delete folder test-lib
* Rename “war” to “webapp” and move folder under /src. (here I ran into problems. Really the best way?)
* Add folder <tt>/src/main/resources/config</tt>. Add to this folder <tt>configuration.properties</tt> file.
* Add under <tt>src/test/java</tt> following folders: <tt>/client/</tt> and <tt>/selenium</tt>??
* Delete files in root folder with exception of src. Delete e.g. /etc/,

To move files/directories you can use Tortoise as described in http://stackoverflow.com/questions/62570/how-do-i-move-a-file-or-folder-from-one-folder-to-another-in-tortoisesvn.

'''Hint:''' In the developer guide there is a description how to import a project from SVN and immediatelly update the src-folder to the expected structure.

==How to upload required artifacts (typicall jar-files) to Nexus repository==
There are multiple ways of adding resources to the repository
# Direct copy ('''not recommended''')
#* Copy resources directly to Nexus subfolder e.g. to <tt>/var/nexus/sonatype-work/nexus/storage/thirdparty/edu/stanford/bmir/core/icd</tt>.
#* You need to put the file the right directory and give it the name indicating the version number, e.g. <tt>/edu/Stanford/bmir/core/protégé-1.0.jar</tt>
#* Goto nexus and right click on third party repository: reindex respectively rebuild metadata
# Uploaded file automatically in due course of a build process (this is '''recommended''' for "own" code as Snapshots and Releases).
#* There is nothing to do besides adding the <distributionManagement> tag to the pom.xml and use the deploy plugin. The PC specific <tt>settings.xml</tt> has to point to the repository as described in the adminstrators guide in section TODO
# Uploaded file using the Nexus interface ('''recommended only for third party artifacts'''). This option is described in the following:

{|
| [[Image:nexus-upload-1.png|thumb|upright|alt=Screenshot how to upload jars to Nexus (step 1)|upload an artifact to Nexus (part 1): Select repository]]
| [[Image:nexus-upload-2.png|thumb|upright|alt=Screenshot how to upload jars to Nexus (step 2)|upload an artifact to Nexus (part 2): Define GAV parameters]]
| [[Image:nexus-upload-3.png|thumb|upright|alt=Screenshot how to upload jars to Nexus (step 3)|upload an artifact to Nexus (part 3): Reindexing]]
| [[Image:nexus-get-dependency.png|thumb|upright|alt=Screenshot how copy the dependency snippet for pom.xml|copy the dependency snippet for pom.xml]]
|}

For each artifact (jar) you can later copy the dependency information for Maven (into the pom.xml). The code snipped look like:

<dependency>
<groupId>edu.stanford.bmir.core</groupId>
<artifact>protege</artifact>
<version>1.0</version>
</dependency>

TODO: define naming convention for groupId. Currently discussed are the following
* protege3
* protege4
* webprotege
* owl

Further reading
* http://www.sonatype.com/books/nexus-book/reference/maven-sect-single-group.html
* http://www.sonatype.com/books/nexus-book/reference/maven-sect-single-group.html
* http://stackoverflow.com/questions/1584763/how-do-i-deploy-to-nexus-hosted-by-secureci

==How to write the Maven script (pom.xml)==
In our case the pom.xml typically will have the following structure:
* Some general information e.g.

<modelVersion>4.0.0</modelVersion>
<groupId>edu.stanford.smi.protegex</groupId>
<artifactId>dlquery</artifactId>
<packaging>jar</packaging>
<name>protege-plugin-dlquery</name>
<version>0.0.3-SNAPSHOT</version>

* Properties as the Java version
* the <tt><distributionManagement></tt> tag which is necessary if artifacts have to deployed to a repository
* the <tt><dependency/></tt> tags (an example was given above)
* the build part with its plugins (e.g. to compile, test, deploy)
* the reporting part with its plugins (e.g. PMD, Findbugs, JDepend)

It is recommended to use an existing <tt>pom.xml</tt> as template.

Further hints and readings:
* the version number can be automatically adjusted with a version plugin. The postfix "<tt>SNAPSHOT</tt>" determines that the artifact won't be uploaded to the release but to the snapshot repository.
* Both repositories (snapshot and release) are defined in the <tt><distributionManagement></tt> section respectively in the <tt>/maven/conf/settings.xml</tt> file.
* If you are deploying to tomcat, e.g. to perform integration tests, make sure that user and password match with tomcat manger credentials.
* GWT Plugin
** http://gwt-maven.googlecode.com/svn/docs/maven-googlewebtoolkit2-plugin/setup.html
** http://www.ducktools.org/2010/03/maven-and-gwt.html
** http://mojo.codehaus.org/gwt-maven-plugin/examples/compile.html
** http://zenoconsulting.wikidot.com/blog:16
* '''Please read the FAQ section with specific questions on how to write a pom.xml'''.

==How to add project to Hudson==
[[File:hudson-configure-svn.png|thumb|Projects can be added from the Hudson administration interface]]
* Go to Hudson page (e.g. http://bmir-hudson1.stanford.edu).
* Add new job. Select name (e.g. WebProtégé”) and type of project (“Build a maven2 project”).
* Select in section “Source Code Management” the option “Subversion” and add SVN server URL (e.g. http://smi-protege.stanford.edu/repos/protege/web-protege/branches/who-maven/). Keep “Use update” checked. No local module directory. (no password needed?)
* Determine build interval respectively trigger. Currently we use “Build whenever a SNAPSHOT dependency is built”.
* Optionally enable email notification.
* Activate Sonar in “Post-Build-Activities” (Sonar needs to be installed first)

=FAQs=
==Related to reporting==
===My code coverage statistics aren’t updated. What can I do?===
Please change version in pom.xml to next snapshot respectively release number. Don’t forget the configuration.properties file.

===I do not get code coverage statistics for my integration tests. What can I do?===
Currently nothing, this is the way maven handles the build process.

==My build fails since the sonar plugin was not found! What can I do?==
Your Hudson build fails. In the console output you find this stacktrace:
<pre>
org.apache.maven.lifecycle.LifecycleExecutionException: The plugin 'org.codehaus.mojo:sonar-maven-plugin' does not exist or no valid version could be found
at org.apache.maven.lifecycle.DefaultLifecycleExecutor.verifyPlugin(DefaultLifecycleExecutor.java:1569)
at org.apache.maven.lifecycle.DefaultLifecycleExecutor.getMojoDescriptor(DefaultLifecycleExecutor.java:1851)
at org.apache.maven.lifecycle.DefaultLifecycleExecutor.segmentTaskListByAggregationNeeds(DefaultLifecycleExecutor.java:462)
at org.apache.maven.lifecycle.DefaultLifecycleExecutor.execute(DefaultLifecycleExecutor.java:175)
at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:328)
</pre>
Then you most probably ran into a Maven bug which is [http://docs.codehaus.org/display/SONAR/Frequently+Asked+Questions#FrequentlyAskedQuestions-Theplugin%27org.apache.maven.plugins%3Amavensonarplugin%27doesnotexistornovalidversioncouldbefound|described here].

What can you do? As the plugin update is not working as it is supposed to do, please remove the following two directories:
# Maven local repository: <tt>sudo rm -r /usr/local/data/hudson/.m2/repository/org/codehaus/mojo/sonar-maven-plugin</tt>
# Nexus repository: <tt>sudo rm -r /usr/local/data/sonatype-work/nexus/storage/central/org/codehaus/mojo/sonar-maven-plugin</tt>

Then run the build again. Now the repositories are updated and your build should run successfully.

If this fails do addtionally the following:
# ssh to bmir-hudson1.standford.edu
# Switch user: <tt>sudo su - hudson</tt>
# if Maven path is not yet set:
#* <tt>export M2_HOME=/usr/local/apache-maven-2.2.1</tt>
#* <tt>export PATH=$PATH:$HOME/bin:$JAVA_HOME/bin:$M2_HOME/bin</tt>
# Run one project from command line
#* switch to one project <tt>cd /usr/local/data/hudson/jobs/Example-Project/workspace</tt>
#* <tt>mvn -U sonar:sonar</tt> The -U forces the update. Now the maven plugin should be downloaded

==Related to pom.xml==
===How can copy output to a specific directory?===
Remark: In the perfect world you are deploying your artifacts to a local or a remote repository. You are not supposed to work with specific target directories. Nevertheless there may be occasions where it is necessary to do so:

====Step 1: Use Resource Plugin====
Add copy plugin to your pom.xml (in build section). Example:

<syntaxhighlight lang="xml">

<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>2.4.3</version>
<executions>
<execution>
<id>copy-resources</id>

<phase>test</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${outputdir}</outputDirectory>
<resources>
<resource>
<directory>src</directory>
<filtering>true</filtering>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
</syntaxhighlight>

====Step 2: Parametrize output directory====
Set the variable (outputdir) either in the properties-section of the pom.xml:

<syntaxhighlight lang="xml">
<properties>
<maven.compiler.source>1.6</maven.compiler.source>
<maven.compiler.target>1.6</maven.compiler.target>
<outputdir>testoutput/testdirectory</outputdir>
</properties>
</syntaxhighlight>

Or in an external properties file. This requires the Maven properties plugin:

<syntaxhighlight lang="xml">
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>properties-maven-plugin</artifactId>
<version>1.0-alpha-1</version>
<executions>
<execution>
<phase>initialize</phase>
<goals>
<goal>read-project-properties</goal>
</goals>
<configuration>
<files>
<file>src/main/resources/example.properties</file>
</files>
</configuration>
</execution>
</executions>
</plugin>
</syntaxhighlight>

In this (latter) case there is a src/main/resources/example.properties with an entry

outputdir = testoutput2/testdirectory

Further reading:

* “Copy-plugin”: http://maven.apache.org/plugins/maven-resources-plugin/examples/copy-resources.html
* Version plugin: http://mojo.codehaus.org/properties-maven-plugin/plugin-info.html (not to be mixed up with similar plugin http://haroon.sis.utoronto.ca/zarar/properties-maven-plugin/usage.html)

===How can I set the version number in the manifest of OSGI bundles?===

Further reading
* http://felix.apache.org/site/apache-felix-maven-osgi-plugin.html
* http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html

===How can I set the version number of the build number===
====Do it the default way====
The easiest way is to do nothing. Maven automatically increases the version number for snapshot releases. You even would have to turn it off explicitly in the pom.xml:

<syntaxhighlight lang="xml">
<distributionManagement>
<repository>
<id>releases</id>
<url>${nexus.path}/bmir-release</url>
</repository>

<snapshotRepository>
<id>snapshots</id>
<name>Internal Snapshots</name>
<url>${nexus.path}/snapshots</url>
<uniqueVersion>false</uniqueVersion> 
</snapshotRepository>
</distributionManagement>
</syntaxhighlight>

====Do it explicitly====
Another way to determine the build number is by using the Maven build number plugin. This is quite forward:

<syntaxhighlight lang="xml">
<build>

<finalName>${project.artifactId}-${project.version}-r${buildNumber}</finalName>

<plugins>

<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>buildnumber-maven-plugin</artifactId>
<version>1.0-beta-3</version>
<executions>
<execution>
<phase>validate</phase>
<goals>
<goal>create</goal>
</goals>
</execution>
</executions>
<configuration>

<format>{0,date,yyyy-MM-dd-HH-mm-ss}</format>
<items>
<item>timestamp</item>
</items>
</configuration>
</plugin>


</plugins>
</build>
</syntaxhighlight>

The resulting file name could be sth. like <tt>dlquery-0.0.3-r2010-11-15-10-36-20.jar</tt>. The <tt>dlquery</tt> is the artifact id, <tt>0.0.3</tt> the version, both read from the pom.xml (and not generated by the version plugin).

The plugin also provides you the option to include this version in manifest files (jar, war).

Additional ways to determine the build number:
* The plugin supports also to retrieve the version number from the current repository revision.
* You also can include the branch (${scmBranch}) into the version number.
* The plugin supports also autoincrement.
* You could use a property file which you can access in the <finalName> tag.

Further reading
* http://mojo.codehaus.org/buildnumber-maven-plugin/usage.html

===How and where to I decide if I want to make a snapshot release or a "real" release?===
Maven picks up your decision from the version. If your ends with <tt>-SNAPSHOT</tt> then it is a snapshot release, otherweise are productive release.

Example for a snapshot release:

<syntaxhighlight lang="xml">
<project xmlns="http://maven.apache.org/POM/4.0.0">
<modelVersion>4.0.0</modelVersion>
<groupId>protege4</groupId>
<artifactId>xmlcatalog</artifactId>
<packaging>jar</packaging>
<name>xmlcatalog</name>
<version>1.0.0-SNAPSHOT</version>
...
</project>
</syntaxhighlight>

==="I get a return error 400" or "I the deploy of artifacts to Nexus fails. What can I do?"===
There are two typical errors:
# the Maven setting.xml file (either locally or on Hudson) does not contain the right credentials.
# you are trying to deploy to a release repository. Per default it is not allowed to "overwrite" artifacts in a release repository. It is possible in Snapshot repositories. What type a repository has, you can find out by selecting the repository in Nexus (login first). The configuration tab will tell you.

===What are the repositories I'm supposed to deploy to?===
We decided to work with two repositories only:
# BMIR-Release
# Snapshot

===How do I assemple a complex project with dependencies?===
Please use the assembly plugin.

Further reading:
* http://maven.apache.org/plugins/maven-assembly-plugin/index.html
* http://maven.apache.org/plugins/maven-dependency-plugin/ (includes the unpacking of artifacts into a directory)

[[Category:QualityAssurance]]

Main Page

2010-12-16T19:51:33Z

Johner: /* Protege Developers */

__NOTOC__
<div style="background:#F0E6CA; border:1px solid #AE5B08; padding:10px 15px 10px 20px; margin:2em 0 0 0;">
=== Welcome to the Protege Wiki! ===

Protege is a free, open-source platform that provides a growing user community with a suite of tools to construct domain models and knowledge-based applications with ontologies. Please see the [http://protege.stanford.edu/overview/index.html overview section] of the [http://protege.stanford.edu/ Protege website] for a more detailed description of what the Protege platform offers.
</div><br />

<div style="display:block; float:left; width:75%;">

== Upcoming Events ==
<ul>
<li>'''[http://protege.stanford.edu/shortcourse/protege-owl/201103/ Protege-OWL Short Course]''', March 23-25, 2011, Stanford University.</li>
</ul><br />

== Protege Users ==
<ul>
<li style="padding-bottom:5px; list-style:circle;">[http://protege.stanford.edu Protege Website]</li>
<li style="padding-bottom:5px; list-style:circle;">Browse the [[Protege Plugin Library]]</li>
<li style="padding-bottom:5px; list-style:circle;">Browse the [[Protege Ontology Library]]</li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[ProtegeUserDocs|General Documentation]]</strong> - this page is a collection of links to documentation that is applicable to all versions of Protege, including guidelines for developing ontologies, information about scalability and tuning in Protege, etc.</li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[Protege3UserDocs|Protege 3 Documentation]]</strong> - this page is a collection of links to documentation that is specific to the 3.x series such as Getting Started guides, User's Guides, etc.</li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[Protege4UserDocs|Protege 4 Documentation]]</strong> - this page is a collection of links to documentation that is specific to the 4.x series.</li>
<li style="list-style:circle;"><strong>[[WebProtege|WebProtege Documentation]]</strong></li>
</ul><br />

== Protege Developers ==
<ul>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[ProtegeDevDocsGeneral|General Developer Documentation]]</strong> - this page is a collection of links to developer documentation that is applicable to all versions of Protege, such as how to connect to our Subversion repository, etc.</li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[Protege3DevDocs|Protege 3 Developer Documentation]]</strong></li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[Protege4DevDocs|Protege 4 Developer Documentation]]</strong></li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[WebProtegeDevelopersGuide|WebProtege Developer's Guide]]</strong></li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[ProtegeQAGuide|Protege Guide to Quality Assurance]]</strong> - this page is about Maven, continuous integration, build, testing and code/architecture metrics.</li>
</ul><br />

== Wiki Help ==
If you are new to using a Wiki, please see the [[Help:Contents|Help page]] page for useful links to User's Guides, etc.

The [[Help:Contents|Help page]] also has suggestions for where to find help with using the Protege application.
</div>

<div style="display:block; float:right; width:25%;">
[[image:Protege-OWL.jpg|none|thumb|right|protege-owl editor]]
[[image:Protege-Frames.jpg|none|thumb|right|protege-frames editor]]
[[image:Webprotege.png|none|thumb|right|[[WebProtege|web-protege editor]] ]]
</div>

Stanford:ToDoPage

2010-12-16T19:49:12Z

Johner:

=Christian=
==open==
* WebProtege: distinguish SNAPSHOT and release in terms of getting latest or defined dependencies.
==Pending==
* Pending (until further instructions): Copy plugin: instruction,with Tim: properties are overwritten, before war is actually is build
* Not really a task: http://icatdev.stanford.edu
* Pending (until further instructions): Copy plugin: instruction,with Tim: properties are overwritten, before war is actually is build
* Can not be reproduced: Tania's machine (/usr/locasl/icat-files/src/icat-maven): Maven runs out of diskspace, increase memory for Maven. /usr/locasl/icat-files/src/icat-maven (Alex: user access right). User right problem?
==done==
* Christian, please add this line to your ~/.bashrc: umask u=rwx,g=rwx,o=rx. thanks Alex
* SVN checkout problem in project project.editor.application: files are not check-out plugin.xml, version.properties. Update of svn-externals and Hudson solved the issued.
* pom.xml: Make configurable: GWT-compile only of certain modules and of the html file. (e.g. webprotege.html). Relevant web pages added to QaGuide.
* pom.xml: reduce size of war. the lib folder is cleaned, the svn is updated. Now only the libs defined in pom.xml are part of the war. Can be further reduced with <provided>true></provided>
* pom.xml: folder webprotege (generated by GWT with ugly files): all *.rpc files have to be copied one level up (same level as webprotege), http://maven.apache.org/plugins/maven-resources-plugin/examples/copy-resources.html
* Complete UI scripting for iCAT and finish automatic build and testing of WebProtege: Build 168: Strike!

=Alex=
==open==
nothing
==status unclear==
# Synchronize times on different servers (especially SVN and bmir-husdson1), e.g. by using a time server/service (http://time.stanford.edu?).
==done==
# Setup X-Server and care about "export DISPLAY=localhost:0.0"
# have all servers running as service: Hudson, Sonar, Nexus, Tomcat (and have it restarted on a daily basis), Selenium
# Add plugins to MediaWiki:
#* Add Syntaxhighlighter plugin to MediaWiki: http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi
#* Add Video-Plugin to MediaWiki: http://paulgu.com/wiki/FLV_Player
#* Give Christian Access to upload images and videos either per FTP or file upload

[[Category:QualityAssurance]]

Stanford:QaGuide

2010-12-16T19:48:44Z

Johner:

=How-to for architects, test and project managers=
==Target audience and scope==
In this section you find how tos which are related to convert projects from ANT to Maven, to write pom.xml files etc.
==Comprehensive example==
There is a project that shows everything related to build and testing:
* how to write a pom.xml
* how to write and integrate unit tests (JUnit and TestNG)
* how to write and integrate integration tests (selenium)

Please visit https://bmir-gforge.stanford.edu/svn/hudson-test/Hudson-Test.

=How to create a new or convert an existing project =
This steps steps have to be done once per project)
==Establish or change to Maven directory structure==
The following is copied from http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html. It documents the directory layout expected by Maven and the directory layout created by Maven. Please try to conform to this structure as much as possible; however, if you can't these settings can be overridden via the project descriptor.
{| border="1"
!Path
!Description
|-
|'''src/main/java'''
| Application/Library sources
|-
|'''src/main/resources'''
| Application/Library resources
|-
|src/main/filters
| Resource filter files
|-
|src/main/assembly
| Assembly descriptors
|-
|src/main/config
| Configuration files
|-
|'''src/main/webapp'''
| Web application sources
|-
|'''src/test/java'''
| Test sources
|-
|'''src/test/resources'''
| Test resources
|-
|src/test/filters
| Test resource fiter files
|-
|src/site
| Site
|-
|LICENSE.txt
| Project's license
|-
|NOTICE.txt
| Notices and attributions required by libraries that the project depends on
|-
|README.txt
| Project's readme
|-
|}

In the table the most relevant paths are marked bold.

Additionally there are at the top level
* pom.xml
* other optional files as properties, maven.xml or build.xml (if using Ant).

In order to get to the new file structure:
* Add folder inside /src: <tt>/src/main/java and /src/test/java</tt>
* Move <tt>/src/edu</tt> respectively <tt>/test/edu</tt> folders into new folders.
* Delete folder test-lib
* Rename “war” to “webapp” and move folder under /src. (here I ran into problems. Really the best way?)
* Add folder <tt>/src/main/resources/config</tt>. Add to this folder <tt>configuration.properties</tt> file.
* Add under <tt>src/test/java</tt> following folders: <tt>/client/</tt> and <tt>/selenium</tt>??
* Delete files in root folder with exception of src. Delete e.g. /etc/,

To move files/directories you can use Tortoise as described in http://stackoverflow.com/questions/62570/how-do-i-move-a-file-or-folder-from-one-folder-to-another-in-tortoisesvn.

'''Hint:''' In the developer guide there is a description how to import a project from SVN and immediatelly update the src-folder to the expected structure.

==How to upload required artifacts (typicall jar-files) to Nexus repository==
There are multiple ways of adding resources to the repository
# Direct copy ('''not recommended''')
#* Copy resources directly to Nexus subfolder e.g. to <tt>/var/nexus/sonatype-work/nexus/storage/thirdparty/edu/stanford/bmir/core/icd</tt>.
#* You need to put the file the right directory and give it the name indicating the version number, e.g. <tt>/edu/Stanford/bmir/core/protégé-1.0.jar</tt>
#* Goto nexus and right click on third party repository: reindex respectively rebuild metadata
# Uploaded file automatically in due course of a build process (this is '''recommended''' for "own" code as Snapshots and Releases).
#* There is nothing to do besides adding the <distributionManagement> tag to the pom.xml and use the deploy plugin. The PC specific <tt>settings.xml</tt> has to point to the repository as described in the adminstrators guide in section TODO
# Uploaded file using the Nexus interface ('''recommended only for third party artifacts'''). This option is described in the following:

{|
| [[Image:nexus-upload-1.png|thumb|upright|alt=Screenshot how to upload jars to Nexus (step 1)|upload an artifact to Nexus (part 1): Select repository]]
| [[Image:nexus-upload-2.png|thumb|upright|alt=Screenshot how to upload jars to Nexus (step 2)|upload an artifact to Nexus (part 2): Define GAV parameters]]
| [[Image:nexus-upload-3.png|thumb|upright|alt=Screenshot how to upload jars to Nexus (step 3)|upload an artifact to Nexus (part 3): Reindexing]]
| [[Image:nexus-get-dependency.png|thumb|upright|alt=Screenshot how copy the dependency snippet for pom.xml|copy the dependency snippet for pom.xml]]
|}

For each artifact (jar) you can later copy the dependency information for Maven (into the pom.xml). The code snipped look like:

<dependency>
<groupId>edu.stanford.bmir.core</groupId>
<artifact>protege</artifact>
<version>1.0</version>
</dependency>

TODO: define naming convention for groupId. Currently discussed are the following
* protege3
* protege4
* webprotege
* owl

Further reading
* http://www.sonatype.com/books/nexus-book/reference/maven-sect-single-group.html
* http://www.sonatype.com/books/nexus-book/reference/maven-sect-single-group.html
* http://stackoverflow.com/questions/1584763/how-do-i-deploy-to-nexus-hosted-by-secureci

==How to write the Maven script (pom.xml)==
In our case the pom.xml typically will have the following structure:
* Some general information e.g.

<modelVersion>4.0.0</modelVersion>
<groupId>edu.stanford.smi.protegex</groupId>
<artifactId>dlquery</artifactId>
<packaging>jar</packaging>
<name>protege-plugin-dlquery</name>
<version>0.0.3-SNAPSHOT</version>

* Properties as the Java version
* the <tt><distributionManagement></tt> tag which is necessary if artifacts have to deployed to a repository
* the <tt><dependency/></tt> tags (an example was given above)
* the build part with its plugins (e.g. to compile, test, deploy)
* the reporting part with its plugins (e.g. PMD, Findbugs, JDepend)

It is recommended to use an existing <tt>pom.xml</tt> as template.

Further hints and readings:
* the version number can be automatically adjusted with a version plugin. The postfix "<tt>SNAPSHOT</tt>" determines that the artifact won't be uploaded to the release but to the snapshot repository.
* Both repositories (snapshot and release) are defined in the <tt><distributionManagement></tt> section respectively in the <tt>/maven/conf/settings.xml</tt> file.
* If you are deploying to tomcat, e.g. to perform integration tests, make sure that user and password match with tomcat manger credentials.
* GWT Plugin
** http://gwt-maven.googlecode.com/svn/docs/maven-googlewebtoolkit2-plugin/setup.html
** http://www.ducktools.org/2010/03/maven-and-gwt.html
** http://mojo.codehaus.org/gwt-maven-plugin/examples/compile.html
** http://zenoconsulting.wikidot.com/blog:16
* '''Please read the FAQ section with specific questions on how to write a pom.xml'''.

==How to add project to Hudson==
[[File:hudson-configure-svn.png|thumb|Projects can be added from the Hudson administration interface]]
* Go to Hudson page (e.g. http://bmir-hudson1.stanford.edu).
* Add new job. Select name (e.g. WebProtégé”) and type of project (“Build a maven2 project”).
* Select in section “Source Code Management” the option “Subversion” and add SVN server URL (e.g. http://smi-protege.stanford.edu/repos/protege/web-protege/branches/who-maven/). Keep “Use update” checked. No local module directory. (no password needed?)
* Determine build interval respectively trigger. Currently we use “Build whenever a SNAPSHOT dependency is built”.
* Optionally enable email notification.
* Activate Sonar in “Post-Build-Activities” (Sonar needs to be installed first)

=FAQs=
==Related to reporting==
===My code coverage statistics aren’t updated. What can I do?===
Please change version in pom.xml to next snapshot respectively release number. Don’t forget the configuration.properties file.

===I do not get code coverage statistics for my integration tests. What can I do?===
Currently nothing, this is the way maven handles the build process.

==My build fails since the sonar plugin was not found! What can I do?==
Your Hudson build fails. In the console output you find this stacktrace:
<pre>
org.apache.maven.lifecycle.LifecycleExecutionException: The plugin 'org.codehaus.mojo:sonar-maven-plugin' does not exist or no valid version could be found
at org.apache.maven.lifecycle.DefaultLifecycleExecutor.verifyPlugin(DefaultLifecycleExecutor.java:1569)
at org.apache.maven.lifecycle.DefaultLifecycleExecutor.getMojoDescriptor(DefaultLifecycleExecutor.java:1851)
at org.apache.maven.lifecycle.DefaultLifecycleExecutor.segmentTaskListByAggregationNeeds(DefaultLifecycleExecutor.java:462)
at org.apache.maven.lifecycle.DefaultLifecycleExecutor.execute(DefaultLifecycleExecutor.java:175)
at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:328)
</pre>
Then you most probably ran into a Maven bug which is [http://docs.codehaus.org/display/SONAR/Frequently+Asked+Questions#FrequentlyAskedQuestions-Theplugin%27org.apache.maven.plugins%3Amavensonarplugin%27doesnotexistornovalidversioncouldbefound|described here].

What can you do? As the plugin update is not working as it is supposed to do, please remove the following two directories:
# Maven local repository: <tt>/usr/local/data/hudson/.m2/repository/org/codehaus/mojo/sonar-maven-plugin</tt>
# Nexus repository: <tt>/usr/local/data/sonatype-work/nexus/storage/central/org/codehaus/mojo/sonar-maven-plugin</tt>

Then run the build again. Now the repositories are updated and your build should run successfully.

If this fails do addtionally the following:
# ssh to bmir-hudson1.standford.edu
# Switch user: <tt>sudo su - hudson</tt>
# if Maven path is not yet set:
#* <tt>export M2_HOME=/usr/local/apache-maven-2.2.1</tt>
#* <tt>export PATH=$PATH:$HOME/bin:$JAVA_HOME/bin:$M2_HOME/bin</tt>
# Run one project from command line
#* switch to one project <tt>cd /usr/local/data/hudson/jobs/Example-Project/workspace</tt>
#* <tt>mvn -U sonar:sonar</tt> The -U forces the update. Now the maven plugin should be downloaded

==Related to pom.xml==
===How can copy output to a specific directory?===
Remark: In the perfect world you are deploying your artifacts to a local or a remote repository. You are not supposed to work with specific target directories. Nevertheless there may be occasions where it is necessary to do so:

====Step 1: Use Resource Plugin====
Add copy plugin to your pom.xml (in build section). Example:

<syntaxhighlight lang="xml">

<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>2.4.3</version>
<executions>
<execution>
<id>copy-resources</id>

<phase>test</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${outputdir}</outputDirectory>
<resources>
<resource>
<directory>src</directory>
<filtering>true</filtering>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
</syntaxhighlight>

====Step 2: Parametrize output directory====
Set the variable (outputdir) either in the properties-section of the pom.xml:

<syntaxhighlight lang="xml">
<properties>
<maven.compiler.source>1.6</maven.compiler.source>
<maven.compiler.target>1.6</maven.compiler.target>
<outputdir>testoutput/testdirectory</outputdir>
</properties>
</syntaxhighlight>

Or in an external properties file. This requires the Maven properties plugin:

<syntaxhighlight lang="xml">
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>properties-maven-plugin</artifactId>
<version>1.0-alpha-1</version>
<executions>
<execution>
<phase>initialize</phase>
<goals>
<goal>read-project-properties</goal>
</goals>
<configuration>
<files>
<file>src/main/resources/example.properties</file>
</files>
</configuration>
</execution>
</executions>
</plugin>
</syntaxhighlight>

In this (latter) case there is a src/main/resources/example.properties with an entry

outputdir = testoutput2/testdirectory

Further reading:

* “Copy-plugin”: http://maven.apache.org/plugins/maven-resources-plugin/examples/copy-resources.html
* Version plugin: http://mojo.codehaus.org/properties-maven-plugin/plugin-info.html (not to be mixed up with similar plugin http://haroon.sis.utoronto.ca/zarar/properties-maven-plugin/usage.html)

===How can I set the version number in the manifest of OSGI bundles?===

Further reading
* http://felix.apache.org/site/apache-felix-maven-osgi-plugin.html
* http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html

===How can I set the version number of the build number===
====Do it the default way====
The easiest way is to do nothing. Maven automatically increases the version number for snapshot releases. You even would have to turn it off explicitly in the pom.xml:

<syntaxhighlight lang="xml">
<distributionManagement>
<repository>
<id>releases</id>
<url>${nexus.path}/bmir-release</url>
</repository>

<snapshotRepository>
<id>snapshots</id>
<name>Internal Snapshots</name>
<url>${nexus.path}/snapshots</url>
<uniqueVersion>false</uniqueVersion> 
</snapshotRepository>
</distributionManagement>
</syntaxhighlight>

====Do it explicitly====
Another way to determine the build number is by using the Maven build number plugin. This is quite forward:

<syntaxhighlight lang="xml">
<build>

<finalName>${project.artifactId}-${project.version}-r${buildNumber}</finalName>

<plugins>

<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>buildnumber-maven-plugin</artifactId>
<version>1.0-beta-3</version>
<executions>
<execution>
<phase>validate</phase>
<goals>
<goal>create</goal>
</goals>
</execution>
</executions>
<configuration>

<format>{0,date,yyyy-MM-dd-HH-mm-ss}</format>
<items>
<item>timestamp</item>
</items>
</configuration>
</plugin>


</plugins>
</build>
</syntaxhighlight>

The resulting file name could be sth. like <tt>dlquery-0.0.3-r2010-11-15-10-36-20.jar</tt>. The <tt>dlquery</tt> is the artifact id, <tt>0.0.3</tt> the version, both read from the pom.xml (and not generated by the version plugin).

The plugin also provides you the option to include this version in manifest files (jar, war).

Additional ways to determine the build number:
* The plugin supports also to retrieve the version number from the current repository revision.
* You also can include the branch (${scmBranch}) into the version number.
* The plugin supports also autoincrement.
* You could use a property file which you can access in the <finalName> tag.

Further reading
* http://mojo.codehaus.org/buildnumber-maven-plugin/usage.html

===How and where to I decide if I want to make a snapshot release or a "real" release?===
Maven picks up your decision from the version. If your ends with <tt>-SNAPSHOT</tt> then it is a snapshot release, otherweise are productive release.

Example for a snapshot release:

<syntaxhighlight lang="xml">
<project xmlns="http://maven.apache.org/POM/4.0.0">
<modelVersion>4.0.0</modelVersion>
<groupId>protege4</groupId>
<artifactId>xmlcatalog</artifactId>
<packaging>jar</packaging>
<name>xmlcatalog</name>
<version>1.0.0-SNAPSHOT</version>
...
</project>
</syntaxhighlight>

==="I get a return error 400" or "I the deploy of artifacts to Nexus fails. What can I do?"===
There are two typical errors:
# the Maven setting.xml file (either locally or on Hudson) does not contain the right credentials.
# you are trying to deploy to a release repository. Per default it is not allowed to "overwrite" artifacts in a release repository. It is possible in Snapshot repositories. What type a repository has, you can find out by selecting the repository in Nexus (login first). The configuration tab will tell you.

===What are the repositories I'm supposed to deploy to?===
We decided to work with two repositories only:
# BMIR-Release
# Snapshot

===How do I assemple a complex project with dependencies?===
Please use the assembly plugin.

Further reading:
* http://maven.apache.org/plugins/maven-assembly-plugin/index.html
* http://maven.apache.org/plugins/maven-dependency-plugin/ (includes the unpacking of artifacts into a directory)

[[Category:QualityAssurance]]

Stanford:AdministratorGuide

2010-12-16T19:48:28Z

Johner:

=Installation and configuration of central server infrastructure =
[[File:infrastructure-2.png|thumb|Infrastructure with all servers and information flow]]
It is recommended to install the tools in the proposed sequence, since we have the following dependencies:
* Hudson uses Maven
* Hudson includes the Sonar plugin and triggers Sonar
* Maven retrieves libraries from Nexus
* Hudson executes the Maven script
* Maven includes profiles from Sonar and Nexus.

We assume that SVN is already installed and that the projects exist in SVN.

=JAVA=
* Download and install java.
* Set environment setting JAVA_HOME pointing to the java folder (e.g. on Windows “C:\Program Files\Java\jdk1.6.0_21\bin”).

=Nexus=
==Initial Installation and configuration (one time)==
Download file (OS dependent) from http:////nexus.sonatype.org/downloads (e.g. “nexus-oss-webapp-1.8.0-bundle.zip”). Extract files to final directory.
OS dependent
* Windows: Open command line with bin folder as current directory (e.g. “C:\nexus\nexus-oss-webapp-1.8.0\bin\jsw\windows-x86-32”). Run Installnexus and Startnexus from command line. Windows Users (Vista, Windows 7) need to execute cmd.exe as Administrator (go to “All Programs”, “Accessories”, “Command Prompt”, right mouse click on “Run as Administrator”.
* Linux: Create folder /var/nexus/. Copy downloaded filder into this folder. Open command line with bin folder as current (e.g. /var/nexus/nexus-oss-webapp-1.8.0/bin/jsw/linux-x86-32). Run sudo ./nexus start

Alternatively you can install Nexus as service as described in http://www.sonatype.com/books/nexus-book/reference/ch03s06.html.

Test Nexus: http://localhost:8081/nexus/index.html. Login to Nexus with user name and password “admin” respectively XXX (/var/nexus/nexus-oss-webapp-1.8.0/conf/users.txt). Optionally make SMTP settings.

==How to change the password==
If the NEXUS password is changed (TODO: has to be done soon), this has to happen in two places:
1. Change it in Nexus itself using the administration/security interface
2. Change it in the settings.xml in maven/conf/ directory.

TODO: Change password.
==Setting up repositories==
===Option 1: Upload files individually===
Nexus comes with a predefined set of repositories. Now add the artifacts as described in the project manager's guide. TODO add link.

===Option 2: Optionally import external repositories===
After install there is a “storage” folder (e.g. “C:\nexus\sonatype-work\nexus\storage”).

Copy Sonar folder to storage and overwrite folder “thirdparty”. In thirdparty there are the Stanford libs. Please refer to the appendix to get an overview.

Current problem: the jars in the official repositories have not distinct versions. So it is not possible to point to a specific version. We are talking about the jars mentioned in the WebProtege developer guide (http://protegewiki.stanford.edu/wiki/WebProtegeDevelopersGuide) section “Fix project compilation errors”.

=Sonar=
Just download zip file sonar-2.2 from http://www.sonarsource.org/. Unpack it to our tools folder (e.g. to /var/sonar/sonar-2.2).

Start sonar from bin folder (e.g. /var/sonar/sonar-2.2/bin/linux-x86-32 folder:
* Windows StartSonar
* Linux: sonar.sh (don’t forget to make this file and wrapper to be executable (set permissions)

Test Sonar via http://localhost:9000. The default admin user name and password are admin/admin, however, there is no need to login.

Optionally install Sonar as LINUX service. Command line /var/sonar/sonar-2.2.3/sudo cp bin/linux-x86-64/sonar.sh /etc/init.d/sonar

The default password is changed. The current one can be found in /var/sonar/sonar-2.3/conf/users.txt. Or ask christian.johner@johner-institut.de.

=Maven=
==Installation==
Download Maven from http://maven.apache.org/download.html und chose apache-maven-2.2.1.

Add system environment variables:
* M2_HOME pointing to new directory apache-maven-2.2.1
* JAVA_HOME (if not already set)

Add to Path ;%M2_HOME%\bin

==Configuration==
Change file “apache-maven-2.2.1/conf/settings.xml”
* Add mirror (http://localhost:8081/nexus/content/groups/public)
<mirrors>
<mirror>

<id>nexus</id>
<mirrorOf>*</mirrorOf>
<url>http://localhost:8081/nexus/content/groups/public</url>
</mirror>
</mirrors>
* Add profiles for sonar and nexus
<profiles>
<profile>
<id>nexus</id>


<repositories>
<repository>
<id>central</id>
<url>http://central</url>
<releases><enabled>true</enabled></releases>
<snapshots><enabled>true</enabled></snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>central</id>
<url>http://central</url>
<releases><enabled>true</enabled></releases>
<snapshots><enabled>true</enabled></snapshots>
</pluginRepository>
</pluginRepositories>
</profile>
<profile>
<id>sonar</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<properties>
</properties>
</profile>
</profiles>
<activeProfiles>

<activeProfile>nexus</activeProfile>
</activeProfiles>
* Add servers
<servers>
<server>
<id>snapshots</id>
<username>admin</username>
<password>admin123</password>
</server>

<server>
<id>releases</id>
<username>admin</username>
<password>admin123</password>
</server>
</servers>

'''Hint:''' the passwords shown in the code above have been the default passwords. They do not match the actual password. The actual password can be found in the Maven directory /conf/settings.xml on bmir-hudson.standford.edu.

A complete settings.xml file can be downloaded from [[Stanford:SettingsXmlExample|here]].

=Hudson=
==Install (one time) and start Hudson==
Windows
* Download war-file from www.hudson-ci.org. Just click on “latest and greatest”.
* Start server with java –jar hudson.war. Runs on http://localhost:8080

Linux
* Follow steps as described in http://hudson-ci.org/redhat/ (to use YUM) which are
* sudo rpm --import http://hudson-ci.org/redhat/hudson-ci.org.key
* wget -O /tmp/hudson.rpm http://hudson-ci.org/latest/redhat/hudson.rpm
* sudo rpm --install /tmp/hudson.rpm
* Start: sudo /etc/rc.d/init.d/hudson start

==Initial Configuration (one time)==
[[File:hudson-add-sonar.png|thumb|Sonar can be added as plugin]]
Add plugins
* Go to “Manage Hudson” → “Manage Plugins”.
* Go to available plugins and install “Hudson Sonar Plugin”.
* Optionally add additional plugins. E.g. for Twitter, Trigger, e.g. jabber. Build reports is not needed as we use Sonar.

[[File:hudson-configure.png|thumb|Paths to Maven and JDK to be defined in the configuration settings]]
Go back to “Manage Hudson” and select “Configure System” and make the following changes/settings
* Jdk: set name (e.g. “Java 1.6”) and path to Java (e.g. “C:\Program Files\Java\jdk1.6.0_21”). Hudson does not read the system variable JAVA_HOME.
* Maven: Add Maven (not ANT) and set name (e.g. “Maven 2”) and path to Maven (e.g. “C:\Tools\apache-maven-2.2.1” respectively ). Hudson does not read the system variable MAVEN_HOME.
* “Add Sonar”. Just add a name (e.g. “Sonar”). Set location e.g. to http://bmir-hudson1:9000.
* Optionally set e-mail notifications

==Add projects==
Please refer to the project manager section. TODO add link.

==Add Users==
Go to Hudson > Manage Server > Configure System and add an user by entering a name in text field "User/group to add". Ignore the warning symbol, it will disappear as soon the user has registered himself. Give user rights by checking checkboxes. Click save.

=Selenium Server (Selenium Remote Control)=
Set up a central Selenium Server.
* Download Selenium RC from http://seleniumhq.org/download/.
* Unzip file. We only need selenium-server-1.0.3 subfolder.
* Start server with java –jar selenium-server.jar
* Make sure that the display is set, e.g. export DISPLAY=… (case sensitive, only WLAN IP worked?!?)

There is already a file /etc/init.d/start-selenium-server.sh.
[johner@bmir-hudson1 ~]$ export DISPLAY=10.39.35.249:0.0
[johner@bmir-hudson1 ~]$ xhost
access control disabled, clients can connect from any host
INET:DN0a2723f9.SUNet
LOCAL:
INET:bmir-hudson1.stanford.edu
[johner@bmir-hudson1 ~]$ java -jar /var/selenium/selenium-server.jar

Note: the display settings have to be done before selenium is started!

Either there is a XServer running on the test machine or a client machine (or server itself) needs running X-Server, e.g. run xming –ac. XMing is available for Windows.

=Tomcat=
Standard out of the box: Either use yum or just download and extract apache-tomcat. Change in server-xml port to 8082 in order to avoid conflicts with Hudson.

old:
sudo /opt/tomcat/bin/startup.sh
user name and password currently are currently set to admin/protégé.

Change by Alex: /usr/local/tomcat6 it should start with /sbin/service tomact6 start
Password can be found in /etc/tomcat6/tomcat-users.xml

[[Category:QualityAssurance]]

Stanford:DeveloperGuide

2010-12-16T19:48:01Z

Johner:

=In a nutshell=
You work as you typically work just using Eclipse to develop and test. There are only a few things you need to consider:
* The initial setup of your Eclipse project is done with Maven.
* Prefer TestNG over JUnit in order to write unit tests.
* We encourage you to write UI tests using the Selenium framework.
* We encourage you to deploy your artifacts not just to the file system (local Maven repository) but also to the central Nexus repository, at least if you have the privileges to do so.

And don’t forget to update and commit to/from on a daily basis.

=How to start from scratch=
==Downloads and Installs==
[[Image:eclipse-jdk.png|thumb|Use the JDK instead of the JRE]]
===JAVA===
* Download and install java.
* Set environment setting <tt>JAVA_HOME</tt> pointing to the java folder, e.g. <tt>C:\Program Files\Java\jdk1.6.0_21\bin</tt>.

===Maven===
* Download Maven from http://maven.apache.org/download.html und chose apache-maven-2.2.1.
* Add system environment variable M2_HOME pointing to new directory apache-maven-2.2.1
* Add to Path <tt>;%M2_HOME%\bin</tt>
* Modify <tt>/conf/settings.xml</tt>: Path to Nexus and you operating system. There is an [[Stanford:SettingsXmlExample|example page for a settings file]].

===Eclipse===
* Download, extract and start eclipse
* Install subclipse plugin (update site is http://subclipse.tigris.org/update_1.6.x). Check all options, otherwise the SCM handler of Maven will be missing.
* Install GWT plusing (update site is http://dl.google.com/eclipse/plugin/3.6) with Helios 3.6, otherwise 3.5
* Install m2eclipse plugin (Update site is http://m2eclipse.sonatype.org/sites/m2e)
* Optional: Install m2eclipse extra plugin (Update site is http://m2eclipse.sonatype.org/sites/m2e-extras). Select Maven SCM handler for Subclipse and Maven SCM integration.
* Let Eclipse know the location of your installed JDK (nor JRE!)
* Start Eclipse with JDK (not JRE!) as described in http://help.eclipse.org/help33/index.jsp?topic=/org.eclipse.platform.doc.user/tasks/running_eclipse.htm. Example:
"C:\Program Files\eclipse-jee-helios-SR1-win32\eclipse\eclipse.exe" -vm "C:\Programme\Java\jdk1.6.0_21\bin\javaw.exe"

===Firefox & GWT plugin (only for GWT UI testing)===
After download and install of Firefox we recommend adding a new profile. Rationale: Selenium typically initiates a new Firefox profile which is missing the GWT Firefox plugin. Therefore we generate a new one:
* Open command window and go to Firefox directory
* Execute firefox -P. Plugin manager shows up.
* Add new profile and chose a directory, e.g. one Protégé related.
* Start Firefox and start eclipse. Open page http://127.0.0.1:8888/WebProtege.html?gwt.codesvr=127.0.0.1:9997. This prompts you to install the GWT plugin.
* Save the profile

===Selenium (only for GWT UI testing)===
Please refer to chapter in section administration. TODO add link.

Start server with <tt>java –jar selenium-server.jar -firefoxProfileTemplate <Path2Profile></tt>. <Path2Profile> is the folder you were choosing when creating the new profile.

Example:

C:\Users\DrCJ\selenium-server-1.0.3>java -jar selenium-server.jar -firefoxProfileTemplate c:\Users\DrCJ\firefoxprofile

==Start working with a project e.g. with Protégé==
===Option 1: import project using Subclipse (preferred)===
Pretty straight forward
* Import project from repository using Subclipse.
** File > Import > SVN > SVN Projects. Import desired project and branch.
** Use “Create Project wizard”, use “Next” instead of “Finish” button and add a new source folder “src/main/java” and remove “src” from build path.
** Copy imported files from src to “src/main/java” folder. There will be problems, since libraries are missing. Do not tweak build path, this will be done automatically in the next step.
* Execute mvn eclipse:eclipse from command line
* Refresh project (F5)

To update classpath (e.g. if there is a new jar (as defined in the pom.xml)) just repeat these steps.

If there are still libraries missing (which are obviously defined in your pom.xml), please consult with your project manager or upload the artifacts to the respository as described in the project manager guide.

[[Media:Import-Project.flv|import project using Subclipse (video tutorial)]]

{|
| [[Image:eclipse-checkout-maven.png|thumb|upright|alt=Maven can be used to check out the project|Maven can be used to check out the project]]
| [[Image:eclipse-import-project.png|thumb|upright|alt=Or use SVN to download. Then call mvn eclipse:eclipse and import project|Or use SVN to download. Then call mvn eclipse:eclipse and import project]]
| [[Image:eclipse-gwt.png|thumb|upright|alt=make project to become a GWT project|make project to become a GWT project]]
| [[Image:eclipse-gwt-2.png|thumb|upright|alt=Set the webapp folder for the GWT compiled code|Set the webapp folder for the GWT compiled code]]
|}

===Option 2: import project from command line (using a SVN client)===
* Download project from repository with Tortoise or other (command line based) SVN client
* Execute mvn eclipse:eclipse from command line
* Refresh project (F5)

To update classpath (e.g. if there is a new pom.xml) just repeat these steps.

===Option 3: using the m2eclipse plugin===
Chose “Project” from the “File” menu, select Maven and then “Checkout maven Projects from SCM”.

===Configure GWT plugin===
* Select Project Properties and check under Google “Use Google App Engine”
* In project properties set plugin as active and change WAR directory to be /src/main/webapp (there is no longer a /war directory!)

=Questions that may arise during development=
==How do I work with multiple projects in parallel==
To given an example: We work with projects A and B where B depends on A. (An example would be A = Protégé, B = WebProtégé.)

Assuming you would like to make a change to project A which is required to continue working with project B:

# Make the change in project A
# Go to the command line in project A's directory (e.g. in <tt>/home/<USER_NAME>/workspace/projectA</tt>) and enter <tt>mvn install</tt> [1], [2]. This will update your local Maven repository (M2_REPO) which typically is located in <tt>/home/.m2/repository</tt> respectively in <tt>c:\user\<username>\.m2\repository</tt>. [1]
# Go to the command line of project B and enter <tt>mvn eclipse:eclipse</tt> [2]. This will update the classpath and (re)load the artifact of project A.
# Continue developing in project B.

Actually there are two variants:
# Variant 1: you do not change the version number of the artifact of project A. In this case you do not have to modify the version number in project A's pom.xml. This is an advantage, another advantage is that you do not need to update the dependency section in the pom.xml of project B.
# Variant 2: you change the version number of the artifact of project A in the project A' pom.xml. This requires that you update the version in the dependency section in project B's pom.xml. The advantage of this variant is that you easily can switch back to the old version of project A's artifact, you even can have multiple versions in your repository.

The dependency section in the pom.xml the text above is refering to looks like:

<syntaxhighlight lang="xml">
<dependency>
<groupId>protege</groupId>
<artifactId>protege-core</artifactId>
<version>3.4.2</version>
</dependency>
</syntaxhighlight>

[1]: If you want to skip the unit tests use <tt>mvn install -DskipTests=true</tt> instead.

[2]: Alternatively you can use the m2eclipse plugin.

==How do I deploy my artifacts to the (central) Nexus repository==
First you have to have write privileges to BMIR's Nexus repository (http://bmir-hudson1.stanford.edu/nexus). Typically these privileges are only granted to a closed group of developers. Both, these privileges (-> credentials) and the path to the repository have to be entered to your Maven settings file (<tt><MAVEN_INSTALL_DIR>/conf/settings.xml</tt>). There is a [[Stanford:SettingsXmlExample|complete example of this file]] available.

As soon you execute <tt>mvn deploy</tt> the Nexus repository is updated. Please keep in mind that your artifact either is stored in the snapshot or in the release repository dependent on the version number in your pom.xml: If the version number ends with <tt>SNAPSHOT</tt> the snapshot directory is addressed, otherwise the release repository.

Keep in mind that...
* the SNAPSHOT repository allows the redeployment of an artifact (with the same version number), the release repository doesn't,
* a deployment (<tt>mvn deploy</tt>) to the SNAPSHOT repository will autoincrement the version number of your artifact (if not explicitly turned off in the pom.xml), a deployment to the release repository won't.
* there is no autoincrement of the version number during install (<tt>mvn install</tt>),
* there is no need to install a local Nexus repository on your machine.

==How to update classpath==
Just get latest pom.xml and execute mvn eclipse:eclipse. This will update (not overwrite) your classpath. Press refresh in Eclipse. There is not even a restart necessary.

=How to write unit test case (TestNG, JUnit) and UI test cases (FEST, QFS)=
This section is about standard unit tests, i.e. not about writing UI tests/integrations tests using Selenium.
==How to re-use existing JUnit test cases==
===Option 1: Convert JUnit test cases to TestNG test cases===
You either can do that programmatically as described in http://testng.org/doc/migrating.html or you do that manually. TestNG tests look pretty much the same then JUnit tests. What has to be done typically includes:
* Change <tt>import to org.testng.annotations.*;</tt> and <tt>import static org.testng.Assert.*;</tt>
* Add annotation <tt>@BeforeClass</tt> to setup-method.
* Add annotation <tt>@Test</tt> to your test methods

===Option 2: Keep JUnit tests cases as they are and run it from TestNG===
In the <tt>/src/test/resources/unit-tests.xml</tt> there is a section with <tt>junit=true</tt>. Just add your tests there.

Example (mind second set of tests)

<syntaxhighlight lang="xml">
<!DOCTYPE suite SYSTEM "http://testng.org/testng-1.0.dtd" >
<suite name="ProtegeTestSuite" verbose="1">
<test name="TestNG-Tests">
<classes>
<class name="edu.stanford.bmir.protege.web.server.WatchedEntitiesCacheTest"></class>
<class name="client.TestUnitProtege"></class>
</classes>
</test>
<test name="JUnit-Tests (Example)" junit="true">
<classes>
<class name="client.JUnitExample"></class>
</classes>
</test>
</suite>
</syntaxhighlight>

There are (theoretically) two options how to include JUnit tests cases to the continuous integration.
# Make sure that your test classes are in the designated folder /src/test/java and that they are following the naming convention *Test.java
# Specify the classes in the xml file in /src/test/resources
We decided to go for the latter option. All types of specification as test parameters, grouping of tests and running tests in parallel have to be defined in theses TestNG-XML-files (and not(!) in the pom.xml). In the pom.xml we deliberatly disabled the automatic execution of JUnit tests in the line

<syntaxhighlight lang="xml">
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<skip>true</skip>
</configuration>
...
</plugin>
</syntaxhighlight>

==Write new TestNG test cases==
The vest resource to start is http://www.testng.org. Nevertheless the following lines might be helpful:

It is recommended to use the TestNG plugin for Eclipse since it adds all libraries to your classpath. Then writing a new test case is straight forward:
* write a standard Java class. Even there is no naming convention required it is recommended to call the class XXXTest, whereas XXX stands for the class under test.
* Write some test methods. Even there is no naming convention required it is recommended to call the method testXXX, whereas XXX stands for the method to be tested. However the test methods require the annotation @Test.
* Optionally have methods which have to be executed one before the test class is executed respectively which are executed before each test method. Add annotations @BeforeClass, @AfterClass, @BeforeMethod, respectively @AfterMetehod
* Fix imports

<syntaxhighlight lang="java">
import junit.framework.Assert;
import org.testng.annotations.AfterClass;
import org.testng.annotations.BeforeClass;
import org.testng.annotations.Parameters;
import org.testng.annotations.Test;
</syntaxhighlight>

* Optional enhancements
** Add dependencies between methods e.g. <tt>@Test (dependsOnMethods = {"openICDTree"})</tt> where openICDTree is the name of the other method.
** Move test parameters from test code to the configuration file, e.g.

<syntaxhighlight lang="xml">
<test name="Navigation 1">
<parameter name="username" value="protege"/>
<parameter name="username" value="secret"/>
<classes>
<class name="selenium.TestICat"></class>
</classes>
</test>
</syntaxhighlight>

* Refer to these parameters in the Java code
<syntaxhighlight lang="java">
@Test
@Parameters({ "username", "password" })
public void login(String username, String password) throws InterruptedException {...}
</syntaxhighlight>

* Add new test case to the test-configuration xml as shown above.

==How to write UI test cases (web) with Selenium==
===General===
The UI tests use the Selenium test framework. You either can write the tests from scratch or use the Selenium IDE, a Firefox Plugin to record actions and to generate Java Code (TestNG classes).

The biggest challenge with writing UI tests is the identification of UI components since one can not relay on the id of the component. These ids are generated by GWT dynamically.

===Example Code===
s. example.
===How to locate UI elements===
s. example.
===Resources===
* How to locate elements
** General: http://seleniumhq.org/docs/04_selenese_commands.html#locating-elements
** Usefull X-Path patterns: http://seleniumhq.org/docs/appendix_locating_techniques.html#useful-xpath-patterns
** X-Path in general: http://www.w3schools.com/xpath/xpath_examples.asp
** Calendars, Comboboxes, Popup etc: http://www.ibm.com/developerworks/opensource/library/os-webautoselenium/index.html?cmp=dw&cpb=dwope&ct=dwnew&cr=dwnen&ccy=zz&csr=120910

==Comprehensive example==
There is a project that shows everything related to build and testing:
* how to write a pom.xml
* how to write and integrate unit tests (JUnit and TestNG)
* how to write and integrate integration tests (selenium)

Please visit https://bmir-gforge.stanford.edu/svn/hudson-test/Hudson-Test.
==How to write UI test cases (Swing) using FEST==
The tutorial on how to write FEST tests will be written upon decision for/against FEST. So far please refer to the official documentation: http://docs.codehaus.org/display/FEST/Getting+Started

The "Example-Project" (Hudson) also contains a demo application using FEST: https://bmir-gforge.stanford.edu/svn/hudson-test/Hudson-Test

==How to write UI test cases (Swing) using QF-Test==
The tutorial on how to write QFS tests will be written upon decision for/against QFS. So far please refer to the official documentation:
http://www.qfs.de (tutorials in English available).

=Other questions=
==How to switch to ICD11 with all data (database)==
Follow instructions given in http://groups.google.com/group/icat-users/web/accessing-the-icat-content-programmatically?hl=en&_done=%2Fgroup%2Ficat-users%3Fhl%3Den%26&hl=en

On Windows the import command might be slightly different than described in the website. Use instead
mysql --user=protege --password=protege < c:\protege_2010-11-01_04h02m.Monday.sql

In summary you need to
* import database (and check that protege DB acutally exists afterwards)
* add user
* grant rights to the user

In order to do so, make use of the follwing commands:
mysql -u root
mysql> -u root connect to localhost;
mysql> show databases;
mysql> use protege;
mysql> show tables;
mysql> CREATE USER protege IDENTIFIED BY 'protege';
mysql> GRANT SELECT, INSERT, UPDATE, DELETE on *.* to 'protege'@'localhost';

More useful commands: http://www.pantz.org/software/mysql/mysqlcommands.html

[[Category:QualityAssurance]]

Stanford:OverviewPage

2010-12-16T19:47:12Z

Johner:

=Overview=
==Infrastructure==
[[File:infrastructure-2.png|thumb|Infrastructure with all servers and information flow]]

The workflow is supposed to work as follows (the numbers refer to the numbers in figure XY):
# The developer works on his machine where he/she writes code and tests. He works with the usual set of tools as Eclipse and GWT as well as Selenium, JUnit respectively TestNG for testing.
# After development code including test code is checked in to a version control system as SVN.
# This or a schedulder triggers a build on the integration server. We chose Hudson for continuous integration. On this server the usual steps are described in a Maven script:
## Retrieve code (including test code)
## Retrieve libraries
## Compile code (including test code)
## Run Unit-Tests via TestNG
## Deploy artifacts to test environment and/or other servers
## Run UI- and System-Tests on test enviroment via TestNG and Selenium
## Generate reports
# The war file is deployed to Tomcat (optional step)
# The UI- and System-Tests are executed via TestNG scripts using Selenium. (optional step)
# The reporting (e.g. error reports, compile errors, code and architecture metrics) which is triggered by Hudson is done via Sonar which also performs an analysis of code and architecture.
# Hudson is capable to communicate the results by the means of RSS, Twitter, Mail or Skype, to name a few examples.
# Both, the developer as well as the build server (Hudson) retrieve the Maven script as well as the libraries from a central repository server. We chose Nexus.
# Hudson deploys tested artifacts to repository from where developers and users can download it

==Rationale==
[[File:iso9126.png|thumb|ISO 9126: Quality criteria of software]]
The rationale for continuous integration and testing is as import as evident:
* Avoid redundant tasks as
** Build software (including compile, package etc.)
** Run unit tests
** Run system tests including UI-tests
** Evaluate quality of code and architecture
* Provide a faster start for new programmers. A one-click install is the ultimate goal. Any unnecessary step will take time, might lead to errors and has the potential to frustrate “newbies”.
* Bugs which are found early are easy and fast to fix. As longer it takes and as more commits were done as more difficult and tedious the bug fixing will become.
* (Web-) Protégé is supposed to attract continuously more programmers. At the same time, the quality of the software has to be assured. Especially with respect to maintainability and functionality. But also quality aspects like efficiency and reliability can be partially tested automatically.
=Description and Rationale for Tools=
This page is intended to give an overview on the systems and to describe why we selected particularily this set. How to install, operate, and use this tools is described in
* [[Stanford:AdministratorGuide| administrator guide]]
* [[Stanford:DeveloperGuide|developer guide]]

==Hudson==
Hudson is a server application to automatically and continuously build, test and deploy one or more projects. It provides an overview on the build and tests results including code metrics, architecture metrics, JUnit results and much more.

It is obvious that such repetitive tasks should be automated. However, there are several products to facilitate this task. Among those there is CruiseControl We decided to prefer Hudson over CruiseControl for the following reasons:

* Installation is simpler. It is just download the jar file. E.g. no installation of DB necessary.
* Administration is simpler: An easy to use web interface gives access to all administrative settings
* Easy integration with other tools e.g. with Sonar, TestNG and communication services
* Related to Plug-ins
* Easier plug-in development
* More plug-ins available (e.g. twitter, email, Sonar, Selenium)
* Easier plug-ins administration

Hudson executes the Maven script(s) including builds as well as unit and UI tests, triggers reporting and communication of build and test results.

<Link>Instruction how to install and configure Hudson.

==Nexus==
[[File:nexus.png|thumb|Nexus the central and shared repository for all developers (and users)]]
As more libraries a project requires and as more dependencies these libraries have as more complex the setup of a new development environment and of executing a build become. For example WebProtégé has dependencies to Protégé, to the Google Web Toolkit, to Apache libraries, and so on. And even the referenced libraries are interdependent.

Maven is capable of resolving these dependencies. Nexus is a repository manager which allows you to centrally provide these libraries in a versioned and reproducible manner. Nexus also can serve as proxy. So the developers (and the build system) just need to retrieve these files from the repository instead of individually downloading these artifacts redundantly. This not only saves bandwidth, but also reduces the load on “Central” (the central Maven repository).

Nexus is not replacing Maven. Nexus proxies the Maven requests to a central Maven repository. Nexus provides as the feature not only to proxy repositories, but to operate our “own” repository which is the deployment target of all of our projects. Please note that Maven itself uses a repository (the Maven repository).

Further feature of Nexus include
* a quick and easy search of all artifacts.
* Developers don’t have to have the entire source. They just can work with libraries from Nexus. This makes collaboration easier.
* Clear responsibility and maintenance of “official” 3rd party libraries.

An additional list of reasons for using repository managers can be found at http://www.sonatype.com/books/nexus-book/reference/sect-repoman-reasons.html.

A comparison of repository managers (Apache Archiva, Artifactory, and Nexus) can be found at http://docs.codehaus.org/display/MAVENUSER/Maven+Repository+Manager+Feature+Matrix.

“Standard” developers not necessarily have to deal with Nexus. She just uses Nexus as a repository to retrieve artifacts from. If she requires a new jar-file, this has to be done as described in the How-Tos. However, we recommend to have a local repository as well.

<Link>Instruction how to install and configure Nexus.

==Sonar==
Sonar is a very powerful platform to report the quality of software products considering aspects as
* Code metrics as complexity
* Error/bug patterns
* Architectural metrics
* Conformity with coding guidelines
* Results of tests (Unit tests, UI tests) including errors, failures and code coverage.

Sonar provides both, a comprehensive overview on the quality o projects as well as the option to drill down to single metrics/aspects and even to the single line of source code.

Sonar serves as shell compiling and consistently visualizing the results of numerous tools as Checkstyle, FindBugs, PMD, and TestNG .

<Link>Instruction how to install and configure Maven.

==TestNG==
We prefer TestNG over JUnit for the following reasons:
* Better separation of test code and test data
* Better grouping of tests and re-use of test groups
* Better support for parallel (multi-threaded) testing
* TestNG automatically produces test reports without having the need to use other tasks as JUnitReport.

==Maven==
Maven is used by
* Developers to initially create his workspace (initial build)
* To define the build and test process which is executed and scheduled by Hudson.

<Link>Instruction how to install and configure Maven.

# validate
# generate-sources
# process-sources
# generate-resources
# process-resources
# compile
# process-classes
# generate-test-sources
# process-test-sources
# generate-test-resources
# process-test-resources
# test-compile
# test
# prepare-package (maven 2.1+)
# package
# pre-integration-test
# integration-test
# post-integration-test
# verify
# install
# deploy

==Firefox ==
We prefer Firefox over other browsers for two major reasons:
* Firefox is available on LINUX, too. LINUX will be our server OS.
* There is a Selenium Plugin available for Firefox.

Having said this, it is nevertheless worth mentioning that the web applications have to be tested on other browsers as well. This requires no plugin. The plugin is only required for automated UI tests.

==Selenium Server (Selenium Remote Control)==
[[File:selenium-server.png|thumb|Selenium Server Architecure. Picture taken form http://seleniumhq.org/projects/remote-control]]
Selenium remote control is a server which allows developers test web applications (even with AJAX) using Java code (e.g. JUnit, TestNG) or any other language.

Selenium RC automatically launches the browser, simulates the user actions and kills the browser afterwards. Thereby Selenium RC facilitates the complete test automation ($rarr; regression testing) of rich web applications.

<Link>Instruction how to install and configure Selenium.

==Selenium Plugin (optional)==
The Selenium IDE is an optional Firefox plugin which helps developers to record actions in the browser and generate Java code. However, the capture & replay functionality is very limited. Therefore Selenium tests will be written as regular Java respectively TestNG code.
[[Category:QualityAssurance]]

Category:QualityAssurance

2010-12-16T19:45:34Z

Johner: Created page with 'This is the QualityAssurance category.'

This is the QualityAssurance category.

File:Selenium-server.png

2010-12-16T19:40:06Z

Johner: Selenium server architecture (picture taken from Selenium website)

Selenium server architecture (picture taken from Selenium website)

File:Nexus-upload-3.png

2010-12-16T19:39:39Z

Johner: Upload an artifact to Nexus (part 3)

Upload an artifact to Nexus (part 3)

File:Nexus-upload-2.png

2010-12-16T19:39:26Z

Johner: Upload an artifact to Nexus (part 2)

Upload an artifact to Nexus (part 2)

File:Nexus-upload-1.png

2010-12-16T19:39:08Z

Johner: Upload an artifact to Nexus (part 1)

Upload an artifact to Nexus (part 1)

File:Nexus-get-dependency.png

2010-12-16T19:38:47Z

Johner: Nexus provides the GAV parameters (group id, artifact id and version) as XML snippet which can be copied to the pom.xml (<dependency/>

Nexus provides the GAV parameters (group id, artifact id and version) as XML snippet which can be copied to the pom.xml (<dependency/>

File:Nexus.png

2010-12-16T19:38:22Z

Johner: Nexus is the central repository for all artifacts e.g. jars

Nexus is the central repository for all artifacts e.g. jars

File:Mavenprotege.png

2010-12-16T19:38:01Z

Johner:

File:Iso9126.png

2010-12-16T19:37:47Z

Johner: Software quality aspects according to ISO 9126

Software quality aspects according to ISO 9126

File:Infrastructure.png

2010-12-16T19:37:24Z

Johner: Infrastructure with all servers and sketch of information flow

Infrastructure with all servers and sketch of information flow

File:Import-Project.flv

2010-12-16T19:36:53Z

Johner: Import Project vom SVN and convert it to MVN structure

Import Project vom SVN and convert it to MVN structure

File:Hudson-configure-svn.png

2010-12-16T19:36:30Z

Johner: Point Hudson to the SVN repository

Point Hudson to the SVN repository

File:Hudson-configure.png

2010-12-16T19:36:07Z

Johner: Configure Hudson

Configure Hudson

File:Hudson-add-sonar.png

2010-12-16T19:35:47Z

Johner: Add plugins (e.g. Sonar) to Hudson

Add plugins (e.g. Sonar) to Hudson

File:Eclipse-jdk.png

2010-12-16T19:35:17Z

Johner: Select jdk (instead of jre) to compile and build projects

Select jdk (instead of jre) to compile and build projects

File:Eclipse-import-project.png

2010-12-16T19:34:57Z

Johner: Import existing project into Eclipse workspace

Import existing project into Eclipse workspace

File:Eclipse-gwt-2.png

2010-12-16T19:34:37Z

Johner: Define webapp folder for GWT projec

Define webapp folder for GWT projec

File:Eclipse-gwt.png

2010-12-16T19:34:18Z

Johner: Make Eclipse project to become a GWT project

Make Eclipse project to become a GWT project

File:Eclipse-checkout-maven.png

2010-12-16T19:33:51Z

Johner: How to check out a project from SVN to Eclipse

How to check out a project from SVN to Eclipse

File:Infrastructure-2.png

2010-12-16T19:33:12Z

Johner: The entire system landscape

The entire system landscape

ProtegeQAGuide

2010-12-16T19:26:23Z

Johner: Created page with 'This is the start page on how to (automatically) build and test all applications/projects related to Protégé. =Guidance Documents= [[File:infrastructure-2.png|thumb|Infrastruc…'

This is the start page on how to (automatically) build and test all applications/projects related to Protégé.

=Guidance Documents=
[[File:infrastructure-2.png|thumb|Infrastructure with all servers and information flow]]

{| border="1"
| On the <span style="font-variant:small-caps;font-size:1.3em;font-weight:bold">[[Stanford:OverviewPage|Overview Page]]</span>
you find
* some background information describing the rationale for caring about automated builds and testing and for establishing a corresponding infrastructure.
* an overview chart displaying the entire infrastructure landscape.
* a short description of all the relevant tools and the rationale for chosing the selected ones

| The <span style="font-variant:small-caps;font-size:1.3em;font-weight:bold">[[Stanford:AdministratorGuide|Administrator Guide]]</span> (→ Alex)
describes how to install and operate all the servers, among those:
* Nexus repository: http://bmir-hudson1.stanford.edu/nexus
* Hudson Build Sever (build statistics, administration of jobs): http://bmir-hudson1.stanford.edu
* Sonar Server (code and architecture metrics, coverage reports and more): http://bmir-hudson1.stanford.edu/sonar (use link from Hudson to Sonar reports instead)
* Tomcat Server (automated UI testing, not of general interest): http://bmir-hudson1.stanford.edu:8080
* SVN-Repository: http://smi-protege.stanford.edu/repos/protege/

|-
| The <span style="font-variant:small-caps;font-size:1.3em;font-weight:bold">[[Stanford:DeveloperGuide|Developer Guide]]</span> (→ external and Stanford internal)
is the main page for developers. On these pages developers get answers to questions like
* How do I initially set up my tools to work with one or more of the Protégé projects?
* <strong>New:</strong> Please watch video tutorial.
* How do I write test cases?
* How do I get the lastest downloads?

| The <span style="font-variant:small-caps;font-size:1.3em;font-weight:bold">[[Stanford:QaGuide|QA & Project Manager Guide]]</span> (→ Tania, Jennifer, Tim & other)
is the address for everybody interested in the success and quality of builds and code. It gives explanations like
* How to write/adjust the pom.xml?
* What do these metrics tell me?
* What do I have to do in order to add artifacts (e.g. jar-files) to my repository
|}

=Contact and further Information=
The selection, installation and testing of the infrastructure as well as the initial transistion from traditional ANT-based to Maven based projects was done by [mailto://c.faigle@gmx.net Christian Faigle] and [mailto://mail@johner.org Christian Johner]. Please contact either for questions related to
* Selection of tools
* Administration of tools
* Converting projects to MAVEN
* Interpretation and adaptation of reports

This page originally was written by [mailto://mail@johner.org Christian Johner].

The [[Stanford:ToDoPage|Todos]] (for Christian, Alex)

Main Page

2010-12-16T19:26:10Z

Johner: /* Protege Developers */

__NOTOC__
<div style="background:#F0E6CA; border:1px solid #AE5B08; padding:10px 15px 10px 20px; margin:2em 0 0 0;">
=== Welcome to the Protege Wiki! ===

Protege is a free, open-source platform that provides a growing user community with a suite of tools to construct domain models and knowledge-based applications with ontologies. Please see the [http://protege.stanford.edu/overview/index.html overview section] of the [http://protege.stanford.edu/ Protege website] for a more detailed description of what the Protege platform offers.
</div><br />

<div style="display:block; float:left; width:75%;">

== Upcoming Events ==
<ul>
<li>'''[http://protege.stanford.edu/shortcourse/protege-owl/201103/ Protege-OWL Short Course]''', March 23-25, 2011, Stanford University.</li>
</ul><br />

== Protege Users ==
<ul>
<li style="padding-bottom:5px; list-style:circle;">[http://protege.stanford.edu Protege Website]</li>
<li style="padding-bottom:5px; list-style:circle;">Browse the [[Protege Plugin Library]]</li>
<li style="padding-bottom:5px; list-style:circle;">Browse the [[Protege Ontology Library]]</li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[ProtegeUserDocs|General Documentation]]</strong> - this page is a collection of links to documentation that is applicable to all versions of Protege, including guidelines for developing ontologies, information about scalability and tuning in Protege, etc.</li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[Protege3UserDocs|Protege 3 Documentation]]</strong> - this page is a collection of links to documentation that is specific to the 3.x series such as Getting Started guides, User's Guides, etc.</li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[Protege4UserDocs|Protege 4 Documentation]]</strong> - this page is a collection of links to documentation that is specific to the 4.x series.</li>
<li style="list-style:circle;"><strong>[[WebProtege|WebProtege Documentation]]</strong></li>
</ul><br />

== Protege Developers ==
<ul>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[ProtegeDevDocsGeneral|General Developer Documentation]]</strong> - this page is a collection of links to developer documentation that is applicable to all versions of Protege, such as how to connect to our Subversion repository, etc.</li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[Protege3DevDocs|Protege 3 Developer Documentation]]</strong></li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[Protege4DevDocs|Protege 4 Developer Documentation]]</strong></li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[WebProtegeDevelopersGuide|WebProtege Developer's Guide]]</strong></li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[ProtegeQAGuide|Protege Guide to Quality Assurance]]</strong></li>
</ul><br />

== Wiki Help ==
If you are new to using a Wiki, please see the [[Help:Contents|Help page]] page for useful links to User's Guides, etc.

The [[Help:Contents|Help page]] also has suggestions for where to find help with using the Protege application.
</div>

<div style="display:block; float:right; width:25%;">
[[image:Protege-OWL.jpg|none|thumb|right|protege-owl editor]]
[[image:Protege-Frames.jpg|none|thumb|right|protege-frames editor]]
[[image:Webprotege.png|none|thumb|right|[[WebProtege|web-protege editor]] ]]
</div>

Stanford:QaGuide

2010-12-16T19:22:59Z

Johner: 20 revisions: Import from CF Pages (2)

=How-to for architects, test and project managers=
==Target audience and scope==
In this section you find how tos which are related to convert projects from ANT to Maven, to write pom.xml files etc.
==Comprehensive example==
There is a project that shows everything related to build and testing:
* how to write a pom.xml
* how to write and integrate unit tests (JUnit and TestNG)
* how to write and integrate integration tests (selenium)

Please visit https://bmir-gforge.stanford.edu/svn/hudson-test/Hudson-Test.

=How to create a new or convert an existing project =
This steps steps have to be done once per project)
==Establish or change to Maven directory structure==
The following is copied from http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html. It documents the directory layout expected by Maven and the directory layout created by Maven. Please try to conform to this structure as much as possible; however, if you can't these settings can be overridden via the project descriptor.
{| border="1"
!Path
!Description
|-
|'''src/main/java'''
| Application/Library sources
|-
|'''src/main/resources'''
| Application/Library resources
|-
|src/main/filters
| Resource filter files
|-
|src/main/assembly
| Assembly descriptors
|-
|src/main/config
| Configuration files
|-
|'''src/main/webapp'''
| Web application sources
|-
|'''src/test/java'''
| Test sources
|-
|'''src/test/resources'''
| Test resources
|-
|src/test/filters
| Test resource fiter files
|-
|src/site
| Site
|-
|LICENSE.txt
| Project's license
|-
|NOTICE.txt
| Notices and attributions required by libraries that the project depends on
|-
|README.txt
| Project's readme
|-
|}

In the table the most relevant paths are marked bold.

Additionally there are at the top level
* pom.xml
* other optional files as properties, maven.xml or build.xml (if using Ant).

In order to get to the new file structure:
* Add folder inside /src: <tt>/src/main/java and /src/test/java</tt>
* Move <tt>/src/edu</tt> respectively <tt>/test/edu</tt> folders into new folders.
* Delete folder test-lib
* Rename “war” to “webapp” and move folder under /src. (here I ran into problems. Really the best way?)
* Add folder <tt>/src/main/resources/config</tt>. Add to this folder <tt>configuration.properties</tt> file.
* Add under <tt>src/test/java</tt> following folders: <tt>/client/</tt> and <tt>/selenium</tt>??
* Delete files in root folder with exception of src. Delete e.g. /etc/,

To move files/directories you can use Tortoise as described in http://stackoverflow.com/questions/62570/how-do-i-move-a-file-or-folder-from-one-folder-to-another-in-tortoisesvn.

'''Hint:''' In the developer guide there is a description how to import a project from SVN and immediatelly update the src-folder to the expected structure.

==How to upload required artifacts (typicall jar-files) to Nexus repository==
There are multiple ways of adding resources to the repository
# Direct copy ('''not recommended''')
#* Copy resources directly to Nexus subfolder e.g. to <tt>/var/nexus/sonatype-work/nexus/storage/thirdparty/edu/stanford/bmir/core/icd</tt>.
#* You need to put the file the right directory and give it the name indicating the version number, e.g. <tt>/edu/Stanford/bmir/core/protégé-1.0.jar</tt>
#* Goto nexus and right click on third party repository: reindex respectively rebuild metadata
# Uploaded file automatically in due course of a build process (this is '''recommended''' for "own" code as Snapshots and Releases).
#* There is nothing to do besides adding the <distributionManagement> tag to the pom.xml and use the deploy plugin. The PC specific <tt>settings.xml</tt> has to point to the repository as described in the adminstrators guide in section TODO
# Uploaded file using the Nexus interface ('''recommended only for third party artifacts'''). This option is described in the following:

{|
| [[Image:nexus-upload-1.png|thumb|upright|alt=Screenshot how to upload jars to Nexus (step 1)|upload an artifact to Nexus (part 1): Select repository]]
| [[Image:nexus-upload-2.png|thumb|upright|alt=Screenshot how to upload jars to Nexus (step 2)|upload an artifact to Nexus (part 2): Define GAV parameters]]
| [[Image:nexus-upload-3.png|thumb|upright|alt=Screenshot how to upload jars to Nexus (step 3)|upload an artifact to Nexus (part 3): Reindexing]]
| [[Image:nexus-get-dependency.png|thumb|upright|alt=Screenshot how copy the dependency snippet for pom.xml|copy the dependency snippet for pom.xml]]
|}

For each artifact (jar) you can later copy the dependency information for Maven (into the pom.xml). The code snipped look like:

<dependency>
<groupId>edu.stanford.bmir.core</groupId>
<artifact>protege</artifact>
<version>1.0</version>
</dependency>

TODO: define naming convention for groupId. Currently discussed are the following
* protege3
* protege4
* webprotege
* owl

Further reading
* http://www.sonatype.com/books/nexus-book/reference/maven-sect-single-group.html
* http://www.sonatype.com/books/nexus-book/reference/maven-sect-single-group.html
* http://stackoverflow.com/questions/1584763/how-do-i-deploy-to-nexus-hosted-by-secureci

==How to write the Maven script (pom.xml)==
In our case the pom.xml typically will have the following structure:
* Some general information e.g.

<modelVersion>4.0.0</modelVersion>
<groupId>edu.stanford.smi.protegex</groupId>
<artifactId>dlquery</artifactId>
<packaging>jar</packaging>
<name>protege-plugin-dlquery</name>
<version>0.0.3-SNAPSHOT</version>

* Properties as the Java version
* the <tt><distributionManagement></tt> tag which is necessary if artifacts have to deployed to a repository
* the <tt><dependency/></tt> tags (an example was given above)
* the build part with its plugins (e.g. to compile, test, deploy)
* the reporting part with its plugins (e.g. PMD, Findbugs, JDepend)

It is recommended to use an existing <tt>pom.xml</tt> as template.

Further hints and readings:
* the version number can be automatically adjusted with a version plugin. The postfix "<tt>SNAPSHOT</tt>" determines that the artifact won't be uploaded to the release but to the snapshot repository.
* Both repositories (snapshot and release) are defined in the <tt><distributionManagement></tt> section respectively in the <tt>/maven/conf/settings.xml</tt> file.
* If you are deploying to tomcat, e.g. to perform integration tests, make sure that user and password match with tomcat manger credentials.
* GWT Plugin
** http://gwt-maven.googlecode.com/svn/docs/maven-googlewebtoolkit2-plugin/setup.html
** http://www.ducktools.org/2010/03/maven-and-gwt.html
** http://mojo.codehaus.org/gwt-maven-plugin/examples/compile.html
** http://zenoconsulting.wikidot.com/blog:16
* '''Please read the FAQ section with specific questions on how to write a pom.xml'''.

==How to add project to Hudson==
[[File:hudson-configure-svn.png|thumb|Projects can be added from the Hudson administration interface]]
* Go to Hudson page (e.g. http://bmir-hudson1.stanford.edu).
* Add new job. Select name (e.g. WebProtégé”) and type of project (“Build a maven2 project”).
* Select in section “Source Code Management” the option “Subversion” and add SVN server URL (e.g. http://smi-protege.stanford.edu/repos/protege/web-protege/branches/who-maven/). Keep “Use update” checked. No local module directory. (no password needed?)
* Determine build interval respectively trigger. Currently we use “Build whenever a SNAPSHOT dependency is built”.
* Optionally enable email notification.
* Activate Sonar in “Post-Build-Activities” (Sonar needs to be installed first)

=FAQs=
==Related to reporting==
===My code coverage statistics aren’t updated. What can I do?===
Please change version in pom.xml to next snapshot respectively release number. Don’t forget the configuration.properties file.

===I do not get code coverage statistics for my integration tests. What can I do?===
Currently nothing, this is the way maven handles the build process.

==My build fails since the sonar plugin was not found! What can I do?==
Your Hudson build fails. In the console output you find this stacktrace:
<pre>
org.apache.maven.lifecycle.LifecycleExecutionException: The plugin 'org.codehaus.mojo:sonar-maven-plugin' does not exist or no valid version could be found
at org.apache.maven.lifecycle.DefaultLifecycleExecutor.verifyPlugin(DefaultLifecycleExecutor.java:1569)
at org.apache.maven.lifecycle.DefaultLifecycleExecutor.getMojoDescriptor(DefaultLifecycleExecutor.java:1851)
at org.apache.maven.lifecycle.DefaultLifecycleExecutor.segmentTaskListByAggregationNeeds(DefaultLifecycleExecutor.java:462)
at org.apache.maven.lifecycle.DefaultLifecycleExecutor.execute(DefaultLifecycleExecutor.java:175)
at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:328)
</pre>
Then you most probably ran into a Maven bug which is [http://docs.codehaus.org/display/SONAR/Frequently+Asked+Questions#FrequentlyAskedQuestions-Theplugin%27org.apache.maven.plugins%3Amavensonarplugin%27doesnotexistornovalidversioncouldbefound|described here].

What can you do? As the plugin update is not working as it is supposed to do, please remove the following two directories:
# Maven local repository: <tt>/usr/local/data/hudson/.m2/repository/org/codehaus/mojo/sonar-maven-plugin</tt>
# Nexus repository: <tt>/usr/local/data/sonatype-work/nexus/storage/central/org/codehaus/mojo/sonar-maven-plugin</tt>

Then run the build again. Now the repositories are updated and your build should run successfully.

If this fails do addtionally the following:
# ssh to bmir-hudson1.standford.edu
# Switch user: <tt>sudo su - hudson</tt>
# if Maven path is not yet set:
#* <tt>export M2_HOME=/usr/local/apache-maven-2.2.1</tt>
#* <tt>export PATH=$PATH:$HOME/bin:$JAVA_HOME/bin:$M2_HOME/bin</tt>
# Run one project from command line
#* switch to one project <tt>cd /usr/local/data/hudson/jobs/Example-Project/workspace</tt>
#* <tt>mvn -U sonar:sonar</tt> The -U forces the update. Now the maven plugin should be downloaded

==Related to pom.xml==
===How can copy output to a specific directory?===
Remark: In the perfect world you are deploying your artifacts to a local or a remote repository. You are not supposed to work with specific target directories. Nevertheless there may be occasions where it is necessary to do so:

====Step 1: Use Resource Plugin====
Add copy plugin to your pom.xml (in build section). Example:

<syntaxhighlight lang="xml">

<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>2.4.3</version>
<executions>
<execution>
<id>copy-resources</id>

<phase>test</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${outputdir}</outputDirectory>
<resources>
<resource>
<directory>src</directory>
<filtering>true</filtering>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
</syntaxhighlight>

====Step 2: Parametrize output directory====
Set the variable (outputdir) either in the properties-section of the pom.xml:

<syntaxhighlight lang="xml">
<properties>
<maven.compiler.source>1.6</maven.compiler.source>
<maven.compiler.target>1.6</maven.compiler.target>
<outputdir>testoutput/testdirectory</outputdir>
</properties>
</syntaxhighlight>

Or in an external properties file. This requires the Maven properties plugin:

<syntaxhighlight lang="xml">
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>properties-maven-plugin</artifactId>
<version>1.0-alpha-1</version>
<executions>
<execution>
<phase>initialize</phase>
<goals>
<goal>read-project-properties</goal>
</goals>
<configuration>
<files>
<file>src/main/resources/example.properties</file>
</files>
</configuration>
</execution>
</executions>
</plugin>
</syntaxhighlight>

In this (latter) case there is a src/main/resources/example.properties with an entry

outputdir = testoutput2/testdirectory

Further reading:

* “Copy-plugin”: http://maven.apache.org/plugins/maven-resources-plugin/examples/copy-resources.html
* Version plugin: http://mojo.codehaus.org/properties-maven-plugin/plugin-info.html (not to be mixed up with similar plugin http://haroon.sis.utoronto.ca/zarar/properties-maven-plugin/usage.html)

===How can I set the version number in the manifest of OSGI bundles?===

Further reading
* http://felix.apache.org/site/apache-felix-maven-osgi-plugin.html
* http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html

===How can I set the version number of the build number===
====Do it the default way====
The easiest way is to do nothing. Maven automatically increases the version number for snapshot releases. You even would have to turn it off explicitly in the pom.xml:

<syntaxhighlight lang="xml">
<distributionManagement>
<repository>
<id>releases</id>
<url>${nexus.path}/bmir-release</url>
</repository>

<snapshotRepository>
<id>snapshots</id>
<name>Internal Snapshots</name>
<url>${nexus.path}/snapshots</url>
<uniqueVersion>false</uniqueVersion> 
</snapshotRepository>
</distributionManagement>
</syntaxhighlight>

====Do it explicitly====
Another way to determine the build number is by using the Maven build number plugin. This is quite forward:

<syntaxhighlight lang="xml">
<build>

<finalName>${project.artifactId}-${project.version}-r${buildNumber}</finalName>

<plugins>

<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>buildnumber-maven-plugin</artifactId>
<version>1.0-beta-3</version>
<executions>
<execution>
<phase>validate</phase>
<goals>
<goal>create</goal>
</goals>
</execution>
</executions>
<configuration>

<format>{0,date,yyyy-MM-dd-HH-mm-ss}</format>
<items>
<item>timestamp</item>
</items>
</configuration>
</plugin>


</plugins>
</build>
</syntaxhighlight>

The resulting file name could be sth. like <tt>dlquery-0.0.3-r2010-11-15-10-36-20.jar</tt>. The <tt>dlquery</tt> is the artifact id, <tt>0.0.3</tt> the version, both read from the pom.xml (and not generated by the version plugin).

The plugin also provides you the option to include this version in manifest files (jar, war).

Additional ways to determine the build number:
* The plugin supports also to retrieve the version number from the current repository revision.
* You also can include the branch (${scmBranch}) into the version number.
* The plugin supports also autoincrement.
* You could use a property file which you can access in the <finalName> tag.

Further reading
* http://mojo.codehaus.org/buildnumber-maven-plugin/usage.html

===How and where to I decide if I want to make a snapshot release or a "real" release?===
Maven picks up your decision from the version. If your ends with <tt>-SNAPSHOT</tt> then it is a snapshot release, otherweise are productive release.

Example for a snapshot release:

<syntaxhighlight lang="xml">
<project xmlns="http://maven.apache.org/POM/4.0.0">
<modelVersion>4.0.0</modelVersion>
<groupId>protege4</groupId>
<artifactId>xmlcatalog</artifactId>
<packaging>jar</packaging>
<name>xmlcatalog</name>
<version>1.0.0-SNAPSHOT</version>
...
</project>
</syntaxhighlight>

==="I get a return error 400" or "I the deploy of artifacts to Nexus fails. What can I do?"===
There are two typical errors:
# the Maven setting.xml file (either locally or on Hudson) does not contain the right credentials.
# you are trying to deploy to a release repository. Per default it is not allowed to "overwrite" artifacts in a release repository. It is possible in Snapshot repositories. What type a repository has, you can find out by selecting the repository in Nexus (login first). The configuration tab will tell you.

===What are the repositories I'm supposed to deploy to?===
We decided to work with two repositories only:
# BMIR-Release
# Snapshot

===How do I assemple a complex project with dependencies?===
Please use the assembly plugin.

Further reading:
* http://maven.apache.org/plugins/maven-assembly-plugin/index.html
* http://maven.apache.org/plugins/maven-dependency-plugin/ (includes the unpacking of artifacts into a directory)

Stanford:ToDoPage

2010-12-16T19:22:59Z

Johner: 18 revisions: Import from CF Pages (2)

Stanford:OverviewPage

2010-12-16T19:22:55Z

Johner: 10 revisions: Import from CF Pages (2)

Main Page

2010-12-16T19:22:54Z

Johner: 38 revisions: Import from CF Pages (2)

__NOTOC__
<div style="background:#F0E6CA; border:1px solid #AE5B08; padding:10px 15px 10px 20px; margin:2em 0 0 0;">
=== Welcome to the Protege Wiki! ===

Protege is a free, open-source platform that provides a growing user community with a suite of tools to construct domain models and knowledge-based applications with ontologies. Please see the [http://protege.stanford.edu/overview/index.html overview section] of the [http://protege.stanford.edu/ Protege website] for a more detailed description of what the Protege platform offers.
</div><br />

<div style="display:block; float:left; width:75%;">

== Upcoming Events ==
<ul>
<li>'''[http://protege.stanford.edu/shortcourse/protege-owl/201103/ Protege-OWL Short Course]''', March 23-25, 2011, Stanford University.</li>
</ul><br />

== Protege Users ==
<ul>
<li style="padding-bottom:5px; list-style:circle;">[http://protege.stanford.edu Protege Website]</li>
<li style="padding-bottom:5px; list-style:circle;">Browse the [[Protege Plugin Library]]</li>
<li style="padding-bottom:5px; list-style:circle;">Browse the [[Protege Ontology Library]]</li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[ProtegeUserDocs|General Documentation]]</strong> - this page is a collection of links to documentation that is applicable to all versions of Protege, including guidelines for developing ontologies, information about scalability and tuning in Protege, etc.</li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[Protege3UserDocs|Protege 3 Documentation]]</strong> - this page is a collection of links to documentation that is specific to the 3.x series such as Getting Started guides, User's Guides, etc.</li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[Protege4UserDocs|Protege 4 Documentation]]</strong> - this page is a collection of links to documentation that is specific to the 4.x series.</li>
<li style="list-style:circle;"><strong>[[WebProtege|WebProtege Documentation]]</strong></li>
</ul><br />

== Protege Developers ==
<ul>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[ProtegeDevDocsGeneral|General Developer Documentation]]</strong> - this page is a collection of links to developer documentation that is applicable to all versions of Protege, such as how to connect to our Subversion repository, etc.</li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[Protege3DevDocs|Protege 3 Developer Documentation]]</strong></li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[Protege4DevDocs|Protege 4 Developer Documentation]]</strong></li>
<li style="padding-bottom:5px; list-style:circle;"><strong>[[WebProtegeDevelopersGuide|WebProtege Developer's Guide]]</strong></li>
</ul><br />

== Wiki Help ==
If you are new to using a Wiki, please see the [[Help:Contents|Help page]] page for useful links to User's Guides, etc.

The [[Help:Contents|Help page]] also has suggestions for where to find help with using the Protege application.
</div>

<div style="display:block; float:right; width:25%;">
[[image:Protege-OWL.jpg|none|thumb|right|protege-owl editor]]
[[image:Protege-Frames.jpg|none|thumb|right|protege-frames editor]]
[[image:Webprotege.png|none|thumb|right|[[WebProtege|web-protege editor]] ]]
</div>

Stanford:AdministratorGuide

2010-12-16T19:22:54Z

Johner: 9 revisions: Import from CF Pages (2)

Stanford:DeveloperGuide

2010-12-16T19:21:37Z

Johner: 28 revisions: Import from CF Pages

=In a nutshell=
You work as you typically work just using Eclipse to develop and test. There are only a few things you need to consider:
* The initial setup of your Eclipse project is done with Maven.
* Prefer TestNG over JUnit in order to write unit tests.
* We encourage you to write UI tests using the Selenium framework.
* We encourage you to deploy your artifacts not just to the file system (local Maven repository) but also to the central Nexus repository, at least if you have the privileges to do so.

And don’t forget to update and commit to/from on a daily basis.

=How to start from scratch=
==Downloads and Installs==
[[Image:eclipse-jdk.png|thumb|Use the JDK instead of the JRE]]
===JAVA===
* Download and install java.
* Set environment setting <tt>JAVA_HOME</tt> pointing to the java folder, e.g. <tt>C:\Program Files\Java\jdk1.6.0_21\bin</tt>.

===Maven===
* Download Maven from http://maven.apache.org/download.html und chose apache-maven-2.2.1.
* Add system environment variable M2_HOME pointing to new directory apache-maven-2.2.1
* Add to Path <tt>;%M2_HOME%\bin</tt>
* Modify <tt>/conf/settings.xml</tt>: Path to Nexus and you operating system. There is an [[Stanford:SettingsXmlExample|example page for a settings file]].

===Eclipse===
* Download, extract and start eclipse
* Install subclipse plugin (update site is http://subclipse.tigris.org/update_1.6.x). Check all options, otherwise the SCM handler of Maven will be missing.
* Install GWT plusing (update site is http://dl.google.com/eclipse/plugin/3.6) with Helios 3.6, otherwise 3.5
* Install m2eclipse plugin (Update site is http://m2eclipse.sonatype.org/sites/m2e)
* Optional: Install m2eclipse extra plugin (Update site is http://m2eclipse.sonatype.org/sites/m2e-extras). Select Maven SCM handler for Subclipse and Maven SCM integration.
* Let Eclipse know the location of your installed JDK (nor JRE!)
* Start Eclipse with JDK (not JRE!) as described in http://help.eclipse.org/help33/index.jsp?topic=/org.eclipse.platform.doc.user/tasks/running_eclipse.htm. Example:
"C:\Program Files\eclipse-jee-helios-SR1-win32\eclipse\eclipse.exe" -vm "C:\Programme\Java\jdk1.6.0_21\bin\javaw.exe"

===Firefox & GWT plugin (only for GWT UI testing)===
After download and install of Firefox we recommend adding a new profile. Rationale: Selenium typically initiates a new Firefox profile which is missing the GWT Firefox plugin. Therefore we generate a new one:
* Open command window and go to Firefox directory
* Execute firefox -P. Plugin manager shows up.
* Add new profile and chose a directory, e.g. one Protégé related.
* Start Firefox and start eclipse. Open page http://127.0.0.1:8888/WebProtege.html?gwt.codesvr=127.0.0.1:9997. This prompts you to install the GWT plugin.
* Save the profile

===Selenium (only for GWT UI testing)===
Please refer to chapter in section administration. TODO add link.

Start server with <tt>java –jar selenium-server.jar -firefoxProfileTemplate <Path2Profile></tt>. <Path2Profile> is the folder you were choosing when creating the new profile.

Example:

C:\Users\DrCJ\selenium-server-1.0.3>java -jar selenium-server.jar -firefoxProfileTemplate c:\Users\DrCJ\firefoxprofile

==Start working with a project e.g. with Protégé==
===Option 1: import project using Subclipse (preferred)===
Pretty straight forward
* Import project from repository using Subclipse.
** File > Import > SVN > SVN Projects. Import desired project and branch.
** Use “Create Project wizard”, use “Next” instead of “Finish” button and add a new source folder “src/main/java” and remove “src” from build path.
** Copy imported files from src to “src/main/java” folder. There will be problems, since libraries are missing. Do not tweak build path, this will be done automatically in the next step.
* Execute mvn eclipse:eclipse from command line
* Refresh project (F5)

To update classpath (e.g. if there is a new jar (as defined in the pom.xml)) just repeat these steps.

If there are still libraries missing (which are obviously defined in your pom.xml), please consult with your project manager or upload the artifacts to the respository as described in the project manager guide.

[[Media:Import-Project.flv|import project using Subclipse (video tutorial)]]

{|
| [[Image:eclipse-checkout-maven.png|thumb|upright|alt=Maven can be used to check out the project|Maven can be used to check out the project]]
| [[Image:eclipse-import-project.png|thumb|upright|alt=Or use SVN to download. Then call mvn eclipse:eclipse and import project|Or use SVN to download. Then call mvn eclipse:eclipse and import project]]
| [[Image:eclipse-gwt.png|thumb|upright|alt=make project to become a GWT project|make project to become a GWT project]]
| [[Image:eclipse-gwt-2.png|thumb|upright|alt=Set the webapp folder for the GWT compiled code|Set the webapp folder for the GWT compiled code]]
|}

===Option 2: import project from command line (using a SVN client)===
* Download project from repository with Tortoise or other (command line based) SVN client
* Execute mvn eclipse:eclipse from command line
* Refresh project (F5)

To update classpath (e.g. if there is a new pom.xml) just repeat these steps.

===Option 3: using the m2eclipse plugin===
Chose “Project” from the “File” menu, select Maven and then “Checkout maven Projects from SCM”.

===Configure GWT plugin===
* Select Project Properties and check under Google “Use Google App Engine”
* In project properties set plugin as active and change WAR directory to be /src/main/webapp (there is no longer a /war directory!)

=Questions that may arise during development=
==How do I work with multiple projects in parallel==
To given an example: We work with projects A and B where B depends on A. (An example would be A = Protégé, B = WebProtégé.)

Assuming you would like to make a change to project A which is required to continue working with project B:

# Make the change in project A
# Go to the command line in project A's directory (e.g. in <tt>/home/<USER_NAME>/workspace/projectA</tt>) and enter <tt>mvn install</tt> [1], [2]. This will update your local Maven repository (M2_REPO) which typically is located in <tt>/home/.m2/repository</tt> respectively in <tt>c:\user\<username>\.m2\repository</tt>. [1]
# Go to the command line of project B and enter <tt>mvn eclipse:eclipse</tt> [2]. This will update the classpath and (re)load the artifact of project A.
# Continue developing in project B.

Actually there are two variants:
# Variant 1: you do not change the version number of the artifact of project A. In this case you do not have to modify the version number in project A's pom.xml. This is an advantage, another advantage is that you do not need to update the dependency section in the pom.xml of project B.
# Variant 2: you change the version number of the artifact of project A in the project A' pom.xml. This requires that you update the version in the dependency section in project B's pom.xml. The advantage of this variant is that you easily can switch back to the old version of project A's artifact, you even can have multiple versions in your repository.

The dependency section in the pom.xml the text above is refering to looks like:

<syntaxhighlight lang="xml">
<dependency>
<groupId>protege</groupId>
<artifactId>protege-core</artifactId>
<version>3.4.2</version>
</dependency>
</syntaxhighlight>

[1]: If you want to skip the unit tests use <tt>mvn install -DskipTests=true</tt> instead.

[2]: Alternatively you can use the m2eclipse plugin.

==How do I deploy my artifacts to the (central) Nexus repository==
First you have to have write privileges to BMIR's Nexus repository (http://bmir-hudson1.stanford.edu/nexus). Typically these privileges are only granted to a closed group of developers. Both, these privileges (-> credentials) and the path to the repository have to be entered to your Maven settings file (<tt><MAVEN_INSTALL_DIR>/conf/settings.xml</tt>). There is a [[Stanford:SettingsXmlExample|complete example of this file]] available.

As soon you execute <tt>mvn deploy</tt> the Nexus repository is updated. Please keep in mind that your artifact either is stored in the snapshot or in the release repository dependent on the version number in your pom.xml: If the version number ends with <tt>SNAPSHOT</tt> the snapshot directory is addressed, otherwise the release repository.

Keep in mind that...
* the SNAPSHOT repository allows the redeployment of an artifact (with the same version number), the release repository doesn't,
* a deployment (<tt>mvn deploy</tt>) to the SNAPSHOT repository will autoincrement the version number of your artifact (if not explicitly turned off in the pom.xml), a deployment to the release repository won't.
* there is no autoincrement of the version number during install (<tt>mvn install</tt>),
* there is no need to install a local Nexus repository on your machine.

==How to update classpath==
Just get latest pom.xml and execute mvn eclipse:eclipse. This will update (not overwrite) your classpath. Press refresh in Eclipse. There is not even a restart necessary.

=How to write unit test case (TestNG, JUnit) and UI test cases (FEST, QFS)=
This section is about standard unit tests, i.e. not about writing UI tests/integrations tests using Selenium.
==How to re-use existing JUnit test cases==
===Option 1: Convert JUnit test cases to TestNG test cases===
You either can do that programmatically as described in http://testng.org/doc/migrating.html or you do that manually. TestNG tests look pretty much the same then JUnit tests. What has to be done typically includes:
* Change <tt>import to org.testng.annotations.*;</tt> and <tt>import static org.testng.Assert.*;</tt>
* Add annotation <tt>@BeforeClass</tt> to setup-method.
* Add annotation <tt>@Test</tt> to your test methods

===Option 2: Keep JUnit tests cases as they are and run it from TestNG===
In the <tt>/src/test/resources/unit-tests.xml</tt> there is a section with <tt>junit=true</tt>. Just add your tests there.

Example (mind second set of tests)

<syntaxhighlight lang="xml">
<!DOCTYPE suite SYSTEM "http://testng.org/testng-1.0.dtd" >
<suite name="ProtegeTestSuite" verbose="1">
<test name="TestNG-Tests">
<classes>
<class name="edu.stanford.bmir.protege.web.server.WatchedEntitiesCacheTest"></class>
<class name="client.TestUnitProtege"></class>
</classes>
</test>
<test name="JUnit-Tests (Example)" junit="true">
<classes>
<class name="client.JUnitExample"></class>
</classes>
</test>
</suite>
</syntaxhighlight>

There are (theoretically) two options how to include JUnit tests cases to the continuous integration.
# Make sure that your test classes are in the designated folder /src/test/java and that they are following the naming convention *Test.java
# Specify the classes in the xml file in /src/test/resources
We decided to go for the latter option. All types of specification as test parameters, grouping of tests and running tests in parallel have to be defined in theses TestNG-XML-files (and not(!) in the pom.xml). In the pom.xml we deliberatly disabled the automatic execution of JUnit tests in the line

<syntaxhighlight lang="xml">
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<skip>true</skip>
</configuration>
...
</plugin>
</syntaxhighlight>

==Write new TestNG test cases==
The vest resource to start is http://www.testng.org. Nevertheless the following lines might be helpful:

It is recommended to use the TestNG plugin for Eclipse since it adds all libraries to your classpath. Then writing a new test case is straight forward:
* write a standard Java class. Even there is no naming convention required it is recommended to call the class XXXTest, whereas XXX stands for the class under test.
* Write some test methods. Even there is no naming convention required it is recommended to call the method testXXX, whereas XXX stands for the method to be tested. However the test methods require the annotation @Test.
* Optionally have methods which have to be executed one before the test class is executed respectively which are executed before each test method. Add annotations @BeforeClass, @AfterClass, @BeforeMethod, respectively @AfterMetehod
* Fix imports

<syntaxhighlight lang="java">
import junit.framework.Assert;
import org.testng.annotations.AfterClass;
import org.testng.annotations.BeforeClass;
import org.testng.annotations.Parameters;
import org.testng.annotations.Test;
</syntaxhighlight>

* Optional enhancements
** Add dependencies between methods e.g. <tt>@Test (dependsOnMethods = {"openICDTree"})</tt> where openICDTree is the name of the other method.
** Move test parameters from test code to the configuration file, e.g.

<syntaxhighlight lang="xml">
<test name="Navigation 1">
<parameter name="username" value="protege"/>
<parameter name="username" value="secret"/>
<classes>
<class name="selenium.TestICat"></class>
</classes>
</test>
</syntaxhighlight>

* Refer to these parameters in the Java code
<syntaxhighlight lang="java">
@Test
@Parameters({ "username", "password" })
public void login(String username, String password) throws InterruptedException {...}
</syntaxhighlight>

* Add new test case to the test-configuration xml as shown above.

==How to write UI test cases (web) with Selenium==
===General===
The UI tests use the Selenium test framework. You either can write the tests from scratch or use the Selenium IDE, a Firefox Plugin to record actions and to generate Java Code (TestNG classes).

The biggest challenge with writing UI tests is the identification of UI components since one can not relay on the id of the component. These ids are generated by GWT dynamically.

===Example Code===
s. example.
===How to locate UI elements===
s. example.
===Resources===
* How to locate elements
** General: http://seleniumhq.org/docs/04_selenese_commands.html#locating-elements
** Usefull X-Path patterns: http://seleniumhq.org/docs/appendix_locating_techniques.html#useful-xpath-patterns
** X-Path in general: http://www.w3schools.com/xpath/xpath_examples.asp
** Calendars, Comboboxes, Popup etc: http://www.ibm.com/developerworks/opensource/library/os-webautoselenium/index.html?cmp=dw&cpb=dwope&ct=dwnew&cr=dwnen&ccy=zz&csr=120910

==Comprehensive example==
There is a project that shows everything related to build and testing:
* how to write a pom.xml
* how to write and integrate unit tests (JUnit and TestNG)
* how to write and integrate integration tests (selenium)

Please visit https://bmir-gforge.stanford.edu/svn/hudson-test/Hudson-Test.
==How to write UI test cases (Swing) using FEST==
The tutorial on how to write FEST tests will be written upon decision for/against FEST. So far please refer to the official documentation: http://docs.codehaus.org/display/FEST/Getting+Started

The "Example-Project" (Hudson) also contains a demo application using FEST: https://bmir-gforge.stanford.edu/svn/hudson-test/Hudson-Test

==How to write UI test cases (Swing) using QF-Test==
The tutorial on how to write QFS tests will be written upon decision for/against QFS. So far please refer to the official documentation:
http://www.qfs.de (tutorials in English available).

=Other questions=
==How to switch to ICD11 with all data (database)==
Follow instructions given in http://groups.google.com/group/icat-users/web/accessing-the-icat-content-programmatically?hl=en&_done=%2Fgroup%2Ficat-users%3Fhl%3Den%26&hl=en

On Windows the import command might be slightly different than described in the website. Use instead
mysql --user=protege --password=protege < c:\protege_2010-11-01_04h02m.Monday.sql

In summary you need to
* import database (and check that protege DB acutally exists afterwards)
* add user
* grant rights to the user

In order to do so, make use of the follwing commands:
mysql -u root
mysql> -u root connect to localhost;
mysql> show databases;
mysql> use protege;
mysql> show tables;
mysql> CREATE USER protege IDENTIFIED BY 'protege';
mysql> GRANT SELECT, INSERT, UPDATE, DELETE on *.* to 'protege'@'localhost';

More useful commands: http://www.pantz.org/software/mysql/mysqlcommands.html

Stanford:SettingsXmlExample

2010-12-16T19:21:37Z

Johner: 2 revisions: Import from CF Pages

The following is an example for a settings.xml file. This file is specific for a developer's machine and has to be located in <tt><<Maven-Install-Dir>/conf</tt>
<syntaxhighlight lang="xml">

<?xml version="1.0" encoding="UTF-8"?>




<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">








<pluginGroups>

</pluginGroups>


<proxies>

</proxies>


<servers>


<server>
<id>snapshots</id>
<username>USER</username>
<password>SECRET_PASSWORD</password>
</server>


<server>
<id>releases</id>
<username>USER</username>
<password>SECRET_PASSWORD</password>
</server>
</servers>


<mirrors>
<mirror>

<id>nexus</id>
<mirrorOf>*</mirrorOf>
<url>http://bmir-hudson1/nexus/content/groups/public</url>
</mirror>
</mirrors>
<profiles>
<profile>
<id>nexus</id>
<properties>

<os.family>windows</os.family>
<nexus.path>http://bmir-hudson1/nexus/content/repositories</nexus.path>
</properties>


<repositories>
<repository>
<id>central</id>
<url>http://central</url>
<releases><enabled>true</enabled></releases>
<snapshots><enabled>true</enabled></snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>central</id>
<url>http://central</url>
<releases><enabled>true</enabled></releases>
<snapshots><enabled>true</enabled></snapshots>
</pluginRepository>
</pluginRepositories>
</profile>
<profile>
<id>sonar</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<properties>
</properties>
</profile>
</profiles>
<activeProfiles>

<activeProfile>nexus</activeProfile>
</activeProfiles>
</settings>
</syntaxhighlight>

You just can replace the existing settings.xml with this file/content.

Stanford:Tools

2010-12-16T19:21:37Z

Johner: 2 revisions: Import from CF Pages

=Description and Rationale for Tools=
This page is intended to give an overview on the systems and to describe why we selected particularily this set. How to install, operate, and use this tools is described in
* [[Stanford:AdministratorGuide| administrator guide]]
* [[Stanford:DeveloperGuide|developer guide]]

=Hudson=
Hudson is a server application to automatically and continuously build, test and deploy one or more projects. It provides an overview on the build and tests results including code metrics, architecture metrics, JUnit results and much more.

It is obvious that such repetitive tasks should be automated. However, there are several products to facilitate this task. Among those there is CruiseControl We decided to prefer Hudson over CruiseControl for the following reasons:

* Installation is simpler. It is just download the jar file. E.g. no installation of DB necessary.
* Administration is simpler: An easy to use web interface gives access to all administrative settings
* Easy integration with other tools e.g. with Sonar, TestNG and communication services
* Related to Plug-ins
* Easier plug-in development
* More plug-ins available (e.g. twitter, email, Sonar, Selenium)
* Easier plug-ins administration

Hudson executes the Maven script(s) including builds as well as unit and UI tests, triggers reporting and communication of build and test results.

<Link>Instruction how to install and configure Hudson.

=Nexus=
[[File:nexus.png|thumb|Nexus the central and shared repository for all developers (and users)]]
As more libraries a project requires and as more dependencies these libraries have as more complex the setup of a new development environment and of executing a build become. For example WebProtégé has dependencies to Protégé, to the Google Web Toolkit, to Apache libraries, and so on. And even the referenced libraries are interdependent.

Maven is capable of resolving these dependencies. Nexus is a repository manager which allows you to centrally provide these libraries in a versioned and reproducible manner. Nexus also can serve as proxy. So the developers (and the build system) just need to retrieve these files from the repository instead of individually downloading these artifacts redundantly. This not only saves bandwidth, but also reduces the load on “Central” (the central Maven repository).

Nexus is not replacing Maven. Nexus proxies the Maven requests to a central Maven repository. Nexus provides as the feature not only to proxy repositories, but to operate our “own” repository which is the deployment target of all of our projects. Please note that Maven itself uses a repository (the Maven repository).

Further feature of Nexus include
* a quick and easy search of all artifacts.
* Developers don’t have to have the entire source. They just can work with libraries from Nexus. This makes collaboration easier.
* Clear responsibility and maintenance of “official” 3rd party libraries.

An additional list of reasons for using repository managers can be found at http://www.sonatype.com/books/nexus-book/reference/sect-repoman-reasons.html.

A comparison of repository managers (Apache Archiva, Artifactory, and Nexus) can be found at http://docs.codehaus.org/display/MAVENUSER/Maven+Repository+Manager+Feature+Matrix.

“Standard” developers not necessarily have to deal with Nexus. She just uses Nexus as a repository to retrieve artifacts from. If she requires a new jar-file, this has to be done as described in the How-Tos. However, we recommend to have a local repository as well.

<Link>Instruction how to install and configure Nexus.

=Sonar=
Sonar is a very powerful platform to report the quality of software products considering aspects as
* Code metrics as complexity
* Error/bug patterns
* Architectural metrics
* Conformity with coding guidelines
* Results of tests (Unit tests, UI tests) including errors, failures and code coverage.

Sonar provides both, a comprehensive overview on the quality o projects as well as the option to drill down to single metrics/aspects and even to the single line of source code.

Sonar serves as shell compiling and consistently visualizing the results of numerous tools as Checkstyle, FindBugs, PMD, and TestNG .

<Link>Instruction how to install and configure Maven.

=TestNG=
We prefer TestNG over JUnit for the following reasons:
* Better separation of test code and test data
* Better grouping of tests and re-use of test groups
* Better support for parallel (multi-threaded) testing
* TestNG automatically produces test reports without having the need to use other tasks as JUnitReport.

=Maven=
Maven is used by
* Developers to initially create his workspace (initial build)
* To define the build and test process which is executed and scheduled by Hudson.

<Link>Instruction how to install and configure Maven.

# validate
# generate-sources
# process-sources
# generate-resources
# process-resources
# compile
# process-classes
# generate-test-sources
# process-test-sources
# generate-test-resources
# process-test-resources
# test-compile
# test
# prepare-package (maven 2.1+)
# package
# pre-integration-test
# integration-test
# post-integration-test
# verify
# install
# deploy

=Firefox =
We prefer Firefox over other browsers for two major reasons:
* Firefox is available on LINUX, too. LINUX will be our server OS.
* There is a Selenium Plugin available for Firefox.

Having said this, it is nevertheless worth mentioning that the web applications have to be tested on other browsers as well. This requires no plugin. The plugin is only required for automated UI tests.

=Selenium Server (Selenium Remote Control)=
[[File:selenium-server.png|thumb|Selenium Server Architecure. Picture taken form http://seleniumhq.org/projects/remote-control]]
Selenium remote control is a server which allows developers test web applications (even with AJAX) using Java code (e.g. JUnit, TestNG) or any other language.

Selenium RC automatically launches the browser, simulates the user actions and kills the browser afterwards. Thereby Selenium RC facilitates the complete test automation ($rarr; regression testing) of rich web applications.

<Link>Instruction how to install and configure Selenium.

=Selenium Plugin (optional)=
The Selenium IDE is an optional Firefox plugin which helps developers to record actions in the browser and generate Java code. However, the capture & replay functionality is very limited. Therefore Selenium tests will be written as regular Java respectively TestNG code.