Extended documentation.

git-svn-id: https://joinup.ec.europa.eu/svn/mocca/trunk@739 8a26b1a7-26f0-462f-b9ef-d0e30c41f5a4

12 files changed, 217 insertions, 109 deletions

diff --git a/BKUOnline/src/site/apt/configuration.apt b/BKUOnline/src/site/apt/configuration.apt
new file mode 100644
index 00000000..38b05e12
--- /dev/null
+++ b/BKUOnline/src/site/apt/configuration.apt
@@ -0,0 +1,56 @@
+	---
+	Configuration
+	---
+	EGIZ
+	---
+	2010
+	---
+	
+MOCCA Online Configuration
+
+	MOCCA Online comes with a reasonable default configuration. Therefore, providing your own configuration is only required when you need configuration options different from the default parameters.
+	
+	Since MOCCA version 1.3 a configuration resource may be specified as servlet context init parameter. This allows to keep your configuration resource outside of the deployed servlet context and to redeploy the web application without overwriting your configuration resource.
+	
+	To specify your own configuration {{{http://static.springsource.org/spring/docs/2.5.5/reference/resources.html}resource}} simply set the corresponding servlet context init parameter <<<configurationResource>>>. Please refer to the documentation of your servlet container on how to set servlet context initialization parameters. Usually this is done via the <<<web.xml>>> file in your web application.
+	
+	<<<WEB-INF/web.xml>>>:
+	
++------------------+
+...
+<web-app>
+
+  ...
+  <context-param>
+    <param-name>configurationResource</param-name>
+    <param-value>file://mocca/configuration.xml</param-value>
+  </context-param>
+  ...
+
+</web-app>
++------------------+
+
+	The value of the <<<configurationResource>>> parameter must be a valid {{{http://static.springsource.org/spring/docs/2.5.5/reference/resources.html}Spring resource}} name. Placeholders such as <<<$\{user.home\}>>> are also supported (via {{{http://static.springsource.org/spring/docs/2.5.5/api/org/springframework/beans/factory/config/PropertyPlaceholderConfigurer.html}Spring's Property Placeholder Configurer}}).
+	
+* Apache Tomcat	
+	
+	In addition to the specifying init parameters in the <<<web.xml>>> Apache Tomcat also allows to provide a file named <<<$CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml>>> (e.g. <<<.../conf/Catalina/localhost/mocca.xml>>>) to specify context parameters. See also {{http://tomcat.apache.org/tomcat-6.0-doc/config/context.html}}.
+	
+	The <<<configurationResource>>> parameter may be specified like the following:
+	
++------------------+
+
+<?xml version="1.0" encoding="UTF-8"?>
+<Context>
+
+  <Parameter name="configurationResource" value="file:${user.home}/mocca/configuration.xml" override="false"/>
+
+</Context>
+
++------------------+
+
+	This way the init parameter is not overwritten when the web application is redeployed.
+	
+* Configuration Options
+
+	For the available configuration options please see {{{../bkucommon/configuration.html}MOCCA Configuration}}.
\ No newline at end of file
diff --git a/BKUOnline/src/site/apt/deployment.apt b/BKUOnline/src/site/apt/deployment.apt
new file mode 100644
index 00000000..844b8d58
--- /dev/null
+++ b/BKUOnline/src/site/apt/deployment.apt
@@ -0,0 +1,77 @@
+	---
+	Deployment
+	---
+	EGIZ
+	---
+	2010
+	---
+	
+MOCCA Online Deployment
+
+	We have tried to keep the deployment procedure of MOCCA Online as simple as possible. In the standard case, all you need to do is download the appropriate war file and deploy it usign the standard deployment mechanism of your favorite servlet container.
+	
+    [Note: <<<war>>> File Deployment] 
+    
+    MOCCA assumes that the war file is unpacked upon deployment by the servlet container (which is the standard case e.g. in Apache Tomcat). 
+    
+    MOCCA requires proper directories for the certificate and trust stores. It is therefore possible to deploy and run MOCCA from the packed war file, but you need to provide your own configuration resource as described in {{{./configuration.html}Configuration}} in such a case. This configuration resource must provide URLs for the certificate and trust stores that resolve to proper directories (see {{{/bkucommon/configuration.html}MOCCA Configuration}}).
+    
+    []
+    
+    [Note: {Java Cryptographic Service Providers}]
+    
+    MOCCA requires some Java {{{http://java.sun.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html#ProviderArch}Cryptographic Service Providers}} to be registered.
+    
+    To allow for a simple deployment in the standard case MOCCA tries to register any required and not yet registered Cryptographic Service Providers upon startup. Since such security providers can only be registered statically with the class <<<{{{http://java.sun.com/javase/6/docs/api/java/security/Security.html}java.security.Security}}>>> which is load by a class loader shared by all servlet contexts (see {{{http://tomcat.apache.org/tomcat-6.0-doc/class-loader-howto.html}Apache Tomcat Class Loader How-To}}) the registered security providers are also visibile to other servlet contexts in the same container. This may affect other web applications in the same servlet container!
+    
+    When the security providers registered with the class <<<java.security.Security>>> have been load by the context class loader of one servlet context they are <visible but not usable> by servlets in another servlet context. This may cause other web applications in the same servlet container to fail!
+    
+    Therefore, <<when deploying MOCCA together with other web applications>> in the same servlet container (e.g. Apache Tomcat) <<make sure any Cryptographic Service Providers registered>> with the class <<<java.security.Security>>> <<are load by a shared class loader>>.
+    
+    There are (at least) two possibilities to accomplish this:
+    
+    	[[A]] 
+    	
+    	Make sure to remove the following <<<jar>>> files from the <<<WEB-INF/lib>>> directory of your deployed MOCCA web application (archive)
+    		
+    		* <<<iaik_jce_full_signed-*.jar>>>
+    		
+    		* <<<iaik_ecc_signed-*.jar>>>
+    		
+    		* <<<iaik_xsect-*.jar>>>
+    		
+    	and place them into the appropriate directory accessible by the shared class loader (e.g. <<<$CATALINA_HOME/lib>>> for Apache Tomcat).
+    	
+    	[[A]] 
+    	
+    	Register the security providers statically  with your Java VM as explained in {{{http://java.sun.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html#ProviderInstalling}Provider Installing}}. The classes
+    	    	
+    		* <<<iaik.security.provider.IAIK>>>
+    		
+    		* <<<iaik.security.ecc.provider.ECCProvider>>>
+    		
+    	should be registered at first and second position. And the class
+    	
+    		* <<<iaik.xml.crypto.XSecProvider>>>
+    		
+    	must be registered before any other XMLDSig provider (e.g. <<<org.jcp.xml.dsig.internal.dom.XMLDSigRI>>>).
+    	
+    	You may then tell MOCCA to omit the provider registration via the <<<RegisterSecurityProviders>>> {{{/bkucommmon/configuration.html}configuration parameter}}. However, this is not required as MOCCA detects already registered providers.
+    
+	[]
+	
+* Deploying MOCCA Online in Apache Tomcat 6.0
+
+	If MOCCA Online is the only application going to be deployed in Tomcat all you need to do is:
+
+	[[]] Copy the MOCCA Online <<<war>>> file to the <<<./webapps>>> directory of your Tomcat installation.
+	
+	[[]] Optionally rename the <<<war>>> file to match the desired context name (e.g. <<<mocca.war>>> for a web application context of <<</mocca>>>).
+	
+	[[]] Startup Tomcat. 
+	
+	[]
+	
+	MOCCA Online should now be accessible by directing your browser to {{http://localhost:8080/mocca/}} (replace <<<mocca>>> with the name of your war file).
+	
+	If other web applications are deployed into the same Tomcat instance, your may also need to perform the steps in the Note on {{Java Cryptographic Service Providers}} above.
\ No newline at end of file
diff --git a/BKUOnline/src/site/apt/index.apt b/BKUOnline/src/site/apt/index.apt
new file mode 100644
index 00000000..3ea0fdcd
--- /dev/null
+++ b/BKUOnline/src/site/apt/index.apt
@@ -0,0 +1,15 @@
+	---
+	MOCCA Online
+	---
+	EGIZ
+	---
+	2010
+	---
+
+
+MOCCA Online
+
+	MOCCA Online (aka <BKUOnline>) provides a new approach for an implementation of a {{{http://www.buergerkarte.at/konzept/securitylayer/spezifikation/20040514/Index.en.html}citizen card environment}} that overcomes the need to install dedicated software on the user's PC. MOCCA Online is <to be installed as online service> (usually together with a citizen card enabled web application) by a service provider. It offers the same interfaces and protocol bindings for integration with applications via the user's browser as a citizen card environment installed on the user's PC. Access to the user's citizen card and user interaction is performed via a Java Applet. Therefore, a user only needs a properly installed (PC/SC supported) card reader and a recent version of the Java browser plug-in to be able to use a citizen card with MOCCA Online.
+	
+	Releases can be found in the {{{http://egovlabs.gv.at/frs/?group_id=13}download}} section. For installation of MOCCA Online see {{{./deployment.html}Deployment}} and {{{./configuration.html}Configuration}}.
+	
\ No newline at end of file
diff --git a/BKUOnline/src/site/site.xml b/BKUOnline/src/site/site.xml
index 7500b6cc..00ea29c7 100644
--- a/BKUOnline/src/site/site.xml
+++ b/BKUOnline/src/site/site.xml
@@ -31,6 +31,11 @@ under the License.
   
     <menu ref="parent"/>
   
+    <menu name="${project.name}">
+      <item name="Deployment" href="deployment.html"/>
+      <item name="Configuration" href="configuration.html"/>
+    </menu>
+  
     <menu ref="reports"/>
 
   </body>
diff --git a/BKUWebStart/pom.xml b/BKUWebStart/pom.xml
index 4b43921b..b50b2436 100644
--- a/BKUWebStart/pom.xml
+++ b/BKUWebStart/pom.xml
@@ -33,6 +33,7 @@
             <configuration>
               <includeArtifactIds>BKULocal</includeArtifactIds>
               <includeGroupIds>at.gv.egiz</includeGroupIds>
+              <includeTypes>jar</includeTypes>
               <excludes>META-INF/</excludes>
               <outputDirectory>${project.build.directory}/classes</outputDirectory>
               <stripVersion>true</stripVersion>
@@ -280,4 +281,28 @@
       <systemPath>${java.home}/lib/javaws.jar</systemPath>
     </dependency>
   </dependencies>
+  <reporting>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-project-info-reports-plugin</artifactId>
+        <version>2.1.2</version>
+        <configuration>
+          <dependencyDetailsEnabled>true</dependencyDetailsEnabled>
+          <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
+        </configuration>
+        <reportSets>
+          <reportSet>
+            <reports>
+              <report>index</report>
+              <report>summary</report>
+              <report>license</report>
+              <report>dependencies</report>
+              <report>dependency-management</report>
+            </reports>
+          </reportSet>
+        </reportSets>
+      </plugin>
+    </plugins>
+  </reporting>
 </project>
diff --git a/bkucommon/pom.xml b/bkucommon/pom.xml
index dffde75d..b8f1b1b0 100644
--- a/bkucommon/pom.xml
+++ b/bkucommon/pom.xml
@@ -142,11 +142,17 @@
         <artifactId>maven-javadoc-plugin</artifactId>
         <version>2.7</version>
         <configuration>
-          <doctitle>${project.name} API ${project.version}</doctitle>
-          <windowtitle>${project.name} API ${project.version}</windowtitle>
-          <testDoctitle>${project.name} Test API ${project.version}</testDoctitle>
-          <testWindowtitle>${project.name} Test API ${project.version}</testWindowtitle>
+          <quiet>true</quiet>
+          <detectOfflineLinks>false</detectOfflineLinks>
         </configuration>
+        <reportSets>
+          <reportSet>
+            <id>non-aggregate</id>
+            <reports>
+              <report>javadoc</report>
+            </reports>
+          </reportSet>
+        </reportSets>
       </plugin>
 	  </plugins>
 	</reporting>
diff --git a/bkucommon/src/site/apt/configuration.apt b/bkucommon/src/site/apt/configuration.apt
index cf1d384d..9ae662f7 100644
--- a/bkucommon/src/site/apt/configuration.apt
+++ b/bkucommon/src/site/apt/configuration.apt
@@ -1,4 +1,4 @@
-	---
+ 	---
 	Configuration
 	---
 	EGIZ
@@ -70,7 +70,7 @@ MOCCA Configuration
 		
 		NOTE: Do not enable the following two options in production environments!
 
-		[<<<disableHostnameVerification>>>] May be set to <<<true>>> disable verification of the server host name given in the server's certificate.
+		[<<<disableHostnameVerification>>>] May be set to <<<true>>> to disable verification of the server host name given in the server's certificate.
 		
 		Default: <<<false>>>
 		
diff --git a/pom.xml b/pom.xml
index f81a4e2f..49a5f047 100644
--- a/pom.xml
+++ b/pom.xml
@@ -11,6 +11,7 @@
   <properties>
     <mocca.certificates.version>1.2</mocca.certificates.version>
     <mocca.fonts.version>1.2</mocca.fonts.version>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
   </properties>
   <modules>
     <module>utils</module>
diff --git a/src/site/apt/example.apt b/src/site/apt/example.apt
deleted file mode 100644
index 556e399c..00000000
--- a/src/site/apt/example.apt
+++ /dev/null
@@ -1,91 +0,0 @@
-Section title
-
-* Sub-section title
-
-** Sub-sub-section title
-
-*** Sub-sub-sub-section title
-
-**** Sub-sub-sub-sub-section title
-
-      * List item 1.
-
-      * List item 2.
-
-        Paragraph contained in list item 2.
-
-            * Sub-list item 1.
-
-            * Sub-list item 2.
-
-      * List item 3.
-        Force end of list:
-
-      []
-
-+------------------------------------------+
-Verbatim text not contained in list item 3
-+------------------------------------------+
-
-      [[1]] Numbered item 1.
-
-                [[A]] Numbered item A.
-
-                [[B]] Numbered item B.
-
-      [[2]] Numbered item 2.
-
-  List numbering schemes: [[1]], [[a]], [[A]], [[i]], [[I]].
-
-      [Defined term 1] of definition list.
-
-      [Defined term 2] of definition list.
-
-+-------------------------------+
-Verbatim text
-                        in a box
-+-------------------------------+
-
-  --- instead of +-- suppresses the box around verbatim text.
-
-[Figure name] Figure caption
-
-*----------*--------------+----------------:
-| Centered | Left-aligned | Right-aligned  |
-| cell 1,1 | cell 1,2     | cell 1,3       |
-*----------*--------------+----------------:
-| cell 2,1 | cell 2,2     | cell 2,3       |
-*----------*--------------+----------------:
-Table caption
-
-  No grid, no caption:
-
-*-----*------*
- cell | cell
-*-----*------*
- cell | cell
-*-----*------*
-
-  Horizontal line:
-
-=======================================================================
-
-^L
-  New page.
-
-  <Italic> font. <<Bold>> font. <<<Monospaced>>> font.
-
-  {Anchor}. Link to {{anchor}}. Link to {{http://www.pixware.fr}}.
-  Link to {{{anchor}showing alternate text}}.
-  Link to {{{http://www.pixware.fr}Pixware home page}}.
-
-  Force line\
-  break.
-
-  Non\ breaking\ space.
-
-  Escaped special characters: \~, \=, \-, \+, \*, \[, \], \<, \>, \{, \}, \\.
-
-  Copyright symbol: \251, \xA9, \u00a9.
-
-~~Commented out.
\ No newline at end of file
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
index c0d7ed95..3e2179cc 100644
--- a/src/site/apt/index.apt
+++ b/src/site/apt/index.apt
@@ -19,7 +19,7 @@ MOCCA Project
 
 	MOCCA Local is provided as Java Web Start application via {{http://webstart.buergerkarte.at}}.
     
-	* <<MOCCA Online>>
+	* <<{{{./BKUOnline/}MOCCA Online}}>>
 
 	MOCCA Online (aka <BKUOnline>) provides a new approach that overcomes the need to install dedicated software on the user's PC. MOCCA Online  is <to be installed as online service> (usually together with a citizen card enabled web application) by a service provider. It offers the same interfaces and protocol bindings for integration with applications via the user's browser as MOCCA Local. Access to the user's citizen card and user interaction is performed via a Java Applet. Therefore, a user only needs a properly installed (PC/SC supported) card reader and a recent version of the Java browser plug-in to be able to use a citizen card with MOCCA Online.  
 	
@@ -35,17 +35,7 @@ Releases
 
 Development
 
-	The current development version of MOCCA is 1.3.
-
-* Whats new in 1.3?
-
-	* Some parts of MOCCA needed to be redesigned to allow for a better integration with other software deployed within the same servlet container.
-
-	It is now possible to deploy multiple instances of MOCCA within the same servlet container. It should also be possible to deploy MOCCA together with most other software within a single servlet container.
-
-	* Configuration has been redesigned and is now based on {{{http://commons.apache.org/configuration/}commons-configuration}}.
-
-	
+	The current development version of MOCCA is 1.3. Take a look at {{{./new.html}What's new in MOCCA 1.3?}}
  
 Licensing
 
diff --git a/src/site/apt/new.apt b/src/site/apt/new.apt
new file mode 100644
index 00000000..62ad851e
--- /dev/null
+++ b/src/site/apt/new.apt
@@ -0,0 +1,22 @@
+	---
+	What's new in MOCCA 1.3?
+	---
+	EGIZ
+	---
+	2010
+	---
+	
+Whats new in MOCCA 1.3?
+
+	* Some parts of MOCCA needed to be redesigned to allow for a better integration with other software deployed within the same servlet container.
+
+	It is now possible to deploy multiple instances of {{{./BKUOnline}MOCCA Online}} within the same servlet container. Further, it should also be possible to deploy MOCCA Online together with most other software within a single servlet container.
+	
+	(See {{{./BKUOnline/deployment.html}Deployment}}.)
+
+	* Configuration has been redesigned and is now based on {{{http://commons.apache.org/configuration/}commons-configuration}}.
+	
+	(See {{{./bkucommon/configuration.html}Configuration}}.)
+
+	* {{{http://commons.apache.org/logging/}Commons-Logging}} has been replaced by {{{http://www.slf4j.org/}slf4j}} because of it's MDC (mapped diagnostic context) support.
+
diff --git a/src/site/site.xml b/src/site/site.xml
index 4f0ea09d..79196ed9 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -32,6 +32,7 @@ under the License.
   <body>
     <links>
       <item name="Austrian Citizen Card" href="http://www.buergerkarte.at"/>
+      <item name="Digital Austria" href="http://www.digitales.oesterreich.gv.at/site/6497/Default.aspx"/>
       <item name="EGIZ" href="http://www.egiz.gv.at" />
       <item name="Federal Chancellery" href="http://www.bka.gv.at/"/>
       <item name="Graz University of Technology" href="http://www.tugraz.at"/>
@@ -43,6 +44,7 @@ under the License.
       <item name="Download" href="http://egovlabs.gv.at/frs/?group_id=13"/>
       <item name="Source" href="http://egovlabs.gv.at/scm/?group_id=13"/>
       <item name="Wiki" href="http://egovlabs.gv.at/plugins/wiki/index.php?id=13&amp;type=g"/>
+      <item name="What's new in 1.3?" href="new.html"/>
     </menu>
     
     <menu ref="reports"/>