/usr/share/doc/red5/html/migration-guide.html

<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>Chapter&nbsp;4.&nbsp;Migration Guide</title><link rel="stylesheet" type="text/css" href="html.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="Red5 - Reference Documentation"><link rel="up" href="getting-started.html" title="Part&nbsp;I.&nbsp;Getting Started"><link rel="prev" href="configuration-files.html" title="Chapter&nbsp;3.&nbsp;Configuration Files"><link rel="next" href="libraries.html" title="Chapter&nbsp;5.&nbsp;Red5 Libraries"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div xmlns="http://www.w3.org/TR/xhtml1/transitional" style="background-color:white;border:none;height:73px;border:1px solid black;"><a style="border:none;" href="http://osflash.org/red5" title="Red5 Open Source Flash Server"><img style="border:none;" src="images/red5-banner.png"></img></a><a style="border:none;" href="http://osflash.org/red5" title="Red5 Open Source Flash Server"><img style="border:none;position:absolute;padding-top:5px;right:42px;" src="images/red5-banner-logo.png"></img></a></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="migration-guide"></a>Chapter&nbsp;4.&nbsp;Migration Guide</h2></div></div></div>
	
	<p>This document describes API differences between the Macromedia Flash Communication 
		Server / Adobe Flash Media Server and Red5. It aims at helping migrate existing 
		applications to Red5. </p>
	<p>If you don't have an application in Red5 yet, please read the tutorial about howto create 
		new applications first. </p>
	<div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e771"></a>4.1.&nbsp;Application callbacks</h2></div></div></div>
		
		<p>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. </p>
		<div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d5e774"></a>4.1.1.&nbsp;Interface IScopeHandler</h3></div></div></div>
			
			<p>Red5 specifies these actions in the interface IScopeHandler 
				<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/api/IScopeHandler.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/IScopeHandler.html</a>. See the API documentation for further details.
			</p>
		</div>
		<div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d5e778"></a>4.1.2.&nbsp;Class ApplicationAdapter</h3></div></div></div>
			
			<p>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 

				<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html</a> defines 
				additional methods. 
			</p>
			<p>This class usually is used as base class for new applications. </p>
			<p>Here is a short overview of methods of the FCS / FMS application class and their 
				corresponding methods of ApplicationAdapter 
				<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html</a> in Red5:
			</p>
			<div class="table"><a name="fms-red5-migration"></a><p class="title"><b>Table&nbsp;4.1.&nbsp;FMS to Red5 Callback Methods</b></p><div class="table-contents">
				
				<table summary="FMS to Red5 Callback Methods" border="0"><colgroup><col width="50%" class="FCS / FMS"><col width="50%" class="Red5"></colgroup><tbody><tr><td>onAppStart</td><td>appStart / roomStart</td></tr><tr><td>onAppStop</td><td>appStop / roomStop</td></tr><tr><td>onConnect</td><td>appConnect / roomConnect / appJoin / roomJoin</td></tr><tr><td>onDisconnect</td><td>appDisconnect / roomDisconnect / appLeave / roomLeave</td></tr></tbody></table>
			</div></div><br class="table-break">
			
			<p>The app''' methods are called for the main application, the room''' methods are called for 
				rooms (i.e. instances) of the application. </p>
			<p>You can also also use the ApplicationAdapter 
				<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html</a> to check for streams, shared objects, or subscribe 
				them. See the API documentation for further details. 
			</p>
			<div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="d5e806"></a>4.1.2.1.&nbsp;Execution order of connection methods</h4></div></div></div>
				
				<p>Assuming you connect to rtmp://server/app/room1/room2 </p>
				<p>At first, the connection is established, so the user "connects" to all scopes that are 
					traversed up to room2: </p>
				<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
						<p>app (-&gt; appConnect)</p>
					</li><li class="listitem">
						<p>room1 (-&gt; roomConnect) </p>
					</li><li class="listitem">
						<p>room2 (-&gt; roomConnect) </p>
					</li></ol></div>
				<p>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: </p>
				<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
						<p>app (-&gt; appJoin)</p>
					</li><li class="listitem">
						<p>room1 (-&gt; roomJoin)</p>
					</li><li class="listitem">
						<p>room2 (-&gt; roomJoin)</p>
					</li></ol></div>
				<p>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 </p>
				<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
						<p>appConnect("app") </p>
					</li><li class="listitem">
						<p>joinConnect("room1") </p>
					</li><li class="listitem">
						<p>joinConnect("room3") </p>
					</li><li class="listitem">
						<p>roomJoin("room3")</p>
					</li></ol></div>
				<p>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. </p>
			</div>
		</div>
		<div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d5e836"></a>4.1.3.&nbsp;Accepting / rejecting clients</h3></div></div></div>
			
			<p>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. </p>
			<p>If a client should not be allowed to connect, the method rejectClient can be called which is 
				implemented by the ApplicationAdapter 
				<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html</a> class. Any parameter passed to rejectClient is available 
				as the application property of the status object that is returned to the caller. 
			</p>
		</div>
	</div>
	<div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e841"></a>4.2.&nbsp;Current connection and client</h2></div></div></div>
		
		<p>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 
			<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/api/Red5.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/Red5.html</a> object: 
		</p>
		<pre class="programlisting">


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(); 
    // ... 
} 

</pre>
		<p>The second possiblity requires the method to be defined with an argument of type 
			IConnection 
			<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/api/IConnection.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/IConnection.html</a> as 
			implicit first parameter which is automatically added by Red5 when a client calls the 
			method: 
		</p>
		<pre class="programlisting">


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(); 
    // ... 
} 

</pre>
	</div>
	<div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e849"></a>4.3.&nbsp;Additional handlers</h2></div></div></div>
		
		<p>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. </p>
		<p>There are currently two ways to register these handlers: </p>
		<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
				<p>By adding them to the configuration files.</p>
			</li><li class="listitem">
				<p>By registering them manually from the application code. </p>
			</li></ol></div>
		<p>The handlers can be executed by clients with code similar to this:</p>
		<div class="literallayout"><p><br>
nc&nbsp;=&nbsp;new&nbsp;NetConnection();&nbsp;<br>
nc.connect("rtmp://localhost/myapp");&nbsp;<br>
nc.call("handler.method",&nbsp;nc,&nbsp;"Hello&nbsp;world!");&nbsp;<br>
</p></div>
		<p>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. </p>
		<div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="MigrationGuideHandlersinconfigurationfiles"></a>4.3.1.&nbsp;Handlers in configuration files</h3></div></div></div>
			
			<p>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. </p>
			<p>To register the class com.fancycode.red5.HandlerSample as handler sample, the following 
				bean needs to be added to WEB-INF/red5-web.xml:</p>
			<pre class="programlisting">


&lt;bean id="sample.service" 
   class="com.fancycode.red5.HandlerSample" 
   singleton="true" /&gt; 

</pre>
			<p>Note that the id of the bean is constructed as the name of the handler (here sample) and 
				the keyword service. </p>
		</div>
		<div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d5e867"></a>4.3.2.&nbsp;Handlers from application code</h3></div></div></div>
			
			<p>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 
				<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/api/service/IServiceHandlerProvider.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/service/IServiceHandlerProvider.html</a> which is implemented 
				by ApplicationAdapter 
				<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html</a>. 
			</p>
			<p>The same class as above can be registered using this code: </p>
			<pre class="programlisting">


public boolean appStart(IScope app) { 
    if (!super.appStart(scope)) 
        return false; 
    Object handler = new com.fancycode.red5.HandlerSample(); 
    app.registerServiceHandler("sample", handler); 
    return true; 
} 

</pre>
			<p>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.</p>
		</div>
	</div>
	<div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e875"></a>4.4.&nbsp;Calls to client methods</h2></div></div></div>
		
		<p>To call methods from your Red5 application on the client, you will first need a reference to 
			the current connection object: </p>
		<pre class="programlisting">


