# XML - Managing Data Exchange/Cocoon


------------------------------------------------------------------------

```{=html}
<table cellspacing=10 cellpadding=10 border=5>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<font size=4>`{=html}`<b>`{=html}Learning
objectives`</b>`{=html}`</font>`{=html}\

-   `<font size=3>`{=html} Understand the function of
    Cocoon`</font>`{=html}
-   `<font size=3>`{=html} Create a working sitemap`</font>`{=html}
-   `<font size=3>`{=html} Make available a stylesheet-formatted XML
    document`</font>`{=html}
-   `<font size=3>`{=html} Create a simple Cocoon form`</font>`{=html}
-   `<font size=3>`{=html} Create a simple XSP`</font>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
sponsored by:\
\

```{=html}
<center>
```
`<font size=3>`{=html}`<b>`{=html}The University of
Georgia`</b>`{=html}`</font>`{=html}\
\
`<font size=5 color=#990000>`{=html}`<b>`{=html}Terry College of
Business`</b>`{=html}`</font>`{=html}\
\
`<font size=3>`{=html}`<b>`{=html}Department of Management Information
Systems`</b>`{=html}`</font>`{=html}

```{=html}
</center>
```
```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
</table>
```
\
\

## Introduction

Cocoon is a product of the Apache Software Foundation. It is a powerful
server heavily based on Java and XML technology. While it does have a
command line interface, most users will be able to do everything they
need to with it simply through careful editing of a few configuration
files, formatted as XML documents. If you want to see some examples of
what Cocoon can do, go to <http://MIST5730.terry.uga.edu:8080/cocoon/>.

## Assumptions

This tutorial is set up based on the user having access to an
installation of Cocoon on Terry's Blaze server. If you do not have this
access, simply replace file locations and access methods with those
provided by your server administrator. Some programs described may be
Windows-only; you will need to find out a suitable replacement if you
are a Macintosh or Linux user, although these utilities are often
included with the operating system. JEdit is a free text editor that can
read and save files on an FTP or SFTP server as easily as on a hard
disk, and properly manipulate many different types of files, with the
proper plugins. It is available for Windows, Macintosh, some Linux
distributions and as a platform-independent Java application at
<http://www.jedit.org/>.

## The Sitemap

The primary Cocoon file to be concerned with is sitemap.xmap, located in
the root Cocoon directory. It uses XML tags to define things such as
different ways to present data, the location of important files,
identification of browsers, and the most important aspect, pipelines.
The default xmap will be fine for our purposes, and we will only need to
look at the last few lines of it, where pipeline matches are defined.
This section begins at the tag `<map:pipeline>`{=html}. A pipeline match
looks like this:

``` XML
<map:match pattern=”test”>
    <map:generate type=”file” src=”content/test.xml”/>
    <map:transform type=”xslt” src=”stylesheets/test.xslt”/>
    <map:serialize type=”html”/>
</map:match>
```

Let's look at what each line does. The first line tells Cocoon to watch
for someone browsing to
<http://blaze.terry.uga.edu:8080/cocoon/otc/test>. When this happens,
the actions on the next three lines take place. Cocoon will take the
information from the file test.xml within the content directory, and
apply the stylesheet test.xslt from the stylesheets directory. It
formats this result as an html page, as specified on the fourth line.
Cocoon can use different serializers to format data as an html or xhtml
page, flash object, pdf, or even OpenOffice document. Unlike when
working with XML for other purposes, no XSD schema is needed -- simply
create and populate fields in the XML file as necessary.

## Cocoon Forms

Cocoon forms, or CForms, are a way to use XML structure to create
validating form field objects and then arrange them in a template for
use. The primary advantage of CForms over using HTML forms is that
fields can be validated either with built-in functionality or simple XML
attributes. There are several elements required for this. A definition
XML file, which holds the fields, called \"widgets\":

``` XML
<fd:field id="email" required="true">
<fd:label>Email address:</fd:label>
<fd:datatype base="string"/>
<fd:validation>
<fd:email/>
</fd:validation>
</fd:field>
```

\
A template XML file calls on these widgets, adding HTML code to help
with look and feel:

``` html4strict
<br/>
<ft:widget-label id="email"/>
<ft:widget id="email"/>
```

A Javascript file that controls the flow of data from one file to the
next:

``` javascript
function registration() {
var form = new Form("registration_definition.xml");
form.showForm("registration-display-pipeline");
var viewData = { "username" : form.getChild("name").getValue() }
cocoon.sendPage("registration-success-pipeline", viewData);
}
```

Pipelines in the sitemap that also control flow:

``` XML
<map:match pattern="registration">
<map:call function="registration"/>
</map:match>
...
<map:match pattern="registration-display-pipeline">
<map:generate type="jx" src="registration_template.xml"/>
<map:transform type="i18n">
<map:parameter name="locale" value="en-US"/>
</map:transform>
<map:transform src="forms-samples-styling.xsl"/>
<map:serialize/>
</map:match>
...
<map:match pattern="registration-success-pipeline">
<map:generate type="jx" src="registration_success.jx"/>
<map:serialize/>
</map:match>
```

