Skip to main content

XMLA endpoint

The XMLA endpoint or XMLA servlet is the webservice that allows ActivePivot to be compatible with well-known business frontends such as Microsoft Excel or Tableau.

Thanks the XMLA servlet, ActivePivot can be connected to as though it were a Microsoft SQL Server Analysis Services database.

The XMLA servlet is available through Spring configuration by importing com.qfs.server.cfg.impl.ActivePivotXmlaServletConfig (it is available by default in the sandbox project).

Binary XML

The objective of binary XML is to have a format that is quickly readable by Excel or any client that supports it.

The binary XML format is a “pre-parsed” version of an XML document.

  • Values (for example, attribute values or text nodes) are stored in a binary format, which means that a parser or a writer is not required to convert the values to and from string representations.
  • XML element and attribute names are declared once and they are later referenced by numeric identifiers. This is in contrast to the text representation of XML which repeats element and attribute names wherever they are used in an XML document.

As a result, endpoints can process binary-encoded documents many times faster than the equivalent text-encoded XML files.

The drawback is that it takes a little bit longer for the server to produce, when comparing with usual XMLA SOAP format. In our benchmark tests we noticed that it takes approximately 5% longer to produce the binary XML format.

One can configure whether the XMLA servlet is effectively offering the Binary XML format feature: by default, the feature is activated (see ActivePivotXmlaServletConfig.isBinaryEnabled()).

The binaryEnabled servlet config parameter is not enough to make such format being used in a servlet XMLA response.

Some other conditions must be fulfilled. Refer to Client-Server Content Type Negotiation.

The servlet binaryEnabled parameter offers a way to systematically disable the feature when it is set to false. On the other hand, when set to true it does not mean that any response generated by the XMLA servlet will be in binary XML.

When debugging, we often advise that one keeps the Binary XML feature disabled (then using the traditional XMLA SOAP format — MIME type txt/xml). However, one can also set the log level to FINE, which will make the servlet print the decoded XML in clear in the logs.

Detailed information about the Binary XML format can be found here.

Binary Compression

The objective of the compression algorithm is to reduce the size of the XMLA messages, including (but not only) when those messages are in Binary XML format.

One can configure whether the XMLA servlet is effectively offering the Binary Compression feature: by default, the feature is activated (see ActivePivotXmlaServletConfig.isCompressionEnabled()).

The compressionEnabled servlet parameter is not enough to make such format being used in a servlet XMLA response.

Some other conditions must be fulfilled. Refer to Client-Server Content Type Negotiation.

The servlet parameter offers a way to systematically disable the feature when it is set to false. On the other hand, when set to true it does not mean that any response generated by the XMLA servlet will be compressed.

Some general remarks about the compression:

  • Detailed information about the binary compression/decompression algorithm can be found here.
  • To debug while compression is activated, you can put the level of your logging to FINE. The decompressed XML will be printed.
  • The binary compression feature provides a 90% rate of compression on large files.
  • The binary compression can also be disabled client-side with the following options in the connection string: Transport Compression=None and Protocol Format=XML.

In-Memory Compression

When we build the XMLA response we have to generate the whole response before sending anything to the client. This is because if a failure occurs while generating the XMLA response, then the response sent to the server should be a proper XMLA failure message (and we do not want the output stream to be polluted in this case).

The response is compressed (using gzip) in memory and on the fly, in order to reduce the memory footprint while the XMLA response is constructed. That said, eventually, we have to send the unzipped message to the application container (e.g. Tomcat) output stream because any optional HTTP gzip compression negotiated by the client (via HTTP request header "Accept-Encoding") is something that is handled by the application container itself.

In short:

  • In-memory compression reduces the transient memory used before sending the full response.
  • In-memory compression does not optimize the transport phase / circumvent network performance or other low-bandwidth issues. It is simply useful in case one has issues with transient memory consumption on server side when processing queries with significant results data sizes.
  • This is something totally internal to ActivePivot and happening in-memory. It aims to minimize the footprint of the XMLA response generated in-memory by the XMLA servlet before flushing it into the application container output channel.

One can configure whether or not the XMLA servlet is effectively offering the in-memory compression feature: by default, the feature is not activated. You have to set the inMemoryCompression servlet init parameter to true to activate it.

The inMemoryCompression servlet config parameter IS enough to make the compression happen.

Servlet Response Type

The default response type of the XMLA servlet is usually automatically determined when considering possible options of binary XML and binary compression (Client-Server Content Type Negotiation). As such this servlet config parameter should usually be left alone.

However, in some specific cases, it might be useful (or even mandatory) to be able to override the default implemented logic and force the response type used by the servlet.

For instance, OLAP clients based on ADOMD.NET version 9 are expecting to receive an "empty" response type all the time. In such case, one must set the responseContentType servlet init parameter to '' (empty String).

Servlet Encoding

You can override the default servlet encoding thanks to the charEncoding servlet config parameter, for example setting it to "UTF-8".

Client-Server Content Type Negotiation

As mentioned previously in this article, the ActivePivot XMLA servlet supports the binary XML and compression features documented in MS-SSAS transport protocol specifications. However, even if they have been enabled in the servlet configuration (see Binary XML and Binary Compression), it does not mean that those features will be used systematically for any response sent by the XMLA servlet.

MS-SSAS specification also refers to the condition of Content Type Negotiation, wherein a given OLAP client and a given OLAP server must negotiate whether or not they will use binary XML (for requests? for responses?) and/or binary compression (for requests? for responses?).

This information is encoded within the HTTP header attribute called HTTP X-Transport-Caps-Negotiation-Flags, that is included in all client and server HTTP messages.

In a typical client-server connection where both the binary XML and binary compression are used by the server when producing responses (but not by the client when producing requests), an example HTTP request would include the following headers:

POST http://myhost:9090/myapserver/xmla HTTP/1.1
Content-Type: text/xml
SOAPAction: "urn:schemas-microsoft-com:xml-analysis:Execute"
X-Transport-Caps-Negotiation-Flags: 1,0,0,1,1
User-Agent: MSOLAP 10.0 Client
Host: mypchostnamestuff
Content-Length: 718
Cookie: JSESSIONID=376B0F176DFDB1B7B74B4F5056ECB93E; BCSI-CS-50E42EC723C64FC7=2

The value 1,0,0,1,1 means that the "negotiation is over" (the first "1") and that the server can generate binary XML (the before-last "1") and binary compress the data (the last "1"). As mentioned in the specification, there always is a negotiation phase (when the first digit is a "0" instead of a "1"), which corresponds to the first client-server exchanges made during a XMLA session (the definition of a XMLA session here is very variable, depending on the client and server involved).

  • During the negotiation phase all the communication is done by traditional XMLA SOAP "clear" message (MIME type text/xml), unless some HTTP compression is also used on the web-application host.
  • Once the negotiation phase is over the behavior will depend on what has been negotiated.

In ActivePivot use cases, only the server may use binary XML and/or binary compression when generating responses: we don't support clients using binary XML and/or binary compression when generating requests. So, we end up with 4 possible MIME type for the ActivePivot XMLA servlet responses:

  1. binary XML off, binary compression off: MIME type = text/xml
  2. binary XML on, binary compression off: MIME type = application/sx
  3. binary XML off, binary compression on : MIME type = application/xml+xpress
  4. binary XML on, binary compression on : MIME type = application/sx+xpress