import org.red5.server.api.IConnection; 
import org.red5.server.api.Red5; 
import org.red5.server.api.service.IServiceCapableConnection; 
... 
IConnection conn = Red5.getConnectionLocal(); 

</pre>
		<p>If the connection implements the IServiceCapableConnection 
			<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/api/service/IServiceCapableConnection.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/service/IServiceCapableConnection.html</a> interface, it supports 
			calling methods on the other end: 
		</p>
		<pre class="programlisting">


if (conn instanceof IServiceCapableConnection) { 
    IServiceCapableConnection sc = (IServiceCapableConnection) conn; 
    sc.invoke("the_method", new Object[]{"One", 1}); 
} 

</pre>
		<p>If you need the result of the method call, you must provide a class that implements the 
			IPendingServiceCallback 
			<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/api/service/IPendingServiceCallback.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/service/IPendingServiceCallback.html</a> interface: 
		</p>
		<pre class="programlisting">


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()" 
    } 
} 

</pre>
		<p>The method call looks now like this: </p>
		<pre class="programlisting">


if (conn instanceof IServiceCapableConnection) { 
    IServiceCapableConnection sc = (IServiceCapableConnection) conn; 
    sc.invoke("the_method", new Object[]{"One", 1}, new MyCallback()); 
} 

</pre>
		<p>Of course you can implement this interface in your application and pass a reference to the 
			application instance.</p>
	</div>
	<div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e888"></a>4.5.&nbsp;SharedObjects</h2></div></div></div>
		
		<p>The methods to access shared objects from an application are specified in the interface 
			ISharedObjectService 
			<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObjectService.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObjectService.html</a>. 
		</p>
		<p>When dealing with shared objects in serverside scripts, special care must be taken about 
			the scope they are created in. </p>
		<p>To create a new shared object when a room is created, you can override the method 
			roomStart in your application: </p>
		<pre class="programlisting">


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; 
  } 
} 

</pre>
		<p>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. </p>
		<p>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. </p>
		<p>For further informations about the possible methods a shared object provides please refer 
			to the api documentation of the interface ISharedObject 
			<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObject.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObject.html</a>. 
		</p>
		<div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d5e899"></a>4.5.1.&nbsp;Serverside change listeners</h3></div></div></div>
			
			<p>To get notified about changes of the shared object similar to onSync in FCS / FMS, a 
				listener must implement the interface ISharedObjectListener 
				<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObjectListener.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObjectListener.html</a>: 
			</p>
			<pre class="programlisting">


import org.red5.server.api.so.ISharedObject; 
import org.red5.server.api.so.ISharedObjectListener; 
public class SampleSharedObjectListener
Migration Guide 
       implements ISharedObjectListener { 
  public void onSharedObjectUpdate(ISharedObject so, 
                                   String key, Object value) { 
      // The attribute &amp;lt;key&amp;gt; of the shared object &amp;lt;so&amp;gt; 
      // was changed to &amp;lt;value&amp;gt;. 
  } 
  public void onSharedObjectDelete(ISharedObject so, String key) { 
      // The attribute &amp;lt;key&amp;gt; of the shared object &amp;lt;so&amp;gt; was deleted. 
  } 
  public void onSharedObjectSend(ISharedObject so, 
                                 String method, List params) { 
      // The handler &amp;lt;method&amp;gt; of the shared object &amp;lt;so&amp;gt; was called 
      // with the parameters &amp;lt;params&amp;gt;. 
  } 
  // Other methods as described in the interface... 
} 

</pre>
			<p>Additionally, the listener must get registered at the shared object: </p>
			<pre class="programlisting">


ISharedObject so = getSharedObject(scope, "sampleSO"); 
so.addSharedObjectListener(new SampleSharedObjectListener()) 

</pre>
		</div>
		<div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="MigrationGuideChangingfromapplicationcode"></a>4.5.2.&nbsp;Changing from application code</h3></div></div></div>
			
			<p>A shared object can be changed by the server as well: </p>
			<pre class="programlisting">


