Potential performance concerns with oxy_url() and oxy_xpath() ?

[csun]

Hi,

I notice that if the CSS custom funtions like oxy_url() and oxy_xpath() are used for resolving links in DocBook5, something like:

Code: Select all

link:empty{

content:oxy_xpath(oxy_concat('doc("', oxy_url('${pdu}/', 'a.xml'), '")//@val')) !important;

}

it works, but apparently when it is turned on Oxygen would work noticeably slower. E.g. if I open a Docbook5 XML that contains many links, then turn on the link resolution, Oxygen can usually become unresponsive for even a few minutes.

Is it a known issue that oxy_url() and oxy_xpath() might take a bit long to process? If that’s the case, with Oxygen XML Editor 19, do we have the option of creating our own CSS custom functions to use in a framework, or do we need to create a whole new plugin to make link resolution faster?

Any suggestions are much appreciated.

[Radu]

Hi,

Indeed you should avoid using oxy_xpath or at least change the value of the "evaluate" parameter:

https://www.oxygenxml.com/doc/versions/ ... ction.html

to avoid evaluating the XPath very often like:

Code: Select all

content:oxy_xpath(oxy_concat('doc("', oxy_url('${pdu}/', 'a.xml'), '")//@val'), evaluate, static) !important;

To avoid oxy_xpath completely we have a CSS extension function called oxy_link-text():

https://www.oxygenxml.com/doc/versions/ ... -text.html

this function will call a Java-based API extension of an interface in our Author SDK, you can search for "LinkTextResolver" here:

https://www.oxygenxml.com/doc/versions/ ... undle.html

Our Author SDK which can be used to compile Java extensions can be found here:

https://www.oxygenxml.com/oxygen_sdk.html

Regards,
Radu

[csun]

Hi Radu,
Thanks for your help! Sorry I didn't reply sooner.

Yes, it makes perfect sense that avoiding the use of oxy_xpath() and doc() could give us a boost in Oxygen performance. I would like to try using oxy_link-text() for populating the value of CSS "content" property. Could you help with a few more questions?

To avoid the I/O operations with doc(), we may need a way to cache the opened file data in the memory (or elsewhere). Does oxy_link-test() come with the option of caching the data? Or, could you let me know where I can find the source code for DocbookLinkTextResolver - hopefully I can build a customized function by calling DocbookLinkTextResolver, and perform the caching with this Java extension?

Meanwhile, it seems that oxy_link-text() cannot be used on the CSS "link" property. Is there a function that is analogous to oxy_link-text(), but can be used in the following case, for replacing the usage of oxy_xpath() and doc() ?

Code: Select all

*[xlink|href]:before{

    link: oxy_url('${pdu}', oxy_xpath(oxy_concat('doc("', oxy_url('${targets}/', 'b.xml'), '")//@Href'), evaluate, static)) !important;

}

Thanks!
Charles

[alex_jitianu]

Hi,

My colleague Radu asked me to help you with these extensions.

1. The first step is to define a custom anchor. On the link property you should specify an URL with an anchor that contains everything needed to compute, later on, the target:

Code: Select all

.../b.xml#attrName=val

You will need a custom Link Target Element Finder that will know how to use this anchor and identify the target element.

2. Since you are using a custom anchor, you will also need a customized version of the DocbookLinkTextResolver that, again, will know how to interpret the special anchor

To crete these extensions I suggest:
1. You should download the Oxygen SDK. Afterwards, focus on the submodule called oxygen-sample-framework. After executing a mvn generate-resources you will notice a samples directory which will contain the DocbookLinkTextResolver code.
2. Also add the [OXYGEN_INSTALL_DIR]\frameworks\docbook\docbook.jar to the class path of the project.
3. Create a class that extends ro.sync.ecss.extensions.docbook.DocBook5ExtensionsBundle and overwrites the methods:
3.1 ro.sync.ecss.extensions.api.ExtensionsBundle#createLinkTextResolver() and returns the extension of DocbookLinkTextResolver that handles the special anchor.
3.2 and ro.sync.ecss.extensions.api.ExtensionsBundle#createElementLocatorProvider() and returns an extension of ro.sync.ecss.extensions.commons.DefaultElementLocatorProvider that handles the special anchor

If you take a look at the DocbookLinkTextResolver code you will notice that it actually keeps a cache. Please let me know how it goes.


Best regards,
Alex

[csun]

Hi Alex and Radu,

Excellent, the information is really helpful. Thanks again.

Do I understand correctly that even though DocbookLinkTextResolver keeps a cache, when loading the DocBook XML that contains links, the performance would be identical whether we use DocbookLinkTextResolver or doc() and oxy_xpath() ? My guess is that we would always need to parse the targetset (i.e. ${targets}), and the amount of I/O operations are probably the same at this stage, even if we use DocbookLinkTextResolver .

