-
/* ====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
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
{
@Override
public void initialize(final String cat) {
this.log = _creator.getInstance(cat);
- }
-
+ }
+
/**
* Log a message
*
break;
}
}
-
+
/**
* Log a message
*
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 {
// do nothing
}
-
+
/**
* Check if a logger is enabled to log at the specified level
*
* 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 {
* 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)) {
sb.append(objs[i]);
}
}
-
+
String msg = sb.toString();
// log forging escape
msg = msg.replaceAll("[\r\n]+", " ");
-
+
if (lastEx == null) {
_log(level, msg);
} else {
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 {
/**
/**
* 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.
*
* @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.
*/
*
* @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.
*/
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);
}
}
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.
*/
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)
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())) {
marshallRelationshipPart(part.getRelationships(),
relationshipPartName, zos);
-
}
+
return true;
}
* @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,
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
public void reset() {
logged = new ArrayList<>();
}
-
+
@Override
public boolean check(int level) {
return true;
projects / poi.git / commitdiff