NAME

Config::XPath::Reloadable - a subclass of Config::XPath that supports reloading

DESCRIPTION

This subclass of Config::XPath supports reloading the underlying XML file and updating the containing program's data structures. This is achieved by taking control of the lifetimes of the program's data structures that use it.

Where a simple name=value config file could be reloaded just by reapplying string values, a whole range of new problems occur with the richer layout afforded to XML-based files. New nodes can appear, old nodes can move, change their data, or disappear. All these changes may involve data structure changes within the containing program. To cope with these types of events, callbacks in the form of closures can be registered that are called when various changes happen to the underlying XML data.

As with the non-reloadable parent class, configuration is generally processed by forming a tree of objects which somehow maps onto the XML data tree. The way this is done in this class, is to use the $node parameter passed in to the add and keep event callbacks. This parameter will hold a child Config::XPath::Reloadable object with its XPath context pointing at the corresponding node in the XML data, much like the get_sub_config() method does.

Because of the dynamically-reloadable nature of objects in this class, the get_sub_config() and get_sub_config_list() methods are no longer allowed. They will instead throw exceptions of Config::XPath::Exception type. The event callbacks should be used instead, to obtain subconfigurations.

CONSTRUCTOR

$conf = Config::XPath::Reloadable->new( %args )

This function returns a new instance of a Config::XPath::Reloadable object, initially containing the configuration in the named XML file. The file is closed by the time this method returns, so any changes of the file itself will not be noticed until the reload method is called.

The %args hash takes the following keys

filename => $file

The filename of the XML file to read

$conf = Config::XPath->new( $filename )

This form is now deprecated; please use the filename named argument instead. This form may be removed in some future version.

METHODS

$conf->reload()

This method requests that the configuration object reloads the configuration data that constructed it.

If called on the root object, the XML file that was named in the constructor is reopened and reparsed. The file is re-opened by name, rather than by rereading the filehandle that was opened in the constructor. (This distinction is only of significance for systems that allow open files to be renamed). If called on a child object, the stored XPath data tree is updated from the parent.

In either case, after the data is reloaded, each nodelist stored by the object is reevlauated, by requerying the XML nodeset using the stored XPaths, and the event callbacks being invoked as appropriate.

$conf->associate_nodeset( $listpath, $namepath, %events )

This function associates callback closures with events that happen to a given nodeset in the XML data. When the function is first called, and every time the $conf->reload() method is called, the nodeset given by the XPath string $listpath is obtained. For each node in the set, the value given by $namepath is obtained, by using the get_string() method (so it must be a plain text node or attribute value). The name for each node is then used to determine whether the nodes have been added, or kept since the last time. The add or keep callback is then called as appropriate on each node, in the order they appear in the current XML data.

Finally, the list of nodes that were present last time which no longer exist is determined, and the remove callback called for those, in no particular order.

The signature for each callback is as follows:

 $add->( $name, $node )

 $keep->( $name, $node )

 $remove->( $name )

The $name parameter will contain the string value returned by the $namepath path on each node, and the $node parameter will contain a Config::XPath::Reloadable object reference, with the XPath context at the respective XML data node.

SEE ALSO

• XML::XPath - Perl XML module that implements XPath queries

• Error - Base module for exception-based error handling

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>