Is there a way to parse the targetset where it doesn't negatively affect Oxygen's performance? For example, I notice that if we insert a link using the OLink dialog box and load the targetset with the Targetset URL drop-down menu, Oxygen is able to respond rather quickly. In this operation, is it parsing the targetset in a manner that is different from what is done during link resolution?

Thanks,
Charles

[alex_jitianu]

Hi Charles,

My guess is that we would always need to parse the targetset (i.e. ${targets}), and the amount of I/O operations are probably the same at this stage, even if we use DocbookLinkTextResolver.

The current cache maps a node to the resolved linked text. If you have a document that contains many link nodes (like you mentioned in the first post) to the same ${targets}, Oxygen will still parse the ${targets} document once for every link. Afterwards, the cache will kick in and there will be no performance penalties. In your customization of an DocbookLinkTextResolver you can keep an additional cache, make sure you only parse ${targets} once and keep it somehow in memory (Maybe a DOM model)

Best regards,
Alex

[csun]

Thanks Alex!

If you have a document that contains many link nodes (like you mentioned in the first post) to the same ${targets}, Oxygen will still parse the ${targets} document once for every link.

In your customization of an DocbookLinkTextResolver you can keep an additional cache, make sure you only parse ${targets} once and keep it somehow in memory (Maybe a DOM model)

Before going ahead with customizing the DocbookLinkTextResolver, may I ask - will Syncro Soft plan to develop a similar enhancement? It seems that the performance issue with link resolution could be encountered by most DocBook writers. Thanks.

[alex_jitianu]

Hi Charles,

Currently, Oxygen handles just internal references (references to other elements that are in the scope of the current document, ID-based) so the caching inside DocbookLinkTextResolver doesn't take have to take care of olink references. It is something that we should handle as well, so I will add an issue for that, but it is not a trivial change. It will definitely not be available in version 20 because there is little time left until its release.

If you have some sample files, it would be great if you can send them to our email address (support@oxygenxml.com). This way, when we start working on the feature, we can make sure it handles your case as well. Is it an use case similar with the one in the Inserting an olink in DocBook Documents or is it a bit different? From your examples above, it is not entirely clear if you are using link elements or not...

Best regards,
Alex

[csun]

Hi Alex,

Sorry for my delayed reply - and thanks for adding an issue for the enhancement.

Our use case is similar to the one described in Inserting an olink in DocBook Documents, but we have some customization on top of it. I will send some sample files to your email address.

Thanks!
Charles

[csun]

Hi again,
Can I ask some more questions, about deploying the customization discussed earlier (i.e. keeping a cache for visited targetsets):
- Would it work the best if I make it a plugin, or would you recommend some other approaches?
- To deploy the customization, should I follow the instructions on those pages?
https://www.oxygenxml.com/doc/versions/ ... ddons.html
https://www.oxygenxml.com/doc/versions/ ... ugins.html

Thanks,
Charles

[alex_jitianu]

Hi Charles,

You are using a framework level API, {{ro.sync.ecss.extensions.api.link.LinkTextResolver}}, which means that a plugin is not an option. I recommend extending the built-in Docbook 5 framework because it will make the updating to future built-in frameworks much easier. In this extension you can change the Extensions Bundle (in the Extensions tab) from the default ro.sync.ecss.extensions.docbook.DocBook5ExtensionsBundle to one that extends it and creates a custom {{ro.sync.ecss.extensions.api.link.LinkTextResolver}}.

For deployment, there are a couple of options. Packing the framework as an add-on is a good choice.
Best regards,
Alex

[csun]

Hi,

Thanks Alex, for confirming that plugin is not an option.

Then most likely we'll go with this approach when deploying the extended framework,
"Distribute the extended framework along with a project", as mentioned in this page: https://www.oxygenxml.com/doc/versions/ ... aring.html

After packing the framework as an add-on, do I understand correctly that I should do the following to put it in use in the extended framework?
1. In Oxygen -> framework configuration, in the Classpath tab, add a reference to the Jar file (i.e. the packed framework);
2. Perhaps go to Extensions tab, and choose {{ro.sync.ecss.extensions.api.link.LinkTextResolver}} for "Link target element finder" under "Individual extensions"?

Best regards,
Charles

[alex_jitianu]

Hi Charles,

If you decide to distribute the framework inside a project then you don't need to pack it as an add-on at all.

do I understand correctly that I should do the following to put it in use in the extended framework?
1. In Oxygen -> framework configuration, in the Classpath tab, add a reference to the Jar file (i.e. the packed framework);
2. Perhaps go to Extensions tab, and choose {{ro.sync.ecss.extensions.api.link.LinkTextResolver}} for "Link target element finder" under "Individual extensions"?

