The Package Content Provider

OpenOffice.org Developer's Guide

Universal Content Providers

< Previous Section

Next Section >

• The Hierarchy Content Provider
• The File Content Provider
• The FTP Content Provider
• The WebDAV Content Provider
• The Package Content Provider
• The Help Content Provider

< Previous Page

Next Page >

The Package Content Provider (PCP) implements a content provider for the Universal Content Broker (UCB). It provides access to the content of ZIP and JAR archive files. It maybe extended to support other packages, such as OLE storages, in the future.

PCP Contents

The PCP provides two different types of contents: stream and folder.

1. A PCP stream is a content that represents a file inside a package. It is always contained in a PCP folder. A PCP stream has no children.
2. A PCP folder is a container for other PCP folders and PCP streams.

A Package Content Provider

Creation of New PCP Contents

PCP folders implement the interface com.sun.star.ucb.XContentCreator. PCP streams and PCP folders support the command "insert", therefore all PCP folders can create new PCP folders and PCP streams. To create a new child of a PCP folder:

1. The parent folder creates a new content by calling its createNewContent() method. The content type for new folders is "application/vnd.sun.star.pkg-folder". To create a new stream, use the type string "application/vnd.sun.star.pkg-stream".
2. Set a title for the new folder or stream. The new child executes a "setPropertyValues" command that sets the property Title to a non-empty value.
3. The new child, not the parent, executes the command "insert". This commits the creation process. For streams, supply the implementation of an com.sun.star.io.XInputStream with the command parameters that provide access to the stream data.

Another convenient method to create streams is to assemble the URL for the new content where the last part of the path becomes the title of the new stream and obtain a Content object for that URL from the UCB. Then, let the content execute the command "insert". The command fails if you set the command parameter "ReplaceExisting" to false and there is already a stream with the title given by the content's URL.

URL Scheme for PCP Contents

Each PCP content has an identifier corresponding to the following scheme:

 package-URL ::=   "vnd.sun.star.pkg://" orig-URL [ abs-path ]
 abs-path ::=      "/" path-segments
 path-segments ::= segment * ( "/" segment )
 segment ::=       pchar
 pchar ::=         unreserved | escaped | ":" | "@" | "&" | "=" | "+" | "$" | ","
 unreserved ::=    alphanum | mark
 mark ::=          "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")"
 escaped ::= "     %" hex hex
 orig-URL1 ::=     * ( unreserved | escaped | "$" | "," | ";" | ":" | "@" | "&" | "&" | "=" | "+" )

Examples:

vnd.sun.star.pkg://file:%2F%2F%2Fe:%2Fmy.xsw/

The root folder of the package located at file:///e:/my.xsw.

vnd.sun.star.pkg://file:%2F%2F%2Fe:%2Fmy.xsw/Content

The folder or stream named "Content" that is contained in the root folder of the package located at file:///e:/my.xsw.

vnd.sun.star.pkg://file:%2F%2F%2Fe:%2Fmy.xsw/Content%20A

The folder or stream named "Content A" that is contained in the root folder of the package located at file:///e:/my.xsw.

You may use the service com.sun.star.uri.VndSunStarPkgUrlReferenceFactory as a helper to correctly encode the URL.

Commands and Properties

	UCB Type (returned by XContent::getContentType )	Properties	Commands	Interfaces
Stream	application/vnd.sun.star.pkg-stream	[readonly] ContentType [readonly] IsDocument [readonly] IsFolder MediaType [readonly] Size Title Compressed1	getCommandInfo getPropertySetInfo getPropertyValues setPropertyValues insert delete open	XTypeProvider XServiceInfo XComponent XContent XCommandProcessor XPropertiesChangeNotifier XPropertyContainer XPropertySetInfoChangeNotifier XCommandInfoChangeNotifier XChild
Folder	application/vnd.sun.star.pkg-folder	[readonly] ContentType [readonly] IsDocument [readonly] IsFolder MediaType [readonly] Size Title	getCommandInfo getPropertySetInfo getPropertyValues setPropertyValues insert delete open transfer2 flush3	same as PCP Stream, plus XContentCreator

¹ The property Compressed is introduced by package streams to explicitly state if you want a stream to be compressed or not. The default value of this property is determined according to the value suggested by the underlying packager implementation.

² The "transfer" command only transfers PCP folders or streams to other PCP folders. It does not handle contents with a URL scheme other then the PCP-URL scheme.

³ 'flush' is a command introduced by the PCP Folder. It takes a void argument and returns void. This command is used to write unsaved changes to the underlying package file. Note that in the current implementation, PCP contents never flush automatically! Operations which require a flush to become persistent are: "setPropertyValues(Title | MediaType)", "delete", "insert".

Content on this page is licensed under the Public Documentation License (PDL).