Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.poi.openxml4j.opc
Class OPCPackage

    java.lang.Object
      org.apache.poi.openxml4j.opc.OPCPackage

All Implemented Interfaces:
  RelationshipSource, poi.support.Closeable

Direct Known Subclasses:
  Package

    public abstract class OPCPackage

extends java.lang.Object
implements RelationshipSource, poi.support.Closeable

Represents a container that can store multiple data objects.

Version:
  0.1
Author:
  Julien Chable, CDubet

Method Summary
`PackageRelationship` | `addExternalRelationship(java.lang.String target, java.lang.String relationshipType)` Adds an external relationship to a part (except relationships part).
`PackageRelationship` | `addExternalRelationship(java.lang.String target, java.lang.String relationshipType, java.lang.String id)` Adds an external relationship to a part (except relationships part).
`void` | `addMarshaller(java.lang.String contentType, PartMarshaller marshaller)` Add a marshaller.
`PackageRelationship` | `addRelationship(PackagePartName targetPartName, TargetMode targetMode, java.lang.String relationshipType)` Add a package relationship.
`PackageRelationship` | `addRelationship(PackagePartName targetPartName, TargetMode targetMode, java.lang.String relationshipType, java.lang.String relID)` Add a relationship to the package (except relationships part).
`void` | `addThumbnail(java.lang.String path)` Add a thumbnail to the package.
`void` | `addUnmarshaller(java.lang.String contentType, PartUnmarshaller unmarshaller)` Add an unmarshaller.
`void` | `clearRelationships()` Clear package relationships.
`void` | `close()` Close the open, writable package and save its content.
`boolean` | `containPart(PackagePartName partName)` Check if a part already exists in this package from its name.
`static OPCPackage` | `create(java.io.File file)` Creates a new package.
`static OPCPackage` | `create(java.io.OutputStream output)`
`static OPCPackage` | `create(java.lang.String path)` Creates a new package.
`PackagePart` | `createPart(PackagePartName partName, java.lang.String contentType)` Create and add a part, with the specified name and content type, to the package.
`PackagePart` | `createPart(PackagePartName partName, java.lang.String contentType, java.io.ByteArrayOutputStream content)` Add a part to the package.
`void` | `deletePart(PackagePartName partName)` Delete the part with the specified name and its associated relationships part if one exists.
`void` | `deletePartRecursive(PackagePartName partName)` Delete the part with the specified name and all part listed in its associated relationships part if one exists.
`void` | `ensureRelationships()` Ensure that the relationships collection is not null.
`void` | `flush()` Flush the package : save all.
`PackageAccess` | `getPackageAccess()` Get the package access mode.
`PackageProperties` | `getPackageProperties()` Retrieves or creates if none exists, core package property part.
`PackagePart` | `getPart(PackagePartName partName)` Retrieve a part identified by its name.
`PackagePart` | `getPart(PackageRelationship partRel)` Get the target part from the specified relationship.
`java.util.ArrayList` | `getParts()` Load the parts of the archive if it has not been done yet.
`java.util.ArrayList` | `getPartsByContentType(java.lang.String contentType)` Retrieve parts by content type.
`java.util.List` | `getPartsByName(java.util.regex.Pattern namePattern)`
`java.util.ArrayList` | `getPartsByRelationshipType(java.lang.String relationshipType)` Retrieve parts by relationship type.
`PackageRelationship` | `getRelationship(java.lang.String id)` Retrieves a package relationship from its id.
`PackageRelationshipCollection` | `getRelationships()` Retrieves all package relationships.
`PackageRelationshipCollection` | `getRelationshipsByType(java.lang.String relationshipType)` Retrieves all relationships with the specified type.
`boolean` | `hasRelationships()` Knows if the part have any relationships.
`boolean` | `isRelationshipExists(PackageRelationship rel)` Checks if the specified relationship is part of this package part.
`static OPCPackage` | `open(java.io.InputStream in)` Open a package.
`static OPCPackage` | `open(java.lang.String path)` Open a package with read/write permission.
`static OPCPackage` | `open(java.lang.String path, PackageAccess access)` Open a package.
`static OPCPackage` | `openOrCreate(java.io.File file)` Opens a package if it exists, else it creates one.
`void` | `removeMarshaller(java.lang.String contentType)` Remove a marshaller by its content type.
`void` | `removePart(PackagePart part)` Remove the specified part in this package.
`void` | `removePart(PackagePartName partName)` Remove a part in this package.
`void` | `removePartRecursive(PackagePartName partName)` Remove a part from this package as well as its relationship part, if one exists, and all parts listed in the relationship part.
`void` | `removeRelationship(java.lang.String id)` Delete a relationship from this package.
`void` | `removeUnmarshaller(java.lang.String contentType)` Remove an unmarshaller by its content type.
`boolean` | `replaceContentType(java.lang.String oldContentType, java.lang.String newContentType)` Replace a content type in this package.
`void` | `revert()` Close the package WITHOUT saving its content.
`void` | `save(java.io.File targetFile)` Save the document in the specified file.
`void` | `save(java.io.OutputStream outputStream)` Save the document in the specified output stream.
`boolean` | `validatePackage(OPCPackage pkg)` Validates the package compliance with the OPC specifications.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### open

    public static OPCPackage open(java.lang.String path)
                           throws InvalidFormatException

  Open a package with read/write permission.

  Parameters:
    `path` - The document path.
  Returns:
    A Package object, else null.
  Throws:
    `InvalidFormatException` - If the specified file doesn't exist, and a parsing error occur.

