*** empty log message ***

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

src/contrib/src/org/apache/poi/contrib/poibrowser/POIBrowser.java

@@ -18,11 +18,19 @@
 
 package org.apache.poi.contrib.poibrowser;
 
-import java.awt.event.*;
-import java.io.*;
-import javax.swing.*;
-import javax.swing.tree.*;
-import org.apache.poi.poifs.eventfilesystem.*;
+import java.awt.event.WindowAdapter;
+import java.awt.event.WindowEvent;
+import java.io.FileInputStream;
+import java.io.IOException;
+
+import javax.swing.JFrame;
+import javax.swing.JScrollPane;
+import javax.swing.JTree;
+import javax.swing.tree.DefaultMutableTreeNode;
+import javax.swing.tree.DefaultTreeModel;
+import javax.swing.tree.MutableTreeNode;
+
+import org.apache.poi.poifs.eventfilesystem.POIFSReader;
 
 /**
  * <p>The main class of the POI Browser. It shows the structure of POI

src/contrib/src/org/apache/poi/contrib/poibrowser/PropertySetDescriptor.java

@@ -18,9 +18,16 @@
 
 package org.apache.poi.contrib.poibrowser;
 
-import java.io.*;
-import org.apache.poi.hpsf.*;
-import org.apache.poi.poifs.filesystem.*;
+import java.io.IOException;
+import java.io.UnsupportedEncodingException;
+
+import org.apache.poi.hpsf.MarkUnsupportedException;
+import org.apache.poi.hpsf.NoPropertySetStreamException;
+import org.apache.poi.hpsf.PropertySet;
+import org.apache.poi.hpsf.PropertySetFactory;
+import org.apache.poi.hpsf.UnexpectedPropertySetTypeException;
+import org.apache.poi.poifs.filesystem.DocumentInputStream;
+import org.apache.poi.poifs.filesystem.POIFSDocumentPath;
 
 /**
  * <p>Describes the most important (whatever that is) features of a
@@ -63,8 +70,9 @@ public class PropertySetDescriptor extends DocumentDescriptor
                                  final POIFSDocumentPath path,
                                  final DocumentInputStream stream,
                                  final int nrOfBytesToDump)
-        throws NoPropertySetStreamException, MarkUnsupportedException,
-        UnexpectedPropertySetTypeException, IOException
+        throws UnexpectedPropertySetTypeException, NoPropertySetStreamException,
+               MarkUnsupportedException, UnsupportedEncodingException,
+               IOException
     {
         super(name, path, stream, nrOfBytesToDump);
         propertySet = PropertySetFactory.create(stream);

src/documentation/content/xdocs/hpsf/how-to.xml

@@ -41,10 +41,15 @@
 
     <li>
      The <link href="#sec4">fourth section</link> tells you how to write
-     property set streams. Writing is still rudimentary in HPSF. You have to
-     understand the <link href="#sec3">third section</link> before you should
-     think about writing properties. Check the Javadoc API documentation to
-     find out about the details!
+     property set streams. At this time HPSF provides low-level methods only
+     for writing properties. Therefore you have to understand the <link
+      href="#sec3">third section</link> before you should think about writing
+     properties. Check the Javadoc API documentation to find out about the
+     details!  <strong>Please note:</strong> HPSF's writing functionality is
+     <strong>not</strong> present in POI releases up to and including 2.5. In
+     order to write properties you have to download a later POI release (when
+     available) or retrieve the POI development version from the CVS
+     repository.
     </li>
    </ol>
 
@@ -853,16 +858,24 @@ No property set stream: "/1Table"</source>
       codepage number is illegal, an UnsupportedEncodingException will be
       thrown.</p>
 
-     <p>There are two exceptions to the rule that a character encoding's name
-      is derived from the codepage number by prepending the string "cp" to
-      it:</p>
+     <p>There are some exceptions to the rule saying that a character
+      encoding's name is derived from the codepage number by prepending the
+      string "cp" to it:</p>
 
      <dl>
+      <dt>Codepage 932</dt>
+      <dd>is mapped to the character encoding "SJIS".</dd>
       <dt>Codepage 1200</dt>
       <dd>is mapped to the character encoding "UTF-16".</dd>
       <dt>Codepage 65001</dt>
       <dd>is mapped to the character encoding "UTF-8".</dd>
      </dl>
+
+     <p>Probably there will be a need to add more mappings between codepage
+      numbers and character encoding names. They should be added to the method
+      <code>codepageToEncoding</code> in the class
+      <code>org.apache.poi.hpsf.VariantSupport</code>. The HPSF author will
+      appreciate any advices for mappings to be added.</p>
     </section>
    </section>
 
@@ -873,7 +886,7 @@ No property set stream: "/1Table"</source>
 
     <section><title>Overview of Writing Properties</title>
      <p>Writing properties is possible at a low level only at the moment. You
-      have to deal with property IDs and variant types to write
+      have to deal with things like property IDs and variant types to write
       properties. There are no convenience classes or convenience methods for
       dealing with summary information and document summary information streams
       yet. Therefore you should have read <link href="#sec3">section 3</link>
@@ -884,7 +897,9 @@ No property set stream: "/1Table"</source>
       <code>MutableProperty</code>, and some helper classes. The "mutable"
       classes extend their respective superclasses <code>PropertySet</code>,
       <code>Section</code>, and <code>Property</code> and provide "set" and
-      "write" methods.</p>
+      "write" methods, following the <link
+       href="http://en.wikipedia.org/wiki/Decorator_pattern">Decorator
+       pattern</link>.</p>
 
      <p>When you are going to write a property set stream your application has
       to perform the following steps:</p>
@@ -934,15 +949,38 @@ No property set stream: "/1Table"</source>
 
      <source>package org.apache.poi.hpsf.examples;
 
-import java.io.*;
-
-import org.apache.poi.hpsf.*;
-import org.apache.poi.hpsf.wellknown.*;
-import org.apache.poi.poifs.filesystem.*;
-
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+
+import org.apache.poi.hpsf.MutableProperty;
+import org.apache.poi.hpsf.MutablePropertySet;
+import org.apache.poi.hpsf.MutableSection;
+import org.apache.poi.hpsf.SummaryInformation;
+import org.apache.poi.hpsf.Variant;
+import org.apache.poi.hpsf.WritingNotSupportedException;
+import org.apache.poi.hpsf.wellknown.PropertyIDMap;
+import org.apache.poi.hpsf.wellknown.SectionIDMap;
+import org.apache.poi.poifs.filesystem.POIFSFileSystem;
+
+/**
+ * &lt;p&gt;This class is a simple sample application showing how to create a property
+ * set and write it to disk.&lt;/p&gt;
+ *
+ * @author Rainer Klute
+ * @since 2003-09-12
+ */
 public class WriteTitle
 {
-
+    /**
+     * &lt;p&gt;Runs the example program.&lt;/p&gt;
+     *
+     * @param args Command-line arguments. The first and only command-line 
+     * argument is the name of the POI file system to create.
+     * @throws IOException if any I/O exception occurs.
+     * @throws WritingNotSupportedException if HPSF does not (yet) support 
+     * writing a certain property type.
+     */
     public static void main(final String[] args)
     throws WritingNotSupportedException, IOException
     {
@@ -955,7 +993,6 @@ public class WriteTitle
         }
 
         final String fileName = args[0];
-        final POIFSFileSystem poiFs = new POIFSFileSystem();
 
         /* Create a mutable property set. Initially it contains a single section
          * with no properties. */
@@ -978,6 +1015,12 @@ public class WriteTitle
         p.setType(Variant.VT_LPWSTR);
         p.setValue("Sample title");
 
+        /* Place the property into the section. */
+        ms.setProperty(p);
+
+        /* Create the POI file system the property set is to be written to. */
+        final POIFSFileSystem poiFs = new POIFSFileSystem();
+
         /* For writing the property set into a POI file system it has to be
          * handed over to the POIFS.createDocument() method as an input stream
          * which produces the bytes making out the property set stream. */
@@ -994,8 +1037,9 @@ public class WriteTitle
 
 }</source>
 
