Author: centic
Date: Sun Mar 8 08:28:11 2020
New Revision: 1874965
URL: http://svn.apache.org/viewvc?rev=1874965&view=rev
Log:
Update JavaDoc for logging and marshalling
Modified:
poi/trunk/src/java/org/apache/poi/util/CommonsLogger.java
poi/trunk/src/java/org/apache/poi/util/NullLogger.java
poi/trunk/src/java/org/apache/poi/util/POILogger.java
poi/trunk/src/java/org/apache/poi/util/SystemOutLogger.java
poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/PackagePart.java
poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/ZipPackage.java
poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/DefaultMarshaller.java
poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/ZipPartMarshaller.java
poi/trunk/src/testcases/org/apache/poi/util/DummyPOILogger.java
Modified: poi/trunk/src/java/org/apache/poi/util/CommonsLogger.java
URL:
http://svn.apache.org/viewvc/poi/trunk/src/java/org/apache/poi/util/CommonsLogger.java?rev=1874965&r1=1874964&r2=1874965&view=diff
==============================================================================
--- poi/trunk/src/java/org/apache/poi/util/CommonsLogger.java (original)
+++ poi/trunk/src/java/org/apache/poi/util/CommonsLogger.java Sun Mar 8
08:28:11 2020
@@ -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.<p>
+ * 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 PO
@Override
public void initialize(final String cat) {
this.log = _creator.getInstance(cat);
- }
-
+ }
+
/**
* Log a message
*
@@ -81,7 +78,7 @@ public class CommonsLogger implements PO
break;
}
}
-
+
/**
* Log a message
*
Modified: poi/trunk/src/java/org/apache/poi/util/NullLogger.java
URL:
http://svn.apache.org/viewvc/poi/trunk/src/java/org/apache/poi/util/NullLogger.java?rev=1874965&r1=1874964&r2=1874965&view=diff
==============================================================================
--- poi/trunk/src/java/org/apache/poi/util/NullLogger.java (original)
+++ poi/trunk/src/java/org/apache/poi/util/NullLogger.java Sun Mar 8 08:28:11
2020
@@ -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.<p>
+ * 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 POILo
// do nothing
}
-
+
/**
* Check if a logger is enabled to log at the specified level
*
Modified: poi/trunk/src/java/org/apache/poi/util/POILogger.java
URL:
http://svn.apache.org/viewvc/poi/trunk/src/java/org/apache/poi/util/POILogger.java?rev=1874965&r1=1874964&r2=1874965&view=diff
==============================================================================
--- poi/trunk/src/java/org/apache/poi/util/POILogger.java (original)
+++ poi/trunk/src/java/org/apache/poi/util/POILogger.java Sun Mar 8 08:28:11
2020
@@ -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 {
Modified: poi/trunk/src/java/org/apache/poi/util/SystemOutLogger.java
URL:
http://svn.apache.org/viewvc/poi/trunk/src/java/org/apache/poi/util/SystemOutLogger.java?rev=1874965&r1=1874964&r2=1874965&view=diff
==============================================================================
--- poi/trunk/src/java/org/apache/poi/util/SystemOutLogger.java (original)
+++ poi/trunk/src/java/org/apache/poi/util/SystemOutLogger.java Sun Mar 8
08:28:11 2020
@@ -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 {
/**
Modified: poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/PackagePart.java
URL:
http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/PackagePart.java?rev=1874965&r1=1874964&r2=1874965&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/PackagePart.java
(original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/PackagePart.java Sun
Mar 8 08:28:11 2020
@@ -466,7 +466,7 @@ public abstract class PackagePart implem
/**
* 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 implem
*
* @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 implem
*
* @param ios
* The input stream of the content to load.
- * @return <b>true</b> if the content has been successfully loaded, else
- * <b>false</b>.
+ * @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.
*/
Modified: poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/ZipPackage.java
URL:
http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/ZipPackage.java?rev=1874965&r1=1874964&r2=1874965&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/ZipPackage.java
(original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/ZipPackage.java Sun
Mar 8 08:28:11 2020
@@ -539,8 +539,9 @@ public final class ZipPackage extends OP
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);
}
}
Modified:
poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/DefaultMarshaller.java
URL:
http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/DefaultMarshaller.java?rev=1874965&r1=1874964&r2=1874965&view=diff
==============================================================================
---
poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/DefaultMarshaller.java
(original)
+++
poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/DefaultMarshaller.java
Sun Mar 8 08:28:11 2020
@@ -33,8 +33,12 @@ import org.apache.poi.openxml4j.opc.inte
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.
*/
Modified:
poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/ZipPartMarshaller.java
URL:
http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/ZipPartMarshaller.java?rev=1874965&r1=1874964&r2=1874965&view=diff
==============================================================================
---
poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/ZipPartMarshaller.java
(original)
+++
poi/trunk/src/ooxml/java/org/apache/poi/openxml4j/opc/internal/marshallers/ZipPartMarshaller.java
Sun Mar 8 08:28:11 2020
@@ -50,10 +50,15 @@ public final class ZipPartMarshaller imp
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 imp
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 imp
marshallRelationshipPart(part.getRelationships(),
relationshipPartName, zos);
-
}
+
return true;
}
@@ -113,6 +118,9 @@ public final class ZipPartMarshaller imp
* @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,
Modified: poi/trunk/src/testcases/org/apache/poi/util/DummyPOILogger.java
URL:
http://svn.apache.org/viewvc/poi/trunk/src/testcases/org/apache/poi/util/DummyPOILogger.java?rev=1874965&r1=1874964&r2=1874965&view=diff
==============================================================================
--- poi/trunk/src/testcases/org/apache/poi/util/DummyPOILogger.java (original)
+++ poi/trunk/src/testcases/org/apache/poi/util/DummyPOILogger.java Sun Mar 8
08:28:11 2020
@@ -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 P
public void reset() {
logged = new ArrayList<>();
}
-
+
@Override
public boolean check(int level) {
return true;
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
