You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@santuario.apache.org by mu...@apache.org on 2006/10/19 23:15:20 UTC
svn commit: r465892 -
/xml/security/tags/J_1_4_RC2a/doc/site/src/documentation/content/xdocs/Java/installation.xml
Author: mullan
Date: Thu Oct 19 14:15:18 2006
New Revision: 465892
URL: http://svn.apache.org/viewvc?view=rev&rev=465892
Log:
Lots of changes:
- updated link to ant site
- updated "Compiling the source" section
- added more sample targets to try out
- updated list of files in source package release
- updated 'Where is my JCE" section, updated property names, and how
to configure it to use a different JCE provider
- removed commented out sections, and some stale content
Modified:
xml/security/tags/J_1_4_RC2a/doc/site/src/documentation/content/xdocs/Java/installation.xml
Modified: xml/security/tags/J_1_4_RC2a/doc/site/src/documentation/content/xdocs/Java/installation.xml
URL: http://svn.apache.org/viewvc/xml/security/tags/J_1_4_RC2a/doc/site/src/documentation/content/xdocs/Java/installation.xml?view=diff&rev=465892&r1=465891&r2=465892
==============================================================================
--- xml/security/tags/J_1_4_RC2a/doc/site/src/documentation/content/xdocs/Java/installation.xml (original)
+++ xml/security/tags/J_1_4_RC2a/doc/site/src/documentation/content/xdocs/Java/installation.xml Thu Oct 19 14:15:18 2006
@@ -58,8 +58,8 @@
<section>
<title>Prerequisites</title>
<p>
- Make sure you get the Jakarta Ant Tool from
- <jump href="ext:ant">http://jakarta.apache.org/ant/</jump>
+ Make sure you get the Apache Ant Tool from
+ <jump href="ext:ant">http://ant.apache.org</jump>
</p>
</section>
@@ -82,7 +82,7 @@
The checkout will contain both the Java and the C++ source.
</p>
<p>
- A HTTP interface to browse the sources online is available via
+ An HTTP interface to browse the sources online is available via
<jump href="site:getting-involved/SVN">http://svn.apache.org/viewvc/xml/security/trunk/</jump>
</p>
</section>
@@ -90,64 +90,40 @@
<section>
<title>Compiling the source</title>
<p>
- At the command prompt type <code>ant test</code>. If you want to
- use jikes instead of your default java compiler locate the <code>build.xml</code>
- file and replace the line
+ At the command prompt type <code>ant test</code>. If you are behind
+ a firewall, you may need to set the <code>proxy.host</code> and
+ <code>proxy.port</code> in the <code>proxy.properties</code> file.
</p>
- <source><property name="build.compiler" value="classic"/></source>
<p>
- with
+ By default, the XML Security project downloads and uses the
+ Legion of Bouncy Castle's JCE provider. See "Where is my JCE? below
+ for information on how this works and configuring it to use other
+ providers.
</p>
- <source><property name="build.compiler" value="jikes"/></source>
</section>
-<!-- Uncommented in the original docs
- <section>
- <title>Unpacking the files</title>
- <p>
- &packagename; is packaged as a ZIP file for all
- platforms and operating systems. You can run the Java
- <ref>jar</ref> command to unpack the distribution.
- </p>
- <ul>
- <li>jar xf &packagename;-bin.&packageversion;.zip</li>
- <li>jar xf &packagename;-src.&packageversion;.zip</li>
- <li>This command creates a "&packagedirectory;" sub-directory in the
- current directory containing all the files.</li>
- </ul>
- </section>
-
- <section>
- <title>Files in the binary package release</title>
- <table>
- <tr><td>LICENSE</td><td>License for &packagename;</td></tr>
- <tr><td>Readme.html</td><td>Web page redirect to docs/html/index.html</td></tr>
- <tr><td>xerces.jar</td><td>Jar file containing all the parser class files</td></tr>
- <tr><td>xercesSamples.jar</td><td>Jar file containing all sample class files</td></tr>
- <tr><td>data/</td><td>Directory containing sample XML data files</td></tr>
- <tr><td>doc/html/</td><td>Directory containing documentation</td></tr>
- <tr><td>doc/html/api/</td><td>Directory containing Javadoc API</td></tr>
- </table>
- <note>To use &packagename; you do not need the source files.</note>
- </section>
--->
<section>
<title>Testing the distibution</title>
<p>
The first way to ensure that everything is in place is to run the unit
tests. This is simply done by typing <code>ant test</code>. This starts
- the included JUnit test cases. Actually, we do not have complete test
- coverage, but as a first start, it works.
+ the included JUnit test cases.
</p>
</section>
<section>
<title>Playing around with the examples </title>
<p>
- To see how the distribution works, simply run <code>ant
- mega-sample</code> to let ant execute several examples from the
- <code>src_samples/</code> directory.
- </p>
+ To see how the distribution works, simply run one of the sample
+ targets below to let ant execute several examples from the
+ <code>src_samples/</code> directory:
+ </p>
+ <ul>
+ <li><code>mega-sample</code></li>
+ <li><code>jsr105-samples</code></li>
+ <li><code>encryptAndDecrypt</code></li>
+ <li><code>signAndVerify</code></li>
+ </ul>
</section>
<section>
<title>Files in the source package release</title>
@@ -158,7 +134,15 @@
file before building</td>
</tr>
<tr>
- <td>LICENSE.txt</td>
+ <td>provider.properties</td>
+ <td>JCE provider properties for ant</td>
+ </tr>
+ <tr>
+ <td>proxy.properties</td>
+ <td>Proxy properties for ant</td>
+ </tr>
+ <tr>
+ <td>LICENSE</td>
<td>License for the software</td>
</tr>
<tr>
@@ -170,15 +154,31 @@
<td>Web page redirect required for building documentation</td>
</tr>
<tr>
- <td>STATUS</td>
+ <td>CHANGELOG.txt</td>
+ <td>Revision history</td>
+ </tr>
+ <tr>
+ <td>TODO</td>
<td>Current source code status information</td>
</tr>
<tr>
+ <td>INSTALL</td>
+ <td>Installation notes</td>
+ </tr>
+ <tr>
+ <td>NOTICE</td>
+ <td>Release notice</td>
+ </tr>
+ <tr>
+ <td>KEYS</td>
+ <td>PGP keys for validating distribution signatures</td>
+ </tr>
+ <tr>
<td>data/</td>
<td>Directory containing sample data files and test vectors for the unit tests</td>
</tr>
<tr>
- <td>doc/xml/</td>
+ <td>doc/site/</td>
<td>Directory containing documentation, in XML form</td>
</tr>
<tr>
@@ -193,58 +193,53 @@
<td>src_unitTests/</td>
<td>Directory containing source code for unit tests</td>
</tr>
+ <tr>
+ <td>libs/</td>
+ <td>Directory containing jar file dependencies </td>
+ </tr>
</table>
</section>
<section>
<title>Where is my JCE?</title>
<p>
- There is <em>no</em> JCE bundled together with this
- distribution. Living in Germany, I had no problem to include the JCE in
- this software package but then I realized that the Apache Project is
- hosted in the US where some export restrictions apply to the
- cryptographic primitives.
- </p>
- <p>
- Well, how do we solve this problem? The nice guys from the <jump
- href="ext:bouncy">Bouncy Castle</jump> where so
- helpful to supply the JAR that you need to create HMAC integrity checks
- on their web site. When you use the ant makefile <code>build.xml</code>
- and simply say <code>ant compile</code> or <code>ant get-jce</code>,
- <code>ant</code> tries to fetch this JAR from the australian
- server. After that step, the compilation works completely.
- </p>
- <p/>
- <p>
- The ant make tools initiates an automated download of the BouncyCastle
- JCE. The file is downloaded into the libs/ directory and a "bc-" is
- prepended to the filename. This is done because we want the provider
- name (bc means BouncyCastle) being visible in the JAR's filename.
- </p>
- <p/>
- <p>
- If you are a little paranoid like all security people and don't want
- ant to make automated downloads or your firewall doesn't permit it
- (preventing programs "phoning home"), look in the
- <code>./build.xml</code> file for the properties called
- </p>
- <p/>
- <source><![CDATA[
- <property name="jce.download.file" value="]]>&jce_download_file;<![CDATA[ />
- <property name="jce.download"
- value="http://www.bouncycastle.org/download/${jce.download.file}" />
- <property name="lib.jce" value="${libs}/bc-${jce.download.file}" />
- ]]></source>
+ There is <em>no</em> JCE bundled together with this distribution
+ since the Apache Project is hosted in the US where some export
+ restrictions apply to the cryptographic primitives.
+ </p>
+ <p>
+ By default, the ant compile target initiates an automated download of
+ the BouncyCastle JCE. The file is downloaded into the <code>libs/</code>
+ directory and a <code>bc-</code> is prepended to the filename. This is
+ done because we want the provider name (bc means BouncyCastle) being
+ visible in the JAR's filename.
+ </p>
+ <p>
+ If you prefer to use a different JCE provider or don't want ant to make
+ automated downloads or your firewall doesn't permit it, look in the
+ <code>./provider.properties</code> file for the properties called
+ </p>
+ <source>
+ jce.provider.source = http://www.bouncycastle.org/download
+ jce.provider.prefix = bc
+ jce.provider.jar = &jce_download_file;
+ </source>
<p>
- Here you can see that the file
+ and edit them accordingly. Above you can see that the file
<jump href="ext:java/jce/download/file">&jce_download_file;</jump>
is downloaded and stored in the location <code>&lib_jce;</code>
</p>
<p>
- If you do this by hand (pointing you favourite web browser and download
- it yourself), simply put a "<code>bc-</code>" in front of the filename
- and put it to <code>./libs/</code>, then ant won't try to make a
- download.
+ Alternatively if you prefer to use the JCE provider included in the
+ JDK (as of JDK 5.0, Sun's implementation supports all of the required
+ algorithms), or you prefer to download the JCE provider manually,
+ simply set the <code>has.jce.provider</code> property to true in the
+ <code>provider.properties</code> file:
+ </p>
+ <p>
+ <code>has.jce.provider=true</code>
+ </p>
+ <p>If this property is set, ant will not try to download a JCE provider.
</p>
</section>
</body>