OPS User Guide
- Getting Started
- Tutorial
- Core Technologies Reference
- XForms
- Page Flow
- XML Pipelines (XPL)
- OPS Technologies Reference
- Processors Reference
- API Reference
- Integration
- Obsolete
|
Orbeon PresentationServer and Orbeon Studio FAQ
1. Introduction
This FAQ answsers technical questions. See also the Orbeon community FAQ.
2. Orbeon PresentationServer FAQ
2.1. How does Orbeon PresentationServer compare with Apache Cocoon?
OPS is similar to Cocoon in many respects but also presents many
differences. For more information, see our OPS and
Cocoon comparison matrix.
2.2. 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.
2.3. What is XPL?
At the core of OPS 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 OPS is designed for
low-memory consumption and supports transparent caching.
2.4. What is an XML processor?
The term XML processor is commonly used to refer to XML parsers. In the context
of OPS, 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.
2.5. 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, or the OPS tutorial.

2-Stage XPL Pipeline Diagram

2-Stage Pipeline XPL Code
2.6. 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.
2.7. Is anybody free to implement XPL?
2.8. How does OPS compare with Model 2X?
Model 2 defines how the Model-View-Controller (MVC) pattern can be applied to
Web applications. Model 2X builds on top of Model 2 and replaces the JSP layer
with XML and XSLT. Model 2X was first described in an
article
published by JavaWorld in February 2002. OPS can be used to
implement Model 2X and much more. For more information, please refer to the
OPS User Guide.
2.9. What is XForms?
XForms is W3C's next generation web forms. XForms 1.0 is a W3C Recommendation
since October 2003.
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
- 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 OPS XForms Introduction section.
2.10. How much of the XForms specification does OPS support?
The XForms specification assumes that XForms is implemented on the client-side.
Ideally an XForms implementation would be implemented in a web browser, and
until XForms becomes standard on mainstream browsers, XForms-based applications
need to use server-side implementations, such as the one implemented by the
OPS. It is believed that using server-side implementation is a
great migration path towards XForms.
A server-side implementation of XForms translates your forms described in terms
of the XForms specification into HTML forms. It also creates one or more XML
documents, the XForms instances, based on the data entered by the
end-user with a browser. The following diagram shows a high-level overview of
the architecture of a server-side XForms implementation:

