Language:

The Free and Open Productivity Suite
Apache OpenOffice 4.1.4 released

Developer's Guide

API

SDK

Tips 'n' Tricks

Miscellaneous


:: com :: sun :: star :: configuration :: backend ::

interface XUpdateHandler
Description
receives a description of a configuration update or layer as a sequence of events.
Since
OOo 1.1.2

Methods' Summary
startUpdate receives notification that a update or description is started.  
endUpdate receives notification that the current update description is complete.  
modifyNode receives notification that a modification of a node is started.  
addOrReplaceNode receives notification that a node is started as a new item.  
addOrReplaceNodeFromTemplate receives notification that a node is started as a new item based on a particular template.  
endNode receives notification that a node modification is complete.  
removeNode receives notification that an item is to be dropped from a set.  
modifyProperty receives notification that modification of an existing property is started. .  
setPropertyValue receives notification about a change to the value of the current property.  
setPropertyValueForLocale receives notification about a change to the value of the current property for a specific locale.  
resetPropertyValue receives notification that the value of the current property should be reset to its default.  
resetPropertyValueForLocale receives notification that the value of the current property for a specific locale should be reset to its default.  
endProperty receives notification that a property modification is complete.  
resetProperty receives notification that a property is reset to its default state.  
addOrReplaceProperty receives notification that a property having a value of void is added to the current node.  
addOrReplacePropertyWithValue receives notification that a property having a non-NULL value is added to the current node.  
removeProperty receives notification that a property is dropped from the current node.  
Methods' Details
startUpdate
void
startUpdate()
raises( MalformedDataException,
::com::sun::star::lang::IllegalAccessException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification that a update or description is started.
Throws
com::sun::star::configuration::backend::MalformedDataException if the update already was started
Throws
com::sun::star::lang::IllegalAccessException if the target layer is read-only

Some implementations can only detect this when executing XUpdateHandler::endUpdate()

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
endUpdate
void
endUpdate()
raises( MalformedDataException,
::com::sun::star::lang::IllegalAccessException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification that the current update description is complete.

Must match a previous call to XUpdateHandler::startUpdate().

Throws
com::sun::star::configuration::backend::MalformedDataException
  • if no update is started at all
  • if invalid data is detected in the update
  • if there is an unfinished subnode in progress
  • if the update tries to change read-only data

Not every implementation can detect each condition

Throws
com::sun::star::lang::IllegalAccessException if the target layer is read-only
Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
modifyNode
void
modifyNode( [in] string  aName,
[in] short  aAttributes,
[in] short  aAttributeMask,
[in] boolean  bReset )
raises( MalformedDataException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification that a modification of a node is started.

Subsequent calls describe changes to properties and items or members of the node until a matching call to XUpdateHandler::endNode() is encountered.

Parameter aName
specifies the name of the node.
Parameter aAttributes
specifies attribute values to be applied to the node in the current layer.

The value is a combination of NodeAttribute flags.

Only attributes which are selected in aAttributeMask are changed.

Parameter aAttributeMask
specifies which attributes should be changed for the node.

The value is a combination of NodeAttribute flags.

Parameter bReset
if true, specifies that the node should be reset to its default state as given by lower layers and the schema or template prior to applying the changes.
Throws
com::sun::star::configuration::backend::MalformedDataException
  • if there isn't an update in progress at all
  • if a node is not valid in this place
  • if there already was a change to that node
  • if there is no node with that name
  • if the node is read-only
  • if the name is not a valid node name
  • if the attributes or mask are not valid for the node

Not every implementation can detect each condition

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
See also
NodeAttribute
addOrReplaceNode
void
addOrReplaceNode( [in] string  aName,
[in] short  aAttributes )
raises( MalformedDataException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification that a node is started as a new item.

The current node must be a set and a preexisting item (if any) must be removeable.

The new item will be created from the default template of the set.

Subsequent calls describe the difference from the template of properties, items or members of the node until a matching call to XUpdateHandler::endNode() is encountered.

Parameter aName
specifies the name of the new item.
Parameter aAttributes
specifies attribute values to be applied to the new node.

The value is a combination of NodeAttribute flags. Note that NodeAttribute::FUSE has an impact on the semantics of this method.

Throws
com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a set node in progress currently
  • if there already was a change to an item of that name
  • if the template for the new node is not found
  • if an item of that name exists and is not removeable
  • if the name is not a valid item name
  • if the attributes are not valid for the node

Not every implementation can detect each condition

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
See also
NodeAttribute
addOrReplaceNodeFromTemplate
void
addOrReplaceNodeFromTemplate( [in] string  aName,
[in] short  aAttributes,
[in] TemplateIdentifier  aTemplate )
raises( MalformedDataException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification that a node is started as a new item based on a particular template.

The current node must be a set and a preexisting item (if any) must be removeable.

Subsequent calls describe the difference from the template of properties or members of the node until a matching call to XUpdateHandler::endNode() is encountered.

Parameter aName
specifies the name of the item.
Parameter aTemplate
specifies the template to use for the new node
Parameter aAttributes
specifies attribute values to be applied to the new node.

The value is a combination of NodeAttribute flags. Note that NodeAttribute::FUSE has an impact on the semantics of this method.

Throws
com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a set node in progress currently
  • if there already was a change to an item of that name
  • if the template for the new node is not found
  • if an item of that name exists and is not removeable
  • if the name is not a valid item name
  • if the template is not a valid item type for the containing set
  • if the attributes are not valid for the node

Not every implementation can detect each condition

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
See also
NodeAttribute
endNode
void
endNode()
raises( MalformedDataException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification that a node modification is complete.

Must match the last open call to XUpdateHandler::modifyNode(), XUpdateHandler::addOrReplaceNode() or XUpdateHandler::addOrReplaceNodeFromTemplate().

Throws
com::sun::star::configuration::backend::MalformedDataException
  • if invalid data is detected in the node
  • if no node is started at all

Not every implementation can detect each condition

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
removeNode
void
removeNode( [in] string  aName )
raises( MalformedDataException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification that an item is to be dropped from a set.

The current node must be a set and the item must be removeable.

Parameter aName
specifies the name of the node.
Throws
com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a set node in progress currently
  • if there already was a change to a node of that name
  • if there is no item with that name
  • if the item is not removeable
  • if the name is not a valid node name

Not every implementation can detect each condition

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
modifyProperty
void
modifyProperty( [in] string  aName,
[in] short  aAttributes,
[in] short  aAttributeMask,
[in] type  aType )
raises( MalformedDataException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification that modification of an existing property is started. .

Subsequent calls describe changes to the value(s) of the property until a matching call to XUpdateHandler::endProperty() is encountered.

Parameter aName
specifies the name of the property.
Parameter aAttributes
specifies new attributes of the property.

The value is a combination of NodeAttribute flags.

Only attributes which are selected in aAttributeMask are changed.

NodeAttribute::MANDATORY need not be set and can't be removed, as dynamic properties always are mandatory in subsequent layers.

Parameter aAttributeMask
specifies which attributes should be changed for the property.

The value is a combination of NodeAttribute flags.

Parameter aType
specifies the type of the property.

A void type can be used to signify that the type is unknown and should not be recorded.

Throws
com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a group or extensible node in progress currently
  • if there already was a change to a property of that name
  • if there is no property with that name
  • if the property is read-only
  • if the name is not a valid property name
  • if the attributes are not valid for the property

Not every implementation can detect each condition

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
See also
NodeAttribute
setPropertyValue
void
setPropertyValue( [in] any  aValue )
raises( MalformedDataException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification about a change to the value of the current property.
Parameter aValue
specifies the new value of the property.

The value must match the type of the existing property. If the property does not have the SchemaAttribute::REQUIRED flag set, the value can be void.

Throws
com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a property modification in progress currently
  • if there already was a change to this value
  • if the type of the value is not an allowed type
  • if the value is not valid for the property

Not every implementation can detect each condition

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
See also
NodeAttribute
setPropertyValueForLocale
void
setPropertyValueForLocale( [in] any  aValue,
[in] string  aLocale )
raises( MalformedDataException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification about a change to the value of the current property for a specific locale.
Parameter aValue
specifies the new value of the property for the given locale.

The value must match the type of the existing property. If the property does not have the SchemaAttribute::REQUIRED flag set, the value can be void.

Parameter aLocale
specifies the locale that the new value applies to.
Throws
com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a property modification in progress currently
  • if the property is not localizable
  • if there already was a change to this value
  • if the type of the value is not an allowed type
  • if the value is not valid for the property
  • if the locale is not a valid locale name

Not every implementation can detect each condition

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
See also
NodeAttribute
resetPropertyValue
void
resetPropertyValue()
raises( MalformedDataException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification that the value of the current property should be reset to its default.
Throws
com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a property modification in progress currently
  • if there already was a change to this value

Not every implementation can detect each condition

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
See also
NodeAttribute
resetPropertyValueForLocale
void
resetPropertyValueForLocale( [in] string  aLocale )
raises( MalformedDataException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification that the value of the current property for a specific locale should be reset to its default.
Parameter aLocale
specifies the locale the change applies to.
Throws
com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a property modification in progress currently
  • if the property is not localizable
  • if there already was a change to this value
  • if the locale is not a valid locale name

Not every implementation can detect each condition

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
See also
NodeAttribute
endProperty
void
endProperty()
raises( MalformedDataException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification that a property modification is complete.

Must match the last open call to XUpdateHandler::modifyProperty().

Throws
com::sun::star::configuration::backend::MalformedDataException
  • if invalid data is detected in the property
  • if no property is started at all

Not every implementation can detect each condition

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
resetProperty
void
resetProperty( [in] string  aName )
raises( MalformedDataException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification that a property is reset to its default state.
Parameter aName
specifies the name of the property.
Throws
com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a group or extensible node in progress currently
  • if there already was a change to a property of that name
  • if there is no property with that name, or if the property has no default
  • if the property is read-only
  • if the name is not a valid property name

Not every implementation can detect each condition

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
See also
NodeAttribute
addOrReplaceProperty
void
addOrReplaceProperty( [in] string  aName,
[in] short  aAttributes,
[in] type  aType )
raises( MalformedDataException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification that a property having a value of void is added to the current node.

The current node must be extensible and a preexisting property (if any) must be removeable in this layer.

Parameter aName
specifies the name of the new property.
Parameter aAttributes
specifies the attributes of the new property.

The value is a combination of NodeAttribute flags and may also contain the SchemaAttribute::REQUIRED flag.

NodeAttribute::MANDATORY need not be set, as dynamic properties always are mandatory in subsequent layers.

Parameter aType
specifies the type of the new property.
Throws
com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a group or extensible node in progress currently
  • if there already was a change to a property of that name
  • if a property of that name exists and is not removeable
  • if the specified type is not allowed
  • if the name is not a valid property name
  • if the attributes are not valid for the property

Not every implementation can detect each condition

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
See also
SchemaAttribute
addOrReplacePropertyWithValue
void
addOrReplacePropertyWithValue( [in] string  aName,
[in] short  aAttributes,
[in] any  aValue )
raises( MalformedDataException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification that a property having a non-NULL value is added to the current node.

The current node must be extensible and a preexisting property (if any) must be removeable in this layer.

Parameter aName
specifies the name of the new property.
Parameter aAttributes
specifies the attributes of the new property.

The value is a combination of NodeAttribute flags and may also contain the SchemaAttribute::REQUIRED flag.

NodeAttribute::MANDATORY need not be set, as dynamic properties always are mandatory in subsequent layers.

Parameter aValue
specifies the value of the new property.

The value also determines the type. Therefore the value must not be void.

Throws
com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a group or extensible node in progress currently
  • if there already was a change to a property of that name
  • if a property of that name exists and is not removeable
  • if the type of the value is not an allowed type, or if the value is void
  • if the name is not a valid property name
  • if the attributes are not valid for the property

Not every implementation can detect each condition

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
See also
SchemaAttribute
removeProperty
void
removeProperty( [in] string  aName )
raises( MalformedDataException,
::com::sun::star::lang::WrappedTargetException );

Description
receives notification that a property is dropped from the current node.

The current node must be extensible and the property removeable.

Parameter aName
specifies the name of the property.
Throws
com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a group or extensible node in progress currently
  • if there is no property with that name
  • if the property is not removeable
  • if the name is not a valid node name

Not every implementation can detect each condition

Throws
com::sun::star::lang::WrappedTargetException if an error occurs processing the event.
Top of Page

Apache Software Foundation

Copyright & License | Privacy | Contact Us | Donate | Thanks

Apache and the Apache feather logo are trademarks of The Apache Software Foundation. OpenOffice, OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.