Yes, you must do this in your extended framework so ensure that the custom link resolver will be used.

When you set up the project, you do something like this:
1. On your local drive, create a directory (with full write access) that contains the project files and a custom_frameworks folder with your extended framework inside.
2. Start Oxygen XML Editor, go to the Project view and create a project. Save it in the newly created directory.
In the Document Type Association > Locations preferences page, select Project Options at the bottom of the page.
In the Additional frameworks directories list, add an entry like this: ${pd}/custom_frameworks.

Your framework should reside inside this custom_frameworks folder. You'll probably have a structure like:

Code: Select all

project_Folder

-custom_frameworks

--dockook5_extension

----dockook5_extension.framework

----link_text_resolver.jar

Best regards,
Alex

[csun]

It seems like that somehow I didn't reply to the thread... Just wanted to say that I really appreciated the help!

[csun]

The current cache maps a node to the resolved linked text. If you have a document that contains many link nodes (like you mentioned in the first post) to the same ${targets}, Oxygen will still parse the ${targets} document once for every link. Afterwards, the cache will kick in and there will be no performance penalties. In your customization of an DocbookLinkTextResolver you can keep an additional cache, make sure you only parse ${targets} once and keep it somehow in memory (Maybe a DOM model)

Hi again,

Now I am working with the Oxygen SDK version 20 to implement the customization discussed here, i.e. adding an additional cache in DocbookLinkTextResolver so that it only parses ${targets} once and keep it in memory.

However, I don't seem to find the classes discussed earlier in the context of SDK version 19, i.e.

3. Create a class that extends ro.sync.ecss.extensions.docbook.DocBook5ExtensionsBundle and overwrites the methods:
3.1 ro.sync.ecss.extensions.api.ExtensionsBundle#createLinkTextResolver() and returns the extension of DocbookLinkTextResolver that handles the special anchor.
3.2 and ro.sync.ecss.extensions.api.ExtensionsBundle#createElementLocatorProvider() and returns an extension of ro.sync.ecss.extensions.commons.DefaultElementLocatorProvider that handles the special anchor

Specifically, I don't find any code for ro.sync.ecss.extensions.api.ExtensionsBundle. Has anything changed between versions 19.1 and 20, so that it has been renamed or moved to other places?

Thanks,
Charles

[alex_jitianu]

Hi,

You should download the Oxygen SDK. In the submodule called oxygen-sample-framework, after executing a mvn generate-resources, you will notice a samples directory which will contain the DocbookLinkTextResolver code as well as ro.sync.ecss.extensions.docbook.DocBook5ExtensionsBundle. ro.sync.ecss.extensions.api.ExtensionsBundle is not present there but, if you have the sample Maven project, then Maven will bring the source code for that API as well.

2. Also add the [OXYGEN_INSTALL_DIR]\frameworks\docbook\docbook.jar to the class path of the project.

After you do this you will be able to extend ro.sync.ecss.extensions.docbook.DocBook5ExtensionsBundle because it will be present in the classpath.

Anyway, the source code for the Docbook extensions, the one also available at oxygen-sample-framework/samples/Oxygen Default Frameworks, can be downloaded directly from the Maven repository.

Best regards,
Alex

[csun]

Hi Alex,

Yes, I see the samples directory, as well as DocbookLinkTextResolver.java and DocBook5ExtensionsBundle.java in their respective sub-folders now.

ro.sync.ecss.extensions.api.ExtensionsBundle is not present there but, if you have the sample Maven project, then Maven will bring the source code for that API as well.

Sorry I am still a bit confused about this... When Maven brings the source code for that API, should I expect to find the source code somewhere from within the Eclipse interface? Or should I just refer to the API doc https://www.oxygenxml.com/InstData/Edit ... undle.html , when creating a class that extends ro.sync.ecss.extensions.docbook.DocBook5ExtensionsBundle and overwriting the following methods?
- ro.sync.ecss.extensions.api.ExtensionsBundle#createLinkTextResolver()
- ro.sync.ecss.extensions.api.ExtensionsBundle#createElementLocatorProvider()

Another question is, after I create the new class, is this new class all that I need to pack into a .jar file (and later deploy with the custom framework)?

Thanks,
Charles

[alex_jitianu]

Hi Charles,

When we publish our API as Maven artifacts we also pack their source code. ro.sync.ecss.extensions.api.ExtensionsBundle is part of the API so you will have access to its source code without having to do anything in particular. So if you invoke the Eclipse action Open Type (Ctrl+Shift+T) and type ExtensionsBundle then you will be able to open it and see its source code.

DocBook5ExtensionsBundle is not part of the API so Maven will not bring its source code. That's why we make its source code available in a subfolder of the project.

