XQuery In Workshop

By FB2

Saturday, January 24, 2004

My current development platform, the WebLogic 8.1 Platform, uses XQuery as one of the key technologies enabling rapid development for the J2EE platform. XQuery is mainly used for XML document transformation related to Business Processes and Workflows, and for binding XML to Java code for Web Services.

I'm not going to do a WebLogic Workshop tutorial here, you can find some of those on the BEA web site. To get the basics for XQuery, please read my XQuery article first. There's a very long and detailed tutorial about Processes installed with WebLogic Workshop, but this article focuses on how we can apply our XQuery skills.

Acquiring and basics

To get the WebLogic Platform, you'll need to download it from the BEA web site. You're probably also going to need to upgrade your PC: my suggestion is to have a minimum of 1 G of memory in your development machine. You can play around with some of the features of Workshop even on half a gig of memory, but eventually as your application grows, the swapping and the out-of-memory errors will turn your life into living hell.

If you've downloaded the Platform, all you need to do is to press the "Next" button throughout the installation wizard. My suggestion is to download the full installer, instead of the download-on-demand net installer, and share the (almost 500 megs) package with your colleagues. Otherwise everyone will individually download the huge files from bea.com.

Before actually launching Workshop to develop our XQueries, we need to create a WebLogic Server domain, which will host our code. As we're playing around with Business Process-related functionality, we should create a so-called "Integration" domain. This will ensure that all the required components and libraries will be available for our project. To do this:

Now we have a WebLogic domain for our project. The wizard even placed a shortcut in the Start Menu to launch the server - but we don't need it, Workshop will take care of launching/stopping the domain, and the deployment process.

Work the Shop

Launch WebLogic Workshop, and create a new Application (File/New.../Application) - select a Process Application.
In Workshop land, an Application is just a container for Projects, which is funny,  because everywhere else a Project is a container for one or more actual applications. Anyway, for our exercise, we need to create a new Project, specifically a Process Project.

If you have the new Process Application, with a Process Project in it, we can continue with an overview of the Transformation features of Workshop. We will try do recreate the same transformation as in the previous XQuery article. We will take my DVD movie list, maintained in an XML file by the DVDAttache application, and we will produce formatted HTML output, which can be published on my web site.

Transformations

For data transformations, Workshop has support for multiple source types:

Here's a nice image from the Workshop manual describing the possible input formats and the transformation process:

These transformations, including the associated meta-data, are defined in Transformation Control files. Each Transformation Control file can have multiple, annotated Transformation Methods. Each method describes a transformation. These are the important attributes for us:

My First Transformation Control

To get started with our first transformation, we need to do the following:

I always try to do these exercises with "Real Life" examples, so let's bring up the DVD list XML document from my previous XQuery article. With the help of XMLSpy (which is optionally installed with Workshop), I've created a dvd.xsd file to describe the document structure.

  1. We need to copy this XSD file into the Schemas project directory. When the XSD file is dropped in the Schemas project, Workshop will compile the schema into XMLBeans classes, which is a subject of a different article. The point here is that the Schema should be known to the Workshop environment.
  2. In the previous article, we've generated HTML output from the list of DVD movies. To do that, it's obvious that we should just use the XHTML XSD file available from w3c.org, however the compiler in Workshop chokes on that file. I used a cheat: I just took the HTML output generated by the previous article's XQuery script, and I loaded it up into XMLSpy as an XML document, then I generated a matching XSD file automatically from XMLSpy. I called it mini-html.xsd. Copy this new XML Schema file into the Schema project.
  3. My Process project is called "test", and I've also created a transforms folder in this Process project, which will contain our new Control. You can create new folders by right-clicking on the project, select New, then folder.
  4. Once the Project/folder structure is done, in the transforms folder, right-click and select New > Transformations File.
  5. After the creation of the new Control, Workshop will open it in Design View. Use the tabs to switch between Design and Source Views during the exercise. To add our new method, just drag and drop a new Transformation Method from the Palette to the body of our Control. Give a descriptive name to the method.

Now we have all the required elements in place. Make sure that your Application structure view is similar to mine, displayed in the image on the right.
You should have the dvd.xsd file in the Schemas project, and the Process Project should contain the Transformation Control.

Now we just need to get our XQuery done.

XQuery Creation

Workshop has a visual drag-and-drop mapping tool to create XQuery transformations.

To associate the .xq file with our Control, right-click on the Transformation Method's name, and select Configure XQuery Transformation Method from the popup menu. A new dialog will pop up, which will allow us to define some parameters for our query.

These are the parameters we need to configure:

Full sized imageNow something very cool pops up - a visual editor, where you can map nodes, and attributes from your source schema to the target schema. It also allows you to assemble XQuery statements from the palette of built-in functions. I was able to quickly map the <dvdlist> source node to the root element of the HTML output, the <table> node. Then I was able to map the list of <dvd> nodes into a list of <tr> nodes in the result document. The next step was to assign a <td> output node, containing an <img> with the src attribute containing the value of <smallImage> for each DVD cover.

You can review the generated XQuery script in the Source View of the editor.

Unfortunately the visual approach breaks down on anything more complex than a one-to-one mapping. I need a separate <td> node for my movie image, and the rest of the information should be located in a separate column, which would actually contain a new <table>. Once I added a new <td> into the XQuery document, the visual mapper was not able to parse the structure, so I was not able to continue using the Designer.

Still, using the Source View of the editor, I've quickly copy-pasted the XQuery document from my previous article. I had to update several items:

Throughout the editing process, the Source Editor highlighted all the structural errors in the output XML document, and in the semantic errors in the XQuery script, so even without the visual mapper, development is certainly easier than with a simple text editor.

Here's the end result:

Running the Query

Now that we have an XQuery, it'd be nice to see the actual results of a transformation.  If we'd develop a real application, probably we'd create a Web Service, which would invoke our Business Process, which in turn would invoke the transformation using the XML document received with the Web Service call. Then we'd develop a Web Service client, or we could use the test client Workshop would generate for our Web Service.

However, for our purposes, the easiest way to see the result of the XQuery is the Test View of the XQuery Editor.

Test View

If you switch the Editor to Test View, the left pane describes the source XML document for the transformation - by default, Workshop generates a simple XML based on the XSD schema, but we can select a real document with the "Import..." button. I've loaded up my real DVD list. When you import the document, it will be validated against the schema.
The right side of the window contains the XQuery transformation results. You can select between the XML Design view - the structural view of the XML document, and a syntax-highlighted text view. After loading up the source document on the left panel, press the Test button on the right side.

Now, here comes the funny part - the XQuery scripts need to be executed inside a running WebLogic server instance, so Workshop will automatically start up your WebLogic domain, sucking up most of the resources of your PC. An "empty" WebLogic Integration domain will eat up something like 350-400 megs of memory...After launching the Server, it will remain running, until you stop it, or until you close Workshop, so the subsequent XQuery test runs will be quite fast.

I've just copy-pasted the output XML view into notepad, and saved it as a HTML document. No surprises - the XQuery engine produced the expected HTML output. I think it's fair to say that we've been using a cannon to shoot a bird - the point here is that doing XQuery development in Workshop is well-supported by the IDE, and we haven't even touched advanced topics yet: how you can invoke Java methods from your Controls in the XQuery script, and how you could take advantage of these XQuery transformations in a complex J2EE application.

Another useful feature of WebLogic Workshop

With Workshop, you need a high-end development PC to do even the simplest things - so if you've been unsuccessfully trying to convince your boss that you need a new PC, install Workshop, and ask your boss to watch you work with it for 5 minutes. The GUI and the Visual designers will dazzle him, but the need for that new PC or laptop will be apparent. He will have an easier time to open his wallet, with the visions of improved productivity, drag-and-drop development, and buzzword compliancy clouding his judgment.

Good luck!