- Compiling POI now includes the example classes.

- Javadoc now includes the example classes.
- Added usage instructions to the POI Browser documentation.
- Added references to the examples and the contributed software to the POI overview.
- Added a missing import to an HPSF example class.


git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@353626 13f79535-47bb-0310-9956-ffa450edef68

build.xml

@@ -41,44 +41,65 @@
     The POI project Ant build.
   </description>
 
-    <property environment="env"/>
-
-    <property name="repository" value="http://www.ibiblio.org/maven"/>
-    <property name="forrest.home" value="${env.FORREST_HOME}"/>
-
-    <property name="main.resource1.dir" value="src/resources/fontmetrics"/>
-    <property name="main.src" location="src/java"/>
-    <property name="main.src.test" location="src/testcases"/>
-    <property name="main.documentation" value="src/documentation"/>
-    <property name="main.output.dir" location="build/classes"/>
-    <property name="main.output.test.dir" location="build/test-classes"/>
-    <property name="main.lib" location="lib"/>
-    <property name="main.reports.test" location="build/test-results"/>
-    <property name="main.jar1.dir" location="${main.lib}/commons-logging-1.0.1.jar"/>
-    <property name="main.jar1.url" value="${repository}/commons-logging/jars/commons-logging-1.0.1.jar"/>
-    <property name="main.jar2.dir" location="${main.lib}/log4j-1.2.8.jar"/>
-    <property name="main.jar2.url" value="${repository}/log4j/jars/log4j-1.2.8.jar"/>
-    <property name="main.testokfile" location="build/main-testokfile.txt"/>
-    <property name="scratchpad.src" location="src/scratchpad/src"/>
-    <property name="scratchpad.src.test" location="src/scratchpad/testcases"/>
-    <property name="scratchpad.lib" location="src/scratchpad/lib"/>
-    <property name="scratchpad.reports.test" location="build/scratchpad-test-results"/>
-    <property name="scratchpad.output.dir" location="build/scratchpad-classes"/>
-    <property name="scratchpad.output.test.dir" location="build/scratchpad-test-classes"/>
-    <property name="scratchpad.testokfile" location="build/scratchpad-testokfile.txt"/>
-    <property name="contrib.src" location="src/contrib/src"/>
-    <property name="contrib.src.test" location="src/contrib/testcases"/>
-    <property name="contrib.lib" location="src/contrib/lib"/>
-    <property name="contrib.reports.test" location="build/contrib-test-results"/>
-    <property name="contrib.output.dir" location="build/contrib-classes"/>
-    <property name="contrib.output.test.dir" location="build/contrib-test-classes"/>
-    <property name="contrib.jar1.dir" location="${contrib.lib}/commons-beanutils-1.6.jar"/>
-    <property name="contrib.jar1.url" value="${repository}/commons-beanutils/jars/commons-beanutils-1.6.jar"/>
-    <property name="contrib.jar2.dir" location="${contrib.lib}/commons-collections-2.1.jar"/>
-    <property name="contrib.jar2.url" value="${repository}/commons-collections/jars/commons-collections-2.1.jar"/>
-    <property name="contrib.jar3.dir" location="${contrib.lib}/commons-lang-1.0-b1.jar"/>
-    <property name="contrib.jar3.url" value="${repository}/commons-lang/jars/commons-lang-1.0-b1.jar"/>
-    <property name="contrib.testokfile" location="build/contrib-testokfile.txt"/>
+  <property environment="env"/>
+
+  <property name="repository" value="http://www.ibiblio.org/maven"/>
+  <property name="forrest.home" value="${env.FORREST_HOME}"/>
+
+  <!-- Main: -->
+  <property name="main.resource1.dir" value="src/resources/fontmetrics"/>
+  <property name="main.src" location="src/java"/>
+  <property name="main.src.test" location="src/testcases"/>
+  <property name="main.documentation" value="src/documentation"/>
+  <property name="main.output.dir" location="build/classes"/>
+  <property name="main.output.test.dir" location="build/test-classes"/>
+  <property name="main.lib" location="lib"/>
+  <property name="main.reports.test" location="build/test-results"/>
+  <property name="main.jar1.dir" location="${main.lib}/commons-logging-1.0.1.jar"/>
+  <property name="main.jar1.url" value="${repository}/commons-logging/jars/commons-logging-1.0.1.jar"/>
+  <property name="main.jar2.dir" location="${main.lib}/log4j-1.2.8.jar"/>
+  <property name="main.jar2.url" value="${repository}/log4j/jars/log4j-1.2.8.jar"/>
+  <property name="main.testokfile" location="build/main-testokfile.txt"/>
+
+  <!-- Scratchpad: -->
+  <property name="scratchpad.src" location="src/scratchpad/src"/>
+  <property name="scratchpad.src.test" location="src/scratchpad/testcases"/>
+  <property name="scratchpad.lib" location="src/scratchpad/lib"/>
+  <property name="scratchpad.reports.test" location="build/scratchpad-test-results"/>
+  <property name="scratchpad.output.dir" location="build/scratchpad-classes"/>
+  <property name="scratchpad.output.test.dir" location="build/scratchpad-test-classes"/>
+  <property name="scratchpad.testokfile" location="build/scratchpad-testokfile.txt"/>
+
+  <!-- Contributed software: -->
+  <property name="contrib.src" location="src/contrib/src"/>
+  <property name="contrib.src.test" location="src/contrib/testcases"/>
+  <property name="contrib.lib" location="src/contrib/lib"/>
+  <property name="contrib.reports.test" location="build/contrib-test-results"/>
+  <property name="contrib.output.dir" location="build/contrib-classes"/>
+  <property name="contrib.output.test.dir" location="build/contrib-test-classes"/>
+  <property name="contrib.jar1.dir" location="${contrib.lib}/commons-beanutils-1.6.jar"/>
+  <property name="contrib.jar1.url" value="${repository}/commons-beanutils/jars/commons-beanutils-1.6.jar"/>
+  <property name="contrib.jar2.dir" location="${contrib.lib}/commons-collections-2.1.jar"/>
+  <property name="contrib.jar2.url" value="${repository}/commons-collections/jars/commons-collections-2.1.jar"/>
+  <property name="contrib.jar3.dir" location="${contrib.lib}/commons-lang-1.0-b1.jar"/>
+  <property name="contrib.jar3.url" value="${repository}/commons-lang/jars/commons-lang-1.0-b1.jar"/>
+  <property name="contrib.testokfile" location="build/contrib-testokfile.txt"/>
+
+  <!-- Examples: -->
+  <property name="examples.src" location="src/examples/src"/>
+  <property name="examples.src.test" location="src/examples/testcases"/>
+  <property name="examples.lib" location="src/examples/lib"/>
+  <property name="examples.reports.test" location="build/examples-test-results"/>
+  <property name="examples.output.dir" location="build/examples-classes"/>
+  <property name="examples.output.test.dir" location="build/examples-test-classes"/>
+  <property name="examples.jar1.dir" location="${examples.lib}/commons-beanutils-1.6.jar"/>
+  <property name="examples.jar1.url" value="${repository}/commons-beanutils/jars/commons-beanutils-1.6.jar"/>
+  <property name="examples.jar2.dir" location="${examples.lib}/commons-collections-2.1.jar"/>
+  <property name="examples.jar2.url" value="${repository}/commons-collections/jars/commons-collections-2.1.jar"/>
+  <property name="examples.jar3.dir" location="${examples.lib}/commons-lang-1.0-b1.jar"/>
+  <property name="examples.jar3.url" value="${repository}/commons-lang/jars/commons-lang-1.0-b1.jar"/>
+  <property name="examples.testokfile" location="build/examples-testokfile.txt"/>
+
     <property name="junit.jar1.dir" location="${main.lib}/junit-3.8.1.jar"/>
     <property name="junit.jar1.url" value="${repository}/junit/jars/junit-3.8.1.jar"/>
     <property name="build.site" location="build/tmp/site/build/site"/>
