Documentation/DevGuide/Universal Content Providers

The Universal Content Providers consist of the:
 * Hierarchy content
 * File content
 * FTP content
 * WebDAV content
 * Package content
 * Help content

The Hierarchy Content Provider
The Hierarchy Content Provider (HCP) implements a content provider for the Universal Content Broker (UCB). It provides access to a persistent, customizable hierarchy of contents.

HCP Contents
The HCP provides three different types of contents: link, folder and root folder.


 * 1) An HCP link is a content that "points" to another UCB content. It is always contained in an HCP Folder. An HCP Link has no children.
 * 2) An HCP folder is a container for other HCP Folders and HCP Links.
 * 3) There is at least one instance of an HCP root folder at a time. All other HCP contents are children of this folder. The HCP root folder contains HCP folders and links. It has the URL vnd.sun.star.hier:/.



Creation of New HCP Content
HCP folders and the HCP root folder implement the interface com.sun.star.ucb.XContentCreator. HCP links and HCP folders support the command "insert" allowing all the HCP folders, as well as the HCP root folder to create new HCP folders and HCP links. To create a new child of an HCP folder:


 * 1) The parent folder creates a new content by calling its   method. The content type for new folders is "application/vnd.sun.star.hier-folder". To create a new link, use the type string " ".
 * 2) Set a title at the new folder or link. The new child executes the " " command that sets the property   to a non-empty value. For a link, set the property   to a non-empty value.
 * 3) The new child, not the parent executes the command " ". This commits the creation process.

URL Scheme for HCP Contents
Each HCP content has an identifier corresponding to the following scheme:

vnd.sun.star.hier:/

where is a hierarchical path of the form

/ /.../

where  is an encoded string according to the URL conventions.

Examples:

vnd.sun.star.hier:/(The URL of the HCP Root Folder)

vnd.sun.star.hier:/Bookmarks/Sun%20Microssystems%20Home%20Page

vnd.sun.star.hier:/Workplace/Printers

Commands and Properties
1 The "transfer" command only transfers HCP-contents to HCP folders. It does not handle contents with a URL scheme other then the HCP-URL-scheme.

The File Content Provider
The File Content Provider (FCP), a content provider for the Universal Content Broker (UCB), provides access to the local file system by providing file content objects that represent a directory or a file in the local file system. The FCP is able to restrict access to the file system to a number of directories shown to the client under configurable aliases.

File Contents
The FCP provides content representing a directory or file in the local file system.


 * 1) A directory contains other directories or files.
 * 2) A file is a container for document data or content. The FCP can not determine the   property of a file content.

Creation of New File Contents
A content representing directories implements the interface com.sun.star.ucb.XContentCreator. A file content object supports the command "insert". To create a new directory or file in a directory:


 * 1) The parent directory creates a new content by calling its   method. The content type for new folders is " ". To create a new file, use the type string " ". A new file content object is the return value.
 * 2) Set a title at the new file content object. The new child executes a " " command that sets the property   to a non-empty value.
 * 3) The new file content object, not the parent, executes the command "insert". This creates the corresponding physical file or directory. For files, supply the implementation of an com.sun.star.io.XInputStream with the command's parameters that provide access to the stream data.

The file URL Scheme
Each file content has an identifier corresponding to the following scheme:

file:///

where  is a hierarchical path of the form

/ /.../.

The first part of  is not required to denote a physically existing directory, but may be remapped to such a directory. If this is done, the FCP refuses file access for any URL whose  is not an element of a predefined list of alias names.

The vnd.sun.star.wfs URL Scheme
In the Sun ONE Webtop, the server-side file system is addressed with vnd.sun.star.wfs URLs. The wfs stands for Webtop File System. The file URL scheme is reserved for a potential client-side file system.



The vnd.sun.star.wfs URL scheme is completely hidden from the FCP, that is, the server side FCP internally works with file URLs, like any other FCP: There is a Remote Access Content Provider (RAP) between the UCB and the FCP. The RAP, among other things, can route requests to another UCP and rewrite URLs. This feature is used so that the client of the UCB works with vnd.sun.star.wfs URLs and the FCP remains unmodified and works with file URLs, with a RAP in between that maps between those two URL schemes.

Except for the different scheme name, the syntax of the vnd.sun.star.wfs URL scheme is exactly the same as the file URL scheme.

The FTP Content Provider
The FTP content provider implements a content provider for the Universal Content Broker (UCB). It provides access to the contents, folders and documents, made available by FTP servers.

FTP Contents
The FTP Content Provider provides three different types of contents: accounts, folders and documents.


 * 1) An FTP account is a content that represents an account for an FTP server. An account is uniquely determined by a combination of a user name and the host name of the FTP server. Anonymous FTP accounts have the string "anonymous" as a user name. An FTP account also represents the base directory, that is, the directory that is selected when the user logs in to the FTP server, and behaves like an FTP folder.
 * 2) An FTP folder is a content that represents a directory on an FTP server. An FTP folder never has a content stream, but it can have FTP folders and FTP documents as children.
 * 3) An FTP document is a content that represents a single file on an FTP server. An FTP document always has a content stream and never has children.



Creation of New FTP Content
FTP accounts and FTP folders implement the interface com.sun.star.ucb.XContentCreator. FTP folders and FTP documents support the command "insert"allowing all the FTP accounts and FTP folders to create new FTP folders and FTP documents. To create a new child of an FTP account or FTP folder:


 * 1) The folder creates a new content by calling its   method. The content type for new folders is " ". To create a new document, use the type string " ".
 * 2) Set a title at the new folder or document. The new child executes a " " command that sets the property   to a non-empty value.
 * 3) The new child, not the parent, executes the command "insert". This commits the creation process. For documents, supply an com.sun.star.io.XInputStream, whose contents are transferred to the FTP server with the command's parameters.

FTP accounts cannot be created the way new FTP folders or FTP documents are created. When you call the FTP content provider's  method with the URL of an FTP account, a content object representing that account, user name and host combination, is automatically created. The same as the URL of an already existing FTP folder or FTP document.

URL Scheme for FTP Contents
Each FTP content has an identifier corresponding to the following scheme (see also RFCs 1738, 2234, 2396, and 2732):

ftp-URL ::=            "ftp://" login *("/" segment) login ::=              [user [":" password] "@"] hostport user ::=               *(escaped / unreserved / "$" / "&" / "+" / "," / ";" / "=") password ::=           *(escaped / unreserved / "$" / "&" / "+" / "," / ";" / "=") hostport ::=           host [":" port] host ::=               incomplete-hostname / hostname / IPv4address incomplete-hostname ::= *(domainlabel ".") domainlabel hostname ::=           *(domainlabel ".") toplabel ["."] domainlabel ::=        alphanum [*(alphanum / "-") alphanum] toplabel ::=           ALPHA [*(alphanum / "-") alphanum] IPv4address ::=        1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT port ::=               *DIGIT segment ::=            *pchar pchar ::=              escaped / unreserved / "$" / "&" / "+" / "," / ":" / "=" / "@" escaped ::=            "%" HEXDIG HEXDIG unreserved ::=         alphanum / mark alphanum ::=           ALPHA / DIGIT mark ::=               "!" / "'" / "(" / ")" / "*" / "-" / "." / "_" / "~"

FTP accounts have a login part, optionally followed by a single slash, and no segments. FTP folders have a login part followed by one or more nonempty segments that must be followed by a slash. FTP documents have a login part followed by one or more nonempty segments that must not be followed by a slash, that is, the FTP content provider uses a potential final slash of a URL to distinguish between folders and documents. Note that this is subject to change in future versions of the provider.

Examples:

ftp://me@ftp.host
 * The account of user "me" on the FTP server "ftp.host".

ftp://ftp.host/pub/doc1.txt
 * A document on an anonymous FTP account.

ftp://me:secret@ftp.host/secret-documents/
 * A folder within the account of user "me" with the password specified directly in the URL. Not recommended.

Commands and Properties
1 The property  is similar to. Some FTP servers not only require authentication through a password, but also through a second token called an "account".

2 The property  is used to override the default directory associated with an FTP account.

3 The " " command only transfers contents within one FTP Account. It cannot transfer contents between different FTP accounts or between the FTP content provider and another content provider.

The WebDAV Content Provider
The WebDAV Content Provider (DCP) implements a content provider for the Universal Content Broker (UCB). An overview is provided at URL http://www.webdav.org. It provides access to WebDAV and standard HTTP servers. The DCP communicates with the server by using the WebDAV protocol that is an extension to the HTTP protocol, or by using the plain HTTP protocol if the server is not WebDAV-enabled.

DCP Contents
The DCP provides two types of content: a folder or document that corresponds to a collection or non-collection, of nodes and leafs, in WebDAV, respectively.


 * 1) A DCP folder is a container for other DCP Folders or Documents.
 * 2) A DCP document is a container for document data or content. The data or content can be any type. A WebDAV server, like an HTTP server, does not mandate what type of data or content is contained within Documents. The type of data or content is defined by the   property which is different from the content type returned from the   method. The   property is mapped to the equivalent WebDAV property and the WebDAV server calculates the value.



Creation of New DCP Contents
DCP folders implement the interface com.sun.star.ucb.XContentCreator. DCP documents and DCP folders support the command " ". To create a new child of a DCP folder:


 * 1) The parent folder creates a new content by calling its   method. The content type for new folders is " ". To create a new document, use the type string " ".
 * 2) Set a title for the new folder or document. The new child executes a " " command that sets the property Title to a non-empty value.
 * 3) The new child, not the parent, executes the command " ". This commits the creation process and makes the newly-created content on the WebDAV server persistent.

Authentication
DAV resources that require authentication are accessed using the interaction handler mechanism of the UCB. The DAV content calls an interaction handler supplied by the client to let it handle an authentication request. The implementation of the interaction handler collects the username or password from a location, for example, a login dialog, and supplies this data as an interaction response.

Property Handling
In addition to the mandatory UCB properties, the DCP supports reading and writing all DAV live and dead properties. Some DAV live properties are mapped in addition to the UCB properties and conversely, that is, DAV:creationdate is mapped to. Adding and removing dead properties is also supported by the implementation of the  interface of a DCP content.

Property Values
The DCP cannot determine the semantics of unknown properties, thus the values of such properties will always be presented as plain text, as they were returned from the server.

Namespaces
The following namespaces are known to the DCP:


 * DAV:
 * http://apache.org/dav/props/

Properties with these namespaces are addressed using a UCB property name which is the concatenation of namespace and name, that is, DAV:getcontentlength.

Dead properties with namespaces that are not well-known to the DCP are addressed using a special UCB property name string, that contains both the namespace and the property name. A special property name string must be similar to the following:

The DCP internally applies the namespace http://ucb.openoffice.org/dav/props/ to all UCB property names that:


 * are not predefined by the UCB API.
 * do not start with a well-known namespace.
 * do not use the special property name string to encode namespace and name.

For example, a client does an. The resulting DAV property has the name, its namespace is http://ucb.openoffice.org/dav/props/. However, the DCP client never sees that namespace, but the client can always use the simple name.

URL Scheme for DCP Contents
Each DCP content has an identifier corresponding to the following scheme:

vnd.sun.star.webdav://host:port/

where  is a hierarchical path of the form

/ /.../

where  is an encoded string according to the URL conventions.

It is also possible to use standard HTTP URLs. The implementation determines if the requested resource is DAV enabled.

Examples:

vnd.sun.star.webdav://localhost/davhome/

vnd.sun.star.webdav://davserver.com/Documents/report.sdw

http://davserver.com/Documents/report.sdw

The Package Content Provider
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.



Creation of New PCP Contents
PCP folders implement the interface com.sun.star.ucb.XContentCreator. PCP streams and PCP folders support the command " ", 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   method. The content type for new folders is " ". To create a new stream, use the type string " ".
 * 2) Set a title for the new folder or stream. The new child executes a " " command that sets the property   to a non-empty value.
 * 3) The new child, not the parent, executes the command " ". 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 " ". The command fails if you set the command parameter " " to  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
1 The property  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.

2 The " " 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.

3 '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: " ", " ", " ".

The Help Content Provider
Currently, the Help Content Provider has the following responsibilities:


 * 1) It is the interface to a search engine that allows a full-text search, including searching specific scopes, such as headers. The range of accessible scopes depends on the indexing process and is currently not changeable after setup.
 * 2) It delivers a keyword index to its clients.
 * 3) The actual helpcontent has media type "text/html," with some images of type "image/gif" embedded. The content is generated from packed xml files that have to be transformed according to a xsl-transformation to produce the resulting XHTML. There is a cascading style sheet used for formatting the XHTML files of media type "text/css".
 * 4) It provides its clients the modules for which help is available.

Help Content Provider Contents
The responsibilities mentioned above are fulfilled by providing different kinds of content objects to the client, namely:


 * a root content giving general information about the installed help files
 * a module content serving as the interface to all search functionality
 * picture and XHTML Contents providing the actual content of the transformed help files and pictures

These contents are described below.

URL Scheme for Help Contents
Each Help content has an identifier corresponding to the following scheme:

URL ::=         scheme delimiter path? query? anchor? scheme ::=      "vnd.sun.star.help" delimiter ::=   "://" | ":/" path ::=        module ( "/" id )? query ::=       "?" key-value-list? keyvaluelist ::= keyvalue ( "&" keyvalue )? keyvalue ::=    key "=" value anchor ::=      "#" anchor-name

Currently, to have a fault-tolerant system, some enveloping set of this is allowed, but without carrying more information.

Examples:

vnd.sun.star.help://?System=WIN&Language=de

vnd.sun.star.help://swriter?System=WIN&Language=de&Query=text&HitCount=120&Scope=Heading

vnd.sun.star.help://portal/4711?System=UNIX&Language=en_US&HelpPrefix=http%3A%2F%2Fportal%2Fportal

Some information must be given in every URL, namely the value of the keys "System"/"Language."

"System" may be one of "UNIX," "WIN," "OS2" and "MAC". This key parameterizes the XSL transformation applied to the help filesand their content changes according to this parameter, and is mandatory only for helpcontents delivering XHTML-files. This may change in the future.

"Language" is coded as ISO639 language code, optionally followed by "-" and ISO3166 country code. Only the language code part of "Language" is used and directly determines the directory, which is relative to the installation path where the help files are found.

In the following, the term "help-directory" is used to determine the directory named "help" in the office/portal installation. The term "help-installation-directory" is used to denote the particular language-dependent subdirectory of the help-directory that contains the actual help files as a packed jar file, the index, the config files and some other items not directly used by the help content provider.

Properties and Commands
Every creatable content can execute the following commands. It is not constrained to a particular URL-scheme:

com::sun::star::ucb::XCommandInfo getCommandInfo com::sun::star::beans::XPropertySetInfo getPropertySetInfo com::sun::star::sdbc::XRow getPropertyValues([in] sequence< com::sun::star::beans::Property > ) void setPropertyValues([in] sequence< com::sun::star::beans::PropertyValue > )

These commands repeat the information given in the following. The available properties and commands are explained by the following URL examples:

Root Content
vnd.sun.star.help://?System=WIN&Language=de

Properties:

Commands:

1 Return value of this command contains the modules available in the particular installation for the requested language. The modules are currently determined by looking for the files in the help-installation-directory matching "*.db", with the exception of the file "picture.db".

Generally, a module corresponds to a particular application, namely, if the writer application is installed, there should be a module " " and so forth.

The written  or the set   (set at  ) makes the cascading style sheet available, which is used to format the XHTML files. Physically, the stream contains the content of the file custom.css in the help-directory of the office or portal installation.

Only the key "Language" is used. Any other key may be set, but is ignored.

Module Content
vnd.sun.star.help://swriter?System=WIN&Language=de&Query=text&HitCount=120&Scope=Heading

Properties:

The help files contain specially marked keywords. The alphabetically sorted list of keywords is contained in the property.

For example, you are looking for keyword, where   is an integer. The help module in which this keyword should be found is determined by the module part of the content URL, "swriter" in our example. Now  contains a list of document ids, where the document belonging to that id contains the keyword string " ".

The location in the XHTML document where this particular keyword refers to is marked by an HTML anchor element:



Here the anchor is given by the string " ".

For our example, the URL of the  document in the swriter module containing the keyword   is determined as vnd.sun.star.help://swriter/docid?System=WIN&Language=de#anchor.

The keys " ", " " and " " have no value with regards to the keywords.

The title of the resulting document is determined directly without having to instantiate the content by the value of " ".

The module contents are also the interface to the search engine. A number of additional keys in the URL are necessary, namely the keys:


 * HitCount
 * Query
 * Scope

The value of Scope should be one of the strings given by the property, currently " " or " ". Leaving the key undefined defaults to a full-text search, Setting it to " " means to search in only the document titles.

There may be any number of  key definitions in the URL. Many  keys determine a query search, first for documents containing all the values, then searching for those containing only subsets of all the values. The requested number of results is determined by the value of the key. The actual returned number may be smaller. The interface to the results returned by the search engine is given by an com.sun.star.ucb.XDynamicResultSet, which is the return value of the command " ":

XHTML Content or Picture Content
vnd.sun.star.help://portal/4711?System=UNIX&Language=en_US&HelpPrefix=http%3A%2F%2Fportal%2Fportal%2F

Properties:

1 The MediaType "image/gif" corresponds to a URL which contains a module part "picture", as opposed to "portal" in the example.

Commands:

1 Returns the transformed XHTML-content, or the gif-content of a.

There is one special document for every module, namely those named start (replace 4711 by start in our example). It identifies the main help page for every module.

There is an additional key named. If set, every link in a generated document pointing to another help-document, either XHTML or image document, is first encoded and then prefixed by the URL-decoded form of the value of this key. This key is only used by Sun One Webtop.