Red5 Flash ServerReference Documentation1.0.0DanRossiPrefaceOverall Preface hereRed5 ArchitecturePart intro10/24/05Dominick Accattato(daccattato at gmail dot com)IntroductionWhat is Red5?An open source project dedicated towards the interaction between the Flash Player and a
Free Connection Oriented Server using rtmp (real time messaging protocol).
Where can I download Red5?Mirrors: http://osflash.org/red5#conference_linksWhy does Red5 exist?
Like most open source projects, the project exists because there was interest in the topic.
Even before any code was written people had been dissecting the bytes that come down the pipe
from the flash comm server and flash player interaction.
What does Red5 mean?Please read: Why "RED5"?Why is it not called Red5 Media Server?
Red5 does much more than server up media. We feel that Red5 is a technology.
What other names does Red5 go by?
Red5 aka R5
What does the Red5 logo look like?Is Red5 Legal ?
RTMP (real time messaging protocol) has been introduced to the Flash Platform as a proprietary closed source protocol.
Can we legally create source code that may unveil the true workings behind this protocol?
Yes, examining packets is not illegal. The Red5 team has stated its intent to remain completely legal in
this situation, and thanks to some outstanding developers in the Flash world,
we've never had to even consider any other alternative.
What is the outcome of this project ?
What would be the best possible scenario that could come out of this project?
Macromedia would endorse us and provide the open source community with the RTMP protocol specifications.
This would greatly help out the few who are coding “Free Servers” out there including
the Red5 open source project.
What license does Red5 use?
Red5 uses the LGPL license. LGPL licenseWhat is the estimated time of delivery for Red5 ?
Please Review: Project Roadmap.
RTMPReal Time Messaging Protocol (RTMP) Is a proprietary protocol developed by
Macromedia that is primarily used with Macromedia's Media Server product to stream audio
and video over the web.
The default connection port is 1935.
Red5 page dedicated to RTMP: http://osflash.org/rtmp_os.AMF
Action Message Format (AMF) is a binary message format designed for the ActionScript object model.
What implementations are there ?
Java and Ruby. Currently all focus has been on the Java implementation.
How mature is the Java implementation?
There is a codebase checked into subversion. The code currently uses two frameworks,
Mina and Spring discussed below. The protocol handler has been created and output of byte
information is viewable. Team members are currently testing the code and sending different rtmp
calls from the flash player to figure out how to deal with the rest of the rmtp protocol.
Why did the Red5 team choose Mina?
It allowed us to focus on the protocol, and not implementing low level nio code.
We also plan to implement other protocols / transports in the future so having a
standard framework is good.
I looked at a number of frameworks for this. Mina, EmberIO, Mule, etc.
Mina seemed to be the most focused and developed (essentially being v2 of Netty).
EmberIO is quite similar and something we should look into in the future, esp the threading
stategies but not as mature or documented as a framework. Mule seems to be message exchange /
network framework on speed. It does everything which I think is too much for our stage of development.
Why did the Red5 team choose Spring?
TODO
Which component frameworks are we currently reviewing?
Actionstep, ASwing.
What are the advantages of this framework?
TODO
What is the estimated time of delivery for these components (eta)?
TODO
Do I have to use this component framework?
TODO
Can I use Macromedia Flash Communication Server components?
TODO
What IDE (integrated development environment) are we using?
I’m using eclipse. I know a few others are too. As well, you will need to install the subversion plugin
so that you can check out the code base.
Additionally, you should install one of the actionscript plugins if you plan to do any of the front end coding.
Recommend IDE / Software
Eclipse IDE Spring IDE Eclipse Plugin ASDT Eclipse Actionscript Plugin Is there a place that we can meet and talk about the project status?
Yes, you can join a few of us developers on IRC (internet relay chat).
Connect to the irc.freenet.org server and then join room #red5
Is there a mailing list ?
Yes, red5@osflash.org.
You can find more information on the site http://osflash.org/doku.php?id=red5Where’s the best place to start?
Where’s the best place to start?
Read about the protocol. http://osflash.org/doku.php?id=red5#protocol.
Navigate the Red5 site, learn the basics behind the frameworks.
Then check out the codebase and discuss through one of the many communication channels (irc, mailing list).
If you are interested in becoming a Red5 team member please fill out the Team Signup Form and email it to the project managers.
What are the milestones ?
TODO
Who are the team members?
Project Management
Chris AllenJohn Grden
Server Side Development
Mick MerresLuke HubbardGrant DaviesFernando AugustoLucas FerreiraChris AllenAshvin SavaniYannick ConnanDominick Accattato
Release Manager
Grant Davies
Codecs/Media integration
Dominick Accattato
Client Side/API Testing
John GrdenMarcos AugustoGabriel LaetMarlos CarmoTim BeynartLucas FerreiraChris AllenAshvin Savani
Branding/Logo/Website
Tim BeynartAldo Bucchi
Documentation
Patrick Mineault (AMF documentation)John GrdenLee McColl-Sylvester2006-11-15 10:22:04 +1100 (Wed, 15 Nov 2006)JoachimBauchjojo@struktur.deMigration guide from FCS/FMS to Red5
This document describes API differences between the Macromedia Flash
Communication Server / Flash Media Server 2 and Red5. It aims at helping
migrate existing applications to Red5.
If you don't have an application in Red5 yet, please read the tutorial about
`howto create new applications`__ first.
Application callbacks
When implementing serverside applications, one of the most important
functionalities is to get notified about clients that connect or disconnect
and to be informed about the creation of new instances of the application.
Interface IScopeHandler
Red5 specifies these actions in the interface IScopeHandler_. See the API
documentation for further details.
Class ApplicationAdapter
As some methods may be called multiple times for one request (e.g. `connect`
will be called once for every scope in the tree the client connects to),
the class ApplicationAdapter_ defines additional methods.
This class usually is used as base class for new applications.
Here is a short overview of methods of the FCS / FMS `application` class and
their corresponding methods of ApplicationAdapter_ in Red5:
The `app*` methods are called for the main application, the `room*` methods
are called for rooms (i.e. instances) of the application.
You can also also use the ApplicationAdapter_ to check for streams, shared
objects, or subscribe them. See the API documentation for further details.
Execution order of connection methods
Assuming you connect to `rtmp://server/app/room1/room2`
At first, the connection is established, so the user "connects" to all scopes
that are traversed up to `room2`:
`app` (-> appConnect)`room1` (-> roomConnect)`room2` (-> roomConnect)
After the connection is established, the client object is retrieved and if
it's the first connection by this client to the scope, he "joins" the scopes:
`app` (-> appJoin)`room1` (-> roomJoin)`room2` (-> roomJoin)
If the same client establishes a second connection to the same scope, only
the `connect` methods will be called. If you conect to partially the same
scopes, only a few `join` methods might be called, e.g.
`rtmp://server/app/room1/room3` will trigger
`appConnect("app")``joinConnect("room1")``joinConnect("room3")``roomJoin("room3")`
The `appStart` method currently is only called once during startup of Red5
as it currently can't unload/load applications like FCS/FMS does.
The `roomStart` methods are called when the first client connects to a room.
Accepting / rejecting clients
FCS / FMS provide the methods `acceptConnection` and `rejectConnection` to
accept and reject new clients. To allow clients to connect, no special
action is required by Red5 applications, the `*Connect` methods just need
to return `true` in this case.
If a client should not be allowed to connect, the method `rejectClient`
can be called which is implemented by the ApplicationAdapter_ class. Any
parameter passed to `rejectClient` is available as the `application`
property of the status object that is returned to the caller.
Current connection and client
Red5 supports two different ways to access the current connection from an
invoked method. The connection can be used to get the active client and
the scope he is connected to. The first possibility uses the "magic" Red5_
object:
import org.red5.server.api.IClient;
import org.red5.server.api.IConnection;
import org.red5.server.api.IScope;
import org.red5.server.api.Red5;
public void whoami() {
IConnection conn = Red5.getConnectionLocal();
IClient client = conn.getClient();
IScope scope = conn.getScope();
// ...
}
The second possiblity requires the method to be defined with an argument of
type IConnection_ as implicit first parameter which is automatically added
by Red5 when a client calls the method:
import org.red5.server.api.IClient;
import org.red5.server.api.IConnection;
import org.red5.server.api.IScope;
public void whoami(IConnection conn) {
IClient client = conn.getClient();
IScope scope = conn.getScope();
// ...
}
Additional handlers
For many applications, existing classes containing application logic that
is not related to Red5 are required to be reused. In order to make them
available for clients connecting through RTMP, these classes need to be
registered as handlers in Red5.
There are currently two ways to register these handlers:
By adding them to the configuration files.By registering them manually from the application code.
The handlers can be executed by clients with code similar to this:
nc = new NetConnection();
nc.connect("rtmp://localhost/myapp");
nc.call("handler.method", nc, "Hello world!");
If a handler is requested, Red5 always looks it up in the custom scope
handlers before checking the handlers that have been set up in the context
through the configuration file.
Handlers in configuration files
This method is best suited for handlers that are common to all scopes the
application runs in and that don't need to change during the lifetime of
an application.
To register the class `com.fancycode.red5.HandlerSample` as handler `sample`,
the following bean needs to be added to `WEB-INF/red5-web.xml`:
]]>
Note that the id of the bean is constructed as the name of the handler
(here `sample`) and the keyword `service`.
Handlers from application code
All applications that use handlers which are different for the various
scopes or want to change handlers, need a way to register them from the
serverside code. These handlers always override the handlers configured in
`red5-web.xml`. The methods required for registration are described in the
interface IServiceHandlerProvider_ which is implemented by
ApplicationAdapter_.
The same class as above can be registered using this code:
public boolean appStart(IScope app) {
if (!super.appStart(scope))
return false;
Object handler = new com.fancycode.red5.HandlerSample();
app.registerServiceHandler("sample", handler);
return true;
}
Note that in this example, only the application scope has the `sample`
handler but not the subscopes! If the handler should be available in the
rooms as well, it must be registered in `roomStart` for the room scopes.
Calls to client methods
To call methods from your Red5 application on the client, you will first need
a reference to the current connection object:
import org.red5.server.api.IConnection;
import org.red5.server.api.Red5;
import org.red5.server.api.service.IServiceCapableConnection;
...
IConnection conn = Red5.getConnectionLocal();
If the connection implements the IServiceCapableConnection_ interface, it
supports calling methods on the other end:
if (conn instanceof IServiceCapableConnection) {
IServiceCapableConnection sc = (IServiceCapableConnection) conn;
sc.invoke("the_method", new Object[]{"One", 1});
}
If you need the result of the method call, you must provide a class that
implements the IPendingServiceCallback_ interface:
import org.red5.server.api.service.IPendingService;
import org.red5.server.api.service.IPendingServiceCallback;
class MyCallback implements IPendingServiceCallback {
public void resultReceived(IPendingServiceCall call) {
// Do something with "call.getResult()"
}
}
The method call looks now like this:
if (conn instanceof IServiceCapableConnection) {
IServiceCapableConnection sc = (IServiceCapableConnection) conn;
sc.invoke("the_method", new Object[]{"One", 1}, new MyCallback());
}
Of course you can implement this interface in your application and pass a
reference to the application instance.
SharedObjects
The methods to access shared objects from an application are specified in the
interface ISharedObjectService_.
When dealing with shared objects in serverside scripts, special care must be
taken about the scope they are created in.
To create a new shared object when a room is created, you can override the
method `roomStart` in your application:
import org.red5.server.adapter.ApplicationAdapter;
import org.red5.server.api.IScope;
import org.red5.server.api.so.ISharedObject;
public class SampleApplication extends ApplicationAdapter {
public boolean roomStart(IScope room) {
if (!super.roomStart(room))
return false;
createSharedObject(room, "sampleSO", true);
ISharedObject so = getSharedObject(room, "sampleSO");
// Now you could do something with the shared object...
return true;
}
}
Now everytime a first user connects to a room of a application, e.g. through
`rtmp://server/application/room1`, a shared object `sampleSO` is created by
the server.
If a shared object should be created for connections to the main application,
e.g. `rtmp://server/application`, the same must be done in the method
`appStart`.
For further informations about the possible methods a shared object provides
please refer to the api documentation of the interface ISharedObject_.
Serverside change listeners
To get notified about changes of the shared object similar to `onSync` in
FCS / FMS, a listener must implement the interface ISharedObjectListener_:
of the shared object
// was changed to .
}
public void onSharedObjectDelete(ISharedObject so, String key) {
// The attribute of the shared object was deleted.
}
public void onSharedObjectSend(ISharedObject so,
String method, List params) {
// The handler of the shared object was called
// with the parameters .
}
// Other methods as described in the interface...
}
]]>
Additionally, the listener must get registered at the shared object:
ISharedObject so = getSharedObject(scope, "sampleSO");
so.addSharedObjectListener(new SampleSharedObjectListener());
Changing from application code
A shared object can be changed by the server as well:
ISharedObject so = getSharedObject(scope, "sampleSO");
so.setAttribute("fullname", "Sample user");
Here all subscribed clients as well as the registered handlers are notified
about the new / changed attribute.
If multiple actions on a shared object should be combined in one update
event to the subscribed clients, the methods `beginUpdate` and `endUpdate`
must be used:
ISharedObject so = getSharedObject(scope, "sampleSO");
so.beginUpdate();
so.setAttribute("One", "1");
so.setAttribute("Two", "2");
so.removeAttribute("Three");
so.endUpdate();
The serverside listeners will receive their update notifications through
separate method calls as without the `beginUpdate` and `endUpdate`.
SharedObject event handlers
, )`
from a Flash client or the corresponding serverside call can be mapped to
methods in Red5. Therefore a handler must get registered through a method
of the ISharedObjectHandlerProvider_ interface similar to the application
handlers:
]]>
package com.fancycode.red5;
class MySharedObjectHandler
{
public void myMethod(String arg1) {
// Now do something
}
}
...
ISharedObject so = getSharedObject(scope, "sampleSO");
so.registerServiceHandler(new MySharedObjectHandler());
Handlers with a given name can be registered as well:
ISharedObject so = getSharedObject(scope, "sampleSO");
so.registerServiceHandler("one.two", new MySharedObjectHandler());
Here, the method could be called through `one.two.myMethod`.
..soservice`, so
the above example could also be defined with:
]]>
]]>
Persistence
Persistence is used so properties of objects can be used even after the server
has been restarted. In FCS / FMS usually local shared objects on the
serverside are used for this.
Red5 allows arbitrary objects to be persistent, all they need to do is
implement the interface IPersistable_. Basically these objects have a `type`,
a `path`, a `name` (all strings) and know how to serialize and deserialize
themselves.
Here is a sample of serialization and deserialization:
import java.io.IOException;
import org.red5.io.object.Input;
import org.red5.io.object.Output;
import org.red5.server.api.persistence.IPersistable;
class MyPersistentObject implements IPersistable {
// Attribute that will be made persistent
private String data = "My persistent value";
void serialize(Output output) throws IOException {
// Save the objects's data.
output.writeString(data);
}
void deserialize(Input input) throws IOException {
// Load the object's data.
data = input.readString();
}
// Other methods as described in the interface...
}
To save or load this object, the following code can be used:
import org.red5.server.adapter.ApplicationAdapter;
import org.red5.server.api.IScope;
import org.red5.server.api.Red5;
import org.red5.server.api.persistence.IPersistenceStore;
class MyApplication extends ApplicationAdapter {
private void saveObject(MyPersistentObject object) {
// Get current scope.
IScope scope = Red5.getConnectionLocal().getScope();
// Save object in current scope.
scope.getStore().save(object);
}
private void loadObject(MyPersistentObject object) {
// Get current scope.
IScope scope = Red5.getConnectionLocal().getScope();
// Load object from current scope.
scope.getStore().load(object);
}
}
If no custom objects are required for an application, but data must be stored
for future reuse, it can be added to the IScope_ through the interface
IAttributeStore_. In scopes, all attributes that don't start with
`IPersistable.TRANSIENT_PREFIX` are persistent.
The backend that is used to store objects is configurable. By default
persistence in memory and in the filesystem is available.
/persistence///.red5", e.g. for a shared
object "theSO" in the connection to "rtmp://server/myApp/room1" a file at
"webapps/myApp/persistence/SharedObject/room1/theSO.red5" would be created.
]]>
Periodic events
Applications that need to perform tasks regularly can use the `setInterval`
in FCS / FMS to schedule methods for periodic execution.
Red5 provides a scheduling service (ISchedulingService_) that is implemented
by ApplicationAdapter_ like most other services. The service can register
an object (which needs to implement the IScheduledJob_ interface) whose
`execute` method is called in a given interval.
To register an object, code like this can be used:
import org.red5.server.api.IScope;
import org.red5.server.api.IScheduledJob;
import org.red5.server.api.ISchedulingService;
import org.red5.server.adapter.ApplicationAdapter;
class MyJob implements IScheduledJob {
public void execute(ISchedulingService service) {
// Do something
}
}
public class SampleApplication extends ApplicationAdapter {
public boolean roomStart(IScope room) {
if (!super.roomStart(room))
return false;
// Schedule invokation of job every 10 seconds.
String id = addScheduledJob(10000, new MyJob());
room.setAttribute("MyJobId", id);
return true;
}
}
The id that is returned by `addScheduledJob` can be used later to stop
execution of the registered job:
public void roomStop(IScope room) {
String id = (String) room.getAttribute("MyJobId");
removeScheduledJob(id);
super.roomStop(room);
}
Remoting
Remoting can be used by non-rtmp clients to invoke methods in Red5. Another
possibility is to call methods from Red5 to other servers that provide a
remoting service.
Remoting server
Services that should be available for clients need to be registered the same
way as additional application handlers are registered. See above for details.
To enable remoting support for an application, the following section must be
added to the `WEB-INF/web.xml` file:
gateway
org.red5.server.net.servlet.AMFGatewayServlet
gateway/gateway/*
]]>
` tag (here `gateway`) can be used
by the remoting client as connection url. If this example would have been
specified for an application `myApp`, the URL would be:
]]>
http://localhost:5080/myApp/gateway
Methods invoked through this connection will be executed in the context of
the application scope. If the methods should be executed in subscopes, the
path to the subscopes must be added to the URL like:
http://localhost:5080/myApp/gateway/room1/room2
Remoting client
The class RemotingClient_ defines all methods that are required to call
methods through the remoting protocol.
The following code serves as example about how to use the remoting client:
import org.red5.server.net.remoting.RemotingClient;
String url = "http://server/path/to/service";
RemotingClient client = new RemotingClient(url);
Object[] args = new Object[]{"Hello world!"};
Object result = client.invokeMethod("service.remotingMethod", args);
// Now do something with the result
By default, a timeout of 30 seconds will be used per call, this can be
changed by passing a second parameter to the constructor defining the maximum
timeout in milliseconds.
The remoting headers `AppendToGatewayUrl`, `ReplaceGatewayUrl` and
`RequestPersistentHeader` are handled automatically by the Red5 remoting
client.
Some methods may take a rather long time on the called server to complete, so
it's better to perform the call asynchronously to avoid blocking a thread in
Red5. Therefore an object that implements the interface IRemotingCallback_
must be passed as additional parameter:
import org.red5.server.net.remoting.RemotingClient;
import org.red5.server.net.remoting.IRemotingCallback;
public class CallbackHandler implements IRemotingCallback {
void errorReceived(RemotingClient client, String method,
Object[] params, Throwable error) {
// An error occurred while performing the remoting call.
}
void resultReceived(RemotingClient client, String method,
Object[] params, Object result) {
// The result was received from the server.
}
}
String url = "http://server/path/to/service";
RemotingClient client = new RemotingClient(url);
Object[] args = new Object[]{"Hello world!"};
IRemotingCallback callback = new CallbackHandler();
client.invokeMethod("service.remotingMethod", args, callback);
Streams
TODO: How can streams be accessed from an application?
Configuration files used by Red5
This document describes the configuration files used by Red5.
Please note that this document is still *work in progress*, so some things
may (and surely will) change until the final release of Red5!
26 September 2006JoachimBauchjojo@struktur.dePaulGregoiremondain@gmail.comDirectory "conf"jetty.xml
The settings of the HTTP server and servlet container are specified using
this file. It runs on all available interfaces on port 5080 by default.
See the `Jetty homepage`__ for further information about the syntax of this
file.
http://jetty.mortbay.org/jetty6/keystore
Contains a sample private key and certificate to be used for secure
connections.
log4j.properties
Controls the log levels and output handlers for the logging subsystem.
Further information about log4j can be found on `the official homepage`.
http://logging.apache.org/log4j/docs/realm.properties (Jetty)
This file defines users passwords and roles that can be used for protected
areas.
The format is:
: [, ...]
]]>
Passwords may be clear text, obfuscated or checksummed. The class
"org.mortbay.util.Password" should be used to generate obfuscated passwords
or password checksums.
tomcat-users.xml (Tomcat)
This file defines users passwords and roles that can be used for protected
areas.
The format is:
" password="" roles="[, ...]" />
]]>
Passwords may be clear text, obfuscated or checksummed. For information on different
digest support or available realm implementations use the how-to:
http://tomcat.apache.org/tomcat-5.5-doc/realm-howto.html
Further information about tomcat realms can be found on `the official homepage`
http://tomcat.apache.org/tomcat-5.5-doc/catalina/docs/api/org/apache/catalina/realm/package-summary.htmlred5.globals
Specifies the path to the configuration file for the default global context
to be used for Red5.
By default this file is located in "/webapps/red5-default.xml".
red5.properties
File containing key / value pairs to configure the host and port of basic
services like RTMP or remoting.
red5.xml
The main configuration file that wires together the context tree. It takes
care of loading "red5-common.xml" and "red5-core.xml" and sets up the rest of
the server. This is the first file to be loaded by Red5.
The J2EE container is selected in this configuration file by configuring one of the
following bean elements.
- Jetty
]]>
- Tomcat
... cut for brevity ...
]]>
red5-common.xml
Classes that are shared between all child contexts are declared in this file.
It contains information about the object serializers / deserializers, the
codecs to be used for the network protocols as well as the available video
codecs.
The object (FLV) cache is configured / spring-wired in this file. Four implementations
are currently available; The first one is our own creation (simple byte-buffers) and the others use
WhirlyCache, or Ehcache. If no caching is desired then the NoCache implementation should be specified like so:
]]>
The other bean configurations are as follows (Only one may be used at a time):
- Red5 homegrown simple example
5
]]>
- EhCache http://ehcache.sourceforge.net/
]]>
- Whirlycache https://whirlycache.dev.java.net/
com.whirlycott.cache.policy.LFUMaintenancePolicycom.whirlycott.cache.impl.FastHashMapImpl
]]>
red5-core.xml
All available network services are specified here. By default these are
RTMP and RTMPT. The actual settings for the RTMPT server can be found in
"red5-rtmpt.xml" when using Jetty as the J2EE container.
The RTMPT handler is selected by configuring one of the following bean elements.
- Jetty
]]>
- Tomcat
... cut for brevity ...
]]>
red5-rtmpt.xml
Sets up the mapping between the RTMPT URLs and the servlets to use as well
as specify the host and port to run on. By default the RTMPT server runs on
all available interfaces on port 8088.
See the `Jetty homepage` for further information about the syntax of this
file.
http://jetty.mortbay.org/jetty6/
web.xml (Tomcat)
Default web.xml file used by Tomcat. The settings from this file are applied to a web
application before it's own WEB_INF/web.xml file.
Further info about the configuration of this file may be found here:
http://tomcat.apache.org/tomcat-5.5-doc/jasper-howto.html#Configurationweb-default.xml (Jetty)
Default web.xml file used by Jetty. The settings from this file are applied to a web
application before it's own WEB_INF/web.xml file.
26 September 2006JoachimBauchjojo@struktur.dePaulGregoiremondain@gmail.comWebapp config directoryred5-web.xml
Red5 applications are configured within this file. The scripting implementations or Java
applications are configured via Spring bean elements.
- Java application
]]>
- Javascript / Rhino application
org.red5.server.api.IScopeHandlerorg.red5.server.adapter.IApplicationorg.red5.server.adapter.ApplicationAdapter
]]>
- Ruby application
org.red5.server.api.IScopeHandlerorg.red5.server.adapter.IApplication
]]>
Building Red5Part intro10/24/05Dominick Accattato(daccattato at gmail dot com)Building with Ant
TODO
10/24/05Dominick Accattato(daccattato at gmail dot com)Building a Red5 Debian package
Install the debian packages "dpkg-dev", "debhelper", "dh-make",
"devscripts" and "fakeroot".
Checkout the debian build scripts to a folder "debian" inside the Red5
root from http://svn1.cvsdude.com/osflash/red5/debian/trunk
Update "debian/changelog" and add an entry for the new version you are
building. Note that the syntax must match the previous entries!
Update the filename in "debian/files" to match the version you are
building.
Make sure you run from a clean Red5 checkout of the tag to build!!!
From the red5 root run "dpkg-buildpackage -uc -b -rfakeroot"
If all goes well, you should have a debian package one folder below the
Red5 root.
10/24/05Dominick Accattato(daccattato at gmail dot com)Release
This document describes the steps necessary to create a new release of Red5:
Make sure everything has been committed to the trunk or correct branch.
Update the file doc/changelog.txt with informations about the new release.
Create tags of the modules that are linked into the main code tree:
- documentation at http://svn1.cvsdude.com/osflash/red5/doc/tags
Tags for versions should always be the version string with dots replaced
by underscores, e.g. version "1.2.3" becomes tag "1_2_3".
If you would tag the documentation folder for version "1.2.3", you would
use the url http://svn1.cvsdude.com/osflash/red5/doc/tags/1_2_3
Tag the server code according to the naming scheme from above at
http://svn1.cvsdude.com/osflash/red5/java/server/tags
Update the svn:externals in the newly created server code tag to point
to the tagged modules from step 3.
You're done.
Applications
This document describes how new applications can be created in Red5.
It applies to the new API introduced by Red5 0.4.
3 May 2007PaulGregoireCreate new applications in Red5
This document describes how new applications can be created in Red5.
It applies to the new API introduced by Red5 0.4.
The application directory
Red5 stores all application definitions as folders inside the "webapps"
directory beneath the root of Red5. So the first thing you will have to
do in order to create a new application, is to create a new subfolder
in "webapps". By convention this folder should get the same name the
application will be reached later.
Inside your new application, you will need a folder "WEB-INF" containing
configuration files about the classes to use. You can use the templates
provided by Red5 in the folder "doc/templates/myapp".
During the start of Red5, all folders inside "webapps" are searched for
a directory "WEB-INF" containing the configuration files.
Configuration
The main configuration file that is loaded is "web.xml". It contains the
following parameters:
globalScope
The name of the global scope, this should be left at the default:
globalScopedefault
]]>
contextConfigLocation
Specifies the name(s) of handler configuration files for this application.
The handler configuration files reference the classes that are used to notify
the application about joining / leaving clients and that provide the methods
a client can call.
Additionally, the handler configuration files specify the scope hierarchy for
these classes.
The path name given here can contain wildcards to load multiple files:
contextConfigLocation/WEB-INF/red5-*.xml
]]>
locatorFactorySelector
References the configuration file of the root application context which
usually is "red5.xml":
locatorFactorySelectorred5.xml
]]>
parentContextKey
Name of the parent context, this usually is "default.context":
parentContextKeydefault.context
]]>
log4jConfigLocation
Path to the configuration file for the logging subsystem:
log4jConfigLocation/WEB-INF/log4j.properties
]]>
webAppRootKey
Unique name for this application, should be the public name:
webAppRootKey/myapp
]]>
Handler configuration
Every handler configuration file must contain at least three beans:
Context
The context bean has the reserved name `web.context` and is used to map paths
to scopes, lookup services and handlers. The default class for this is
`org.red5.server.Context`.
By default this bean is specified as:
]]>
Every application can only have one context. However this context can be
shared across multiple scopes.
Scopes
Every application needs at least one scope that links the handler to the
context and the server. The scopes can be used to build a tree where clients
can connect to every node and share objects inside this scope (like shared
objects or live streams). You can see the scopes as rooms or instances.
The default scope usually has the name `web.scope`, but the name can be chosen
arbitrarily.
The bean has the following properties:
`server` - This references the global server `red5.server`.
`parent` - References the parent for this scope and usually is `global.scope`.
`context` - The server context for this scope, use the `web.context` from above.
`handler` - The handler for this scope (see below).
`contextPath` - The path to use when connecting to this scope.
`virtualHosts` - A comma separated list of hostnames or ip addresses this scope runs at.
A sample definition looks like this:
]]>
You can move the values for `contextPath` and `virtualHosts` to a separate
properties file and use parameters. In that case you need another bean:
]]>
Assuming a `red5-web.properties` containing the following data:
the properties of the scope can now be changed to:
]]>
The `contextPath` specified in the configuration can be seen as "root" path
of the scope. You can add additional elements after the configured path when
connecting to dynamically create extra scopes.
These extra scopes all use the same handler but have their own properties,
shared objects and live streams.
Handlers
Every context needs a handler that implements the methods called when a client
connects to the scope, leaves it and that contains additional methods that can
be called by the client. The interface these handlers need to implement is
specified by `org.red5.server.api.IScopeHandler`, however you can implement
other interfaces if you want to control access to shared objects or streams.
A sample implementation that can be used as base class can be found at
`org.red5.server.adapter.ApplicationAdapter`. Please refer to the javadoc
documentation for further details.
The bean for a scope handler is configured by:
]]>
The `id` attribute is referenced by the scope definition above.
If you don't need any special server-side logic, you can use the default
application handler provided by Red5:
]]>
Sample handler
A sample handler can be implemented in a few lines of code:
Assuming the sample configuration above, you can call this method using the
following ActionScript snippet:
This should give you the output:
The result is 3
2007-05-03PaulGregoiremondain@gmail.comSetup applications in Red5 WAR
This document describes how applications can be configured in Red5 when using the WAR
implementation. In this version of Red5 the J2EE container is not contained within Red5
and therefore is configured differently. This document assumes that the application WAR
has already been expanded.
The application directory
An application war is normally expanded into a directory based upon the name of the war file, eg. red5.war
expands into tomcat/webapps/red5 on a Tomcat server. In a standard Red5 installation, all the applications
are stored within their own directory under the webapps directory; the difference here is that they are all
located in the same directory.
Configuration
The WAR version stores all application definitions as Spring configuration files suffixed with the
string "-context.xml"; If your application was called ofla then its configuration file would be
named "ofla-context.xml". The context files are loaded automatically upon server startup.
The main configuration file that is loaded is "web.xml". It contains the following parameters:
globalScope
The name of the global scope, this should be left at the default:
globalScopedefault
]]>
contextConfigLocation
Specifies the name(s) of handler configuration files for this application.
The handler configuration files reference the classes that are used to notify
the application about joining / leaving clients and that provide the methods
a client can call.
Additionally, the handler configuration files specify the scope hierarchy for
these classes.
The path name given here can contain wildcards to load multiple files:
contextConfigLocation/WEB-INF/applicationContext.xml, /WEB-INF/red5-common.xml, /WEB-INF/red5-core.xml, /WEB-INF/*-context.xml
]]>
listener (start-up / shutdown)
References the context listener servlet of the application, this technically takes the place of
the Standalone.class in a standard Red5 server.
org.red5.server.MainServlet
]]>
parentContextKey
Name of the parent context, this usually is "default.context":
parentContextKeydefault.context
]]>
log4jConfigLocation
Path to the configuration file for the logging subsystem:
log4jConfigLocation/WEB-INF/log4j.properties
]]>
Handler configuration
Every handler configuration file must contain at least three beans:
Context
The context bean has the reserved name `web.context` and is used to map paths
to scopes, lookup services and handlers. The default class for this is
`org.red5.server.Context`.
By default this bean is specified as:
]]>
.context' so that they will not conflict with one another.
Application contexts can be shared across multiple scopes.
]]>
Scopes
Every application needs at least one scope that links the handler to the
context and the server. The scopes can be used to build a tree where clients
can connect to every node and share objects inside this scope (like shared
objects or live streams). You can see the scopes as rooms or instances.
.scope' so that they will not conflict with one another.
]]>
The bean has the following properties:
`server` - This references the global server `red5.server`.
`parent` - References the parent for this scope and usually is `global.scope`.
`context` - The server context for this scope, use the `web.context` from above.
`handler` - The handler for this scope (see below).
`contextPath` - The path to use when connecting to this scope.
`virtualHosts` - A comma separated list of hostnames or ip addresses this scope runs at.
In this version we do not control
the host names, this is accomplished by the server.
A sample definition looks like this:
]]>
The 'contextPath' specified in the configuration can be seen as "root" path of the scope.
You can add additional elements after the configured path when connecting to dynamically
create extra scopes.
These extra scopes all use the same handler but have their own properties, shared objects and
live streams.
Handlers
Every context needs a handler that implements the methods called when a client
connects to the scope, leaves it and that contains additional methods that can
be called by the client. The interface these handlers need to implement is
specified by `org.red5.server.api.IScopeHandler`, however you can implement
other interfaces if you want to control access to shared objects or streams.
A sample implementation that can be used as base class can be found at
`org.red5.server.adapter.ApplicationAdapter`. Please refer to the javadoc
documentation for further details.
The bean for a scope handler is configured by:
]]>
The `id` attribute is referenced by the scope definition above.
If you don't need any special server-side logic, you can use the default
application handler provided by Red5:
]]>
ManagementPart intro3 May 2007PaulGregoireJava Management Extensions (JMX) and Red5
TODO
JMX classes
Red5's implementation consists of the following classes and various other MBeans:
org.red5.server.jmx.JMXFactory - Provides access to the platform MBeanServer as well as registration, unregistration, and creation of new MBean instances. Creation and registration is performed using StandardMBean wrappers.
org.red5.server.jmx.JMXAgent - Provides the HTML adapter and registration of MBeans.
org.red5.server.jmx.JMXUtil - Helper methods for working with ObjectName or MBean instances.
Spring configuration
The Spring configuration for the JMX implementation allows you to configure the "domain"
for MBean registration and listener port for the HTML adaptor.
The default entries are shown below.
]]>
The HTML adapter is disabled by default, but it allows easy management of MBeans from a web browser.
The RMI adapter may only be used if an RMI registry is running. To start a registry simply execute this at the command prompt:
- windows
rmiregistry 9999
- unix
rmiregistry 9999 &
The "9999" is the port and should match your RMI configuration.
jConsole
JConsole is a utility that ships with the JRE (since 1.5), it allows you to manage local and remote JMX implementations.
To enable introspection you must add the following VM parameter to your startup:
-Dcom.sun.management.jmxremote
After the parameter is set and the application initialized you can start jConsole at the command line by typing:
jconsole
A Swing application will appear and you must select the implementation (agent) you wish to manage,
for local simply select "org.red5.server.Standalone".
Linkshttp://www.onjava.com/pub/a/onjava/2004/09/29/tigerjmx.html?page=1http://java.sun.com/developer/JDCTechTips/2005/tt0315.html#2Scripting
TODO
2 Feb 2007PaulGregoire22 Feb 2007Select a scripting implementationLevel: Beginner
Red5 includes interpreters for the following scripting languages:
Javascript - version 1.6 (Mozilla Rhino version 1.6.2)JRuby - version 0.9.2 (Ruby version 1.8.5)Jython - version 2.1 (Python version 2.1)Groovy - version 1.0Beanshell - version 2.0b4
Future versions may include:
JudoScriptScalaPHP (This one is non-trivial, I may just provide a bridge)Actionscript (Not SSAS)
The scripting implementation classes are pre-specified in the
following locations depending upon your Java version:
Java5jsr-223-1.0-pr.jar /META-INF/services/javax.script.ScriptEngineFactoryJava6resources.jar /META-INF/services/javax.script.ScriptEngineFactoryRed5red5.jar /META-INF/services/javax.script.ScriptEngineFactory
It is most likely that the classes read from the jdk or jre will be prefered over any specified elsewhere.
2 Feb 2007PaulGregoire22 Feb 2007Configuring SpringLevel: Intermediate
Step one is to locate your web applications red5-web.xml file. Within the xml config file the web.scope bean
definition must supply a web.handler, this handler is your Red5 application (An application must extend the org.red5.server.adapter.ApplicationAdapter class).
The application provides access to the Red5 server and any service instances that are created.
The service instances and the application itself may be scripted.
Bean definitions in Spring config files may not have the same id, here are some web handler definition examples:
Java
]]>
Javascriptorg.red5.server.api.IScopeHandlerorg.red5.server.adapter.IApplicationorg.red5.server.adapter.ApplicationAdapter
]]>
Rubyorg.red5.server.api.IScopeHandlerorg.red5.server.adapter.IApplication
]]>
Groovyorg.red5.server.api.IScopeHandlerorg.red5.server.adapter.IApplication
]]>
Pythonorg.red5.server.api.IScopeHandlerorg.red5.server.adapter.IApplicationOne2III
]]>
In general the configuration using scripted classes is defined using the constructor arguments (see interpreter section) in the following order:
Argument 1Location of the script source fileArgument 2Java interfaces implemented by the script
The interfaces for the code which extends an Application are basically boilerplate as seen in the examples above; You do not
have to use those interfaces in all your script definitions.
Argument 3Java classes extended by the scriptThe extended class is not always necessary, it depends upon the scripting engine implementation.
The example location starts with classpath:applications which in physical disk terms for the "oflaDemo"
application equates to webapps/oflaDemo/WEB-INF/applications
2 Feb 2007PaulGregoire22 Feb 2007Creating an application scriptLevel: IntermediateApplication adapter
Scripting an application adapter is more difficult in some languages than it is in others,
because of this I present the Ruby example which works really well and is easy to write
and integrate. The application services are easily written in any of the supported languages,
but they require a Java interface at a minimum.
JRuby application adapter implementationApplication services
Here is an example of a Java interface (Yes, the methods are supposed to be empty)
which is used in the examples to provide a template for applications which will gather a list
of files and return them as a "Map" (key-value pairs) to the caller.
Simple Java interface for implementation by scripts Spring bean definition for a script implementation of the interfaceorg.red5.server.webapp.oflaDemo.IDemoService
]]>
JRuby script implementing the interface
ex
puts "Error in getListOfAvailableFLVs #{errorType} \n"
puts "Exception: #{ex} \n"
puts caller.join("\n");
end
return filesMap
end
def formatDate(date)
return date.strftime("%d/%m/%Y %I:%M:%S")
end
def method_missing(m, *args)
super unless @value.respond_to?(m)
return @value.send(m, *args)
end
end
]]>
Java application implementing the interface
upon which the Ruby code was based (This code is NOT needed when using the script)
filesMap = new HashMap();
Map fileInfo;
try {
log.debug("getting the FLV files");
Resource[] flvs = scope.getResources("streams/*.flv");
if (flvs != null) {
for (Resource flv : flvs) {
File file = flv.getFile();
Date lastModifiedDate = new Date(file.lastModified());
String lastModified = formatDate(lastModifiedDate);
String flvName = flv.getFile().getName();
String flvBytes = Long.toString(file.length());
if (log.isDebugEnabled()) {
log.debug("flvName: " + flvName);
log.debug("lastModified date: " + lastModified);
log.debug("flvBytes: " + flvBytes);
log.debug("-------");
}
fileInfo = new HashMap();
fileInfo.put("name", flvName);
fileInfo.put("lastModified", lastModified);
fileInfo.put("size", flvBytes);
filesMap.put(flvName, fileInfo);
}
}
Resource[] mp3s = scope.getResources("streams/*.mp3");
if (mp3s != null) {
for (Resource mp3 : mp3s) {
File file = mp3.getFile();
Date lastModifiedDate = new Date(file.lastModified());
String lastModified = formatDate(lastModifiedDate);
String flvName = mp3.getFile().getName();
String flvBytes = Long.toString(file.length());
if (log.isDebugEnabled()) {
log.debug("flvName: " + flvName);
log.debug("lastModified date: " + lastModified);
log.debug("flvBytes: " + flvBytes);
log.debug("-------");
}
fileInfo = new HashMap();
fileInfo.put("name", flvName);
fileInfo.put("lastModified", lastModified);
fileInfo.put("size", flvBytes);
filesMap.put(flvName, fileInfo);
}
}
} catch (IOException e) {
log.error(e);
}
return filesMap;
}
private String formatDate(Date date) {
SimpleDateFormat formatter;
String pattern = "dd/MM/yy H:mm:ss";
Locale locale = new Locale("en", "US");
formatter = new SimpleDateFormat(pattern, locale);
return formatter.format(date);
}
}
]]>
Flex AS3 method calling the serviceCreating your own interpreterLevel: Advanced
Lets just open this up by saying that I attempted to build an interpreter for PHP this last weekend 02/2007 and it was a real pain;
after four hours I had to give up. So what I learned from this is that you must first identify scripting languages
which operate as applications, not as http request processors. Heres a test: Can X language be compiled into
an executable or be run on the command-line? If yes then it should be trivial to integrate.
Links with scripting informationSpring scriptinghttp://static.springframework.org/spring/docs/2.0.x/reference/dynamic-language.htmlhttp://rhinoinspring.sourceforge.net/Java scriptinghttp://java.sun.com/developer/technicalArticles/J2SE/Desktop/scripting/http://blogs.sun.com/sundararajan/https://scripting.dev.java.net/https://scripting.dev.java.net/http://today.java.net/pub/a/today/2006/04/11/scripting-for-java-platform.htmlhttp://www.javaworld.com/javaworld/jw-03-2005/jw-0314-scripting_p.htmlhttp://www.oreillynet.com/onjava/blog/2004/01/java_scripting_half_the_size_h.htmlhttp://www.robert-tolksdorf.de/vmlanguages.htmlJavascripthttp://www.mozilla.org/rhino/http://www.mozilla.org/rhino/ScriptingJava.htmlRubyhttp://jruby.codehaus.org/Beanshellhttp://www.beanshell.org/Pythonhttp://www.jython.org/Project/http://www.onjava.com/pub/a/onjava/2002/03/27/jython.htmlhttp://jepp.sourceforge.net/http://jpe.sourceforge.net/http://jpype.sourceforge.net/Groovyhttp://groovy.codehaus.org/