ISharedObject so = getSharedObject(scope, "sampleSO"); 
so.setAttribute("fullname", "Sample user"); 

</pre>
			<p>Here all subscribed clients as well as the registered handlers are notified about the new / 
				changed attribute. </p>
			<p>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: </p>
			<pre class="programlisting">


ISharedObject so = getSharedObject(scope, "sampleSO"); 
so.beginUpdate(); 
so.setAttribute("One", "1"); 
so.setAttribute("Two", "2"); 
so.removeAttribute("Three"); 
so.endUpdate(); 

</pre>
			<p>The serverside listeners will receive their update notifications through separate method 
				calls as without the beginUpdate and endUpdate.</p>
			<p>Calls to shared object handlers through remote_so.send(&lt;handler&gt;, &lt;args&gt;) 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 
				<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObjectHandlerProvider.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/so/ISharedObjectHandlerProvider.html</a> 
				interface similar to the application handlers: 
			</p>
			<pre class="programlisting">


package com.fancycode.red5; 
class MySharedObjectHandler { 
    public void myMethod(String arg1) { 
        // Now do something 
    } 
} 
... 
ISharedObject so = getSharedObject(scope, "sampleSO"); 
so.registerServiceHandler(new MySharedObjectHandler()); 

</pre>
			<p>Handlers with a given name can be registered as well: </p>
			<pre class="programlisting">


ISharedObject so = getSharedObject(scope, "sampleSO"); 
so.registerServiceHandler("one.two", new MySharedObjectHandler()); 

</pre>
			<p>Here, the method could be called through one.two.myMethod. 
				Another way to define event handlers for SharedObjects is to add them to the red5- 
				web.xml similar to the file-based application handlers. The beans must have a name of 
				&lt;SharedObjectName&gt;.&lt;DottedServiceName&gt;.soservice, so the above example could also 
				be defined with: </p>
			<pre class="programlisting">


&lt;bean id="sampleSO.one.two.soservice" 
   class="com.fancycode.red5.MySharedObjectHandler" 
   singleton="true" /&gt; 

</pre>
		</div>
	</div>
	<div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e921"></a>4.6.&nbsp;Persistence</h2></div></div></div>
		
		<p>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. </p>
		<p>Red5 allows arbitrary objects to be persistent, all they need to do is implement the 
			interface IPersistable 
			<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/api/persistence/IPersistable.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/persistence/IPersistable.html</a>. Basically these objects have a type, a path, a name (all strings) and 
			know how to serialize and deserialize themselves.
		</p>
		<p>Here is a sample of serialization and deserialization: </p>
		<pre class="programlisting">


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... 
} 

</pre>
		<p>To save or load this object, the following code can be used: </p>
		<pre class="programlisting">


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); 
  } 
} 

</pre>
		<p>If no custom objects are required for an application, but data must be stored for future 
			reuse, it can be added to the IScope 
			<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/api/IScope.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/IScope.html</a> through the interface IAttributeStore 
			<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/api/IAttributeStore.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/IAttributeStore.html</a>. In scopes, all attributes that don't start with 
			IPersistable.TRANSIENT_PREFIX are persistent.
		</p>
		<p>The backend that is used to store objects is configurable. By default persistence in memory 
			and in the filesystem is available. </p>
		<p>When using filesystem persistence for every object a file is created in "webapps/&lt;app&gt;/ 
			persistence/&lt;type&gt;/&lt;path&gt;/&lt;name&gt;.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. </p>
	</div>
	<div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e935"></a>4.7.&nbsp;Periodic events</h2></div></div></div>
		
		<p>Applications that need to perform tasks regularly can use the setInterval in FCS / FMS to 
			schedule methods for periodic execution. </p>
		<p>Red5 provides a scheduling service (ISchedulingService 
			<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/api/scheduling/ISchedulingService.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/scheduling/ISchedulingService.html</a>) that is implemented 
			by ApplicationAdapter 
			<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/adapter/ApplicationAdapter.html</a> like most other services. The service can register an object (which 
			needs to implement the IScheduledJob 
			<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/api/scheduling/IScheduledJob.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/api/scheduling/IScheduledJob.html</a> interface) whose execute method is called in a given 
			interval. 
		</p>
		<p>To register an object, code like this can be used: </p>
		<pre class="programlisting">


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; 
  } 
} 

