Orbeon Forms FAQ
- 1. Introduction
- 2. General Orbeon Forms FAQ
- 3. XForms FAQ
- 3.1. What is XForms?
- 3.2. How much of the XForms specification does Orbeon Forms support?
- 3.3. I hear that XForms is not well supported in web browsers. This is a problem, right?
- 3.4. What is a server-side XForms implementation?
- 3.5. What are the XForms Classic and XForms NG engines?
- 3.6. How do I know which XForms engine I am using?
- 3.7. Should I keep using the XForms Classic engine?
- 3.8. How do I migrate from XForms Classic to XForms NG?
- 3.9. Do I need to use XForms to create my HTML forms?
- 3.10. How can I perform a file upload?
- 3.11. My XForms upload doesn't work. What can I do?
- 3.12. Can I mix and match XForms and JSP?
- 3.13. Can I mix and match XForms and JavaServer Faces?
- 3.14. Can I run XForms within JSR-168 portlets?
- 3.15. What web browsers does the Ajax-based XForms engine support?
- 3.16. What visual tool / graphical designer do you recommend for XForms?
- 3.17. Can I use JavaScript to modify the page DOM and add or remove XForms controls?
- 3.18. I just want to use Orbeon Forms's XForms engine. Can I do that?
- 3.19. How do I design forms in Orbeon Forms?
- 4. XML pipelines (XPL) FAQ
- 4.1. What is an XML pipeline and why do I care?
- 4.2. What is XPL?
- 4.3. What is an XML processor?
- 4.4. What does an XML pipeline look like?
- 4.5. Is there a specification for XPL?
- 4.6. Is anybody free to implement XPL?
- 4.7. How much of the XPointer specification does XPL support?
- 4.8. How can I pass parameters to an XSLT stylesheet?
- 4.9. How does caching work in Orbeon Forms?
- 4.10. Do debug attributes make my application slower?
- 4.11. Can I disable debug attributes globally?
- 4.12. When invoking a processor in XPL, what is the difference between a name and an id?
- 4.13. I am confused by all those oxf: prefixes. What do they mean?
- 5. Other Orbeon Forms FAQ
- 5.1. Why am I getting an error page "Cannot find server or DNS server error" on IE only?
- 5.2. Why am I getting an "Illegal HTML character" exception?
- 5.3. I am concerned about the performance of Orbeon Forms. Can you provide performance numbers please?
- 5.4. What is the recommended XSLT transformer for Orbeon Forms?
- 5.5. Isn't XSLT processing slow?
- 5.6. Is XSLTC a mature product?
- 5.7. Why am I getting an "org.dom4j.IllegalAddException" error?
- 5.8. How can I parse a string containing XML into a document that Orbeon Forms can process?
- 5.9. What can I do if the application server hangs?
- 5.10. What can I do about the error "Cannot output a namespace node for the default namespace when the element is in no namespace"?
- 5.11. Where can I find more information about XUpdate?
- 5.12. How can I debug the XUpdate code in my page flow?
- 5.13. Why am I getting a "Empty local name in SAX event" exception?
- 5.14. Why am I getting extra xml:base attributes on my documents?
- 5.15. What should I do about the error message ERROR: invalid console appender config detected, console stream looping when deploying to JBOSS:
- 5.16. I am getting frequent Out of Memory errors with Orbeon Forms. What can I do?
- 5.17. Orbeon Forms Java stack traces are very long. Does that mean that performance is necessarily bad?
- 5.18. Can JSP or other servlets share a session with Orbeon Forms?
- 6. Studio FAQ
1. Introduction
This FAQ answsers technical questions about Orbeon Forms.
2. General Orbeon Forms FAQ
2.1. What is Orbeon Forms?
Orbeon Forms (formerly Orbeon PresentationServer (OPS)) is an open source forms solution that handles the complexity of forms typical of the enterprise or government. It is brought to standard web browsers (including Internet Explorer, Firefox, Safari and Opera) thanks to Ajax technology, with no need for client-side software or plugins. Orbeon Forms allows you to build fully interactive forms with features that include as-you-type validation, optional and repeated sections, always up-to-date error summaries, PDF output, full internationalization, and controls like auto-completion, tabs, dialogs, trees and menus. Orbeon Forms already supports parts of the XForms 1.1 specification.
Unlike other web application platforms based on Java objects or scripting languages, Orbeon Forms is based on XML documents and XForms. This leads to an architecture perfectly suited for the tasks of capturing, processing, and presenting XML data (in particular form data), and does not require writing any Java, JavaScript or other scripting code at all.
Orbeon Forms is built around a user-friendly Ajax-based XForms engine, which brings W3C XForms to standard browsers, and the XPL engine, a mature, high-performance XML pipeline engine for processing XML data.
2.2. Is Orbeon Forms an XForms Engine?
Orbeon Forms does contain an XForms engine, which we refer to as the Orbeon Forms XForms engine. It also contains an XML pipeline engine running the XPL pipeline language, an application controller (the Page Flow Controller or PFC), and built-in components to perform XSLT transformations, database access, and more. Needless to say, Orbeon Forms ships with examples and documentation.
You are free to use Orbeon Forms only for its XForms functionality, but you can also leverage more of Orbeon Forms to build your forms-based application.
2.3. Why did we rename Orbeon PresentationServer to Orbeon Forms?
Renaming a product is not something to be taken lightly. However we feel that:
-
Orbeon Forms better reflects the fact that forms have been the main focus of our development efforts over the last two years.
-
This new face will help potential users understand more easily what the platform can do for them.
-
Orbeon Forms is just an easier name to remember!
We are encouraged in this decision by the fact that almost all current users build complex web forms using our Ajax-based XForms engine. The name change also conveys that we plan to keep focusing on form-related capabilities in the future like we have done in the last two years.
It is important to precise the following:
-
We are not creating a separate product: Orbeon Forms is simply the new name of Orbeon PresentationServer.
-
Other XML technologies like XSLT and XML pipelines remain an important part of the platform.
-
And of course, Orbeon Forms remains an open source solution!
2.4. Where do I find the source code?
In the ObjectWeb CVS repository. This page provides the instructions to retrieve it. You can also browse the repository with your web browser.
2.5. What is OXF?
OXF was the name of Orbeon Forms before it was open sourced in 2004. For backward compatibility, the string "oxf" still persists in a few places, including:
-
As XML namespace prefix for built-in XPL processors.
-
As part of built-in XML namespace URIs.
-
As a URL scheme for accessing Orbeon Forms resources.
-
As a prefix for property names in
properties.xml
. -
As a prefix for parameter names in
web.xml
. -
As a package name in the Java source code.
See also I am confused by all those oxf: prefixes. What do they mean?.
2.6. What is OPS?
OPS stands for Orbeon PresentationServer and was the name of the platform before it was renamed to Orbeon Forms in November 2006. The string "ops" still persists in a few places, including some resource paths, and the name of the Orbeon Forms mailing-list.
3. XForms FAQ
3.1. What is XForms?
W3C XForms is a standard, markup-based, declarative, XML- and HTML-friendly user interface technology particularly adapted to building complex forms. XForms makes it easy to build dynamic user interfaces able to talk to XML services.
XForms is a W3C Recommendation since October 2003, with a second edition of the 1.0 published in March 2006. The XForms Working Group is, as of August 2006, working on XForms 1.1, due in late 2006 or 2007, before embarking on XForms 1.2 or XForms 2.0! Please visit XForms - The Next Generation of Web Forms for more information about XForms direct from W3C.
XForms aims at replacing HTML forms, but it is not strictly tied to HTML. The main goal of XForms is to make web forms design easier, allowing the developer to write less client-side scripting (or none at all), and less server-side code thanks to a feature-rich declarative approach.
Benefits of XForms include:
- Clear separation between data captured and presentation (separation of concerns)
- Flexible, structured XML-based data model: define your data model as an XML document, then create forms accessing the data
- Built-in facilities for validation and data integrity based on XML Schema and/or assertions
- Declarative approach requiring less / no scripting at all, in particular thanks to declarative events and actions
- Ease of internationalization
- Support for a variety of devices
- W3C standard
- Not tied to a particular platform or language such as Java or .NET
See also the Orbeon Forms XForms Introduction section.
3.2. How much of the XForms specification does Orbeon Forms support?
The Orbeon Forms implementation is based on the W3C XForms 1.0 (Second Edition) Recommendation (14 March 2006). The XForms NG engine in Orbeon Forms 3.5 is close to supporting all of the XForms 1.0 specification. For more detailed information on what features are supported in the latest version of Orbeon Forms, see the XForms Compliance section of the documentation.
Orbeon Forms also supports several features from XForms 1.1 (in draft as of August 2006), as well as extensions such as new widgets (autocomplete, tree, menu, dialog, etc.).
3.3. I hear that XForms is not well supported in web browsers. This is a problem, right?
No, this is not a problem at all, because XForms can run on the server, in the same way that other web applications technologies like PHP, ASP, JavaServer Faces or Ruby run on the server.
You run XForms on the server by installing the Orbeon Forms XForms engine on your server. The XForms engine translates your XForms pages to HTML, CSS and JavaScript that your browser understands. Your web browser sees a regular Ajax application, but as a developer you write standard XForms instead of JavaScript!
Running XForms on the server has even several benefits over running it in the client:
-
Users don't have to upgrade their web browser or install plugins or extensions. You can use and develop with XForms today and target over 90% of the users on the web.
-
The data used by your XForms application remains safely on the server. With client-side implementations, on the other hand, you have to be very careful not to send confidential information to the XForms engine, as that information may be seen by the user.
-
You can upgrade your XForms implementation at a single location on your server instead of waiting for users ot upgrade their browsers when bugs are fixed or new features are implemented.
3.4. What is a server-side XForms implementation?
Historically, the XForms specification assumed that XForms was implemented on the client-side, natively within a web browser. But as discussed here, XForms-based applications can use server-side or hybrid implementations that share XForms processing between server-side code and client-side code and rely on Ajax technology. Orbeon Forms features such an Ajax-based implementation.
A server-side implementation of XForms translates your forms described in terms of the XForms specification into HTML, CSS and JavaScript code understood by your web browser. The following diagram shows a high-level overview of the architecture of an Ajax-based XForms implementation:
For more information, we refer you to these articles we presented at the XTech 2005 and XTech 2006 conferences:
-
XForms: an alternative to Ajax? (XTech 2006)
-
Are Server-Side XForms Engines the Future of XForms? (XTech 2005) (see also the pre-conference proceedings, which contain an out of date version of the article)
3.5. What are the XForms Classic and XForms NG engines?
Up to version 2.8, Orbeon Forms featured a pure server-side XForms engine with limited XForms functionality. With version 3.0, Orbeon Forms features a much enhanced XForms engine, with support for almost the entire XForms specification, with the intent to completely support XForms 1.0 and XForms 1.1 in the future. The older XForms engine has been informally dubbed "XForms Classic", and the new XForms engine "XForms NG".
For backward compatibility reasons, the XForms Classic engine is still present in Orbeon Forms 3.5. We plan over time to allow XForms NG to support non-JavaScript, non-Ajax browsers as well, therefore making XForms Classic obsolete in Orbeon Forms.
3.6. How do I know which XForms engine I am using?
If you are using Orbeon Forms 2.8 or earlier, you are using XForms Classic. If you are using Orbeon
Forms 3.0 or later, then you may be using XForms Classic or XForms NG, but there is an easy way to
tell: if a <page>
entry in your page flow features an xforms
attribute, then and only then that page is using XForms Classic. Otherwise, if the page view
contains at least one XForms model under its xhtml:head
element, then it is using
XForms NG.
3.7. Should I keep using the XForms Classic engine?
The XForms Classic engine is available only for backward compatibility. It is deprecated and may be removed in the future. If you are starting an application from scratch with Orbeon Forms 3.5, we strongly advise against using XForms Classic. If you are migrating to Orbeon Forms 3.5, we advise starting migrating XForms NG. You can keep your existing pages working with XForms Classic, and write new pages with XForms NG. Over time, you can migrate existing XForms Classic pages to XForms NG, making for a smooth transition.
As of Orbeon Forms 3.5, only one feature of XForms Classic have not yet made it into XForms NG: support for browsers with very limited JavaScript functionality (non-Ajax mode). In time, we hope to bring these features to XForms NG as well, therefore completely deprecating XForms Classic.
3.8. How do I migrate from XForms Classic to XForms NG?
Please visit Migrating from XForms Classic to XForms NG.
3.9. Do I need to use XForms to create my HTML forms?
It is not a requirement to use XForms. It is possible to generate HTML form elements and to examine request parameters manually. We recommend however using XForms whenever possible, because it provides an elegant abstraction that greatly simplifies form handling.
3.10. How can I perform a file upload?
Check the XForms upload control and the XForms upload example
3.11. My XForms upload doesn't work. What can I do?
With Orbeon Forms 2.8 or earlier, or if you are using XForms Classic with Orbeon Forms 3.0 or later, make sure that you have the correct submission method and encoding in your XForms model:
With Orbeon Forms 3.0 and XForms NG, uploaded files can only be retrieved with a submission with
replace="all"
.
3.12. Can I mix and match XForms and JSP?
Yes, you can use JSP alongside XForms, even within the same web app. You can "call" JSP by redirecting or forwarding using the Redirect processor. You can also use the Servlet Include generator to include the content produced by a JSP. Finally, you can use the Servlet Filter generator and implement JSP post-processing with Orbeon Forms.
3.13. Can I mix and match XForms and JavaServer Faces?
It all depends on what you are trying to achieve with this integration. Technically, you can write a page in JSP + JSF that produces XForms, which can then be processed by the Orbeon Forms XForms engine using a Servlet filter approach. But mixing JSF components with XForms components can cause difficulties related to the way each component set handles form submissions and state. In particular:
-
If you use non-AJAX JSF components, the standard JSF components (buttons, etc.) will perform HTML form submissions to the server, which then reevaluates the JSF component tree to produce an updated page that is then sent back to the client. If you do this and your page contains XForms components as well, you will lose the state of your XForms controls when the page reloads.
-
If you use AJAX JSF components (we have no experience whatsoever with those), there could be conflicts due to the JavaScript libraries those components use vs. the ones we use in Orbeon Forms.
Feel free to experiment with JSF and XForms together, but at the moment we recommend using either JSF or XForms exclusively in a given page. However you can very well use JSF for some pages, and XForms for other pages within the same application.
3.14. Can I run XForms within JSR-168 portlets?
As of Orbeon Forms 3.5, it is possible to use the Orbeon Forms XForms engine within the Java Portlet (JSR-168) compliant Liferay portal, thanks to kind sponsoring by Atkins Transport Systems.
To do this, use the provided epilogue-portlet-liferay.xpl
epilogue instead of the
default epilogue-portlet.xpl
. It is expected that Orbeon Forms will work within other
JSR-168 portals, or that only minor adjustments will be needed in such cases.
The great thing about Orbeon Forms and portlets is that there is very little difference if any between writing an application working in a portlet vs. a servlet. In fact, all the Orbeon Forms XForms examples work unmodified as portlets. You can use some particularities of portlets, like preferences, and you have to be careful about paths to serve resources, but otherwise portlets are transparent to the developer. This contrasts with many other web platforms.
In other words, Orbeon Forms gives you the flexibility to write an application that works in standalone mode, and allows you to migrate to a portlet environment at minimal cost. This contrasts with many other web application technologies, which sometimes require you to rewrite your application entirely to fit within a portlet.
HISTORICAL NOTE: There has been a lot of code in Orbeon Forms to support JSR-168 since late 2003 already. When this code was written, the JSR-168 specification was not final and no JSR-168 container was available. So Orbeon developped a container based on draft specifications for testing. This code was used until recently to run the Orbeon Forms examples portal: examples were actually using the portlet code and running as portlets, and the examples portal is an early JSR-168 portal. Note that this is no longer the case with Orbeon Forms 3.5, where the example applications portal does not use JSR-168 for performance and simplicity reasons.
3.15. What web browsers does the Ajax-based XForms engine support?
Orbeon Forms 3.5's XForms engine supports Firefox (1.0.7 and later), IE 6, Safari (1.3 and later), and Opera (8.5 and later).
In the future we hope to also add support in XForms NG for non-JavaScript (and non-Ajax) browsers.
3.16. What visual tool / graphical designer do you recommend for XForms?
We develop all our applications and forms using an XML editor. This is the only way you can leverage all the features of XForms today, especially the more complex ones like events and actions. This means that we do not have a visual tool to recommend officially. You may however try the Intalio designer. Trial versions are available from their web site once you register.
Our perception is that visual tools tend to be of little use for actual developers except for the first few steps of development (and this is not only true for XForms but also for other frameworks like JavaServer Faces), so we advise not to have too high expectations when it comes to visual tools. However, we reckon that helping developers during the first stages of application development is valuable and we would like in the future to offer such a tool, most likely web-based (and itself implemented with XForms!).
If you have good experience with a visual tool, please be sure to let us know.
3.17. Can I use JavaScript to modify the page DOM and add or remove XForms controls?
No, because your JavaScript code will run within the web browser, which doesn't know anything about XForms controls. All the web browser sees is an HTML DOM (Document Object Model), which represents the HTML document produced by Orbeon Forms when it transforms XForms+XHTML into plain HTML. That DOM does not include in XForms elements.
Remember, the Orbeon XForms implementation works server-side in order to support currently deployed browsers. It achieves this by sending to web browsers not XForms (which they wouldn't understand), but HTML, JavaScript, and CSS (which they do understand).
If you just want to conditionally include XForms controls when the page is loaded, you can use an XSLT page view. If you want to control the showing or hiding of XForms controls after the page is loaded, you can use XForms relevance or switch/case. Currently, the only thing you can't do is dynamically add and remove trees of controls in a running XForms page.
3.18. I just want to use Orbeon Forms's XForms engine. Can I do that?
In addition to the XForms engine, Orbeon Forms comes with an XML pipeline engine and a Page Flow Controller (PFC). While these additional building blocks are often useful to put together your form-based applications, you may not have a need for them.
The good news is that Orbeon Forms is very configurable and you are not forced to use XML pipelines or the PFC. Users have been successfuylly using the Orbeon Forms XForms engine with JSP/Struts or PHP. The bad news is that we haven't yet written as much documentation as we would want on this topic. In the meanwhile, check Using XForms with JSP and post your questions to the ops-users mailing-list.
3.19. How do I design forms in Orbeon Forms?
Orbeon Forms does not come with a visual forms designer. You create forms by writing XHTML pages that contain embedded XForms markup.
Orbeon Forms 3.5 will come with a new tutorial that explains step by step how to create your first
forms. In the meanwhile, we recommend you look at the sample Orbeon Forms applications that you find
under your WAR file's WEB-INF/resources/apps
directory.
Also note that Orbeon provides services around Orbeon Forms, including training. Please visit our support page for more information.
4. XML pipelines (XPL) FAQ
4.1. What is an XML pipeline and why do I care?
XML pipelining is an approach to processing XML where the inputs and outputs of multiple processing steps (e.g., XSLT transformations) are connected together using a pipeline metaphor. Orbeon has implemented an XML pipeline engine in Java that executes a declarative XML pipelining language called XPL.
"Programming" pipelines using declarative XML instead of writing procedural code results in a significant increase in productivity for tasks that require high volume or complex XML processing. XML documents enter a pipeline, are efficiently processed by one or more processors as specified by XPL instructions, and are then output for further processing, display, or storage. XPL features advanced capabilities such as document aggregation, conditionals ("if" conditions), loops, schema validation, caching, and sub-pipelines.
XML pipelines are built up from smaller components called XML processors. An XML processor is a software component which consumes and produces XML documents. New XML processors are most often written in Java, but most often developers do not need to write their own processors because the engine provides a comprehensive library. Example processors include an XSLT processor, database processors that interface with both SQL and native XML databases, and a serializer processor that writes XML documents to disk. XPL orchestrates these to create business logic, similar to the way Java code "orchestrates" Java object method calls.
4.2. What is XPL?
At the core of Orbeon Forms lies a powerful XML processing engine that natively speaks the XML Pipeline Language (XPL). XPL is a declarative language for processing XML using a pipeline metaphor. XML documents enter a pipeline, are efficiently processed by one or more processors as specified by XPL instructions, and are then output for further processing, display, or storage. XPL features advanced capabilities such as document aggregation, conditionals ("if" conditions), loops, schema validation, and sub-pipelines.
The Orbeon XPL pipeline engine used in Orbeon Forms is designed for low-memory consumption and supports transparent caching.
4.3. What is an XML processor?
The term XML processor is commonly used to refer to XML parsers. In the context of Orbeon Forms, the term XML processor is used to refer to any software component consuming and/or producing XML documents. An XML processor can also simply be called an XML component.
4.4. What does an XML pipeline look like?
This particular example illustrates a simple 2-stage XPL pipeline that performs an XSLT transformation on an XML document that is located on disk, and then writes the result back to a another file on disk. For more details about XPL, please see the XPL and Pipelines reference documentation.
4.5. Is there a specification for XPL?
As of February 2005, a draft specification has been completed amd submitted to W3C. It serves as a basis of discussion for an XPL 1.0 specification.
As of December 2005, XML Processing Model Working Group meetings have started at W3C. This working group, of which Orbeon is a member, is in charge of working on a standard XML processing language. While the deliverable of the working group will certainly not be exactly XPL, we do hope that in its first version it will cover a significant number of use cases currently covered by the XPL implementation found in Orbeon Forms.
As of September 2006, the XML Processing Model Working Group (of which Orbeon is a member) has released a first public draft of the XProc XML Pipeline Language.
4.6. Is anybody free to implement XPL?
Yes.
4.7. How much of the XPointer specification does XPL support?
Orbeon Forms supports a subset of XPointer. You can use the
XPointer document#xpointer(/xpath/expression)
syntax to extract a
nodeset from a document.
4.8. How can I pass parameters to an XSLT stylesheet?
It is possible by importing the stylesheet within another stylesheet, as follows:
4.9. How does caching work in Orbeon Forms?
Caching mechanisms should have no impact on the behavior of a system, except for a gain in performance. This is also the principle followed by the Orbeon Forms cache: when you develop an application with Orbeon Forms, you should be able to ignore that caching takes place. This may be all you want to know about caching in Orbeon Forms!
To get a better understanding of the underlying mechanism, consider the example below:
Let's assume the following:
- The XSLT processor's
config
input is an XSLT stylesheet on disk - The XSLT processor's
data
input is an XML file on disk - The XSLT stylesheet does not contain imports, includes, the document() function, or calls to Java code.
Under those assumptions, the XSLT transformation does not
have side effects, which means that if neither the XSLT
stylesheet
(
config
input) nor the input XML
document (
data
input) change, the output of the
transformation will be the same.
If you were to keep the result of the transformation, knowing that both inputs have not changed since the last time you generated that output, you wouldn't have to actually run the transformation again: you could just reuse the result you already have. This is the basic of caching in Orbeon Forms.
In this example, the result of the XSLT transformation is used to create an XUpdate processor configuration, which is an XUpdate program that will be interpreted or compiled by the XUpdate processor. Instead of keeping the result of the XSLT transformation as an XML document, the XUpdate processor can cache the compiled XUpdate program. Compared to a solution where the XML document is cached, this technique saves memory by not keeping the XML document in cache, and saves processing power by preventing the XUpdate processor to recompile its program.
Therefore, if neither the XSLT transformer's
config
nor
data
input has changed, the XUpdate processor can keep the
same program in the Orbeon Forms object cache, saving an XSLT stylesheet
compilation, an XSLT transformation, and an XUpdate program compilation.
The same mechanism applies to the XSLT transformer configuration: the compiled XSLT stylesheet can be kept in the Orbeon Forms object cache. And if the output of the XUpdate transformation is sent to an HTML serializer, the HTML output could be cached as well.
In general, Orbeon Forms does not unnecessarily cache the XML documents passed between processors. Instead, it caches the result of time-consuming operations, as illustrated above.
Some cases are more complex than the example shown here. For
example in the case of XSLT 1.0, Orbeon Forms handles caching and
dependencies related to imports, includes as well as the
XPath
document()
function when the URL passed
to the function is static. Some processors, like the SQL
processors, never allow their output to be cached.
4.10. Do debug attributes make my application slower?
The Orbeon Forms cache avoids executing the parts of a pipeline that do not need to be re-evaluated. However when the a debug attribute is set, the point where the attribute is set needs to be evaluated so that meaningful data can be displayed. This can cause the performance to degrade. Debug attributes should be removed in production.
4.11. Can I disable debug attributes globally?
Not at this time.
4.12. When invoking a processor in XPL, what is the difference between a name and an id?
Processors can be compared to functions in traditional programming languages. Processors (just like functions) have inputs (arguments) and outputs (return values). Each input and output has a name. The name is part of the processor's interface. For instance, using an informal function-like notation, the XSLT processor interface is:
(data) = xslt(data, config)
since the XSLT processor has 2 inputs named data
and
config
, and one output named data
.
The interface to a processor is the contract that defines what inputs and outputs do. If you are using an existing processor, for example the XSLT transformer, you have to use the names declared by that processor. To know what names you must use, you have to consult the documentation for each processor. We have tried to be consistent and to use "config" and "data" as often as possible. You can for example call the XSLT transformer like this:
A pipeline can also be viewed as a processor. If that pipeline decides to
export inputs and outputs, it must do so using the <p:param
name="..."/>
syntax. This defines its interface. You can compare this to
writing your own method in Java, as opposed to using an existing method. The
difference is that in Java, you address method parameters by position when you
call a method. In XPL, you always address them by name. Therefore it is
important to use the right name when you call a processor (or a pipeline).
This also applies to the cases where the Web Application Controller calls your
own pipelines: the PFC has to know the names of the inputs and outputs to
connect to. Therefore, you have to use the names ( data
and
instance
) documented.
If you implement a pipeline or write a new processor in Java, and you don't have any external naming constraints (such as the ones defined by the PFC, or if somebody expects to call your pipeline using names defined in advance), you are free to use any name.
In XPL an id can be assigned to an output when invoking a processor. This id can then be used latter on in the same pipeline to refer to that specific output, and for instance connect it to the input of another processor. Ids are similar to variable names in most programming languages.
4.13. I am confused by all those oxf: prefixes. What do they mean?
By default Orbeon Forms makes two uses of the string oxf:
:
-
As an XML namespace prefix in XPL. The XML namespace prefix
oxf
is typically mapped to the XML namespace URIhttp://www.orbeon.com/oxf/processors
. This namespace is used to resolve XML qualified names (also referred to as "QNames") that identify the built-in XML processors in XPL, such asoxf:xslt
. These are constructs specific to XML. -
As a URL scheme. The
oxf
URL scheme is used to address Orbeon Forms resources through the Orbeon Forms Resource Manager. They are part of URLs such asoxf:/config/properties.xml
. Such URLs are supported throughout the Orbeon XForms XPL engine and XForms engine.
Having both uses in the same file may be confusing. But while you have to use the
oxf
scheme to access Orbeon Forms resources, you don't have to use the
oxf
prefix in XPL: you can use any prefix you like, for example:
5. Other Orbeon Forms FAQ
5.1. Why am I getting an error page "Cannot find server or DNS server error" on IE only?
If you get the white IE error page with the message "Cannot find server or DNS server error" when
navigating to another page, it most likely means that the length of the URL for that page exceeds
the limit imposed by IE. This can happen if you are passing an XForms instance from one page to
another with a redirect. The solution often involves changing in your properties.xml
the value of the instance-passing
property for the processor
oxf:page-flow
from redirect
to forward
.
The instance-passing
can be defined at application level in
properties.xml
, the page flow level, or the <result>
element level. See
the changes in version 2.5 for more information about
instance-passing
.
5.2. Why am I getting an "Illegal HTML character" exception?
The exception typically looks like:
org.orbeon.saxon.trans.DynamicError: Illegal HTML character: decimal 150
at org.orbeon.saxon.event.HTMLEmitter.writeEscape(HTMLEmitter.java:321)
In general, you get this error when the encoding on your XML file missing or is incorrect. In the example above, we had specified the encoding to be ISO-8859-1, while editing the file on a Windows machine. The file contained a dash encoded as the character 150 in decimal, 96 in hexadecimal, which is not a valid character for the ISO-8859-1 encoding. In this case changing the encoding to windows-1252 solves the problem.
Specifying ISO-8859-1 instead of windows-1252 on files that contain characters invalid in ISO-8859-1 does sometimes work, but not always. In particular, more recent versions of Saxon became stricter checking for invalid characters. So we recommend you use windows-1252 instead of ISO-8859-1 when appropriate. You specify the windows-1252 encoding by starting your XML file with the following XML declaration:
<?xml version="1.0" encoding="windows-1252"?>
For more information, see this discussion on the difference between ISO-8859-1 and Windows-1252.
5.3. I am concerned about the performance of Orbeon Forms. Can you provide performance numbers please?
We provide recommendations on how to tune Orbeon Forms applications in the Performance and Tuning section. Orbeon does not provide performance figures at this point, due to the number of different possible scenarios, the differences between hardware platforms, and the different expectations of users. We believe that the best way to tackle performance questions is to go beyond theory and work on a small but representative prototype. Orbeon can help you build that prototype, a task often done in just a few days. Upon completion of the prototype, you can evaluate whether the performance of the prototype is satisfying or not, and if not, Orbeon can help you determine whether and how performance can be improved. The final appreciation belongs to you.
5.4. What is the recommended XSLT transformer for Orbeon Forms?
Saxon 8 is used by default within Orbeon Forms. It has proven reliable, and supports the latest XSLT 2.0 and XPath 2.0 drafts from the W3C.
Orbeon Forms also ships with Saxon 6, Xalan 2.5 and XSLTC 2.5.
5.5. Isn't XSLT processing slow?
XSLT performance can vary greatly depending on the XSLT processor used. In general, XSLT performance has shown perfectly adequate for all but the most performance-intensive applications. This being said, Orbeon Forms minimizes the performance hit with its advanced cache, which for example caches objects such as XSLT templates, therefore avoiding reparsing and revalidating stylesheets unless absolutely necessary.
Orbeon Forms also ships with XSLTC, an XSLT compiler now part of Apache Jakarta. XSLTC has shown significant performance improvements over the regular Xalan implementation, at the cost of a lack of maturity.
5.6. Is XSLTC a mature product?
XSLTC is not quite mature yet and caution must be exercised when using it. If you plan to use XSLTC, we recommend extensive testing as well as switching back and forth between XSLTC and the regular Xalan implementation during development to ensure proper behavior. We also recommend submitting bugs to the Jakarta project if necessary.
5.7. Why am I getting an "org.dom4j.IllegalAddException" error?
The full message looks like:
org.dom4j.IllegalAddException: The node "org.dom4j.util.UserDataElement@c11567 [Element: <gaga attributes: []/>] userData: null, line 0, column 0" could not be added to the branch "null" because: Cannot add another element to this Document as it already has a root element of: gaga
You get this error when you have a stylesheet that generate two or more root elements. This tends to happen if your stylesheet does not match on "/". For instance, say you have this stylesheet:
And this input document:
The XSLT output will be <x/><x/>, which is a not legal XML document (of course, you can only have one root element in an XML document).
5.8. How can I parse a string containing XML into a document that Orbeon Forms can process?
Use the XSLT transformer and the
saxon:parse
function. This function parses an XML document supplied as a string and returns
a document node. To copy the resulting document to the output of your XSLT
transformation, use
xsl:copy
. For example, assuming your input
document is as follows:
Consider also the following XSLT transformation:
Running this transformation on the input document above generates the following output:
This tip is particularly useful for parsing XML strings returned by EJBs, Web Services, or entered by a user in XForms textarea controls.
5.9. What can I do if the application server hangs?
-
If your JVM is running but is not responding to HTTP requests, you might first want to see where in the Java code threads are blocked. To do so, on Windows hit ctrl-break in the command prompt window where your application server is running; on Linux identify the process id of the JVM running your application server and issue a
kill -3 pid
.If you are using Tomcat and the threads are blocked in database code (e.g. SQLProcessor, PoolingDataSource) open your
server.xml
, locate the element configuring the Coyote HTTP 1.1 Connector. Make sure that themaxProcessors
attribute on Tomcat 4.1 or themaxThreads
attribute on Tomcat 5 is set to a value that is much lower than the value of theacceptCount
attribute. Typically values formaxProcessor
ormaxThreads
are 3 for a single-CPU server or 4 for a dual-CPU server, while the value ofacceptCount
can be much higher, typically between 50 and 100.For more information on those and other attributes configuring the Coyote HTTP 1.1 Connector in general, see the Tomcat 4.1 or Tomcat 5 documentation.
-
Some versions of Chainsaw have a bug where Chainsaw stops responding in certain situations, which blocks the application server. If you are using Chainsaw, this might be the problem: use the FileAppender instead, or use Orbeon Studio instead of Chainsaw to view log messages.
-
If you are running RedHat 9, set the environment variable LD_ASSUME_KERNEL=2.4.1 and restart the application server.
5.10. What can I do about the error "Cannot output a namespace node for the default namespace when the element is in no namespace"?
This is a Saxon issue. It might happen when in the input document of a stylesheet or in the output of the stylesheet you have an element declared with no prefix as the child of an element with a prefix. One way to get around this is to add a prefix to all the element having a parent declared with a prefix.
5.11. Where can I find more information about XUpdate?
Efforts around the XUpdate language appear to be stalled. XML databases now tend to bid on proprietary extensions to the standard XQuery language (e.g. see what Tamino does, and there are talks about implementing something similar in the open source eXist database). In the future, XQuery will support standard update features, but that is probably years away.
We do recognize that XUpdate has definite advantages over XSLT in certain use cases (which is why we implemented it in the first place), but it seems that the market is currently not supporting what is considered "yet another XML transformation language".
For use as a general-purpose XML update language with Orbeon Presentation Server, we now recommend using XSLT. Use either XSLT 1.0 or XSLT 2.0 (12 November 2003 Draft as implemented by Saxon) instead of using the XUpdate processor. The only place where XUpdate is not deprecated is within Page Flow, but only a subset of XUpdate is required and you can simply consider that it is part of the Page Flow syntax.
This being said, our XUpdate implementation is functional and of course anybody is free to use it or contribute to it. Like the rest of Orbeon Forms, it is available under the LGPL license.
5.12. How can I debug the XUpdate code in my page flow?
Insert at the very beginning of the in the XUpdate code those 3 lines to log the instance being modified (instance of target page), the current instance, and the output of the action pipeline:
Then as the very last instruction in the XUpdate code, add:
5.13. Why am I getting a "Empty local name in SAX event" exception?
If this exception is thrown from the class TransformerImpl class in a Xalan
package (orbeon.apache.xalan.transformer
), a bug in Xalan is at
the source of the problem. Xalan calls the SAX startElement()
method with an attribute that has an empty local name.
Switching to Saxon will solve the problem. Saxon is now the default XSLT 1.0 and
XSLT 2.0 processor in Orbeon Forms, and will get used when using oxf:xslt
.
See the XSLT documentation for more information.
5.14. Why am I getting extra xml:base attributes on my documents?
This usually happens when you use XInclude. As per the XInclude specification, such attributes are added upon inclusion. You can get rid of them by using XSLT:
5.15. What should I do about the error message ERROR: invalid console appender config detected, console stream looping when deploying to JBOSS:
This used to happen with JBoss 3.2.1 and OXF 2.2. The work around a the time
was to add -Dorg.jboss.logging.Log4jService.catchSystemOut=false
to
the end of the JAVA_OPTS line in JBOSS_HOME/bin/run.bat. (run.sh on UNIX)
5.16. I am getting frequent Out of Memory errors with Orbeon Forms. What can I do?
Often, this is due to too many threads doing processing within Orbeon Forms at the same time. There is just a lot going on in Orbeon Forms when a request is processed, including typically several XSLT transformations.
Servlet containers like Tomcat, or application servers like WebLogic, by default allow a very large number of concurrent threads to enter a servlet. For Tomcat, the default is 200. This means that memory usage cannot be effectively bound. It is enough to have a few requests slightly overlapping to cause extra memory consuption that can lead to Out of Memory errors. In addition, extra memory usage leads to poorer performance.
It is recommended to start by changing the container parameters that control threads. With Tomcat (see the documentation), try first:
- maxThreads="3"
- acceptCount="50"
This setting will set a small maximum of 3 concurrent requests, and 50 more requests being queued. This will ensure that memory usage does not go out of control.
Then, experiment with a tool like Apache JMeter to test load, and adjust those parameters, as well as your virtual machine heap, until you get results that are satisfactory as far as memory consumption and number of concurrent requests are concerned.
Note that it is typical for Java virtual machines to have maximum heap sizes of 256 MB to 1 GB in production.
5.17. Orbeon Forms Java stack traces are very long. Does that mean that performance is necessarily bad?
Java stack traces are indeed very long in Orbeon Forms. This is due mainly to the nature of XPL pipelines, which are implemented on top of the event-based SAX API.
In reality you cannot make any reasonable conclusion about performance just by looking at the length of a typical stack trace: you would have in addition to that to look at the pattern of execution of those methods. For example, if every top-level method call was going through, say, 300 levels of method calls, this would likely be an issue, but it is not the case in Orbeon Forms. The bottom line is that no, the length of a stack trace does not directly correlate with poor performance.
To reach valid conclusions about performance, run a tool like Apache JMeter on your application.
5.18. Can JSP or other servlets share a session with Orbeon Forms?
Yes, the Scope serializer and Scope generator simply use the Servlet (or Portlet) session to store and retrieve information.
6. Studio FAQ
6.1. In Studio, why nothing shows up in the XPL Trace Views?
The XPL Trace facility provides information for a given page served by Orbeon Forms. For that page, it shows a tree of processor calls and indicates on that tree how much time has been spent on each node. This information collected by XPL Trace can be either sent to the standard output, or to Studio. When sent to Studio, it will be shown in the XPL Trace Table and XPL Trace Tree views. For this to work as expected:
- You need to setup the port Studio listens to, from Preferences / Orbeon. That port must match the one you have setup in Orbeon Forms properties.
- After changing the port number in Studio, you might have to restart Eclipse.
- For Studio to listen on the specified port, you need to have two views (XPL Trace Table and XPL Trace Tree) open. You might also need to at least make one of the views active before Studio starts listening on the specified port. On Windows, you can check if Studio is listening on the port you specified using TCPView.
6.2. In Studio, how can I add my own VM arguments (e.g. heap size, debugging)
- For version 1.0.3 or higher :
- Select the menu item
Run | Run...
- Either create a new J2EE Container Container for Orbeon Forms launch configuration or select an existing one.
- Select the Argguments tab.
- In the VM arguments field add your VM arguments.
- Click the Apply button to save the change.
- Select the menu item
- For versions lower than 1.0.3 :
- Open the Window | Preferences dialog.
- Under Java | Installed JRE, select the "Standard VM".
- Click on the Edit button.
- Enter your own VM arguments in the Default VM Arguments text field.
Note that this sets the VM arguments for all the applications you run from Eclipse. At this point there is no way to set VM arguments that are only used when starting the J2EE container.
6.3. In Studio, why is the Logging Events view always empty?
Check the following:
-
Make you don't have any "Address already in use" error in the Console view when you start the application server. If you do, it means that you already have another application (other program, or other Orbeon Forms application maybe deployed in the same application server) using the same port. On Windows, you can use TCPView to determine what application is using the port you mention in the
log4j.xml
. -
Make sure you don't have any filter setup in Logging Events view by right-clicking on the "down arrow" icon and selecting "Filters".
-
To populate the Logging Events view, Studio connects to log4j, and log4j listens on the port specified in the log4j.xml file.
There is nothing in the Studio preferences to tell Studio to which port it should connect. Instead, Studio finds the port by looking at all the log4j.xml files you have in all the open projects. It will then try to connect to all the ports specified those files.
If log4j was able to listen on the port specified in your log4j.xml (see point 1 above) and still no messages appear in the Logging Events view, that might be because Studio cannot find your log4j.xml. So make sure that this file is in an open project defined in the Studio. Also note that if you modify this file outside of Eclipse with an external program, Studio won't pick up that modification. In that case, in the Navigator view, right click on the project that contains your log4j.xml and choose Refresh. Right after this, events should start to appear in the Logging Event view as you load pages in the browser.