donaldp 2003/04/04 14:50:18
Added: demo/src/java/org/apache/avalon/apps/demos/helloworldserver
package.html
Log:
Add helloworld docs
Revision Changes Path
1.1
avalon-apps/demo/src/java/org/apache/avalon/apps/demos/helloworldserver/package.html
Index: package.html
===================================================================
<html><body>
<h1>AltRMI HelloWorld Demo</h1>
<center>By Paul Hammant</center>
<h2>Introduction</h2>
<p>
The 'Hello World' demo server component is a socket listener app that
replies 'Hello World' to client applications that open the port. The reply is in HTML
form so can be viewed by a Browser. The HTTP headers are missing, but it still works.
Telnet is another client that can view the message.
</p>
<h2>Architecture</h2>
<p>
The following shows how the HelloWorld demo block depends on
ConnectionManager from cornerstone. These
two blocks packaged as a server application (.SAR file) are loaded and
launched by Phoenix, itself sitting on top of Avalon's framework.
</p>
<h2>Relevant source modules</h2>
<p>
The HelloWorld demo compiles as part of the build process for avalon-apps
demo. The important modules that contribute to the demo are listed here. All are
within the src directory
</p>
<ol>
<li>
<b>org.apache.avalon.apps.demos.helloworldserver package</b> This package
contains the Java source for 'Hello World' and the xinfo block descriptor.
</li>
<li>
<b>conf\avalon-demo-assembly.xml</b> This contains the assembly
instructions for the resulting server archive (sar) file.
</li>
<li>
<b>conf\avalon-demo-config.xml</b> This contains the configuration for the
resulting server archive (sar) file.
</li>
</ol>
<h2>Java Source</h2>
<h2>HelloWorldHandler.java</h2>
<p>
Instantiated and dispatched by the impl once per socket request that comes
in.
</p>
<h2>HelloWorldServer.java</h2>
<p>
The interface that's the contract for the Server block. As it happens
HelloWorld is not that resusable. If it were "ObjectDataBase.java" many server apps
could use it through this interface. The interface could set more useful things that
the greeting ("Hello", "Bonjour" etc.)
</p>
<h2>HelloWorldServerImpl.java</h2>
<p>
This like all impls implements an interface. Which interface is rather
obvious in this case. It's a standard pattern that uses other blocks (SocketManager
and ConnectionManager) to do the hard work of listening on a port, pooling threads and
connections and organizing socket invokations in a queue and multi app friendly way.
</p>
<h2>avalon-demo-assembly xml</h2>
<p>
The file is renamed as part of the build process to assembly.xml, and only has
a separate name here to aid development. The bulk of the contents of the file pertain
to other blocks including ones that HelloWorld is dependant upon. Here's the section
that's for HelloWorld
</p>
<pre>
(text snipped)
<block
class="org.apache.avalon.apps.demos.helloworldserver.HelloWorldServerImpl"
name="helloworldserver" >
<provide name="socketsection"
role="org.apache.avalon.cornerstone.services.sockets.SocketManager"/>
<provide name="connections"
role="org.apache.avalon.cornerstone.services.connection.ConnectionManager" />
</block>
(text snipped)
</pre>
<p>
Of the block element, listed attributes are the instatiatable class
implementing the HelloWorld interface (not mentioned itself in this assembly xml), the
display name of the block, and two services that HelloWorld needs.
</p>
<h2>avalon-altrmidemo-config xml</h2>
<p>
The file is renamed as part of the build process to config.xml, and only has a
separate name here to aid development. Again here is the pertinent section:
</p>
<pre>
(text snipped)
<helloworldserver>
<port>8999</port>
<bind>127.0.0.1</bind>
<helloworldhandler>
<connectiontimeout> 360000 </connectiontimeout>
</helloworldhandler>
</helloworldserver>
(text snipped)
</pre>
<p>
The configuration element named <helloworldserver> is used as it's
name suggests and is passed the blocks being used for the app. Elements port and bind
are used by the socket manager.
</p>
<p>
If you had configuration for an app, you'd specify it here in with element
and attribute names that are invented for the application.
</p>
<h2>Starting your own server project</h2>
<p>
Familiarity with Ant and it's build script would be a good place to start.
After learning how Cornerstone compiles and jars the demos would be a good second
step. Thirdly, as I've done before, take the demos out of Cornerstone, delete classes
and xml not relating to the HelloWorld server and rename from HelloWorld to whatever
suits you. I import into the lib dir avalon-cornerstone-compilation-0.x.jar to allow
things that use it to compile. I also import cornerstone-0.x.bar to the same place to
allow it's inclusion in the sar file being made. The build xml file even contains a
target that allow you to install the freshly made sar file into a nearby Avalon
installation - "build install", though for development you'll initially only be
running "build" and "build clean".
</p>
<p>
As a secondary process, it would be handy to learn xdocs (the technology
that allows the creation of these book pages). You're copying cornerstone to be
(after some selective trimming) the foundation stone for new server app, so you might
as well take adavantage of all it's templates.. "build xdocs" and look in build/docs.
All the Apache java based projects do this and then copy that to the website. The
project I'm involved with <a href="http://www.jesktop.org";>Jesktop</a> does too.
</p>
</body></html>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