</pre>
		<p>The id that is returned by addScheduledJob can be used later to stop execution of the 
			registered job: </p>
		<pre class="programlisting">


public void roomStop(IScope room) { 
    String id = (String) room.getAttribute("MyJobId");
    removeScheduledJob(id); 
    super.roomStop(room); 
} 

</pre>
	</div>
	<div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e946"></a>4.8.&nbsp;Remoting</h2></div></div></div>
		
		<p>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. </p>
		<div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d5e949"></a>4.8.1.&nbsp;Remoting server</h3></div></div></div>
			
			<p>Services that should be available for clients need to be registered the same way as 
				additional application handlers are registered. See above for details. </p>
			<p>To enable remoting support for an application, the following section must be added to the 
				WEB-INF/web.xml file: </p>
			<p>
				<span class="bold"><strong>web.xml</strong></span> - 
			</p>
			<pre class="programlisting">


&lt;servlet&gt; 
   &lt;servlet-name&gt;gateway&lt;/servlet-name&gt; 
   &lt;servlet-class&gt; 
      org.red5.server.net.servlet.AMFGatewayServlet 
   &lt;/servlet-class&gt; 
&lt;/servlet&gt; 
&lt;servlet-mapping&gt; 
   &lt;servlet-name&gt;gateway&lt;/servlet-name&gt; 
   &lt;url-pattern&gt;/gateway/*&lt;/url-pattern&gt; 
&lt;/servlet-mapping&gt; 

</pre>
			<p>The path specified in the &lt;url-pattern&gt; 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: </p>
			<div class="literallayout"><p><br>
http://localhost:5080/myApp/gateway&nbsp;<br>
</p></div>
			<p>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: </p>
			<div class="literallayout"><p><br>
http://localhost:5080/myApp/gateway/room1/room2&nbsp;<br>
</p></div>
		</div>
		<div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d5e960"></a>4.8.2.&nbsp;Remoting client</h3></div></div></div>
			
			<p>The class RemotingClient 
				<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/net/remoting/RemotingClient.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/net/remoting/RemotingClient.html</a> defines all methods that are required to call methods through the 
				remoting protocol. 
			</p>
			<p>The following code serves as example about how to use the remoting client:</p>
			<pre class="programlisting">


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 

</pre>
			<p>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. </p>
			<p>The remoting headers AppendToGatewayUrl, ReplaceGatewayUrl and 
				RequestPersistentHeader are handled automatically by the Red5 remoting client. </p>
			<p>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 
				<a class="ulink" href="http://dl.fancycode.com/red5/api/org/red5/server/net/remoting/IRemotingCallback.html" target="_top">http://dl.fancycode.com/red5/api/org/red5/server/net/remoting/IRemotingCallback.html</a> must be passed as additional parameter: 
			</p>
			<pre class="programlisting">


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); 

</pre>
		</div>
	</div>
	<div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e971"></a>4.9.&nbsp;Streams</h2></div></div></div>
		
		<p>TODO: How can streams be accessed from an application?</p>
	</div>
</div><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuration-files.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="libraries.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;3.&nbsp;Configuration Files&nbsp;</td><td width="20%" align="center"><span style="color:white;font-size:90%;"><a href="http://osflash.org/red5" title="Red5">Red5 Open Source Flash Server</a></span></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;5.&nbsp;Red5 Libraries</td></tr></table></div></body></html>
red5-doc 1.0~svn4374-3 / usr / share / doc / red5 / html / migration-guide.html