-     <p>The applications first checks that there is exactly a single argument
-      on the command line. If this is true, the application stores it in the
+     <p>The application first checks that there is exactly one single argument
+      on the command line: the name of the file to write. If this single
+      argument is present, the application stores it in the
       <code>fileName</code> variable. It will be used in the end when the POI
       file system is written to a disk file.</p>
 

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

@@ -1,4 +1,3 @@
-
 /* ====================================================================
    Copyright 2002-2004   Apache Software Foundation
 
@@ -26,6 +25,7 @@ import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.io.UnsupportedEncodingException;
 import java.util.HashMap;
 import java.util.Iterator;
 import java.util.Map;
@@ -98,9 +98,12 @@ public class CopyCompare
      * create a property set from a POI document stream that is not a property
      * set stream.
      * @exception IOException if any I/O exception occurs.
+     * @exception UnsupportedEncodingException if a character encoding is not
+     * supported.
      */
     public static void main(final String[] args)
-    throws MarkUnsupportedException, NoPropertySetStreamException, IOException
+    throws NoPropertySetStreamException, MarkUnsupportedException,
+           UnsupportedEncodingException, IOException
     {
         String originalFileName = null;
         String copyFileName = null;
@@ -174,7 +177,8 @@ public class CopyCompare
     private static boolean equal(final DirectoryEntry d1,
                                  final DirectoryEntry d2,
                                  final StringBuffer msg)
-    throws MarkUnsupportedException, NoPropertySetStreamException, IOException
+    throws NoPropertySetStreamException, MarkUnsupportedException,
+           UnsupportedEncodingException, IOException
     {
         boolean equal = true;
         /* Iterate over d1 and compare each entry with its counterpart in d2. */
@@ -251,7 +255,8 @@ public class CopyCompare
      */
     private static boolean equal(final DocumentEntry d1, final DocumentEntry d2,
                                  final StringBuffer msg)
-    throws MarkUnsupportedException, NoPropertySetStreamException, IOException
+    throws NoPropertySetStreamException, MarkUnsupportedException,
+           UnsupportedEncodingException, IOException
     {
         boolean equal = true;
         final DocumentInputStream dis1 = new DocumentInputStream(d1);

src/testcases/org/apache/poi/hpsf/basic/TestBasic.java

@@ -1,4 +1,3 @@
-
 /* ====================================================================
    Copyright 2002-2004   Apache Software Foundation
 
@@ -24,6 +23,7 @@ import java.io.FileFilter;
 import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.io.InputStream;
+import java.io.UnsupportedEncodingException;
 import java.util.List;
 
 import junit.framework.Assert;
@@ -133,9 +133,13 @@ public class TestBasic extends TestCase
      * NoPropertySetStreamException} will be thrown when trying to
      * create a {@link PropertySet}.</p>
      * 
-     * @exception IOException if an I/O exception occurs
+     * @exception IOException if an I/O exception occurs.
+     * 
+     * @exception UnsupportedEncodingException if a character encoding is not
+     * supported.
      */
-    public void testCreatePropertySets() throws IOException
+    public void testCreatePropertySets()
+    throws UnsupportedEncodingException, IOException
     {
         Class[] expected = new Class[]
             {

src/testcases/org/apache/poi/hpsf/basic/TestEmptyProperties.java

@@ -22,6 +22,7 @@ import java.io.File;
 import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.io.InputStream;
+import java.io.UnsupportedEncodingException;
 
 import junit.framework.Assert;
 import junit.framework.TestCase;
@@ -116,9 +117,13 @@ public class TestEmptyProperties extends TestCase
      * NoPropertySetStreamException} will be thrown when trying to
      * create a {@link PropertySet}.</p>
      * 
-     * @exception IOException if an I/O exception occurs
+     * @exception IOException if an I/O exception occurs.
+     * 
+     * @exception UnsupportedEncodingException if a character encoding is not
+     * supported.
      */
-    public void testCreatePropertySets() throws IOException
+    public void testCreatePropertySets()
+    throws UnsupportedEncodingException, IOException
     { 
         Class[] expected = new Class[]
             {

src/testcases/org/apache/poi/hpsf/basic/TestUnicode.java

@@ -26,6 +26,7 @@ import java.io.IOException;
 import junit.framework.Assert;
 import junit.framework.TestCase;
 
+import org.apache.poi.hpsf.Constants;
 import org.apache.poi.hpsf.HPSFException;
 import org.apache.poi.hpsf.PropertySet;
 import org.apache.poi.hpsf.PropertySetFactory;
@@ -99,7 +100,7 @@ public class TestUnicode extends TestCase
         Assert.assertEquals(ps.getSectionCount(), 2);
         Section s = (Section) ps.getSections().get(1);
         Assert.assertEquals(s.getProperty(1),
-                            new Integer(1200));
+                            new Integer(Constants.CP_UTF16));
         Assert.assertEquals(s.getProperty(2),
                             new Long(4198897018L));
         Assert.assertEquals(s.getProperty(3),