openamf/docs openamf.texi,NONE,1.1 version.texi,NONE,1.1

Update of /cvsroot/openamf/openamf/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv19163

Added Files:
	openamf.texi version.texi 
Log Message:
Add first draft of Texinfo documentation


--- NEW FILE: openamf.texi ---
\input texinfo @c -*-texinfo-*-
@comment ========================================================
@comment %**start of header
@setfilename openamf.info
@include version.texi
@settitle OpenAMF
@setchapternewpage odd
@setcontentsaftertitlepage
@finalout

@c =========================================== macro definitions
@c (these were appropriated from the Autoconf manual)

@c A simple macro for optional variables.
@macro ovar{varname}
@r{[}@var{\varname\}@r{]}
@end macro

@c A simple macro for optional variables with a default value.
@macro dvar{varname, default}
@r{[}@var{\varname\} = @samp{\default\}@r{]}
@end macro

@c I don't like the way URL are displayed in TeX with @uref.
@ifhtml
@macro href{url, title}
@uref{\url\, \title\}
@end macro
@end ifhtml
@ifnothtml
@macro href{url, title}
\title\@footnote{\title\, @url{\url\}.}
@end macro
@end ifnothtml

@c Define an environment variable index.
@defcodeindex ev
@c Define an output variable index.
@defcodeindex ov
@c Define a CPP variable index.
@defcodeindex cv
@c Define an Autoconf macro index that @defmac doesn't write to.
@defcodeindex ac
@c Define an Autotest macro index that @defmac doesn't write to.
@defcodeindex at
@c Define an M4sugar macro index that @defmac doesn't write to.
@defcodeindex ms
@c Define an index for *foreign* programs: `mv' etc.  Used for the
@c portability sections and so on.
@defindex pr

@c Define an index for functions: `alloca' etc.  Used for the
@c portability sections and so on.  We can't use `fn' (aka `fnindex),
@c since `@defmac' goes into it => we'd get all the macros too.

@c   FIXME: Aaarg!  It seems there are too many indices for TeX :(
@c
@c   ! No room for a new @write .
@c   l.112 @defcodeindex fu
@c
@c   so don't define yet another one :(  Just put some tags before each
@c   @prindex which is actually a @funindex.
@c
@c   @defcodeindex fu
@c
@c
@c   @c Put the programs and functions into their own index.
@c   @syncodeindex fu pr

@comment %**end of header
@comment ========================================================

@c =========================================== end macro definitions

@copying

This manual is for the OpenAMF project
(version @value{VERSION}, @value{UPDATED}).

Copyright @copyright{} 2004

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the @acronym{GNU} Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover texts
being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
(a) below.  A copy of the license is included in the section entitled
``@acronym{GNU} Free Documentation License.''

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and
modify this @acronym{GNU} Manual, like @acronym{GNU} software.  Copies
published by the Free Software Foundation raise funds for
@acronym{GNU} development.''
@end quotation
@end copying

@titlepage
@title OpenAMF
@subtitle An open source replacement for Macromedia's Flash Remoting
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Darin Wilson
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents


@ifnottex
@node Top
@top OpenAMF
@insertcopying
@end ifnottex

@c The master menu, created with texinfo-master-menu, goes here.

@menu
* Introduction::                Overview of OpenAMF
* Getting Started::             Getting up and running with OpenAMF
* Deploying OpenAMF::           Detailed deplolyment instructions
* Application Development::     Examples of coding with OpenAMF
* About OpenAMF::               Information about the OpenAMF project

@detailmenu
@strong{Detailed Node Listing}

Getting Started
* Quick Start::                 Start guide for the impatient
* Quick Start Detail::          Detailed explanation of the previous section

Deploying OpenAMF

* Deployment Options::          Using OpenAMF with or without an existing app
* External Dependencies::       Libraries that OpenAMF works with
* Logging::                     OpenAMF's logging mechanism
* Config File Reference::       All about OpenAMF's configuration file

Application Development

* A Simple Example::            A simple server echo
* Using Custom Objects::        How to send and receive custom objects
* Using EJBs::                  An EJB example
* Using The Advanced Gateway::  Advanced server-side features

About OpenAMF
* Support::                     How to get help
* Getting Involved::            How to contribute to the project
* Credits::                     Who made it all happen
* License::                     Legal mumbo jumbo

@end detailmenu
@end menu

@c ============================================================= Introduction.

@node Introduction
@chapter Introduction

OpenAMF is a free, open-source alternative to Macromedia's Java Flash Remoting. It is as capable of providing application services to Flash MX as Macromedia's proprietary solution.

This project began as a Java port of @href{http://www.amfphp.org, AMF-PHP}.

@c ========================================================== Getting Started

@node Getting Started
@chapter Getting Started

Before learning about how to use OpenAMF in your applications, you should confirm that your system is correctly set up. This section will take you through the steps needed to get OpenAMF up and running. 

@menu
* Quick Start::                 Start guide for the impatient
* Quick Start Detail::          Detailed explanation of the previous section
@end menu

@node Quick Start
@section Quick Start

@enumerate
@item
Deploy openamf.war to your Java servlet container

@item
Point your browser to http://localhost:8080/openamf/examples/client2.html

@item
Click the "Add Person" button in the left window of the Flash app

@item
Get "Get With Name" in the right window
@end enumerate

You should see the address info for "Bob Monkeyman" appear in the right pane.


@node Quick Start Detail
@section Quick Start Detail

@enumerate
@item Make sure you have a working Java servlet container.

You need Tomcat, JBoss or a comparable J2EE application server set up and working to use OpenAMF. Tomcat can be obtained @href{http://jarkarta.apache.org/tomcat,here}, JBoss can be obtained @href{http://www.jboss.org, here}. Follow the instructions included with the installation and make sure the application is working correctly before continuing.

@item Deploy openamf.war

Copy the openamf.war file to the directory your servlet container uses to deploy web applications. If you're using Tomcat, this directory is called "webapps"; if you're using JBoss, this directory is called "deploy".

@item Point your browser to http://localhost:8080/openamf/examples/client2.html

This assumes that you've installed your servlet container on localhost and that it's configured to listen to port 8080. The default setup may vary between applications - check your servlet application's documentation if the above URL does not work.

@item Click the "Add Person" button in the left window of the Flash app

If your servlet application is not listening on localhost:8080, change the "Gateway Path" edit field to reflect the correct server and port

@item Get "Get With Name" in the right window

If the information for "Bob MonkeyMan" appears, then your setup is correct
@end enumerate

If any of the above steps fail, check that your browser is Flash-enabled and that the URL in the test app is pointing to is correct host and port.


@c ======================================================== Deploying OpenAMF

@node Deploying OpenAMF
@chapter Deploying OpenAMF

This section provides more detailed information about OpenAMF deployment and configuration. If you followed the steps in @ref{Getting Started} and have confirmed that your setup is working correctly, you can skip this section and go straight to @ref{Application Development} to learn about how to use OpenAMF in your applications. You can return to this section later if you are curious about how to fine-tune your deployment. 

@menu
* Deployment Options::          Using OpenAMF with or without an existing app
* External Dependencies::       Libraries that OpenAMF works with
* Logging::                     OpenAMF's logging mechanism
* Config File Reference::       All about OpenAMF's configuration file
@end menu

@node Deployment Options
@section Deployment Options

The simplest way to start using OpenAMF is to deploy the openamf.war file in your servlet container (as described in "Getting Started"). This creates a web application in your server called "openamf" which provides the gateway servlet needed to expose Java services to your Flash clients.
 
You can also add OpenAMF capabilities to an existing web application. This is useful if you want to make other servlets available from within the same application. To add OpenAMF to an existing application:

@enumerate
@item
Copy openamf.jar to the WEB-INF/lib directory of the application you want to add OpenAMF to

@item
Copy /src/web/WEB-INF/openamf-config.xml to your WEB-INF directory

@item
Copy /src/web/WEB-INF/build-webservice.xml to your WEB-INF directory

@item
Add an entry to your WEB-INF/web.xml file. Here's an example:
@end enumerate

@example
	<servlet>
		<servlet-name>DefaultGateway</servlet-name>
		<display-name>DefaultGateway</display-name>
		<description>DefaultGateway</description>
		<servlet-class>org.openamf.DefaultGateway</servlet-class>
		<init-param>
			<param-name>OPENAMF_CONFIG</param-name>
			<param-value>/WEB-INF/openamf-config.xml</param-value>
			<description>Location of the OpenAMF config file.</description>
		</init-param>
	</servlet>

	<servlet-mapping>
		<servlet-name>DefaultGateway</servlet-name>
		<url-pattern>/gateway</url-pattern>
	</servlet-mapping>
@end example
	
NOTE: If you choose to deploy OpenAMF in this fashion, the you'll need to change the URLs that appear in the following examples to reflect your set up. For example, if you've added openamf.jar to a web application called "my-app", then your Flash clients would use this URL as its gateway:

http://localhost:8080/myapp/gateway



@node External Dependencies
@section External Dependencies

The OpenAMF Project makes use of several other open source projects.  Depending 
on your planned use of OpenAMF you will need to include different jar files in 
your WEB-INF/lib directory.  

If you are not sure which to add you can add them all; the only side effect will 
be the increased size of your war file.

@strong{Basic Use - DefaultGateway}

The DefaultGateway is the simplest way to use OpenAMF. It is designed to be a drop-in replacement for Macromedia's propietary Java Flash Remoting. The DefaultGateway needs the following dependencies:

@table @samp
@item @href{http://carbonfive.sourceforge.net/astranslator/api/com/carbonfive/flash/package-summary.html#documentation, astranslator.jar (1.5.6)}
Used to translate ASObjects to JavaBeans and other type conversion

@item @href{http://jakarta.apache.org/commons/digester.html, commons-digester.jar (1.5)}
Used to parse the opeanamf-config.xml file

@item @href{http://jakarta.apache.org/commons/logging.html, commons-logging.jar (1.0.3)}
Used for generic logging

@item @href{http://jakarta.apache.org/commons/beanutils.html, commons-beanutils.jar (1.6.1)}
Used de/serializing of JavaBeans

@item @href{http://jakarta.apache.org/commons/collections.html,commons-collections.jar (2.1)}
Dependency of commons-beanutils.jar

@item @href{http://jakarta.apache.org/commons/lang.html,commons-lang.jar (1.0.1)}
Used for J2SE 1.3 compatible nested exceptions
@end table

@strong{AdvancedGateway}


This is an extension of the DefaultGateway that allows for advanced configuration and abstraction of services. See @ref{Using The Advanced Gateway} for a more detailed description of this feature.

The AdvancedGateway needs the same dependencies as the DefaultGateway, plus: 

@emph{for web services:}@*
@href{http://ws.apache.org/axis/, axis.jar (1.1)}@*
@href{http://ws.apache.org/axis/, saaj.jar}@*
@href{http://www-124.ibm.com/developerworks/projects/wsdl4j/, wsdl4j.jar}@*
@href{http://jakarta.apache.org/commons/discovery.html, commons-discovery.jar}@*
@href{http://ws.apache.org/axis/, jaxrpc.jar}@*

@emph{other:}@*
commons-httpclient-2.0-rc2.jar (2.0 RC2)@*
ant.jar (1.5.4)@*
servlet.jar (2.3)@*
mysql-connector-java-3.0.6-stable-bin.jar @*
jboss-j2ee.jar (?)@*
jboss-jmx.jar (?)@*

[@strong{TODO:}: check all urls; provide explanations for advanced gateway dependencies;provide more explanation of "other:" (??)]


@node Logging
@section Logging

The OpenAMF project makes use of the Apache Jakarta commmons-logging project 
for its logging. This allows us to work with any of the popular logging systems such as log4j or java.util.logging in J2SE 1.4

@strong{Logging config for JBoss}@*
To view debug log messages while using JBoss you will need to modify 
the @code{@{JBOSS_HOME@}/server/default/conf/log4j.xml} file
@enumerate
@item
First look for this:
@example
  <appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
    <param name="Threshold" value="INFO"/>
    <param name="Target" value="System.out"/>

    <layout class="org.apache.log4j.PatternLayout">
      <!-- The default pattern: Date Priority [Category] Message\n -->
      <param name="ConversionPattern" value="%d@{ABSOLUTE@} %-5p [%c@{1@}:%L] %m%n"/>
    </layout>
 </appender>
@end example

@item
Change the Threshold to DEBUG

@item
Then further down in the file add this
@example
  <category name="org.jboss">
    <priority value="INFO"/>
  </category>
  <category name="org.openamf">
    <priority value="DEBUG"/>
  </category>
@end example
@end enumerate

@strong{Logging config for Tomcat}@*
To view debug messages while using Tomcat you will need to 
set the @code{CATALINA_OPTS} environment variable to:
@example
"-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog -Dorg.apache.commons.logging.simplelog.defaultlog=debug"
@end example

After setting the environment variable you will need to restart Tomcat. All the debug message will be sent to the @code{@{TOMCAT_HOME@}/logs/catalinia.out} file



@node Config File Reference
@section Config File Reference

This section describes the various configuration options available in the openamf-config.xml file.

@strong{amf-serializer/force-lower-case-keys}@*
If set to true, OpenAMF will convert all property names to lower case when objects are sent from the server to the client. This is consistent with the behavior of Flash Remoting and generally presents no problem if you're using ActionScript 1.0, as it is not case-sensitive. ActionScript 2.0 is case-sensitive, however, so if you're using it, you should set this flag to "false" to make sure your objects are deserialized correctly.

@strong{invoker}@*
If you are using the "DefaultGateway" the invoker is selected 
by looping thru all the invokers in the order they are listed in the 
config file.  Then creating an instance of the class and calling 
the supports() method.  If supports returns true, the 
invoker is selected and invoked.  The response is then 
sent to the client.

If you are using the "AdvancedGateway", you get to select 
the Invoker your self using the "service/invoker-ref" element.

@itemize @bullet
@item
@strong{name}@*
Used to name the invoker, this is the name you use in 
the "service/invoker-ref" element.

@item
@strong{class}@*
The class that provides an implementation of the invoker.  
This class must extend org.openamf.invoker.ServiceInvoker.
@end itemize

@strong{service}@*
This is only needed if you are using the AdvancedGateway.

This is how you can map the call coming from the client to 
some server side code. Using the "AdvancedGateway" the 
client can use simple names such as "Directory" and then you 
can map that call to a Java class named 
"org.openamf.test.Directory".  

Later on in development if you want to use a different class you 
only have to change the openamf-config file.  The client doesn't 
need to know about the change.  You could even switch from 
using a POJO to using a EJB, Web Service, MBean, or something 
else if you create a new invoker.  

@itemize @bullet
@item
@strong{name}@*
The name that the client will use when calling the service

@item
@strong{service-location}@*
The class name, jndi name, url, or JMX ObjectName that will be 
used to locate the service implementation.

@item
@strong{invoker-ref}@*
The name of the Invoker to use.

@item
@strong{method}@*
At least one method element is required.  If you want the client to be 
able to call any method on the service just set the name element to "*". The method element has 3 sub-elements name, parameter, 
and state-bean-ref.

@itemize @minus
@item
@strong{name}@*
The name of the method that the client uses and that is called on the 
service.  This can be a "*" to match all method name of the exact method 
name such as "addPerson".

@item
@strong{parameter}@*
Used to specify the parameter of the method for matching purposes.  
Most of the time you will set the method/parameter/type element to "*" to 
indicate an parameters.  You could use the parameter element to restrict 
access to a method based on the parameters.

@item
@strong{state-bean-ref}@*
The name of the state-bean that this method uses.  
@end itemize

@end itemize

@strong{state-bean}@*
To use state-bean you must use the "AdvancedGateway".

State Beans are used to pass state between Service calls.  A state bean 
is just a simple Java Bean that is stored in the web container's Session 
or Application for you.  All you have to do to use state-beans is create 
a simple java bean, make it the last parameter of your method, and 
then configure the openamf-config.xml file.

@strong{pageable-recordset/initial-data-row-count}@*
Used to set the number of rows to return by default.  With Macromedia's remoting 
I think this is hard coded to 25.

@strong{custom-class-mapping}@*
With this new feature you can map a custom class to 
a java class in then openamf-config.xml file.  This way when 
you use Object.registerClass use can use a simple name
such as "Person" and then have it translated to a specific java 
class such as "org.openamf.test.Person".
 
This also works in reverse direction so you can when a java class
class is serialized it can be registered to a flash custom class and all 
the methods will be available.

@itemize @bullet
@item 
@strong{java-class}@*
The name of the Java class to map to the Flash Custom Class. 

@item 
@strong{custom-class}@*
The name of the Flash custom class

@end itemize


@c ====================================================== Application Development

@node Application Development
@chapter Application Development

This section provides a series of examples that will demonstrate how to use the various features of OpenAMF. The examples build on each other and becoming increasingly complex throughout this chapter.

@menu
* A Simple Example::            A simple server echo
* Using Custom Objects::        How to send and receive custom objects
* Using EJBs::                  An EJB example
* Using The Advanced Gateway::  Advanced server-side features
@end menu

@node A Simple Example
@section A Simple Example

[@strong{TODO:} code this example]

The "echo" demo provides a very simple client-server application: the server simply echoes the text sent to it by the client. To see it in action, point your browser to http://localhost:8080/openamf/examples/echo.html. Type some text into the "echo this" box and click "send" (you may need to change the "server url" value, depending on how your server is set up). The text is sent to OpenAMF and returned back to the client; the result is displayed in the "response" box.

You can view the client code by opening the echo.fla file in Flash MX. The client code is exactly the same as if it were connecting to a Flash Remoting server:

[@strong{TODO:} add client code here]

The server code is also very simple. All of the work happens in the EchoServer class:

[@strong{TODO:} add server code here]

When the client connects to the server, the gateway servlet locates the EchoServer class and invokes the echoText method. To implement simple services such as this one, you need only to create a class to provide services to clients. OpenAMF handles all of the client/server traffic for you.

@node Using Custom Objects
@section Using Custom Objects

[@strong{TODO:} modify client2 example to include a method that returns a single Person instance; also make "address" a custom object to demonstrate nested custom objects]

The "echo" demo was very simple to implement as the only data type that was sent between the client and the server was a String. Flash Remoting and OpenAMF automatically convert some data types for you - a full list of recognized data types can be found here [@strong{TODO:} find a url for this]. These data types will suffice for many applications, but it's more than likely that you'll want to use your own custom objects in client/server communications. The "client2" demo shows how to do this. 

For your objects to be serialized and deserialized properly, you must set them up correctly on the client side and the server side. The easiest way to do this is to create ActionScript classes for the client and Java classes for the server that mirror each other. When setting up these classes, make sure you observe the following:

On the ActionScript side:
@itemize @bullet
@item
the class must be accessible by the client application

@item
the class must contain properties (i.e. fields) that match the properties in the corresponding Java class. The "implicit get/set" feature of ActionScript will not suffice in this context: the class must have a named property for the transfer to work.

@item
it must have a default constructor (i.e. a constructor that takes no parameters)

@item
[@strong{TODO:} anything missing here?]

@end itemize

@emph{A note on case-sensitivity:} ActionScript 1.0 is not case-sensitive; ActionScript 2.0 is. By default, OpenAMF converts object property names to lower case when sending them from the server to the client - this is consistent with the behavior of Flash Remoting [@strong{TODO:} is that true?], but may cause undesired results if you're using ActionScript 2.0. If you don't want this behavior, you can set the "force-lower-case-keys" property in the openamf-config.xml file to false: this will preserve the case of properties when they are sent from the server. 

On the Java side:
@itemize @bullet
@item
the class must implement the Serializable interface

@item
it must be set up according to the JavaBeans specification, i.e.

@item
it must have public get/set methods for any property values that are sent to/from the Flash client

@item
it must have a default constructor (i.e. a constructor that takes no parameters)
- others?

@item
[@strong{TODO:} anything missing here?]

@end itemize

The Person class used in "client2" application looks like this:

In ActionScript:
[@strong{TODO:} show Person class code here]

In Java:
[@strong{TODO:} Person class code]

Note that custom objects can be used within custom objects: the Person class uses the Address class as a property. Like the Person class, the Address class is implemented in both ActionScript and Java according to the rules described above.

The Directory class in Java is the "service class" in this object: the Flash client makes calls to the Directory object:

[@strong{TODO:} show Flash code here]

which transfers data using the Person class.


@node Using EJBs
@section Using EJBs

[@strong{TODO:} is there an existing EJB example?]


@node Using The Advanced Gateway
@section Using The Advanced Gateway

[@strong{TODO:} is there an existing AdvancedGateway example?]


@c ========================================================== About OpenAMF

@node About OpenAMF
@chapter About OpenAMF

@menu
* Support::                     How to get help
* Getting Involved::            How to contribute to the project
* Credits::                     Who made it all happen
* License::                     Legal mumbo jumbo
@end menu

@node Support
@section Support

Support is provided via the openamf-user mailing list. This mailing list is archived and searchable at the @href{http://sourceforge.net/projects/openamf/,OpenAMF Sourceforge page}.

To subscribe to the mailing list, sign up @href{http://sourceforge.net/mail/?group_id=77268, here}.

@node Getting Involved
@section Getting Involved

The OpenAMF project welcomes new contributors. To get involved, start by @href{http://sourceforge.net/mail/?group_id=77268, subscribing to the openamf-user and/or openamf-developer lists}.


@node Credits
@section Credits

Kevin Baker (Mission Vi Inc) : Test flash clients, OpenAMF logo and website@*
Jason Calabrese (Mission Vi Inc) : Major Enhancements, Refactoring, bug fixes@*
Pat Maddox : Initial port of AMF-PHP code@*
Adrian Roston : WebServices, debugging, and flash test clients@*
Roberto Saccon : XML data type, Stateless Session EJB's and JMX@*
Sylwester Lachiewicz : Enhancements, Refactoring, bug fixes, partial javadoc@*
Sean C. Sullivan : bug fixes, enhancements, javadoc improvements@*


@node License
@section License

OpenAMF is licensed under the @href{http://www.gnu.org/copyleft/lesser.txt, GNU Lesser General Public License (LGPL) Version 2.1}


@ignore
@node Index
@unnumbered Index
@end ignore

@printindex cp

@bye

--- NEW FILE: version.texi ---
@set UPDATED 27 April 2004
@set UPDATED-MONTH April 2004
@set EDITION 0.1
@set VERSION 0.1



-------------------------------------------------------
This SF.Net email is sponsored by: Oracle 10g
Get certified on the hottest thing ever to hit the market... Oracle 10g. 
Take an Oracle 10g class now, and we'll give you the exam FREE.
http://ads.osdn.com/?ad_id=3149&alloc_id=8166&op=click