Another question is, after I create the new class, is this new class all that I need to pack into a .jar file (and later deploy with the custom framework)?

Besides this jar you will also need docbook.jar which contains the Docbook specific extensions that we've developed. But this JAR is probably already there, in the custom Docbook framework, since it was created starting from the built-in Docbook framework.

So all you have to do is to copy your JAR in the custom framework followed by a bit of setup (luckily you only have to do this setup once):
1. Start oxygen, go to Options->Preferences... on page Document type Associations and edit the custom framework
2. On the Classpath tab, add an entry with your new JAR. You should use the ${framework} variable to ensure portability.
3. On the Extensions tab, on the Extensions bundle section, click Choose and select you custom extension bundle.

Best regards,
Alex

[csun]

Hi Alex,
Thanks for the clarification! This is very helpful.

Charles

[csun]

Hi again Alex,

I've run into a few more questions; can you please help again?

1. The first step is to define a custom anchor. On the link property you should specify an URL with an anchor that contains everything needed to compute, later on, the target

Do you mean that in the CSS, I should write something like:

Code: Select all

*[xlink|href]:before{

    link: oxy_url(${targets}/b.xml#myAnchor);

 }

 

*[xlink|href]:empty{

    content: oxy_link-text(${targets}/b.xml#myAnchor); /* This doesn't look right to me, but how should oxy_link-text handle the custom anchor? */

 }

Then for the custom Link Target Element Finder, is there a way that the Java code can access the value of ${targets}, which is a custom editor variable?

For the customized version of DocbookLinkTextResolver to handle the custom anchor: in my CSS code above, I guess my way of passing in the custom anchor to oxy_link-text() isn't correct. However, I don't seem to find any documentation regarding how the current DocbookLinkTextResolver can receive any parameters that are passed in from oxy_link-text() , if parameters can be passed in at all. Can you shed some light on this too?

Thanks,
Charles

[alex_jitianu]

Hi Charles,

I guess that the ${targets} variable is defined inside preferences, right?

oxy_link-text() doesn't support any parameters so you can't pass it any data that way. Inside a LinkTextResolver you can expand editor variables:

Code: Select all

authorAccess.getUtilAccess().expandEditorVariables("${targets}", systemID);

Considering the fact that LinkTextResolver has access to the AuthorNode, don't you have enough information to build that URL?

Best regards,
Alex

[csun]

Hi Alex,

Yes exactly, the ${targets} variable is defined inside preferences.

The expandEditorVariables code you provided is very helpful. And yes, I think I have enough information to build the URL now. Thanks again for the help! Really appreciated.

Charles

[csun]

Hi Alex,

I have been able to extend the DocbookLinkTextResolver class, let it expand the editor variable {targets} and parse this target database XML, look up the nodes we need, and return the text. I am using the Java DOM XML parser and XPath for looking up the nodes. It is returning the correct text now; so basically it is functioning!

However, I notice that when Oxygen is in the Author mode, if I

• resize Oxygen window,
  refresh Oxygen window, or
  edit something in the DocBook file opened in Author view,

Oxygen always freezes for a few minutes.

I believe the target database XML's size (about 40M) has contributed to the slowness, but why would Oxygen become slow when the window gets resized - is it because the AuthorListenerAdapter object somehow considers the window-resize as an "AttributeChangedEvent", so that it tries to refresh the view? (I haven't changed the way how the authorListenerAdapter is implemented in the default DocbookLInkTextResolver.)

Moreover, it seems at each resize / refresh / edit, Oxygen is trying to parse the target database XML again; however as I understand, after the "Document" object has been created, the customized link resolver should be able to access it from the RAM and it should be quick enough. Or am I missing anything?

Any help would be again, so much appreciated.
Charles

[alex_jitianu]

Hi Charles,

THe docbook CSSs contain at-rules that depends on the viewport width:

Code: Select all

@media screen AND (min-width:25cm) {

This means that when the viewport changes, styles are recomputed. But when this happens and your LinkTextResolver is invoked the resolver should be lightning fast since it has already built its cache. If you go on the toolbar, on the Styles drop-down and activate the "Full width" mode, this behavior should disappear. Nevertheless, we should investigate if something is wrong with the resolver's cache.

Code: Select all

Moreover, it seems at each resize / refresh / edit, Oxygen is trying to parse the target database XML again;

This is the LinkTextResolver implementation's duty. It should make sure it parses the XML Database once and builds its cache.

Can you send me the source code for the LinkTextResolver on support@oxygenxml.com ? After I take a look at it, maybe I'll have some suggestions on how to improve it.

Best regards,
Alex

[csun]

OK, I have just sent an email with the source code to support@oxygenxml.com . Looking forward to your suggestions. Thanks!