@@ -117,6 +138,11 @@
         <pathelement location="${contrib.output.test.dir}"/>
     </path>
 
+  <path id="examples.classpath">
+    <path refid="main.classpath"/>
+    <pathelement location="${main.output.dir}"/>
+  </path>
+
 
 
   <!-- Prints POI's Ant usage help -->
@@ -170,8 +196,9 @@
         
         <mkdir dir="build"/>
         <mkdir dir="${main.output.dir}"/>
-        <mkdir dir="${contrib.output.dir}"/>
         <mkdir dir="${scratchpad.output.dir}"/>
+        <mkdir dir="${contrib.output.dir}"/>
+        <mkdir dir="${examples.output.dir}"/>
         <mkdir dir="${main.output.test.dir}"/>
         <mkdir dir="${contrib.output.test.dir}"/>
         <mkdir dir="${scratchpad.output.test.dir}"/>
@@ -221,8 +248,9 @@
         <get src="${junit.jar1.url}" dest="${junit.jar1.dir}"/>
     </target>
 
-    <target name="compile" depends="init,compile-main,compile-scratchpad,compile-contrib"
-        description="Compiles the POI classes"/>
+  <target name="compile" depends="init, compile-main, compile-scratchpad,
+    compile-contrib, compile-examples"
+    description="Compiles the POI main classes, scratchpad, contrib, and examples"/>
 
     <target name="compile-main" depends="init">
         <copy todir="${main.output.dir}">
