Update JavaDoc for logging and marshalling

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

src/java/org/apache/poi/util/CommonsLogger.java

@@ -1,4 +1,3 @@
-
 /* ====================================================================
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
@@ -15,18 +14,16 @@
    See the License for the specific language governing permissions and
    limitations under the License.
 ==================================================================== */
-        
-
 package org.apache.poi.util;
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 
 /**
- * A logger class that strives to make it as easy as possible for
+ * An implementation of the {@link POILogger} using the
- * developers to write log calls, while simultaneously making those
+ * Apache Commons Logging framework. Which itself can be configured to
- * calls as cheap as possible by performing lazy evaluation of the log
+ * send log to various different log frameworks and even allows to create
- * message.<p>
+ * a small wrapper for custom log frameworks.
  */
 public class CommonsLogger implements POILogger
 {
@@ -36,8 +33,8 @@ public class CommonsLogger implements POILogger
     @Override
     public void initialize(final String cat) {
         this.log = _creator.getInstance(cat);
-    }   
+    }
-     
+
     /**
      * Log a message
      *
@@ -81,7 +78,7 @@ public class CommonsLogger implements POILogger
                 break;
         }
     }
-    
+
     /**
      * Log a message
      *

src/java/org/apache/poi/util/NullLogger.java

@@ -18,10 +18,11 @@
 package org.apache.poi.util;
 
 /**
- * A logger class that strives to make it as easy as possible for
+ * An empty-implementation of the {@link POILogger}.
- * developers to write log calls, while simultaneously making those
+ *
- * calls as cheap as possible by performing lazy evaluation of the log
+ * This can be used to not log anything, however the suggested approach
- * message.<p>
+ * in production systems is to use the {@link CommonsLogger} and configure
+ * proper log-handling via Apache Commons Logging.
  */
 @Internal
 public class NullLogger implements POILogger {
@@ -66,7 +67,7 @@ public class NullLogger implements POILogger {
         // do nothing
     }
 
-    
+
     /**
      * Check if a logger is enabled to log at the specified level
      *

src/java/org/apache/poi/util/POILogger.java

@@ -22,6 +22,19 @@ package org.apache.poi.util;
  * developers to write log calls, while simultaneously making those
  * calls as cheap as possible by performing lazy evaluation of the log
  * message.
+ *
+ * A logger can be selected via system properties, e.g.
+ * <code>
+ *     -Dorg.apache.poi.util.POILogger=org.apache.poi.util.SystemOutLogger
+ * </code>
+ *
+ * The following Logger-implementations are provided:
+ *
+ * <ul>
+ *     <li>NullLogger</li>
+ *     <li>CommonsLogger</li>
+ *     <li>SystemOutLogger</li>
+ * </ul>
  */
 @Internal
 public interface POILogger {
@@ -62,7 +75,7 @@ public interface POILogger {
      * Check if a logger is enabled to log at the specified level
      * This allows code to avoid building strings or evaluating functions in
      * the arguments to log.
-     * 
+     *
      * An example:
      * <code><pre>
      * if (logger.check(POILogger.INFO)) {
@@ -92,11 +105,11 @@ public interface POILogger {
                 sb.append(objs[i]);
             }
         }
-        
+
         String msg = sb.toString();
         // log forging escape
         msg = msg.replaceAll("[\r\n]+", " ");
-        
+
         if (lastEx == null) {
             _log(level, msg);
         } else {

src/java/org/apache/poi/util/SystemOutLogger.java

@@ -14,16 +14,14 @@
    See the License for the specific language governing permissions and
    limitations under the License.
 ==================================================================== */
-
 package org.apache.poi.util;
 
-
-
 /**
- * A logger class that strives to make it as easy as possible for
+ * An implementation of the {@link POILogger} which uses System.out.println.
- * developers to write log calls, while simultaneously making those
+ *
- * calls as cheap as possible by performing lazy evaluation of the log
+ * This can be used to provide simply output from applications, however the
- * message.
+ * suggested approach in production systems is to use the {@link CommonsLogger}
+ * and configure proper log-handling via Apache Commons Logging.
  */
 public class SystemOutLogger implements POILogger {
     /**

src/ooxml/java/org/apache/poi/openxml4j/opc/PackagePart.java

@@ -466,7 +466,7 @@ public abstract class PackagePart implements RelationshipSource, Comparable<Pack
    /**
     * Get the PackagePart that is the target of a relationship.
     *
-    * @param rel A relationship from this part to another one 
+    * @param rel A relationship from this part to another one
     * @return The target part of the relationship
     * @throws InvalidFormatException
     *             If the specified URI is not valid.
@@ -698,7 +698,8 @@ public abstract class PackagePart implements RelationshipSource, Comparable<Pack
      *
      * @param zos
      *            Output stream to save this part.
-     * @return boolean flag that shows if the save succeeded
+     * @return true if the content has been successfully stored, false otherwise.
+     *         More information about errors may be logged via {@link org.apache.poi.util.POILogger}
      * @throws OpenXML4JException
      *             If any exception occur.
      */
@@ -709,8 +710,8 @@ public abstract class PackagePart implements RelationshipSource, Comparable<Pack
      *
      * @param ios
      *            The input stream of the content to load.
-     * @return <b>true</b> if the content has been successfully loaded, else
+     * @return true if the content has been successfully loaded, false otherwise.
-     *         <b>false</b>.
+     *         More information about errors may be logged via {@link org.apache.poi.util.POILogger}
      * @throws InvalidFormatException
      *             Throws if the content format is invalid.
      */

src/ooxml/java/org/apache/poi/openxml4j/opc/ZipPackage.java

@@ -539,8 +539,9 @@ public final class ZipPackage extends OPCPackage {
 
 				final PartMarshaller pm = (marshaller != null) ? marshaller : defaultPartMarshaller;
                 if (!pm.marshall(part, zos)) {
-                    String errMsg = "The part " + ppn.getURI() + " failed to be saved in the stream with marshaller ";
+                    String errMsg = "The part " + ppn.getURI() + " failed to be saved in the stream with marshaller " + pm +
-                    throw new OpenXML4JException(errMsg + pm);
+                            ". Enable logging via POILogger for more details.";
+                    throw new OpenXML4JException(errMsg);
                 }
 			}
 

src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/DefaultMarshaller.java

@@ -33,8 +33,12 @@ import org.apache.poi.openxml4j.opc.internal.PartMarshaller;
 public final class DefaultMarshaller implements PartMarshaller {
 
 	/**
-	 * Save part in the output stream by using the save() method of the part.
+	 * Save the given part in the output stream by using the save() method of the part.
 	 *
+	 * @param part The {@link PackagePart} to store.
+	 * @param out Output stream to save this part.
+	 * @return true if the content has been successfully stored, false otherwise.
+	 *         More information about errors may be logged via {@link org.apache.poi.util.POILogger}
 	 * @throws OpenXML4JException
 	 *             If any error occur.
 	 */

src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/ZipPartMarshaller.java

@@ -50,10 +50,15 @@ public final class ZipPartMarshaller implements PartMarshaller {
 	private final static POILogger logger = POILogFactory.getLogger(ZipPartMarshaller.class);
 
 	/**
-	 * Save the specified part.
+	 * Save the specified part to the given stream.
 	 *
+	 * @param part The {@link PackagePart} to save
+	 * @param os The stream to write the data to
+	 * @return true if saving was successful or there was nothing to save,
+	 * 		false if an error occurred.
+	 * 		In case of errors, logging via the {@link POILogger} is used to provide more information.
 	 * @throws OpenXML4JException
-	 *             Throws if an internal exception is thrown.
+	 *      Throws if the stream cannot be written to or an internal exception is thrown.
 	 */
 	@Override
 	public boolean marshall(PackagePart part, OutputStream os)
@@ -61,10 +66,10 @@ public final class ZipPartMarshaller implements PartMarshaller {
 		if (!(os instanceof ZipArchiveOutputStream)) {
 			logger.log(POILogger.ERROR,"Unexpected class " + os.getClass().getName());
 			throw new OpenXML4JException("ZipOutputStream expected !");
-			// Normally should happen only in developement phase, so just throw
+			// Normally should happen only in development phase, so just throw
 			// exception
 		}
-		
+
 		// check if there is anything to save for some parts. We don't do this for all parts as some code
 		// might depend on empty parts being saved, e.g. some unit tests verify this currently.
 		if(part.getSize() == 0 && part.getPartName().getName().equals(XSSFRelation.SHARED_STRINGS.getDefaultFileName())) {
@@ -98,8 +103,8 @@ public final class ZipPartMarshaller implements PartMarshaller {
 
 			marshallRelationshipPart(part.getRelationships(),
 					relationshipPartName, zos);
-
 		}
+
 		return true;
 	}
 
@@ -113,6 +118,9 @@ public final class ZipPartMarshaller implements PartMarshaller {
 	 * @param zos
 	 *            Zip output stream in which to save the XML content of the
 	 *            relationships serialization.
+	 * @return true if saving was successful,
+	 * 		false if an error occurred.
+	 * 		In case of errors, logging via the {@link POILogger} is used to provide more information.
 	 */
 	public static boolean marshallRelationshipPart(
 			PackageRelationshipCollection rels, PackagePartName relPartName,

src/testcases/org/apache/poi/util/DummyPOILogger.java

@@ -20,7 +20,7 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * POILogger which logs into an ArrayList, so that 
+ * {@link POILogger} which logs into an ArrayList so that
  *  tests can see what got logged
  */
 @Internal
@@ -30,7 +30,7 @@ public class DummyPOILogger implements POILogger {
 	public void reset() {
 		logged = new ArrayList<>();
 	}
-	
+
     @Override
 	public boolean check(int level) {
 		return true;