javadocs fixes

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1748042 13f79535-47bb-0310-9956-ffa450edef68

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) {
+    private void init(OPCPackage p) {
-        this.pkg = pkg;
+        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
+     * Wrapper to open a package, which works around shortcomings in java's this() constructor calls
-     *  in the event of a problem.
+     * 
-     * 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
+     * Retrieves all the PackageParts which are defined as relationships of the base document with the
-     *  relationships of the base document with the
+     * specified content type.
-     *  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<PackagePart> 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();
+        OPCPackage p = getPackage();
-        if(pkg == null) {
+        if(p == null) {
             throw new IOException("Cannot write data, document seems to have been closed already");
         }
-        pkg.save(stream);
+        p.save(stream);
     }
 }

src/ooxml/java/org/apache/poi/POIXMLDocumentPart.java

@@ -46,8 +46,6 @@ import org.apache.poi.util.POILogger;
  * <p>
  * Each POIXMLDocumentPart keeps a reference to the underlying a {@link org.apache.poi.openxml4j.opc.PackagePart}.
  * </p>
- *
- * @author Yegor Kozlov
  */
 public class POIXMLDocumentPart {
     private static final POILogger logger = POILogFactory.getLogger(POIXMLDocumentPart.class);
@@ -80,6 +78,8 @@ public class POIXMLDocumentPart {
         }
         
         /**
+         * @param <T> 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);
     }
@@ -324,6 +335,8 @@ public class POIXMLDocumentPart {
      * @param relationshipType the package relationship type
      * @param part the child to add
      * 
+     * @return the new RelationPart
+     *
      * @since 3.14-Beta1
      */
     public final RelationPart addRelation(String relId, POIXMLRelation relationshipType, POIXMLDocumentPart part) {
@@ -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);

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;

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!");
 	}
 }

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();