moparisthebest/poi
1
0
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity

javadocs fixes

Browse Source 
git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1748042 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Andreas Beeker 2016-06-12 19:54:35 +00:00
parent 0ef5f1d292
commit 1ace43ba9f
5 changed files with 91 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
src/ooxml/java/org/apache/poi/POIXMLDocument.java
View File

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

21
src/ooxml/java/org/apache/poi/POIXMLDocumentPart.java
View File

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

2
src/ooxml/java/org/apache/poi/POIXMLFactory.java
View File

@ -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;

8
src/ooxml/java/org/apache/poi/POIXMLPropertiesTextExtractor.java
View File

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

6
src/ooxml/java/org/apache/poi/POIXMLTextExtractor.java
View File

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