### open

    public static OPCPackage open(java.lang.String path,
                                  PackageAccess access)
                           throws InvalidFormatException

  Open a package.

  Parameters:
    `path` - The document path.
    `access` - PackageBase access.
  Returns:
    A PackageBase object, else null.
  Throws:
    `InvalidFormatException` - If the specified file doesn't exist, and a parsing error occur.

### open

    public static OPCPackage open(java.io.InputStream in)
                           throws InvalidFormatException,
                                  java.io.IOException

  Open a package. Note - uses quite a bit more memory than `open(String)`, which doesn't need to hold the whole zip file in memory, and can take advantage of native methods

  Parameters:
    `in` - The InputStream to read the package from
  Returns:
    A PackageBase object
  Throws:
    `InvalidFormatException`
    `java.io.IOException`

### openOrCreate

    public static OPCPackage openOrCreate(java.io.File file)
                                   throws InvalidFormatException

  Opens a package if it exists, else it creates one.

  Parameters:
    `file` - The file to open or to create.
  Returns:
    A newly created package if the specified file does not exist, else the package extract from the file.
  Throws:
    `InvalidFormatException` - Throws if the specified file exist and is not valid.

### create

    public static OPCPackage create(java.lang.String path)

  Creates a new package.

  Parameters:
    `path` - Path of the document.
  Returns:
    A newly created PackageBase ready to use.

### create

    public static OPCPackage create(java.io.File file)

  Creates a new package.

  Parameters:
    `file` - Path of the document.
  Returns:
    A newly created PackageBase ready to use.

### create

    public static OPCPackage create(java.io.OutputStream output)

### flush

    public void flush()

  Flush the package : save all.

  See Also:
    `close()`

### close

    public void close()
               throws java.io.IOException

  Close the open, writable package and save its content. If your package is open read only, then you should call `revert()` when finished with the package.

  Specified by:
    `close` in interface `poi.support.Closeable`
  Throws:
    `java.io.IOException` - If an IO exception occur during the saving process.

### revert

    public void revert()

  Close the package WITHOUT saving its content. Reinitialize this package and cancel all changes done to it.

### addThumbnail

    public void addThumbnail(java.lang.String path)
                      throws java.io.IOException

  Add a thumbnail to the package. This method is provided to make easier the addition of a thumbnail in a package. You can do the same work by using the traditionnal relationship and part mechanism.

  Parameters:
    `path` - The full path to the image file.
  Throws:
    `java.io.IOException`

### getPackageProperties

    public PackageProperties getPackageProperties()
                                           throws InvalidFormatException

  Retrieves or creates if none exists, core package property part.

  Returns:
    The PackageProperties part of this package.
  Throws:
    `InvalidFormatException`

