Chapter 6. "Hello World" application

Lets begin by creating a skeleton project structure for Hello World. The top level directory, in this case helloworld, can be arbitrary, though, for clarity I usually create matching package and project names. Here is what the anatomy of a simple package looks like.



helloworld
|-- package-in.xml
|-- com
|   '-- transvirtual
|       '-- examples
|           '-- HelloWorld.java
'-- resources
     |-- helloworld.xoe-config
     |-- icon.gif
     |-- index.xhtml
     |-- primary.dtd
     |-- services.xml
     '-- shortcuts.xml

Package-in.xml. Within the top level project directory is a package definition file (package-in.xml) and a resources directory. The package-in.xml file is used to define values for the package name, version number, dependencies, and other useful meta data. Refer to the Advanced Topics section for more information on package-in.xml.


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE package PUBLIC "-//TVT//DTD XOEPKG 1.0//EN" "http://www.xoe.org/DTD/xoe-package.dtd">

<package name="helloworld" version="1.0">
   <info>
      <name>Hello World</name>
      <description>An simple hello world application.</description>
      <maintainer>
         <name>Patrick Schork</name>
         <email>pschork@transvirtual.com</email>
      </maintainer>
      <copyright>
         <year>2001</year>
         <holder>Transvirtual Technologies Inc.</holder>
      </copyright>
      <licence type="Transvirtual Technologies" common="EULA" />
   </info>
   <requires>
      <dep name='xoe-servlet' predepends='true' ns='http://www.xoe.org/installer/base/package'/>
      <dep name='xhtml' predepends='true' ns='http://www.xoe.org/installer/base/package'/>
   </requires>
</packages>      

The first line in the package-in.xml file specifies the xml version and encoding to be used, in this case UTF-8 (Unicode).


<?xml version="1.0" encoding="UTF-8"?>

The second line specifies the Xoe package format DTD.


<!DOCTYPE package PUBLIC "-//TVT//DTD XOEPKG 1.0//EN" "http://www.xoe.org/DTD/xoe-package.dtd">

Next, the package begins to take form with the definition of its root element, "package". Here we have specified name and version number attributes for it, respectively "helloworld" and "1.0" for the version. These two attributes are important because they will determine the actual package filename, in this case helloworld_1.0.xoe.


<package name="helloworld" version="1.0">

The package element contains two child elements, "info" and "requires". First lets look at the info element.


<info>
   <name>Hello World</name>
   <description>An simple application.</description>
   <maintainer>
      <name>Patrick Schork</name>
      <email>pschork@transvirtual.com</email>
   </maintainer>
   <copyright>
      <year>2001</year>
      <holder>Transvirtual Technologies Inc.</holder>
   </copyright>
   <licence type="open" common="GPL" />
</info>

As you can see, the info element amounts to an "about" screen, listing the maintainer, copyright and license information. The "name" and "description" elements are important because they will be used by the package manager to give the end user information on what the package / application does.

The next element with the package is the "requires" element. Here we need to define other packages that our application will use. You can copy the "requires" definition from a TVT package.


<requires>
   <dep name='xoe-servlet' predepends='true' ns='http://www.xoe.org/installer/base/package'/>
   <dep name='xhtml' predepends='true' ns='http://www.xoe.org/installer/base/package'/>
</requires>

The first package defined within our requires element is "xoe-servlet". This package is required because our helloworld servlet will subclass it. The second package defined within our required element is "xhtml". This package is required so that our views, the .xhtml files in the resources directory, can displayed. The requires element can also contain references to conflicting packages which could prevent a package from being installed if the conflict was met. The order of the dep elements is also important.

Resources. The resources directory contains the application views, icons, localization DTDs and any other content your application may use. The resources directory is analogous to the base directory on a web server, allowing your application to reference local content and data through relative URLs.

HelloWorld Servlet. A servlet that will be used to manipulate application views and handle background logic. This version simply displays our index.xhtml file.

