Serving XML from Caché

Caché can serve XML data in a variety of ways by making use of the tools given in the previous topic, as well as using Caché server pages. This topic covers the following items:

Overview of what is needed to serve XML from Caché server pages (CSP)
How to create a simple XML server
How to create an XML server that serves XML documents based on objects stored within a database

You can also use Caché to create web services. For more information, see Creating Web Services and Web Clients in Caché.

Overview of Serving XML

To serve XML from Caché server pages (CSP), the requirements are as follows:

The XML server must be a subclass of the %CSP.PageOpens in a new tab class.
The content type for the server must be "text/xml". This is controlled by the CONTENTTYPE class parameter.
The OnPage() class method writes the XML document to the current device (that is, the browser).
In order to serve a Caché object as XML, that object must be XML-enabled, as described in Projecting Objects to XML. In this case, the OnPage() class method creates an instance of the %XML.WriterOpens in a new tab class and uses it to write the XML document.

Creating a Simple Caché XML Server

This section demonstrates a simple HTTP-based XML server that serves static XML content in response to incoming HTTP requests. The XML server is a subclass of the %CSP.PageOpens in a new tab class that has been extended to serve XML instead of HTML. Such a server class looks like this:

Class GXML.Server Extends %CSP.Page
{

Parameter CONTENTTYPE = "text/xml";

ClassMethod OnPage() As %Status
{
   write "<?xml version=""1.0""?>"
   write "<Person><Name>Jaynes,Janice Q.</Name>"
   write "<DOB>1959-09-03</DOB></Person>"
   quit $$$OK
}

}

This class extends the %CSP.PageOpens in a new tab class, overrides the CONTENTTYPE parameter to "text/xml" and overrides the OnPage() method to write out XML content (in this case, static content).

How the Example Behaves

If you have written a sample like the preceding, you can view it in two ways:

In Studio, if you are viewing the source, select View > Web page.
In a browser, open a URL of the following form:
```
http://127.0.0.1/csp/samples/GXML.Server.cls
```
Instead of GXML.Server, substitute your package name and class. Also substitute your root URL as appropriate.

Depending on your browser, you see either an XML tree or just text. In either case, you can use the View Source command in the browser to display the actual XML sent.

Creating the Example with the New Class Wizard

The New Class Wizard in Studio makes it easy to create code like the preceding, if you forget the details. The procedure is as follows:

Select File > New.
Select New Class Definition.
On the first page of the wizard, enter a package name and a class name.
On the second page of the wizard, specify that the new class definition is a CSP page.
On the third page of the wizard, specify that this CSP page serves XML.
Select Finish.

At this point, Studio displays a new class definition similar to this:

Class GXML.Server Extends %CSP.Page
{
Parameter CONTENTTYPE = "text/xml";

ClassMethod OnPage() As %Status
{
    Write "<?xml version=""1.0"" ?>",!
    Quit $$$OK
}
}

Then edit the OnPage() method as needed.

Serving Objects as XML from CSP

Rather than writing static XML as in the previous example, it would be more interesting to write an XML document that contains the contents of a Caché object. In order to do this, the object class must be XML-enabled; that is, it must extend %XML.AdaptorOpens in a new tab and specify any needed settings such as element names (if the defaults are not wanted). See Projecting Objects to XML.

You would also modify the OnPage() method to generate XML output, as described in “Writing XML Output from Caché Objects.” The OnPage() method should create an instance of %XML.WriterOpens in a new tab and invoke its methods to generate the output.

Modifying the XML Server Class

This section shows how a XML server class can serve XML generated from persistent objects. Here the OnPage() method writes one instance of an XML-enabled class (GXML.Person1) as an XML document. By default, %XML.WriterOpens in a new tab generates output to the current device; if called from a browser, that means the output goes to the browser

Class GXML.Server2 Extends %CSP.Page
{

Parameter CONTENTTYPE = "text/xml";

ClassMethod OnPage() As %Status
{
    set writer=##class(%XML.Writer).%New()
    set writer.Indent=1
    set obj=##class(GXML.Person1).%OpenId(1)
    set status=writer.RootObject(obj)
    if $$$ISERR(status) { quit $$$ERROR($$$GeneralError,"Error writing root object") }
    quit $$$OK
}

}

View the results by requesting the following URL from a browser:

http://127.0.0.1/csp/samples/GXML.Server2.cls

As in the previous example, this serves an XML document to the browser. In this case, the document you see corresponds to the instance of GXML.Person1 with the ID equal to 1. A more robust server could let the user choose among the existing stored objects and then would display the selected one.