@@ -266,6 +294,12 @@
         </javac>
     </target>
 
+  <target name="compile-examples" depends="init">
+    <javac srcdir="${examples.src}" destdir="${examples.output.dir}" debug="on">
+      <classpath refid="examples.classpath"/>
+    </javac>
+  </target>
+
     <target name="test" depends="test-main,test-scratchpad,test-contrib"
         description="Tests main, contrib and scratchpad"/>
 
@@ -550,7 +584,7 @@ FORREST_HOME environment variable!</echo>
       version="true"
       use="true"
       verbose="false"
-      windowtitle="POI API">
+      windowtitle="POI API Documentation">
 
       <packageset dir="${main.src}" defaultexcludes="yes">
         <include name="org/apache/poi/**"/>
@@ -561,17 +595,21 @@ FORREST_HOME environment variable!</echo>
       <packageset dir="${contrib.src}" defaultexcludes="yes">
         <include name="org/apache/poi/**"/>
       </packageset>
+      <packageset dir="${examples.src}" defaultexcludes="yes">
+        <include name="org/apache/poi/**"/>
+      </packageset>
 
       <classpath>
         <path refid="main.classpath"/>
         <path refid="scratchpad.classpath"/>
         <path refid="contrib.classpath"/>
+        <path refid="examples.classpath"/>
       </classpath>
 
-      <doctitle><![CDATA[<h1>POI Documentation</h1>]]></doctitle>
+      <doctitle><![CDATA[<h1>POI API Documentation</h1>]]></doctitle>
       <bottom>
         <![CDATA[<i>Copyright ${tstamp.year} The Apache Software Foundation or
-	its licensors, as applicable.</i>]]>
+        its licensors, as applicable.</i>]]>
       </bottom>
       <group title="HDF" packages="org.apache.poi.hdf*"/>
       <group title="HPSF" packages="org.apache.poi.hpsf*"/>
@@ -580,6 +618,11 @@ FORREST_HOME environment variable!</echo>
       <group title="POIFS" packages="org.apache.poi.poifs*"/>
       <group title="Record Generator" packages="org.apache.poi.record*"/>
       <group title="Utils" packages="org.apache.poi.util*"/>
+      <group>
+        <title>Examples</title>
+        <package name="org.apache.poi.hpsf.examples*"/>
+        <package name="org.apache.poi.hssf.usermodel.examples*"/>
+      </group>
     </javadoc>
 
     <antcall target="clover.html"/>

src/contrib/src/org/apache/poi/contrib/poibrowser/package.html

@@ -32,6 +32,10 @@
     (operating system) filenames. An internal file (i.e. a "stream" or a
     "document") is shown with its name, its size and a hexadecimal dump of its
     first bytes.</p>
+  </div>
+
+  <div>
+   <h3>Property Set Streams</h3>
 
    <p>The POI Browser pays special attention to property set streams. For
     example, the <tt>\005SummaryInformation</tt> stream  contains information
@@ -40,6 +44,49 @@
     not just its first bytes but analyses the whole stream and displays its
     contents in a more or less readable manner.</p>
   </div>
