mirror of https://github.com/apache/poi.git
Update JavaDoc for logging and marshalling
git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1874965 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
parent
da4c9cc706
commit
af4751b260
|
@ -1,4 +1,3 @@
|
||||||
|
|
||||||
/* ====================================================================
|
/* ====================================================================
|
||||||
Licensed to the Apache Software Foundation (ASF) under one or more
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
||||||
contributor license agreements. See the NOTICE file distributed with
|
contributor license agreements. See the NOTICE file distributed with
|
||||||
|
@ -15,18 +14,16 @@
|
||||||
See the License for the specific language governing permissions and
|
See the License for the specific language governing permissions and
|
||||||
limitations under the License.
|
limitations under the License.
|
||||||
==================================================================== */
|
==================================================================== */
|
||||||
|
|
||||||
|
|
||||||
package org.apache.poi.util;
|
package org.apache.poi.util;
|
||||||
|
|
||||||
import org.apache.commons.logging.Log;
|
import org.apache.commons.logging.Log;
|
||||||
import org.apache.commons.logging.LogFactory;
|
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
|
public class CommonsLogger implements POILogger
|
||||||
{
|
{
|
||||||
|
|
|
@ -18,10 +18,11 @@
|
||||||
package org.apache.poi.util;
|
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
|
@Internal
|
||||||
public class NullLogger implements POILogger {
|
public class NullLogger implements POILogger {
|
||||||
|
|
|
@ -22,6 +22,19 @@ package org.apache.poi.util;
|
||||||
* developers to write log calls, while simultaneously making those
|
* developers to write log calls, while simultaneously making those
|
||||||
* calls as cheap as possible by performing lazy evaluation of the log
|
* calls as cheap as possible by performing lazy evaluation of the log
|
||||||
* message.
|
* 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
|
@Internal
|
||||||
public interface POILogger {
|
public interface POILogger {
|
||||||
|
|
|
@ -14,16 +14,14 @@
|
||||||
See the License for the specific language governing permissions and
|
See the License for the specific language governing permissions and
|
||||||
limitations under the License.
|
limitations under the License.
|
||||||
==================================================================== */
|
==================================================================== */
|
||||||
|
|
||||||
package org.apache.poi.util;
|
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 {
|
public class SystemOutLogger implements POILogger {
|
||||||
/**
|
/**
|
||||||
|
|
|
@ -698,7 +698,8 @@ public abstract class PackagePart implements RelationshipSource, Comparable<Pack
|
||||||
*
|
*
|
||||||
* @param zos
|
* @param zos
|
||||||
* Output stream to save this part.
|
* 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
|
* @throws OpenXML4JException
|
||||||
* If any exception occur.
|
* If any exception occur.
|
||||||
*/
|
*/
|
||||||
|
@ -709,8 +710,8 @@ public abstract class PackagePart implements RelationshipSource, Comparable<Pack
|
||||||
*
|
*
|
||||||
* @param ios
|
* @param ios
|
||||||
* The input stream of the content to load.
|
* 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 InvalidFormatException
|
||||||
* Throws if the content format is invalid.
|
* Throws if the content format is invalid.
|
||||||
*/
|
*/
|
||||||
|
|
|
@ -539,8 +539,9 @@ public final class ZipPackage extends OPCPackage {
|
||||||
|
|
||||||
final PartMarshaller pm = (marshaller != null) ? marshaller : defaultPartMarshaller;
|
final PartMarshaller pm = (marshaller != null) ? marshaller : defaultPartMarshaller;
|
||||||
if (!pm.marshall(part, zos)) {
|
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);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
|
@ -33,8 +33,12 @@ import org.apache.poi.openxml4j.opc.internal.PartMarshaller;
|
||||||
public final class DefaultMarshaller implements 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
|
* @throws OpenXML4JException
|
||||||
* If any error occur.
|
* If any error occur.
|
||||||
*/
|
*/
|
||||||
|
|
|
@ -50,10 +50,15 @@ public final class ZipPartMarshaller implements PartMarshaller {
|
||||||
private final static POILogger logger = POILogFactory.getLogger(ZipPartMarshaller.class);
|
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 OpenXML4JException
|
||||||
* Throws if an internal exception is thrown.
|
* Throws if the stream cannot be written to or an internal exception is thrown.
|
||||||
*/
|
*/
|
||||||
@Override
|
@Override
|
||||||
public boolean marshall(PackagePart part, OutputStream os)
|
public boolean marshall(PackagePart part, OutputStream os)
|
||||||
|
@ -61,7 +66,7 @@ public final class ZipPartMarshaller implements PartMarshaller {
|
||||||
if (!(os instanceof ZipArchiveOutputStream)) {
|
if (!(os instanceof ZipArchiveOutputStream)) {
|
||||||
logger.log(POILogger.ERROR,"Unexpected class " + os.getClass().getName());
|
logger.log(POILogger.ERROR,"Unexpected class " + os.getClass().getName());
|
||||||
throw new OpenXML4JException("ZipOutputStream expected !");
|
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
|
// exception
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -98,8 +103,8 @@ public final class ZipPartMarshaller implements PartMarshaller {
|
||||||
|
|
||||||
marshallRelationshipPart(part.getRelationships(),
|
marshallRelationshipPart(part.getRelationships(),
|
||||||
relationshipPartName, zos);
|
relationshipPartName, zos);
|
||||||
|
|
||||||
}
|
}
|
||||||
|
|
||||||
return true;
|
return true;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -113,6 +118,9 @@ public final class ZipPartMarshaller implements PartMarshaller {
|
||||||
* @param zos
|
* @param zos
|
||||||
* Zip output stream in which to save the XML content of the
|
* Zip output stream in which to save the XML content of the
|
||||||
* relationships serialization.
|
* 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(
|
public static boolean marshallRelationshipPart(
|
||||||
PackageRelationshipCollection rels, PackagePartName relPartName,
|
PackageRelationshipCollection rels, PackagePartName relPartName,
|
||||||
|
|
|
@ -20,7 +20,7 @@ import java.util.ArrayList;
|
||||||
import java.util.List;
|
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
|
* tests can see what got logged
|
||||||
*/
|
*/
|
||||||
@Internal
|
@Internal
|
||||||
|
|
Loading…
Reference in New Issue