From af4751b2604105f0add7e6db551a3ca5e18b9197 Mon Sep 17 00:00:00 2001 From: Dominik Stadler Date: Sun, 8 Mar 2020 08:28:11 +0000 Subject: [PATCH] Update JavaDoc for logging and marshalling git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1874965 13f79535-47bb-0310-9956-ffa450edef68 --- .../org/apache/poi/util/CommonsLogger.java | 17 +++++++---------- src/java/org/apache/poi/util/NullLogger.java | 11 ++++++----- src/java/org/apache/poi/util/POILogger.java | 19 ++++++++++++++++--- .../org/apache/poi/util/SystemOutLogger.java | 12 +++++------- .../apache/poi/openxml4j/opc/PackagePart.java | 9 +++++---- .../apache/poi/openxml4j/opc/ZipPackage.java | 5 +++-- .../marshallers/DefaultMarshaller.java | 6 +++++- .../marshallers/ZipPartMarshaller.java | 18 +++++++++++++----- .../org/apache/poi/util/DummyPOILogger.java | 4 ++-- 9 files changed, 62 insertions(+), 39 deletions(-) diff --git a/src/java/org/apache/poi/util/CommonsLogger.java b/src/java/org/apache/poi/util/CommonsLogger.java index c5a4374fc8..cdc4f92804 100644 --- a/src/java/org/apache/poi/util/CommonsLogger.java +++ b/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 - * developers to write log calls, while simultaneously making those - * calls as cheap as possible by performing lazy evaluation of the log - * message.

+ * An implementation of the {@link POILogger} using the + * Apache Commons Logging framework. Which itself can be configured to + * send log to various different log frameworks and even allows to create + * 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 * diff --git a/src/java/org/apache/poi/util/NullLogger.java b/src/java/org/apache/poi/util/NullLogger.java index e4fab3903b..8a9daeaa0b 100644 --- a/src/java/org/apache/poi/util/NullLogger.java +++ b/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 - * developers to write log calls, while simultaneously making those - * calls as cheap as possible by performing lazy evaluation of the log - * message.

+ * An empty-implementation of the {@link POILogger}. + * + * This can be used to not log anything, however the suggested approach + * 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 * diff --git a/src/java/org/apache/poi/util/POILogger.java b/src/java/org/apache/poi/util/POILogger.java index 627f83743e..fa52baabd5 100644 --- a/src/java/org/apache/poi/util/POILogger.java +++ b/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. + * + * -Dorg.apache.poi.util.POILogger=org.apache.poi.util.SystemOutLogger + * + * + * The following Logger-implementations are provided: + * + *

*/ @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: * 
      * 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 {
diff --git a/src/java/org/apache/poi/util/SystemOutLogger.java b/src/java/org/apache/poi/util/SystemOutLogger.java
index 8eba4b0063..3567c40808 100644
--- a/src/java/org/apache/poi/util/SystemOutLogger.java
+++ b/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
- * developers to write log calls, while simultaneously making those
- * calls as cheap as possible by performing lazy evaluation of the log
- * message.
+ * An implementation of the {@link POILogger} which uses System.out.println.
+ *
+ * This can be used to provide simply output from applications, however the
+ * 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 {
     /**
diff --git a/src/ooxml/java/org/apache/poi/openxml4j/opc/PackagePart.java b/src/ooxml/java/org/apache/poi/openxml4j/opc/PackagePart.java
index 1b04417ee2..0fdacdd214 100644
--- a/src/ooxml/java/org/apache/poi/openxml4j/opc/PackagePart.java
+++ b/src/ooxml/java/org/apache/poi/openxml4j/opc/PackagePart.java
@@ -466,7 +466,7 @@ public abstract class PackagePart implements RelationshipSource, Comparabletrue if the content has been successfully loaded, else
-     *         false.
+     * @return true if the content has been successfully loaded, false otherwise.
+     *         More information about errors may be logged via {@link org.apache.poi.util.POILogger}
      * @throws InvalidFormatException
      *             Throws if the content format is invalid.
      */
diff --git a/src/ooxml/java/org/apache/poi/openxml4j/opc/ZipPackage.java b/src/ooxml/java/org/apache/poi/openxml4j/opc/ZipPackage.java
index a1a8910456..5cd3a14598 100644
--- a/src/ooxml/java/org/apache/poi/openxml4j/opc/ZipPackage.java
+++ b/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 ";
-                    throw new OpenXML4JException(errMsg + pm);
+                    String errMsg = "The part " + ppn.getURI() + " failed to be saved in the stream with marshaller " + pm +
+                            ". Enable logging via POILogger for more details.";
+                    throw new OpenXML4JException(errMsg);
                 }
 			}
 
diff --git a/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/DefaultMarshaller.java b/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/DefaultMarshaller.java
index 8cd2f7d245..16a5917ad3 100644
--- a/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/DefaultMarshaller.java
+++ b/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.
 	 */
diff --git a/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/ZipPartMarshaller.java b/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/ZipPartMarshaller.java
index a1ba382ff8..7ff1c74abd 100644
--- a/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/ZipPartMarshaller.java
+++ b/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,
diff --git a/src/testcases/org/apache/poi/util/DummyPOILogger.java b/src/testcases/org/apache/poi/util/DummyPOILogger.java
index e220cc0a0c..bb6526be2d 100644
--- a/src/testcases/org/apache/poi/util/DummyPOILogger.java
+++ b/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;