+
+  <div>
+   <h3>Running POI Browser</h3>
+
+   <p>Running the POI Browser requires you to start a Java Virtual Machine
+    (JVM) and to set up a valid classpath so that the JVM can find all the Java
+    classes it needs. These are the main POI classes and the "contrib" POI
+    classes.</p>
+
+   <p>The following instructions assume that you have set up your Java
+    enviromnent variables properly, i.e. the variable JAVA_HOME contains the
+    name of your Java installation directory and the variable PATH includes the
+    <var>bin</var> subdirectory of the Java installation directory. At the time
+   of this writing the current POI version was 2.5.1-final dating from August
+    4th, 2004. The example statements reflect version numbering and
+    date. Change the commands accordingly if you are running the POI Browser of
+   a later or earlier than this!</p>
+
+   <div>
+    <h4>Running POI Browser on Unix</h4>
+
+    <p>Suppose you have unpacked the POI&nbsp;2.5.1 release in the
+     <var>/opt/local/poi</var> directory of your Unix box. Then the following
+     command starts the POI Browser and displays the structure of the files
+     <var>MyWord.doc</var>, <var>MyExcel.xls</var> and
+     <var>MyPowerpoint.ppt</var>:</p>
+ 
+   <pre>java -classpath /opt/local/poi/poi-2.5.1-final-20040804.jar:/opt/local/poi/poi-contrib-2.5.1-final-20040804.jar org.apache.poi.contrib.poibrowser.POIBrowser MyWord.doc MyExcel.xls MyPowerpoint.ppt</pre>
+   </div>
+
+   <div>
+    <h4>Running POI Browser on Windows</h4>
+
+    <p>Suppose you have unpacked the POI&nbsp;2.5.1 release in the
+     <var>C:\Programs\POI</var> directory of your Windows box. Then the following
+     command starts the POI Browser and displays the structure of the files
+     <var>MyWord.doc</var>, <var>MyExcel.xls</var> and
+     <var>MyPowerpoint.ppt</var>:</p>
+ 
+   <pre>java -classpath C:\Programs\POI\poi-2.5.1-final-20040804.jar;C:\Programs\POI\poi-contrib-2.5.1-final-20040804.jar org.apache.poi.contrib.poibrowser.POIBrowser MyWord.doc MyExcel.xls MyPowerpoint.ppt</pre>
+   </div>
+
+  </div>
  </body>
 </html>
 

src/documentation/content/xdocs/overview.xml

@@ -7,6 +7,7 @@
     <title>Overview</title>
     <authors>
       <person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/>
+      <person id="RK" name="Rainer Klute" email="klute@apache.org"/>
     </authors>
   </header>
   
@@ -33,7 +34,7 @@
       <section><title>HSSF</title>
         <p>
           <link href="hssf/index.html">HSSF</link> is the set of APIs 
- 	  for reading and writing Microsoft Excel 97(-XP) spreadsheet using (only) Java.
+           for reading and writing Microsoft Excel 97(-XP) spreadsheet using (only) Java.
         </p>
       </section>
 
@@ -54,17 +55,45 @@
       <section><title>POI-Utils</title>
         <p>
           <link href="utils/index.html">POI-Utils</link> are general purpose artifacts
-	  from POI development that have not yet been implemented elsewhere.  We're 
+          from POI development that have not yet been implemented elsewhere.  We're 
           always looking to donate these and maintain them as part of a general library
           used in another project.  These are things we need to complete our mission but
           are generally outside of it.  
         </p>
       </section>
     </section>
+
+    <section>
+      <title>Examples</title>
+
+      <p>Small sample programs using the POI API are available in the
+        <em>src/examples</em> directory of the source distribution. Before
+        studying the source code you might want to have a look at the
+        "Examples" section of the <link
+          href="apidocs/overview-summary.html">POI API
+          documentation</link>.</p> 
+    </section>
+
+    <section><title>Contributed Software</title>
+      <p>Besides the "official" components outlined above there is some further
+      software distributed with POI. This is called "contributed" software. It
+        is not explicitly recommended or even maintained by the POI team, but
+        it might still be useful to you.</p>
+
+      <section>
+        <title>POI Browser</title>
+        <p>The POI Browser is a very simple Swing GUI tool that displays the
+          internal structure of a Microsoft Office file and especially the
+          property set streams. Further information and  instructions how to
+          execute it can be found in the <link
+            href="apidocs/org/apache/poi/contrib/poibrowser/package-summary.html#package_description">POI
+            Browser package description</link>.</p>
+      </section>
+    </section>
   </body>
   <footer>
     <legal>
-      Copyright (c) @year@ The POI Project All rights reserved.
+      Copyright 2005 The Apache Software Foundation or its licensors, as applicable.
       $Revision$ $Date$
     </legal>
   </footer>

src/examples/src/org/apache/poi/hpsf/examples/WriteAuthorAndTitle.java

@@ -34,6 +34,7 @@ import org.apache.poi.hpsf.MutableSection;
 import org.apache.poi.hpsf.NoPropertySetStreamException;
 import org.apache.poi.hpsf.PropertySet;
 import org.apache.poi.hpsf.PropertySetFactory;
+import org.apache.poi.hpsf.SummaryInformation;
 import org.apache.poi.hpsf.Util;
 import org.apache.poi.hpsf.Variant;
 import org.apache.poi.hpsf.WritingNotSupportedException;