An XSP can be used in this flow in order to pass submissions to a
database.

## XSPs

XSPs function similarly to JSPs and servlets - they are server-side
applications that can support many users at once. Unlike JSPs and
servlets, XSPs can use XML tags to accomplish much of their
functionality, although they can also use Java code between
`<xsp:logic>`{=html}`</xsp:logic>`{=html} tags. One good use for XSPs is
passing information to a database or recalling and displaying stored
data. While JSPs and servlets have to either call a specific database
connector or contain all of the code for connecting within them, Cocoon
has a configuration file which holds this information, and XSPs just
call the name of the database as specified in WEB-INF/cocoon.xconf:

`<esql:pool>`{=html}`dbname``</esql:pool>`{=html}

XSP code to enter data from a form might look like this:

`  ``<esql:execute-query>`{=html}\
`  ``<esql:query>`{=html}\
`  ``INSERT into otc_users (name,email,password,age,spam) values ('``<xsp:expr>`{=html}`esc_name``</xsp:expr>`{=html}`','``<xsp-request:get-parameter name="email"/>`{=html}`','``<xsp-request:get-parameter name="password"/>`{=html}`','``<xsp-request:get-parameter name="age"/>`{=html}`','``<xsp-request:get-parameter name="spam"/>`{=html}`')`\
`  ``</esql:query>`{=html}\
`  ``</esql:execute-query>`{=html}

## Exercises

1.  Create a basic XML file and accompanying html stylesheet. Upload
    them into the proper folders (content and stylesheets respectively)
    on the Blaze server, and write a pipeline match that would enable
    you to view the XML content with your stylesheet applied in a
    browser. Files and match pattern should be named after your own
    name, for example Bob Jones would use "bjones." It is not necessary
    to upload the pipeline code - simply browse to
    <http://blaze.terry.uga.edu:8080/cocoon/otc/yourname> and it should
    be visible.
2.  Follow along with the CForms example located at
    <http://cocoon.apache.org/2.1/userdocs/basics/sample.html>. Create
    and implement at least one widget of your own making. You can view
    this at work by browsing to
    <http://blaze.terry.uga.edu:8080/cocoon/cforms/registration>.
3.  Browse to opt/tomcat5/webapps/cocoon/cforms on Blaze. Examine
    sitemap-modified.xmap to see how the pipelines could be modified to
    pass CForm data to an XSP. Test.xsp shows how that data could be
    inserted into or called from a database.

## Appendix - Accessing the Blaze server

When you have an account set up on the Blaze server, there are several
steps you will need to take in order to be able to work with files in
the Cocoon directory. Generally, new user accounts are set up with the
user's UGA MyId as the username, and social security number as the
password. This password must be changed at the user's first login, which
requires using an SSH client to accomplish. UGA students can download
Secure Shell Utilities 3.1 at <http://sitesoft.uga.edu/>. Two programs
are installed by this download, Secure Shell Client and Secure File
Transfer Client.

Open the Secure Shell client and click the "Quick Connect" button
located near the top of the window. In the resulting window, enter
"blaze.terry.uga.edu" as the Host Name, and your specified username as
User Name. Port Number should be set to "22", and Authentication Method
should be "Passworded". Click "Connect". In the resulting window, enter
your given password and click "Ok". You may see a window asking to save
the new host key, click "Yes". You will now be presented with a text
box. It will notify you that your password has expired and must be
changed. You will need to enter your given password once, hit enter,
enter your desired new password, hit enter, and again enter your desired
new password and hit enter. Be aware that nothing you type will show up
for security purposes, and you will not be able to delete any typos -
you\'ll have to log in and start over if you mess up. This is all we
will be using the Secure Shell Client application for; you can click the
"Disconnect" button in the row of small buttons at the top of the
screen, and then exit the program.

In order to actually access files on the Blaze server, the Secure File
Transfer Client is used. Open it and click the "Quick Connect" button
located near the top of the window, entering the same Host Name as with
the Secure Shell Client, your new password, and make sure the other
settings are the same. Click "Connect." You will be presented with a
Windows Explorer-type screen where you can browse through the files on
the Blaze server. To access our Cocoon installation go to the "opt"
folder, then the "tomcat5" folder, then the "webapps" folder, then the
cocoon folder. Most of our work will be done in the "otc" folder within.
To download a file for editing, simply highlight it and click the
"Download" button in the row of small buttons at the top of the screen.
Once you select a download location and click "Download." You can then
open it in your editor of choice. To upload a file to the server, simply
do the reverse -- click the "Upload" button in the row of small buttons
as the top of the screen, select a file to upload, and click "Upload,"
which will put the file in the folder you are currently viewing on the
Blaze server.