Server-Side XForms
The OPS implementation is based on the W3C XForms 1.0 Recommendation (14
October 2003). For more detailed information on what features are supported in
the latest version of OPS, see the XForms conformance matrix
section of the documentation.
2.11. 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
simplifies form handling.
2.12. How much of the XPointer specification does XPL support?
OPS supports a subset of XPointer. You can use the
XPointer document#xpointer(/xpath/expression) syntax to extract a
nodeset from a document.
2.13. How can I pass parameters to an XSLT stylesheet?
It is possible by importing the stylesheet within another
stylesheet, as follows:
<p:processor name="oxf:xslt"> <p:input name="data" href="..."/> <p:input name="config"> <xsl:stylesheet version="2.0"> <!-- This is the stylesheet to pass parameters to --> <xsl:import href="tour.xsl"/> <!-- Here we assign a value to the "start" parameter --> <xsl:param name="start" select="'a1'"/> </xsl:stylesheet> </p:input> <p:output name="data" id="..."/> </p:processor>
2.14. What is the recommended XSLT transformer for OPS?
Saxon 8 is used by default within
OPS. It has proven reliable, and supports the latest XSLT 2.0 and XPath 2.0 drafts from the W3C.
OPS also ships with Saxon 6, Xalan 2.5 and XSLTC 2.5.
2.15. 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, OPS
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.
OPS 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.
2.16. 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.
2.17. How does caching work in OPS?
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
OPS cache: when you develop an application with
OPS, you should be able to ignore that caching takes place. This
may be all you want to know about caching in OPS!
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
OPS.
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 OPS 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 OPS 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, OPS 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, OPS 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.
2.18.
Do debug attributes make my application slower?
The OPS 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.
2.19. Can I disable debug attributes globally?
2.20. How can I perform a file upload?
2.21. My XForms upload doesn't work. What can I do?
With OPS 2.8 or earlier, make sure that you have the correct submission method
and encoding in your XForms model:
<xforms:submission method="post" encoding="multipart/form-data" xmlns:xforms="http://www.w3.org/2002/xforms"/>
2.22.
When invoking a processor in XPL, what is the different 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:
<p:processor name="oxf:xslt"> <p:input name="config" href="stylesheet.xsl"/> <p:input name="data" href="input.xml"/> <p:output name="data" id="my-output"/> </p:processor>
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.
2.23.
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:
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:template match="a"> <x/> </xsl:template> </xsl:stylesheet>
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).
2.24.
How can I parse a string containing XML into a document that OPS 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:
<document> <xml-string><name> <first>John</first> <last>Smith</last> </name> </xml-string> </document>
Consider also the following XSLT transformation:
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:template match="/"> <xsl:copy-of select="saxon:parse(/document/xml-string)"/> </xsl:template> </xsl:stylesheet>
Running this transformation on the input document above generates the following
output:
<name> <first>John</first> <last>Smith</last> </name>
This tip is particularly useful for parsing XML strings returned by EJBs, Web
Services, or entered by a user in XForms textarea controls.
2.25.
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 the maxProcessors attribute on Tomcat 4.1 or the maxThreads
attribute on Tomcat 5 is set to a value that is much lower than the value of
the acceptCount attribute. Typically values for maxProcessor
or maxThreads are 3 for a single-CPU server or 4 for a dual-CPU server,
while the value of acceptCount 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.
2.26.
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.
2.27.
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 OPS, it
is available under the LGPL license.
2.28. 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:
<xu:message xmlns:xu="http://www.xmldb.org/xupdate">Instance of target page before XUpdate:<xu:copy-of select="/*"/> </xu:message> <xu:message xmlns:xu="http://www.xmldb.org/xupdate">Instance of this page:<xu:copy-of select="doc('oxf:instance')/*"/> </xu:message> <xu:message xmlns:xu="http://www.xmldb.org/xupdate">Action output:<xu:copy-of select="doc('oxf:action')/*"/> </xu:message>
Then as the very last instruction in the XUpdate code, add:
<xu:message xmlns:xu="http://www.xmldb.org/xupdate">Instance of target page after XUpdate:<xu:copy-of select="/*"/> </xu:message>
2.29.
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 OPS, and will get used when using oxf:xslt .
See the XSLT documentation for more information.
2.30.
Are JSR-168 portlets supported in OPS
The short answer: portlets are not officially "supported" at this time.
The long answer: there is a lot of code in OPS to support JSR-168. When
this code was written back in 2003, 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 is now used to run the examples
portal. Examples are actually using the portlet code and running as portlets,
and the examples portal is an early JSR-168 portal.
The current status is that there are some bugs in the implementation and that
due to high workload at Orbeon and lack of demand so far nobody has spent the
time to make this code work with actual JSR-168 container out there now that the
specification has been final for a while and that containers are available.
The great thing about OPS and portlets is that there is very little difference
between writing an application working in a portlet vs. a servlet. 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. OPS example
applications that run within the examples portal can be trivially made working
outside of the portal (see the BizDoc example).
The bottom line is that there is some cleanup work, compatibility testing and
documentation work to do until support for JSR-168 works robustly and is
considered "supported" in OPS. Orbeon is hoping to find a sponsor for this
work.
2.31.
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:
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:import href="oxf:/oxf/xslt/utils/copy.xsl"/> <xsl:template match="@xml:base"/> </xsl:stylesheet>
2.32.
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)
2.33.
I am getting frequent Out of Memory errors with OPS. What can I do?
Often, this is due to too many threads doing processing within OPS at the same
time. There is just a lot going on in OPS 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.
2.34. OPS Java stack traces are very long. Does that mean that performance is necessarily bad?
Java stack traces are indeed very long in OPS. 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 OPS. 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.
3. Studio FAQ
3.1.
In Studio, how can I add my own VM arguments (e.g. heap size, debugging)
3.2.
In Studio, why is the Logging Events view always empty?
-
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 OPS
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".
|