/* ==================================================================== Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ==================================================================== */ package org.apache.poi.ooxml; import java.io.IOException; import java.net.URI; import java.util.ArrayList; import java.util.Collections; import java.util.LinkedHashMap; 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.exceptions.PartAlreadyExistsException; import org.apache.poi.openxml4j.opc.OPCPackage; import org.apache.poi.openxml4j.opc.PackagePart; import org.apache.poi.openxml4j.opc.PackagePartName; import org.apache.poi.openxml4j.opc.PackageRelationship; import org.apache.poi.openxml4j.opc.PackageRelationshipCollection; import org.apache.poi.openxml4j.opc.PackageRelationshipTypes; import org.apache.poi.openxml4j.opc.PackagingURIHelper; import org.apache.poi.openxml4j.opc.TargetMode; import org.apache.poi.util.IOUtils; import org.apache.poi.util.Internal; import org.apache.poi.util.POILogFactory; import org.apache.poi.util.POILogger; import org.apache.poi.xddf.usermodel.chart.XDDFChart; import org.apache.poi.xssf.usermodel.XSSFRelation; import org.apache.poi.xssf.usermodel.XSSFWorkbook; import org.apache.poi.xwpf.usermodel.XWPFRelation; /** * Represents an entry of a OOXML package. *
* Each POIXMLDocumentPart keeps a reference to the underlying a {@link org.apache.poi.openxml4j.opc.PackagePart}. *
*/ public class POIXMLDocumentPart { private static final POILogger logger = POILogFactory.getLogger(POIXMLDocumentPart.class); private String coreDocumentRel = PackageRelationshipTypes.CORE_DOCUMENT; private PackagePart packagePart; private POIXMLDocumentPart parent; private Map*
* There can be multiple references to the given {@link POIXMLDocumentPart} * and only the first in the order of creation is returned. * * @param part The {@link POIXMLDocumentPart} for which the according * relation-id shall be found. * @return The value of the {@link PackageRelationship#getId()} or null, if * parts are not related. */ public final String getRelationId(POIXMLDocumentPart part) { for (RelationPart rp : relations.values()) { if (rp.getDocumentPart() == part) { return rp.getRelationship().getId(); } } return null; } /** * Add a new child 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 */ public final RelationPart addRelation(String relId, POIXMLRelation relationshipType, POIXMLDocumentPart part) { PackageRelationship pr = this.packagePart.findExistingRelation(part.getPackagePart()); if (pr == null) { PackagePartName ppn = part.getPackagePart().getPartName(); String relType = relationshipType.getRelation(); pr = packagePart.addRelationship(ppn, TargetMode.INTERNAL, relType, relId); } addRelation(pr, part); return new RelationPart(pr, part); } /** * Add a new child POIXMLDocumentPart * * @param pr the relationship of the child * @param part the child to add */ private void addRelation(PackageRelationship pr, POIXMLDocumentPart part) { relations.put(pr.getId(), new RelationPart(pr, part)); part.incrementRelationCounter(); } /** * Remove the relation to the specified part in this package and remove the * part, if it is no longer needed.
*
* If there are multiple relationships to the same part, this will only * remove the first relationship in the order of creation. The removal * via the part id ({@link #removeRelation(String)} is preferred. * * @param part the part which relation is to be removed from this document */ protected final void removeRelation(POIXMLDocumentPart part) { removeRelation(part, true); } /** * Remove the relation to the specified part in this package and remove the * part, if it is no longer needed and flag is set to true.
*
* If there are multiple relationships to the same part, this will only * remove the first relationship in the order of creation. The removal * via the part id ({@link #removeRelation(String, boolean)} is preferred. * * @param part The related part, to which the relation shall be removed. * @param removeUnusedParts true, if the part shall be removed from the package if not * needed any longer. * @return true, if the relation was removed */ protected final boolean removeRelation(POIXMLDocumentPart part, boolean removeUnusedParts) { String id = getRelationId(part); return removeRelation(id, removeUnusedParts); } /** * Remove the relation to the specified part in this package and remove the * part, if it is no longer needed.
*
* If there are multiple relationships to the same part, this will only * remove the first relationship in the order of creation. The removal * via the part id ({@link #removeRelation(String)} is preferred. * * @param partId the part id which relation is to be removed from this document * @since 4.0.0 */ protected final void removeRelation(String partId) { removeRelation(partId, true); } /** * Remove the relation to the specified part in this package and remove the * part, if it is no longer needed and flag is set to true.
*
* @param partId The related part id, to which the relation shall be removed.
* @param removeUnusedParts true, if the part shall be removed from the package if not
* needed any longer.
* @return true, if the relation was removed
* @since 4.0.0
*/
private final boolean removeRelation(String partId, boolean removeUnusedParts) {
RelationPart rp = relations.get(partId);
if (rp == null) {
// part is not related with this POIXMLDocumentPart
return false;
}
POIXMLDocumentPart part = rp.getDocumentPart();
/* decrement usage counter */
part.decrementRelationCounter();
/* remove packagepart relationship */
getPackagePart().removeRelationship(partId);
/* remove POIXMLDocument from relations */
relations.remove(partId);
if (removeUnusedParts) {
/* if last relation to target part was removed, delete according target part */
if (part.getRelationCounter() == 0) {
try {
part.onDocumentRemove();
} catch (IOException e) {
throw new POIXMLException(e);
}
getPackagePart().getPackage().removePart(part.getPackagePart());
}
}
return true;
}
/**
* Returns the parent POIXMLDocumentPart. All parts except root have not-null parent.
*
* @return the parent POIXMLDocumentPart or null
for the root element.
*/
public final POIXMLDocumentPart getParent() {
return parent;
}
@Override
public String toString() {
return packagePart == null ? "" : packagePart.toString();
}
/**
* Save the content in the underlying package part.
* Default implementation is empty meaning that the package part is left unmodified.
*
* Sub-classes should override and add logic to marshal the "model" into Ooxml4J. *
* For example, the code saving a generic XML entry may look as follows: *
* protected void commit() throws IOException { * PackagePart part = getPackagePart(); * OutputStream out = part.getOutputStream(); * XmlObject bean = getXmlBean(); //the "model" which holds changes in memory * bean.save(out, DEFAULT_XML_OPTIONS); * out.close(); * } ** * @throws IOException a subclass may throw an IOException if the changes can't be committed */ protected void commit() throws IOException { } /** * Save changes in the underlying OOXML package. * Recursively fires {@link #commit()} for each package part * * @param alreadySaved context set containing already visited nodes * @throws IOException a related part may throw an IOException if the changes can't be saved */ protected final void onSave(Set
* Note: This is overwritten for some objects, as *PictureData seem to store the actual content
* in the part directly without keeping a copy like all others therefore we need to handle them differently.
*/
protected void prepareForCommit() {
PackagePart part = this.getPackagePart();
if (part != null) {
part.clear();
}
}
/**
* Create a new child POIXMLDocumentPart
*
* @param descriptor the part descriptor
* @param factory the factory that will create an instance of the requested relation
* @return the created child POIXMLDocumentPart
* @throws PartAlreadyExistsException If rule M1.12 is not verified : Packages shall not contain
* equivalent part names and package implementers shall neither
* create nor recognize packages with equivalent part names.
*/
public final POIXMLDocumentPart createRelationship(POIXMLRelation descriptor, POIXMLFactory factory) {
return createRelationship(descriptor, factory, -1, false).getDocumentPart();
}
/**
* Create a new child POIXMLDocumentPart
*
* @param descriptor the part descriptor
* @param factory the factory that will create an instance of the requested relation
* @param idx part number
* @return the created child POIXMLDocumentPart
* @throws PartAlreadyExistsException If rule M1.12 is not verified : Packages shall not contain
* equivalent part names and package implementers shall neither
* create nor recognize packages with equivalent part names.
*/
public final POIXMLDocumentPart createRelationship(POIXMLRelation descriptor, POIXMLFactory factory, int idx) {
return createRelationship(descriptor, factory, idx, false).getDocumentPart();
}
/**
* Identifies the next available part number for a part of the given type,
* if possible, otherwise -1 if none are available.
* The found (valid) index can then be safely given to
* {@link #createRelationship(POIXMLRelation, POIXMLFactory, int)} or
* {@link #createRelationship(POIXMLRelation, POIXMLFactory, int, boolean)}
* without naming clashes.
* If parts with other types are already claiming a name for this relationship
* type (eg a {@link XSSFRelation#CHART} using the drawing part namespace
* normally used by {@link XSSFRelation#DRAWINGS}), those will be considered
* when finding the next spare number.
*
* @param descriptor The relationship type to find the part number for
* @param minIdx The minimum free index to assign, use -1 for any
* @return The next free part number, or -1 if none available
*/
@Internal
public final int getNextPartNumber(POIXMLRelation descriptor, int minIdx) {
OPCPackage pkg = packagePart.getPackage();
try {
String name = descriptor.getDefaultFileName();
if (name.equals(descriptor.getFileName(9999))) {
// Non-index based, check if default is free
PackagePartName ppName = PackagingURIHelper.createPartName(name);
if (pkg.containPart(ppName)) {
// Default name already taken, not index based, nothing free
return -1;
} else {
// Default name free
return 0;
}
}
// Default to searching from 1, unless they asked for 0+
int idx = (minIdx < 0) ? 1 : minIdx;
int maxIdx = minIdx + pkg.getParts().size();
while (idx <= maxIdx) {
name = descriptor.getFileName(idx);
PackagePartName ppName = PackagingURIHelper.createPartName(name);
if (!pkg.containPart(ppName)) {
return idx;
}
idx++;
}
} catch (InvalidFormatException e) {
// Give a general wrapped exception for the problem
throw new POIXMLException(e);
}
return -1;
}
/**
* Create a new child POIXMLDocumentPart
*
* @param descriptor the part descriptor
* @param factory the factory that will create an instance of the requested relation
* @param idx part number
* @param noRelation if true, then no relationship is added.
* @return the created child POIXMLDocumentPart
* @throws PartAlreadyExistsException If rule M1.12 is not verified : Packages shall not contain
* equivalent part names and package implementers shall neither
* create nor recognize packages with equivalent part names.
*/
public final RelationPart createRelationship(POIXMLRelation descriptor, POIXMLFactory factory, int idx, boolean noRelation) {
try {
PackagePartName ppName = PackagingURIHelper.createPartName(descriptor.getFileName(idx));
PackageRelationship rel = null;
PackagePart part = packagePart.getPackage().createPart(ppName, descriptor.getContentType());
if (!noRelation) {
/* only add to relations, if according relationship is being created. */
rel = packagePart.addRelationship(ppName, TargetMode.INTERNAL, descriptor.getRelation());
}
POIXMLDocumentPart doc = factory.newDocumentPart(descriptor);
doc.packagePart = part;
doc.parent = this;
if (!noRelation) {
/* only add to relations, if according relationship is being created. */
addRelation(rel, doc);
}
return new RelationPart(rel, doc);
} catch (PartAlreadyExistsException pae) {
// Return the specific exception so the user knows
// that the name is already taken
throw pae;
} catch (Exception e) {
// Give a general wrapped exception for the problem
throw new POIXMLException(e);
}
}
/**
* Iterate through the underlying PackagePart and create child POIXMLFactory instances
* using the specified factory
*
* @param factory the factory object that creates POIXMLFactory instances
* @param context context map containing already visited noted keyed by targetURI
* @throws OpenXML4JException thrown when a related part can't be read
*/
protected void read(POIXMLFactory factory, Map
* This method only exists to allow access to protected {@link POIXMLDocumentPart#onDocumentRead()}
* from {@link org.apache.poi.xwpf.usermodel.XWPFDocument} without reflection. It should be removed.
*
* @param part the part which is to be read
* @throws IOException if the part can't be read
*/
@Internal
@Deprecated
public static void _invokeOnDocumentRead(POIXMLDocumentPart part) throws IOException {
part.onDocumentRead();
}
/**
* Retrieves the core document part
*
* Since POI 4.1.2 - pkg is closed if this method throws an exception
*/
private static PackagePart getPartFromOPCPackage(OPCPackage pkg, String coreDocumentRel) {
PackageRelationship coreRel = pkg.getRelationshipsByType(coreDocumentRel).getRelationship(0);
if (coreRel != null) {
PackagePart pp = pkg.getPart(coreRel);
if (pp == null) {
IOUtils.closeQuietly(pkg);
throw new POIXMLException("OOXML file structure broken/invalid - core document '" + coreRel.getTargetURI() + "' not found.");
}
return pp;
}
coreRel = pkg.getRelationshipsByType(PackageRelationshipTypes.STRICT_CORE_DOCUMENT).getRelationship(0);
if (coreRel != null) {
IOUtils.closeQuietly(pkg);
throw new POIXMLException("Strict OOXML isn't currently supported, please see bug #57699");
}
IOUtils.closeQuietly(pkg);
throw new POIXMLException("OOXML file structure broken/invalid - no core document found!");
}
}