### getPart

    public PackagePart getPart(PackagePartName partName)

  Retrieve a part identified by its name.

  Parameters:
    `partName` - Part name of the part to retrieve.
  Returns:
    The part with the specified name, else `null`.

### getPartsByContentType

    public java.util.ArrayList getPartsByContentType(java.lang.String contentType)

  Retrieve parts by content type.

  Parameters:
    `contentType` - The content type criteria.
  Returns:
    All part associated to the specified content type.

### getPartsByRelationshipType

    public java.util.ArrayList getPartsByRelationshipType(java.lang.String relationshipType)

  Retrieve parts by relationship type.

  Parameters:
    `relationshipType` - Relationship type.
  Returns:
    All parts which are the target of a relationship with the specified type, if the method can't retrieve relationships from the package, then return `null`.

### getPartsByName

    public java.util.List getPartsByName(java.util.regex.Pattern namePattern)

### getPart

    public PackagePart getPart(PackageRelationship partRel)

  Get the target part from the specified relationship.

  Parameters:
    `partRel` - The part relationship uses to retrieve the part.

### getParts

    public java.util.ArrayList getParts()
                                 throws InvalidFormatException

  Load the parts of the archive if it has not been done yet. The relationships of each part are not loaded. Note - Rule M4.1 states that there may only ever be one Core Properties Part, but Office produced files will sometimes have multiple! As Office ignores all but the first, we relax Compliance with Rule M4.1, and ignore all others silently too.

  Returns:
    All this package's parts.
  Throws:
    `InvalidFormatException`

### createPart

    public PackagePart createPart(PackagePartName partName,
                                  java.lang.String contentType)

  Create and add a part, with the specified name and content type, to the package.

  Parameters:
    `partName` - Part name.
    `contentType` - Part content type.
  Returns:
    The newly created part.
  Throws:
    `InvalidFormatException` - 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.
  See Also:
    `createPartImpl(PackagePartName, String, boolean)`

### createPart

    public PackagePart createPart(PackagePartName partName,
                                  java.lang.String contentType,
                                  java.io.ByteArrayOutputStream content)

  Add a part to the package.

  Parameters:
    `partName` - Part name of the part to create.
    `contentType` - type associated with the file
    `content` - the contents to add. In order to have faster operation in document merge, the data are stored in memory not on a hard disk
  Returns:
    The new part.
  See Also:
    `createPart(PackagePartName, String)`

### removePart

    public void removePart(PackagePart part)

  Remove the specified part in this package. If this part is relationship part, then delete all relationships in the source part.

  Parameters:
    `part` - The part to remove. If `null`, skip the action.
  See Also:
    `removePart(PackagePartName)`

### removePart

    public void removePart(PackagePartName partName)

  Remove a part in this package. If this part is relationship part, then delete all relationships in the source part.

  Parameters:
    `partName` - The part name of the part to remove.

### removePartRecursive

    public void removePartRecursive(PackagePartName partName)
                             throws InvalidFormatException

  Remove a part from this package as well as its relationship part, if one exists, and all parts listed in the relationship part. Be aware that this do not delete relationships which target the specified part.

  Parameters:
    `partName` - The name of the part to delete.
  Throws:
    `InvalidFormatException` - Throws if the associated relationship part of the specified part is not valid.

### deletePart

    public void deletePart(PackagePartName partName)

  Delete the part with the specified name and its associated relationships part if one exists. Prefer the use of this method to delete a part in the package, compare to the remove() methods that don't remove associated relationships part.

  Parameters:
    `partName` - Name of the part to delete

### deletePartRecursive

    public void deletePartRecursive(PackagePartName partName)

  Delete the part with the specified name and all part listed in its associated relationships part if one exists. This process is recursively apply to all parts in the relationships part of the specified part. Prefer the use of this method to delete a part in the package, compare to the remove() methods that don't remove associated relationships part.

  Parameters:
    `partName` - Name of the part to delete

### containPart

    public boolean containPart(PackagePartName partName)

  Check if a part already exists in this package from its name.

  Parameters:
    `partName` - Part name to check.
  Returns:
    true if the part is logically added to this package, else false.

