Endeca MDEX Engine Web Services and XQuery Developer's Guide Version 6.2.2 • March 2012 Contents Preface.............................................................................................................................9 About this guide............................................................................................................................................9 Who should use this guide............................................................................................................................9 Conventions used in this guide.....................................................................................................................9 Contacting Oracle Endeca Customer Support............................................................................................10 Chapter 1: Introduction............................................................................11 Overview of Web services and XQuery for Endeca....................................................................................11 How the pieces of Web services and XQuery for Endeca work together............................................12 Using XQuery with the MDEX Engine.................................................................................................13 Why XQuery?.............................................................................................................................................14 Impact on Endeca application development...............................................................................................15 Obtaining more information about XQuery.................................................................................................16 Obtaining more information about Web services........................................................................................16 About this release of Web services and XQuery for Endeca......................................................................17 Changes since the 6.1.2 release.........................................................................................................17 What's not in this release.....................................................................................................................17 Performance expectations for this release...........................................................................................18 About the examples used in this guide................................................................................................18 About connecting Web browsers to your MDEX Engine.............................................................................18 Chapter 2: Getting Started with Web Services and XQuery for Endeca.19 Dgraph flags that control XQuery use.........................................................................................................19 Setting up your XQuery for Endeca directory.............................................................................................20 Determining file location in module import..................................................................................................20 Developer checklist.....................................................................................................................................20 Performance expectations for Web services...............................................................................................21 Exposing XQuery main modules as Web services.....................................................................................21 Web services and XQuery for Endeca example.........................................................................................22 An example XQuery main module.......................................................................................................22 Example request and response bodies...............................................................................................25 Using the MDEX Web service.....................................................................................................................25 About the MDEX Web service.............................................................................................................25 Inputs and outputs of the MDEX Web service ....................................................................................26 Invoking the MDEX Web service.........................................................................................................29 About the mdex.wsdl file......................................................................................................................31 Requesting the WSDL.........................................................................................................................31 Namespaces used by the MDEX Web service....................................................................................31 Supported binding generators for the MDEX Web service..................................................................31 Exception handling in the MDEX Web service....................................................................................32 Returning non-MAX XML in the MDEX Web service...........................................................................36 Using the exquery command-line tool........................................................................................................36 Application debugging with exquery....................................................................................................37 Exquery usage.....................................................................................................................................37 Exquery access to environment variables...........................................................................................37 Chapter 3: Web Services and XQuery Components and Features......39 Implementation-defined behavior in XQuery for Endeca............................................................................39 Static type checking.............................................................................................................................39 Troubleshooting static type system errors...........................................................................................41 fn:doc() behavior..................................................................................................................................42 fn:error() behavior................................................................................................................................42 fn:trace() behavior................................................................................................................................43 fn:replace() behavior............................................................................................................................43 xs:integer precision details..................................................................................................................44 xs:decimal precision details.................................................................................................................44 iii xs:string length limitation.....................................................................................................................44 System response to integer overflow...................................................................................................44 Default ordering mode for an empty sequence....................................................................................44 Treatment of external functions............................................................................................................44 Treatment of options............................................................................................................................44 Treatment of extra digits in numeric operations...................................................................................44 Treatment of collation..........................................................................................................................44 Treatment of illegal characters in XML.................................................................................................45 Casting strings to xs:decimal ..............................................................................................................45 XQuery try/catch expressions..............................................................................................................45 Optimizations and error message details...................................................................................................45 Tips for optimizing XQuery..................................................................................................................46 Impact of optimizations in the Endeca XQuery evaluator....................................................................47 Treatment of unused variables in let statements.................................................................................48 Error message details..........................................................................................................................48 About functions...........................................................................................................................................48 Built-in functions..................................................................................................................................49