com/transvirtual/examples/HelloWorld.java


    /**
     * HelloWorld example
     * Copyright 2001, Transvirtual Technologies, Inc. 
     */
     package com.transvirtual.examples;
     
     import java.io.IOException;
     import javax.servlet.*;
     import javax.servlet.http.*;
     import org.xoe.servlet.XoeServlet;
     import org.xoe.servlet.XoeServletRequest;	
     import org.xoe.servlet.XoeServletResponse;
     import org.xoe.core.dom.XDocument;
     
     public class HelloWorld extends XoeServlet	
     {
       protected void doGet (HttpServletRequest req, HttpServletResponse res) 
       throws ServletException, IOException
       {     
	res.setContentType ("text/html");
	XDocument doc = getRelativeDocument ("index.xhtml");
	res.getWriter ().print (doc);
       }
     }

Once we have the hello world skeleton in place, we need to build and package our application.



  /xoe/tools/xoe_buildpackage ./helloworld

  xoe-buildpackage: building package in: helloworld/
  xoe-buildpackage: package name: helloworld_1.0.xoe
  xoe-buildpackage: maintainer: Patrick Schork <pschork@transvirtual.com>
  xoe-buildpackage: checking XML well-formedness
  xoe-buildpackage: validating package-in.xml
  xoe-buildpackage: failed to find 'rxp': skipping XML validity check	
  xoe-buildpackage: (hint: rxp is part of the rxp package)
  xoe-buildpackage: calculating build deps (cached)
  xoe-buildpackage: compiling classes
  xoe-buildpackage: installing
  xoe-buildpackage: zipping
  xoe-buildpackage: converting package-in.xml --> package.xml
  xoe-buildpackage: re-zipping
  xoe-buildpackage: saving package to: /home/pschork/projects/xoe/stash/packages/helloworld_1.0.xoe

The xoe_buildpackage script has created a package named helloworld_1.0.xoe based on our configuration. The xoe_buildpackage has also copied the new package into out default xoe/stash so that it will be available when we start the framework.

Before we run HelloWorld, lets take a look at the .xoe file that was generated. The .xoe format consists of an uncompressed zip archive.


  unzip helloworld_1.0.xoe
    extracting: com/transvirtual/examples/HelloWorld.class
    extracting: resources/icon.gif      
    extracting: resources/index.xhtml   
    extracting: resources/primary.dtd   
    extracting: resources/shortcuts.xml  
    extracting: resources/services.xml  
    extracting: resources/helloworld.xoe-config  
    extracting: package.xml             

Notice that the package-in.xml file has been changed to package.xml and has declared a new xml element, "provides".


  <provides>
    <proviso name="helloworld" ns="http://www.xoe.org/installer/base/package">
      <version>1.0</version>
      <name>helloworld</name>
      <architecture></architecture>
    </proviso>
    <proviso name="application" ns="http://www.xoe.org/installer/service">
      <functionality>application</functionality>
      <class>class com.transvirtual.examples.HelloWorld</class>
      <implements>org.xoe.services.IApplication</implements>
      <feature name="config" value="stash:/installed-packages/helloworld_1.0/helloworld.xoe-config"/>
    </proviso>
  </provides>

The provides element was generated by xoe_buildpackage and will be used by the framework to determine the packages capabilities and service offerings during installation.

Lets get HelloWorld running within XOE! To do this we need to use the Package Manager to query for our package.

  1. Start XOE with the command /xoe/tvt-make/tvt-start-xoe.

  2. Once loaded select the Package Manager application, then select Search for Packages.

  3. At the Search screen select Advanced Search.

  4. From the Advanced search screen enter "helloworld" into the Exact Name text box and uncheck the High Level Packages check box towards the bottom of the screen. Then click the Query button.

  5. Our helloworld_1.0 package should be selected in the pulldown menu, with a version number and brief description. Select install.

  6. The package is now installed.

There are a few ways we can run the Hello World application. Lets start with the most obvious way of launching it via the Program Manager.

  1. Go back to the Program Manager screen by clicking the bottom return bar. This will always return you to the Program Manager screen. You should see an icon (apple) representing our application with a text label "Hello World"

  2. Selecting the icon will load it. Doesn't do much, but hey, its a Hello World example.

  3. To make our Hello World example a little more interesting, lets launch it via the web browser. Return to the Program Manager and select the Web icon. In the URL textbox enter "stash:/installed-packages/helloworld_1.0/". Hit [ENTER] or select the Go arrow icon on the right of the URL textbox.

  4. You should see a group of files that resemble the projects original resource directory, specifically helloworld.xoe-config.

  5. Selecting helloworld.xoe-config will launch our application within the web browser.