### addRelationship

    public PackageRelationship addRelationship(PackagePartName targetPartName,
                                               TargetMode targetMode,
                                               java.lang.String relationshipType,
                                               java.lang.String relID)

  Add a relationship to the package (except relationships part). Check rule M4.1 : The format designer shall specify and the format producer shall create at most one core properties relationship for a package. A format consumer shall consider more than one core properties relationship for a package to be an error. If present, the relationship shall target the Core Properties part. Check rule M1.25: The Relationships part shall not have relationships to any other part. Package implementers shall enforce this requirement upon the attempt to create such a relationship and shall treat any such relationship as invalid.

  Specified by:
    `addRelationship` in interface `RelationshipSource`
  Parameters:
    `targetPartName` - Target part name.
    `targetMode` - Target mode, either Internal or External.
    `relationshipType` - Relationship type.
    `relID` - ID of the relationship.
  Returns:
    The newly created and added relationship
  See Also:
    `PackageRelationshipTypes`

### addRelationship

    public PackageRelationship addRelationship(PackagePartName targetPartName,
                                               TargetMode targetMode,
                                               java.lang.String relationshipType)

  Add a package relationship.

  Specified by:
    `addRelationship` in interface `RelationshipSource`
  Parameters:
    `targetPartName` - Target part name.
    `targetMode` - Target mode, either Internal or External.
    `relationshipType` - Relationship type.
  Returns:
    The newly created and added relationship
  See Also:
    `PackageRelationshipTypes`

### addExternalRelationship

    public PackageRelationship addExternalRelationship(java.lang.String target,
                                                       java.lang.String relationshipType)

  Adds an external relationship to a part (except relationships part). The targets of external relationships are not subject to the same validity checks that internal ones are, as the contents is potentially any file, URL or similar.

  Specified by:
    `addExternalRelationship` in interface `RelationshipSource`
  Parameters:
    `target` - External target of the relationship
    `relationshipType` - Type of relationship.
  Returns:
    The newly created and added relationship
  See Also:
    `RelationshipSource.addExternalRelationship(java.lang.String, java.lang.String)`

### addExternalRelationship

    public PackageRelationship addExternalRelationship(java.lang.String target,
                                                       java.lang.String relationshipType,
                                                       java.lang.String id)

  Adds an external relationship to a part (except relationships part). The targets of external relationships are not subject to the same validity checks that internal ones are, as the contents is potentially any file, URL or similar.

  Specified by:
    `addExternalRelationship` in interface `RelationshipSource`
  Parameters:
    `target` - External target of the relationship
    `relationshipType` - Type of relationship.
    `id` - Relationship unique id.
  Returns:
    The newly created and added relationship
  See Also:
    `RelationshipSource.addExternalRelationship(java.lang.String, java.lang.String)`

### removeRelationship

    public void removeRelationship(java.lang.String id)

  Delete a relationship from this package.

  Specified by:
    `removeRelationship` in interface `RelationshipSource`
  Parameters:
    `id` - Id of the relationship to delete.

### getRelationships

    public PackageRelationshipCollection getRelationships()

  Retrieves all package relationships.

  Specified by:
    `getRelationships` in interface `RelationshipSource`
  Returns:
    All package relationships of this package.
  Throws:
    `OpenXML4JException`
  See Also:
    `getRelationshipsHelper(String)`

### getRelationshipsByType

    public PackageRelationshipCollection getRelationshipsByType(java.lang.String relationshipType)

  Retrieves all relationships with the specified type.

  Specified by:
    `getRelationshipsByType` in interface `RelationshipSource`
  Parameters:
    `relationshipType` - The filter specifying the relationship type.
  Returns:
    All relationships with the specified relationship type.

### clearRelationships

    public void clearRelationships()

  Clear package relationships.

  Specified by:
    `clearRelationships` in interface `RelationshipSource`

### ensureRelationships

    public void ensureRelationships()

  Ensure that the relationships collection is not null.

