You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@poi.apache.org by ki...@apache.org on 2016/06/12 19:54:35 UTC
svn commit: r1748042 - in /poi/trunk/src/ooxml/java/org/apache/poi:
POIXMLDocument.java POIXMLDocumentPart.java POIXMLFactory.java
POIXMLPropertiesTextExtractor.java POIXMLTextExtractor.java
Author: kiwiwings
Date: Sun Jun 12 19:54:35 2016
New Revision: 1748042
URL: http://svn.apache.org/viewvc?rev=1748042&view=rev
Log:
javadocs fixes
Modified:
poi/trunk/src/ooxml/java/org/apache/poi/POIXMLDocument.java
poi/trunk/src/ooxml/java/org/apache/poi/POIXMLDocumentPart.java
poi/trunk/src/ooxml/java/org/apache/poi/POIXMLFactory.java
poi/trunk/src/ooxml/java/org/apache/poi/POIXMLPropertiesTextExtractor.java
poi/trunk/src/ooxml/java/org/apache/poi/POIXMLTextExtractor.java
Modified: poi/trunk/src/ooxml/java/org/apache/poi/POIXMLDocument.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/POIXMLDocument.java?rev=1748042&r1=1748041&r2=1748042&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/POIXMLDocument.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/POIXMLDocument.java Sun Jun 12 19:54:35 2016
@@ -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 ext
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 ext
}
/**
- * 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 ext
}
/**
- * 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 ext
* 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 ext
/**
* 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 ext
/**
* 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 ext
/**
* 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 ext
*
* @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 ext
//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);
}
}
Modified: poi/trunk/src/ooxml/java/org/apache/poi/POIXMLDocumentPart.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/POIXMLDocumentPart.java?rev=1748042&r1=1748041&r2=1748042&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/POIXMLDocumentPart.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/POIXMLDocumentPart.java Sun Jun 12 19:54:35 2016
@@ -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);
}
@@ -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);
Modified: poi/trunk/src/ooxml/java/org/apache/poi/POIXMLFactory.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/POIXMLFactory.java?rev=1748042&r1=1748041&r2=1748042&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/POIXMLFactory.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/POIXMLFactory.java Sun Jun 12 19:54:35 2016
@@ -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;
Modified: poi/trunk/src/ooxml/java/org/apache/poi/POIXMLPropertiesTextExtractor.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/POIXMLPropertiesTextExtractor.java?rev=1748042&r1=1748041&r2=1748042&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/POIXMLPropertiesTextExtractor.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/POIXMLPropertiesTextExtractor.java Sun Jun 12 19:54:35 2016
@@ -149,7 +149,7 @@ public class POIXMLPropertiesTextExtract
* 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 POIXMLPropertiesTextExtract
return text.toString();
}
- public String getText() {
+ @Override
+ public String getText() {
try {
return
getCorePropertiesText() +
@@ -264,7 +265,8 @@ public class POIXMLPropertiesTextExtract
}
}
- public POIXMLPropertiesTextExtractor getMetadataTextExtractor() {
+ @Override
+ public POIXMLPropertiesTextExtractor getMetadataTextExtractor() {
throw new IllegalStateException("You already have the Metadata Text Extractor, not recursing!");
}
}
Modified: poi/trunk/src/ooxml/java/org/apache/poi/POIXMLTextExtractor.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/POIXMLTextExtractor.java?rev=1748042&r1=1748041&r2=1748042&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/POIXMLTextExtractor.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/POIXMLTextExtractor.java Sun Jun 12 19:54:35 2016
@@ -73,7 +73,8 @@ public abstract class POIXMLTextExtracto
* 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 POIXMLTextExtracto
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();
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@poi.apache.org
For additional commands, e-mail: commits-help@poi.apache.org