Getting Started

Introduction

This document provides developers with simple documentation for getting started with Phoenix. For information about the overall structure of Avalon Framework (on which Phoenix is based), please refer to the Framework documentation.

Instructions for downloading and installing Phoenix can be found on the Install document.

More detailed instructions will be added to this document in the future. Feel free to send in patches ;)

View Detailed API Documentation

To generate a full set of detailed API documentation for Avalon, go to the base directory of source distribution and run the appropriate build script for your platform with the parameter 'javadocs'. > build.[bat|sh] javadocs

Run the HelloWorld example

After you have successfully built Phoenix, you can verify that it has compiled correctly by running the HelloWorld demo Service Application.

Firstly you will need to get the demo-helloworld.sar file and drop it into the apps directory of Phoenix. Currently it needs to be built from CVS - http://cvs.apache.org/viewcvs/avalon-apps/demo/.

Then fire up phoenix with the following command: > bin/run.[bat|sh]

Next, fire up your favorite webbrowser and point it to http://localhost:8999/, where localhost is the network name of your machine ("localhost") should work on all windows platforms.
If all goes well, you will see something like the following: Hello World! Requests so far = 1 you are 127.0.0.1 at 127.0.0.1

This shows that Phoenix has unpacked and launched the server application contained within the demo-helloworld.sar file. If you close and relaunch Phoenix, it should restart the application.

As examples go this is a fairly simple one. You should ignore the altrmihelloworldserver, rmihelloworldserver and soaphelloworldserver packages as they are retrofitting the helloworld demo with remote capability using three technologies. HelloWorld uses connection management from the Avalon-Cornerstone project, which is good as it allows us to share connection pooling across multiple servers.

The Phoenix Developer Kit - A different example

This self contained kit could be considered a starter project for someone wanting to make a Phoenix compatible application. The idea is that you start with this skeleton including Ant build script and then add in more and more as your se code to copy from elsewhere.

This also demonstrates that it is possible to make a server application that is dual mode. Dual mode to us is the ability for the server application to run inside Phoenix and to stand-alone from the command line. It is a little bit of a sleight of hand as the codebase would be zipped into two forms - the sar file for phoenix and a jar file for standalone.

The Phoenix development kit originates in Phoenix's CVS. When you have that file, unzip it and immediately launch ant to make the jars and sars. There are four:

  1. phoenix-demo.sar - the server app in Phoenix form
  2. phoenix-demo-block.sar - used inside the sar
  3. phoenix-demo-client.sar - a client app to test the server
  4. phoenix-demo-server.sar - the server app in standalone form

The Server app in standalone mode after being tested with the client app(see below): java -jar phoenix-demo-server.jar PDK Demo listening on port 7654 Ctrl-C to exit String passed = Hello!!!!! The Server app running inside Phoenix and after being tested with the client app (see below): Phoenix 4.0a4 Server started on port 1234 String passed = Hello!!!!! The client application being used to poke the server : java -jar phoenix-demo-client.jar localhost 7654 Hello!!!!! (Change the port to 1234 from 7654 to poke the in-Phoenix server).

Note - because of the need to make this dual mode, the PDK does not use Cornerstone components. We normally recommend that people should reuse components from cornerstone as the potential for sharing will be much higher.

by Phoenix Documentation Team, Leo Simons, Paul Hammant