### getRelationship

    public PackageRelationship getRelationship(java.lang.String id)

  Description copied from interface: `RelationshipSource`
  Retrieves a package relationship from its id.

  Specified by:
    `getRelationship` in interface `RelationshipSource`
  Parameters:
    `id` - ID of the package relationship to retrieve.
  Returns:
    The package relationship
  See Also:
    `RelationshipSource.getRelationship(java.lang.String)`

### hasRelationships

    public boolean hasRelationships()

  Description copied from interface: `RelationshipSource`
  Knows if the part have any relationships.

  Specified by:
    `hasRelationships` in interface `RelationshipSource`
  Returns:
    true if the part have at least one relationship else false.
  See Also:
    `RelationshipSource.hasRelationships()`

### isRelationshipExists

    public boolean isRelationshipExists(PackageRelationship rel)

  Description copied from interface: `RelationshipSource`
  Checks if the specified relationship is part of this package part.

  Specified by:
    `isRelationshipExists` in interface `RelationshipSource`
  Parameters:
    `rel` - The relationship to check.
  Returns:
    true if the specified relationship exists in this part, else returns false
  See Also:
    `RelationshipSource.isRelationshipExists(org.apache.poi.openxml4j.opc.PackageRelationship)`

### addMarshaller

    public void addMarshaller(java.lang.String contentType,
                              PartMarshaller marshaller)

  Add a marshaller.

  Parameters:
    `contentType` - The content type to bind to the specified marshaller.
    `marshaller` - The marshaller to register with the specified content type.

### addUnmarshaller

    public void addUnmarshaller(java.lang.String contentType,
                                PartUnmarshaller unmarshaller)

  Add an unmarshaller.

  Parameters:
    `contentType` - The content type to bind to the specified unmarshaller.
    `unmarshaller` - The unmarshaller to register with the specified content type.

### removeMarshaller

    public void removeMarshaller(java.lang.String contentType)

  Remove a marshaller by its content type.

  Parameters:
    `contentType` - The content type associated with the marshaller to remove.

### removeUnmarshaller

    public void removeUnmarshaller(java.lang.String contentType)

  Remove an unmarshaller by its content type.

  Parameters:
    `contentType` - The content type associated with the unmarshaller to remove.

### getPackageAccess

    public PackageAccess getPackageAccess()

  Get the package access mode.

  Returns:
    the packageAccess The current package access.

### validatePackage

    public boolean validatePackage(OPCPackage pkg)
                            throws InvalidFormatException

  Validates the package compliance with the OPC specifications.

  Returns:
    true if the package is valid else false
  Throws:
    `InvalidFormatException`

### save

    public void save(java.io.File targetFile)
              throws java.io.IOException

  Save the document in the specified file.

  Parameters:
    `targetFile` - Destination file.
  Throws:
    `java.io.IOException` - Throws if an IO exception occur.
  See Also:
    `save(OutputStream)`

### save

    public void save(java.io.OutputStream outputStream)
              throws java.io.IOException

  Save the document in the specified output stream.

  Parameters:
    `outputStream` - The stream to save the package.
  Throws:
    `java.io.IOException`
  See Also:
    `saveImpl(OutputStream)`

### replaceContentType

    public boolean replaceContentType(java.lang.String oldContentType,
                                      java.lang.String newContentType)

  Replace a content type in this package.

  A typical scneario to call this method is to rename a template file to the main format, e.g. ".dotx" to ".docx" ".dotm" to ".docm" ".xltx" to ".xlsx" ".xltm" to ".xlsm" ".potx" to ".pptx" ".potm" to ".pptm"

  For example, a code converting a .xlsm macro workbook to .xlsx would look as follows:

           OPCPackage pkg = OPCPackage.open(new FileInputStream("macro-workbook.xlsm"));
           pkg.replaceContentType(
               "application/vnd.ms-excel.sheet.macroEnabled.main+xml",
               "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml");

           FileOutputStream out = new FileOutputStream("workbook.xlsx");
           pkg.save(out);
           out.close();

  Parameters:
    `oldContentType` - the content type to be replaced
    `newContentType` - the replacement
  Returns:
    whether replacement was succesfull
  Since:
    POI-3.8

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD