Handling Documents

From Apache OpenOffice Wiki
Jump to: navigation, search

Loading Documents

The framework API defines a simple but powerful interface to load viewable components, the com.sun.star.frame.XComponentLoader. This interface is implemented by the globally accessible com.sun.star.frame.Desktop service and also by the com.sun.star.frame.Frame service.

Services Involved in Document Loading

The interface com.sun.star.frame.XComponentLoader has one method:

  com::sun::star::lang::XComponent loadComponentFromURL ( [in] string aURL,
                  [in] string aTargetFrameName,
                  [in] long nSearchFlags,
                  [in] sequence < com::sun::star::beans::PropertyValue aArgs > )

In the following sections the arguments of this call are explained. For a more detailed description of what happens when this call is executed, see the chapter about the filtering process. It explains how the various parameters in the MediaDescriptor allow to detect the type of the file to load, the best filter to load it and the document type that will receive the data. If these parameters were known already and a document should be loaded without becoming attached to a frame, a simple way to load a document exists that bypasses the detection step and the frame creation:

  • create the document by instantiating it with its UNO service name
  • get the com.sun.star.frame.XLoadable interface from the document
  • call its load(…) method that gets the MediaDescriptor as parameter


A call to loadComponentFromURL() receives a sequence of com.sun.star.beans.PropertyValue structs as a parameter, which implements the com.sun.star.document.MediaDescriptor service, consisting of property definitions. In general it describes a resource and how it shall be handled in the particular context where the MediaDescriptor is used. In the context of loading a file it describes the "from where" and the "how". In the content of storing a document using the interface com.sun.star.frame.XStorable it describes the "where to" and the "how". The table below shows the properties defined in the media descriptor.

Some properties are used for loading and saving while others apply to one or the other. If a media descriptor is used, only a few of the members are specified. The others assume default values. Strings default to empty strings in general and interface references default to empty references. For all other properties, the default values are specified in the description column of the table.

Some properties are tagged deprecated. There are old implementations that still use these properties. They are supported, but their use is discouraged. Use the new property that can be found in the description column of the deprecated property.

To develop a UNO component that uses the media descriptor, note that all the properties are under control of the framework API. Never create your own property names for the media descriptor, or name clashes may be induced if the framework in a later version defines a property that uses the same name. Instead, use the ComponentData property to transport document specific information. ComponentData is specified to be an any, therefore it can be a sequence of property values by itself. If you do use it. make an appropriate specification available to users of your component.

Properties of com.sun.star.document.MediaDescriptor
AsTemplate boolean. Setting AsTemplate to true creates a new untitled document out of the loaded document, even if it has no template extension.

Loading a template, that is, a document with a template extension, creates a new untitled document by default, but setting the AsTemplate property to false loads a template for editing.

Author string. Only for storing versions in components supporting versioning: author of version.
CharacterSet string. Defines the character set for document formats that contain single byte characters, if necessary. Which character set names are valid depends on the filter implementation, but with the current filters you can employ the character sets used for the conversion of byte to unicode strings.
Comment string. Only for storing versions in components supporting versioning: comment (description) for stored version.
ComponentData any. This is a parameter that is used for any properties specific for a special office component type.
FileName - deprecated string. Same as URL (added for compatibility reasons)
FilterData any. This is a parameter that is used for any properties specific for a special filter type.
FilterName string. Name of a filter that should be used for loading or storing the component. Names must match the names of the typedetection configuration. Invalid names are ignored. If a name is specified on loading, it will be verified by a filter detection, but in case of doubt it will be preferred.
FilterFlags - deprecated string. For compatibility reasons: same as FilterOptions
FilterOptions string. Some filters need additional parameters. Use only together with property FilterName. Details must be documented by the filter. This is an old format for some filters. If a string is not enough, filters can use the property FilterData.
Hidden boolean. Defines if the loaded component is made visible. If this property is not specified, the component is made visible by default. Prior to OpenOffice.org 2.3 a document could be loaded either "hidden" or "visible", but is wasn't possible to change the visibility of its frame afterwards (by calling setVisible() at the container window) without risking a crash later on. But starting with version 2.3 doing this is safe. Note that a "hidden" frame (or the document it contains) must be closed by the code that created it or switched it to the hidden state.
InputStream com.sun.star.io.XInputStream. Used when loading a document. Reading must be done using this stream. If no stream is provided, the loader creates a stream by itself using the URL, version number, readonly flag, password, or anything required for stream creation, given in the media descriptor.

The model becomes the final owner of the stream and usually holds the reference to lock the file. Therefore, it is not allowed to keep a reference to this InputStream after loading the component.It is useless, because an InputStream is only usable once for reading. Even if it implements the com.sun.star.io.XSeekable interface, do not interfere with the model's reading process. Consider all the objects involved in the loading process as temporary.

InteractionHandler com.sun.star.task.XInteractionHandler. Object implementing the com.sun.star.task.InteractionHandler service that handles exceptional situations where proceeding with the task is impossible without additional information or impossible at all.

Apache OpenOffice provides a default implementation that can handle many situations. If no InteractionHandler is set, a suitable exception is thrown.

It is not allowed to keep a reference to this object, not even in the loaded or stored components' copy of the MediaDescriptor provided by its arguments attribute.

JumpMark string. Jump to a marked position after loading. The office document loaders expect simple strings used like targets in HTML documents.Do not use a leading # character. The meaning of a jump mark depends upon the filter, but in Writer, bookmarks can be used, whereas in Calc cells, cell ranges and named areas are supported.
MediaType (string) string. Type of the medium to load that must match to one of the types defined in the typedetection configuration, otherwise it is ignored. The typedetection configuration can be found in several different xcu files in the config/registry/modules/org/openoffice/TypeDetection folders of the user or share tree. The MediaType is found in the "Type" property. This parameter bypasses the type detection of the desktop environment, so that passing a wrong MediaType causes load failures.
OpenFlags - deprecated string. For compatibility reasons: string that summarizes some flags for loading. The string contains capital letters for the flags:
  • "ReadOnly" - "R"
  • "Preview" - "B"
  • "AsTemplate" - "T"
  • "Hidden" - "H"

Use the corresponding boolean parameters instead.

OpenNewView boolean. Affects the behavior of the component loader when a resource is already loaded. If true, the loader tries to open a new view for a document already loaded. For components supporting multiple views, a second window is opened as if the user clicked Window → New Window. Other components are loaded one more time. Without this property, the default behavior of the loader applies, for example, the loader of the desktop activates a document if the user tries to load it a second time.
Overwrite boolean. For storing only: overwrite existing files with the same name, default is true, so an com.sun.star.io.IOException occurs if the target file already exists. If the default is changed and the file exists, the UCB throws an exception. If the file is loaded through API, this exception is transported to the caller or handled by an interaction handler.
Password string. A password for loading or storing a component, if necessary. If no password is specified, loading of a password protected document fails, storing is done without encryption.
PostData sequence<byte>. HTTP post data to send to a location described by the media descriptor to get a result that is loaded as a component, usually in webforms. Default is: no PostData.
PostString - deprecated string. Same as PostData, but the data is transferred as a string (just for compatibility).
Preview boolean. Setting this to true tells the loaded component that it is loaded as a preview, so that it can optimize loading and viewing for this special purpose. Default is false.
ReadOnly boolean. Tells if a document is to be loaded in a (logical) readonly or in read/write mode. If opening in the desired mode is impossible, an error occurs. By default, the loaded content decides what to do. If its UCB content supports a "readonly" property, the logical open mode depends on that property, otherwise it is read/write.

This property only affects the UI. Opening a document in read only mode does not prevent the component from being modified by API calls, but all modifying functionality in the UI is disabled or removed.


(the wrong spelling is kept for compatibility reasons)

string. A URL describing the environment of the request; for example,. a referrer may be the URL of a document, if a hyperlink inside this document is clicked to load another document. The referrer may be evaluated by the addressed UCB content or the loaded document.

Without a referrer, the processing of URLs that require security checks is denied, for instance macro: URLs.

StatusIndicator com.sun.star.task.XStatusIndicator. Object implementing the com.sun.star.task.XStatusIndicator interface that gives status information, such as text or progress, for the target frame.

Apache OpenOffice provides a default implementation that is retrieved by calling createStatusIndicator() at the frame you load a component into. Usually you do not need this parameter if you do not want to use any other indicator than the one in the status bar of the document window. It is not allowed to keep a reference to this object, not even in the loaded or stored component's copy of the MediaDescriptor provided by its getArgs() method.

TemplateName string. The logical name of a template to load. Together with the TemplateRegionName property this is used instead of the URL of the template. The logical names are the template names you see in the templates dialog.
TemplateRegionName string. See TemplateName. The template region names are the folder names you see in the templates dialog.
Documentation caution.png The possibility to store documents in unpacked way is not currently supported, the "Unpacked" property is just ignored, see Issue 64364 .

boolean. For storing: Setting this to true means that a zip file is not used to save the document. Use a folder instead for UCB contents that support folders, such as file, WebDAV, and ftp. Default is false.

URL string. The location of the component in URL syntax.
Version short. For components supporting versioning: the number of the version to be loaded or saved. Default is zero and means that no version is created or loaded, and the main document is processed.
ViewData any. Data to set a special view state after loading. The type depends on the component and is retrieved from a controller object by its com.sun.star.document.XViewDataSupplier interface. Default is: no ViewData.
ViewId short. For components supporting different views: a number to define the view that should be constructed after loading. Default is: zero, and this should be treated by the component as the default view.
MacroExecutionMode short. How should the macro be executed - the value should be one from com.sun.star.document.MacroExecMode constants group
UpdateDocMode short. Can the document be updated depending on links. The value should be one from com.sun.star.document.UpdateDocMode constant group

The media descriptor used for loading and storing components is passed as an in/out parameter to some methods of objects that participate in the loading or storing process, e.g. the com.sun.star.document.TypeDetection service or a com.sun.star.document.ExtendedTypeDetection service, but also to the filter objcects involved. This enable these objects to add more information to the MediaDescriptor. As an example, if the MediaDescriptor at the beginning just contains a URL. If an object uses this URL to open a stream, it should add this stream to the MediaDescriptor (Stream, InputStream or OutputStream). This prevents that other objects have to create the stream a second time (unfortunate if a remote file is loaded) and it must be reused by later users of the MediaDescriptor.

So if a method gets a MediaDescriptor parameter for loading content it is supposed to do the following:

  • first check for a "Stream" property
  • if it isn't available, check for an "InputStream" property
  • if you find a stream, don't expect that its position is at the beginning of the file, seek to the position where you want to start
  • only if none of these properties is available, try to create a stream by yourself from other properties, e.g. the URL property
  • if the resulting stream is seekable (supports com.sun.star.io.XSeekable, add it to the MediaDescriptor if it is an in/out parameter
  • if the resulting stream is seekable, the MediaDescriptor is an in-parameter and the stream isn't a return value, close it when you are done with it
  • if the stream is not seekable, it is a "one way read" stream and must not be added to the MediaDescriptor.

If it gets a MediaDescriptor parameter for storing content the workflow is:

  • first check for a "Stream" property
  • if it isn't available, check for an "OutputStream" property
  • only if none of these properties is available, try to create a stream by yourself from other properties, e.g. the URL property
  • if the resulting stream is seekable, it can be used for a direct access
  • if the resulting stream isn't seekable, a temporary stream must be created for the storing process and after successful storing all content must be copied to the target stream.

Methods that get the MediaDescriptor as in-parameter only of course can't modify it.

Documentation caution.png It is not allowed to hold a member of this descriptor by reference longer than it is used. This is especially important for the stream properties, except if the ownership of the stream is unquestionable. If it isn't, the stream can't be closed and only releases its file by refcounting down to zero. So if you are in doubt whether your code is the owner of a stream that you have passed to a MediaDescriptor, don't keep any reference to it outside of that descriptor.

URL Parameter

The URL is part of the media descriptor and also an explicit parameter for loadComponentFromURL(). This enables script code to load a document without creating a media descriptor at the cost of code redundancy. The URL parameter of loadComponentFromURL() overrides a possible URL property passed in the media descriptor. Aside from valid URLs that describe an existing file, the following URLs are used to open viewable components in Apache OpenOffice:

Component URL
Writer private:factory/swriter
Calc private:factory/scalc
Draw private:factory/sdraw
Impress private:factory/simpress
Database .component:DB/QueryDesign


Bibliography .component:Bibliography/View1

Such empty documents also can created without a frame:

Target Frame

The URL and media descriptor loadComponentFromURL() have two additional arguments, the target frame name and search flags. The method loadComponentFromURL() looks for a frame in the frame hierarchy and loads the component into the frame it finds. It uses the same algorithm as findFrame() at the com.sun.star.frame.XFrame interface, described in section Frame Hierarchies.

The target frame name is a reserved name starting with an underscore or arbitrary name. The reserved names denote frequently used frames in the frame hierarchy or special functions, whereas an arbitrary name is searched recursively. If a reserved name is used, the search flags are ignored and set to 0. The following reserved names are supported:


Returns the frame itself. The same as with an empty target frame name. This means to search for a frame you already have, but it is legal.


Returns the top frame of the called frame .,The first frame where isTop() returns true when traveling up the hierarchy. If the starting frame does not have a parent frame, the call is treated as a search for "_self". This behavior is compatible to the frame targeting in a web browser.


Returns the next frame above in the frame hierarchy. If the starting frame does not have a parent frame, the call is treated as a search for "_self". This behavior is compatible to the frame targeting in a web browser.


Creates a new top-level frame as a child frame of the desktop. If the called frame is not part of the desktop hierarchy, this call fails. Using the "_blank" target loads open documents again that result in a read-only document, depending on the UCB content provider for the component. If loading is done as a result of a user action, this becomes confusing to the users, therefore the "_default" target is recommended in calls from a user interface, instead of "_blank". Refer to the next section for a discussion about the _default target.


Similar to "_blank", but the implementation defines further behavior that has to be documented by the implementer. The com.sun.star.frame.XComponentLoader implemented at the desktop object shows the following default behavior.
First, it checks if the component to load is already loaded in another top-level frame. If this is the case, the frame is activated and brought to the foreground. When the OpenNewView property is set to true in the media descriptor, the loader creates a second controller to show another view for the loaded document. For components supporting this, a second window is opened as if the user clicked Window - New Window. The other components are loaded one more time, as if the "_blank" target had been used. Currently, almost all office components implementing com.sun.star.frame.XModel have multiple controllers, except for HTML and writer documents in the online view. The database and bibliography components have no model, therefore they cannot open a second view at all and OpenNewView leads to an exception with them.
Next, the loader checks if the active frame contains an unmodified, empty document of the same document type as the component that is being loaded. If so, the component is loaded into that frame, replacing the empty document, otherwise a new top-level frame is created similar to a call with "_blank".

Names starting with an underscore must not be used as real names for a frame.

If the given frame name is an arbitrary string, the loader searches for this frame in the frame hierarchy. The search is done in the following order: self, children, siblings, parent, create if not found. Each of these search steps can be skipped by deleting it from the com.sun.star.frame.FrameSearchFlag bit vector:

Constants in com.sun.star.frame.FrameSearchFlag group
SELF search current frame
CHILDREN search children recursively
SIBLINGS search frames on the same level
PARENT search frame above the current frame in the hierarchy
CREATE create new frame if not found
TASKS do not stop searching when a top frame is reached, but continue with other top frames

A typical case for a named frame is a situation where a frame is needed to be reused for subsequent loading of components, for example, a frame attached to a preview window or a docked frame, such as the frame in OpenOffice.org that opens the address book when the F4 key is pressed.

The frame names "_self", "_top" and "_parent" define a frame target relative to a starting frame. They can only be used if the component loader interface finds the frame and the setComponent() can be used with the frame. The desktop frame is the root, therefore it does not have a top and parent frame. The component loader of the desktop cannot use these names, because the desktop refuses to have a component set into it. However, if a frame implemented com.sun.star.frame.XComponentLoader, these names could be used.

Documentation note.png OpenOffice.org 1.0.x didn't have a frame implementation that supports XComponentLoader.

The reserved frame names are also used as a targeting mechanism in the dispatch framework with regard to as far as the relative frame names being resolved. For additional information, see chapter Using the Dispatch Framework.

The example below creates a frame, and uses the target frame and search flag parameters of loadComponentFromURL() to load a document into it.

  // Conditions: sURL = "private:factory/swriter" 
  // xSMGR = m_xServiceManager 
  // xFrame = reference to a frame
  // lProperties[] = new com.sun.star.beans.PropertyValue[0]
  // First prepare frame for loading. 
  // We must adress it inside the frame tree without any complications. 
  // To do so we set an unambiguous name and use it later. 
  // Don't forget to reset the name to the original name after that.
  String sOldName = xFrame.getName(); 
  String sTarget = "odk_officedev_desk"; 
  // Get access to the global component loader of the office 
  // for synchronous loading of documents. 
  com.sun.star.frame.XComponentLoader xLoader = 
  // Load the document into the target frame by using our unambigous name 
  // and special search flags. 
  xDocument = xLoader.loadComponentFromURL( 
    sURL, sTarget, com.sun.star.frame.FrameSearchFlag.CHILDREN, lProperties); 
  // dont forget to restore old frame name ... 

The loadComponentFromURL() call returns a reference to a com.sun.star.lang.XComponent interface. The object belonging to this interface depends on the loaded component. If it is a component that only provides a component window, but not a controller, the returned component is this window. If it is an office component that provides a controller, the returned component is the controller or its model, if these is one. All Writer, Calc, Draw, Impress or Math documents in Apache OpenOffice support a model, therefore the loadComponentFromURL() call returns it. The database and bibliography components however, return a controller, because they do not have a model.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages