==================================================================== */
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";
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,
}
/**
- * 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;
}
}
/**
- * 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 =
* 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);
}
/**
* 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) {
/**
* 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;
/**
* 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) {
*
* @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?
//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);
}
}
* <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);
}
/**
+ * @param <T> the cast of the caller to a document sub class
+ *
* @return the child document part
*/
@SuppressWarnings("unchecked")
/**
* Construct POIXMLDocumentPart representing a "core document" package part.
+ *
+ * @param pkg the OPCPackage containing this document
*/
public POIXMLDocumentPart(OPCPackage pkg) {
this(pkg, PackageRelationshipTypes.CORE_DOCUMENT);
/**
* 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));
* 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 =
/**
* 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);
}
* @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
*/
/**
* 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);