From: Andreas Beeker Date: Sun, 12 Jun 2016 19:54:35 +0000 (+0000) Subject: javadocs fixes X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=1ace43ba9f33c30f90c7f20efbbc66cbd4f5959b;p=poi.git javadocs fixes git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1748042 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/src/ooxml/java/org/apache/poi/POIXMLDocument.java b/src/ooxml/java/org/apache/poi/POIXMLDocument.java index 1d73329a4e..7fa934c03c 100644 --- a/src/ooxml/java/org/apache/poi/POIXMLDocument.java +++ b/src/ooxml/java/org/apache/poi/POIXMLDocument.java @@ -16,15 +16,30 @@ ==================================================================== */ package org.apache.poi; +import java.io.Closeable; +import java.io.File; +import java.io.IOException; +import java.io.InputStream; +import java.io.OutputStream; +import java.util.HashMap; +import java.util.HashSet; +import java.util.List; +import java.util.Map; +import java.util.Set; + import org.apache.poi.openxml4j.exceptions.InvalidFormatException; import org.apache.poi.openxml4j.exceptions.OpenXML4JException; -import org.apache.poi.openxml4j.opc.*; +import org.apache.poi.openxml4j.opc.OPCPackage; +import org.apache.poi.openxml4j.opc.PackageAccess; +import org.apache.poi.openxml4j.opc.PackagePart; +import org.apache.poi.openxml4j.opc.PackageRelationship; +import org.apache.poi.openxml4j.opc.PackageRelationshipCollection; import org.apache.poi.poifs.filesystem.DocumentFactoryHelper; import org.apache.xmlbeans.impl.common.SystemCache; -import java.io.*; -import java.util.*; - +/** + * This holds the common functionality for all POI OOXML Document classes. + */ public abstract class POIXMLDocument extends POIXMLDocumentPart implements Closeable { public static final String DOCUMENT_CREATOR = "Apache POI"; @@ -52,8 +67,8 @@ public abstract class POIXMLDocument extends POIXMLDocumentPart implements Close init(pkg); } - private void init(OPCPackage pkg) { - this.pkg = pkg; + private void init(OPCPackage p) { + this.pkg = p; // Workaround for XMLBEANS-512 - ensure that when we parse // the file, we start with a fresh XML Parser each time, @@ -62,18 +77,26 @@ public abstract class POIXMLDocument extends POIXMLDocumentPart implements Close } /** - * Wrapper to open a package, returning an IOException - * in the event of a problem. - * Works around shortcomings in java's this() constructor calls + * Wrapper to open a package, which works around shortcomings in java's this() constructor calls + * + * @param path the path to the document + * @return the new OPCPackage + * + * @exception IOException if there was a problem opening the document */ public static OPCPackage openPackage(String path) throws IOException { try { return OPCPackage.open(path); } catch (InvalidFormatException e) { - throw new IOException(e.toString()); + throw new IOException(e.toString(), e); } } + /** + * Get the assigned OPCPackage + * + * @return the assigned OPCPackage + */ public OPCPackage getPackage() { return this.pkg; } @@ -83,9 +106,19 @@ public abstract class POIXMLDocument extends POIXMLDocumentPart implements Close } /** - * Retrieves all the PackageParts which are defined as - * relationships of the base document with the - * specified content type. + * Retrieves all the PackageParts which are defined as relationships of the base document with the + * specified content type. + * + * @param contentType the content type + * + * @return all the base document PackageParts which match the content type + * + * @throws InvalidFormatException when the relationships or the parts contain errors + * + * @see org.apache.poi.xssf.usermodel.XSSFRelation + * @see org.apache.poi.xslf.usermodel.XSLFRelation + * @see org.apache.poi.xwpf.usermodel.XWPFRelation + * @see org.apache.poi.xdgf.usermodel.XDGFRelation */ protected PackagePart[] getRelatedByType(String contentType) throws InvalidFormatException { PackageRelationshipCollection partsC = @@ -107,10 +140,15 @@ public abstract class POIXMLDocument extends POIXMLDocumentPart implements Close * If your InputStream does not support mark / reset, * then wrap it in a PushBackInputStream, then be * sure to always use that, and not the original! + * * @param inp An InputStream which supports either mark/reset, or is a PushbackInputStream + * @return true, if the InputStream is an ooxml document + * + * @throws IOException if the InputStream can't be read * * @deprecated use the method from DocumentFactoryHelper, deprecated as of 3.15-beta1, therefore eligible for removal in 3.17 */ + @Deprecated public static boolean hasOOXMLHeader(InputStream inp) throws IOException { return DocumentFactoryHelper.hasOOXMLHeader(inp); } @@ -118,6 +156,8 @@ public abstract class POIXMLDocument extends POIXMLDocumentPart implements Close /** * Get the document properties. This gives you access to the * core ooxml properties, and the extended ooxml properties. + * + * @return the document properties */ public POIXMLProperties getProperties() { if(properties == null) { @@ -132,6 +172,10 @@ public abstract class POIXMLDocument extends POIXMLDocumentPart implements Close /** * Get the document's embedded files. + * + * @return the document's embedded files + * + * @throws OpenXML4JException if the embedded parts can't be determined */ public abstract List getAllEmbedds() throws OpenXML4JException; @@ -149,7 +193,10 @@ public abstract class POIXMLDocument extends POIXMLDocumentPart implements Close /** * Closes the underlying {@link OPCPackage} from which this * document was read, if there is one + * + * @throws IOException for writable packages, if an IO exception occur during the saving process. */ + @Override public void close() throws IOException { if (pkg != null) { if (pkg.getPackageAccess() == PackageAccess.READ) { @@ -172,6 +219,7 @@ public abstract class POIXMLDocument extends POIXMLDocumentPart implements Close * * @exception IOException if anything can't be written. */ + @SuppressWarnings("resource") public final void write(OutputStream stream) throws IOException { //force all children to commit their changes into the underlying OOXML Package // TODO Shouldn't they be committing to the new one instead? @@ -182,10 +230,10 @@ public abstract class POIXMLDocument extends POIXMLDocumentPart implements Close //save extended and custom properties getProperties().commit(); - OPCPackage pkg = getPackage(); - if(pkg == null) { + OPCPackage p = getPackage(); + if(p == null) { throw new IOException("Cannot write data, document seems to have been closed already"); } - pkg.save(stream); + p.save(stream); } } diff --git a/src/ooxml/java/org/apache/poi/POIXMLDocumentPart.java b/src/ooxml/java/org/apache/poi/POIXMLDocumentPart.java index 623385072b..d142b4a797 100644 --- a/src/ooxml/java/org/apache/poi/POIXMLDocumentPart.java +++ b/src/ooxml/java/org/apache/poi/POIXMLDocumentPart.java @@ -46,8 +46,6 @@ import org.apache.poi.util.POILogger; *

* Each POIXMLDocumentPart keeps a reference to the underlying a {@link org.apache.poi.openxml4j.opc.PackagePart}. *

- * - * @author Yegor Kozlov */ public class POIXMLDocumentPart { private static final POILogger logger = POILogFactory.getLogger(POIXMLDocumentPart.class); @@ -80,6 +78,8 @@ public class POIXMLDocumentPart { } /** + * @param the cast of the caller to a document sub class + * * @return the child document part */ @SuppressWarnings("unchecked") @@ -110,6 +110,8 @@ public class POIXMLDocumentPart { /** * Construct POIXMLDocumentPart representing a "core document" package part. + * + * @param pkg the OPCPackage containing this document */ public POIXMLDocumentPart(OPCPackage pkg) { this(pkg, PackageRelationshipTypes.CORE_DOCUMENT); @@ -117,6 +119,9 @@ public class POIXMLDocumentPart { /** * Construct POIXMLDocumentPart representing a custom "core document" package part. + * + * @param pkg the OPCPackage containing this document + * @param coreDocumentRel the relation type of this document */ public POIXMLDocumentPart(OPCPackage pkg, String coreDocumentRel) { this(getPartFromOPCPackage(pkg, coreDocumentRel)); @@ -194,6 +199,11 @@ public class POIXMLDocumentPart { * When you open something like a theme, call this to * re-base the XML Document onto the core child of the * current core document + * + * @param pkg the package to be rebased + * + * @throws InvalidFormatException if there was an error in the core document relation + * @throws IllegalStateException if there are more than one core document relations */ protected final void rebase(OPCPackage pkg) throws InvalidFormatException { PackageRelationshipCollection cores = @@ -307,12 +317,13 @@ public class POIXMLDocumentPart { /** * Add a new child POIXMLDocumentPart * + * @param id the id of an existing child to replace * @param part the child to add * * @deprecated in POI 3.14, scheduled for removal in POI 3.16 */ @Deprecated - public final void addRelation(String id,POIXMLDocumentPart part) { + public final void addRelation(String id, POIXMLDocumentPart part) { PackageRelationship pr = part.getPackagePart().getRelationship(id); addRelation(pr, part); } @@ -323,6 +334,8 @@ public class POIXMLDocumentPart { * @param relId the preferred relation id, when null the next free relation id will be used * @param relationshipType the package relationship type * @param part the child to add + * + * @return the new RelationPart * * @since 3.14-Beta1 */ @@ -376,6 +389,8 @@ public class POIXMLDocumentPart { /** * Remove the relation to the specified part in this package and remove the * part, if it is no longer needed. + * + * @param part the part which relation is to be removed from this document */ protected final void removeRelation(POIXMLDocumentPart part){ removeRelation(part,true); diff --git a/src/ooxml/java/org/apache/poi/POIXMLFactory.java b/src/ooxml/java/org/apache/poi/POIXMLFactory.java index f5d8c790f4..c0457e43fd 100644 --- a/src/ooxml/java/org/apache/poi/POIXMLFactory.java +++ b/src/ooxml/java/org/apache/poi/POIXMLFactory.java @@ -16,10 +16,8 @@ ==================================================================== */ package org.apache.poi; -import java.lang.reflect.Constructor; import java.lang.reflect.InvocationTargetException; -import org.apache.poi.POIXMLDocumentPart.RelationPart; import org.apache.poi.openxml4j.exceptions.InvalidFormatException; import org.apache.poi.openxml4j.opc.PackagePart; import org.apache.poi.openxml4j.opc.PackageRelationship; diff --git a/src/ooxml/java/org/apache/poi/POIXMLPropertiesTextExtractor.java b/src/ooxml/java/org/apache/poi/POIXMLPropertiesTextExtractor.java index 681a71208a..1ed72abaa0 100644 --- a/src/ooxml/java/org/apache/poi/POIXMLPropertiesTextExtractor.java +++ b/src/ooxml/java/org/apache/poi/POIXMLPropertiesTextExtractor.java @@ -149,7 +149,7 @@ public class POIXMLPropertiesTextExtractor extends POIXMLTextExtractor { * Returns the custom document properties, if * there are any */ - @SuppressWarnings({ "deprecation", "resource" }) + @SuppressWarnings({ "resource" }) public String getCustomPropertiesText() { POIXMLDocument document = getDocument(); if(document == null) { // event based extractor does not have a document @@ -253,7 +253,8 @@ public class POIXMLPropertiesTextExtractor extends POIXMLTextExtractor { return text.toString(); } - public String getText() { + @Override + public String getText() { try { return getCorePropertiesText() + @@ -264,7 +265,8 @@ public class POIXMLPropertiesTextExtractor extends POIXMLTextExtractor { } } - public POIXMLPropertiesTextExtractor getMetadataTextExtractor() { + @Override + public POIXMLPropertiesTextExtractor getMetadataTextExtractor() { throw new IllegalStateException("You already have the Metadata Text Extractor, not recursing!"); } } diff --git a/src/ooxml/java/org/apache/poi/POIXMLTextExtractor.java b/src/ooxml/java/org/apache/poi/POIXMLTextExtractor.java index a0f4359287..db771ce7cf 100644 --- a/src/ooxml/java/org/apache/poi/POIXMLTextExtractor.java +++ b/src/ooxml/java/org/apache/poi/POIXMLTextExtractor.java @@ -73,7 +73,8 @@ public abstract class POIXMLTextExtractor extends POITextExtractor { * Returns an OOXML properties text extractor for the * document properties metadata, such as title and author. */ - public POIXMLPropertiesTextExtractor getMetadataTextExtractor() { + @Override + public POIXMLPropertiesTextExtractor getMetadataTextExtractor() { return new POIXMLPropertiesTextExtractor(_document); } @@ -81,7 +82,8 @@ public abstract class POIXMLTextExtractor extends POITextExtractor { public void close() throws IOException { // e.g. XSSFEventBaseExcelExtractor passes a null-document if(_document != null) { - OPCPackage pkg = _document.getPackage(); + @SuppressWarnings("resource") + OPCPackage pkg = _document.getPackage(); if(pkg != null) { // revert the package to not re-write the file, which is very likely not wanted for a TextExtractor! pkg.revert();